Skip to content

v3.6.0.0

Choose a tag to compare

@github-actions github-actions released this 11 Sep 16:54
· 3 commits to main since this release
0a994f5

Targets cuvis SDK 3.6.0.
First wrapper release for that SDK.

Added

  • cuvis.ReferenceType.WhiteSpectrum - new enum member.
  • cuvis.ReferenceType.TargetSpectrum - new enum member.
  • cuvis.ProcessingContext.set_reference - new parameter effective_bit_depth: int | None = None.
  • cuvis.ProcessingContext.set_reference - new parameter integration_time: float = 0.0.
  • cuvis.ProcessingContext.get_reference_spectrum - new method.
    Returns the white or target reference spectrum as an ImageData, or None when the slot is empty.
    Target values are reflectance fractions (1.0 = 100 percent); the white spectrum additionally carries effective_bit_depth and integration_time attributes.
  • tests/ - behavior tests for the reference spectra: a 0.5 reflectivity target halves the reflectance cube, white spectrum and white measurement clear each other, four times the white counts quarter the cube, and both spectra survive a legacy .cu3 save behind .cu3sp sidecar links and the stored cube is bit-identical after reload.
  • CI - .github/workflows/ci.yml runs the test suite and a lint job enforcing ruff check and ruff format --check on every pull request and on every push to develop and main.
  • CI - .github/workflows/release.yml is driven by v*.*.*.* tags: it validates the tag against pyproject.toml, this file and the cuvis_pyil image, builds, publishes to TestPyPI, and publishes to PyPI plus a GitHub Release after manual approval.
    Pre-release tags (a, b, rc suffix) publish to PyPI as pre-releases and create no GitHub Release.
  • CI - the changelog structure and the tag/version/changelog agreement are validated by the shared actions in cuvis.docker.
  • CI - the release refuses to publish when the cuvis-il requirement disagrees with the version: it must accept the SDK the version targets, and it may open to pre-releases only when the release is itself a pre-release.
  • CONTRIBUTING.md - documents the branch model, the version scheme, the changelog conventions and the release checklist.
  • cuvis.BindingInfo - new frozen dataclass with the fields built_against: str, library_version: str, library_path: str and missing_symbols: tuple[str, ...], the read-only property is_complete: bool, and a __str__ rendering a report fit for a bug report.
  • cuvis.CudaImageData - new class, device-resident image data backed by a shareable CUDA buffer, exposed zero-copy through DLPack or __cuda_array_interface__ with no host copy.
  • cuvis.CudaImageData.export_payload - new method, returns bytes.
  • cuvis.CudaImageData.make_ipc - new method, returns bytes.
  • cuvis.CudaImageData.to_torch - new method, returns torch.Tensor.
  • cuvis.Measurement.get_cube - new method, returns ImageData | CudaImageData depending on whether cuvis.cuda.enable was called.
  • cuvis.Measurement.get_cube_cuda - new method, returns CudaImageData.
  • cuvis.Measurement.get_cube_cuda_ipc - new method, returns CudaImageData.
  • cuvis.SdkSettings - new class, a MutableMapping of setting id to value that writes the SDK's cuvis.settings file, so the SDK configuration can be built in Python instead of maintained by hand.
    Values are stored as strings: bool becomes true/false, an Enum becomes its value, anything else goes through str(), and None drops the entry.
  • cuvis.SdkSettings.__enter__, cuvis.SdkSettings.__exit__ - new methods; entering the context serializes the settings into a temporary directory and returns its path as str, leaving the context removes the directory.
  • cuvis.SdkSettings.save - new method, writes the settings to a file, or into a directory as cuvis.settings.
  • cuvis.SdkSettings.xml_str - new read-only property, returns the serialized settings document as str.
  • cuvis.UnavailableSDKFunction - new exception deriving from both cuvis.cuvis_aux.SDKException and RuntimeError, with the field names: tuple[str, ...].
  • cuvis.binding - new module reporting the compiled binding, the cuvis library loaded beside it, and the functions that library does not provide.
    Nothing in it needs the SDK to be initialised, so it can be called before cuvis.init.
  • cuvis.binding.available - new function, returns bool.
  • cuvis.binding.info - new function, returns BindingInfo.
  • cuvis.binding.missing_symbols - new function, returns frozenset[str].
  • cuvis.binding.require - new function, raises UnavailableSDKFunction naming whichever of the given functions the installed cuvis library does not provide.
  • cuvis.binding.unavailable - new function, returns tuple[str, ...].
    A function the binding never exposed is unusable as well, so availability cannot be answered from the reported-missing list alone.
  • cuvis.cuda - new module gating the optional CUDA feature surface; CUDA stays off until cuvis.cuda.enable is called.
  • cuvis.cuda.BACKEND_NONE, cuvis.cuda.BACKEND_POOL, cuvis.cuda.BACKEND_LEGACY, cuvis.cuda.BACKEND_VMM - new constants, the IPC backend codes from cuvis.h.
  • cuvis.cuda.CudaCapabilities - new NamedTuple with the bool fields same_process, ipc_pool, ipc_legacy, ipc_vmm, torch and cuda_python, and the read-only property any_ipc: bool.
  • cuvis.cuda.capabilities - new function, returns CudaCapabilities.
  • cuvis.cuda.disable - new function.
  • cuvis.cuda.enable - new function.
  • cuvis.cuda.is_enabled - new function, returns bool.
  • cuvis.cuda.require_device - new function, raises UnavailableSDKFunction unless the installed library provides the same-process device path.
  • cuvis.cuda.require_ipc - new function, raises UnavailableSDKFunction unless the installed library provides the cross-process export path.
  • cuvis_ipc - new top-level module, the consumer side of cross-process CUDA IPC.
    It sits outside the cuvis package because importing cuvis requires the SDK and a consumer process does not have one; its only import is struct.
  • cuvis_ipc.ImportedCube - new class, a mapped IPC buffer in the consumer process, usable as a context manager.
  • cuvis_ipc.open - new function, returns ImportedCube.
  • cuvis_ipc.open_descriptor - new function, returns ImportedCube.
  • cuvis_ipc.pack_payload - new function, returns bytes.
  • pyproject.toml - py-modules declaring the top-level cuvis_ipc.
  • tests/ - test_binding.py, test_cuda.py and test_cuvis_ipc.py.

