GDSII layout

Import a GDSII cell as extruded Polygon structures, or export geometry back out. Requires the gds extra (gdstk).

Import

import_gds

import_gds(
    gds_path: Union[str, Path],
    layers: Sequence[GDSLayer],
    *,
    cell_name: Optional[str] = None,
    axis: AxisName = "z",
    flatten: bool = True,
    min_area_um2: float = 0.0,
    max_flattened_elements: int = GDS_MAX_FLATTENED_ELEMENTS,
    max_flattened_vertices: int = GDS_MAX_FLATTENED_VERTICES,
) -> Tuple[Structure, ...]

Import a GDSII layout as a tuple of extruded Structure.

Labels, paths and polygon properties are discarded after reading because only polygons become structures. With flatten=True, hierarchies deeper than 256 levels are refused to protect the reader's thread stack.

Parameters

gds_path: Path to the .gds file. Coordinates are converted to MICRONS on read regardless of the file's user unit (a GDS authored in nm or mm imports at its true physical size). layers: The layers to import, as GDSLayer specs (each maps a GDS (layer, datatype) to a z-slab + medium). A GDS layer present in the file but absent from this list is ignored; a spec whose layer is absent from the file simply yields no structures. cell_name: Which cell to import. None (default) uses the file's single top-level cell (raising if there are several, pass a name to choose). axis: Extrusion axis = slab normal (default "z": the GDS drawing plane is (x, y)). The two GDS coordinate columns map to the two transverse axes of axis in index order, so axis="z" keeps GDS x,y as the device x,y. flatten: Resolve cell references (instances) into polygons first (default True). Required for hierarchical layouts; with False only the chosen cell's own polygons are read. min_area_um2: Drop polygons whose absolute area is below this (default 0 = keep all), a guard against zero-area slivers from boolean ops. max_flattened_elements: Maximum polygons in the flattened cell (default 100,000). Each polygon counts once per reference repetition. max_flattened_vertices: Maximum polygon outline vertices in the flattened cell (default 1,000,000). Each vertex counts once per reference repetition. Increase either limit deliberately for a trusted layout if memory is available.

Returns

tuple[Structure, ...] One Polygon structure per polygon, grouped in the given layers order (file order within a layer). Paint order is last-wins; same-material overlaps from a flattened hierarchy are therefore harmless.

read_gds_cell_names

read_gds_cell_names(
    gds_path: Union[str, Path],
) -> Tuple[str, ...]

List every cell name in a GDS file (top-level first), a discovery helper for picking cell_name / layers before import_gds.

GDSLayer dataclass

GDSLayer(
    layer: Tuple[int, int],
    medium: Medium,
    zmin_um: float,
    thickness_um: float,
    sidewall_angle: float = 0.0,
    reference_plane: str = "middle",
)

One GDS (layer, datatype) mapped to an extruded slab of one medium.

zmin_um / thickness_um give the slab extent along the extrusion axis (the import_gds axis, default z); the slab spans [zmin_um, zmin_um + thickness_um]. sidewall_angle (radians) and reference_plane are forwarded to every Polygon emitted for this layer (see Polygon).

layer instance-attribute

layer: Tuple[int, int]

medium instance-attribute

medium: Medium

zmin_um instance-attribute

zmin_um: float

thickness_um instance-attribute

thickness_um: float

sidewall_angle class-attribute instance-attribute

sidewall_angle: float = 0.0

reference_plane class-attribute instance-attribute

reference_plane: str = 'middle'

slab_bounds_um property

slab_bounds_um: Tuple[float, float]

Lower and upper extrusion heights, in microns.

Export

export_gds

export_gds(
    structures,
    gds_path: Union[str, Path],
    *,
    layers: Optional[Sequence[GDSLayer]] = None,
    axis: AxisName = "z",
    cell_name: str = "TOP",
    unit: float = 1e-06,
    precision: float = 1e-09,
    cylinder_tolerance_um: float = 0.001,
    max_points: int = 0,
    z_tol_um: float = 1e-06,
) -> Tuple[GDSLayer, ...]

Write PhotonHub structures OUT to a .gds layout, the reciprocal of import_gds. Returns the GDSLayer stack that maps the file back to structures (hand it straight to import_gds to round-trip).

structures is a sequence of Structure or a Component. Each structure's in-plane cross-section on the axis drawing plane becomes one polygon: a Box -> a rectangle, a Polygon -> its vertex polygon, a Cylinder -> a faceted (annular/wedge) polygon at cylinder_tolerance_um. Structures are grouped into GDS layers by their (z-extent, medium, sidewall_angle, reference_plane):

• layers=None (default) auto-assigns (1, 0), (2, 0), ... in first-occurrence order, one per distinct slab, medium, and sidewall setting. A vertical polygon uses the same layer as a flat shape of the same slab and medium, regardless of its reference plane.
• pass an explicit layers list (e.g. the one import_gds used) to pin the layer numbers; every structure must match one of them, including its sidewall angle and, for nonvertical walls, reference plane. Angles match within 1e-9 radians. A mismatched layer is refused. Repeated layer identifiers remain valid, as in import_gds.

Gotchas handled: max_points=0 disables gdstk's default 199-vertex polygon fracturing (a tolerance-faceted ring stays one polygon); unit/precision default to the 1 nm database grid import_gds reads. Paint order is not representable in GDS (last-wins is lost); interleaved cross-layer paint orders are flattened to layer order. Sphere and out-of-plane-extruded geometries are rejected (no top-down layer representation).