pheon/docs/layer-names.md

44 lines
1.8 KiB
Markdown
Raw Normal View History

# Layer names
Attach readable names to numeric GDSII layer/type pairs so Pheon can show a
legend in comparison reports. Names are annotations; geometry keeps its numeric
layer assignments.
## Add or update names
```sh
pheon name-layers chip.gds named.gds --cell CHIP --carrier 900/7 \
--name 1:0:WG --name 2:0:METAL
```
Choose an existing cell and an otherwise unused `(layer, texttype)` pair in that
cell as the carrier. The carrier must contain no ordinary design objects.
The output path must be new; Pheon refuses to overwrite any existing file,
including the input.
The command consolidates the legend into that cell. Existing mappings remain
unless you override them with `--name`. It creates no cells or references, and
copies other records, timestamps, unknown records, and trailing padding byte for
byte. Input and annotation validation finish before the output is created.
## Annotation format
A text label whose exact string is `KLAMATH_LAYER_NAMES_V1` identifies a carrier
pair in its cell. Every other text label on that pair in the same cell is a
mapping of the form:
```text
layer:datatype:name
```
For example, `1:0:WG` names pair `(1, 0)` as WG. Numbers are unsigned 16-bit
decimals. The name must be nonempty UTF-8 and may contain colons; only the first
two colons separate fields. The legacy marker remains part of the format.
Mappings are collected across the library. Identical duplicates are accepted;
conflicting names for the same pair are errors. Recognized annotation labels
are excluded from ordinary object comparison. The name mapping compares
separately, while unchanged names remain available in the report legend.
Pheon does not currently read LayoutEditor LayerNames metadata, extract layers,
or remap geometry. See the [CLI guide](cli.md) for layer selection during review.