diku-dk / open-full-jaw

A dataset and python-based pipeline for "An open-access dataset and nearly-automated pipeline for generating finite element models of human jaw".

Open-Full-Jaw Dataset Repository

An open-access dataset and nearly-automated pipeline for generating finite element models of the human jaw ( link to the article )

Table of contents

• Motivation
• Content of the repository
• How to cite us
• How to install
• How to use
• Features
• Funding
• Acknowledgements

Motivation

Developing accurate patient-specific computational models of the human jaw acquired from cone-beam computed tomography (CBCT) scans is labor-intensive and non-trivial. In addition, it involves time-consuming unreproducible manual procedures. Hence, we share an open-access dataset of 17 patient-specific computational models of human jaws and the utilized pipeline for generating them.

Content of the repository

This repository comprises 17 patient-specific computational models of human jaws (including the mandible, maxilla, their associated teeth, and PDL meshes, as well as teeth principal axes) and the utilized code for generating them.

1. Dataset

⚠️ Please make sure to install git lfs on your system before cloning the repository.

The dataset includes:

1. Clinically validated segmented geometries in form of unprocessed dense surface meshes that can be imported to different meshing tools
2. The quality and adaptive volumetric meshes to be used directly in FE simulations
3. The reduced surface meshes with no undesired gaps/penetrations
4. The principal axes of every patient's teeth that provides great information for setting up different scenarios automatically
5. The automatically generated FEM files for tipping scenario and a biting scenario

2. Code for reproducibility of dataset

6. The python code utilized for generating the volumetric meshes and producing the simulation files is shared in this repository. A summary of the pipeline is illustrated as follows

High resolution PDF format: graphical abstract

How to cite us

If you use the content of this repository please consider to cite us as below,

@article{gholamalizadeh2022open,
  title     = {Open-Full-Jaw: An open-access dataset and pipeline for finite element models of human jaw},
  author    = {Gholamalizadeh, Torkan and Moshfeghifar, Faezeh and Ferguson, Zachary and Schneider, Teseo and Panozzo, Daniele and Darkner, Sune and Makaremi, Masrour and Chan, Fran{\c{c}}ois and S{\o}ndergaard, Peter Lampel and Erleben, Kenny},
  journal   = {Computer Methods and Programs in Biomedicine},
  volume    = {224},
  pages     = {107009},
  year      = {2022},
  publisher = {Elsevier}
}

How to install

Setting up the conda environment and the required packages

The first step is to set up your conda environment for running the jupyter notebook as below:

conda create -n fulljaw
conda activate fulljaw
conda config --add channels conda-forge

Next, install the following packages in the fulljaw environment:

conda install igl
conda install jupyter
conda install meshio
conda install meshplot
conda install -c anaconda scikit-image

Other Dependencies

‼️ You need to install PyMesh by cloning the repository and building it on your machine.

‼️ Note that our pipeline uses fTetWild as a backbone for volumetric mesh generation. Therefore, you need to install the fTetWild by cloning the repository and building it on your machine in a desired directory.

How to use

First, activate the environment, then run jupyter notebook:

conda activate fulljaw
jupyter notebook

Now you can open and run the pipeline.ipynb, which is an interactive python code, shared in the "src" folder, for reproducing the models of this dataset or generating new models for your own input data.

⚠️ Make sure to update the "path_ftetwild" variable in pipeline.ipynb with the path of fTetwild's binary file, e.g.,

path_ftetwild = '/your_desired_directory/fTetWild/build/FloatTetwild_bin'

Features

Params of step1 (Preprocessing and Smoothing)

• preprocess_bone_eps: The epsilon value for fTetWild used in preprocessing of the bone mesh.
• preprocess_bone_l: The edge_length value for fTetWild used in preprocessing of the bone mesh.
• preprocess_teeth_eps: The epsilon value for fTetWild used in preprocessing of the teeth mesh.
• preprocess_teeth_l: The edge_length value for fTetWild used in preprocessing of the teeth mesh.
• preprocess_smooth_bone_iter: The number of iterations for smoothing the bone.
• preprocess_smooth_bone_stepsize: The step size used for smoothing the bone.

Params of step2 (Gap Generation)

• gap_thickness: The gap thickness which indicates the average width of the PDL layer.

Params for step3 (PDL Rim Generation)

