The VoxelImage class#

class rockverse.voxel_image.VoxelImage(store: Any, path=None, read_only=False, chunk_store=None, synchronizer=None, cache_metadata=True, cache_attrs=True, partial_decompress=False, write_empty_chunks=True, zarr_version=None, meta_array=None)[source]#

The basic type for RockVerse Digital Rock Petrophysics, intended to contain voxelized images and scalar fields in general. The class builds upon Zarr arrays by adding attributes and methods specifically designed for digital rock petrophysics in a high performance parallel computing environment.

Note

This class should not be instantiated directly. Instead, use the provided creation functions.

Digital rock attributes summary

`description`	Image or scalar field description.
`field_name`	Name for the stored scalar field.
`field_unit`	Unit for the stored scalar field.
`nx`	The number of voxels in x-direction (first axis).
`ny`	The number of voxels in y-direction (second axis).
`nz`	The number of voxels in z-direction (third axis).
`shape`	A tuple of integers describing the length of each dimension of the array.
`hx`	Voxel length in x-direction (first axis).
`hy`	Voxel length in y-direction (second axis).
`hz`	Voxel length in z-direction (third axis).
`voxel_length`	Returns the image voxel length in each spatial direction (x, y, z) as a tuple.
`dimensions`	Image total dimension in each direction.
`h_unit`	Image voxel unit.
`voxel_unit`	Image voxel unit.
`ox`	Spatial x-coordinate for the first voxel in x-direction (first axis).
`oy`	Spatial y-coordinate for the first voxel in y-direction (second axis).
`oz`	Spatial z-coordinate for the first voxel in z-direction (third axis).
`voxel_origin`	Image voxel origin for each direction.
`bounding_box`	Image bounding box in voxel units.
`meta_data_as_dict`	Return voxel image meta data as a dictionary.

Basic methods summary

`chunk_slice_indices`(chunk_id)	Calculate the slice indices for a given Zarr chunk.
`get_voxel_coordinates`(i, j, k)	Get the spatial coordinates of the voxel at a given position.
`get_closest_voxel_index`(x, y, z[, allow_outside])	Get the voxel index closest to a given spatial position.
`check_mask_and_segmentation`(*[, mask, ...])	Validate mask and segmentation compatibility.
`create_mask_from_region`(region, **kwargs)	Parallel CPU GPU Create a mask voxel image.

Inherited Zarr attributes summary

`attrs`	A MutableMapping containing user-defined attributes.
`basename`	Final component of name.
`blocks`	Shortcut for blocked chunked indexing, see `get_block_selection()` and `set_block_selection()` for documentation and examples.
`cdata_shape`	A tuple of integers describing the number of chunks along each dimension of the array.
`chunk_store`	A MutableMapping providing the underlying storage for array chunks.
`chunks`	A tuple of integers describing the length of each dimension of a chunk of the array.
`compressor`	Primary compression codec.
`dtype`	The NumPy data type.
`fill_value`	A value used for uninitialized portions of the array.
`filters`	One or more codecs used to transform data prior to compression.
`info`	Report some diagnostic information about the array.
`initialized`	The number of chunks that have been initialized with some data.
`is_view`	A boolean, True if this array is a view on another array.
`itemsize`	The size in bytes of each item in the array.
`meta_array`	An array-like instance to use for determining arrays to create and return to users.
`name`	Array name following h5py convention.
`nbytes`	The total number of bytes that would be required to store the array without compression.
`nbytes_stored`	The total number of stored bytes of data for the array.
`nchunks`	Total number of chunks.
`nchunks_initialized`	The number of chunks that have been initialized with some data.
`ndim`	Number of dimensions.
`oindex`	Shortcut for orthogonal (outer) indexing, see `get_orthogonal_selection()` and `set_orthogonal_selection()` for documentation and examples.
`order`	A string indicating the order in which bytes are arranged within chunks of the array.
`path`	Storage path.
`read_only`	A boolean, True if modification operations are not permitted.
`size`	The total number of elements in the array.
`store`	A MutableMapping providing the underlying storage for the array.
`synchronizer`	Object used to synchronize write access to the array.
`vindex`	Shortcut for vectorized (inner) indexing, see `get_coordinate_selection()`, `set_coordinate_selection()`, `get_mask_selection()` and `set_mask_selection()` for documentation and examples.
`write_empty_chunks`	A Boolean, True if chunks composed of the array's fill value will be stored.

