edu.stanford.rsl.apps.gui.blobdetection

Class ConnectedComponent3D

java.lang.Object

edu.stanford.rsl.apps.gui.blobdetection.ConnectedComponent3D

public class ConnectedComponent3D
extends java.lang.Object

This class implements multithreaded and linear O(n) 3D particle identification and shape analysis. Surface meshing and 3D visualisation are provided by Bene Schmid's ImageJ 3D Viewer.

This plugin is based on Object_Counter3D by Fabrice P Cordelires and Jonathan Jackson, but with significant speed increases through reduction of recursion and multi-threading. Thanks to Robert Barbour for the suggestion to 'chunk' the stack. Chunking works as follows:

1. Perform initial labelling on the whole stack in a single thread
2. for n discrete, contiguous chunks within the labelling array, connectStructures()
   1. connectStructures() can run in a separate thread for each chunk
   2. chunks are approximately equal-sized sets of slices
3. stitchChunks() for the pixels on the first slice of each chunk, except for the first chunk, restricting replaceLabels() to the current and all previous chunks.
   1. stitchChunks() iterates through the slice being stitched in a single thread

The performance improvement should be in the region of a factor of n if run linearly, and if multithreaded over c processors, speed increase should be in the region of n * c, minus overhead.

Author:

Michael Doube, Jonathan Jackson, Fabrice Cordelires, Michal Klosowski

See Also:

3D Object Counter

Field Summary

Fields

Modifier and Type	Field and Description
static int	BACK Background value
static int	FORE Foreground value
static int	LINEAR Particle joining method
static int	MAPPED Particle joining method
static int	MULTI Particle joining method

Constructor Summary

Constructors

Constructor and Description
ConnectedComponent3D()

Method Summary

Methods

Modifier and Type	Method and Description
boolean	dialogItemChanged(ij.gui.GenericDialog gd, java.awt.AWTEvent e)
ij.ImagePlus	displayParticleValues(ij.ImagePlus imp, int[][] particleLabels, double[] values, java.lang.String title) Create an image showing some particle measurement
static ij.ImagePlus	getBinaryParticle(int p, ij.ImagePlus imp, int[][] particleLabels, int[][] limits, int padding) create a binary ImagePlus containing a single particle and which 'just fits' the particle
double[][]	getCentroids(ij.ImagePlus imp, int[][] particleLabels, long[] particleSizes) Get the centroids of all the particles in real units
int[][]	getChunkRanges(ij.ImagePlus imp, int nC, int slicesPerChunk) Get a 2 d array that defines the z-slices to scan within while connecting particles within chunkified stacks.
org.doube.jama.EigenvalueDecomposition[]	getEigens(ij.ImagePlus imp, int[][] particleLabels, double[][] centroids)
java.lang.Object[][]	getEllipsoids(java.util.ArrayList<java.util.List<Point3D>> surfacePoints)
double[]	getFerets(java.util.ArrayList<java.util.List<Point3D>> particleSurfaces) Get the Feret diameter of a surface.
int	getLabelMethod() Return the value of this instance's labelMethod field
java.lang.Object[]	getMaxDistances(ij.ImagePlus imp, int[][] particleLabels, double[][] centroids, org.doube.jama.EigenvalueDecomposition[] E) Get the maximum distances from the centroid in x, y, and z axes, and transformed x, y and z axes
double[][]	getMeanStdDev(ij.ImagePlus imp, int[][] particleLabels, long[] particleSizes, int threshold) Get the mean and standard deviation of pixel values above a minimum value for each particle in a particle label work array
int	getNCavities(ij.ImagePlus imp)
int	getNChunks(ij.ImagePlus imp, int slicesPerChunk) Gets number of chunks needed to divide a stack into evenly-sized sets of slices.
int[][]	getParticleLimits(ij.ImagePlus imp, int[][] particleLabels, int nParticles) Get the minimum and maximum x, y and z coordinates of each particle
java.util.ArrayList<java.util.ArrayList<short[]>>	getParticleLists(int[][] particleLabels, int nBlobs, int w, int h, int d)
java.lang.Object[]	getParticles(ij.ImagePlus imp, byte[][] workArray, int slicesPerChunk, double minVol, double maxVol, int phase)
java.lang.Object[]	getParticles(ij.ImagePlus imp, byte[][] workArray, int slicesPerChunk, double minVol, double maxVol, int phase, boolean doExclude) Get particles, particle labels and sizes from a workArray using an ImagePlus for scale information
java.lang.Object[]	getParticles(ij.ImagePlus imp, byte[][] workArray, int slicesPerChunk, int phase, int method)
java.lang.Object[]	getParticles(ij.ImagePlus imp, int slicesPerChunk, double minVol, double maxVol, int phase)
java.lang.Object[]	getParticles(ij.ImagePlus imp, int slicesPerChunk, double minVol, double maxVol, int phase, boolean doExclude) Get particles, particle labels and particle sizes from a 3D ImagePlus
java.lang.Object[]	getParticles(ij.ImagePlus imp, int slicesPerChunk, int phase)
long[]	getParticleSizes(int[][] particleLabels) Get the sizes of all the particles as a voxel count
double[]	getVolumes(ij.ImagePlus imp, long[] particleSizes)
void	joinBlobs(int b, int p, int[][] particleLabels, java.util.ArrayList<java.util.ArrayList<short[]>> particleLists, int w) Join particle p to particle b, relabelling p with b.
void	replaceLabel(int[][] particleLabels, int m, int n, int startZ, int endZ) Check whole array replacing m with n
void	replaceLabel(int[][] particleLabels, int m, int n, int startZ, int endZ, boolean multithreaded) Check whole array replacing m with n
void	setLabelMethod(int label) Set the value of this instance's labelMethod field

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

