sch-rnd-aux knowledge pool
Using pens
pen_addr by Tibor 'Igor2' Palinkas on 2022-01-21 | Tags: howto, pen, pens, style, symbol, lib, color |
Abstract: This node explains how pen addressing works and how to use it in practice to unifiy drawing style or to deviate from the unified style locally.
Groups of groups
The schematics sheet is a tree: groups of groups of groups with drawing atoms as leaves of the tree. The top level group is the "direct" group of the sheet: objects that are directly in the sheet. A wirenet (a net repersented by a connected set of wires) is a group. A symbol is a group; within the symbol's group each terminal is a group.
Each drawing atom remembers in which group they are in and groups remember their parent groups too.
How pens are used and addressed
Every drawing object gets its color and stroke properties from a pen. Pens are addressed by (human readable) name. When an object refers to a pen, the pen name is first searched in the object's parent group. If not found, the search goes one level up, to the grandparent group. This goes on until the top group (sheet's "direct" group) is reached.
Inherited vs. hardwired pens
In practice this means, for example that the decoration of a symbol (e.g. the triangle of an opamp) can be drawn in two ways:
- Inherited: use the "symbol-decor" pen, but do not specify any pen in the symbol group; when the symbol is placed on any sheet, and the triangle is being drawn, sch-rnd will see there's no symbol-decor pen within the symbol so it will go up and up until it reaches the sheet's root group ("direct"), where it is defined. In other words: all symbols will use the same, sheet defined pen for symbol decoration; all symbols have the same color/line-thickness (unified style) and if the user changes a single pen in the sheet all symbols automaically follow the change.
- Hardwired: use the "symbol-decor" pen, and do specify the "symbol-decor" pen in the symbol. When sch-rnd renders the symbol decoration, it first finds the local "symbol-decor" pen within the same symbol so it stops seaching and uses that. This way the symbol is fully self contained and specifies its own style/colors. This symbol will look the same in any schematics sheet it is placed in. However, it may not use the same style as other similar symbols on the same sheet and there's no simple, central way to unify them.
Intermediate group trick with inherited
The user may create arbitrary groups at any level, and those groups can have pens defined too. Using inherited pen symbols, it is possible to move a few of the symbols already placed on the sheet into a new group and create the "symbol-decor" pen in that new group. This new group would be between the sheet root group ("direct") and the symbols, so rendering code, while traversing the tree upward, would find and use the "symbol-decor" pen from this group before reaching the root group (and use sheet pens).
In other words: if your groups (symbols, wirenets, etc.) use the inherited pen addressing convention, it is possible to group a set of them together and change style for that group. For example this can be used to make DNP symbols render faded, or make optional parts render dashed, with a quick and easy way for objects/groups to join/leave the DNP or optional group.
Standard/custom pen names
Standard pen name conventions are listed in the cschem specification . Pens with custom name can be create any time, at any level of the hierarchy. Custom pen names can be used to work out local (per project or per company) style conventions without interfering with common conventions.
When to use inherited or hardwired
For the normal use case, it is recommended to build libs using the inherited pen method. Sch-rnd creates symbols, wirenets and other groups following this convention.
In some special cases it may be useful to have hardwired pens. For example if a non-standard feature should be drawn into a symbol that doesn't have a conventional pen name (e.g. a big red warning). Or a local (per project or per company) convention may use an entierly different set of pens and may decide to go with hardwired pens and use other methods for unification (e.g. symbol generation).