feat(parser): add hierarchy scans and selective cell reads

Reuse library builders and cell traversal for full reads, lightweight hierarchy scans, and exact cell byte ranges. Preserve file offsets across readers and reject malformed ranges and FFI pointer/count inputs without aborting.

Document scan schemas and ID assignment. Add regression coverage for Arrow round trips, transforms, subset ordering, empty selections, and invalid input.
This commit is contained in:
Jan Petykiewicz 2026-11-14 14:27:09 -08:00
commit 9643089f2d

View file

@ -24,7 +24,7 @@ Each cell in the `cells` list is a `StructArray`.
| Field | Type | Description |
|---|---|---|
| `id` | `UInt32` | Unique identifier for the cell. |
| `file_offset` | `UInt64` | Byte offset of the cell in the original GDSII file. |
| `file_offset` | `UInt64` | Byte offset immediately after the cell's `STRNAME` record (the first element, or `ENDSTR` for an empty cell). Identical for full and selected reads. |
| `srefs` | `List(SRef)` | Simple structure references (no properties). |
| `arefs` | `List(ARef)` | Array references (no properties). |
| `sref_props` | `List(SRefProp)` | Structure references with properties. |
@ -37,6 +37,31 @@ Each cell in the `cells` list is a `StructArray`.
| `boxes` | `List(BoxNode)` | Box elements. |
| `texts` | `List(Text)` | Text labels. |
## Hierarchy Scan Schema
`scan_library` and `scan_bytes` return the same library metadata and `cell_names`
as a full read, with the following `cells` schema and no `layers` field:
| Field | Type | Description |
|---|---|---|
| `id` | `UInt32` | Cell ID indexing this result's `cell_names`. |
| `struct_start_offset` | `UInt64` | Inclusive byte offset of the `BGNSTR` record. |
| `struct_end_offset` | `UInt64` | Exclusive byte offset immediately after `ENDSTR`. |
| `refs` | `List(ScanRef)` | SREFs and AREFs, including references with properties, sorted by target ID. |
Each scan reference has `target`, `invert_y`, `scale`, `angle_rad`, `xy`, `xy0`,
`xy1`, and `counts`, using the ARef types and packed encodings described below.
SREFs use zero basis vectors and counts `(1, 1)`. Properties are omitted from the
scan output; geometry and text are skipped without decoding.
Pass the half-open scan ranges to `read_selected_library` or `read_cells_bytes`
to obtain the full library schema for just those cells. Each range must contain
exactly one complete cell, from `BGNSTR` through `ENDSTR`. Cells appear in the
requested order. Cell and layer IDs are assigned within each result, so use
`cell_names` and `layers` from that result when resolving them; IDs can differ
from a full read or a scan. An empty selection returns metadata and empty lists.
The Rust random-access reader returns the original input slice as its remainder.
## Element Types
### Common Packed Encodings