Changed

  • Whole tree reformatted with ruff format; no behaviour change.
  • pyproject.toml - the cuvis-il requirement moved from >=3.5.0,<3.6.0 to >=3.6.0,<3.7.0, so the wrapper targets cuvis SDK 3.6.
  • CONTRIBUTING.md, README.md - the branch model is now trunk based: develop is gone, every change is cut from main and merged back into it by pull request, and a commit on main is no longer necessarily a release.
  • cuvis.ProcessingContext.set_reference - type changed from (mesu: Measurement, refType: ReferenceType) to (data: Measurement | ImageData | tuple, refType: ReferenceType).
    The spectrum reference types take spectrum data instead of a Measurement; the first parameter is renamed from mesu to data.
  • README.md - documents the version scheme, and lists Python 3.14 among the supported interpreters as pyproject.toml already did.
  • prebuild.py - writes cuvis/git-hash.txt instead of git-hash.txt at the repository root, so the file lands inside the package that declares it as package data.
  • cuvis.General.init - parameter settings_path type changed from str to str | Path | SdkSettings.
    An SdkSettings is written to a temporary directory that exists only for the duration of the call, since the SDK reads the settings once during initialisation.
  • cuvis.FileWriteSettings.GeneralExportSettings.__repr__, cuvis.FileWriteSettings.ViewerSettings.__repr__ - the docstring that sat below the nested helper, where it was a dead expression rather than a docstring, moved to the top of the method.
  • cuvis.Measurement.capture_time, cuvis.Measurement.factory_calibration, cuvis.GPSData.time, cuvis.SensorInfo.readout_time - type changed from a naive datetime.datetime to one carrying tzinfo=datetime.timezone.utc.
    The instant is unchanged, only the +00:00 label is added; comparing or subtracting against a naive datetime now raises TypeError, so use datetime.datetime.now(datetime.timezone.utc) or .astimezone() for local time.
  • cuvis.CalibrationInfo.calibration_date - type changed from int to a datetime.datetime carrying tzinfo=datetime.timezone.utc; the field was annotated as a datetime but returned the raw epoch milliseconds unconverted.
    The SDK derives this value as midnight on the calibration day in the host's standard local time, so unlike the other timestamps the instant it denotes shifts with the reading machine; treat it as a day, not as an exact moment.
  • cuvis.Measurement.factory_calibration - type changed from datetime.datetime to datetime.datetime | None, matching the existing fallback to None for SDK values the datetime range cannot represent.
    Only the day carries meaning: the SDK stores it as midnight in the local time of the machine that wrote the file, so the time component is an artifact of that machine and the day can be off by one when the file is read in another timezone.
  • pyproject.toml - requires-python raised from >=3.9 to >=3.10, Python 3.9 having reached end of life in October 2025.
  • Annotations throughout cuvis restated in the forms Python 3.10 provides: Union[A, B] and Optional[A] became A | B and A | None, and Tuple, FrozenSet, Sequence, Callable and Awaitable now come from builtins and collections.abc rather than typing.
    Every signature denotes what it denoted before; cuvis.cube_utils.ImageData.__getitem__ keeps Union, because its member list contains a forward reference and | cannot join a type to a string at runtime.
  • cuvis.AcquisitionContext.capture - parameter to_interal renamed to to_internal.
  • cuvis.Async.AsyncMesu.__await__, cuvis.Async.Async.__await__, cuvis.Worker.get_next_result_async - await the SDK's own blocking wait in a worker thread instead of polling it every 10 ms or 100 ms, so they resume when the SDK finishes rather than at the next poll.
    Each outstanding wait occupies one pooled thread, and it cannot be cancelled, because a thread blocked in C is not interruptible.
  • cuvis.Worker.register_worker_callback - awaits each result instead of re-checking every 1 ms, so an idle registered callback no longer occupies a core.
    cuvis.Worker.reset_worker_callback therefore takes effect only once the current one-second wait expires.

