Document the text limit, JSON omission counters, and hierarchy options. Use absolute links for the documentation referenced by the README.
5.2 KiB
Command-line tools
Use pheon to inspect a GDSII file, compare revisions, or trace cell references.
The CLI recognizes gzip-compressed GDSII by its file header. Reported byte offsets
refer to the decompressed layout. The CLI runs independently of Python.
Install
If you downloaded a CLI archive, extract it and add the directory containing
pheon (pheon.exe on Windows) to your PATH. Run pheon --help to check it.
To install from a source checkout, use Rust 1.88 or newer:
cargo install --path . --locked --bin pheon
pheon --help
You can also build locally with cargo build --release --locked --bin pheon
and run target/release/pheon (pheon.exe on Windows).
Inspect a layout
pheon dump chip.gds
pheon dump chip.gds --records
pheon hierarchy chip.gds --format ascii --depth 4
pheon hierarchy chip.gds --format mermaid --top CHIP
dump lists objects by cell. A prefix such as 3x counts copies of the same
normalized object within a cell. Coordinates are in database units. Rectangles
show two corners, and longer vertex lists wrap across lines. References show
the target and any array dimensions before the coordinates. Add --records
to inspect the original record sequence, including timestamps.
hierarchy shows direct placement counts on references. Shared cells are
marked where their contents appear earlier in the tree. Mermaid output is
diagram source for a Mermaid renderer.
Compare revisions
pheon diff before.gds after.gds
pheon diff before.gds after.gds --hierarchy ascii --max-changes 20
pheon diff before.gds after.gds --format json > report.json
Text reports start with the result and counts of modified, added, and removed
cells. Added and removed cells show their object counts and group references by
target. Modified cells show counts of rectangles, polygons, and boxes changed,
moved, added, or removed on each layer. Repeated reference additions or removals
to the same target also appear as a count. Object details use - for removals,
+ for additions, and ~ for likely replacements. Unmatched paths with five
or more vertices show their width, vertex count, and vertex bounds in one line.
Use --format json for details of individual objects and --hierarchy to see
which parent cells are affected.
For large unscoped diffs with substantial byte overlap, Pheon reuses parsed contents of matching cells. Cell timestamps and file offsets can differ.
| Exit code | Meaning |
|---|---|
| 0 | Equal under the comparison rules and selected scope. |
| 1 | Differences found in a complete comparison. |
| 2 | Invalid input, a command error, or an incomplete comparison. |
A code of 1 is an expected comparison result. A code of 2 can accompany definite differences, but equality cannot be established. Read the comparison rules before relying on results in automation, and the JSON reference to consume reports programmatically.
Choose the comparison scope
pheon diff before.gds after.gds --top CHIP --layer 1/0
pheon diff before.gds after.gds --cell RESONATOR
| Option | Compared content |
|---|---|
--top NAME |
The named cell and its reachable descendants in each revision. |
--cell NAME |
One cell, including its references, without its descendants. |
--layer L/T |
Objects on a numeric layer/type pair, plus references leading to that layer. |
Selectors combine: --top CHIP --cell RESONATOR selects that cell within CHIP's
subtree. A name absent from both revisions is an error; presence on only one
side is an addition or deletion. Layer selection omits cells irrelevant to that
layer, but library fields and metadata-version diagnostics remain relevant.
The complete input is parsed before scope selection, so malformed records
outside the scope still fail the command.
Control report detail
pheon diff before.gds after.gds --show-cell RESONATOR --show-layer 1/0
pheon diff before.gds after.gds --hierarchy mermaid --depth 4
--show-cell and --show-layer filter displayed changes without changing the
comparison, totals, or exit status. A layer display filter hides references
without a numeric layer. --max-changes N limits displayed object occurrences
after filtering. Text defaults to 100 occurrences and shows a replacement only
when both objects fit within the limit. A single omission line lists changes
hidden by filters or the limit. JSON has no default object limit and reports
omissions from both display filters and any explicit limit in report_selection.
See the JSON reference for the selection counters.
The diff hierarchy shows directly changed cells, affected ancestors, and targets
of modified references. It includes references from both revisions so removed
branches remain visible. Counts represent direct placements, with symbolic
counts for arrays. ASCII omits the section when there are no cell changes and
marks reference changes whose placement count stays the same. Use --depth
with text output.
For the complete graph within the comparison scope, use
--format json --hierarchy graph without --depth. Display filters leave the
graph intact.
Next: configure Git integration or add layer names.