Digital rock attributes documentation

description#: Image or scalar field description.

field_name#: Name for the stored scalar field.

field_unit#: Unit for the stored scalar field.

nx#: The number of voxels in x-direction (first axis). Equivalent to shape[0].

ny#: The number of voxels in y-direction (second axis). Equivalent to shape[1].

nz#: The number of voxels in z-direction (third axis). Equivalent to shape[2].

shape#: A tuple of integers describing the length of each dimension of the array.

hx#: Voxel length in x-direction (first axis).

hy#: Voxel length in y-direction (second axis).

hz#: Voxel length in z-direction (third axis).

voxel_length#: Returns the image voxel length in each spatial direction (x, y, z) as a tuple. This is a read-only property. To alter the voxel lengths, use the hx, hy, and hz properties.

dimensions#

Image total dimension in each direction.

Returns the total physical dimensions of the image by multiplying the number of voxels by the voxel length in each spatial direction (x, y, z).

h_unit#: Image voxel unit.

voxel_unit#: Image voxel unit.

ox#: Spatial x-coordinate for the first voxel in x-direction (first axis).

oy#: Spatial y-coordinate for the first voxel in y-direction (second axis).

oz#: Spatial z-coordinate for the first voxel in z-direction (third axis).

voxel_origin#

Image voxel origin for each direction.

Returns the spatial coordinate origin for the first voxel in the array in each spatial direction (x, y, z) as a tuple. This is a read-only property. To alter the voxel origins, use the ox, oy, and oz properties.

bounding_box#

Image bounding box in voxel units.

Returns the image bounding box, defined by the minimum and maximum voxel coordinates in each spatial direction (x, y, z). The bounding box is calculated based on the voxel origins and lengths.

Returns:: A tuple containing two tuples: ((xmin, ymin, zmin), (xmax, ymax, zmax)), namely the minimum and maximum coordinates in the x, y, and z directions.
Return type:: tuple

meta_data_as_dict#: Return voxel image meta data as a dictionary.

Basic methods documentation

chunk_slice_indices(chunk_id)[source]#

Calculate the slice indices for a given Zarr chunk.

This method computes the first and last+1 indices for a specific Zarr chunk within the array, based on the block’s ID. Useful for working with chunked data in parallel processing.

Parameters:: chunk_id (int) – The ID of the block for which to calculate the slice indices.
Returns:: A tuple containing six integers: (box, bex, boy, bey, boz, bez). These represent the start and end indices for the block in the x, y, and z directions, respectively.
Return type:: tuple

get_voxel_coordinates(i, j, k)[source]#

Get the spatial coordinates of the voxel at a given position.

This method calculates the spatial coordinates of the voxel located at the specified (i, j, k) position, taking into account the voxel origin and voxel length.

Parameters:

i (int) – The voxel index in the x-direction, 0 <= i < nx.
j (int) – The voxel index in the y-direction, 0 <= j < ny.
k (int) – The voxel index in the z-direction, 0 <= k < nz.

Returns:

A tuple containing the spatial coordinates (x, y, z) of the specified voxel.

Return type:

tuple

get_closest_voxel_index(x, y, z, allow_outside=False)[source]#

Get the voxel index closest to a given spatial position.

This method calculates the (i, j, k) indices of the image voxel closest to the specified spatial coordinates (x, y, z).

Parameters:

x (float) – The spatial coordinate in the x-direction.
y (float) – The spatial coordinate in the y-direction.
z (float) – The spatial coordinate in the z-direction.
allow_outside (Boolean) – If False (default) return None in case the spatial coordinates point to a region outside the image bounding box. If True, return the the voxel indices even if (x, y, z) falls outside the image bounding box.

Returns:

