Skip to content

layout.models — typed layout objects

tempura/layout/models.py defines the two typed objects that carry data between layout stages: LayoutData (the read result) and PreparedLayout (the build handoff). Using typed objects instead of loose dictionaries keeps the field names and derived geometry in one place.

LayoutData — the read result

LayoutData holds the normalized polygons from one file plus its unit metadata (unit_scale_m, unit_source, units_known, source_format). It is what a reader returns and what prepare_layout(...) consumes.

PreparedLayout — the build handoff

PreparedLayout holds the rasterized masks in gate_stencils, the internal roi_size, and the physical grid_constant_m, and exposes the derived geometry as read-only properties:

  • grid_step is the internal XY spacing, fixed at \(1.0\): after rasterization one cell is one unit.
  • grid_shape is \((n_y, n_x)\) derived from roi_size.
  • roi_size_m converts the internal ROI size back to meters through the grid constant, \(\ell_\text{m} = \ell_\text{cells} \cdot \texttt{grid\_constant\_m}\).
  • gate_vertices_by_layer recovers polygon vertices from the cropped inspection polygons for plotting.

This is the object build_device takes as input. For a small synthetic handoff in a test or illustration you can construct a PreparedLayout directly rather than running a file through prepare_layout.

API

models

Public layout workflow data objects.

LayoutData dataclass

Normalized polygons and unit metadata loaded from one layout file.

Attributes:

Name Type Description
polygons_by_layer PolygonMap

Polygons grouped by normalized layer name.
unit_scale_m float | None

Physical meters represented by one layout unit, when the source file provides unit metadata.
unit_source str | None

Name of the file metadata field used for unit_scale_m.
precision_m float | None

Layout database precision in meters, when available.
units_known bool

Whether the source file provided enough metadata to derive physical sizes directly.
source_format str

Lowercase layout format label, such as "gds", "oas", or "dxf".
Source code in tempura/layout/models.py 
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
@dataclass(slots=True)
class LayoutData:
    """Normalized polygons and unit metadata loaded from one layout file.

    Attributes:
        polygons_by_layer: Polygons grouped by normalized layer name.
        unit_scale_m: Physical meters represented by one layout unit, when the
            source file provides unit metadata.
        unit_source: Name of the file metadata field used for ``unit_scale_m``.
        precision_m: Layout database precision in meters, when available.
        units_known: Whether the source file provided enough metadata to derive
            physical sizes directly.
        source_format: Lowercase layout format label, such as ``"gds"``,
            ``"oas"``, or ``"dxf"``.
    """

    polygons_by_layer: PolygonMap
    unit_scale_m: float | None
    unit_source: str | None
    precision_m: float | None
    units_known: bool
    source_format: str

PreparedLayout dataclass

Prepared raster masks and geometry ready for device construction.

Attributes:

Name Type Description
gate_stencils MasksByLayer

Boolean masks grouped by source layer. Each mask uses row-major (ny, nx) ordering and aligns to grid_step.
roi_size tuple[float, float]

Rescaled ROI size as (length, width) in Tempura internal grid units.
grid_constant_m float

Physical meters represented by one internal grid unit.
cropped_polygons_by_layer PolygonMap | None

Optional cropped polygons kept for plotting and inspection after preparation.
Source code in tempura/layout/models.py 
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
@dataclass(slots=True)
class PreparedLayout:
    """Prepared raster masks and geometry ready for device construction.

    Attributes:
        gate_stencils: Boolean masks grouped by source layer. Each mask uses
            row-major ``(ny, nx)`` ordering and aligns to ``grid_step``.
        roi_size: Rescaled ROI size as ``(length, width)`` in Tempura internal
            grid units.
        grid_constant_m: Physical meters represented by one internal grid unit.
        cropped_polygons_by_layer: Optional cropped polygons kept for plotting
            and inspection after preparation.
    """

    gate_stencils: MasksByLayer
    roi_size: tuple[float, float]
    grid_constant_m: float
    cropped_polygons_by_layer: PolygonMap | None = None

    @property
    def grid_step(self) -> float:
        """Return the internal XY lattice spacing used for prepared masks.

        Returns:
            The fixed internal layout-grid spacing. Prepared masks always use
            unit spacing because ``grid_constant_m`` carries the physical scale.
        """
        return 1.0

    @property
    def grid_shape(self) -> tuple[int, int]:
        """Return the ``(ny, nx)`` mask shape derived from ``roi_size``.

        Returns:
            Row-major mask shape matching every stencil in ``gate_stencils``.
        """
        roi_length, roi_width = self.roi_size
        return (int(round(roi_width)), int(round(roi_length)))

    @property
    def roi_size_m(self) -> tuple[float, float]:
        """Return the physical ROI size in meters.

        Returns:
            Physical ``(length, width)`` obtained from ``roi_size`` and
            ``grid_constant_m``.
        """
        roi_length, roi_width = self.roi_size
        return (
            float(round(float(roi_length) * float(self.grid_constant_m), 15)),
            float(round(float(roi_width) * float(self.grid_constant_m), 15)),
        )

    @property
    def gate_vertices_by_layer(self) -> VerticesByLayer:
        """Return polygon vertices derived from the cropped inspection polygons.

        Returns:
            Plain nested vertex lists grouped by source layer. Returns an empty
            mapping when no cropped polygons were retained.
        """
        if self.cropped_polygons_by_layer is None:
            return {}
        return polygons_to_vertices(self.cropped_polygons_by_layer)
gate_vertices_by_layer property

Return polygon vertices derived from the cropped inspection polygons.

Returns:

Type Description
VerticesByLayer

Plain nested vertex lists grouped by source layer. Returns an empty
VerticesByLayer

mapping when no cropped polygons were retained.
grid_shape property

Return the (ny, nx) mask shape derived from roi_size.

Returns:

Type Description
tuple[int, int]

Row-major mask shape matching every stencil in gate_stencils.
grid_step property

Return the internal XY lattice spacing used for prepared masks.

Returns:

Type Description
float

The fixed internal layout-grid spacing. Prepared masks always use
float

unit spacing because grid_constant_m carries the physical scale.
roi_size_m property

Return the physical ROI size in meters.

Returns:

Type Description
float

Physical (length, width) obtained from roi_size and
float

grid_constant_m.