Table of contents
- Project Summary
- Application highlights
- Getting started
- Citing GIBBON
- Code of conduct
- Road Map
GIBBON (The Geometry and Image-Based Bioengineering add-On) is an open-source MATLAB toolbox by Kevin M. Moerman and includes an array of image and geometry visualization and processing tools and is interfaced with free open source software such as TetGen, for robust tetrahedral meshing, and FEBio for finite element analysis. The combination provides a highly flexible image-based modelling environment and enables advanced inverse finite element analysis.
- Computer Aided Design (CAD) tools
- Surface meshing tools
- Volumetric meshing
- Lattice structures
- Finite element analysis
GIBBON offers image filtering and smoothing methods, and has a graphical user interface for 3D image segmentation (
HELP_imx.m). The segmented image data can be converted to 3D surface models (
DEMO_imx_levelset_surface_compare) which can be meshed for FEA (
Using GIBBON, geometry can be imported from common mesh based CAD files (such as STL,
HELP_import_STL). For generating geometries within MATLAB®, GIBBON also provides several CAD-style commands such as polygon rounding (
HELP_filletCurve), revolution (
HELP_polyRevolve), extrusion (
HELP_polyExtrude), and sweeping and lofting (
HELP_sweepLoft). Simple geometries such as spheres (
HELP_geoSphere), boxes (
HELP_quadBox), platonic solids (
HELP_platonic_solid), and rhombic dodecahedra (
HELP_rhombicDodecahedron) can also be directly created using GIBBON.
2D multi-region triangular meshing (e.g.
HELP_multiRegionTriMeshUneven2D), resampling meshes geodesically (
DEMO_geodesic_remeshing), smoothing (
DEMO_surface_smooth_methods), and surface mesh refinement (e.g.
HELP_subQuad), mesh type conversions (e.g.
HELP_quad2tri), and mesh dual computation (
HELP_patch_dual). Geometries can also be exported to the STL format e.g. for computer aided manufacture and 3D printing.
Tetrahedral meshing (and constrained Delaunay tessellation) of multi-region domains is enabled through an interface with the TetGen package (
HELP_constrainedDelaunayTetGen). Hexahedral meshes for some geometry types can be directly coded (e.g. spheres
HELP_hexMeshBox and lattices
HELP_element2HexLattice). For general input surfaces multi-region mixed tetrahedral-hexahedral meshing is also available (e.g.
One method to generate surface geometry for lattices is the use of triply-periodic functions (
HELP_triplyPeriodicMinimal). Functions to convert element descriptions, such as tetrahedral and hexahedral elements, to lattice structures have also been implemented (
HELP_element2HexLattice). These allow for the creation of 3D boundary conforming lattice structures on arbitrary input geometry. Exporting of hexahedral elements is also supported allowing for FEA on the created lattice structures (
GIBBON interfaces with the free software FEBio for FEA (source code available on FEBio website). GIBBON can be used as a pre- and post- processor for FEBio as it enables code-based development of meshes, boundary conditions, and input files. FEBio files can be directly exported based on dedicated MATLAB® structures (
HELP_febioStruct2xml). Furthermore, GIBBON can be used to start and control FEBio simulations. As such, iterative and inverse FEA (e.g. based on MATLAB® optimization routines) is also enabled. All
DEMO_febio_... files are FEBio demos, e.g.
DEMO_febio_0001_cube_uniaxial is a simple uniaxial loading example, and
DEMO_FEBio_iFEA_uniaxial_01 is an example of inverse FEA.
The image below is for large strain analysis of a twisting bar and stems from the demo
DEMO_FEBio_bar_twist. Other demos cover tension, compression, shear, applied forces, applied pressures, applied displacements, bending, poroelasticity, dynamic and viscoelastic analysis, contact and indentation problems, multi-generational materials for pre-load analysis.
DEMO_FEBio_... demos are for the older febio_spec 2.0 while the
DEMO_febio_... demos are for the latest febio_spec 2.5.
GIBBON expands the standard MATLAB® visualization capabilities by adding 3D image and voxel visualization (
HELP_sliceViewer), meshed geometries (
HELP_meshView), finite element models (
HELP_element2patch), and colormapped vector data (
HELP_quiverVec), and all visualization methods enable multiple colormaps to be used in each figure or axis window. Furthermore GIBBON offers a custom figure window
cFigure containing 3D rotation options (
HELP_vcw) that mimic CAD behavior of 3D scene rendering, and high quality figure exporting options (
HELP_efw). Advanced graphics animation creation and exporting capabilities through a figure window based GUI are also enabled (
The steps below guide you through a streamlined installation procedure using the
*If you prefer manual installation do the following: 1) Add the GIBBON folder (with subfolders) to the path and save the path definitions, 2) Run
createHelpDemoDocumentation.m to integrate the help and documentation, 3) For the 3rd party packages: 3a) Add the
export_fig folder to the path and save the path definitions, 3b) Go to the config folder in ../GIBBON/config and edit the FEBioPath.txt file to contain the full path to the FEBio executable
1. Get a copy of GIBBON
To use GIBBON you need to create a copy on a local directory on your machine. Obtain a copy by downloading and unzipping the latest zip file or clone GIBBON instead e.g. using:
git clone https://github.com/gibbonCode/GIBBON.git. You can place the GIBBON folder anywhere on your machine, however, MATLAB (and the 3rd party packages listed below) may have file permission limitations for some locations which you may need to address*.
* For instance, some of GIBBON's features, such as those associated with TetGen and FEBio, regularly create and delete temporary files. As such MATLAB (and the 3rd party packes) should have full permissions for these folders. First of all users should make sure MATLAB has full (e.g. read/write/delete) permissions for the entire GIBBON folder (and its sub-folders). On some platforms the 3rd party packages require special treatment. For instance some OSX users have found it necessary to give tetGen or FEBio particular file permissions. For instance in the case of TetGen related features using
git update-index --chmod=+x path/to/tetgen.
2. Installing and setting up 3rd party packages
Below is a list of 3rd party packages that are required for full functionality. Download and install them if needed (some are already included with GIBBON). Skip this step if finite element analysis (with FEBio) and figure exporting (with export_fig) are not desired.
||FEBio is a finite element solver and is used in GIBBON for all finite element analysis. Use of FEBio is featured in the many
||No||Get via GitHub / Download zip|
||Is used for tetrahedral meshing (and possibly constrained 3D Delaunay tessellation). See for instance
||Yes||For other versions: TetGen website|
2. Install GIBBON
installGibbon.m the GIBBON, FEBio, and export_fig path definitions will be added and saved to MATLAB. The help and documentation will also be integrated. Once finished you will be asked to restart MATLAB.
installGibbon.m can be found in the main GIBBON folder.
Access the integrated help
- To access the help documentation from MATLAB click on the HELP browser then click o
Supplemental Softwareas shown below. This will open the toolbox help and documentation which is now searchable and integrated just like the rest of MATLAB's help and documentation.
- You may also use
gdoc(similar to MATLAB's doc) to access GIBBON documentation. For instance for help on
gdoc im2patch. This will search the integrated help for im2patch and display the results.
Where to find functions and the executable help and demo files
libfolder contains all GIBBON's functions and the
lib_extcontains "external functions" i.e. functions developed by others included with GIBBON. The
docsfolder contains the help&documentation, and demo files which when "published" (using MATLAB's publish functionality) create the .html documentation files (found in
docs/html) which are integrated in MATLAB.
The source for the help information for any function
HELP_functionName, and the source for demos have
DEMO_as part of the name. Therefore if one is interested in reproducing or starting off from codes in the help and documentation simply start typing code names starting in
DEMO_in the MATLAB command window, e.g.
HELP_ind2patchcan be used to generate the help information for the
ind2patchfunction. Users can start editing the file by typing
open HELP_ind2patchin the command window. By publishing (MATLAB publish functionality) the HELP_ or DEMO_ files .html files are created in the
docs\htmlfolder. As such if users alter/contribute code in the
libfolder and generate associated
DEMO_files, new help and documentation is added. For new help and documentation to become known and visible to MATLAB run the
createHelpDemoDocumentationfunction and restart MATLAB.
Many of the
DEMO_files focus on the use of FEBio. The demo
DEMO_FEBio_block_uniaxial_compressionfor instance features a simple cube that undergoes a 30% compression. Other demos focus on different load types, single versus multi-step analysis, different materials and inverse analysis (e.g.
DEMO_FEBio_iFEA_uniaxial_01). Demos with
DEMO_FEBio_...are for the old febio_spec 2.0 format. The newer demos with
DEMO_febio_...are for the latest febio_spec 2.5.
GIBBON's core functionality can be tested by running
testGibbon('help','test'); for running the demo or help files only.
GIBBON is currently developed and tested using the most recent version of MATLAB (or the latest pre-release) and has been tested on Windows 10, Ubuntu 14.10/16.04/17.10, and Mac OS. Most of GIBBON's functionality is compatible with older MATLAB versions, especially MATLAB R2014a and newer (Delaunay tessellation and toolbox help integration are amongst things that have undergone large changes). Please inform the developers (or open an issue) if a particular function does not work for your MATLAB environment. It is likely that codes can be easily altered to work for your version.
A large portion of GIBBON's functionality does not rely on special MATLAB toolboxes. However some functions do. Here is a list of toolboxes which appear to be used in GIBBON:
- Image Processing Toolbox
- Bioinformatics Toolbox
- Statistics and Machine Learning Toolbox
- Computer Vision System Toolbox
- Neural Network Toolbox
- Symbolic Math Toolbox
- Curve Fitting Toolbox
- Parallel Computing Toolbox
- Mapping Toolbox
Geodesic remeshing (
DEMO_geodesic_remeshing) currently only works for Windows OS, for other operational systems special mex file compilation is required or an alternative (experimental function) is used instead.
GIBBON is provided under: . The license file is found on the GitHub repository.
Moerman, (2018). GIBBON: The Geometry and Image-Based Bioengineering add-On. Journal of Open Source Software, 3(22), 506, https://doi.org/10.21105/joss.00506