Repository navigation
v3.6.0.0
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 parametereffective_bit_depth: int | None = None.cuvis.ProcessingContext.set_reference- new parameterintegration_time: float = 0.0.cuvis.ProcessingContext.get_reference_spectrum- new method.
Returns the white or target reference spectrum as anImageData, orNonewhen the slot is empty.
Target values are reflectance fractions (1.0 = 100 percent); the white spectrum additionally carrieseffective_bit_depthandintegration_timeattributes.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.cu3save behind.cu3spsidecar links and the stored cube is bit-identical after reload.CI-.github/workflows/ci.ymlruns the test suite and a lint job enforcingruff checkandruff format --checkon every pull request and on every push todevelopandmain.CI-.github/workflows/release.ymlis driven byv*.*.*.*tags: it validates the tag againstpyproject.toml, this file and thecuvis_pyilimage, builds, publishes to TestPyPI, and publishes to PyPI plus a GitHub Release after manual approval.
Pre-release tags (a,b,rcsuffix) 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 thecuvis-ilrequirement 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 fieldsbuilt_against: str,library_version: str,library_path: strandmissing_symbols: tuple[str, ...], the read-only propertyis_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, returnsbytes.cuvis.CudaImageData.make_ipc- new method, returnsbytes.cuvis.CudaImageData.to_torch- new method, returnstorch.Tensor.cuvis.Measurement.get_cube- new method, returnsImageData | CudaImageDatadepending on whethercuvis.cuda.enablewas called.cuvis.Measurement.get_cube_cuda- new method, returnsCudaImageData.cuvis.Measurement.get_cube_cuda_ipc- new method, returnsCudaImageData.cuvis.SdkSettings- new class, aMutableMappingof setting id to value that writes the SDK'scuvis.settingsfile, so the SDK configuration can be built in Python instead of maintained by hand.
Values are stored as strings:boolbecomestrue/false, anEnumbecomes its value, anything else goes throughstr(), andNonedrops the entry.cuvis.SdkSettings.__enter__,cuvis.SdkSettings.__exit__- new methods; entering the context serializes the settings into a temporary directory and returns its path asstr, leaving the context removes the directory.cuvis.SdkSettings.save- new method, writes the settings to a file, or into a directory ascuvis.settings.cuvis.SdkSettings.xml_str- new read-only property, returns the serialized settings document asstr.cuvis.UnavailableSDKFunction- new exception deriving from bothcuvis.cuvis_aux.SDKExceptionandRuntimeError, with the fieldnames: 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 beforecuvis.init.cuvis.binding.available- new function, returnsbool.cuvis.binding.info- new function, returnsBindingInfo.cuvis.binding.missing_symbols- new function, returnsfrozenset[str].cuvis.binding.require- new function, raisesUnavailableSDKFunctionnaming whichever of the given functions the installed cuvis library does not provide.cuvis.binding.unavailable- new function, returnstuple[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 untilcuvis.cuda.enableis called.cuvis.cuda.BACKEND_NONE,cuvis.cuda.BACKEND_POOL,cuvis.cuda.BACKEND_LEGACY,cuvis.cuda.BACKEND_VMM- new constants, the IPC backend codes fromcuvis.h.cuvis.cuda.CudaCapabilities- newNamedTuplewith theboolfieldssame_process,ipc_pool,ipc_legacy,ipc_vmm,torchandcuda_python, and the read-only propertyany_ipc: bool.cuvis.cuda.capabilities- new function, returnsCudaCapabilities.cuvis.cuda.disable- new function.cuvis.cuda.enable- new function.cuvis.cuda.is_enabled- new function, returnsbool.cuvis.cuda.require_device- new function, raisesUnavailableSDKFunctionunless the installed library provides the same-process device path.cuvis.cuda.require_ipc- new function, raisesUnavailableSDKFunctionunless 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 thecuvispackage because importingcuvisrequires the SDK and a consumer process does not have one; its only import isstruct.cuvis_ipc.ImportedCube- new class, a mapped IPC buffer in the consumer process, usable as a context manager.cuvis_ipc.open- new function, returnsImportedCube.cuvis_ipc.open_descriptor- new function, returnsImportedCube.cuvis_ipc.pack_payload- new function, returnsbytes.pyproject.toml-py-modulesdeclaring the top-levelcuvis_ipc.tests/-test_binding.py,test_cuda.pyandtest_cuvis_ipc.py.
Changed
- Whole tree reformatted with
ruff format; no behaviour change. pyproject.toml- thecuvis-ilrequirement moved from>=3.5.0,<3.6.0to>=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:developis gone, every change is cut frommainand merged back into it by pull request, and a commit onmainis 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 aMeasurement; the first parameter is renamed frommesutodata.README.md- documents the version scheme, and lists Python 3.14 among the supported interpreters aspyproject.tomlalready did.prebuild.py- writescuvis/git-hash.txtinstead ofgit-hash.txtat the repository root, so the file lands inside the package that declares it as package data.cuvis.General.init- parametersettings_pathtype changed fromstrtostr | Path | SdkSettings.
AnSdkSettingsis 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 naivedatetime.datetimeto one carryingtzinfo=datetime.timezone.utc.
The instant is unchanged, only the+00:00label is added; comparing or subtracting against a naivedatetimenow raisesTypeError, so usedatetime.datetime.now(datetime.timezone.utc)or.astimezone()for local time.cuvis.CalibrationInfo.calibration_date- type changed fromintto adatetime.datetimecarryingtzinfo=datetime.timezone.utc; the field was annotated as adatetimebut 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 fromdatetime.datetimetodatetime.datetime | None, matching the existing fallback toNonefor SDK values thedatetimerange 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-pythonraised from>=3.9to>=3.10, Python 3.9 having reached end of life in October 2025.- Annotations throughout
cuvisrestated in the forms Python 3.10 provides:Union[A, B]andOptional[A]becameA | BandA | None, andTuple,FrozenSet,Sequence,CallableandAwaitablenow come frombuiltinsandcollections.abcrather thantyping.
Every signature denotes what it denoted before;cuvis.cube_utils.ImageData.__getitem__keepsUnion, because its member list contains a forward reference and|cannot join a type to a string at runtime. cuvis.AcquisitionContext.capture- parameterto_interalrenamed toto_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_callbacktherefore takes effect only once the current one-second wait expires.
Removed
CI-.github/workflows/tests.ymland.github/workflows/publish_version.ymlremoved; their jobs moved intoci.ymlandrelease.yml.git-hash.txtat the repository root - removed; the file is generated intocuvis/byprebuild.pyand 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.docand the test modules; no public name was removed. pyproject.toml- thetyping_extensionsdependency removed;ParamSpecandTypeAliasare intypingfrom Python 3.10.pyproject.toml- theProgramming Language :: Python :: 3.9classifier removed.
Fixed
cuvis.General.wrapper_version- raisedFileNotFoundErroron every pip-installed release since 3.3.1, because it readgit-hash.txtfrom the directory above the package while no distribution ever shipped that file.
The hash is now read fromcuvis/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_versionasserted the literal3.5.3, so it had to be edited on every SDK bump and passed only because an editable install exposed the untracked rootgit-hash.txt.
It now compares against the installed distribution version.cuvis.AcquisitionContext.register_ready_callback- parametercallbackwas annotatedCallable[None, Awaitable[None]], which is not a validCallableform; it is nowCallable[[], Awaitable[None]], matching the no-argument call the implementation makes.cuvis.AcquisitionContext.capture-to_internal=TrueraisedTypeErrorinstead of queueing the measurement, because it passed a Python0where 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__raisedTypeErrorafter a failed construction, because it freed a handle that was stillNone.cuvis.Worker.get_next_result_async- a timeout returned acuvis.Worker.WorkerResultbuilt from handles the SDK never filled in; it now raisescuvis.cuvis_aux.SDKException.cuvis.CudaImageData.to_torch,cuvis.CudaImageData.__cuda_array_interface__- raisedAttributeErroron every call, because_viewusedcuvis_il.cuvis_cuda_view_ptr, which nocuvis-ilbuild exports.
The device pointer is now read from thecuvis_cuda_mem_view_tfield directly, so no binding helper is involved and none can go missing.cuvis.CudaImageData.make_ipc,cuvis.CudaImageData.export_payload- raisedAttributeError, because they usedcuvis_il.cuvis_cuda_descriptor_bytes, which nocuvis-ilbuild exports.
The descriptor is now serialized in Python to the same 184-byte layoutcuvis_ipcparses.cuvis.CudaImageData.__del__,cuvis.CudaImageData.to_torch- device buffers were never released: both freed throughcuvis_cuda_mem_free(handle), but the C API declarescuvis_cuda_mem_free(CUVIS_CUDA_MEM*), so every call raisedTypeErrorout 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, andcuvis_cuda_ipc_handle_freeis corrected the same way.tests/test_cuda_image_data.py- behavior tests for the device-buffer path, which nothing previously executed: a static check thatcube_utilsreferences no absentcuvis_ilsymbol, the descriptor's wire layout and its agreement withcuvis_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.