Creation functions#

Creation functions adapt the Zarr creation functions to efficiently create VoxelImage objects in a parallel MPI execution environment across multiple CPU cores and GPUs.

rockverse.voxel_image.create(shape, dtype, chunks=True, store=None, overwrite=False, field_name='', field_unit='', description='', voxel_origin=None, voxel_length=None, voxel_unit='', **kwargs)[source]#

Parallel CPU

Create empty voxel image.

Parameters:

  • shape (tuple) – Desired image shape.

  • dtype (string or dtype) – NumPy dtype.

  • chunks (int or tuple of ints, optional) – Chunk shape. If True, will be guessed from shape and number of processes. If False, will be set to shape, i.e., single chunk for the whole array. Default is True.

  • store (Any, optional) – Any valid Zarr store.

  • overwrite (bool, optional) – If True, delete all pre-existing data in the store at the specified path before creating the new image. Default value is False.

  • field_name (str, optional) – Name for the stored image or scalar field.

  • field_unit (str, optional) – Unit for the stored image or scalar field.

  • description (str, optional) – Description for the stored image or scalar field.

  • voxel_origin (list or tuple, optional) – Image voxel coordinate origin in units of voxel_unit. This is the spatial coordinate for the voxel with lowest (x, y, z) coordinates. If None, defaults to a tuple of zeros for each image dimension.

  • voxel_length (list or tuple, optional) – Image voxel length in each dimension. If None, defaults to a tuple of ones for each image dimension.

  • voxel_unit (str, optional) – Image voxel length unit.

  • **kwargs – Additional keyword arguments to be passed to the underlying Zarr.creation.create function.

Returns:

The created VoxelImage object.

Return type:

VoxelImage

rockverse.voxel_image.empty(shape, dtype, **kwargs)[source]#

Parallel CPU Create an empty voxel image with the given shape. The array will be initialized without any specific values.

Parameters:

  • shape (tuple) – Desired image shape.

  • dtype (string or dtype) – NumPy dtype.

  • **kwargs – Additional keyword arguments to be passed to the underlying creation function.

Returns:

The created VoxelImage object.

Return type:

VoxelImage

rockverse.voxel_image.zeros(shape, dtype, **kwargs)[source]#

Parallel CPU Create a voxel image filled with zeros.

Parameters:

  • shape (tuple) – Desired image shape.

  • dtype (string or dtype) – NumPy dtype.

  • **kwargs – Additional keyword arguments to be passed to the underlying creation function.

Returns:

The created VoxelImage object.

Return type:

VoxelImage

rockverse.voxel_image.ones(shape, dtype, **kwargs)[source]#

Parallel CPU Create a voxel image filled with ones.

Parameters:

  • shape (tuple) – Desired image shape.

  • dtype (string or dtype) – NumPy dtype.

  • **kwargs – Additional keyword arguments to be passed to the underlying creation function.

Returns:

The created VoxelImage object.

Return type:

VoxelImage

rockverse.voxel_image.full(shape, dtype, fill_value, **kwargs)[source]#

Parallel CPU Create a voxel image filled with a specified value.

Parameters:

  • shape (tuple) – Desired image shape.

  • dtype (string or dtype) – NumPy dtype.

  • fill_value (scalar) – Value to fill the array.

  • **kwargs – Additional keyword arguments to be passed to the underlying creation function.

Returns:

The created VoxelImage object.

Return type:

VoxelImage

rockverse.voxel_image.empty_like(a, **kwargs)[source]#

Parallel CPU Create empty voxel image with same shape, chunks, voxel_origin, voxel_length, and voxel_unit as the given image.

Parameters:

  • a (VoxelImage) – The source voxel image to mimic.

  • **kwargs – Additional keyword arguments to be passed to the underlying creation function.

Returns:

The created VoxelImage object.

Return type:

VoxelImage

rockverse.voxel_image.zeros_like(a, **kwargs)[source]#

Parallel CPU Create voxel image filled with zeros with same shape, chunks, voxel_origin, voxel_length, and voxel_unit as the given image.

Parameters:

  • a (VoxelImage) – The source RockVerse voxel image to mimic.

  • **kwargs – Additional keyword arguments to be passed to the underlying creation function.

Returns:

The created VoxelImage object.

Return type:

VoxelImage

rockverse.voxel_image.ones_like(a, **kwargs)[source]#

Parallel CPU Create voxel image filled with ones with same shape, chunks, voxel_origin, voxel_length, and voxel_unit as the given image.

Parameters:

  • a (VoxelImage) – The source RockVerse voxel image to mimic.

  • **kwargs – Additional keyword arguments to be passed to the underlying creation function.

Returns:

The created VoxelImage object.

Return type:

VoxelImage

rockverse.voxel_image.full_like(a, fill_value, **kwargs)[source]#

Parallel CPU Create voxel image filled with a specified value with same shape, chunks, voxel_origin, voxel_length, and voxel_unit as the given image.

Parameters:

  • a (VoxelImage) – The source RockVerse voxel image to mimic.

  • fill_value (scalar) – Value to fill the array.

  • **kwargs – Additional keyword arguments to be passed to the underlying creation function.

Returns:

The created VoxelImage object.

Return type:

VoxelImage

rockverse.voxel_image.sphere_pack(shape, dtype='u1', xlim=(-10, 10), ylim=(-10, 10), zlim=(-10, 10), sphere_radius=1, fill_value=1, **kwargs)[source]#

