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 GPU

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 GPU 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 GPU 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 GPU 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 GPU 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 GPU 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 GPU 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 GPU 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 GPU 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.copy_from_array(array, **kwargs)[source]#

Parallel CPU

Create a new VoxelImage object and copy array data into it.

Parameters:

  • array (array-like) – Input data to be copied. Must support dtype and shape attributes.

  • **kwargs – Additional keyword arguments to be passed to the underlying creation function. Notice that image shape will match original array shape, and therefore keyword argument shape will be ignored in kwargs.

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