xopto.mcvox.mcgeometry.voxel module

class Voxel

Bases: xopto.mcbase.mcobject.McObject

Minimal implementation of a ctypes structure that represents a singe voxel in the Monte Carlo simulations. All the fields defined by this implementation are required.

static cl_declaration(mc: xopto.mcbase.mcobject.McObject) → str

Structure that represents a single voxel in the Monte Carlo simulator.

static cl_type(mc: xopto.mcbase.mcobject.McObject) → xopto.cl.cltypes.Structure

static np_dtype(mc: xopto.mcbase.mcobject.McObject) → numpy.dtype

Numpy data type representing a single voxel. This implementation uses structured numpy array that can be directly/efficiently mapped to OpenCL data arrays.

Parameters

mc (mcobject.McObject) – Target simulator instance.

Returns

dtype – Numpy data type representing a single voxel.

Return type

np.dtype

class Voxels(xaxis: xopto.mcbase.mcutil.axis.Axis, yaxis: xopto.mcbase.mcutil.axis.Axis, zaxis: xopto.mcbase.mcutil.axis.Axis, voxel: Optional[Type[xopto.mcvox.mcgeometry.voxel.Voxel]] = None)

Bases: xopto.mcbase.mcobject.McObject

Minimal implementation of a voxelized sample. All the fields defined by this implementation are required by the Monte Carlo simulator.

Object that manages the voxelized sample volume. Each voxel item is of integer type that represents the index of material filling the voxel volume.

Parameters

• xaxis (Axis) – Objects that specify the voxelized grid along the three orthogonal coordinate axis. Note that the Axis constructor takes the outer boundaries of the range and not of the voxel centers. Use Axis(-20e-3, 20e-3, 40) to have 40 voxels from -20 to 20 mm (voxel size is 1 mm). It is recommended to start the zaxis at z=0.

• yaxis (Axis) – Objects that specify the voxelized grid along the three orthogonal coordinate axis. Note that the Axis constructor takes the outer boundaries of the range and not of the voxel centers. Use Axis(-20e-3, 20e-3, 40) to have 40 voxels from -20 to 20 mm (voxel size is 1 mm). It is recommended to start the zaxis at z=0.

• zaxis (Axis) – Objects that specify the voxelized grid along the three orthogonal coordinate axis. Note that the Axis constructor takes the outer boundaries of the range and not of the voxel centers. Use Axis(-20e-3, 20e-3, 40) to have 40 voxels from -20 to 20 mm (voxel size is 1 mm). It is recommended to start the zaxis at z=0.

• voxel (type) – Data type representing a single voxel

Note

Initially the material_index of all voxels is set to 0, referencing the material of the surrounding medium. The data array indexing follows C scheme, i.e [z, y, x]. Use the data method to get the numpy voxel array.

center(index: Tuple[int, int, int]) → Tuple[float, float, float]

Returns the center of the voxel at the given index.

Parameters

index ((int, int, int)) – Voxel index as a tuple of three indices (ind_x, ind_y, ind_z).

Returns

position – A tuple of indices into the voxel array.

Return type

(float, float, float)

cl_declaration(mc: xopto.mcbase.mcobject.McObject) → str

Structure that defines the source in the Monte Carlo simulator and the data type that represents a single voxel.

cl_implementation(mc: xopto.mcbase.mcobject.McObject) → str

OpenCL options of the scattering phase function.

cl_options(mc: xopto.mcbase.mcobject.McObject) → str

OpenCL options of the scattering phase function.

cl_pack(mc: xopto.mcbase.mcobject.McObject, target: xopto.cl.cltypes.Structure) → xopto.cl.cltypes.Structure

Fills the ctypes structure (target) with the data required by the Monte Carlo simulator. See Voxels.cl_type() for a detailed list of fields.

Parameters

• mc (mcobject.McObject) – Monte Carlo simulator instance.

• target (mcypes.Structure) – Ctypes structure that is filled with the voxelization configuration.

Returns

target – Filled ctypes structure received as an input argument or a new instance if the input argument target is None.

Return type

mctypes.Structures

static cl_type(mc: xopto.mcbase.mcobject.McObject) → xopto.cl.cltypes.Structure

contains(position: Tuple[float, float, float]) → bool

Returns True if the position is within the voxel array boundaries. Note that the lower bound is included but the upper bound is not.

Parameters

position ((float, float, float)) – Position as a tuple of three coordinates (x, y, z).

Returns

contains – Returns True if the given position lies within the voxel array boundaries.

Return type

bool

data(mc: Optional[xopto.mcbase.mcobject.McObject] = None) → numpy.ndarray

Return the voxel data as a 3D array representing the voxelized sample space.

The data array should be addressed as data[z, y, x], wher x, y and z are the indices along the corresponding spatial axes passed to the constructor. The individual data fields of the selected voxels are addressed as data[x, y, z][‘field_name’], e.g. data[0, :, :][‘material_index’] = 1 sets the material of the first layer of voxels along the z axis to 1 (the second material in the materials list).

