Computed Tomography to Finite Elements
Project description
ciclope
Computed Tomography to Finite Elements.
ciclope processes micro Computed Tomography (microCT) data to generate Finite Element (FE) models.
Installation
For mesh generation, ciclope
requires pygalmesh-0.10.6, a Python frontend to CGAL.
Follow the installation procedure for CGAL and Eigen.
After that, install pygalmesh with pip or conda:
conda install -c conda-forge pygalmesh==0.10.6
After installing pygalmesh, you can install ciclope
using pip. The flag [all]
will install optional dependencies needed to run full pipelines and examples.
pip install ciclope[all]
Some examples will require DXchange. You can install it with:
conda install -c conda-forge dxchange
Testing
To verify your installation checkout this repository and run the tests with the command:
cd test
python -m unittest -v test_ciclope.run_tests
How to contribute
If you want to contribute to this project, please install ciclope
following the development guide.
Usage
ciclope pipelines can be run from the command line as a script. Scroll down and take a look at the Examples folder for this type of use. To view the command line script help run:
ciclope -h
To use ciclope within python, import the package with
import ciclope
Image pre-processing
ciclope.utils
contains functions that help you read and pre-process 3D datasets for FE model generation. You can skip this and use ciclope
with 3D data as numpy.ndarray
, or directly with a 3D meshio
object.
Read 3D CT dataset stored as stack of TIFFs:
from ciclope.utils.recon_utils import read_tiff_stack
input_file = '/path_to_your_file/slice_0000.tiff'
data_3D = read_tiff_stack(input_file)
vs = np.ones(3) * 0.06 # voxelsize [mm]
Segment and remove unconnected voxels:
from skimage import morphology
from ciclope.utils.preprocess import remove_unconnected
BW = data_3D > 142 # fixed global threshold
BW = morphology.closing(BW, morphology.ball(2)) # optional step
L = remove_unconnected(BW)
FE model generation
voxel-FE
Generate voxel-FE model of linear elastic compression test:
import ciclope
input_template = "./input_templates/tmp_example01_comp_static_bone.inp"
# generate unstructured grid mesh
mesh = ciclope.core.voxelFE.vol2ugrid(data_3D, vs)
# generate CalculiX input file
ciclope.core.voxelFE.mesh2voxelfe(mesh, input_template, 'foo.inp', keywords=['NSET', 'ELSET'])
tetrahedra-FE
Generate mesh of tetrahedra. ciclope
uses pygalmesh
for tetrahedra mesh generation:
mesh = ciclope.core.tetraFE.cgal_mesh(L, vs, 'tetra', max_facet_distance=0.2, max_cell_circumradius=0.1)
Generate tetrahedra-FE model of non-linear tensile test
input_template = "./input_templates/tmp_example02_tens_static_steel.inp"
# generate CalculiX input file
ciclope.core.tetraFE.mesh2tetrafe(mesh, input_template, 'foo.inp', keywords=['NSET', 'ELSET'])
Postprocessing
ciclope.utils.postprocess.paraviewplot
calls ParaView to generate and save plots of a chosen model scalar field.
- Add path to your ParaView installation with
import sys
sys.path.append('~/Applications/ParaView-5.9.0-RC1-MPI-Linux-Python3.8-64bit/lib/python3.8/site-packages')
- Plot midplanes of the vertical displacement field
UD3
:
ciclope.utils.postprocess.paraview_plot('test_data/tooth/results/Tooth_3_scaled_2.vtk', slicenormal="xyz",
RepresentationType="Surface", Crinkle=True, ColorBy=['U', 'D2'], Roll=90,
ImageResolution=[1024, 1024], TransparentBackground=True,
colormap='Cool to Warm')
- Plot midplanes of the Von Mises stress
S_Mises
:
ciclope.utils.postprocess.paraview_plot("test_data/tooth/results/Tooth_3_scaled_2.vtk", slicenormal="xyz",
RepresentationType="Surface", Crinkle=False, ColorBy="S_Mises", Roll=90,
ImageResolution=[1024, 1024])
ciclope pipeline
The following table shows a general pipeline for FE model generation from CT data that can be executed from the command line with the ciclope
script:
# | Step | Description | command line script flag |
---|---|---|---|
1. | Load CT data | ||
2. | Pre-processing | Gaussian smooth | --smooth |
Resize image | -r |
||
Add embedding | (not implemented yet) | ||
Add caps | --caps |
||
3. | Segmentation | Uses Otsu method if left empty | -t |
Remove unconnected voxels | |||
4. | Meshing | Outer shell mesh of triangles | --shell_mesh |
Volume mesh of tetrahedra | --vol_mesh |
||
5. | FE model generation | Apply Boundary Conditions | |
Material mapping | -m , --mapping |
||
Voxel FE | --voxelfe |
||
Tetrahedra FE | --tetrafe |
Notes on ciclope
- Tetrahedra meshes are generated with pygalmesh (a Python frontend to CGAL)
- High-resolution surface meshes for visualization are generated with the PyMCubes module.
- All mesh exports are performed with the meshio module.
- ciclope handles the definition of material properties and FE analysis parameters (e.g. boundary conditions, simulation steps..) through separate template files. The folders material_properties and input_templates contain a library of template files that can be used to generate FE simulations.
Examples
Example 1: voxel-uFE model of trabecular bone; linear compression test
The pipeline can be executed from the command line with:
ciclope test_data/LHDL/3155_D_4_bc/cropped/3155_D_4_bc_0000.tif test_data/LHDL/3155_D_4_bc/results/3155_D_4_bc_voxelFE.inp -vs 0.0195 0.0195 0.0195 -r 2 -t 63 --smooth 1 --voxelfe --template input_templates/tmp_example01_comp_static_bone.inp --verbose
The example shows how to:
- Load and inspect microCT volume data
- Apply Gaussian smooth
- Resample the dataset
- Segment the bone tissue
- Remove unconnected clusters of voxels
- Convert the 3D binary to a voxel-FE model for simulation in CalculX or Abaqus
- Linear, static analysis; displacement-driven
- Local material mapping (dataset Grey Values to bone Tissue Elastic Modulus)
- Launch simulation in Calculix
- Convert Calculix output to .VTK for visualization in Paraview
- Visualize simulation results in Paraview
Example 2: tetrahedra-uFE model of trabecular bone; linear compression test
The pipeline can be executed from the command line with:
ciclope test_data/LHDL/3155_D_4_bc/cropped/3155_D_4_bc_0000.tif test_data/LHDL/3155_D_4_bc/results/3155_D_4_bc.inp -vs 0.0195 0.0195 0.0195 -r 2 -t 63 --smooth 1 --tetrafe --max_facet_distance 0.025 --max_cell_circumradius 0.05 --vol_mesh --template input_templates/tmp_example01_comp_static_bone.inp
Example #3 - tetrahedra-FE model of embedded tooth; compression test; heterogeneous materials
Example #4 - non-linear tetrahedra-FE model of stainless steel foam
The pipeline can be executed from the command line with:
ciclope input.tif output.inp -vs 0.0065 0.0065 0.0065 --smooth -r 1.2 -t 90 --vol_mesh --tetrafe --template ./../input_templates/tmp_example02_tens_Nlgeom_steel.inp -v
The example shows how to:
- Load and inspect synchrotron microCT volume data
- Apply Gaussian smooth
- Resample the dataset
- Segment the steel
- Remove unconnected clusters of voxels
- Generate volume mesh of tetrahedra
- Generate high-resolution mesh of triangles of the model outer shell (for visualization)
- Convert the 3D binary to a tetrahedra-FE model for simulation in CalculX or Abaqus
- Non-linear, quasi-static analysis definition: tensile test with material plasticity. For more info visit: github.com/mkraska/CalculiX-Examples
- Local material mapping
- Launch simulation in Calculix
- Convert Calculix output to .VTK for visualization in Paraview
- Visualize simulation results in Paraview
Acknowledgements
This project was partially developed during the Jupyter Community Workshop “Building the Jupyter Community in Musculoskeletal Imaging Research” sponsored by NUMFocus.
Project details
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.