zigfitsio 0.1.1__tar.gz

zigfitsio-0.1.1/.gitignore

@@ -0,0 +1,17 @@
+.zig-cache/
+zig-out/
+*.o
+.claude/
+
+# Python bindings
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.pytest_cache/
+.venv/
+# Zig-built shared library staged into the package by hatch_build.py
+bindings/python/src/zigfitsio/*.so
+bindings/python/src/zigfitsio/*.dylib
+bindings/python/src/zigfitsio/*.dll

zigfitsio-0.1.1/CHANGELOG.md

@@ -0,0 +1,140 @@
+# Changelog
+
+All notable changes to `zigfitsio` are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/); the project adheres to
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html) (`NFR-API-1`).
+
+## [Unreleased]
+
+_Nothing yet._
+
+## [0.1.1] - 2026-07-02
+
+### Fixed
+A swarm bug hunt over the ctypes bindings + C-ABI boundary fixed 27 confirmed defects (the prior
+suite exercised none of these paths; `bindings/python/tests/test_bugfixes.py` now pins them):
+- **Critical:** `open()` → `writeto()`/`to_bytes()` no longer silently drops image/table data — an
+  attached HDU list is copied byte-faithfully (raw device passthrough), and the reconstruction path
+  serializes materialized data for detached/mixed lists.
+- **Crashes:** using an attached HDU after `close()`, and `verify()` on a Python-built HDU list, now
+  raise `FitsError` instead of segfaulting; the C-ABI `zf_*` exports null-check their handle
+  argument (`NULL_INPUT_PTR`, 104).
+- **Silent corruption:** non-native-endian arrays are coerced to native before write; numpy scalar
+  header values (`np.int64/np.float32/np.bool_`) are written with the correct FITS type; out-of-range
+  integer keywords raise instead of wrapping; non-ASCII table strings and ragged/empty tables raise.
+- **Reads:** binary-table columns honor `TSCAL`/`TZERO` (fractional scaling → float; unsigned
+  `TZEROn` → `u2/u4/u8`, no more overflow); VLA columns decode with their real element type (not
+  always `float64`); long-string `CONTINUE` values and `HIERARCH` keywords are parsed.
+- **Writes (feature completion):** unsigned `u2/u4/u8` images and columns, and variable-length-array
+  columns, are now writable; update-mode image data edits are written back on `flush()`.
+- **API/packaging:** `getdata` falls through an empty primary and `hdul['PRIMARY']` resolves
+  (astropy parity); the wheel build hook and dev loader find the Windows DLL under `zig-out/bin` and
+  derive the library name + wheel tag from `ZIG_TARGET`; image element-count ABI widened to 64-bit.
+
+Core-library and build fixes in the same window:
+- **WCS:** `altSuffix` no longer returns a dangling stack temporary — alternate-WCS keyword
+  lookups misbehaved in ReleaseFast builds (Debug's stack layout masked it).
+- **I/O:** `appendHdu` rolls back device growth when it fails after the header write; `sync` on a
+  read-only file device is a no-op (Windows `FlushFileBuffers` fails on read-only handles, which
+  POSIX `fsync` had masked).
+- **Packaging/CI:** wheel builds fixed on Windows (skip 32-bit `*-win32`) and macOS (pin the 11.0
+  deployment target); the retired `macos-13` runner replaced with `macos-15-intel`.
+
+### Added
+- `zf_create_tbl_heap` C-ABI entry point (reserves `PCOUNT` heap for VLA writes).
+
+## [0.1.0] - 2026-06-30
+
+### Added
+- Build scaffolding: `zig build` (static library), `test`, `bench`, `fuzz`, and
+  `wasm-check` steps; dependency-free `build.zig.zon` (`SETUP-1`).
+- MIT license; README usage examples and changelog (`X-DOC`).
+- **M0 foundation:** error sets + CFITSIO status map, diagnostics, version/`errorText`,
+  resource limits with validate-before-allocate, big-endian access, numeric-conversion policy.
+- **I/O layer:** `Device` vtable; in-memory, file, and stream backends; 2880-byte block
+  buffering with the correct pad kinds.
+- **Header layer:** keyword name normalization + wildcard matching, value parsing (the
+  null/empty/undefined distinction, `CONTINUE`, `HIERARCH`), 80-byte cards, the header
+  container with read + full edit operations and header-space pre-allocation.
+- **HDU model & `Fits` handle:** kind detection, mandatory-keyword validation, lazy HDU scan,
+  navigation, and the programmatic image/HDU builders.
+- **HDU editing (`FITS-1b`):** a block-aligned data-resize + following-HDU shift primitive
+  (`resizeHduData`/`refreshGeometry`/`rewriteHeaderInPlace`), plus `deleteHdu`/`copyHdu`.
+- **Images:** `ImageView` over all six `BITPIX`; full/contiguous/strided-section pixel I/O;
+  `BSCALE`/`BZERO` scaling; unsigned-integer convention; `BLANK`/NaN nulls; `reshape` (`IMG-7`).
+- **Tables:** ASCII and binary tables (all `TFORM` codes, scaling, nulls, `A`-format,
+  `TDIM`), variable-length arrays with a compacting heap; binary-table row/column structural
+  operations — append/insert/delete/copy rows and columns (`BTB-3b`).
+- **Integrity:** `DATASUM`/`CHECKSUM` compute/update/verify.
+- **WCS:** keyword set parse/serialize; celestial transforms (zenithal family + `CAR`);
+  spectral and time-coordinate keywords.
+- **Compression:** GZIP_1/GZIP_2 codecs and the type-aware byte shuffle; RICE_1, PLIO_1, and
+  HCOMPRESS_1 tile codecs; subtractive dithering with the Park–Miller generator; a tiled
+  compressed-image **write** path; and tile-compressed-table (`ZTABLE`) reading.
+- **Extended I/O & convenience:** CFITSIO-style extended-filename DSL → `FileSpec` (`EFN-1`);
+  whole-file gzip backend (`RMT-1`); ASCII header-template loader (`TPL-1`); hierarchical
+  grouping tables, read and edit (`GRP-1`).
+- **Utilities:** date/time + Julian-Date helpers; `TFORM`/`TDISP` parsing.
+- **Cross-cutting:** fuzz harnesses for the parsers; a CI portability matrix
+  (incl. a big-endian QEMU cell and a wasm32-freestanding build); real bulk-image throughput
+  benchmarks (`X-BENCH`); and the **full** upper-layer stack now compiles for
+  wasm32-freestanding (`X-WASM`).
+- **HTTP(S) range-GET backend (`RMT-2`):** `src/io/http.zig`'s `HttpDevice` serves a remote
+  FITS file as a seekable read-only `Device` via Range GETs, falling back to a full in-memory
+  download when the server lacks range support; excluded from the freestanding build graph.
+- A transparent `.fits.gz` open path and a committed sample FITS corpus.
+- **In-house end-to-end harness (`test/e2e.zig`):** a CFITSIO `testprog.c`-equivalent that builds a
+  maximal multi-HDU file exercising every `BITPIX`/`TFORM`, all four tile codecs, VLA, WCS,
+  `CONTINUE`/`HIERARCH`, and checksums, then reopens and asserts — plus a deterministic
+  byte-snapshot regression tripwire. New `zig build e2e` step.
+- **CFITSIO 4.6.4 golden corpus (`test/golden/`, `X-FIXTURES`):** reference tiles
+  (RICE/GZIP/PLIO/HCOMPRESS), a checksum vector, images, tables, WCS, and conformance fixtures,
+  authored by `fpack` + a CFITSIO C generator under `interop/` (`MANIFEST.json` with sha256),
+  consumed hermetically by `test/golden.zig` on every cell (incl. big-endian s390x).
+- **`interop` CI job (`X-XVAL`/`X-INTEROP`/`X-CONF`):** opens every zigfitsio-written file with
+  CFITSIO `funpack`, Astropy, and `fitsverify` (`tools/emit_fixtures.zig`, `zig build
+  emit-fixtures`); path-gated and toolchain-isolated from the hermetic matrix.
+- **C-ABI shim (`bindings/capi/`, `zig build capi`):** a dynamic library `zigfitsio_capi`
+  exporting `zf_*` symbols over the public Zig module. The comptime-generic API is monomorphized
+  behind runtime datatype codes; Zig errors map to CFITSIO-compatible status ints via
+  `errors.cfitsioStatus`, with a thread-local last-error (message + `Diagnostics` detail). Covers
+  the full surface: lifecycle (file/memory/gzip), HDU navigation + delete/copy, header read/edit,
+  images (read/write/section/reshape with scaling + nulls), binary & ASCII tables, VLAs, tiled
+  compression write, checksum, structural validation, and WCS celestial transforms. The
+  hand-written contract is `bindings/c/zigfitsio.h`; `zig build capi-test` round-trips the ABI.
+  This is **not** a CFITSIO `fits_*`/`ff*` drop-in — it is a purpose-built ABI for bindings.
+- **Python bindings (`bindings/python/`):** a low-level `ctypes` 1:1 binding (`zigfitsio.lowlevel`)
+  with a typed `FitsError` hierarchy, and a high-level NumPy-first API (`zigfitsio`) modeled on
+  `astropy.io.fits` — `open`, `HDUList`, `Primary`/`Image`/`CompImage`/`BinTable`/`AsciiTable`
+  HDUs, `Column`, a dict-like `Header`, `getdata`/`getheader`/`getval`/`writeto`/`verify`, and
+  celestial WCS. Includes a pytest suite (low + high level, **Astropy cross-checks both
+  directions**, and the committed golden corpus), packaging (`pyproject.toml` + a hatch build hook
+  that compiles and bundles the shared library), and a cibuildwheel matrix workflow.
+
+### Fixed
+- **FITS-conformance correctness pass:** ASCII-table fields now space-fill (not NUL/zero) per
+  `FR-IO-2`; the `CONTINUE`/`HIERARCH`/complex-value header API is wired through
+  `getLongString`/`appendLongString`/`getHierarch`/`getComplex`; float-exponent formatting
+  follows §4.2.4 and FORTRAN-real parsing accepts `D`/`E` exponents; `TDISP` `EN`/`ES`/`G`
+  rendering; `copyHdu` rolls back cleanly on partial failure; write-path keyword-order
+  validation; WCS `CAR`/`LATPOLE` pole rotation corrected; `MJDREF` precedence + a time-keyword
+  writer and completeness fixes; image-section streaming; `TDIM` string arrays; heap-bounds
+  hardening; and grouping-table fixes.
+- **Standard-wire-format codec rewrites:** `PLIO_1` now follows the FITS Table 38 instruction
+  set and `HCOMPRESS_1` the White-1992 quadtree wire format; tiled `ZBLANK`, transparent
+  compressed-image reads (`ImageView.of`), and the write-side codec wiring are all in place.
+- **Iterator** null substitution.
+- **`PLIO_1` was not CFITSIO-interoperable in either direction:** the codec omitted the IRAF/CFITSIO
+  7-word line-list header and stored `COMPRESSED_DATA` as `1PB` instead of `1PI`. Both fixed —
+  zigfitsio now reads genuine CFITSIO PLIO tiles and writes tiles `funpack`/Astropy decode to the
+  exact pixels (caught by the golden corpus).
+- **`checksum_on_close` was a silent no-op:** the `flush` hook was declared but never registered, so
+  no `DATASUM`/`CHECKSUM` was written. Now wired (`src/fits.zig` reserves the cards at HDU-build
+  time; `src/checksum.zig` registers `updateAll`).
+
+### Notes
+- The HTTP(S) range-GET backend (`RMT-2`) is **done**.
+- **Byte-exact CFITSIO 4.6.4 / Astropy golden-corpus parity is now done** (`X-FIXTURES`/`X-SUM`/
+  `X-XVAL`/`X-CONF`/`X-INTEROP`): the tile codecs and checksum are verified against committed CFITSIO
+  tiles both inbound and outbound. The one remaining codec limit is `HCOMPRESS_1` lossy `hsmooth`
+  (lossless only); see `CAVEATS.md §1`.

zigfitsio-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Armando Herrera
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

zigfitsio-0.1.1/PKG-INFO

@@ -0,0 +1,145 @@
+Metadata-Version: 2.4
+Name: zigfitsio
+Version: 0.1.1
+Summary: Python bindings for zigfitsio — a pure-Zig FITS 4.0 I/O library
+Project-URL: Repository, https://github.com/anhydrous99/zigfitsio
+Author: zigfitsio contributors
+License: MIT
+License-File: LICENSE
+Keywords: FITS,astronomy,astrophysics,cfitsio,io,zig
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Astronomy
+Requires-Python: >=3.9
+Requires-Dist: numpy>=1.20
+Provides-Extra: test
+Requires-Dist: astropy>=5; extra == 'test'
+Requires-Dist: pytest>=7; extra == 'test'
+Description-Content-Type: text/markdown
+
+# zigfitsio (Python)
+
+Python bindings for [**zigfitsio**](https://github.com/anhydrous99/zigfitsio) — a pure-[Zig](https://ziglang.org)
+implementation of [FITS](https://fits.gsfc.nasa.gov) 4.0 I/O with feature parity goals against
+CFITSIO, and **no C dependencies**.
+
+Two layers are provided:
+
+- **High-level**, NumPy-first API modeled on `astropy.io.fits` — `open`, `HDUList`, the HDU
+  classes, `Column`, `Header`, and the `getdata`/`getheader`/`writeto`/`verify` conveniences.
+- **Low-level** 1:1 `ctypes` binding under `zigfitsio.lowlevel` (the C ABI from
+  `bindings/c/zigfitsio.h`) for power users.
+
+The native code is a Zig-built shared library loaded via `ctypes`; there is **no C compiler
+requirement** at install time when using a prebuilt wheel.
+
+## Install
+
+```sh
+pip install zigfitsio          # prebuilt wheel (recommended)
+```
+
+Building from source requires a Zig toolchain (supplied automatically by the `ziglang` build
+dependency, or a system `zig` 0.16 on `PATH`).
+
+## Quickstart
+
+```python
+import numpy as np
+import zigfitsio as zf
+
+# Write an image
+zf.writeto("image.fits", np.arange(12, dtype="f4").reshape(3, 4), overwrite=True)
+
+# Read it back (NumPy array, shape (NAXIS2, NAXIS1), C-order — like astropy)
+with zf.open("image.fits") as hdul:
+    data = hdul[0].data
+    hdr = hdul[0].header
+    print(data.shape, hdr["NAXIS1"])
+
+# Build a binary table
+cols = [
+    zf.Column("INDEX", "J", np.array([10, 20, 30], dtype="i4")),
+    zf.Column("FLUX",  "E", np.array([1.5, 2.5, 3.5], dtype="f4"), unit="Jy"),
+    zf.Column("NAME",  "8A", np.array(["alpha", "beta", "gamma"])),
+]
+zf.HDUList([zf.PrimaryHDU(), zf.BinTableHDU.from_columns(cols, name="EVENTS")]).writeto(
+    "table.fits", overwrite=True
+)
+
+# Tile-compressed image (RICE_1)
+ramp = np.arange(256, dtype="i4").reshape(16, 16)
+zf.HDUList([zf.PrimaryHDU(), zf.CompImageHDU(ramp, compression="RICE_1")]).writeto(
+    "comp.fits", overwrite=True
+)
+
+# Structural validation (fitsverify-style)
+for f in zf.verify("image.fits"):
+    print(f)
+```
+
+### Headers (dict-like)
+
+```python
+with zf.open("image.fits", mode="update") as hdul:
+    h = hdul[0].header
+    h["OBSERVER"] = ("Hubble", "the observer")  # value + comment
+    print(h["OBSERVER"], "/", h.comment_of("OBSERVER"))
+    print("BITPIX" in h, list(h.keys()))
+```
+
+### WCS (celestial)
+
+```python
+with zf.open("wcs.fits") as hdul:
+    lon, lat = hdul[0].pix2world(40.0, 30.0)   # 1-based pixel (FITS CRPIX convention)
+    px, py = hdul[0].world2pix(lon, lat)
+```
+
+### Low-level (ctypes)
+
+```python
+import ctypes as c
+import zigfitsio.lowlevel as ll
+
+h = c.c_void_p()
+ll.check(ll.lib.zf_create_memory(None, c.byref(h)))
+ll.check(ll.lib.zf_create_img(h, -32, 2, (c.c_long * 2)(4, 3)))
+ll.lib.zf_close(h)
+```
+
+## Conventions
+
+- Image and table data is exchanged as **native-endian** NumPy arrays; non-native (byte-swapped)
+  input is coerced automatically before writing. Image shape is the reversed FITS axis order
+  (`(NAXIS2, NAXIS1)`), C-contiguous — identical memory layout to `astropy.io.fits`.
+- `BSCALE`/`BZERO` and `TSCAL`/`TZERO` scaling and the unsigned-integer convention are applied
+  automatically on read (images and table columns) and honored on write; the output dtype is
+  widened to float when real scaling is present, or to `u2/u4/u8` for the unsigned convention.
+- Errors are raised as typed `FitsError` subclasses (`KeywordNotFound` is also a `KeyError`).
+
+## Development
+
+```sh
+zig build capi                                   # build the shared library into zig-out/lib
+pip install -e .[test]                           # editable install (builds the lib via the hook)
+pytest bindings/python/tests -q                  # run the suite (incl. astropy cross-checks)
+```
+
+When running tests against an uninstalled checkout, point the loader at the dev build:
+
+```sh
+ZIGFITSIO_LIBRARY=$PWD/zig-out/lib/libzigfitsio_capi.dylib \
+PYTHONPATH=bindings/python/src pytest bindings/python/tests -q
+```
+
+## License
+
+MIT — see [`LICENSE`](../../LICENSE).

zigfitsio-0.1.1/README.md

@@ -0,0 +1,140 @@
+# zigfitsio
+
+A pure-[Zig](https://ziglang.org) implementation of a [FITS](https://fits.gsfc.nasa.gov)
+(Flexible Image Transport System) 4.0 input/output library, with feature parity goals
+against [CFITSIO](https://heasarc.gsfc.nasa.gov/docs/software/fitsio/fitsio.html) — written
+with **no C imports and no C sources** (`GC-1`).
+
+- **Conformance target:** *Definition of the FITS Standard*, Version 4.0 (2018-08-13).
+- **Toolchain:** Zig **0.16.0**, standard library only (`GC-2`, `GC-3`).
+- **License:** MIT (see [`LICENSE`](./LICENSE)).
+
+See [`requirements.md`](./requirements.md), [`design.md`](./design.md), and
+[`tasks.md`](./tasks.md) for the full specification, architecture, and implementation
+backlog.
+
+## Build
+
+```sh
+zig build              # build the static library
+zig build test         # run the test suite
+zig build capi         # build the C-ABI shared library (for the Python/C bindings)
+zig build capi-test    # test the C-ABI shim
+zig build bench        # throughput benchmarks
+zig build fitsverify   # run the structural-validation CLI demo
+zig build fuzz         # fuzz the header/table parsers
+zig build wasm-check   # compile the core for wasm32-freestanding
+```
+
+## Use as a dependency
+
+```sh
+zig fetch --save git+https://github.com/anhydrous99/zigfitsio
+```
+
+```zig
+// build.zig
+const fits = b.dependency("zigfitsio", .{ .target = target, .optimize = optimize });
+exe.root_module.addImport("zigfitsio", fits.module("zigfitsio"));
+```
+
+## Language bindings (C ABI + Python)
+
+A stable **C ABI** and a **Python** package live under [`bindings/`](./bindings). They are
+additive — the pure-Zig library in `src/` is unchanged — and are layered:
+
+- **C-ABI shim** ([`bindings/capi/`](./bindings/capi), `zig build capi`): a dynamic library
+  `zigfitsio_capi` exporting `zf_*` symbols. The comptime-generic Zig API is monomorphized behind
+  runtime datatype codes, and Zig errors are surfaced as CFITSIO-compatible status ints via
+  `errors.cfitsioStatus`. The hand-written contract is [`bindings/c/zigfitsio.h`](./bindings/c/zigfitsio.h).
+  This is **not** a CFITSIO `fits_*`/`ff*` drop-in — it is a purpose-built ABI for bindings.
+- **Low-level Python** (`zigfitsio.lowlevel`): a 1:1 `ctypes` binding over the C ABI, with a typed
+  `FitsError` hierarchy. Pure Python — no C compiler needed at install.
+- **High-level Python** (`zigfitsio`): a NumPy-first API modeled on `astropy.io.fits` — `open`,
+  `HDUList`, the HDU classes, `Column`, a dict-like `Header`, `getdata`/`getheader`/`writeto`/
+  `verify`, and celestial WCS transforms. Interoperability is verified **both directions** against
+  Astropy and the committed CFITSIO golden corpus.
+
+```python
+import numpy as np, zigfitsio as zf
+
+zf.writeto("img.fits", np.arange(12, dtype="f4").reshape(3, 4), overwrite=True)
+with zf.open("img.fits") as hdul:
+    print(hdul[0].data, hdul[0].header["NAXIS1"])
+```
+
+See [`bindings/python/README.md`](./bindings/python/README.md) for install, the full API, and the
+packaging/wheel workflow.
+
+## Status
+
+Feature-complete and tested (459 tests green), with cross-tool interoperability verified against
+**CFITSIO 4.6.4 + Astropy** (see below). Implemented end to end:
+
+- **Foundation:** I/O layer (in-memory, file, stream/gzip, and HTTP backends), typed
+  error sets, big-endian access, numeric-conversion policy, resource limits.
+- **Headers:** value parsing (null/empty/undefined distinction), 80-byte cards, full
+  read + edit operations, header-space pre-allocation, `CONTINUE` long strings,
+  `HIERARCH` long names, and complex-valued cards.
+- **HDUs & data:** HDU model with navigation/mutation; `ImageView` over all six `BITPIX`
+  with scaling, nulls, and strided sections; ASCII and binary tables (all `TFORM` codes,
+  `TDIM`, scaling, nulls); variable-length arrays with a compacting heap.
+- **WCS:** keyword set parse/serialize plus celestial (`TAN`/`SIN`/`ARC`/`STG`/`ZEA`/`CAR`),
+  spectral, and time-coordinate transforms.
+- **Compression:** GZIP_1/2, RICE_1, PLIO_1, and HCOMPRESS_1 tiled read **and** write,
+  with subtractive dithering; tile-compressed-table (`ZTABLE`) reading.
+- **Integrity & validation:** `DATASUM`/`CHECKSUM` compute/update/verify; a
+  `fitsverify`-style structural pass.
+- **Convenience:** CFITSIO-style extended filenames, ASCII header templates, hierarchical
+  grouping tables, and a transparent `.fits.gz` open path.
+
+**Cross-tool interoperability is verified**, not just self-consistent: a committed
+**CFITSIO 4.6.4 + `fpack`** golden corpus (`test/golden/`, generators under `interop/`) is decoded
+hermetically by `test/golden.zig` on every CI cell (including big-endian s390x), an in-house
+full-feature round-trip (`test/e2e.zig`) mirrors CFITSIO's `testprog.c`, and a dedicated `interop`
+CI job opens every zigfitsio-written file with CFITSIO `funpack`, Astropy, and `fitsverify`.
+Authoring this corpus closed two real interop bugs that self-round-trips could not catch (the PLIO
+line-list header + `COMPRESSED_DATA` `1PB`→`1PI`, and an unregistered `checksum_on_close` hook).
+The one remaining codec limit is `HCOMPRESS_1` lossy smoothing (`hsmooth`) — lossless only. See
+`CAVEATS.md` and `tasks.md`.
+
+## Examples
+
+### Read an image into `[]f32`
+
+```zig
+const fits = @import("zigfitsio");
+
+var f = try fits.openFile(allocator, "img.fits", .read_only, .{});
+defer f.deinit();
+
+var img = try fits.ImageView.of(&f, f.current());
+const buf = try allocator.alloc(f32, @intCast(img.elementCount()));
+defer allocator.free(buf);
+
+// BSCALE/BZERO applied, NaN → 0 substituted, stored → f32 converted, in bounded chunks.
+try img.readAll(f32, buf, .{ .null_sentinel = 0.0 });
+```
+
+### Create an image (the programmatic builder is the primary path)
+
+```zig
+var f = try fits.createFile(allocator, "out.fits", .{});
+defer f.deinit();
+
+var img = try fits.ImageView.append(&f, .{ .bitpix = -32, .axes = &.{ 256, 256 } });
+try img.writeAll(f32, pixels, .{});
+try f.flush();
+```
+
+### Navigate HDUs and read a strided section
+
+```zig
+const n = try f.hduCount();
+var img = try fits.ImageView.of(&f, try f.select(2)); // 1-based HDU number
+var tile: [256 * 256]f32 = undefined;
+try img.readSection(f32, &.{ 0, 0 }, &.{ 511, 511 }, &.{ 2, 2 }, &tile, .{});
+```
+
+In-memory and stdin/stdout back-ends are first-class: build a `fits.MemoryDevice` and pass
+`mem.device()` to `fits.open`/`fits.create` for a freestanding-capable, file-less path.