Removed

  • CI - .github/workflows/tests.yml and .github/workflows/publish_version.yml removed; their jobs moved into ci.yml and release.yml.
  • git-hash.txt at the repository root - removed; the file is generated into cuvis/ by prebuild.py and is no longer tracked.
  • Unused imports and locals dropped from cuvis.AcquisitionContext, cuvis.Export, cuvis.General, cuvis.Measurement, cuvis.Viewer, cuvis.Worker, cuvis.cuvis_aux, cuvis.doc and the test modules; no public name was removed.
  • pyproject.toml - the typing_extensions dependency removed; ParamSpec and TypeAlias are in typing from Python 3.10.
  • pyproject.toml - the Programming Language :: Python :: 3.9 classifier removed.

Fixed

  • cuvis.General.wrapper_version - raised FileNotFoundError on every pip-installed release since 3.3.1, because it read git-hash.txt from the directory above the package while no distribution ever shipped that file.
    The hash is now read from cuvis/git-hash.txt, which the wheel and the sdist do ship, and a missing file degrades to reporting the version alone instead of raising.
  • tests/test_general.py - test_wrapper_version asserted the literal 3.5.3, so it had to be edited on every SDK bump and passed only because an editable install exposed the untracked root git-hash.txt.
    It now compares against the installed distribution version.
  • cuvis.AcquisitionContext.register_ready_callback - parameter callback was annotated Callable[None, Awaitable[None]], which is not a valid Callable form; it is now Callable[[], Awaitable[None]], matching the no-argument call the implementation makes.
  • cuvis.AcquisitionContext.capture - to_internal=True raised TypeError instead of queueing the measurement, because it passed a Python 0 where SWIG requires a null pointer.
  • cuvis.Calibration, cuvis.AcquisitionContext, cuvis.ProcessingContext, cuvis.SessionFile, cuvis.Measurement, cuvis.Viewer, cuvis.Worker, cuvis.CubeExporter, cuvis.EnviExporter, cuvis.TiffExporter, cuvis.ViewExporter - __del__ raised TypeError after a failed construction, because it freed a handle that was still None.
  • cuvis.Worker.get_next_result_async - a timeout returned a cuvis.Worker.WorkerResult built from handles the SDK never filled in; it now raises cuvis.cuvis_aux.SDKException.
  • cuvis.CudaImageData.to_torch, cuvis.CudaImageData.__cuda_array_interface__ - raised AttributeError on every call, because _view used cuvis_il.cuvis_cuda_view_ptr, which no cuvis-il build exports.
    The device pointer is now read from the cuvis_cuda_mem_view_t field directly, so no binding helper is involved and none can go missing.
  • cuvis.CudaImageData.make_ipc, cuvis.CudaImageData.export_payload - raised AttributeError, because they used cuvis_il.cuvis_cuda_descriptor_bytes, which no cuvis-il build exports.
    The descriptor is now serialized in Python to the same 184-byte layout cuvis_ipc parses.
  • cuvis.CudaImageData.__del__, cuvis.CudaImageData.to_torch - device buffers were never released: both freed through cuvis_cuda_mem_free(handle), but the C API declares cuvis_cuda_mem_free(CUVIS_CUDA_MEM*), so every call raised TypeError out of the binding.
    In __del__ that surfaced only as an ignored exception, and in the DLPack capsule deleter not at all, so a long-running consumer exhausted the card. The handle is now boxed, and cuvis_cuda_ipc_handle_free is corrected the same way.
  • tests/test_cuda_image_data.py - behavior tests for the device-buffer path, which nothing previously executed: a static check that cube_utils references no absent cuvis_il symbol, the descriptor's wire layout and its agreement with cuvis_ipc, the free calling convention, and, on a machine with a CUDA device, that the zero-copy tensor equals the host cube and that repeated read-and-drop cycles return their memory.
    The static and layout checks need no device, which matters because CI has none and therefore never ran this code.