| name | nanodevice_gdsalign |
| description | Align microscope stack images to a GDS fabrication template using lithographic marker detection. Computes image→GDS transform and commits warped image + material contours to KLayout. |
nanodevice_gdsalign — GDS Template Alignment
Align microscope images to a GDS fabrication template by detecting lithographic markers in both domains and computing a similarity transform.
Coordinate system after gdsalign: Coordinates in traces_gds.json are in the GDS reference frame (floating-point micrometers). When using them in execute_script, convert to dbu via int(value_um / layout.dbu). Do NOT apply the flakedetect_commit image-center transform — gdsalign already handles the coordinate mapping.
Prerequisites
- Conda env
instrMCPdev with opencv, numpy, scipy, gdstk
- Template GDS file with L5/0 alignment markers (4 cross pairs)
- flakedetect output:
traces.json with material contours in pixel coordinates
- All scripts:
${PYTHON_PATH:-conda run -n instrMCPdev python} <script>
Default Output Directory
If the user does not specify an output path, default to <stack_image_dir>/output/gdsalign/ (the directory containing the source images). Never use /tmp as the default output.
Agent Workflow
1. extract_markers — Parse GDS, find 4 innermost L5/0 marker pairs
→ gds_markers.json (pair centers + bounding boxes in um)
2. detect_markers — Find marker crosses in microscope image
→ image_markers.json (detected centers in pixel coordinates)
3. align_gds — Match GDS↔image marker pairs, compute reflected similarity
→ gds_warp.npy (2x3 affine), gds_alignment_report.json
4. commit_gds — Warp image + transform contours, commit to KLayout
→ full_stack_gds.png, traces_gds.json, image_placement.json
Scripts Reference
extract_markers.py
${PYTHON_PATH:-conda run -n instrMCPdev python} skills/nanodevice_gdsalign/scripts/extract_markers.py \
--gds Template.gds --output-dir output/gdsalign/
Parses GDS, finds all L5/0 polygons, selects the 8 closest to grid center, groups into 4 pairs by proximity, labels NE/NW/SE/SW.
Outputs: gds_markers.json
detect_markers.py
${PYTHON_PATH:-conda run -n instrMCPdev python} skills/nanodevice_gdsalign/scripts/detect_markers.py \
--image stack.png --pixel-size <um/px> \
--gds-markers output/gdsalign/gds_markers.json \
--output-dir output/gdsalign/
Renders marker-pair templates from gds_markers.json, then runs multi-method template matching (grayscale, inverted, CLAHE, edge) with geometric consistency filtering to find the 4 marker pairs.
Outputs: image_markers.json, 01_template.png, 03_detections.png
Verification: After running, view 03_detections.png. The 4 detected markers (colored circles) should form a roughly square pattern, ~300-400 um apart (a few thousand pixels at 0.087 um/px), centered in the image near the flake region. The pixel_size parameter is critical for correct template rendering — use the value specified in the task instructions (typically 0.087 um/px). If detections look wrong (markers on image edges, or only 2-3 found), check that pixel_size matches the actual microscope magnification.
align_gds.py
${PYTHON_PATH:-conda run -n instrMCPdev python} skills/nanodevice_gdsalign/scripts/align_gds.py \
--gds-markers output/gdsalign/gds_markers.json \
--image-markers output/gdsalign/image_markers.json \
--output-dir output/gdsalign/
Exhaustive enumeration over 2-point correspondences finds the best reflected similarity (image Y-down → GDS Y-up), then least-squares refinement over all inliers. Automatically resolves rotational ambiguity (90°/180°/270°) for symmetric marker patterns by preferring the solution closest to 0° rotation.
Outputs: gds_warp.npy (2×3 affine matrix), gds_alignment_report.json
commit_gds.py
${PYTHON_PATH:-conda run -n instrMCPdev python} skills/nanodevice_gdsalign/scripts/commit_gds.py \
--warp output/gdsalign/gds_warp.npy \
--traces output/combine/traces.json \
--image full_stack_raw.jpg --pixel-size <um/px> \
--gds Template.gds --output-dir output/gdsalign/ [--warp-only]
Warps the microscope image and material contours into GDS coordinates using the affine from align_gds.py. Without --warp-only, also loads the GDS template into KLayout, adds the warped image as a background overlay, and inserts material polygons on layers 10–13.
| Flag | Description |
|---|
--warp | Path to gds_warp.npy (2×3 affine matrix) |
--traces | Path to traces.json from flakedetect (with contour_um fields) |
--image | Full-stack microscope image |
--pixel-size | Image pixel size in um/px |
--gds | Template GDS file (loaded into KLayout during commit) |
--output-dir | Optional output directory for warp results (default: current working directory). Set this to the agent's workspace directory to keep warp outputs scoped. Files written: traces_gds.json, full_stack_gds.png, image_placement.json |
--warp-only | Only produce warped files, skip KLayout commit |
--mcp-config | Path to MCP config JSON. Fallback chain: .mcp.json in CWD → mcp_config.json in project root → default 127.0.0.1:8765. In Docker, pass a config pointing to http://host.docker.internal:8765/mcp |
--align-report | Path to gds_alignment_report.json for the registration gate. Default: auto-located next to --warp. |
--gds-markers | Path to gds_markers.json for the marker-field frame check. Default: auto-located next to --warp. |
--skip-registration-check | Escape hatch — strongly discouraged. Bypasses the registration self-validation gate. Only for an intentional hand-built transform. |
Outputs: full_stack_gds.png, traces_gds.json, image_placement.json
⚠️ Validated-commit contract — commit flakes ONLY through commit_gds.py
commit_gds.py is the only sanctioned way to place flake polygons in the
GDS frame. Do NOT hand-place flakes via execute_script with a
hand-built transform (a centered shift / Y-flip / "1:1 at origin"). That is
the dominant failure mode (HM08/QH06/AH06): the device looks perfect against
the agent's own flakes but lands hundreds of um off the real marker field and
scores ~0.
Before committing, commit_gds.py runs a registration self-validation
gate (no ground truth — only the alignment report, the marker grid, and your
own warped contours). It hard-fails (exit 3) when:
- there is no
gds_alignment_report.json next to the warp (alignment was
skipped / hand-rolled),
- the alignment is bad (
< 3 inliers or mean residual > 5 um),
- the
--warp matrix does not match the alignment report (a stale/hand-built
transform), or
- the warped flakes land outside the L5 marker field.
If the gate fails, FIX the alignment — do not bypass it. Almost always the
cause is a wrong pixel_size: re-run validate_pixel_size, then
detect_markers → align_gds, and commit the resulting gds_warp.npy. Only
pass --skip-registration-check if you are deliberately committing a
hand-built transform and understand it will likely be off-frame.
Acceptance Thresholds
| Metric | Pass | Fail |
|---|
| Markers detected | >= 3 | < 3 |
| Inliers (align_gds) | >= 2 | < 2 |
| Mean residual | < 5.0 um | >= 5.0 um |
Fail on any metric: Do NOT commit to KLayout. Check diagnostic images and retry.
Known Behaviour
- Rotational ambiguity: Square marker grids have rotational symmetry — θ, θ+90°, θ+180°, θ+270° can yield similar residuals.
align_gds.py automatically tries all four companions and picks the one with rotation closest to 0°.
- PNG orientation: The warped PNG (
full_stack_gds.png) is vertically flipped on save so that row 0 holds GDS-north data. KLayout's pya.Image renders PNG row 0 at the high-Y edge of the placement bbox, so the image ends up right-side-up when placed at origin_um = (x_min, y_min) with identity rotation. If you inspect the PNG in a file viewer it will already look correct (north at top).
- Image ↔ contour consistency: The warped image and the transformed contours (
traces_gds.json) are produced from the same affine. If you re-run the alignment at a different pixel_size, you must also re-run commit_gds.py with the same pixel_size. Mixing a gds_warp.npy produced at one pixel size with commit_gds.py --pixel-size at another will place the image at the wrong scale (the scale factor in the warp matrix compensates for the pixel_size used during alignment).
- Destructive commit:
commit_gds.py calls layout.clear() before loading the template into KLayout, so any pre-existing geometry in the current tab is wiped. This is intentional — it avoids cell-name collisions in Layout.read() that otherwise leave orphaned cell indices. Run commit_gds.py against a fresh tab (or use the create_layout MCP tool first) if you have ongoing work you don't want to lose.
Pixel Size Validation
The pixel_size parameter (um/px) is critical for correct template rendering in detect_markers.py and image placement in commit_gds.py. Always validate the pixel size before running the pipeline.
Common pixel_size values by objective magnification:
| Objective | Typical pixel_size (um/px) |
|---|
| 100x | 0.05 |
| 100x (alt) | 0.087 |
| 50x | 0.1 |
| 20x | 0.25 |
| 10x | 0.5 |
Use validate_pixel_size to confirm the value before running the alignment pipeline. If the pixel size is wrong, marker detection will fail or produce incorrect transforms.
Exit Codes
| Code | Meaning |
|---|
| 0 | Success |
| 1 | Error (missing file, insufficient markers, transform failure) |
| 3 | commit_gds.py registration self-validation failed (skipped/hand-rolled/off-frame transform) — fix the alignment, do not bypass |
