spectrum-reader-certic 0.1.0__py3-none-win_amd64.whl

spectrum_reader/__init__.py

@@ -0,0 +1,113 @@
+"""Read spectra from contiguous hyperspectral HDF5 files."""
+
+from __future__ import annotations
+
+import operator
+import os
+import threading
+from typing import TypeVar
+
+from ._native import ffi, lib
+
+__all__ = ["FormatError", "SpectrumError", "SpectrumFile"]
+
+_SpectrumFileT = TypeVar("_SpectrumFileT", bound="SpectrumFile")
+
+if lib.sr_abi_version() != 1:
+    raise ImportError("spectrum-reader native library has an incompatible ABI")
+
+
+class SpectrumError(RuntimeError):
+    """An internal error in the native spectrum reader."""
+
+
+class FormatError(ValueError):
+    """An unsupported or corrupt hyperspectral HDF5 file."""
+
+
+def _check(status: int) -> None:
+    if status == 0:
+        return
+    message = ffi.string(lib.sr_last_error_message()).decode("utf-8", errors="replace")
+    error = {
+        2: ValueError,
+        3: OSError,
+        4: FormatError,
+        5: IndexError,
+    }.get(status, SpectrumError)
+    raise error(message)
+
+
+class SpectrumFile:
+    """An open spectrum file. Use as a context manager or call close().
+
+    Operations on the same instance are serialized, including close(). The
+    native handle is also released automatically when the instance is collected.
+    """
+
+    def __init__(self, path: str | bytes | os.PathLike) -> None:
+        path = os.fspath(path)
+        encoded = os.fsdecode(path).encode("utf-8") if os.name == "nt" else os.fsencode(path)
+        if b"\0" in encoded:
+            raise ValueError("path must not contain a NUL byte")
+        self._lock = threading.Lock()
+        out = ffi.new("SrFile **")
+        _check(lib.sr_open(encoded, out))
+        self._handle = ffi.gc(out[0], lib.sr_close)
+        shape = ffi.new("uint64_t[3]")
+        _check(lib.sr_shape(self._handle, shape))
+        self._shape = (int(shape[0]), int(shape[1]), int(shape[2]))
+
+    def _require_open(self) -> None:
+        if self._handle == ffi.NULL:
+            raise ValueError("spectrum file is closed")
+
+    @property
+    def closed(self) -> bool:
+        """Whether the file has been closed."""
+        with self._lock:
+            return self._handle == ffi.NULL
+
+    @property
+    def shape(self) -> tuple[int, int, int]:
+        """The dataset dimensions: (rows, columns, bands)."""
+        with self._lock:
+            self._require_open()
+            return self._shape
+
+    @property
+    def wavelengths(self) -> list[float]:
+        """The wavelength of each spectral band, as Python floats."""
+        with self._lock:
+            self._require_open()
+            bands = self._shape[2]
+            out = ffi.new("double[]", bands)
+            _check(lib.sr_wavelengths(self._handle, out, bands))
+            return list(out)
+
+    def read_pixel(self, row: int, col: int) -> list[float]:
+        """Return all bands at a zero-based (row, column) position."""
+        row, col = operator.index(row), operator.index(col)
+        with self._lock:
+            self._require_open()
+            rows, cols, bands = self._shape
+            if not (0 <= row < rows and 0 <= col < cols):
+                raise IndexError(f"pixel ({row}, {col}) is outside ({rows}, {cols})")
+            out = ffi.new("float[]", bands)
+            _check(lib.sr_read_pixel(self._handle, row, col, out, bands))
+            return list(out)
+
+    def close(self) -> None:
+        """Release the native file handle. Repeated calls are harmless."""
+        with self._lock:
+            if self._handle != ffi.NULL:
+                ffi.release(self._handle)
+                self._handle = ffi.NULL
+
+    def __enter__(self: _SpectrumFileT) -> _SpectrumFileT:
+        with self._lock:
+            self._require_open()
+            return self
+
+    def __exit__(self, exc_type, exc_value, traceback) -> None:
+        self.close()

spectrum_reader/_native/__init__.py

@@ -0,0 +1,7 @@
+__all__ = ["lib", "ffi"]
+
+import os
+from .ffi import ffi
+
+lib = ffi.dlopen(os.path.join(os.path.dirname(__file__), '_native.dll'))
+del os

spectrum_reader/_native/ffi.py

