3.1 KiB
Rust and C integration
Use the Rust library or C API to read GDSII into Arrow without Python. For the returned data layout, see the Arrow reference.
Rust
Add pheon as a dependency. The library readers accept GDSII byte slices:
use pheon::library::read_library;
let bytes = std::fs::read("chip.gds").expect("read layout");
let (_remainder, layout) = read_library(&bytes).expect("parse layout");
println!("{layout:?}");
read_library reads geometry; scan_library returns metadata, references, and
cell ranges. Pass (start, end) ranges from a scan to read_selected_library
to load only those cells. Each range must span one complete cell. Readers return
(remainder, StructArray) on success. The selected reader returns the original
input as its remainder, since selection is random access.
The record, records, and basic modules also provide low-level GDSII record
writing. There is no high-level writer for the Arrow layout. REAL8 writing is
exact for representable in-range f64 values: magnitudes below 2^-260
underflow to zero; magnitudes at least 2^252 and nonfinite values are rejected.
C API
Build the shared library with cargo build --release --locked. The
header defines the functions and Arrow C Data structures.
The library is libpheon.so, libpheon.dylib, or pheon.dll on Linux, macOS,
or Windows respectively.
| Function | Input | Result |
|---|---|---|
read_path |
NUL-terminated path | Full layout. |
read_bytes |
Byte pointer and size | Full layout. |
scan_bytes |
Byte pointer and size | Metadata, references, and cell ranges. |
read_cells_bytes |
Bytes and cell ranges | Full layout for selected cells. |
read_path accepts UTF-8 paths on Windows and filesystem bytes on Unix. It reads
uncompressed GDSII; Python's read_path adds gzip handling.
For read_cells_bytes, ranges points to alternating uint64 start/end offsets
and range_count is the number of cells, not the number of offsets. Ranges are
half-open, from BGNSTR through the end of ENDSTR. Range values must be aligned,
native-endian uint64 values. Input buffers must remain readable for the call.
Null buffer pointers are allowed only when their corresponding length is zero.
Status and ownership
Each reader returns 0 on success and -1 on failure. Call last_error_message()
on the same thread after a failure. It returns a borrowed NUL-terminated message;
copy it before the next parser call or thread exit. It returns null after a
successful parser call.
Supply valid, writable, initialized ArrowArray and ArrowSchema structures
without live allocations to overwrite. A failed call leaves them unchanged.
Successful outputs own their storage independently of the input buffer. Transfer
ownership to an Arrow importer, or call each non-null release callback exactly
once. Do not release structures again after an importer takes ownership.
pheon_abi_version() and pheon_arrow_schema_version() both currently return 1.
Check both before using the API. The C calling/ownership contract and Arrow
layout have separate versions; neither is the package version or the
JSON report schema.