Skip to content

Feature extraction

The qim3d library provides a set of methods for feature extraction on volumetric data.

General usage

  • All features assume a single connected object in the input.
  • All feature functions accept either a 3D volume or a mesh as input.
  • If a volume is provided, it is typically binarized (using the provided threshold or Otsu's method by default) and converted to a mesh before feature extraction.
  • A mask can be provided to restrict feature extraction to a specific region of interest in the volume.
  • If a mesh is provided, the threshold and/or mask arguments are ignored.

Efficient feature extraction

Before extracting multiple features, convert your input volume to a mesh using qim3d.mesh.from_volume for best performance. This avoids repeated volume-to-mesh conversions under the hood during feature extraction.

qim3d.features.area 

area(object, mask=None, threshold='otsu')

Calculates the total surface area of a 3D object.

This function quantifies the surface size of a structure, which is a fundamental metric in morphometry and material science. It accepts either a raw 3D volume (which is automatically meshed using Marching Cubes) or a pre-computed PyGEL3D mesh.

Parameters:

Name Type Description Default
object ndarray or Manifold

The input data. Can be a 3D NumPy array (volume) or a pygel3d.hmesh.Manifold object (mesh).

 required
mask ndarray

A boolean mask defining a Region of Interest (ROI) within the volume. Must have the same shape as object. Defaults to None.

 None
threshold float or str

The intensity value used to binarize the volume if a NumPy array is provided.

  • float: A specific intensity value.
  • 'otsu': Automatically calculates the threshold using Otsu's method. Defaults to 'otsu'.
 'otsu'

Returns:

Name Type Description
area float

The computed surface area in square units (determined by the input resolution).

Raises:

Type Description
ValueError

If mask is provided but its shape does not match the input object.
Example

Compute area from a np.ndarray volume: 

import qim3d

# Generate a synthetic object
synthetic_object = qim3d.generate.volume()

# Compute the surface area of the object
area = qim3d.features.area(synthetic_object)
print(area)
58535.06

Example

Compute area from a pygel3d.hmesh.Manifold mesh: 

import qim3d

# Generate a synthetic object
synthetic_object = qim3d.generate.volume()

# Convert into a mesh
mesh = qim3d.mesh.from_volume(synthetic_object)

# Compute the surface area of the object
area = qim3d.features.area(mesh)
print(area)
58535.06

Source code in qim3d/features/_common_features_methods.py 
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
def area(
    object: np.ndarray | hmesh.Manifold,
    mask: np.ndarray | None = None,
    threshold: float | str = 'otsu',
) -> float:
    """
    Calculates the total surface area of a 3D object.

    This function quantifies the surface size of a structure, which is a fundamental metric in morphometry and material science. It accepts either a raw 3D volume (which is automatically meshed using Marching Cubes) or a pre-computed `PyGEL3D` mesh.

    Args:
        object (np.ndarray or hmesh.Manifold): The input data. Can be a 3D NumPy array (volume) or a `pygel3d.hmesh.Manifold` object (mesh).
        mask (np.ndarray, optional): A boolean mask defining a Region of Interest (ROI) within the volume. Must have the same shape as `object`. Defaults to `None`.
        threshold (float or str, optional): The intensity value used to binarize the volume if a NumPy array is provided.

            * **float**: A specific intensity value.
            * **'otsu'**: Automatically calculates the threshold using Otsu's method. Defaults to 'otsu'.

    Returns:
        area (float):
            The computed surface area in square units (determined by the input resolution).

    Raises:
        ValueError: If `mask` is provided but its shape does not match the input `object`.

    Example:
        Compute area from a `np.ndarray` volume:
        ```python
        import qim3d

        # Generate a synthetic object
        synthetic_object = qim3d.generate.volume()

        # Compute the surface area of the object
        area = qim3d.features.area(synthetic_object)
        print(area)
        ```
        58535.06

    Example:
        Compute area from a `pygel3d.hmesh.Manifold` mesh:
        ```python
        import qim3d

        # Generate a synthetic object
        synthetic_object = qim3d.generate.volume()

        # Convert into a mesh
        mesh = qim3d.mesh.from_volume(synthetic_object)

        # Compute the surface area of the object
        area = qim3d.features.area(mesh)
        print(area)
        ```
        58535.06
    """
    # Prepare object
    mesh = prepare_obj(object, threshold=threshold, mask=mask, return_mesh=True)

    # Compute area
    area = hmesh.area(mesh)

    return area

qim3d.features.volume 

volume(object, mask=None, threshold='otsu')

Computes the enclosed physical volume of a 3D object.

This function quantifies the amount of space occupied by a structure. It is robust and versatile, handling both raw 3D image arrays (voxels) and pre-generated meshes. If a voxel array is provided, it is automatically converted into a mesh using the specified threshold before the volume is calculated, ensuring sub-voxel accuracy compared to simple voxel counting.

Parameters:

Name Type Description Default
object ndarray or Manifold

The input data. Can be a 3D NumPy array (volume) or a pygel3d.hmesh.Manifold object (mesh).

 required
mask ndarray

A boolean mask defining a Region of Interest (ROI). Only the volume within this mask is included. Must have the same shape as object. Defaults to None.

 None
threshold float or str

The intensity value used to binarize the volume if a NumPy array is provided.

  • float: A specific intensity value.
  • 'otsu': Automatically calculates the threshold using Otsu's method. Defaults to 'otsu'.
 'otsu'

Returns:

Name Type Description
volume float

The calculated volume in cubic units (determined by the input resolution).

Raises:

Type Description
ValueError

If mask is provided but its shape does not match the input object.
Example 

import qim3d
import numpy as np

# Generate a synthetic object
synthetic_object = qim3d.generate.volume(noise_scale=0.01, final_shape=(100, 100, 100))

# Create a mask for the bottom right corner
mask = np.zeros_like(synthetic_object, dtype=bool)
mask[50:100, 50:100, 50:100] = True

# Compute the volume of the object within the region of interest defined by the mask
volume = qim3d.features.volume(synthetic_object, threshold=50, mask=mask)
print(volume)
48774.99

Source code in qim3d/features/_common_features_methods.py 
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
def volume(
    object: np.ndarray | hmesh.Manifold,
    mask: np.ndarray | None = None,
    threshold: float | str = 'otsu',
) -> float:
    """
    Computes the enclosed physical volume of a 3D object.

    This function quantifies the amount of space occupied by a structure. It is robust and versatile, handling both raw 3D image arrays (voxels) and pre-generated meshes. If a voxel array is provided, it is automatically converted into a mesh using the specified threshold before the volume is calculated, ensuring sub-voxel accuracy compared to simple voxel counting.

    Args:
        object (np.ndarray or hmesh.Manifold): The input data. Can be a 3D NumPy array (volume) or a `pygel3d.hmesh.Manifold` object (mesh).
        mask (np.ndarray, optional): A boolean mask defining a Region of Interest (ROI). Only the volume within this mask is included. Must have the same shape as `object`. Defaults to `None`.
        threshold (float or str, optional): The intensity value used to binarize the volume if a NumPy array is provided.

            * **float**: A specific intensity value.
            * **'otsu'**: Automatically calculates the threshold using Otsu's method. Defaults to 'otsu'.

    Returns:
        volume (float):
            The calculated volume in cubic units (determined by the input resolution).

    Raises:
        ValueError: If `mask` is provided but its shape does not match the input `object`.

    Example:
        ```python
        import qim3d
        import numpy as np

        # Generate a synthetic object
        synthetic_object = qim3d.generate.volume(noise_scale=0.01, final_shape=(100, 100, 100))

        # Create a mask for the bottom right corner
        mask = np.zeros_like(synthetic_object, dtype=bool)
        mask[50:100, 50:100, 50:100] = True

        # Compute the volume of the object within the region of interest defined by the mask
        volume = qim3d.features.volume(synthetic_object, threshold=50, mask=mask)
        print(volume)
        ```
        48774.99
    """
    # Prepare object
    mesh = prepare_obj(object, threshold=threshold, mask=mask, return_mesh=True)

    # Compute volume
    volume = hmesh.volume(mesh)

    return volume

qim3d.features.size 

size(object, mask=None, threshold='otsu')

Calculates the maximum dimension (size) of the object's bounding box.

This function determines the largest spatial extent of the object along the Cartesian axes (X, Y, Z). It computes the Axis-Aligned Bounding Box (AABB) enclosing the structure and returns the length of its longest side. This metric is useful for characterizing the overall scale, fitting constraints, or the maximum caliper diameter along orthogonal axes.

Parameters:

Name Type Description Default
object ndarray or Manifold

The input data. Can be a 3D NumPy array (volume) or a pygel3d.hmesh.Manifold object (mesh).

 required
mask ndarray

A boolean mask defining a Region of Interest (ROI). Only the data within this mask is considered. Must have the same shape as object. Defaults to None.

 None
threshold float or str

The intensity value used to binarize the volume if a NumPy array is provided.

  • float: A specific intensity value.
  • 'otsu': Automatically calculates the threshold using Otsu's method. Defaults to 'otsu'.
 'otsu'

Returns:

Name Type Description
size float

The length of the largest side of the enclosing bounding box.

Raises:

Type Description
ValueError

If mask is provided but its shape does not match the input object.
Example 

import qim3d

# Generate a synthetic object
synthetic_object = qim3d.generate.volume(
    final_shape=(100,30,30),
    noise_scale=0.008,
    shape="cylinder"
    )

# Compute size of the object
size = qim3d.features.size(synthetic_object)
print(f"Size: {size}")

# Visualize the synthetic object
qim3d.viz.volumetric(synthetic_object)
Size: 100.0

Source code in qim3d/features/_common_features_methods.py 
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
def size(
    object: np.ndarray | hmesh.Manifold,
    mask: np.ndarray | None = None,
    threshold: float | str = 'otsu',
) -> float:
    """
    Calculates the maximum dimension (size) of the object's bounding box.

    This function determines the largest spatial extent of the object along the Cartesian axes (X, Y, Z). It computes the Axis-Aligned Bounding Box (AABB) enclosing the structure and returns the length of its longest side. This metric is useful for characterizing the overall scale, fitting constraints, or the maximum caliper diameter along orthogonal axes.

    Args:
        object (np.ndarray or hmesh.Manifold): The input data. Can be a 3D NumPy array (volume) or a `pygel3d.hmesh.Manifold` object (mesh).
        mask (np.ndarray, optional): A boolean mask defining a Region of Interest (ROI). Only the data within this mask is considered. Must have the same shape as `object`. Defaults to `None`.
        threshold (float or str, optional): The intensity value used to binarize the volume if a NumPy array is provided.

            * **float**: A specific intensity value.
            * **'otsu'**: Automatically calculates the threshold using Otsu's method. Defaults to 'otsu'.

    Returns:
        size (float):
            The length of the largest side of the enclosing bounding box.

    Raises:
        ValueError: If `mask` is provided but its shape does not match the input `object`.

    Example:
        ```python
        import qim3d

        # Generate a synthetic object
        synthetic_object = qim3d.generate.volume(
            final_shape=(100,30,30),
            noise_scale=0.008,
            shape="cylinder"
            )

        # Compute size of the object
        size = qim3d.features.size(synthetic_object)
        print(f"Size: {size}")

        # Visualize the synthetic object
        qim3d.viz.volumetric(synthetic_object)
        ```
        Size: 100.0
        <iframe src="https://platform.qim.dk/k3d/size_feature_example.html" width="100%" height="500" frameborder="0"></iframe>
    """
    # Prepare object
    mesh = prepare_obj(object, threshold=threshold, mask=mask, return_mesh=True)

    # Min and max corners of the bounding box
    bbox = hmesh.bbox(mesh)
    mins, maxs = bbox

    # Maximum side length of the bounding box
    side_lengths = maxs - mins
    size = np.max(side_lengths)

    return size

qim3d.features.sphericity 

sphericity(object, mask=None, threshold='otsu')

Computes the sphericity (compactness) of a 3D object.

Sphericity is a measure of how closely the shape of an object resembles a perfect sphere. It is defined as the ratio of the surface area of a sphere (with the same volume as the given object) to the actual surface area of the object. This morphological descriptor is widely used in particle analysis, geology, and biology to quantify roundness and regularity.

  • 1.0: Indicates a perfect sphere.
  • < 1.0: Indicates irregular, elongated, or rough shapes (e.g., a cube has a sphericity of approx. 0.806).

Parameters:

Name Type Description Default
object ndarray or Manifold

The input data. Can be a 3D NumPy array (volume) or a pygel3d.hmesh.Manifold object (mesh).

 required
mask ndarray

A boolean mask defining a Region of Interest (ROI). Only the data within this mask is considered. Must have the same shape as object. Defaults to None.

 None
threshold float or str

The intensity value used to binarize the volume if a NumPy array is provided.

  • float: A specific intensity value.
  • 'otsu': Automatically calculates the threshold using Otsu's method. Defaults to 'otsu'.
 'otsu'

Returns:

Name Type Description
sphericity float

The calculated sphericity value (unitless, max 1.0). Returns nan if the object has zero volume or area.

Raises:

Type Description
ValueError

If mask is provided but its shape does not match the input object.
Example 

import qim3d

# Generate a synthetic object
synthetic_object = qim3d.generate.volume(noise_scale=0.005)

# Compute the sphericity of the object
sphericity = qim3d.features.sphericity(synthetic_object)
print(f"Sphericity: {sphericity:.4f}")

# Visualize the synthetic object
qim3d.viz.volumetric(synthetic_object)
Sphericity: 0.9058

Example 

import qim3d

# Generate a synthetic object
synthetic_object = qim3d.generate.volume(noise_scale=0.008)

# Manipulate the object
synthetic_object = qim3d.operations.stretch(synthetic_object, z_stretch=50)
synthetic_object = qim3d.operations.curve_warp(synthetic_object, x_amp=10, x_periods=4)

# Compute the sphericity of the object
sphericity = qim3d.features.sphericity(synthetic_object)
print(f"Sphericity: {sphericity:.4f}")

# Visualize the synthetic object
qim3d.viz.volumetric(synthetic_object)
Sphericity: 0.6876

Source code in qim3d/features/_common_features_methods.py 
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
def sphericity(
    object: np.ndarray | hmesh.Manifold,
    mask: np.ndarray | None = None,
    threshold: float | str = 'otsu',
) -> float:
    """
    Computes the sphericity (compactness) of a 3D object.

    Sphericity is a measure of how closely the shape of an object resembles a perfect sphere. It is defined as the ratio of the surface area of a sphere (with the same volume as the given object) to the actual surface area of the object. This morphological descriptor is widely used in particle analysis, geology, and biology to quantify roundness and regularity.

    * **1.0**: Indicates a perfect sphere.
    * **< 1.0**: Indicates irregular, elongated, or rough shapes (e.g., a cube has a sphericity of approx. 0.806).

    Args:
        object (np.ndarray or hmesh.Manifold): The input data. Can be a 3D NumPy array (volume) or a `pygel3d.hmesh.Manifold` object (mesh).
        mask (np.ndarray, optional): A boolean mask defining a Region of Interest (ROI). Only the data within this mask is considered. Must have the same shape as `object`. Defaults to `None`.
        threshold (float or str, optional): The intensity value used to binarize the volume if a NumPy array is provided.

            * **float**: A specific intensity value.
            * **'otsu'**: Automatically calculates the threshold using Otsu's method. Defaults to 'otsu'.

    Returns:
        sphericity (float):
            The calculated sphericity value (unitless, max 1.0). Returns `nan` if the object has zero volume or area.

    Raises:
        ValueError: If `mask` is provided but its shape does not match the input `object`.

    Example:
        ```python
        import qim3d

        # Generate a synthetic object
        synthetic_object = qim3d.generate.volume(noise_scale=0.005)

        # Compute the sphericity of the object
        sphericity = qim3d.features.sphericity(synthetic_object)
        print(f"Sphericity: {sphericity:.4f}")

        # Visualize the synthetic object
        qim3d.viz.volumetric(synthetic_object)
        ```
        Sphericity: 0.9058
        <iframe src="https://platform.qim.dk/k3d/sphericity_feature_example_2.html" width="100%" height="500" frameborder="0"></iframe>

    Example:
        ```python
        import qim3d

        # Generate a synthetic object
        synthetic_object = qim3d.generate.volume(noise_scale=0.008)

        # Manipulate the object
        synthetic_object = qim3d.operations.stretch(synthetic_object, z_stretch=50)
        synthetic_object = qim3d.operations.curve_warp(synthetic_object, x_amp=10, x_periods=4)

        # Compute the sphericity of the object
        sphericity = qim3d.features.sphericity(synthetic_object)
        print(f"Sphericity: {sphericity:.4f}")

        # Visualize the synthetic object
        qim3d.viz.volumetric(synthetic_object)
        ```
        Sphericity: 0.6876
        <iframe src="https://platform.qim.dk/k3d/sphericity_feature_example_1.html" width="100%" height="500" frameborder="0"></iframe>
    """
    # Prepare object
    mesh = prepare_obj(object, threshold=threshold, mask=mask, return_mesh=True)

    # Compute surface area and volume
    area = qim3d.features.area(mesh)
    volume = qim3d.features.volume(mesh)

    if area == 0 or volume == 0:
        log.warning('Surface area or volume is zero, sphericity is undefined.')
        return np.nan

    # Compute sphericity
    sphericity = (np.pi ** (1 / 3) * (6 * volume) ** (2 / 3)) / area

    return sphericity

qim3d.features.roughness 

roughness(object, mask=None, threshold='otsu')

Computes the roughness (Surface-Area-to-Volume ratio) of a 3D object.

This feature quantifies the morphological complexity of an object. Unlike a simple measure of size, this ratio indicates how "folded", "spiky", or "porous" a structure is relative to its mass. A perfect sphere has the lowest possible surface-to-volume ratio (smoothest), while highly complex shapes like fractals, trabecular bone, or dendrites will have a much higher value. This metric is often used to analyze texture and surface irregularity.

Parameters:

Name Type Description Default
object ndarray or Manifold

The input data. Can be a 3D NumPy array (volume) or a pygel3d.hmesh.Manifold object (mesh).

 required
mask ndarray

A boolean mask defining a Region of Interest (ROI). Only the data within this mask is considered. Must have the same shape as object. Defaults to None.

 None
threshold float or str

The intensity value used to binarize the volume if a NumPy array is provided.

  • float: A specific intensity value.
  • 'otsu': Automatically calculates the threshold using Otsu's method. Defaults to 'otsu'.
 'otsu'

Returns:

Name Type Description
roughness float

The calculated ratio of Surface Area / Volume. Returns nan if the object has zero volume or area.

Raises:

Type Description
ValueError

If mask is provided but its shape does not match the input object.
Example 

import qim3d

# Generate a synthetic object
synthetic_object = qim3d.generate.volume(
    base_shape=(128,128,128),
    noise_scale=0.019,
    )

# Compute the roughness of the object
roughness = qim3d.features.roughness(synthetic_object)
print(f"Roughness: {roughness:.4f}")

# Visualize the synthetic object
qim3d.viz.volumetric(synthetic_object)
Roughness: 0.1005

Example 

import qim3d

# Generate a synthetic object
synthetic_object = qim3d.generate.volume(
    base_shape=(128,128,128),
    noise_scale=0.08,
    decay_rate=18,
    gamma=0.9,
    )

# Compute the roughness of the object
roughness = qim3d.features.roughness(synthetic_object)
print(f"Roughness: {roughness:.4f}")

# Visualize the synthetic object
qim3d.viz.volumetric(synthetic_object)
Roughness: 0.2534

Source code in qim3d/features/_common_features_methods.py 
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
def roughness(
    object: np.ndarray | hmesh.Manifold,
    mask: np.ndarray | None = None,
    threshold: float | str = 'otsu',
) -> float:
    """
    Computes the roughness (Surface-Area-to-Volume ratio) of a 3D object.

    This feature quantifies the morphological complexity of an object. Unlike a simple measure of size, this ratio indicates how "folded", "spiky", or "porous" a structure is relative to its mass. A perfect sphere has the lowest possible surface-to-volume ratio (smoothest), while highly complex shapes like fractals, trabecular bone, or dendrites will have a much higher value. This metric is often used to analyze texture and surface irregularity.

    Args:
        object (np.ndarray or hmesh.Manifold): The input data. Can be a 3D NumPy array (volume) or a `pygel3d.hmesh.Manifold` object (mesh).
        mask (np.ndarray, optional): A boolean mask defining a Region of Interest (ROI). Only the data within this mask is considered. Must have the same shape as `object`. Defaults to `None`.
        threshold (float or str, optional): The intensity value used to binarize the volume if a NumPy array is provided.

            * **float**: A specific intensity value.
            * **'otsu'**: Automatically calculates the threshold using Otsu's method. Defaults to 'otsu'.

    Returns:
        roughness (float):
            The calculated ratio of Surface Area / Volume. Returns `nan` if the object has zero volume or area.

    Raises:
        ValueError: If `mask` is provided but its shape does not match the input `object`.

    Example:
        ```python
        import qim3d

        # Generate a synthetic object
        synthetic_object = qim3d.generate.volume(
            base_shape=(128,128,128),
            noise_scale=0.019,
            )

        # Compute the roughness of the object
        roughness = qim3d.features.roughness(synthetic_object)
        print(f"Roughness: {roughness:.4f}")

        # Visualize the synthetic object
        qim3d.viz.volumetric(synthetic_object)
        ```
        Roughness: 0.1005
        <iframe src="https://platform.qim.dk/k3d/roughness_feature_example_v1.html" width="100%" height="500" frameborder="0"></iframe>

    Example:
        ```python
        import qim3d

        # Generate a synthetic object
        synthetic_object = qim3d.generate.volume(
            base_shape=(128,128,128),
            noise_scale=0.08,
            decay_rate=18,
            gamma=0.9,
            )

        # Compute the roughness of the object
        roughness = qim3d.features.roughness(synthetic_object)
        print(f"Roughness: {roughness:.4f}")

        # Visualize the synthetic object
        qim3d.viz.volumetric(synthetic_object)
        ```
        Roughness: 0.2534
        <iframe src="https://platform.qim.dk/k3d/roughness_feature_example_v2.html" width="100%" height="500" frameborder="0"></iframe>
    """
    # Prepare object
    mesh = prepare_obj(object, threshold=threshold, mask=mask, return_mesh=True)

    # Compute surface area and volume
    area = qim3d.features.area(mesh)
    volume = qim3d.features.volume(mesh)

    if area == 0 or volume == 0:
        log.warning('Surface area or volume is zero, roughness is undefined.')
        return np.nan

    # Compute roughness
    roughness = area / volume

    return roughness

qim3d.features.mean_std_intensity 

mean_std_intensity(volume, mask=None)

Calculates the mean (average) and standard deviation of voxel intensities within a volume.

This function computes global image statistics, which are fundamental for tasks like data normalization (z-score), contrast analysis, and quality control. By default, it ignores zero-valued voxels (background) to ensure the statistics reflect the actual object or signal rather than the empty space around it. You can further restrict the calculation to a specific Region of Interest (ROI) using a binary mask.

Parameters:

Name Type Description Default
volume ndarray

The input 3D image stack (voxel data).

 required
mask ndarray

A boolean mask defining a specific region to analyze. Only voxels where mask=True are included. Must match the shape of volume. Defaults to None.

 None

Returns:

Name Type Description
stats tuple[float, float]

A tuple containing (mean, std_dev).

  • mean: The average intensity value of the non-zero voxels.
  • std_dev: The standard deviation of the intensity values.

Raises:

Type Description
ValueError

If mask is provided but does not match the shape of volume.
Note

This function automatically filters out background values (intensities equal to 0) before calculation.

Example 

import qim3d

# Load a sample object
shell_object = qim3d.examples.shell_225x128x128

# Compute mean and standard deviation of intensities in the object
mean_intensity, std_intensity = qim3d.features.mean_std_intensity(shell_object)
print(f"Mean intensity: {mean_intensity:.4f}")
print(f"Standard deviation of intensity: {std_intensity:.4f}")

# Visualize slices of the object
qim3d.viz.slices_grid(shell_object, color_bar=True, color_bar_style="large")
Mean intensity: 114.6734
Standard deviation of intensity: 45.8481 mean_std_intensity_feature

Source code in qim3d/features/_common_features_methods.py 
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
def mean_std_intensity(
    volume: np.ndarray,
    mask: np.ndarray | None = None,
) -> tuple[float, float]:
    """
    Calculates the mean (average) and standard deviation of voxel intensities within a volume.

    This function computes global image statistics, which are fundamental for tasks like data normalization (z-score), contrast analysis, and quality control. By default, it ignores zero-valued voxels (background) to ensure the statistics reflect the actual object or signal rather than the empty space around it. You can further restrict the calculation to a specific Region of Interest (ROI) using a binary mask.

    Args:
        volume (np.ndarray): The input 3D image stack (voxel data).
        mask (np.ndarray, optional): A boolean mask defining a specific region to analyze. Only voxels where `mask=True` are included. Must match the shape of `volume`. Defaults to `None`.

    Returns:
        stats (tuple[float, float]):
            A tuple containing `(mean, std_dev)`.

            * **mean**: The average intensity value of the non-zero voxels.
            * **std_dev**: The standard deviation of the intensity values.

    Raises:
        ValueError: If `mask` is provided but does not match the shape of `volume`.

    Note:
        This function automatically filters out background values (intensities equal to 0) before calculation.

    Example:
        ```python
        import qim3d

        # Load a sample object
        shell_object = qim3d.examples.shell_225x128x128

        # Compute mean and standard deviation of intensities in the object
        mean_intensity, std_intensity = qim3d.features.mean_std_intensity(shell_object)
        print(f"Mean intensity: {mean_intensity:.4f}")
        print(f"Standard deviation of intensity: {std_intensity:.4f}")

        # Visualize slices of the object
        qim3d.viz.slices_grid(shell_object, color_bar=True, color_bar_style="large")
        ```
        Mean intensity: 114.6734  
        Standard deviation of intensity: 45.8481
        ![mean_std_intensity_feature](../../assets/screenshots/mean_std_intensity_feature_example.png)
    """

    # Mask the volume (if provided)
    volume = prepare_obj(volume, threshold=None, mask=mask, return_mesh=False)

    # Get only the non-zero intensities (i.e., ignoring the background)
    intensities = volume[volume > 0]

    # Compute mean and standard deviation
    mean_intensity = np.mean(intensities)
    std_intensity = np.std(intensities)

    return mean_intensity, std_intensity