Skip to content

Feature extraction

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

qim3d.features

qim3d.features.area 

area(obj, **mesh_kwargs)

Compute the surface area of a 3D volume or mesh.

Parameters:

Name Type Description Default
obj ndarray or Trimesh

Either a np.ndarray volume or a mesh object of type trimesh.Trimesh.

 required
**mesh_kwargs Any

Additional arguments for mesh creation if the input is a volume.

 {}

Returns:

Name Type Description
area float

The surface area of the object.
Example

Compute area from a mesh: 

import qim3d

# Load a mesh from a file
mesh = qim3d.io.load_mesh('path/to/mesh.obj')

# Compute the surface area of the mesh
area = qim3d.features.area(mesh)
area = qim3d.features.area(mesh)
print(f"Area: {area}")

Compute area from a np.ndarray: 

import qim3d

# Generate a 3D blob
synthetic_blob = qim3d.generate.noise_object(noise_scale = 0.015)
synthetic_blob = qim3d.generate.noise_object(noise_scale = 0.015)

# Compute the surface area of the blob
volume = qim3d.features.area(synthetic_blob, level=0.5)
volume = qim3d.features.area(synthetic_blob, level=0.5)
print('Area:', volume)

Source code in qim3d/features/_common_features_methods.py 
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 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
def area(obj: np.ndarray|trimesh.Trimesh, 
         **mesh_kwargs
         ) -> float:
    """
    Compute the surface area of a 3D volume or mesh.

    Args:
        obj (np.ndarray or trimesh.Trimesh): Either a np.ndarray volume or a mesh object of type trimesh.Trimesh.
        **mesh_kwargs (Any): Additional arguments for mesh creation if the input is a volume.

    Returns:
        area (float): The surface area of the object.

    Example:
        Compute area from a mesh:
        ```python
        import qim3d

        # Load a mesh from a file
        mesh = qim3d.io.load_mesh('path/to/mesh.obj')

        # Compute the surface area of the mesh
        area = qim3d.features.area(mesh)
        area = qim3d.features.area(mesh)
        print(f"Area: {area}")
        ```

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

        # Generate a 3D blob
        synthetic_blob = qim3d.generate.noise_object(noise_scale = 0.015)
        synthetic_blob = qim3d.generate.noise_object(noise_scale = 0.015)

        # Compute the surface area of the blob
        volume = qim3d.features.area(synthetic_blob, level=0.5)
        volume = qim3d.features.area(synthetic_blob, level=0.5)
        print('Area:', volume)
        ```
    """
    if isinstance(obj, np.ndarray):
        log.info("Converting volume to mesh.")
        obj = qim3d.mesh.from_volume(obj, **mesh_kwargs)
        obj = qim3d.mesh.from_volume(obj, **mesh_kwargs)

    return obj.area

qim3d.features.volume 

volume(obj, **mesh_kwargs)

Compute the volume of a 3D volume or mesh.

Parameters:

Name Type Description Default
obj ndarray or Trimesh

Either a np.ndarray volume or a mesh object of type trimesh.Trimesh.

 required
**mesh_kwargs Any

Additional arguments for mesh creation if the input is a volume.

 {}

Returns:

Name Type Description
volume float

The volume of the object.
Example

Compute volume from a mesh: 

import qim3d

# Load a mesh from a file
mesh = qim3d.io.load_mesh('path/to/mesh.obj')

# Compute the volume of the mesh
vol = qim3d.features.volume(mesh)
print('Volume:', vol)

Compute volume from a np.ndarray: 

import qim3d

# Generate a 3D blob
synthetic_blob = qim3d.generate.noise_object(noise_scale = 0.015)
synthetic_blob = qim3d.generate.noise_object(noise_scale = 0.015)

# Compute the volume of the blob
volume = qim3d.features.volume(synthetic_blob, level=0.5)
volume = qim3d.features.volume(synthetic_blob, level=0.5)
print('Volume:', volume)

Source code in qim3d/features/_common_features_methods.py 
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
def volume(obj: np.ndarray|trimesh.Trimesh, 
           **mesh_kwargs
           ) -> float:
    """
    Compute the volume of a 3D volume or mesh.

    Args:
        obj (np.ndarray or trimesh.Trimesh): Either a np.ndarray volume or a mesh object of type trimesh.Trimesh.
        **mesh_kwargs (Any): Additional arguments for mesh creation if the input is a volume.

    Returns:
        volume (float): The volume of the object.

    Example:
        Compute volume from a mesh:
        ```python
        import qim3d

        # Load a mesh from a file
        mesh = qim3d.io.load_mesh('path/to/mesh.obj')

        # Compute the volume of the mesh
        vol = qim3d.features.volume(mesh)
        print('Volume:', vol)
        ```

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

        # Generate a 3D blob
        synthetic_blob = qim3d.generate.noise_object(noise_scale = 0.015)
        synthetic_blob = qim3d.generate.noise_object(noise_scale = 0.015)

        # Compute the volume of the blob
        volume = qim3d.features.volume(synthetic_blob, level=0.5)
        volume = qim3d.features.volume(synthetic_blob, level=0.5)
        print('Volume:', volume)
        ```

    """
    if isinstance(obj, np.ndarray):
        log.info("Converting volume to mesh.")
        obj = qim3d.mesh.from_volume(obj, **mesh_kwargs)

    return obj.volume

