pheon/docs/arrow-schema.md

6 KiB

Arrow layout reference

This reference is for consumers of Pheon's Arrow readers. Each result is a one-row StructArray representing a GDSII library. The Python guide shows how to obtain and access it.

Geometry fields named layer are indices into the result's layers table. Reference target and cell id values index its cell_names table. Resolve IDs using tables from the same result; a selected read can assign different IDs.

pheon_arrow_schema_version() currently returns 1 for all layouts below. Consumers of the C API must check both this application schema version and the separate C API version.

Full library

Field Arrow type Meaning
meters_per_db_unit Float64 Database unit size in meters.
user_units_per_db_unit Float64 User units per database unit.
lib_name Utf8 Library name.
mod_time, acc_time FixedSizeList(Int16, 6) Modification/access time: year, month, day, hour, minute, second.
cells List(Cell) Cell records.
cell_names List(Utf8) Names indexed by cell ID.
layers List(UInt32) Packed layer/type pairs indexed by layer ID.

Cell

Field Arrow type Meaning
id UInt32 Index into cell_names.
file_offset UInt64 Byte offset immediately after STRNAME, before the first element or ENDSTR.
srefs, arefs List(SRef), List(ARef) References without properties.
sref_props, aref_props List(SRefProp), List(ARefProp) References with properties.
rect_batches List(RectBatch) Optimized rectangular boundaries.
boundary_batches List(BoundaryBatch) Other boundaries without properties.
boundary_props List(BoundaryProp) Boundaries with properties.
paths List(Path) Paths.
nodes, boxes List(BoxNode) Node and box elements.
texts List(Text) Text labels.

Hierarchy scan and selected reads

Scans return the same metadata and cell_names, omit layers, and replace cells with these records:

Field Arrow type Meaning
id UInt32 Index into this result's cell_names.
struct_start_offset UInt64 Inclusive offset of BGNSTR.
struct_end_offset UInt64 Exclusive offset after ENDSTR.
refs List(ScanRef) References sorted by target ID, with properties omitted.

ScanRef has ARef's fields below. An SREF uses zero basis vectors and counts (1, 1). Geometry and text are skipped without decoding.

Pass complete half-open cell ranges to read_selected_library in Rust or read_cells_bytes in Python/C. The result uses the full library layout, with cells in requested order. An empty selection returns metadata and empty lists. Offsets always refer to the original uncompressed input. The Rust selected reader returns the original input slice as its remainder.

Packed values

Value Storage Decoding
Layer/type pair in layers UInt32 Layer in high 16 bits; datatype/texttype/boxtype/nodetype in low 16 bits.
Point or vector UInt64 Signed Int32 x in high 32 bits, signed Int32 y in low 32 bits.
Array counts UInt32 Columns in high 16 bits, rows in low 16 bits.

Layer halves preserve the original 16-bit patterns; reinterpret them as signed Int16 where an integration uses signed GDS layer values. Array counts originate from positive Int16 values. Flattened coordinate lists below use [x, y, ...] in integer database units.

References

SRef field Arrow type Meaning
target UInt32 Target cell ID.
invert_y Boolean Reflection flag.
scale Float64 Magnification.
angle_rad Float64 Rotation in radians.
xy UInt64 Packed origin.

ARef adds xy0 and xy1 (UInt64 packed column/row increments) and counts (UInt32). SRefProp and ARefProp add properties: List(Property).

Array increments must be exact signed 32-bit integers. All Arrow readers reject fractional or out-of-range endpoint/count division rather than rounding it. One-placement AREFs can be normalized to SREFs. The review CLI retains original endpoints and distinguishes SREF from AREF independently of this representation.

Geometry and text

Every layer below is a UInt32 table index, not a packed pair.

Type Fields beyond layer
RectBatch rects: List(Int32), flattened [min_x, min_y, max_x, max_y] rectangles.
BoundaryBatch vertices: List(Int32); vertex_offsets: List(UInt32) gives each boundary's start in points, not scalar coordinates.
BoundaryProp vertices: List(Int32); properties: List(Property).
BoxNode xy: List(Int32); properties: List(Property).
Path Fields below.
Text Fields below.
Path field Arrow type Meaning
path_type Int16, nullable Stored path type.
extension_start, extension_end Int32, nullable End extensions.
width Int32, nullable Null when WIDTH is absent.
xy List(Int32) Centerline coordinates.
properties List(Property) Element properties.
Text field Arrow type Meaning
presentation_horiz, presentation_vert, presentation_font UInt8, nullable Presentation attributes.
path_type Int16, nullable Stored path type.
width Int32, nullable Stored width.
invert_y Boolean, nullable Reflection flag.
mag Float64, nullable Magnification.
angle_deg Float64, nullable Rotation in degrees.
xy UInt64 Packed position.
string Utf8 Label text.
properties List(Property) Element properties.

Property contains key: Int16 and value: Utf8. The reader preserves property order and duplicates. Property-list fields are nullable in the schema; the reader normally emits valid lists, including empty ones.

Geometry batching and reference normalization mean this layout is not a verbatim record stream; use the CLI's record dump when original records matter.