caidish/klayoutclaw/klayout-gds-import

klayout_gds_import — Safe GDS Import

Import a GDS file into the running KLayout session in a way that avoids the well-known Layout.read() pitfalls documented in CLAUDE.md:

• Cell-name collisions between the destination layout and the imported GDS

produce orphaned cell index slots (cells() reports N but cell(N-1) is invalid).

• After a name collision, CellView.cell may point at a destroyed cell,

causing downstream crashes.

• Multi-top-cell states are confusing for downstream routing / evaluation

tools that assume a single top cell.

This skill provides a single-shot importer that:

1. Reads the GDS into the current layout (or a fresh tab),
2. Flattens hierarchy so there are no subcells left,
3. Collapses any residual multi-top-cell state into a single top cell,
4. Rebinds CellView.cell to the resolved top, zooms to fit, and refreshes

the layer panel.

Parameters

Usage

From a shell with access to the KlayoutClaw MCP server:

python skills/klayout_gds_import/scripts/import_gds.py \
    --filepath /path/to/template.gds \
    --flatten \
    --merge-into-current

To import into a fresh tab (non-destructive to existing work):

python skills/klayout_gds_import/scripts/import_gds.py \
    --filepath /path/to/template.gds \
    --no-merge-into-current

Return value

On success the script prints a JSON blob like:

{"status": "ok", "top_cell": "TOP", "shapes_added": 1342}

On failure:

{"status": "error", "error": "<message + traceback>"}

Edge cases handled

• Cell-name collisions — the importer reads the GDS, then iterates all

top cells via each_top_cell() (never cell(i) by index) to avoid the orphaned-slot crash documented in CLAUDE.md.

• Multi-top-cell after import — if flatten=true leaves more than one

top cell, the importer picks the top cell with the largest bbox as the canonical top, moves shapes from the other top cells into it shape-by-shape via shapes().each() + shapes().insert(), and deletes the emptied cells.

• Dangling `CellView.cell` — after the read, the importer explicitly

rebinds cv.cell = <resolved_top> before returning, matching the pattern in CLAUDE.md under "Dangling cv.cell after Layout.read()".

• No destructive clear — this skill never calls Layout.clear() when

merge_into_current=true, so existing user geometry is preserved.

• Image annotations — preserved. Images live on the LayoutView, not the

Layout, so a plain read() does not touch them.

Reference

• Script: scripts/import_gds.py
• Uses: skills/scripts/mcp_client.py (shared MCP client)
• Related pitfalls: see CLAUDE.md sections on Layout.read() cell-name

collisions and dangling cv.cell.