pheon/docs/arrow-schema.md

133 lines
6 KiB
Markdown

# 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](python.md) 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](native-api.md) 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](cli.md#inspect-a-layout) when original
records matter.