U.S. flag An official website of the United States government

BoneJ Headless: An Automated Python Tool for Bone Microstructure Analysis

Catalog of Regulatory Science Tools to Help Assess New Medical Devices 


This regulatory science tool is a lab method that computes bone microstructure metrics to characterize bone morphology and skeletal geometry.


Technical Description

The BoneJ Headless tool is a Python package that computes microstructure metrics to characterize bone morphology and skeletal geometry. BoneJ Headless uses Fiji to automatically process binary images using command line and scripting without the need to manually operate a Graphic User Interface (GUI). It allows for substantially faster processing of large datasets, access to Python libraries for image processing, and additional functions to optimize input parameters to provide stable/optimal results for specific functions.

Figure 1

Figure 1. Fiji is a superset of the ImageJ open-source image analysis software, in which popular plugins are pre-installed. BoneJ is an ImageJ plugin. BoneJ Headless is a bridge between BoneJ functionalities and the Python ecosystem. The Python ecosystem is expansive and supports many packages for image analysis. However, due to incompatibility between Python packages and Java, functions in BoneJ are difficult to access without a complex chain of image saving, loading, conversions, and other manual operations. BoneJ Headless automates this workflow and allows the user to compute standardized microstructure metrics available in BoneJ directly from Python.

Fiji is an open-source image processing software with several downloadable plugins for image analysis. One of these plugins is BoneJ, which is capable of computing several common microstructure metrics [2]. BoneJ Headless is a Python wrapper that calls Fiji on a user’s system using command line operations. Once Fiji is called, BoneJ is initialized to calculate metrics. All metrics within BoneJ have been wrapped by BoneJ Headless. The metrics were divided into two categories. The first are primary metrics commonly used in microstructure metric studies, while the second include metrics specific to the BoneJ plugin that are not common metrics used in literature. The primary metrics include measurements such as trabecular thickness and spacing. Area Volume Fraction is a ratio expressing the ratio of trabecular bone to the volume of total bone in the image. Anisotropy quantifies the directionality of trabecular bone. Ellipsoid Factor quantifies the rod/plate geometry of a bone. Connectivity assesses the number of connected structures in the image. The connected structures are representative of trabeculae in a trabecular network. The secondary metrics include measurements such as Analyze Skeleton, an evaluation of the labelled branches and junctions of the topological skeleton., and Fractal Dimension, a measure of the geometric complexity and self-similarity of the trabecular structures. Intertrabecular Angles measures the angles between trabecular structures. Surface Area is a measure of the input image’s surface area. While not a metric the Skeletonize function is an important intermediate step used for computing Analyze Skeleton and Intertrabecular Angles.

The input to BoneJ Headless are binary 8-bit NumPy arrays representing segmentation of bone microstructure. The array is subsequently written to a NRRD file so the local instance of Fiji can open it. Thickness, Spacing, Anisotropy, Ellipsoid Factor, Area Volume Fraction, and Connectivity are the most commonly computed metrics in the literature and have been labelled as primary functions [1]. The remaining functions are labelled as secondary functions, due to their being less commonly used in literature. All input parameters available in the original BoneJ plugin can be adjusted in BoneJ Headless.

Input parameters for BoneJ Headless functions vary, with all functions requiring the user to set the voxel size of the image in microns, and location of the user’s Fiji installation. Metrics such as Area Volume Fraction and Connectivity Density only return numerical values as a result, and require no other inputs to be set. Some metrics have specific input parameters that must be optimized for performance and return of stable results. Examples include Anisotropy and Ellipsoid Factor. BoneJ Headless includes functions to automatically tune these parameters in Python using grid search. This enables the user to gauge the convergence and/or optimality of some parameters.

The outputs are dependent on the specific microstructure metrics. Each function will output a numerical metric value to the console. Metrics such as Thickness and Spacing will output an image that displays the thickness/spacing if the user chooses to. Additional metrics that output images include Ellipsoid Factor, Skeleton, and Analyze Skeleton. All of these image displays are optional. Certain metrics have additional values that are optional to compute. For example, users can choose to display eigenvectors and eigenvalues used to compute the final result of Ellipsoid Factor or mean intercept vectors used to compute Anisotropy.

The tool is relevant to medical device developers, specifically in imaging applications and measurements of bone health, along with orthopedic researchers. These individuals will be able to easily integrate BoneJ Headless for fast and thorough quantitative characterization of bone microstructure. BoneJ Headless is mainly intended for micro-computed tomography (CT) but can be applied to images scanned with any other type of CT scanners.

Intended Purpose

The tool is relevant to medical device developers specifically in imaging applications and measurements of bone health.