FORE

public static final int FORE

Foreground value

See Also:

Constant Field Values

BACK

public static final int BACK

Background value

See Also:

Constant Field Values

MULTI

public static final int MULTI

Particle joining method

See Also:

Constant Field Values

LINEAR

public static final int LINEAR

Particle joining method

See Also:

Constant Field Values

MAPPED

public static final int MAPPED

Particle joining method

See Also:

Constant Field Values

Constructor Detail

ConnectedComponent3D

public ConnectedComponent3D()

Method Detail

getEllipsoids

public java.lang.Object[][] getEllipsoids(java.util.ArrayList<java.util.List<Point3D>> surfacePoints)

getMeanStdDev

public double[][] getMeanStdDev(ij.ImagePlus imp,
                       int[][] particleLabels,
                       long[] particleSizes,
                       int threshold)

Get the mean and standard deviation of pixel values above a minimum value for each particle in a particle label work array

Parameters:

imp - Input image containing pixel values

particleLabels - workArray containing particle labels

particleSizes - array of particle sizes as pixel counts

threshold - restrict calculation to values > i

Returns:

array containing mean, std dev and max pixel values for each particle

getNCavities

public int getNCavities(ij.ImagePlus imp)

getParticleLimits

public int[][] getParticleLimits(ij.ImagePlus imp,
                        int[][] particleLabels,
                        int nParticles)

Get the minimum and maximum x, y and z coordinates of each particle

Parameters:

imp - ImagePlus (used for stack size)

particleLabels - work array containing labelled particles

nParticles - number of particles in the stack

Returns:

int[][] containing x, y and z minima and maxima.

getEigens

public org.doube.jama.EigenvalueDecomposition[] getEigens(ij.ImagePlus imp,
                                                 int[][] particleLabels,
                                                 double[][] centroids)

getMaxDistances

public java.lang.Object[] getMaxDistances(ij.ImagePlus imp,
                                 int[][] particleLabels,
                                 double[][] centroids,
                                 org.doube.jama.EigenvalueDecomposition[] E)

Get the maximum distances from the centroid in x, y, and z axes, and transformed x, y and z axes

Parameters:

imp -

particleLabels -

centroids -

E -

Returns:

array containing two nPoints * 3 arrays with max and max transformed distances respectively

getFerets

public double[] getFerets(java.util.ArrayList<java.util.List<Point3D>> particleSurfaces)

Get the Feret diameter of a surface. Uses an inefficient brute-force algorithm.

Parameters:

particleSurfaces -

Returns:

the array of ferets

getBinaryParticle

public static ij.ImagePlus getBinaryParticle(int p,
                             ij.ImagePlus imp,
                             int[][] particleLabels,
                             int[][] limits,
                             int padding)

create a binary ImagePlus containing a single particle and which 'just fits' the particle

Parameters:

p - The particle ID to get

imp - original image, used for calibration

particleLabels - work array of particle labels

limits - x,y and z limits of each particle

padding - amount of empty space to pad around each particle

Returns:

the imageplus

displayParticleValues

public ij.ImagePlus displayParticleValues(ij.ImagePlus imp,
                                 int[][] particleLabels,
                                 double[] values,
                                 java.lang.String title)

Create an image showing some particle measurement

Parameters:

imp -

particleLabels -

values - list of values whose array indices correspond to particlelabels

title - tag stating what we are displaying

Returns:

ImagePlus with particle labels substituted with some value

getCentroids

public double[][] getCentroids(ij.ImagePlus imp,
                      int[][] particleLabels,
                      long[] particleSizes)

Get the centroids of all the particles in real units

Parameters:

imp -

particleLabels -

