Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -7,9 +7,11 @@
/cuvis/cuvis_il.py
/cuvis/_cuvis_pyil.pyd
/venv
/__pycache__
/cuvis/__pycache__
/cuvis/git-hash.txt

/tests/__pycache__
/examples/__pycache__
/.claude

36 changes: 31 additions & 5 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -29,19 +29,45 @@ Pre-releases (`b*`, `rc*`) are not listed.
- `CI` - the changelog structure and the tag/version/changelog agreement are validated by the shared actions in [cuvis.docker](https://github.com/cubert-hyperspectral/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.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.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.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

Expand All @@ -51,14 +77,14 @@ Pre-releases (`b*`, `rc*`) are not listed.
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 `Union[str, Path, SdkSettings]`.
- `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 `Optional[datetime.datetime]`, matching the existing fallback to `None` for SDK values the `datetime` range cannot represent.
- `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`.
Expand Down
101 changes: 100 additions & 1 deletion cuvis/Measurement.py
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,8 @@
_utc_from_epoch_ms,
)
from .cuvis_types import DataFormat, ProcessingMode, ReferenceType
from .cube_utils import ImageData
from .cube_utils import ImageData, CudaImageData
from . import cuda


import cuvis.cuvis_types as internal
Expand All @@ -36,6 +37,13 @@ class Measurement(object):
session_info: SessionData # read-only
frame_id: int # read-only

# When False, refresh() skips fetching image data to the host via
# cuvis_measurement_get_data_image. That host fetch moves a GPU-processed cube
# into host memory and frees the device copy, which makes the same-process CUDA
# path (get_cube_cuda) unavailable. Set False before processing when you intend
# to read the cube as CUDA device memory. Default True preserves normal behaviour.
_refresh_images = True

def __init__(self, base: int | str | Path):
self._handle = None
self._session = None
Expand Down Expand Up @@ -106,6 +114,10 @@ def refresh(self) -> None:
)
cdtype = cuvis_il.p_cuvis_data_type_t_value(pType)
if cdtype == cuvis_il.data_type_image:
if not Measurement._refresh_images:
# Skip the host fetch so a GPU-processed cube stays in device
# memory and remains reachable via get_cube_cuda.
continue
data = cuvis_il.cuvis_imbuffer_t()
cuvis_il.cuvis_measurement_get_data_image(self._handle, key, data)
# t0 = datetime.datetime.now()
Expand Down Expand Up @@ -274,6 +286,93 @@ def cube(self) -> ImageData:
"This Measurement does not have a cube saved. Consider reprocessing with a Processing Context."
)

def get_cube_cuda(self, key: str = "cube") -> CudaImageData:
"""Image data as a device-resident CUDA buffer for same-process, zero-copy use.

.. code-block:: python3

from cuvis import cuda

if cuda.capabilities().same_process:
cuda.enable() # BEFORE loading or processing
tensor = mesu.get_cube_cuda().to_torch()

Returns a :class:`cuvis.CudaImageData` wrapping a CUVIS_CUDA_MEM handle; read it
with ``.to_torch()`` (DLPack, which ties the buffer lifetime to the tensor) or
through ``__cuda_array_interface__`` (which does not, so keep the CudaImageData
alive). No host copy is made.

The cube must still be on the device, which it is only when `cuda.enable` was
called before it was processed; the host fetch in `refresh` otherwise moves it to
host memory and frees the device copy.

:param key: which image entry to read, `"cube"` unless the measurement carries
several.
:raises cuvis.UnavailableSDKFunction: the installed cuvis library provides no
CUDA support; call `cuda.capabilities` first to avoid this.
:raises cuvis.cuvis_aux.SDKException: the image data is not device-backed.
"""
cuda.require_device()
buf = cuvis_il.cuvis_cuda_imbuffer_t()
if cuvis_il.status_ok != cuvis_il.cuvis_measurement_get_data_image_cuda(
self._handle, key, buf
):
raise SDKException()
return CudaImageData(buf)

def get_cube_cuda_ipc(self, key: str = "cube", backend: int = 0) -> CudaImageData:
"""Image data as a shareable CUDA buffer for cross-process use.

Producer side; the consumer opens the payload with :mod:`cuvis_ipc`, which needs
no SDK of its own.

.. code-block:: python3

cimg = mesu.get_cube_cuda_ipc() # keep alive until the consumer is done
send(cimg.export_payload()) # descriptor + geometry, one blob

# ... in the consumer process, no cuvis installed ...
import cuvis_ipc
with cuvis_ipc.open(payload) as cube:
tensor = cube.to_torch()

Fetches the device buffer with `get_cube_cuda` and creates an IPC export on it,
filling `.descriptor` with the transportable bytes. The returned object is the
in-process pin, since legacy IPC carries no cross-process refcount: drop it and
the consumer is reading freed device memory.

:param key: which image entry to read.
:param backend: which mechanism to export with, one of `cuvis.cuda.BACKEND_NONE`
(auto), `BACKEND_POOL`, `BACKEND_LEGACY` or `BACKEND_VMM`. `cuda.capabilities`
reports which of them this device supports.
:raises cuvis.UnavailableSDKFunction: the installed cuvis library provides no
CUDA IPC support.
:raises cuvis.cuvis_aux.SDKException: the requested backend is unavailable on
this device.
"""
cimg = self.get_cube_cuda(key)
cimg.make_ipc(backend)
return cimg

def get_cube(self, key: str = "cube") -> ImageData | CudaImageData:
"""Cube through whichever mode is active, so one call site serves both.

.. code-block:: python3

cube = mesu.get_cube() # CudaImageData after cuda.enable(), else ImageData

With CUDA mode on (`cuvis.cuda.enable`) this is `get_cube_cuda` and raises when
the device path is unavailable. There is deliberately no silent fallback to the
host: a zero-copy path that quietly degrades to two copies is worse than an error,
because the cost is invisible.

:param key: which image entry to read.
:return: `CudaImageData` in CUDA mode, otherwise the host `ImageData`.
"""
if cuda.is_enabled():
return self.get_cube_cuda(key)
return self.cube

@property
def thumbnail(self):
thumb = [val for key, val in self.data.items() if "view" in key]
Expand Down
3 changes: 2 additions & 1 deletion cuvis/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -41,7 +41,8 @@
from .Export import CubeExporter, EnviExporter, TiffExporter, ViewExporter
from .Calibration import Calibration
from .AcquisitionContext import AcquisitionContext
from .cube_utils import ImageData
from .cube_utils import ImageData, CudaImageData
from . import cuda
import os
import platform
import sys
Expand Down
104 changes: 104 additions & 0 deletions cuvis/_dlpack.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,104 @@
"""Minimal DLPack producer over a raw CUDA device pointer.

Builds a DLManagedTensor PyCapsule via ctypes so torch.from_dlpack can consume a
foreign device buffer zero-copy. The capsule deleter calls a supplied on_delete
callback when torch releases the tensor, which is how buffer lifetime is tied to
the tensor (the callback drops the SDK reference that pins the buffer).

Ported from utils_data_cuda/examples/torch_local.py; the only change is that the
deleter calls an injected callback instead of a hard-coded ctypes SDK.
"""

import ctypes

_kDLCUDA = 2
_kDLInt = 0
_kDLUInt = 1
_kDLFloat = 2


class _DLDevice(ctypes.Structure):
_fields_ = [("device_type", ctypes.c_int), ("device_id", ctypes.c_int)]


class _DLDataType(ctypes.Structure):
_fields_ = [
("code", ctypes.c_uint8),
("bits", ctypes.c_uint8),
("lanes", ctypes.c_uint16),
]


class _DLTensor(ctypes.Structure):
_fields_ = [
("data", ctypes.c_void_p),
("device", _DLDevice),
("ndim", ctypes.c_int),
("dtype", _DLDataType),
("shape", ctypes.POINTER(ctypes.c_int64)),
("strides", ctypes.POINTER(ctypes.c_int64)),
("byte_offset", ctypes.c_uint64),
]


class _DLManagedTensor(ctypes.Structure):
pass


_DELETER = ctypes.CFUNCTYPE(None, ctypes.POINTER(_DLManagedTensor))
_DLManagedTensor._fields_ = [
("dl_tensor", _DLTensor),
("manager_ctx", ctypes.c_void_p),
("deleter", _DELETER),
]

_pycapsule_new = ctypes.pythonapi.PyCapsule_New
_pycapsule_new.restype = ctypes.py_object
_pycapsule_new.argtypes = [ctypes.c_void_p, ctypes.c_char_p, ctypes.c_void_p]

# Keep ctypes structs / deleters / callbacks alive until torch invokes the deleter.
_LIVE = {}


class CudaDlpack:
"""DLPack producer over (ptr, nbytes) on a CUDA device. on_delete() runs when
torch releases the tensor. Exposes a flat uint8 buffer; reshape/retype in torch."""

def __init__(self, ptr, nbytes, device, on_delete):
self._ptr = int(ptr)
self._n = int(nbytes)
self._dev = int(device)
self._on_delete = on_delete

def __dlpack_device__(self):
return (_kDLCUDA, self._dev)

def __dlpack__(self, stream=None, max_version=None, dl_device=None, copy=None):
shape = (ctypes.c_int64 * 1)(self._n)
mt = _DLManagedTensor()
mt.dl_tensor.data = ctypes.c_void_p(self._ptr)
mt.dl_tensor.device = _DLDevice(_kDLCUDA, self._dev)
mt.dl_tensor.ndim = 1
mt.dl_tensor.dtype = _DLDataType(_kDLUInt, 8, 1)
mt.dl_tensor.shape = shape
mt.dl_tensor.strides = None
mt.dl_tensor.byte_offset = 0

on_delete = self._on_delete
key = id(mt)

def _del(_p):
try:
on_delete()
finally:
_LIVE.pop(key, None)

deleter = _DELETER(_del)
mt.deleter = deleter
_LIVE[key] = (mt, shape, deleter)
return _pycapsule_new(ctypes.byref(mt), b"dltensor", None)


def make_cuda_dlpack(ptr, nbytes, device, on_delete):
"""Return an object that torch.from_dlpack consumes into a zero-copy CUDA tensor."""
return CudaDlpack(ptr, nbytes, device, on_delete)
Loading