Parameters

mc (mcobject.McObject) – A simulator instance that is required only during the first call to derive the proper voxel data type and allocate the a 3D structured array that represents the voxels.

Returns

data – Voxel data as a 3D numpy array.

Return type

np.ndarray

property dx: numpy.ndarray

The size of voxels along the x axis.

property dy: numpy.ndarray

The size of voxels along the y axis.

property dz: numpy.ndarray

The size of voxels along the z axis.

classmethod fromdict(data: dict) → xopto.mcvox.mcgeometry.voxel.Voxels

Create a new instance of Voxels from a dict.

Parameters

data (dict) – A dict with instance data.

Returns

instance – A new instance of Voxels.

Return type

Voxels

property grid: Tuple[numpy.ndarray, numpy.ndarray, numpy.ndarray]

Coordinate matrices Z, Y and X of voxel centers as returned by the Voxels.meshgrid() method.

index(position: Tuple[float, float, float]) → Tuple[int, int, int]

Returns index of the voxel at the given position.

Parameters

position ((float, float, float)) – Position as a tuple of three coordinates (x, y, z).

Returns

index – A tuple of indices into the voxel array.

Return type

(int, int, int)

intersect(pos: Tuple[float, float, float], dir: Tuple[float, float, float]) → Tuple[Tuple[float, float, float], Tuple[float, float, float]]

Intersect the voxelized box with the ray and return the intersection. Intersection is considered to exist only if the distance to the intersection is positive.

Parameters

• pos ((float, float, float)) – Ray origin.

• dir ((float, float, float)) – Ray direction.

Returns

• intersection ((float, float, float) or None) – Returns intersection if one exists, else None.

• normal ((float, float, float) or None) – Surface normal of the voxelized sample box that points in the propagation direction.

isvalid(index: Tuple[int, int, int]) → bool

Returns True if the given index is valid for the voxel array.

Parameters

index ((int, int, int)) – Index into the voxel array.

Returns

valid – True if index is valid.

Return type

bool

property material

3D array of material indices.

meshgrid() → Tuple[numpy.ndarray, numpy.ndarray, numpy.ndarray]

Coordinate matrices with x, y and z coordinates of all the voxels. The shape of the matrices equals the shape of the voxel array.

Returns

• Z (np.ndarray) – Z coordinates of all the voxels as a 3D array.

• Y (np.ndarray) – Y coordinates of all the voxels as a 3D array.

• X (np.ndarray) – X coordinates of all the voxels as a 3D array.

Note

The coordinate matrices are created on the first call.

plot(axis: str = 'z', autoscale: bool = True, show: bool = True)

Show slices through the materials array.

Parameters

• scale (str) – Data scaling can be “log” for logarithmic or “lin” for linear.

• axis (str) – The axis of slicing (“x”, “y” or “z”).

• autoscale (bool) – Scale the color coding of individual slices to the corresponding range of weights. If True, the color coding changes from slice to slice.

• show (bool) –

render(show: bool = True)

Show the voxelized volume in a 3D viewer.

Parameters

show (bool) – If True, shows the window and starts the Qt event loop that will block until the window is closed.

Returns

viewer – Use the exec() method to show the viewer and start the Qt event loop that will block until the window is closed.

Return type

slicer3d.Slicer3D

Note

The 3D viewer requires PySide6 and PyQtGraph.

property shape: Tuple[int, int, int]

Voxel array shape (z, y, x).

property size: int

Total number of voxels.

todict() → dict

Export object to a dict.

property top_left: Tuple[float, float, float]

Coordinates (x, y, z) of the top left corner of the voxel array.

update()

Call this method if the voxel data needs to be updated/uploaded to the OpenCL device. This function should be called if the voxel data have been changed after the last simulation call.

update_required(clear: bool = True) → bool

Returns True if the voxel data have been changed and need to be uploaded to the OpenCL device before running the next simulation. The update flag is cleared (set to False) if the value of the clear argument is True.

Parameters

clear (bool) – If True, the update flag is cleared (set to False) after returning its value.

Returns

update_required – True if the voxel data have changed and need to be uploaded to tho OpenCL device before running a new simulation.

Return type

bool

property voxel: xopto.mcvox.mcgeometry.voxel.Voxel

Instance of the Voxel data type.

property voxel_size: Tuple[float, float, float]

Size of a voxel (m) as (dx, dy, dz).

property voxel_type: Type[xopto.mcvox.mcgeometry.voxel.Voxel]

Voxel data type used by this voxelized sample.

property x: numpy.ndarray

Coordinates of the voxel centers along the x axis.

property xaxis: xopto.mcbase.mcutil.axis.Axis

Axis x of the voxel array.

property y: numpy.ndarray

Coordinates of the voxel centers along the y axis.

property yaxis: xopto.mcbase.mcutil.axis.Axis

Axis y of the voxel array.

property z: numpy.ndarray

Coordinates of the voxel centers along the z axis.

property zaxis: xopto.mcbase.mcutil.axis.Axis

Axis z of the voxel array.