particleSizes -

Returns:

double[][] containing all the particles' centroids

getVolumes

public double[] getVolumes(ij.ImagePlus imp,
                  long[] particleSizes)

getParticles

public java.lang.Object[] getParticles(ij.ImagePlus imp,
                              int slicesPerChunk,
                              double minVol,
                              double maxVol,
                              int phase,
                              boolean doExclude)

Get particles, particle labels and particle sizes from a 3D ImagePlus

Parameters:

imp - Binary input image

slicesPerChunk - number of slices per chunk. 2 is generally good.

minVol - minimum volume particle to include

maxVol - maximum volume particle to include

phase - foreground or background (FORE or BACK)

doExclude - if true, remove particles touching sides of the stack

Returns:

Object[] {byte[][], int[][]} containing a binary workArray and particle labels.

getParticles

public java.lang.Object[] getParticles(ij.ImagePlus imp,
                              int slicesPerChunk,
                              double minVol,
                              double maxVol,
                              int phase)

getParticles

public java.lang.Object[] getParticles(ij.ImagePlus imp,
                              int slicesPerChunk,
                              int phase)

getParticles

public java.lang.Object[] getParticles(ij.ImagePlus imp,
                              byte[][] workArray,
                              int slicesPerChunk,
                              int phase,
                              int method)

getParticles

public java.lang.Object[] getParticles(ij.ImagePlus imp,
                              byte[][] workArray,
                              int slicesPerChunk,
                              double minVol,
                              double maxVol,
                              int phase)

getParticles

public java.lang.Object[] getParticles(ij.ImagePlus imp,
                              byte[][] workArray,
                              int slicesPerChunk,
                              double minVol,
                              double maxVol,
                              int phase,
                              boolean doExclude)

Get particles, particle labels and sizes from a workArray using an ImagePlus for scale information

Parameters:

imp - input binary image

workArray - work array

slicesPerChunk - number of slices to use for each chunk

minVol - minimum volume particle to include

maxVol - maximum volume particle to include

phase - FORE or BACK for foreground or background respectively

Returns:

Object[] array containing a binary workArray, particle labels and particle sizes

getNChunks

public int getNChunks(ij.ImagePlus imp,
             int slicesPerChunk)

Gets number of chunks needed to divide a stack into evenly-sized sets of slices.

Parameters:

imp - input image

slicesPerChunk - number of slices per chunk

Returns:

number of chunks

getParticleLists

public java.util.ArrayList<java.util.ArrayList<short[]>> getParticleLists(int[][] particleLabels,
                                                                 int nBlobs,
                                                                 int w,
                                                                 int h,
                                                                 int d)

joinBlobs

public void joinBlobs(int b,
             int p,
             int[][] particleLabels,
             java.util.ArrayList<java.util.ArrayList<short[]>> particleLists,
             int w)

Join particle p to particle b, relabelling p with b.

Parameters:

b -

p -

particleLabels - array of particle labels

particleLists - list of particle voxel coordinates

w - stack width

getChunkRanges

public int[][] getChunkRanges(ij.ImagePlus imp,
                     int nC,
                     int slicesPerChunk)

Get a 2 d array that defines the z-slices to scan within while connecting particles within chunkified stacks.

Parameters:

nC - number of chunks

Returns:

scanRanges int[][] containing 4 limits: int[0][] - start of outer for; int[1][] end of outer for; int[3][] start of inner for; int[4] end of inner 4. Second dimension is chunk number.

replaceLabel

public void replaceLabel(int[][] particleLabels,
                int m,
                int n,
                int startZ,
                int endZ)

Check whole array replacing m with n

Parameters:

m - value to be replaced

n - new value

startZ - first z coordinate to check

endZ - last+1 z coordinate to check

replaceLabel

public void replaceLabel(int[][] particleLabels,
                int m,
                int n,
                int startZ,
                int endZ,
                boolean multithreaded)

Check whole array replacing m with n

Parameters:

m - value to be replaced

n - new value

startZ - first z coordinate to check

endZ - last+1 z coordinate to check

multithreaded - true if label replacement should happen in multiple threads

getParticleSizes

public long[] getParticleSizes(int[][] particleLabels)

Get the sizes of all the particles as a voxel count

Parameters:

particleLabels -

Returns:

particleSizes

getLabelMethod

public int getLabelMethod()

Return the value of this instance's labelMethod field

Returns:

the label method as int

setLabelMethod

public void setLabelMethod(int label)

Set the value of this instance's labelMethod field

Parameters:

label - one of ParticleCounter.MULTI or .LINEAR

dialogItemChanged

public boolean dialogItemChanged(ij.gui.GenericDialog gd,
                        java.awt.AWTEvent e)