API Reference
Global Methods
As the methods are several, below are only listed the most pertinent global methods of voxelmap, in order of the lowest level to highest level of applications to 3-D modeling operations.and classified in sub-sections:
Special
- class voxelmap.objcast(filename='scene.obj', spacing=1)
Converts a Wavefront .obj file into a sparse, third-order (3-D) NumPy array to represent a point cloud model.
Parameters
- filenamestr
Path to the .obj file. Defaults to ‘scene.obj’.
- spacingfloat
Distance between points in the point cloud. Can be adjusted to create a denser or sparser point cloud. Defaults to 1.
- class voxelmap.matrix_toXY(array, mult)
Converts a 2D numpy array into an XYv coordinate matrix where v is the corresponding element in every x-y coordinate.
Parameters
- arraynp.array(int,int)
The 2D numpy array to be converted to an XYv coordinate matrix.
- multint or float
The multiplication factor to be applied to the elements in the matrix.
Load and Save
- class voxelmap.load_array(filename)
Loads a pickled numpy array with filename name
- class voxelmap.save_array(array, filename)
Saves an array array with filename name using the pickle module
- class voxelmap.tojson(filename, array, hashblocks={})
Save 3-D array and hashblocks color mapping as JSON file
- class voxelmap.load_from_json(filename)
Load JSON file to object
Array Manipulation
- class voxelmap.resize_array(array, mult=(2, 2, 2))
Resizes a three-dimensional array by the three dim factors specified by mult tuple. Converts to sparse array of 0s and 1s
Parameters
- arraynp.array(int,int,int)
array to resize
- mult: tuple(float,float,float)
depth length width factors to resize array with. e.g 2,2,2 resizes array to double its size in all dims
- class voxelmap.roughen(array, kernel_level=1)
Makes a 3d array model rougher by a special convolution operation. Uses voxelmap.random_kernel_convolve.
Parameters
- arraynp.array(int,int,int)
array to roughen up
- kernel_level: int
length scale (size) of random kernels used. The smallest scale (=1) gives the roughest transformation.
- class voxelmap.random_kernel_convolve(array, kernel, random_bounds=(-10, 10))
Applies a three-dimensional convolution with a randomly-mutating kernel on a 3-D array which changes for every array site when random_bounds are set to tuple. If random_bounds are set to False, convolution occurs in constant mode for the specified kernel.
Parameters
- arraynp.array(int,int,int)
array to convolve
- kernel: np.array(int,int,int)
kernel to use for convolution. If random_bounds are set to tuple, only the kernel’s shape is used to specify the random_kernels
- random_boundstuple(int,int) OR bool
see above explanation.
Mapping
- class voxelmap.MarchingMesh(array, out_file='scene.obj', level=0, spacing=(1.0, 1.0, 1.0), gradient_direction='descent', step_size=1, allow_degenerate=True, method='lewiner', mask=None, plot=False, figsize=(4.8, 4.8))
Marching cubes on sparse 3-D integer voxelmap arrays (GLOBAL)
Parameters
- array: np.array((int/float,int/float,int/float))
3-D array for which to run the marching cubes algorithm
- out_filestr
name and/or path for Wavefront .obj file output. This is the common format for OpenGL 3-D model files (default: model.obj)
- levelfloat, optional
Contour value to search for isosurfaces in volume. If not given or None, the average of the min and max of vol is used.
- spacinglength-3 tuple of floats, optional
Voxel spacing in spatial dimensions corresponding to numpy array indexing dimensions (M, N, P) as in volume.
- gradient_directionstring, optional
Controls if the mesh was generated from an isosurface with gradient descent toward objects of interest (the default), or the opposite, considering the left-hand rule. The two options are: – ‘descent’ : Object was greater than exterior – ‘ascent’ : Exterior was greater than object
- step_sizeint, optional
Step size in voxels. Default 1. Larger steps yield faster but coarser results. The result will always be topologically correct though.
- allow_degeneratebool, optional
Whether to allow degenerate (i.e. zero-area) triangles in the end-result. Default True. If False, degenerate triangles are removed, at the cost of making the algorithm slower.
- method: str, optional
One of ‘lewiner’, ‘lorensen’ or ‘_lorensen’. Specify which of Lewiner et al. or Lorensen et al. method will be used. The ‘_lorensen’ flag correspond to an old implementation that will be deprecated in version 0.19.
- mask(M, N, P) array, optional
Boolean array. The marching cube algorithm will be computed only on True elements. This will save computational time when interfaces are located within certain region of the volume M, N, P-e.g. the top half of the cube-and also allow to compute finite surfaces-i.e. open surfaces that do not end at the border of the cube.
- plot: bool
plots a preliminary 3-D triangulated image if True
- class voxelmap.MeshView(objfile='scene.obj', color='black', alpha=1, wireframe=True, wireframe_color='white', background_color='#cccccc', viewport=[1024, 768])
Triangulated mesh view with PyVista (GLOBAL)
Parameters
- objfile: string
.obj file to process with MeshView [in GLOBAL function only]
- colorstring / hexadecimal
mesh color. default: ‘pink’
- alphafloat
opacity transparency range: 0 - 1.0. Default: 0.5
- wireframe: bool
Represent mesh as wireframe instead of solid polyhedron if True (default: False).
- wireframe_color: string / hex
edges or wireframe colors
- background_colorstring / hexadecimal
color of background. default: ‘pink’
- viewport(int,int)
viewport / screen (width, height) for display window (default: 80% your screen’s width & height)
Local Methods to Model class
- class voxelmap.Model(array=[], file='')
- __init__(array=[], file='')
Model structure. Calls 3-D array to process into 3-D model.
Parameters
- arraynp.array(int)
array of the third-order populated with discrete, non-zero integers which may represent a voxel block type
- filestr
file name and/or path for image file
- hashblocksdict[int]{str, float }
a dictionary for which the keys are the integer values on the discrete arrays (above) an the values are the color (str) for the specific key and the alpha for the voxel object (float)
- colormap< matplotlib.cm object >
colormap to use for voxel coloring if coloring kwarg in Model.draw method is not voxels. Default: cm.cool
- alphacmfloat
alpha transparency of voxels if colormap option is chosen. default: opaque colormap (alpha=1)
– FOR FILE PROCESSING –
- filestr
file name a/or path for goxel txt file
– FOR XYZ COORDINATE ARRAY PROCESSING –
- XYZnp.array(float )
an array containing the x,y,z coordinates of shape number_voxel-locations x 3 [for each x y z]
- RGBlist[str]
a list for the colors of every voxels in xyz array (length: number_voxel-locations)
- sparsityfloat
a factor to separate the relative distance between each voxel (default:10.0 [> 50.0 may have memory limitations])
- ImageMap(depth=5, out_file='scene.obj', plot=False)
Map image or 2-D array (matrix) to 3-D array
Parameters
- depthint
depth in number of voxels (default = 5 voxels)
- out_filestr
name and/or path for Wavefront .obj file output. This is the common format for OpenGL 3-D model files (default: model.obj)
- plot: bool / str
plots a preliminary 3-D triangulated image if True with PyVista. For more plotting options, plot by calling MeshView separately.
- ImageMesh(out_file='scene.obj', L_sectors=4, rel_depth=0.5, trace_min=1, plot=True, figsize=(4.8, 4.8), verbose=False)
3-D triangulation of 2-D images / 2-D arrays (matrices) with a Convex Hull algorithm (Andrew Garcia, 2022)
Parameters
- out_filestr
name and/or path for Wavefront .obj file output. This is the common format for OpenGL 3-D model files (default: model.obj)
- L_sectors: int
length scale of Convex Hull segments in sector grid, e.g. L_sectors = 4 makes a triangulation of 4 x 4 Convex Hull segments
- rel_depth: float
relative depth of 3-D model with respect to the image’s intensity magnitudes (default: 0.50)
- trace_min: int
minimum number of points in different z-levels to triangulate per sector (default: 1)
- plot: bool / str
plots a preliminary 3-D triangulated image if True [with PyVista (& with matplotlib if plot = ‘img’). For more plotting options, plot with Meshview instead.
- MarchingMesh(voxel_depth=12, level=0, spacing=(1.0, 1.0, 1.0), gradient_direction='descent', step_size=1, allow_degenerate=True, method='lewiner', mask=None, plot=False, figsize=(4.8, 4.8))
Marching cubes on 3-D mapped image or 3-D array
Parameters
- voxel_depthint (optional)
depth of 3-D mapped image on number of voxels (if file [image] is to be processed / i.e. specified)
- levelfloat, optional
Contour value to search for isosurfaces in volume. If not given or None, the average of the min and max of vol is used.
- spacinglength-3 tuple of floats, optional
Voxel spacing in spatial dimensions corresponding to numpy array indexing dimensions (M, N, P) as in volume.
- gradient_directionstring, optional
Controls if the mesh was generated from an isosurface with gradient descent toward objects of interest (the default), or the opposite, considering the left-hand rule. The two options are: – ‘descent’ : Object was greater than exterior – ‘ascent’ : Exterior was greater than object
- step_sizeint, optional
Step size in voxels. Default 1. Larger steps yield faster but coarser results. The result will always be topologically correct though.
- allow_degeneratebool, optional
Whether to allow degenerate (i.e. zero-area) triangles in the end-result. Default True. If False, degenerate triangles are removed, at the cost of making the algorithm slower.
- method: str, optional
One of ‘lewiner’, ‘lorensen’ or ‘_lorensen’. Specify which of Lewiner et al. or Lorensen et al. method will be used. The ‘_lorensen’ flag correspond to an old implementation that will be deprecated in version 0.19.
- mask(M, N, P) array, optional
Boolean array. The marching cube algorithm will be computed only on True elements. This will save computational time when interfaces are located within certain region of the volume M, N, P-e.g. the top half of the cube-and also allow to compute finite surfaces-i.e. open surfaces that do not end at the border of the cube.
- plot: bool
plots a preliminary 3-D triangulated image if True
- MeshView(color='black', alpha=1, wireframe=True, wireframe_color='white', background_color='#ffffff', viewport=[1024, 768])
Triangulated mesh view with PyVista
Parameters
- objfile: string
.obj file to process with MeshView [in GLOBAL function only]
- colorstring / hexadecimal
mesh color. default: ‘pink’
- alphafloat
opacity transparency range: 0 - 1.0. Default: 0.5
- wireframe: bool
Represent mesh as wireframe instead of solid polyhedron if True (default: False).
- wireframe_color: string / hex
edges or wireframe colors
- background_colorstring / hexadecimal
color of background. default: ‘pink’
- viewport(int,int)
viewport / screen (width, height) for display window (default: 80% your screen’s width & height)
- build()
Builds voxel model structure from python numpy array
- draw(coloring='none', geometry='voxels', scalars='', background_color='#cccccc', wireframe=False, wireframe_color='k', window_size=[1024, 768], voxel_spacing=(1, 1, 1), show=True)
Draws voxel model after building it with the provided array with PyVista library
Parameters
- coloring: string
- voxel coloring scheme
‘custom’ –> colors voxel model based on the provided keys to its array integers, defined in the hashblocks variable from the Model class
‘custom: #8599A6’ –> color all voxel types with the #8599A6 hex color (bluish dark gray) and an alpha transparency of 1.0 (default)
‘custom: red, alpha: 0.24’ –> color all voxel types red and with an alpha transparency of 0.24
‘cmap : {colormap name}’ : colors voxel model based on a colormap; assigns colors from the chosen colormap to the defined array integers
‘cmap : viridis’ –> colormap voxel assignment with the viridis colormap
‘cmap : hot’, alpha: 0.56 –> voxel assignment with the hot colormap with an alpha transparency of 0.56
‘none’ –> no coloring
‘cool’ cool colormap
‘fire’ fire colormap
and so on…
- geometry: string
voxel geometry. Choose voxels to have a box geometry with geometry=’voxels’ or spherical one with geometry=’particles’
- scalarslist
list of scalars for cmap coloring scheme
- background_colorstring / hex
background color of pyvista plot
- wireframe: bool
Represent mesh as wireframe instead of solid polyhedron if True (default: False).
- wireframe_color: string / hex
edges or wireframe colors
- window_size(float,float)
defines plot window dimensions. Defaults to [1024, 768], unless set differently in the relevant theme’s window_size property [pyvista.Plotter]
- voxel_spacing(float,float,float)
changes voxel spacing by defining length scales of x y and z directions (default:(1,1,1)).
- showbool
Display Pyvista 3-D render of drawn 3-D model if True (default: True)
- draw_mpl(coloring='custom', edgecolors=None, figsize=(6.4, 4.8), axis3don=False)
Draws voxel model after building it with the provided array (Matplotlib version. For faster graphics, try the
draw()method (uses PyVista)).Parameters
- coloring: string
- voxel coloring scheme
‘custom’ –> colors voxel model based on the provided keys to its array integers, defined in the hashblocks variable from the Model class
‘custom: #8599A6’ –> color all voxel types with the #8599A6 hex color (bluish dark gray) and an alpha transparency of 1.0 (default)
‘custom: red, alpha: 0.24’ –> color all voxel types red and with an alpha transparency of 0.2
‘nuclear’ colors model radially, from center to exterior
‘linear’ colors voxel model vertically, top to bottom.
- edgecolors: string/hex
edge color of voxels (default: None)
- figsize(float,float)
defines plot window dimensions. From matplotlib.pyplot.figure(figsize) kwarg.
- axis3don: bool
defines presence of 3D axis in voxel model plot (Default: False)
- hashblocks_add(key, color, alpha=1)
Make your own 3-D colormap option. Adds to hashblocks dictionary.
Parameters
- keyint
array value to color as voxel
- colorstr
color of voxel with corresponding key index (either in hexanumerical # format or default python color string)
- alphafloat, optional
transparency index (0 -> transparent; 1 -> opaque; default = 1.0)
- load(filename='scene.json', coords=False)
Load to Model object.
Parameters
- filename: string (.json or .txt extensions (see above))
name of file to be loaded (e.g ‘scene.json’)
- coords: bool
loads and processes self.XYZ, self.RGB, and self.sparsity = 10.0 (see Model class desc above) to Model if True. This boolean overrides filename loader option.
- make_intensity()
Turn image into intensity matrix i.e. matrix with pixel intensities. Outputs self.array as mutable matrix to contain relative pixel intensities in int levels [for file if specified]
- resize_intensity(res=1.0, res_interp=3)
Resize the intensity matrix of the provided image.
Parameters
- resfloat, optional
relative resizing percentage as x times the original (default 1.0 [1.0x original dimensions])
- res_interp: object, optional
cv2 interpolation function for resizing (default cv2.INTER_AREA)
- save(filename='scene.json')
Save sparse array + color assignments Model data as a dictionary of keys (DOK) JSON file
Parameters
- filename: string
name of file (e.g. ‘scene.json’) Data types: .json -> voxel data represented as (DOK) JSON file .txt -> voxel data represented x,y,z,rgb matrix in .txt file (see Goxel .txt imports)