@@ -0,0 +1,10 @@
+# auto-generated file
+import _cffi_backend
+
+ffi = _cffi_backend.FFI('ffi',
+    _version = 0x2601,
+    _types = b'\x00\x00\x13\x0D\x00\x00\x00\x0F\x00\x00\x1F\x0D\x00\x00\x1B\x03\x00\x00\x1D\x03\x00\x00\x1C\x01\x00\x00\x00\x0F\x00\x00\x1F\x0D\x00\x00\x03\x11\x00\x00\x0D\x03\x00\x00\x00\x0F\x00\x00\x1F\x0D\x00\x00\x03\x11\x00\x00\x18\x01\x00\x00\x18\x01\x00\x00\x1E\x03\x00\x00\x1C\x01\x00\x00\x00\x0F\x00\x00\x1F\x0D\x00\x00\x1C\x03\x00\x00\x19\x03\x00\x00\x00\x0F\x00\x00\x20\x0D\x00\x00\x00\x0F\x00\x00\x21\x0D\x00\x00\x1B\x03\x00\x00\x00\x0F\x00\x00\x00\x09\x00\x00\x02\x01\x00\x00\x0E\x01\x00\x00\x0D\x01\x00\x00\x15\x01\x00\x00\x16\x01\x00\x00\x00\x01',
+    _globals = (b'\xFF\xFF\xFF\x1FSR_ERR_FORMAT',4,b'\xFF\xFF\xFF\x1FSR_ERR_INTERNAL',1,b'\xFF\xFF\xFF\x1FSR_ERR_INVALID_ARGUMENT',2,b'\xFF\xFF\xFF\x1FSR_ERR_IO',3,b'\xFF\xFF\xFF\x1FSR_ERR_OUT_OF_RANGE',5,b'\xFF\xFF\xFF\x1FSR_OK',0,b'\x00\x00\x16\x23sr_abi_version',0,b'\x00\x00\x18\x23sr_close',0,b'\x00\x00\x00\x23sr_last_error_message',0,b'\x00\x00\x12\x23sr_open',0,b'\x00\x00\x0B\x23sr_read_pixel',0,b'\x00\x00\x07\x23sr_shape',0,b'\x00\x00\x02\x23sr_wavelengths',0),
+    _struct_unions = ((b'\x00\x00\x00\x1B\x00\x00\x00\x10SrFile',),),
+    _typenames = (b'\x00\x00\x00\x1BSrFile',),
+)

spectrum_reader_certic-0.1.0.dist-info/METADATA

