A utility to convert voxel data stored in a 3D NumPy array into a collection of OBJ mesh cubes for visualizing, sharing, and rendering.
- Generates mesh vertices and faces corresponding to each point in a NumPy array.
- The script is a utility to share voxel models with peers who can access a basic mesh modeling program that can open Wavefront OBJ files.
- A helpful tool for generating voxel mesh models for images and renders.
- The mesh OBJ files are relatively large due to the number of generated vertices and faces.
- By default, the script filters out all internal voxels creating a surface view shell made only of voxels that border empty voxel regions.
Dependencies
- NumPy is the only package dependency for the main python script.
- Additional dependencies listed in
requirements.txtsupport the analysis completed in the jupyter notebook.
Example Script Commands
Convert Numpy Voxel Data into OBJ Mesh
python obj-voxel-visualizer.py input-numpy-file.npySpecify Filename of OBJ Output
python obj-voxel-visualizer.py input-numpy-file.npy --output voxel-mesh-visual.objToggle Surface View Off
python obj-voxel-visualizer.py input-numpy-file.npy --no-surface-viewJupyter Notebook
- Interactive examples
- Converting NPY files using the command line function
- Using internal functions to export loaded NPY data
- Inline mesh viewer using Trimesh
- Measured runtime improvements over the original iteration of the function.
- Voxel data metrics evaluating voxel count and file size.
- Data plots illustrating the relationship between voxel count and the resulting OBJ file size when in surface view mode.
Voxel Model Cross-Section
Surface View ON vs Surface View OFF
Mesh Voxel Models with Varied Voxel Resolution
| Surface Voxel Count | Voxel Array Bounding Box Dimensions | Voxel % of Bounding Box Magnitude | |
|---|---|---|---|
| 1 | 340,106 | ( 408, 236, 176 ) | 0.1988% |
| 2 | 83,142 | ( 204, 118, 88 ) | 0.3975% |
| 3 | 36,269 | ( 136, 79, 59 ) | 0.5953% |
| 4 | 19,786 | ( 102, 59, 44 ) | 0.7950% |
- Voxel resolution is measured as a percentage of the voxel grid dimension magnitude.
- Assuming there is no padding around the model's minimum bounding box, the resolution indicates the voxel size and the model orientation within the voxel grid.
- A larger voxel size will decrease the detail on the model surface and reduce the size of the file containing the voxel data.
- Decreasing the voxel resolution percentage increases the number of voxels inside the voxel grid array.