rockverse.voxel_image.import_raw

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)

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

     • 16 for 128-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

  • '<f16': little endian 128-bit float

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

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

  • '>f16': big endian 128-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