• rim_distance_rest: The gap distance used in for selecting the base on all teeth sockets except for molars.
• rim_distance_molars: The gap distance used in for selecting the base on molars' sockets.
• rim_thickness_factor: The constant which will be multiplied by the distance between two surfaces.
• rim_trim_iter: The number of times the trimming step should be performed on the detected base.
• rim_smooth_iter_base: The number of times the smoothing step should be performed on the boundary of the detected base.
• rim_smooth_iter_extruded_base: The number of times the smoothing step should be performed on the boundary of the extruded base.

Params for step4 (Multi-Domain Volumetric Meshing)

• volume_mesh_eps: The epsilon value for fTetWild in multi-material meshing step.
• volume_mesh_l: The edge_length value for fTetWild in multi-material meshing step.
• volume_mesh_json_path: The directory where the json file for CSG operation will be stored.

Params for step5 (Tetrahedra Filtering)

• tet_filtering_dist: The distance used for filtering the tetrahedra to get the intersection of teeth and bone hollows.

Params for step6 (Simulation Setup)

Summery of params and their default values:

⚠️ Note that we have used identical values for most of the abovementioned parameters across all patients to prepare the Open-Full-Jaw dataset. Only a few of the parameters marked below (with 🚧 ) were used to adapt the pipeline's result to the patient-specific geometries.

# params for step1( preprocessing and smoothing step)
preprocess_bone_eps  =  1e-4  # fTetWild's default value for the epsilon: 1e-3
preprocess_bone_l    =  0.02  # fTetWild's default value for the ideal_edge_length: 0.02
preprocess_teeth_eps =  1e-4
preprocess_teeth_l   =  0.01
preprocess_smooth_bone_iter  =  10
preprocess_smooth_bone_stepsize  =  0.0005

# params for step2( gap generation step)
gap_thickness        =  0.2
gap_tooth_bone_ratio =  0.5

# params for step3( PDL rim generation step)
rim_distance_rest    =  0.26   🚧 
rim_distance_molars  =  0.28   🚧 
rim_thickness_factor =  1
rim_trim_iter        =  2
rim_smooth_iter_base =  16   🚧
rim_smooth_iter_extruded_base  = 10   🚧

# params for step4( multi-domain volumetric mesh generation step)
volume_mesh_json_path       =  mid_o_dir + 'logical_operation.json'
volume_mesh_output_fname    =  'unified'
volume_mesh_operation_type  =  'union'
volume_mesh_eps             =  2e-4
volume_mesh_l               =  0.05       

# params for step5( tetrahedra filtering step) 
tet_filtering_dist  =  0.3   🚧

# general params for fTetWild
self.verbose_level  =  3
self.max_iter       =  20
self.ftet_path      =  path_ftetwild
self.output_dir     =  mid_o_dir 

Funding

• This project has received funding from the European Union's Horizon 2020 research and innovation program under the Marie Sklodowska-Curie grant agreement No. 764644. This paper only contains the authors' views, and the Research Executive Agency and the Commission are not responsible for any use that may be made of the information it contains.
• This work was also partially supported by the NSF CAREER award under Grant No. 1652515, the NSF grants OAC-1835712, OIA-1937043, CHS-1908767, CHS-1901091, NSERC DGECR-2021-00461 and RGPIN-2021-03707, a Sloan Fellowship, a gift from Adobe Research and a gift from Advanced Micro Devices, Inc.
• The funders had no role in study design, data collection/analysis, publication decision, or manuscript preparation.

Acknowledgements

• We thank 3Shape A/S for providing this study's CBCT scans
• We especially thank 3Shape A/S Dental CAD AI team for their support in the CBCT segmentation and teeth principal axes computations.
• We also thank NYU IT High-Performance Computing for resources, services, and staff expertise.

open-full-jaw's Issues

missing file config.json

Hi !
I am trying to use this software. I can run the full pre-processing steps but can't run the simulation:
import polyfempy
path_config = os.path.dirname(main_dir) + '/config.json'

because the config.json file is missing. Is this supposed to be generated on the run ?

Also, when I run polyfem --help, I get the following Options:

---

-h,--help Print this help message and exit
--max_threads UINT Maximum number of threads
-j,--json TEXT:FILE Simulation JSON file
--hdf5 TEXT:FILE Simulation hdf5 file
-o,--output_dir TEXT:(DIR) OR (PATH(non-existing))
Directory for output files
-s,--strict_validation,--ns{false},--no_strict_validation{false}
Disables strict validation of input JSON
--enable_overwrite_solver If solver in json is not present, falls back to default
--log_level ENUM:value in {trace->0,debug->1,info->2,warning->3,error->4,critical->5,off->6} OR {0,1,2,3,4,5,6}

---

so it seems that the flag --febio is not available. Any thoughts ?

Thanks,
Xulia