Parallel CPU GPU

Create a sphere pack image.

John Finney’s experimental disordered packing of equal, hard spheres, optically imaged in 1970, is hard-coded in RockVerse from the sphere centers available in Digital Rocks Portal. The volumetric image is analytically built in normalized coordinates, with sphere radius equal to 1 and (x, y, z) positions for sphere centers roughly between -20 and 20 in each direction. The image can be built at any needed resolution by a combination of shape and spatial limits.

Note

If you use this data, please remember to cite the data source and the related publications.

Parameters:

  • shape (tuple) – Shape of the image to create.

  • dtype (string or dtype, optional) – NumPy dtype. Default 8-bit unsigned integer.

  • xlim (tuple, optional) – Spatial limits of the sphere pack in the x-direction.

  • ylim (tuple, optional) – Spatial limits of the sphere pack in the y-direction.

  • zlim (tuple, optional) – Spatial limits of the sphere pack in the z-direction.

  • sphere_radius (float, optional) – Radius of the spheres to pack. Default is 1 (original pack, touching, non-overlapping hard spheres). Increase this value to simulate overlapping spheres (cement growth, for example) or decrease to use smaller spheres (like grain dissolution). Sphere centers will not change.

  • fill_value (scalar, optional) – Value to fill the spheres with. Default is 1.

  • **kwargs – Additional keyword arguments to be passed to the underlying creation function.

Returns:

The created VoxelImage object.

Return type:

VoxelImage

rockverse.voxel_image.import_raw(rawfile, shape, dtype, offset=0, raw_file_order='F', description='', field_name='', field_unit='', voxel_origin=None, voxel_length=None, voxel_unit='', overwrite=False, **kwargs)[source]#

Parallel CPU

Import raw file as a voxel image.

This function imports a raw binary file into a voxel image, adding the necessary metadata specific to digital rock petrophysics in RockVerse. It supports parallel reading to efficiently import large datasets.

Parameters:

  • rawfile (str) – Path to the raw file in the file system.

  • shape (tuple, list, or numpy.ndarray of ints) – Shape of the array to be created.

  • dtype (str) –

    Data type of the raw file, specified as a Numpy typestring formed by the sequence of characters:

    1. The character for byte order:

      • < if little endian

      • > if big endian

      • | if not applicable (8-bit numbers)

    2. The character for data type:

      • b for boolean

      • i for signed integer

      • u for unsigned integer

      • f for floating-point

    3. The number of bytes per voxel

      • 1 for 8-bit data

      • 2 for 16-bit data

      • 4 for 32-bit data

      • 8 for 64-bit data

    These are the accepted combinations:

    • '|b1': boolean

    • '|u1': 8-bit unsigned integer

    • '|i1': 8-bit signed integer

    • '<u2': little endian 16-bit unsigned integer

    • '<u4': little endian 32-bit unsigned integer

    • '<u8': little endian 64-bit unsigned integer

    • '<u16': little endian 128-bit unsigned integer

    • '>u2': big endian 16-bit unsigned integer

    • '>u4': big endian 32-bit unsigned integer

    • '>u8': big endian 64-bit unsigned integer

    • '>u16': big endian 128-bit unsigned integer

    • '<i2': little endian 16-bit signed integer

    • '<i4': little endian 32 -bit signed integer

    • '<i8': little endian 64-bit signed integer

    • '<i16': little endian 128-bit signed integer

    • '>i2': big endian 16-bit signed integer

    • '>i4': big endian 32-bit signed integer

    • '>i8': big endian 64-bit signed integer

    • '>i16': big endian 128-bit signed integer

    • '<f4': little endian 32-bit float

    • '<f8': little endian 64-bit float

    • '>f4': big endian 32-bit float

    • '>f8': big endian 64-bit float

    The imported data will be converted to the system’s native byte order (little endian or big endian).

  • offset (int, optional) – Number of bytes to skip at the beginning of the file. Typically a multiple of the byte-size of dtype. Default is 0.

  • raw_file_order ({'C', 'F'}, optional) – Specify the memory layout order of the raw file: ‘C’ for C-style (row-major), ‘F’ for Fortran-style (column-major). Use ‘F’ when loading raw files exported from Fiji/ImageJ. After importing, C-style memory layout is enforced within chunks for optimal cache performance in RockVerse workflows. Default is ‘F’.

  • description (str, optional) – Description for the stored scalar field.

  • field_name (str, optional) – Name for the stored scalar field.

  • field_unit (str, optional) – Unit for the stored scalar field.

  • voxel_origin (tuple, list, or Numpy array of ints, optional) – Spatial coordinate origin for the first voxel in the array, in units of voxel_unit. If None, defaults to a tuple of zeros for each array dimension.

  • voxel_length (tuple, list, or Numpy array of ints or floats, optional) – Voxel length in each direction. If None, defaults to a tuple of ones for each array dimension.

  • voxel_unit (str, optional) – Unit for the voxel length.

  • overwrite (bool, optional) – If True, delete all pre-existing data in the store at the specified path before creating the new array. Default is False, to prevent accidental overwriting of existing data.

  • **kwargs – Additional keyword arguments to be passed to the underlying creation function.

Returns:

The created VoxelImage object.

Return type:

VoxelImage