qim3d.features.sphericity 

sphericity(obj, **mesh_kwargs)

Compute the sphericity of a 3D volume or mesh.

Sphericity is a measure of how spherical an object is. It is defined as the ratio of the surface area of a sphere with the same volume as the object to the object's actual surface area.

Parameters:

Name Type Description Default
obj ndarray or Trimesh

Either a np.ndarray volume or a mesh object of type trimesh.Trimesh.

 required
**mesh_kwargs Any

Additional arguments for mesh creation if the input is a volume.

 {}

Returns:

Name Type Description
sphericity float

A float value representing the sphericity of the object.
Example

Compute sphericity from a mesh: 

import qim3d

# Load a mesh from a file
mesh = qim3d.io.load_mesh('path/to/mesh.obj')

# Compute the sphericity of the mesh
sphericity = qim3d.features.sphericity(mesh)
sphericity = qim3d.features.sphericity(mesh)

Compute sphericity from a np.ndarray: 

import qim3d

# Generate a 3D blob
synthetic_blob = qim3d.generate.noise_object(noise_scale = 0.015)
synthetic_blob = qim3d.generate.noise_object(noise_scale = 0.015)

# Compute the sphericity of the blob
sphericity = qim3d.features.sphericity(synthetic_blob, level=0.5)
sphericity = qim3d.features.sphericity(synthetic_blob, level=0.5)

Limitations due to pixelation

Sphericity is particularly sensitive to the resolution of the mesh, as it directly impacts the accuracy of surface area and volume calculations. Since the mesh is generated from voxel-based 3D volume data, the discrete nature of the voxels leads to pixelation effects that reduce the precision of sphericity measurements. Higher resolution meshes may mitigate these errors but often at the cost of increased computational demands.

Source code in qim3d/features/_common_features_methods.py 
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
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
def sphericity(obj: np.ndarray|trimesh.Trimesh, 
               **mesh_kwargs
               ) -> float:
    """
    Compute the sphericity of a 3D volume or mesh.

    Sphericity is a measure of how spherical an object is. It is defined as the ratio
    of the surface area of a sphere with the same volume as the object to the object's
    actual surface area.

    Args:
        obj (np.ndarray or trimesh.Trimesh): Either a np.ndarray volume or a mesh object of type trimesh.Trimesh.
        **mesh_kwargs (Any): Additional arguments for mesh creation if the input is a volume.

    Returns:
        sphericity (float): A float value representing the sphericity of the object.

    Example:
        Compute sphericity from a mesh:
        ```python
        import qim3d

        # Load a mesh from a file
        mesh = qim3d.io.load_mesh('path/to/mesh.obj')

        # Compute the sphericity of the mesh
        sphericity = qim3d.features.sphericity(mesh)
        sphericity = qim3d.features.sphericity(mesh)
        ```

        Compute sphericity from a np.ndarray:
        ```python
        import qim3d

        # Generate a 3D blob
        synthetic_blob = qim3d.generate.noise_object(noise_scale = 0.015)
        synthetic_blob = qim3d.generate.noise_object(noise_scale = 0.015)

        # Compute the sphericity of the blob
        sphericity = qim3d.features.sphericity(synthetic_blob, level=0.5)
        sphericity = qim3d.features.sphericity(synthetic_blob, level=0.5)
        ```

    !!! info "Limitations due to pixelation"
        Sphericity is particularly sensitive to the resolution of the mesh, as it directly impacts the accuracy of surface area and volume calculations.
        Since the mesh is generated from voxel-based 3D volume data, the discrete nature of the voxels leads to pixelation effects that reduce the precision of sphericity measurements.
        Higher resolution meshes may mitigate these errors but often at the cost of increased computational demands.
    """
    if isinstance(obj, np.ndarray):
        log.info("Converting volume to mesh.")
        obj = qim3d.mesh.from_volume(obj, **mesh_kwargs)
        obj = qim3d.mesh.from_volume(obj, **mesh_kwargs)

    volume = qim3d.features.volume(obj)
    area = qim3d.features.area(obj)
    volume = qim3d.features.volume(obj)
    area = qim3d.features.area(obj)

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

    sphericity = (np.pi ** (1 / 3) * (6 * volume) ** (2 / 3)) / area
    log.info(f"Sphericity: {sphericity}")
    return sphericity