The VoxelImage class#

class rockverse.voxel_image.VoxelImage(_async_array: AsyncArray[ArrayV3Metadata] | AsyncArray[ArrayV2Metadata])[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

Returns the shape 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

Inherited Zarr attributes summary

attrs

Returns 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

The shape of the chunk grid for this array.

chunks

Returns a tuple of integers describing the length of each dimension of a chunk of the array.

compressor

Compressor that is applied to each chunk of the array.

dtype

Returns the NumPy data type.

fill_value

filters

Filters that are applied to each chunk of the array, in order, before serializing that chunk to bytes.

info

Return the statically known information for an array.

name

Array name following h5py convention.

nbytes

The total number of bytes that can be stored in the chunks of this array.

nbytes_stored()

Determine the size, in bytes, of the array actually written to the store.

nchunks

The number of chunks in the stored representation of this array.

nchunks_initialized

Calculate the number of chunks that have been initialized, i.e. the number of chunks that have been persisted to the storage backend.

ndim

Returns the number of dimensions in the array.

oindex

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

order

path

Storage path.

read_only

size

Returns the total number of elements in the array.

store

vindex

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

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#

Returns the shape of the array.

Returns:

The shape of the array.

Return type:

ChunkCoords

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#

Returns a MutableMapping containing user-defined attributes.

Returns:

attrs – A MutableMapping object containing user-defined attributes.

Return type:

MutableMapping

Notes

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#

The shape of the chunk grid for this array.

chunks#

Returns a tuple of integers describing the length of each dimension of a chunk of the array. If sharding is used the inner chunk shape is returned.

Only defined for arrays using using RegularChunkGrid. If array doesn’t use RegularChunkGrid, NotImplementedError is raised.

Returns:

A tuple of integers representing the length of each dimension of a chunk.

Return type:

tuple

compressor#

Compressor that is applied to each chunk of the array.

Deprecated since version 3.0.0: array.compressor is deprecated and will be removed in a future release. Use array.compressors instead.

dtype#

Returns the NumPy data type.

Returns:

The NumPy data type.

Return type:

np.dtype

fill_value#
filters#

Filters that are applied to each chunk of the array, in order, before serializing that chunk to bytes.

info#

Return the statically known information for an array.

Return type:

ArrayInfo

See also

Array.info_complete

All information about a group, including dynamic information like the number of bytes and chunks written.

Examples

>>> arr = zarr.create(shape=(10,), chunks=(2,), dtype="float32")
>>> arr.info
Type               : Array
Zarr format        : 3
Data type          : DataType.float32
Shape              : (10,)
Chunk shape        : (2,)
Order              : C
Read-only          : False
Store type         : MemoryStore
Codecs             : [BytesCodec(endian=<Endian.little: 'little'>)]
No. bytes          : 40
name#

Array name following h5py convention.

nbytes#

The total number of bytes that can be stored in the chunks of this array.

Notes

This value is calculated by multiplying the number of elements in the array and the size of each element, the latter of which is determined by the dtype of the array. For this reason, nbytes will likely be inaccurate for arrays with variable-length dtypes. It is not possible to determine the size of an array with variable-length elements from the shape and dtype alone.

nbytes_stored = <function Array.nbytes_stored>#
nchunks#

The number of chunks in the stored representation of this array.

nchunks_initialized#

Calculate the number of chunks that have been initialized, i.e. the number of chunks that have been persisted to the storage backend.

Returns:

nchunks_initialized – The number of chunks that have been initialized.

Return type:

int

Notes

On Array this is a (synchronous) property, unlike asynchronous function AsyncArray.nchunks_initialized().

Examples

>>> arr = await zarr.create(shape=(10,), chunks=(2,))
>>> arr.nchunks_initialized
0
>>> arr[:5] = 1
>>> arr.nchunks_initialized
3
ndim#

Returns the number of dimensions in the array.

Returns:

The number of dimensions in the array.

Return type:

int

oindex#

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

order#
path#

Storage path.

read_only#
size#

Returns the total number of elements in the array.

Returns:

Total number of elements in the array.

Return type:

int

store#
vindex#

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