add: KiCad8 symbol properties parser and render (#138)

* add: use a class to record symbol properties

* add: render symbol properties in footprint

* fix: new test for P.dict

* add: simple test for symbol_properties parser

Author: XiangYyang

.gitignore

@@ -4,3 +4,5 @@ dist/
 www/kicanvas
 coverage/
 esbuild-meta.json
+
+.DS_Store

src/kicad/board.ts

@@ -731,7 +731,14 @@ export class DimensionStyle {
     }
 }
 
-type FootprintDrawings = FpLine | FpCircle | FpArc | FpPoly | FpRect | FpText;
+type FootprintDrawings =
+    | FpLine
+    | FpCircle
+    | FpArc
+    | FpPoly
+    | FpRect
+    | FpText
+    | SymbolProperty;
 
 export class Footprint {
     at: At;
@@ -776,7 +783,7 @@ export class Footprint {
         allow_solder_mask_bridges: false,
         allow_missing_courtyard: false,
     };
-    properties: Record<string, string> = {};
+    properties: Record<string, SymbolProperty> = {};
     drawings: FootprintDrawings[] = [];
     pads: Pad[] = [];
     #pads_by_number = new Map<string, Pad>();
@@ -826,7 +833,7 @@ export class Footprint {
                     P.atom("allow_solder_mask_bridges"),
                     P.atom("allow_missing_courtyard"),
                 ),
-                P.dict("properties", "property", T.string),
+                P.dict("properties", "property", T.item(SymbolProperty, this)),
                 P.collection("drawings", "fp_line", T.item(FpLine, this)),
                 P.collection("drawings", "fp_circle", T.item(FpCircle, this)),
                 P.collection("drawings", "fp_arc", T.item(FpArc, this)),
@@ -860,13 +867,13 @@ export class Footprint {
         // KiCad correctly parses both definitions
         //     (fp_text reference XXXX) and (property "Reference" "XXXX")
         // https://dev-docs.kicad.org/en/file-formats/sexpr-intro/index.html#_symbol_properties
-        for (const [prop_name, prop_value] of Object.entries(this.properties)) {
+        for (const [prop_name, prop] of Object.entries(this.properties)) {
             if (this.reference === undefined && prop_name == "Reference") {
-                this.reference = prop_value;
+                this.reference = prop.value;
             }
 
             if (this.value === undefined && prop_name == "Value") {
-                this.value = prop_value;
+                this.value = prop.value;
             }
         }
     }
@@ -879,6 +886,10 @@ export class Footprint {
         yield* this.drawings ?? [];
         yield* this.zones ?? [];
         yield* this.pads.values() ?? [];
+
+        yield* Object.values(this.properties).filter(
+            (prop) => prop.has_symbol_prop,
+        );
     }
 
     resolve_text_var(name: string): string | undefined {
@@ -914,7 +925,7 @@ export class Footprint {
         }
 
         if (this.properties[name] !== undefined) {
-            return this.properties[name]!;
+            return this.properties[name]!.value;
         }
 
         return this.parent.resolve_text_var(name);
@@ -949,7 +960,7 @@ export class Footprint {
             ).rotate_self(Angle.deg_to_rad(this.at.rotation));
 
             for (const item of this.drawings) {
-                if (item instanceof FpText) {
+                if (item instanceof FpText || item instanceof SymbolProperty) {
                     continue;
                 }
 
@@ -963,6 +974,63 @@ export class Footprint {
     }
 }
 
+export class SymbolProperty {
+    has_symbol_prop: boolean;
+
+    // generic properties
+    // https://dev-docs.kicad.org/en/file-formats/sexpr-intro/index.html#_properties
+    value: string;
+
+    // symbol properties
+    // https://dev-docs.kicad.org/en/file-formats/sexpr-intro/index.html#_symbol_properties
+    id: number = 0;
+    unlocked = false;
+    hide = false;
+    at: At = new At();
+    effects: Effects = new Effects();
+    layer: string = "F.SilkS";
+    uuid?: string;
+
+    constructor(
+        expr: Parseable,
+        public parent: Footprint,
+    ) {
+        // for some reasons, I cannot get kicad_version here
+        // const is_newer = parent.parent.version >= 20240108;
+        const is_newer = expr instanceof Array && expr.length > 3;
+
+        if (is_newer) {
+            this.has_symbol_prop = true;
+            // parsed as 'symbol_property' node
+            Object.assign(
+                this,
+                parse_expr(
+                    expr,
+                    P.positional("value", T.string),
+                    P.pair("id", T.number),
+                    P.item("at", At),
+                    P.pair("layer", T.string),
+                    P.pair("uuid", T.string),
+                    P.atom("unlocked"),
+                    P.atom("hide"),
+                    P.item("effects", Effects),
+                ),
+            );
+        } else {
+            this.has_symbol_prop = false;
+            // parsed as 'property' node
+            Object.assign(
+                this,
+                parse_expr(expr, P.positional("value", T.string)),
+            );
+        }
+    }
+
+    get shown_text() {
+        return expand_text_vars(this.value, this.parent);
+    }
+}
+
 class GraphicItem {
     parent?: Footprint;
     layer: string;

src/kicad/parser.ts

@@ -222,7 +222,7 @@ export const P = {
             fn: (obj: Obj, name: string, e: ListOrAtom) => {
                 const el = e as [string, string, any];
                 const rec = obj[name] ?? {};
-                rec[el[1]] = typefn(obj, name, el[2]);
+                rec[el[1]] = typefn(obj, name, el.slice(2));
                 return rec;
             },
         };

src/kicanvas/elements/kc-board/properties-panel.ts

@@ -54,9 +54,11 @@ export class KCBoardPropertiesPanelElement extends KCUIElement {
         } else {
             const itm = this.selected_item;
 
-            const properties = Object.entries(itm.properties).map(([k, v]) => {
-                return entry(k, v);
-            });
+            const properties = Object.entries(itm.properties).map(
+                ([k, prop]) => {
+                    return entry(k, prop.value);
+                },
+            );
 
             entries = html`
                 ${header("Basic properties")}

src/viewers/board/painter.ts

@@ -645,6 +645,55 @@ class FpTextPainter extends BoardItemPainter {
     }
 }
 
+class PropertyTextPainter extends BoardItemPainter {
+    classes = [board_items.SymbolProperty];
+
+    layers_for(t: board_items.SymbolProperty) {
+        return [t.layer];
+    }
+
+    paint(layer: ViewLayer, t: board_items.SymbolProperty) {
+        if (this.filter_net) return;
+
+        if (t.hide || !t.shown_text || !t.has_symbol_prop) {
+            return;
+        }
+
+        const edatext = new EDAText(t.shown_text);
+
+        edatext.apply_effects(t.effects);
+        edatext.apply_at(t.at);
+
+        edatext.attributes.color = layer.color;
+
+        // Looks like the rotation angle for KiCad's symbol attribute rendering
+        // is standalone, so we need to sub it from parent's rotation angle.
+        if (t.parent) {
+            const rot = t.parent.at.rotation;
+            edatext.text_angle.degrees -= rot;
+        }
+
+        // keep the text upright if needed
+        if (edatext.attributes.keep_upright) {
+            while (edatext.text_angle.degrees > 90) {
+                edatext.text_angle.degrees -= 180;
+            }
+            while (edatext.text_angle.degrees <= -90) {
+                edatext.text_angle.degrees += 180;
+            }
+        }
+
+        this.gfx.state.push();
+        StrokeFont.default().draw(
+            this.gfx,
+            edatext.shown_text,
+            edatext.text_pos,
+            edatext.attributes,
+        );
+        this.gfx.state.pop();
+    }
+}
+
 class DimensionPainter extends BoardItemPainter {
     classes = [board_items.Dimension];
 
@@ -984,6 +1033,7 @@ export class BoardPainter extends DocumentPainter {
             new FootprintPainter(this, gfx),
             new GrTextPainter(this, gfx),
             new FpTextPainter(this, gfx),
+            new PropertyTextPainter(this, gfx),
             new DimensionPainter(this, gfx),
         ];
     }

test/kicad/board.test.ts

@@ -21,6 +21,7 @@ import vias_pcb_src from "./files/vias.kicad_pcb";
 import footprint_graphics_pcb_src from "./files/footprint-graphics.kicad_pcb";
 import footprint_pads_pcb_src from "./files/footprint-pads.kicad_pcb";
 import footprint_text_locked_pcb_src from "./files/footprint-text-locked.kicad_pcb";
+import footprint_symbol_properties_pcb_src from "./files/footprint-properties.kicad_pcb";
 import { first } from "../../src/base/iterator";
 
 suite("kicad.board.KicadPCB(): board parsing", function () {
@@ -1045,4 +1046,43 @@ suite("kicad.board.Footprint()", function () {
             clearance: 0.5,
         } as Partial<board.Pad>);
     });
+
+    test("with footprint symbol properties", function () {
+        const pcb = new board.KicadPCB(
+            "test.kicad_pcb",
+            footprint_symbol_properties_pcb_src,
+        );
+        assert.equal(pcb.footprints.length, 1);
+
+        const fp0 = pcb.footprints[0]!;
+
+        assert.isDefined(fp0.properties["Reference"]);
+        const ref_prop = fp0.properties["Reference"]!;
+
+        assert.deepInclude(ref_prop, {
+            has_symbol_prop: true,
+            value: "C1",
+            id: 0,
+            unlocked: false,
+            hide: false,
+            at: { position: { x: 0, y: -1.43 }, rotation: 0, unlocked: false },
+            layer: "F.SilkS",
+            effects: {
+                font: {
+                    face: undefined,
+                    size: { x: 1, y: 1 },
+                    thickness: 0.15,
+                    italic: false,
+                    bold: false,
+                    color: { r: 0, g: 0, b: 0, a: 0 },
+                },
+                justify: {
+                    horizontal: "center",
+                    vertical: "center",
+                    mirror: false,
+                },
+                hide: false,
+            },
+        } as Partial<board.SymbolProperty>);
+    });
 });