Package: bonemapy
An ABAQUS plug-in to map bone properties from CT scans to 3D finite element bone/implant models. This is typically used for applying heterogeneous material properties to the
bone model.Developed together withpyvXRAYandBMDanalyseto provide tools for preparation and post-processing of bone/implant computer models.Copyright 2022, Michael Hogg (michael.christopher.hogg@gmail.com)MIT license - See LICENSE.txt for details on usage and redistributionFigure 1: FE model of scapula showing meshed part (left) and odb results file showing applied bone properties on several slices through the part (right)RequirementsPlease note that:ABAQUS is a commerical software package and requires a license fromSimuliaThe authors of bonemapy are not associated with ABAQUS/Simuliabonemapy uses both Python and numpy, which are built in to ABAQUSABAQUS still uses Python 2.7 which is not longer supported by the Python community. When installing Python libraries, from PyPi for example, the user must be careful to install only versions of packages that still support Python 2.7Software requirementsABAQUS >= 2021setuptools == 41.1.0pip == 19.2.3pydicom == 1.4.2Model setup requirementsThe model must contain only tetrahedral elements. All 3D stress tetrahedral elements are supported (ABAQUS element types C3D4, C3D4H, C3D10, C3D10H, C3D10M, and C3D10MH)Requires that the model coordinates match the CT scan coordinates e.g. the bone model cannot be shifted from its original positionCT informationIfSlicer3Dhas been used to extract the bone geometry, then the geometry should be exported with respect to the RAS coordinate system, not the LPS coordinate system which is the default.All CT slices should be located in the same directory. This directory must not contain any other file types or slices belonging to other stacksFortran compilerThe output of bonemapy is a text file that is used by Abaqus Fortran user subroutine USDFLD to apply the bone properties to the part instances during the simulation. A Fortran compiler is required for this. Instructions on how to setup the Intel oneAPI toolkit on Windows, which contains the Intel Fortran compiler, can be foundhere.The example Abaqus user subroutines provided here use thefreeformat, not the traditionalfixedformat. This will likely require a small modification to thecompile_fortranvariable in the Abaqus environment file (.env). The fix is to add‘/free’,on the next line after the‘ifort’,entry.Installationa. Install setuptools and pipTo facilitate the installation of 3rd party libraries, the first thing to do is to installsetuptoolsandpip. Choose the versions that were released around July 2019, which corresponds to the build date of the Python in Abaqus 2021.DownloadsetuptoolsandpipfromPyPiThe files to download are:setuptools-41.1.0.zippip-19.2.3.tar.gzUnpack these files and browse to the directory wheresetup.pyis located, first for setuptools and then for pip:# Browse to folder 'setuptools-41.1.0' and install via
>>> abaqus python setup.py install

# Browse to folder 'pip-19.2.3' and install via
>>> abaqus python setup.py installCheck thatsetuptoolsandpiphave been installed into the Abaqus python installation using the command below. If installed, you should be able to see it in the list printed to the screen:>>> abaqus python -m pip listb. Install pydicomNow that pip is installed, you can install pydicom using the command below. Note that version 1.4.2, not the latest (2.3.0 at the time of writing) is installed to be compatible with Python 2.7:>>> abaqus python -m pip install pydicom==1.4.2c. Installation of bonemapy plug-inbonemapy is an ABAQUS plug-in. To install any ABAQUS plug-in, the plug-in folder must be copied to one of the ABAQUS plug-in directories, of which there are several options.To install bonemapy into ABAQUS:Download the latest bonemapy zip file from thereleases pageor fromPyPiUnzip the folder to a convenient location. This folder will typically be calledbonemapy-x.x.xCopy thebonemapysub-folder to theabaqus_pluginsdirectory within your ABAQUS installation. For Abaqus 2021 two alternative locations on Windows areC:\SIMULIA\CAE\plugins\2021C:\Users\user_name\abaqus_plugins, whereuser_nameshould be replaced with your Windows user nameUsing bonemapy in ABAQUS/CAEOpen the model within ABAQUS/CAE (not ABAQUS/Viewer)Launch the bonemapy GUI by going to the Menubar at the top of the ABAQUS/CAE window and selecting:Plug-ins --> bonemapy --> Map HU from CTComplete the required inputs in the GUI, which include:The model and set names of the bone regionThe location of the directory containing the CT stackThe base name of all output filesClick OK to run bonemapyLook at the Message Area at the bottom of the ABAQUS/CAE window for messages. On completion ‘Finished’ will be shown.Outputbonemapy produces the following output:A text file containing the HU values. This has a format similar to:instanceName elementNumber IntegrationPointNumber HUvalueThis file is space delimited so it can easily be read by Fortran code such as that used by ABAQUS user subroutines USDFLD / UMAT for applying mechanical properties to models.An odb file of the selected bone region with a fieldoutput of the mapped HU values. This can be used for visually checking that bonemapy has mapped the HU values correctly.ExamplesExample job files can be found in the [examples folder](examples). Each example should contain an Abaqus job file (.inp), a fortran user subroutine (.f) and a text file containing the HU values (i.e. HUvalues.txt).To run the shoulder example from the command line, the following command can be used:>>> abaqus job=shoulder user=USDFLD.f cpus=1Fieldoutputs SDV1, SDV2 and FV1 are created to view the HU values, apparent bone density, and elastic modulus, respectively.HelpIf help is required, please open an Issue or a Pull Request on Github.