Open a GDS or OASIS layout read-only and start a session.

Call this first. The returned session_id is required by every other tool. Sessions expire after a period of inactivity; call close_session when finished.

Args: path: Absolute path to a .gds or .oas file. top_cell: Top cell to use by default. Defaults to the alphabetically first top cell. format: Explicit format (gds or oas) when the file extension is ambiguous.

Close a session and delete its artifact directory (renders, DRC output).

Args: session_id: Session returned by open_layout.

List cells in the layout hierarchy, sorted by name.

Each entry has the cell bounding box in microns, whether it is a top cell, its direct child instance count, and its direct shape count.

Args: session_id: Session returned by open_layout. max_depth: Only include cells within this many levels of a top cell (0 = top cells only, 1 = top cells and their direct children). Omit to list every cell.

Describe one cell: bounding box, child instances, text labels, and shapes per layer.

Args: session_id: Session returned by open_layout. cell: Name of the cell to describe. depth: How many levels of child instances to expand (0 = none).

List every layer in the layout with its layer/datatype, name, and shape count.

Use the returned {layer, datatype} pairs as layer filters in other tools.

Args: session_id: Session returned by open_layout.

Return shapes, text labels, and child instances overlapping a box.

Each returned shape has a session-stable id (e.g. shp_1a2b3c4d). Pass these ids to measure_geometry, analyze_waveguide, or render_view annotations. Results are sorted deterministically; truncation reports how many items the limits dropped.

Args: session_id: Session returned by open_layout. box: Query window in microns: {"left", "bottom", "right", "top"}. cell: Cell to query. Defaults to the session's selected top cell. layers: Optional [{"layer": int, "datatype": int}] filter. Defaults to all layers. hierarchy_mode: top for shapes placed directly in the cell, or recursive / flattened to include shapes from child cells transformed into the cell's coordinates. max_shapes: Maximum number of shapes to return. max_instances: Maximum number of child instances to return. max_texts: Maximum number of text labels to return.

Measure a value from shapes previously returned by query_region.

Modes and the number of target_ids they take: path_width (1), segment_length (1), bend_radius_estimate (1), centerline_distance (2, bounding-box centers), edge_gap (2, bounding-box gap), overlap (2, bounding-box overlap area). Results are in microns and database units.

Args: session_id: Session returned by open_layout. mode: Measurement mode (see above). target_ids: Shape ids from query_region.

Analyze a path shape as a waveguide: width, length, orientation, and bend estimate.

Args: session_id: Session returned by open_layout. target_id: Id of a path shape returned by query_region.

Set the session's default render view used by later render_view calls.

Omitted arguments keep their current value. Changing cell without a box auto-fits the view to that cell.

Args: session_id: Session returned by open_layout. box: View window in microns: {"left", "bottom", "right", "top"}. cell: Cell to render. layers: Visible layers as [{"layer": int, "datatype": int}].

Render layout geometry to a PNG and return its absolute path.

Arguments given here also update the session's default view (see set_view).

Args: session_id: Session returned by open_layout. box: View window in microns. Defaults to the current view. cell: Cell to render. Defaults to the current view's cell. layers: Visible layers as [{"layer": int, "datatype": int}]. image_size: Output size in pixels: {"width": int, "height": int} (default 1200x800). annotations: Overlays such as [{"kind": "shape_outline", "target_ids": ["shp_..."], "color": "#ff3b30"}]. Targets must come from query_region on the rendered cell. style: light, dark, or mask.

Run a KLayout DRC deck in batch mode against the session layout.

The deck receives $input_path and $report_path variables and must write its report to $report_path. Returns a run_id and marker counts per rule; pass the run_id to extract_markers for marker locations. Requires the klayout executable (on PATH or via KLAYOUT_BIN).

Args: session_id: Session returned by open_layout. script_path: Absolute path to the DRC deck. script_type: Deck language. Only ruby is supported. params: Extra variables passed to the deck with -rd name=value.

Return the violation markers from a run_drc_script run.

Args: session_id: Session returned by open_layout. run_id: Run id returned by run_drc_script. include_crops: Also render a PNG crop around each marker. crop_size_um: Crop window size in microns: {"x": float, "y": float} (default 20x20).