# 3. cschem implementation - graphical schematics sheets - drawing primitives

## Goals

{imp3:0} The graphical schematics sheet is a generic vector graphics drawing canvas with enough metadata that cschem can translate them into concrete objects. The goal is to find a balance between generic vector drawing and "possible to implement in a consistent way in reasonable time". A balance that svg for example failed to find. Finding the balance requires temperance: the goal is not to provide a fully generic vector graphics language but only to provide enough features for drawing schematics.

## Dualism #1: independent graphics and meaning

{imp3:1} A novel aspect is that instead of telling how concrete objects look like in graphics, cschem rather separates looks and meanings. That is, there is no single canonical graphical representation of a hub or a wire. The user or an implementation (or plugins) can generate a group of random graphics elements and mark it as being a terminal ("pin").

{imp3:2} Likewise, connections are explicitly specified, without binding it to any specific graphical representation. A typical examples are:

- junction mark: can be a little dot or can be invisible (and the schematics would indicate non-junction by little jumper arcs)
- bus graphics, especially on bus-bus or bus-wire junctions
- pin graphics

{imp3:3} Gschem notes: this is very different from what gschem did: it stored objects that were both concrete objects and drawing objects. This means a pin or a junction dot will always look the same in gschem. Connections were not marked explicitly but calculated on load, from line endings being on other lines or pin ends. This made it hard to interpret the file by 3rd party software, as such a software would need to reproduce the same geometric calculations (potentially with the same rounding and/or tolerances!) to have the same connection conclusions.

{imp3:4} Is allowing the user to use different drawing styles desirable? On one hand, cschem won't enforce the One True Style, which could potentially lead to different users or implementations using different graphics for the same construct. On the other hand, this is already happening without cschem too, and EEs don't seem to struggle understanding schematics of a different style. Cschem won't struggle understanding them too, as the logical data is not extracted from the graphical looks.

{imp3:5} An interesting question is how implementation A will handle the graphics created by implementation B. For example a bus-wire junction: implementation A may draw a 45 degree white line coming out from the bus, wire connected to the end of this stub, and add a text with the channel name next to the stub. The stub line and the text are put in a group and this group is then used by the connection object's gfx. The data that actually makes the logical connection is the conn property of the connection. When B needs to edit this stub, it will not understand why the text is there, so the graphics will not be properly updated. The user may need to do that manually or use the bus connection graphics offer by B.

{imp3:6} The reference cschem implementation will set its own drawing conventions; it's recommended, but not enforced that other implementation follow these conventions.

## Dualism #2: is that really that novel?

{imp3:7} In a sense it is not: a symbol is usually a custom set of drawing primitives. The schematics capture software understands that it's a symbol, it needs to be drawn as is. Orthogonal to that, the software also has non-graphical metadata with the symbol (e.g. attributes) so it can understand the symbol.

{imp3:8} In that sense, a symbol in many software (including gschem) already shows this dualism. The novel aspect in cschem is that it extends the same idea to all other object types, e.g. terminals ("pins"), junction graphics, and even wires and buses.

{imp3:9} Revisiting the alternative styles question: a 4 slot digital inverter gate is already drawn as 4 separate triangular symbols and as a single box with 4 or 5 sections. Readers are not confused by the variants. The same way buses and even junctions have alternative styles on existing schematics. Cschem merely permits having such styles not by defining and hardwiring each of them in code, but by separating the looks from the works.

## text object and font

{imp3:20} There are two ways to specify font geometry of a text object:

1. {imp3:21} bbox based: when x2;y2 are specified; this is useful for fixed text objects placed on the sheet by the user; it's more important that these text objects, especially when multiline, stay in place and don't start to overlap with other objects than to have the exact font size matched.
2. {imp3:22} pen height based: when the text object does not have x2;y2, pen height property is used; this is useful when the placement and approximate size of the text is important but bbox matching is not. This is the typical case in symbols.

## grouping

{imp3:10} Cschem has only one kind of group and allows group-in-group. The typical use is that any concrete object is represented by a group. For example a symbol is a group, a terminal ("pin") is a group within the symbol group. What concrete object a group becomes is controlled by the role attribute of the group.

{imp3:11} A group can be a reference (group_ref) to another group specified elsewhere. This is how a symbol from a library can be instantiated. Since groups and group references can do two basic transformation (shift and rotate), they can place instances freely. This allows both by-reference and by-copy instantiation. It's up to the user to decide which one to use.

{imp3:12} Only composites have attributes, atoms don't. This means placing an atom directly on the sheet can not have attributes. Since groups are cheap, this can be easily solved by putting the atom in its own group.

{imp3:13} Wire-nets are obviously represented by a group that usually will contain lines representing wires. A connection objects can connect two groups by referring to group member drawing objects, e.g. a line (part of a wire-net group) and another line (part of a terminal group).

## default pens

{imp3:14} The most trivial use of pens is that a group defines its own set of pens, hardwiring how the drawing of the group works on the low level. For example for a group that represents a symbol, it means hardwiring the style of a "pin" (line thickness and color), thus the symbol always looks the same, no matter in which schematics sheet it is placed.

{imp3:15} However, it's equally important that symbols from different source can be combined in a sheet and they look the same. Plus the user should be able to control, on sheet level the style of the symbols. This is achieved by using the pen fallback mechanism:

- {imp3:17} there is a table about the conventional pen names all sheets expected to have
- {imp3:18} groups intended to be used on any sheet should mostly use conventional pens without defining them as pens for those purposes described below, falling back to the actual pen definitions in the direct root group; for other purposes groups should define local pens; using uppercase pen names avoids collision with future conventional names

{imp3:19} the convention for centrally defined pens
name | usage
--- | ---
sheet-decor | default sheet decoration
titlebox-frame | used for lines of the box
titlebox-fill | background fill of the titlebox
titlebox-big | used for title text
titlebox-small | used for other fields listed above
wire | default wire-net (wiring)
bus | default bus (wiring)
hub | default hubs and connection graphics for wire-nets
sym-decor | default symbol decoration lines
sym-primary | default symbol primary data text (e.g. refdes, value)
sym-secondary | default symbol secondary data text (e.g. devmap, footprint)
term-decor | default terminal decoration lines
term-primary | default terminal primary data text (e.g. number, name)
term-secondary | default terminal secondary data text
busterm-decor | default terminal decoration lines
busterm-primary | default terminal primary data text (e.g. number, name)
busterm-secondary | default terminal secondary data text
junction | default wire-net junction mark

## misc notes

{imp3:23} Property next_oid is typically not saved in files but are reproduced during load.