A tuple containing the voxel indices (i, j, k) corresponding to the specified spatial coordinates (x, y, z), or None.

Return type:

tuple or None

check_mask_and_segmentation(*, mask=None, segmentation=None)[source]#

Validate mask and segmentation compatibility.

This method checks the validity of the provided mask, segmentation, and phases to ensure they are compatible with the voxel image.

Parameters:

mask (VoxelImage, optional) – A mask voxel image. If provided, must be a voxel image of boolean dtype with the same shape, voxel length, voxel origin, and voxel unit.
segmentation (VoxelImage, optional) – A segmentation voxel image. If provided, must be a voxel image of boolean or unsigned integer dtype with the same shape, voxel length, voxel origin, and voxel unit.

Raises:

ValueError – If any of the provided parameters are invalid or incompatible with the current voxel image.

create_mask_from_region(region, **kwargs)[source]#

Parallel CPU GPU Create a mask voxel image.

Create boolean voxel image with same shape, chunks, voxel_origin, voxel_length, and voxel_unit as the original image, masking voxels outside the region of interest.

Parameters:

a (VoxelImage) – The source voxel image to mimic.
**kwargs – Additional keyword arguments to be passed to the underlying creation function. Keyword argument dtype will be ignored if passed, as the mask has to be of boolean type.

Returns:

The created VoxelImage object.

Return type:

VoxelImage

Inherited Zarr attributes documentation

attrs#: A MutableMapping containing user-defined attributes. Note that attribute values must be JSON serializable.

basename#: Final component of name.

blocks#: Shortcut for blocked chunked indexing, see get_block_selection() and set_block_selection() for documentation and examples.

cdata_shape#: A tuple of integers describing the number of chunks along each dimension of the array.

chunk_store#: A MutableMapping providing the underlying storage for array chunks.

chunks#: A tuple of integers describing the length of each dimension of a chunk of the array.

compressor#: Primary compression codec.

dtype#: The NumPy data type.

fill_value#: A value used for uninitialized portions of the array.

filters#: One or more codecs used to transform data prior to compression.

info#

Report some diagnostic information about the array.

Examples

>>> import zarr
>>> z = zarr.zeros(1000000, chunks=100000, dtype='i4')
>>> z.info
Type               : zarr.core.Array
Data type          : int32
Shape              : (1000000,)
Chunk shape        : (100000,)
Order              : C
Read-only          : False
Compressor         : Blosc(cname='lz4', clevel=5, shuffle=SHUFFLE, blocksize=0)
Store type         : zarr.storage.KVStore
No. bytes          : 4000000 (3.8M)
No. bytes stored   : 320
Storage ratio      : 12500.0
Chunks initialized : 0/10

initialized#: The number of chunks that have been initialized with some data.

is_view#: A boolean, True if this array is a view on another array.

itemsize#: The size in bytes of each item in the array.

meta_array#: An array-like instance to use for determining arrays to create and return to users.

name#: Array name following h5py convention.

nbytes#: The total number of bytes that would be required to store the array without compression.

nbytes_stored#: The total number of stored bytes of data for the array. This includes storage required for configuration metadata and user attributes.

nchunks#: Total number of chunks.

nchunks_initialized#: The number of chunks that have been initialized with some data.

ndim#: Number of dimensions.

oindex#: Shortcut for orthogonal (outer) indexing, see get_orthogonal_selection() and set_orthogonal_selection() for documentation and examples.

order#: A string indicating the order in which bytes are arranged within chunks of the array.

path#: Storage path.

read_only#: A boolean, True if modification operations are not permitted.

size#: The total number of elements in the array.

store#: A MutableMapping providing the underlying storage for the array.

synchronizer#: Object used to synchronize write access to the array.

vindex#: Shortcut for vectorized (inner) indexing, see get_coordinate_selection(), set_coordinate_selection(), get_mask_selection() and set_mask_selection() for documentation and examples.

write_empty_chunks#: A Boolean, True if chunks composed of the array’s fill value will be stored. If False, such chunks will not be stored.

The VoxelImage class#

This Page