Package: ciclope
ciclopeComputed 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.ciclopeprovides fully open-source pipelines from microCT data preprocessing to microFE model generation, solution and postprocessing.InstallationFor mesh generation,cicloperequirespygalmesh, a Python frontend toCGAL.
Follow theinstallation procedureforCGALandEigen.
After that, install pygalmesh with pip or condaconda install -c conda-forge pygalmeshAfter installing pygalmesh, you can installciclopeusing pip. The flag[all]will install optional dependencies needed to run full pipelines and examples.pip install ciclope[all]Some examples will requireDXchange. You can install it withcondainstall-cconda-forgedxchangeTestingTo verify your installation checkout this repository and run the tests with the commandcd test
python -m unittest -v test_ciclope.run_testsHow to contributeIf you want to contribute to this project, please installciclopefollowing thedevelopment guide.Usageciclopepipelines can be run from the command line as a script. Scroll down and take a look at theExamplesfolder for this type of use.
To view the command line script help runciclope -hTo useciclopewithin python, import the package withimportciclopeImage pre-processingciclope.utilscontains functions that help you read and pre-process 3D datasets for FE model generation.Read 3D CT dataset stored as stack of TIFFsfromciclope.utils.recon_utilsimportread_tiff_stackinput_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_stackreads all TIFF files (slices) contained in theinput_filefolder. The volume is stored in a 3Dnumpy.ndarraywith size[slices, rows, columns].Segment and remove unconnected voxelsfromskimageimportmorphologyfromciclope.utils.preprocessimportremove_unconnectedBW=data_3D>142# fixed global thresholdBW=morphology.closing(BW,morphology.ball(2))# optional stepL=remove_unconnected(BW)Mesh and FE model generationIf you already have a mesh file, you can skip the mesh generation steps and useciclopewith 3Dmeshioobjects.voxel-FEGenerate unstructured grid mesh of hexahedra (voxels)importciclopemesh=ciclope.core.voxelFE.vol2ugrid(data_3D,vs)Generate CalculiX input file.INPforvoxel-FEmodel of linear elastic compression testinput_template="./input_templates/tmp_example01_comp_static_bone.inp"ciclope.core.voxelFE.mesh2voxelfe(mesh,input_template,'foo.inp',keywords=['NSET','ELSET'])tetrahedra-FEGenerate mesh of tetrahedra.ciclopeusespygalmeshfor tetrahedra mesh generationmesh=ciclope.core.tetraFE.cgal_mesh(L,vs,'tetra',max_facet_distance=0.2,max_cell_circumradius=0.1)Generate CalculiX input file.INPfortetrahedra-FEmodel of non-linear tensile testinput_template="./input_templates/tmp_example02_tens_static_steel.inp"ciclope.core.tetraFE.mesh2tetrafe(mesh,input_template,'foo.inp',keywords=['NSET','ELSET'])Postprocessingciclope.utils.postprocess.paraviewplotcallsParaViewto generate and save plots of a chosen model scalar field.Add path to your ParaView installation withimportsyssys.path.append('~/Applications/ParaView-5.9.0-RC1-MPI-Linux-Python3.8-64bit/lib/python3.8/site-packages')Plot midplanes of the vertical displacement fieldUD3ciclope.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 stressS_Misesciclope.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 theexamples sectionfor more examples of 3D data and results visualization.ciclope pipelineThe following table shows a general pipeline for FE model generation from CT data that can be executed from the command line with theciclopescript:#StepDescriptioncommand line script flag1.Load CT data2.Pre-processingGaussian smooth--smoothResize image-rAdd embedding(not implemented yet)Add caps--caps3.SegmentationUses Otsu method if left empty-tRemove unconnected voxels4.MeshingOuter shell mesh of triangles--shell_meshVolume mesh of tetrahedra--vol_mesh5.FE model generationApply Boundary ConditionsMaterial mapping-m,--mappingVoxel FE--voxelfeTetrahedra FE--tetrafeNotes on ciclopeTetrahedra meshes are generated withpygalmesh(a Python frontend toCGAL)High-resolution surface meshes for visualization are generated with thePyMCubesmodule.All mesh exports are performed with themeshiomodule.ciclopehandles the definition of material properties and FE analysis parameters (e.g. boundary conditions, simulation steps..) through separate template files. The foldersmaterial_propertiesandinput_templatescontain a library of template files that can be used to generate FE simulations.Additional libraries ofCalculiXexamples and template files can be foundhereandhereExamplesExample 1: voxel-uFE model of trabecular bone; linear compression testThe 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 --verboseThe example shows how to:Load and inspect microCT volume dataApply Gaussian smoothResample the datasetSegment the bone tissueRemove unconnected clusters of voxelsConvert the 3D binary to a voxel-FE model for simulation in CalculX or AbaqusLinear, static analysis; displacement-drivenLocal material mapping (dataset Grey Values to bone Tissue Elastic Modulus)Launch simulation in CalculixConvert Calculix output to .VTK for visualization in ParaviewVisualize simulation results in ParaviewExample 2: tetrahedra-uFE model of trabecular bone; linear compression testThe 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.inpExample #3 - tetrahedra-FE model of embedded tooth; compression test; heterogeneous materialsExample #4 - non-linear tetrahedra-FE model of stainless steel foamThe 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 -vThe example shows how to:Load and inspect synchrotron microCT volume dataApply Gaussian smoothResample the datasetSegment the steelRemove unconnected clusters of voxelsGenerate volume mesh of tetrahedraGenerate 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 AbaqusNon-linear, quasi-static analysis definition: tensile test with material plasticity. For more info visit:github.com/mkraska/CalculiX-ExamplesLocal material mappingLaunch simulation in CalculixConvert Calculix output to .VTK for visualization in ParaviewVisualize simulation results in ParaviewAcknowledgementsThis project was partially developed during the Jupyter Community Workshop“Building the Jupyter Community in Musculoskeletal Imaging Research”sponsored byNUMFocus.