Organize documentation into focused user guides
This commit is contained in:
parent
b3346b40a4
commit
a384bb2f89
1 changed files with 798 additions and 681 deletions
133
docs/arrow-schema.md
Normal file
133
docs/arrow-schema.md
Normal file
|
|
@ -0,0 +1,133 @@
|
|||
# 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.
|
||||
Loading…
Reference in a new issue