@@ -0,0 +1,196 @@
+Metadata-Version: 2.4
+Name: spectrum-reader-CERTIC
+Version: 0.1.0
+Requires-Dist: cffi>=1.17
+License-File: LICENSE.txt
+Summary: Read single-pixel spectra from hyperspectral HDF5 files without libhdf5
+License-Expression: CECILL-B
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
+
+# spectrum-reader
+
+Small Rust library that reads single-pixel spectra from hyperspectral HDF5 files without libhdf5. Designed for use in the SIDS.
+
+## Targets
+
+- Linux x86_64 (Debian trixie): the production build. It is built on Debian trixie and its binary is the one shipped to the SIDS.
+- macOS arm64: native library for local development and Python wheels (macOS 11+).
+- Windows x86_64: native library and Python wheels, built with the MSVC target.
+
+The Python Linux wheels target x86_64 with glibc 2.34 or newer, including Debian trixie.
+
+## C API
+
+The declarations below are those of `include/spectrum_reader.h`.
+
+```c
+uint32_t    sr_abi_version(void);
+const char *sr_last_error_message(void);
+int32_t     sr_open(const char *path, SrFile **out);
+void        sr_close(SrFile *file);
+int32_t     sr_shape(const SrFile *file, uint64_t *out);
+int32_t     sr_wavelengths(const SrFile *file, double *out, size_t len);
+int32_t     sr_read_pixel(const SrFile *file, uint64_t row, uint64_t col, float *out, size_t len);
+```
+
+- Functions returning `int32_t` return `0` on success, otherwise one of: `1` internal error (including a caught panic), `2` invalid argument (null pointer, wrong buffer length), `3` I/O error, `4` unsupported or corrupt file, `5` pixel out of range.
+- After a failed call, `sr_last_error_message()` returns a description. The message is kept per thread, is replaced by the next call on the same thread, and the pointer is only valid until then: copy it right away.
+- `path` is a NUL-terminated byte string: filesystem bytes on Unix, UTF-8 on Windows. `sr_open` sets `*out` to NULL on failure.
+- `sr_shape` writes three values: `rows`, `cols`, `bands`. `row` and `col` are the first two indices of the `spectra` dataset.
+- The caller owns every output buffer. `len` must equal the number of bands exactly, otherwise the call fails and the buffer is left untouched.
+- A handle can be shared between threads for `sr_shape`, `sr_wavelengths` and `sr_read_pixel`. `sr_close` must not run while another call uses the handle, and a closed handle must not be used again. `sr_close(NULL)` does nothing.
+- Only little-endian float32 `spectra` (3 dimensions) and float64 `Wavelength` (1 dimension) with contiguous storage are supported. Anything else is rejected at `sr_open`.
+
+## Development
+
+[rustup](https://rustup.rs) is required. The toolchain is pinned in `rust-toolchain.toml` and rustup installs it automatically the first time cargo runs.
+
+```
+make test
+make build
+make smoke
+make lint
+```
+
+`make smoke` compiles `tests/smoke.c` against the built library and `include/spectrum_reader.h`, then runs it.
+
+The C header is generated and committed. After changing the exported functions, run `make header`; `make check-header` fails if the committed header is out of date. This needs cbindgen 0.29.4:
+
+```
+cargo install cbindgen --version 0.29.4 --locked
+```
+
+The release library is `target/release/libspectrum_reader.so` (`.dylib` on macOS).
+
+### Building on macOS (arm64)
+
+Install the Xcode command-line tools (`xcode-select --install`) and [rustup](https://rustup.rs), then from the repository root:
+
+```
+make build
+```
+
+The library is `target/release/libspectrum_reader.dylib`. Point the SIDS wrapper at it for local development, together with `include/spectrum_reader.h`.
+
+### Building the Linux library from macOS
+
+An alternative to building on Debian trixie. [zig](https://ziglang.org) is used as the linker, and the glibc version the library requires is pinned in the target name (`.2.34`; trixie ships 2.41, so anything up to that works).
+
+```
+rustup target add x86_64-unknown-linux-gnu
+brew install zig
+cargo install cargo-zigbuild --version 0.24.0 --locked
+make build-linux
+```
+
+The library is `target/x86_64-unknown-linux-gnu/release/libspectrum_reader.so`. It cannot run on the Mac, so `make smoke` does not test it: `make check` tests the macOS build of the same code.
+
+## Python bindings and wheels
+
+The `spectrum-reader` Python package bundles the native library and uses CFFI to
+call the C API. It supports Python 3.10+ and needs neither Rust nor libhdf5 on
+the machine where a wheel is installed. Its only Python runtime dependency is
+`cffi`, which pip installs automatically.
+
+```python
+from spectrum_reader import SpectrumFile
+
+with SpectrumFile("image.h5") as spectrum:
+    rows, cols, bands = spectrum.shape
+    wavelengths = spectrum.wavelengths
+    values = spectrum.read_pixel(row=0, col=0)
+```
+
+Wavelengths and pixel values are returned as lists of Python floats. Coordinates
+are zero-based. Paths can be strings, bytes, or `pathlib.Path` objects. Use the
+context manager or call `close()` explicitly; repeated closes are harmless.
+Calls on the same object, including `close()`, are synchronized.
+
+Missing or unreadable files raise `OSError`; unsupported or corrupt files raise
+`spectrum_reader.FormatError` (a `ValueError`); out-of-range pixels raise
+`IndexError`. Using a closed file raises `ValueError`. Internal native errors
+raise `spectrum_reader.SpectrumError` (a `RuntimeError`).
+
+### Build all three wheels from macOS
+
+Install [uv](https://docs.astral.sh/uv/) and the Rust toolchain, then prepare the
+cross-compilation tools:
+
+```sh
+rustup target add aarch64-apple-darwin x86_64-unknown-linux-gnu x86_64-pc-windows-msvc
+brew install zig llvm lld
+export PATH="$(brew --prefix llvm)/bin:$(brew --prefix lld)/bin:$PATH"
+make build-wheels
+```
+
+The build targets run Maturin 1.15.0 and CFFI through uv. Linux builds use Zig;
+Windows builds use Maturin's integrated xwin support, which downloads the
+Microsoft CRT and Windows SDK on the first build (under the
+[xwin license terms](https://github.com/rust-cross/cargo-xwin#cargo-xwin)).
+Building the Darwin wheel requires a macOS host and the Xcode command-line tools.
+
+The wheels are written to `dist/` (override with `WHEEL_OUT=path`):
+
+| Make target | Wheel platform tag |
+| --- | --- |
+| `build-wheel-darwin-arm64` | `macosx_11_0_arm64` |
+| `build-wheel-linux-amd64` | `manylinux_2_34_x86_64` |
+| `build-wheel-windows-amd64` | `win_amd64` |
+
+Each wheel has the `py3-none` Python/ABI tags, so a separate build for each
+Python version is unnecessary. Run an individual target to build just that
+platform, or `make build-wheel` for the current host. On Windows, run Make from
+a shell with the MSVC build tools available; native builds do not use xwin.
+
+Install the wheel matching your platform, for example on an Apple Silicon Mac:
+
+```sh
+python -m pip install dist/spectrum_reader-0.1.0-py3-none-macosx_11_0_arm64.whl
+```
+
+### Test the Python package
+
+```sh
+make test-python
+```
+
+This builds and installs the package into an isolated uv environment and runs
+the Python integration tests against the HDF5 fixtures. To test a particular
+built wheel on its target platform:
+
+```sh
+uv run --no-project --with /path/to/spectrum_reader.whl python -m unittest discover -s tests/python -v
+```
+
+Use the wheel's actual filename. Cross-compiled wheels must be tested on their
+respective operating systems; the local tests exercise only the host platform.
+
+## Updating the library in the SIDS
+
+Build from a clean working tree at the commit being shipped, either on Debian trixie or from macOS (see above).
+
+1. Run all the checks; they must pass:
+
+```
+make check
+```
+
+   It runs clippy (warnings are errors), the tests, the header staleness check and the C smoke test.
+
+2. If built on Debian trixie, check the glibc requirement of the library; the highest version printed must not exceed trixie's (2.41). A library from `make build-linux` is pinned to 2.34 already:
+
+```
+objdump -T target/release/libspectrum_reader.so | grep -o 'GLIBC_[0-9.]*' | sort -uV | tail -1
+```
+
+3. Copy these two files into the SIDS repository:
+   - `target/release/libspectrum_reader.so` (`target/x86_64-unknown-linux-gnu/release/libspectrum_reader.so` if built with `make build-linux`)
+   - `include/spectrum_reader.h`
+
+4. If the exported functions or their behavior changed incompatibly, bump `ABI_VERSION` in `src/lib.rs` first, run `make header`, and update the version the SIDS wrapper expects from `sr_abi_version()`.
+
+## License
+
+CeCILL-B. See `LICENSE.txt`.
+

spectrum_reader_certic-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+spectrum_reader/__init__.py,sha256=ATZgMZ0uh8K22WkOdf85KgA97yVAGjBNr5HsPaO-tNc,3744
+spectrum_reader/_native/__init__.py,sha256=6rC8Q16GkZtTIOrjfJTUvSGifaw5q6hgy4R3fFnk9wM,138
+spectrum_reader/_native/_native.dll,sha256=ZGoJbE6IfMVqYCszw5fsK25Uioosv25wikCB382AudM,145920
+spectrum_reader/_native/ffi.py,sha256=vf11rFTn6XEIr4BcKjr6aOEKjn33aLg_drAEfPc4qbc,1252
+spectrum_reader/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+spectrum_reader_certic-0.1.0.dist-info/METADATA,sha256=mNsr8KdOLESvxKbfspj_52BraGmBQCyTts02TGtA-ZM,8448
+spectrum_reader_certic-0.1.0.dist-info/WHEEL,sha256=8Aej0W0a6Cz6apA3IzJrTnxLRVLAt-w0Oh8SA3Con_c,94
+spectrum_reader_certic-0.1.0.dist-info/licenses/LICENSE.txt,sha256=J-xqEfyVAesI6lUagCL93NuigDfeFE1qX-4dA-xZhl0,3421
+spectrum_reader_certic-0.1.0.dist-info/sboms/spectrum_reader.cyclonedx.json,sha256=7-DW2iko48Oeyk7O_cBzd6ogwAi6Blu7ig3E2qQtJZk,1321
+spectrum_reader_certic-0.1.0.dist-info/RECORD,,

spectrum_reader_certic-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: maturin (1.15.0)
+Root-Is-Purelib: false
+Tag: py3-none-win_amd64

spectrum_reader_certic-0.1.0.dist-info/licenses/LICENSE.txt

@@ -0,0 +1,73 @@
+Copyright 2026 Université de Caen Normandie
+Esplanade de la paix
+CS 14032
+14032 Caen CEDEX 5
+
+Auteur : CERTIC Université de Caen Normandie
+
+Contributeurs :
+- thomas.hennebert@unicaen.fr
+
+Ce logiciel est régi par la licence CeCILL-B soumise au droit français et
+respectant les principes de diffusion des logiciels libres. Vous pouvez
+utiliser, modifier et/ou redistribuer ce programme sous les conditions
+de la licence CeCILL-B telle que diffusée par le CEA, le CNRS et l'INRIA
+sur le site "http://www.cecill.info".
+
+En contrepartie de l'accessibilité au code source et des droits de copie,
+de modification et de redistribution accordés par cette licence, il n'est
+offert aux utilisateurs qu'une garantie limitée. Pour les mêmes raisons,
+seule une responsabilité restreinte pèse sur l'auteur du programme, le
+titulaire des droits patrimoniaux et les concédants successifs.
+
+A cet égard l'attention de l'utilisateur est attirée sur les risques
+associés au chargement, à l'utilisation, à la modification et/ou au
+développement et à la reproduction du logiciel par l'utilisateur étant
+donné sa spécificité de logiciel libre, qui peut le rendre complexe à
+manipuler et qui le réserve donc à des développeurs et des professionnels
+avertis possédant des connaissances informatiques approfondies. Les
+utilisateurs sont donc invités à charger et tester l'adéquation du
+logiciel à leurs besoins dans des conditions permettant d'assurer la
+sécurité de leurs systèmes et ou de leurs données et, plus généralement,
+à l'utiliser et l'exploiter dans les mêmes conditions de sécurité.
+
+Le fait que vous puissiez accéder à cet en-tête signifie que vous avez
+pris connaissance de la licence CeCILL-B, et que vous en avez accepté les
+termes.
+
+=========================================================================
+Copyright 2026 Université de Caen Normandie
+Esplanade de la paix
+CS 14032
+14032 Caen CEDEX 5
+
+Author: CERTIC Université de Caen Normandie
+
+Contributors:
+- thomas.hennebert@unicaen.fr
+
+This software is governed by the CeCILL-B license under French law and
+abiding by the rules of distribution of free software. You can use,
+modify and/ or redistribute the software under the terms of the CeCILL-B
+license as circulated by CEA, CNRS and INRIA at the following URL
+"http://www.cecill.info".
+
+As a counterpart to the access to the source code and rights to copy,
+modify and redistribute granted by the license, users are provided only
+with a limited warranty and the software's author, the holder of the
+economic rights, and the successive licensors have only limited
+liability.
+
+In this respect, the user's attention is drawn to the risks associated
+with loading, using, modifying and/or developing or reproducing the
+software by the user in light of its specific status of free software,
+that may mean that it is complicated to manipulate, and that also
+therefore means that it is reserved for developers and experienced
+professionals having in-depth computer knowledge. Users are therefore
+encouraged to load and test the software's suitability as regards their
+requirements in conditions enabling the security of their systems and/or
+data to be ensured and, more generally, to use and operate it in the
+same conditions as regards security.
+
+The fact that you are presently reading this means that you have had
+knowledge of the CeCILL-B license and that you accept its terms.

spectrum_reader_certic-0.1.0.dist-info/sboms/spectrum_reader.cyclonedx.json

@@ -0,0 +1,50 @@
+{
+  "bomFormat": "CycloneDX",
+  "specVersion": "1.5",
+  "version": 1,
+  "serialNumber": "urn:uuid:43cca485-4ff4-40b6-9be0-8d216455323c",
+  "metadata": {
+    "timestamp": "2026-11-12T13:05:11.115192000Z",
+    "tools": [
+      {
+        "vendor": "CycloneDX",
+        "name": "cargo-cyclonedx",
+        "version": "0.5.9"
+      }
+    ],
+    "component": {
+      "type": "library",
+      "bom-ref": "path+file:///Users/mickael/code/spectrum-reader#spectrum_reader@0.1.0",
+      "name": "spectrum_reader",
+      "version": "0.1.0",
+      "scope": "required",
+      "licenses": [
+        {
+          "expression": "CECILL-B"
+        }
+      ],
+      "purl": "pkg:cargo/spectrum_reader@0.1.0?download_url=file://.",
+      "components": [
+        {
+          "type": "library",
+          "bom-ref": "path+file:///Users/mickael/code/spectrum-reader#spectrum_reader@0.1.0 bin-target-0",
+          "name": "spectrum_reader",
+          "version": "0.1.0",
+          "purl": "pkg:cargo/spectrum_reader@0.1.0?download_url=file://.#src/lib.rs"
+        }
+      ]
+    },
+    "properties": [
+      {
+        "name": "cdx:rustc:sbom:target:all_targets",
+        "value": "true"
+      }
+    ]
+  },
+  "components": [],
+  "dependencies": [
+    {
+      "ref": "path+file:///Users/mickael/code/spectrum-reader#spectrum_reader@0.1.0"
+    }
+  ]
+}