VoxelFeatureField
Note
This page is a reference documentation. It only explains the class signature, and not how to use it. Please refer to the Habitat Guide and Python API guide (v2.0) for usage.
- class VoxelFeatureField(subject_id: str, feature_names: Tuple[str, ...], values: ndarray, voxel_index: ndarray, geometry: Geometry, provenance: Provenance)[source]
Bases:
objectPer-voxel feature vectors inside one subject’s ROI.
This is where every habitat analysis begins. In v0.1 it existed only as an anonymous
DataFramepassed between pipeline steps, which made it impossible for an external tool to supply its own voxel features (for example embeddings from a self-supervised model).- values
Array of shape
(n_voxels, n_features).- Type:
- voxel_index
Array of shape
(n_voxels, 3)giving the(z, y, x)grid position of each row, so the field can be rendered back into image space.- Type:
- geometry
Grid the indices refer to.
- provenance
How this field was produced.
- feature_frame() DataFrame[source]
Return the bare unit-by-feature matrix.
The uniform algorithm view shared with
Supervoxelization.feature_frame(). Any operation defined on “a matrix whose rows are clustering units” can therefore be written once and applied at either granularity, even though the two contracts store their matrices differently – an array plus column names here, because a subject holds hundreds of thousands of voxels whose row identity is a 3D coordinate; an indexed frame there, because supervoxels are few and identified by a single id.Unlike
to_frame(), no coordinate columns are added: the result contains features and nothing else, so column-wise computations need no exclusion list.- Returns:
Feature matrix with a positional index, in
feature_namesorder.
- with_feature_frame(frame: DataFrame, *, produced_by: str, spec_fingerprint: str) VoxelFeatureField[source]
Return a copy carrying a recomputed feature matrix.
- Parameters:
frame – Replacement matrix, row-aligned with this field. Columns may be fewer than the current ones (a filtering step) but the row count must match, since
voxel_indexcontinues to describe those rows.produced_by – Provenance label of the step that produced
frame.spec_fingerprint – Fingerprint of that step’s specification.
- Returns:
A new field sharing this field’s geometry and voxel index.
- Raises:
HABITAPIError – If
framehas a different number of rows.
- save(path: str | Path) Path[source]
Persist the field as a versioned zip (manifest + arrays).
Not a pickle: the archive stays readable across HABIT versions.
voxel_batchand device knobs do not belong here; they do not change the numbers.- Parameters:
path – Destination file path.
- Returns:
The written path.
- classmethod load(path: str | Path) VoxelFeatureField[source]
Load a field previously written by
save().- Parameters:
path – Source file path.
- Returns:
The reconstructed field.
- Raises:
FileNotFoundError – If
pathdoes not exist.CompatibilityError – If the archive is not a voxel-field file or is newer than this HABIT can read.