BoneJ Headless is a Python tool that streamlines the calculation of microstructure metrics for large bone image datasets. BoneJ functionalities can be accessed through a GUI but is challenging to use for large batches of images due to limited scripting capability in Fiji and is hard to integrate with other Python-based open source image analysis packages. Any of the microstructure metrics can be easily calculated for an entire dataset and output as a table to a user specified location. BoneJ Headless saves time with its automation, it is also able to build more functional scripts due to integration with other Python packages. This tool can be used in place of micro-CT vendor software, and the GUI form of ImageJ. This open-source tool makes reference implementation of metrics in BoneJ more accessible for medical device developers and researchers in bone health. Developers of micro-CT systems can use BoneJ Headless as part of their development process, while bone health researchers are able to characterize and quantify the trabecular microstructure of their samples.


BoneJ Headless was tested to confirm the values being returned by the Python wrapper are identical to the values returned by BoneJ with the GUI. All of the metrics were computed on several different test cases: data from lumbar vertebrae, data from shrew trabecular bone, emu trabecular bone, and digital phantoms of trabecular bone microstructure. The human lumbar vertebrae data were thresholded by the BoneJ Headless team. The shrew and emu bones were provided by the BoneJ2 developer team as test images and are thresholded images of trabecular bone microstructure from the respective animals. Lastly, trabecular bone digital phantoms were developed through custom bone modeling software to represent bone microstructure. The animal bones and human bones were scanned with differing system parameters and microCT resolution. All of the metrics returned identical values except for Anisotropy and Ellipsoid Factor, as these two metrics are computed stochastically. To verify agreement of these two metrics, shrew sample, and lumbar vertebrae sample were run 5 times with BoneJ and 5 times with BoneJ Headless. Ellipsoid Factor showed a variation of less than 5% for both BoneJ and BoneJ Headless. Anisotropy showed a variation of less than 1.5% for BoneJ and BoneJ Headless.

Anisotropy and Ellipsoid Factor were additionally tested for metric convergence. Both of these metrics have an assortment of input variables that must be specifically tuned for a sample to provide stable results. An anisotropy result is accurate if a convergence is observed for the input parameters. The user must plot the different input values alongside the returned anisotropy value. If the anisotropy value no longer increases with the input metrics, convergence is achieved. For Ellipsoid Factor, the filling percentage value returned by the metric must be greater than 90% to be considered a stable result. A filling percentage less than 90% indicates an inaccurate Ellipsoid Factor value [3]. This must be carefully tuned as an object can be overfilled and return large filling percentages yet still have an inaccurate Ellipsoid Factor value. Users must observe the plot returned by the function to assess if the filling is sufficient as well.


  • (Quality of Segmentation) The results are dependent on the quality of segmentations of trabecular bone from the cortical bone and the resolution of micro-CT images. Poorly thresholded images may not account for all of the structures and yield inaccurate metric results. Users should make sure they have carefully segmented images prior to computing the output metrics. Low resolution images may require image processing.
  • (Visualization of Some Intermediate Outputs) BoneJ has the option to display images in a 3D view such as a point cloud of anisotropy. These results were unable to be saved and exported without GUI dependence.
  • (Operating System) BoneJ Headless currently is only configured for Linux OS and requires an installation of Fiji with BoneJ to operate.
  • (Speed) Despite BoneJ Headless being much faster than using BoneJ with GUI, there can be issues with computation speed. BoneJ Headless opens a new instance of Fiji and rewrites the input binary NumPy array to an NRRD file each time a metric is ran. This can add additional processing time to compute metrics. The speed of the metrics is dependent on image size. Metrics will also be slower if the user chooses to return plots for specific metrics such as Ellipsoid Factor or Thickness. Ellipsoid Factor is the slowest metric and is dependent on how finely the user chooses to sample the image.
  • (Input Parameter Sensitivity) Anisotropy and Ellipsoid Factor are very sensitive to input parameters. A user must first determine the optimal parameters for these metrics to receive stable results. Anisotropy has a convergence function included from the developers to vary results. Ellipsoid Factor has issues with robustness than can make convergence difficult.

Supporting Documentation

Tool GitHub: Bone J Headless User Manual: Welcome to BoneJ Headless Documentation!


  1. Bouxsein, Mary L, Stephen K Boyd, Blaine A Christiansen, Robert E Guldberg, Karl J Jepsen, and Ralph Müller. 2010. “Guidelines for Assessment of Bone Microstructure in Rodents Using Micro-Computed Tomography.” Journal of Bone and Mineral Research 25 (7): 1468–86. https://doi.org/10.1002/jbmr.141 .
  2. Domander, Richard, Alessandro A Felder, and Michael Doube. 2021. “BoneJ2 - Refactoring Established Research Software.” Wellcome Open Research 6 (February): 37. https://doi.org/10.12688/wellcomeopenres.16619.1 .
  3. Doube, Michael. 2015. “The Ellipsoid Factor for Quantification of Rods, Plates, and Intermediate Forms in 3D Geometries.” Frontiers in Endocrinology 6 (February). https://doi.org/10.3389/fendo.2015.00015 .


For more information