BioVoxxel 3D Box
The known BioVoxxel Toolbox functions now improved for 2D and 3D images
BioVoxxel 3D Box (bv3dbox)
REMARK: Please inform me about any issues you encounter!
Most of the known BioVoxxel Toolbox functions now for 2D and 3D images in one place. All functions are heavily based on GPU computing via the fabulous CLIJ2 library. Segmentation output is based stronger on labels (intensity coding of objects) instead of ROIs. Those labels can be equivalently used like ROIs with many CLIJ2 functions. Also label images created via other tools such as MorphoLibJ are suitable inputs for any plugin using labels.
Installation
The BioVoxxel 3D Box are distributed via the BioVoxxel 3D Box update site in Fiji.
Run >Help >Update...- Select
Manage update sites -
The following update sites need currently to be minimally active to be able to use all functionalities of the BioVoxxel 3D Box
- BioVoxxel 3D Box
- clij
- clij2
- clijx-assistant
- clijx-assistant-extensions
- 3D ImageJ Suite
Functionalities
Filtering
Flat Field Correction
The flat field correction allows to correct for uneven illumination including a dark-field (dark current) image subtraction. The dark-field image can also be ommited if unavailable. If the original image which sould be corrected for uneven illumination is a stack, flat-field as well as dark-field images can also be provided as single images. Those will be adapted to the original stack slice number. Otherwise, if they are not single slices, dark-field and flat-field need to have the same dimensions as the image to be corrected. Input images can have 8, 16, or 32-bit. RGB images are not yet supported (will be available in the future as well). The Output image is always 32-bit to account for correct float-point values after image division.
Formula:
\[result = { original - darkfield \over flatfield - darkfield } * { average\;of\;(flatfield - darkfield) }\]
Pseudo Flat Field Correction
The pseudo flat field correction takes a copy of the original image to be corrected and blurs it with a Gaussian Blur filter using the specified radius. If the image is a scaled 3D stack (with indicated units such as µm), the filter will also consider the correct x/y/z scaling ratio and perform the blurring accordingly in 3D space. This way the background created stays undistorted in relation to the original data. If the original image is a time series, slices should be considered independent the blurring can be forced to be done in 2D and correction will be applied slice by slice to the original. The background image can be displayed and for easier adaption of the radius value. The blurring radius should be high enough to eliminate all traces of any original object in the background image. Only different intensity shading must remain. If this is impossible to achieve, the method might not be suitable for that particular type of image. In the case of a 3D image all slices can be checked using the stack slice slider. The output will be 32-bit to account for accurate float-point pixel intensity values. Calculation is done according to the upper formula used for flat-field correction without a dark-field subtraction
Important: this is a non-quantitative optical correction. Intensity values will not be corrected according to any real uneven illumination and are therefore NOT suitable for intensity quantifications anymore! If intensity quantification is desired and uneven illumination needs to be corrected, the Flat Field Correction must be used.
Recursive Filter
A recursive filter repetitively applies the same filter on the previously filtered version of the underlying image. This keepsspecifically for the median filter shape alterations low, perfectly removes noise, homogenizes objects but still keeps border of also small objects better that a median filter with a bigger radius. It also performs efficiently due to the small filter size.
Segmentation
Threshold Check:
A helping tool to better identify suitable histogram-based automatic intensity thresholds, compare them qualitatively and quantitatively. This is based on the publication: Qualitative and Quantitative Evaluation of Two New Histogram Limiting Binarization Algorithms, Brocher J., IJIP (2014).
The Threshold Check allows to compare all implemented Auto Thresholds from ImageJ (by Gabriel Landini) and its counterparts from the CLIJ2 library (by Robert Haase). It uses false color to indicate the following:
blue: non-extracted pixels which are also not part of the ground truth (true negative)cyan: non-extracted pixels which are part of the ground truth (false negative)orangetored: extracted pixels which are NOT overlapping with the ground truth (false positive)orangetoyellow: extracted pixels which are part of the ground truth (true positive)
The ground truth is in this case NOT the perfect, desired outcome but rather the next best estimation. It will also contain unspecific objects (or generally pixels) if the underlying image is not pre-processed by image filtering and/or background subtraction. It just serves as the quickest and direct way of comparing the extraction to an approximation of an acceptable outcome!
The following example image which the segmentation result according to Jaccard and Dice indices in Fiji’s main window are ok but indicate the slight over-segmentation (red pixels) with the chosen Threshold.
The Contrast saturation (%) slider serves to highlight brighter image content and “add” it to the ground truth. Objects of interest should in the best case therefore appear completely in yellow. If parts are highlighted in cyan they are not recognized by the current threshold even though being of interest, while if they show up in orange or red they are picked up by the threshold but are rather undesired.
The Histogram usage field allows to restrict the histogram during threshold calculation by ignoring black or white pixels or both. This can avoid that a big amount of saturated pixels contributes oversized to the final threshold. If “full” is chosen the original histogram is taken into account. The latter is the default setting.
In the ImageJ main window, the status bar shows the corresponding Jaccard Index and Dice Coefficient values for the current setup and comparison of approximated ground truth versus segmentation result are displayed. The closer to 1.0 they are the more more accurate the segmentation will be (in context of the approximated ground truth). The lower they are the lower the relative “segmentation quality”.
If the Contrast saturationvalue is kept fixed a more objective and quantitative comparison of the performance of individual Auto Thresholds can be achieved.
If the user finds a useful threshold the output can be set to either binary with the values 0/255 (ImageJ binary standard), binary 0/1 (CLIJ2 standard) or “Labels” which extracts the the objects filled with unique intensity values to be used as labeled connected components for further analysis (recommended setup).
Currently, stacks will automatically be considered as volume and thresholding is done on the stack histogram to achieve consistent results over the complete stack.
Slice-by-slice thresholding might come up in a future release.
Voronoi Threshold Labeler
The labeler is meant to be used as a image segmentation tool combining image pre-processing using a variety of convolition filters, background subtraction methods, auto thresholding and intensity maxima detection. The latter allows object separation similar to the a watershed algorithm, but will be only effective if Labels is chosen as output. Dependent on the combination of pre-processing. background subtraction, threshold and maxima detection quite variable objects can be extracted from an image.
Parameter meaning and usage:
Image Filter: diverse convolution filter methods to homogenize objects and background for improved background subtraction and object segmentationFilter radius: strength of filtering. Bigger radii homogenize more but increase processing time. Hint: the median filter has a maximum radius of 15Background subtraction: Diverse options to reduce unspecific signal. TopHat is comparable with ImageJ’s Rolling Ball method (>Process >Subtract Background).Background radius: Strength of background homogenization. One can orient on a certain prinziple like, the bigger the objects, the bigger the radius needed.Histogram usage: either the complete histogram can be handed to the thresholding algorithm or a limited one by ignoring black or white or both (black and white) pixels to achive better segmentation results.Threshold method: Automatic intensity threshold to extract basic object areas after the upper pre-processing stepsFill Holes: Closing holes inside objects either 2D (= slice by slice in case of stacks) or 3D.-
Separation method: There are different object separations. Those are meant to be used in exchange for a common Watershed algorithm. The different methods are explained below in the section Label SplitterThe erosion methods are useful for bigger and irregularly shaped objects, while the maxima method performs better for smaller objects. The erosion-based methods ignore the field
Maxima detection radius. Too high spot sigmas will delete smaller objects from the image. Spot sigma: Blurring strength for maxima detection OR neighborhood definition for the ersosion methods.Maxima detection radius: Defines the box neighborhood in which unique maxima are detected.Output type:Labels(recommended): creates individual labels for separable objects with consecutive numbering.Binary: creates a binary (0/255) image without object separation.
Stack slice: allows to navigate through stack slices in 3D stacksApply on complete image: In case the procedure is tested in a user created ROI/selection it will finally be applied to the complete image if this option is active. For very big 3D images it is strongly recommended to first test on smaller subregions to avoid running out of graphics card memory and long processing times.
3D Example:
Labels
Label Splitter
The label splitter is the equivalent of a watershedding function for binary images or images containing labeld objects already. It will separate objects according to the following methods. The output image will be displayed as consecutive intensity labels (intensity = identifier). This is the last part of the Voronoi Threshold Labeler processing. All of these functions work best on 3D isotropic voxels, so consider to run Make 3D image isotropic!
Methods:
Separation method: There are 3 different object separations. Those are meant to be used in exchange for a common Watershed algorithm. The different methods areMaxima(extremely good for small objects): intensity maxima are determined on the original image in a square/box neighborhood defined by theMaxima detection radiusafter applying a gaussian blur on the original image in a neighborhood defined by theSpot sigma. The detected maxima are the seeds from which the objects are filled via a masked voronoi extension.Eroded Maxima: takes the input image and erodes the objects using theSpot sigmaas erosion iterations. Then it identifies intensity maxima on the eroded objects using theMaxima detection radius.EDM Maxima: Maxima are detected on the euclidean distance map after gaussian blurring using theSpot sigmaandMaxima detection radiusas for the normalMaximamethod.Maxima Spheres(good for bigger and roundish objects): the EDM (euclidean distance map) is created from the binary segmentation result, then blurred with theSpot sigmaand maxima are detected on the blurred EDM. The underlying EDM intensity of those maxima is measured and taken as a radius of a sphere. An image with those spheres serves as seeds for the label splitting (advantage is that the EDM info reflects to some extent the object size and adapts seeds accodingly which might achieves more accurate separation).
DoG Seeds: There will be a difference of gausian (DoG) filter be applied on the segmented binary objects which leads to smooth seed objects still dependent on the original object size bit with less smaller fragmented seeds. This does not work well on big connections/bridges between objects but has advantages on fairly irregularly shaped objects.Eroded box: The extracted objects/areas are eroded in a square/box neighborhood defined by theSpot sigmaand used as a seed for the same voronoi filling of the objects.Eroded sphere: The extracted objects/areas are eroded in a circle/sphere neighborhood defined by theSpot sigmaand used as seeds.
The erosion methods are useful for bigger and irregularly shaped objects, while the maxima method performs better for smaller objects. The erosion-based methods ignore the field Maxima detection radius. Too high spot sigmas will delete smaller objects from the image.
Spot sigma: Blurring strength for maxima detection OR neighborhood definition for the ersosion methods.Maxima detection radius: Defines the box neighborhood in which unique maxima are detected.
Further separation methods are planned to be added, so stay tuned!
Separate Labels
The label separator takes a label image and places a separation in form of background pixels between touching labels. This can be considered the equivalent of the standard binary watershed function in ImageJ / Fiji. This can influence further post processing such as erosion or opening functions from the Post Processor.
Post Processor
This tool is meant to be used on binary images or labels but can be used for most functions also as a normal image filter tool. This way, is partially the counter part of the Filter Check
Ongoing development: more filter functions will be added in future
Analysis
Object Inspector
The Object Inspector is the new version of the Speckle Inspector. It analyzes (secondary) objects inside (primary) objects. Input parameters are:
Primary objects: this is an image holding the primary (outer) objects in form of labels or a binary image. Must be provided!Secondary objects: this is an image holding the secondary (inner) objects in form of labels or a binary image. Must be provided!Primary original image: The original image related to the primary objects. This has to be provided only if pixel intensity-related values should be analyzedSecondary original image: The original image related to the secondary objects. This has to be provided only if pixel intensity-related values should be analyzedPrimary volume limitation: all primary objects inside this 2D area / 3D volume range will be analyzed. All others will be excluded from analysisPrimary mean/max extension ratio: This refers to the Mean / Max Extension Ratio (ratio between the average and maximum distance of the objects’ border to the centroid). This is used to exclude objects of similar size but difference in shape (similar to the circularity in the standard ImageJAnalyze Particles...function.Secondary volume limitation: equivalent of the above for the secondary objects.Secondary mean/max extension ratio: equivalent of the above for the secondary objects.Exclude primary edge objects: All objects which touch the image border or in 3D the image borders and the upper and lower stack slice will be excluded. All secondary objects contained in those objects will also be removed from the nalysis and output imagePad stack tops: if active it will add a black slice before the first and after the last stack slice. This avoids removing primary objects still visible in the first and last slice if Exclude primary edge objects is active. To achieve proper measurements, however, it is recommended to avoid this function and acquire objects completely during imaging.Show analysis label maps: will display the analyzed objects as intensity coded labels (with new consecutive numbering)Show count map: shows labels of the primary objects with the intensity indicating the numbers of secondary objects contained inside them.
Results tables are available for primary as well as secondary objects including object counting and relational identification, size, intensity and some shape values.
Overlap Extractor
This tool is the new version of the Binary Feature Extractor. It keeps objects from one image which overlap with objects from a second image by a specified area (2D) or volume (3D) range. All primary objects which are covered less or more than the specified range values will be excluded from the analysis. The remaining ones will be extracted in a separate image. Original primary objects can also be displayed with the actual volume coverage. Original statistics for all objects are displayed in one table if desired while extraction statistics are displayed in a seperate table (OE3D_Statistics)
3D Neighbor Analysis
The neighbor analysis allows to analyze how many neighbor objects a specific labeled object has (intensity values in objects indicate neighbor count). In addition, the neighbor counts as well as the count distribution can be plotted.
Parameters:
Method: Neighbors are determined based on…Objects: …the voronoi drawn on basis of the original object outlineDistance: …the distance range given calculated from the centroid of each object to the other centroids. Therefore, object shape is neglected. Only recommended for small and isotropic objectsObject size range: excludes objects with an area/volume outside the given range before the analysisDistance range: centroids not reachable within the given distance range are not considered as neighbors.Exclude edges from visualization: objects which directly touch the border or whos voronoi is touching imge edges are taken into account as neighbors of others but are finally not displayed since their own neighbor count is incorrect due to missing neighbors not part of the field of view. If the complete sample is imaged this option should not be used.Plot neighbour counts: for each input label the number of neighbors will be plotted. Those are also indicated in the neighbor count map image.Plot neighbor distribution: the distribution of neighbor frequencies is plotted. The value plotted for zero neighbors are excluded objects (due to edge exclusion).
Additional Functions
Add Labels to 3D ROI Manager
This adds all 2D or 3D labels as ROIs to the 3D ROI Manager from the magnificent 3D Suite by Thomas Boudier
In some cases this function might run a little unstable and ROIs might not directly be visible in the ROI Manager. Either try again or play with the Live ROI activation in the 3D ROI Manager.
Add Labels to 2D ROI Manager
This is based on a Groovy script from Bram van den Broek (@bramvdbroek) shown and discused here
Make 3D Image Isotropic
For some operations, isotropic voxels create better segmentation results due to how the individual methods are applied to the image. Therefore, it can be advantages to convert the image into one having isotropic voxels. This function is considering the actual calibration of the image e.g. in µm and reslices the volume to create those isotropic voxels. This however will apply liniear interpolation to the intensity values and change those. So, one needs to choose between best segmentation result or most original intensity values in some cases.
Convoluted Background Subtraction
The equivalent function to the original convoluted background subtraction is already on the todo list
Citation
If you use this library and its functions to generate and publish results, please condider to acknowledge and cite the toolbox using the DOI.
Issues
https://github.com/biovoxxel/bv3dbox/issues
Contact
via e-mail via BioVoxxel gitter channel
Acknowledgement
The BioVoxxel 3D Box funtions are heavily based and rely strongly on the CLIJ library family. Therefore, this development would have not been possible without the work of Robert Haase and colleagues.
Robert Haase, Loic Alain Royer, Peter Steinbach, Deborah Schmidt, Alexandr Dibrov, Uwe Schmidt, Martin Weigert, Nicola Maghelli, Pavel Tomancak, Florian Jug, Eugene W Myers. CLIJ: GPU-accelerated image processing for everyone. Nat Methods (2019)
J. Ollion, J. Cochennec, F. Loll, C. Escudé, T. Boudier. (2013) TANGO: A Generic Tool for High-throughput 3D Image Analysis for Studying Nuclear Organization. Bioinformatics 2013 Jul 15;29(14):1840-1. http://dx.doi.org/10.1093/bioinformatics/btt276