Migration

0.10.2 to 1.0.0

Version 1.0.0 renames several public Python and C APIs to remove the redundant HS and HSI prefixes and to make camera and stage-control APIs explicit. Most image processing code keeps the same lazy execution model: build pipelines first, then evaluate them with operations such as qtec_hv_sdk.Image.to_numpy(), qtec_hv_sdk.Image.resolve(), qtec_hv_sdk.Image.stream(), or qtec_hv_sdk.write().

Python package and type names

Use qtec_hv_sdk as the Python package name:

import qtec_hv_sdk as hs

img = hs.open("input.hdr")
result = img.ensure_dtype(hs.float32).to_numpy()

The preferred v1 names are shorter and match the current documentation.

0.10.2 name	1.0.0 name	Notes
HSImage	qtec_hv_sdk.Image	Main image and pipeline type.
InMemoryCube	ImageArray	In-memory image data.
HSIFile	ImageFile	File-backed image data.
HSCamera	qtec_hv_sdk.control.Camera	Now exposed from the control submodule.
HSIHeader	qtec_hv_sdk.ImageMeta	HSIHeader is kept as a compatibility alias.
HSIError	Error	Base SDK error type.

Update type annotations and imports to the v1 names in new code. Compatibility aliases may exist for some older names, but they should be treated as a bridge while migrating rather than as the preferred API.

Removed and added Python APIs

The write_meta function was removed. Metadata should be carried by the image object and written together with image data through qtec_hv_sdk.write().

Images now expose a deterministic structural UUID for pipeline nodes through the qtec_hv_sdk.Image.uuid property:

import qtec_hv_sdk as hs

img = hs.open("input.hdr")
print(img.uuid)

The Python package also ships with .pyi type stubs. Type checkers and editors can use these stubs to find old imports, old type names, and calls to removed functions during migration.

Camera and stage control

Camera and stage APIs now live under the qtec_hv_sdk.control submodule:

from qtec_hv_sdk.control import Camera, StageController

cam = Camera("<camera_ip>")
stage = StageController("<camera_ip>", fps=30.0, distance=150.0)

If existing code imported these objects from the package root, update those imports:

# 0.10.2
from qtec_hv_sdk import HSCamera, StageController

cam = HSCamera("<camera_ip>")
stage = StageController("<camera_ip>")

# 1.0.0
from qtec_hv_sdk.control import Camera, StageController

cam = Camera("<camera_ip>")
stage = StageController("<camera_ip>")

Control errors were also renamed from CameraError to ControlError to cover both camera and stage failures. Missing camera controls now report a clearer ControlNotFound error variant.

The stage-controller lens-size helper has been replaced by explicit optical parameters:

from qtec_hv_sdk.control import StageController

stage = StageController("<camera_ip>", fps=30.0, distance=150.0)
stage.focal_length = 12.0      # mm
stage.object_distance = 258.0  # mm
stage.pixel_pitch = 5.0        # um
stage.slit_width = 20.0        # um

These values are used to derive the pixel and slit field of view used by the stage controller. Code that relied on the old lens-size helper should set the explicit optical parameters instead.

C FFI names

The C API follows the same v1 naming cleanup. Update public image and metadata types and function prefixes:

0.10.2 C API	1.0.0 C API
hv_hs_image_t	hv_image_t
hv_hs_image_*	hv_image_*
hv_hsi_header_t	hv_image_meta_t
hv_hsi_header_*	hv_image_meta_*

The v1 metadata struct groups public metadata fields by topic, including camera, spectral, spatial, radiometric, temporal, calibration, sensor, encoding, and display metadata. See the C metadata reference for the current hv_image_meta_t layout.

Metadata

Python metadata now uses qtec_hv_sdk.ImageMeta as the top-level type. It keeps core shape and layout information directly and groups richer metadata into focused objects.

# 0.10.2 style
header = img.meta
wavelengths = header.wavelength_info
byte_order = header.byte_order

# 1.0.0 style
meta = img.meta
wavelengths = meta.spectral.wavelengths
byte_order = meta.encoding.byte_order

Legacy metadata accessors such as byte_order, capture, default_bands, measurement_info, and wavelength_info are kept for older code where possible. Prefer the grouped metadata objects in new code and when updating examples.

Versioned documentation

The documentation is now built for both current and previous SDK versions. Keep the 0.10.2 documentation available while migrating if you need to compare old examples with the v1 API.