ciclope 2.0.3

Computed Tomography to Finite Elements

ciclope

Computed Tomography to Finite Elements.

Micro Finite Element (microFE) models can be derived from micro Computed Tomography (microCT) 3D images to non-destructively assess mechanical properties of biological or artificial specimens.
ciclope provides fully open-source pipelines from microCT data preprocessing to microFE model generation, solution and postprocessing.

Installation

Anaconda 2025.12 or newer is required.

1. Create a new conda environment

conda create -n ciclope python=3.10

2. Activate the environment

conda activate ciclope

3. Install IPyKernel and register the ciclope kernel to be seen by the main Jupyter installation

conda install ipykernel

4. For mesh generation, ciclope requires pygalmesh, a Python frontend to CGAL. Pygalmesh installed via (ana)conda from conda-forge channel already ships with a CGAL binary installation.

conda install -c conda-forge pygalmesh

5. Install Ciclope

pip install ciclope[all]

A minimal version of ciclope (voxelFE pipelines only) can be installed without CGAL, Eigen, and pygalmesh following instructions in the development guide

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.

Read 3D CT dataset stored as stack of TIFFs

from ciclope.utils.recon_utils import read_tiff_stack

input_file = './test_data/LHDL/3155_D_4_bc/cropped/3155_D_4_bc_0000.tif'

data_3D = read_tiff_stack(input_file)
vs = np.ones(3) * 0.06  # voxelsize [mm]

read_tiff_stack reads all TIFF files (slices) contained in the input_file folder. The volume is stored in a 3D numpy.ndarray with size [slices, rows, columns].

---

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)

Mesh and FE model generation

If you already have a mesh file, you can skip the mesh generation steps and use ciclope with 3D meshio objects.

voxel-FE

Generate unstructured grid mesh of hexahedra (voxels)

import ciclope
mesh = ciclope.core.voxelFE.vol2ugrid(data_3D, vs)

Generate CalculiX input file .INP for voxel-FE model of linear elastic compression test

input_template = "./input_templates/tmp_example01_comp_static_bone.inp"
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 CalculiX input file .INP for tetrahedra-FE model of non-linear tensile test

input_template = "./input_templates/tmp_example02_tens_static_steel.inp"
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])

See the Jupyter Notebooks in the examples section for more examples of 3D data and results visualization.

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.
  • Additional libraries of CalculiX examples and template files can be found here and here

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.