Directionality_ (Fiji Javadocs 0-SNAPSHOT API)

java.lang.Object
- fiji.analyze.directionality.Directionality_

All Implemented Interfaces:

ij.plugin.PlugIn
```
public class Directionality_
extends Object
implements ij.plugin.PlugIn
```
Usage
This plugin is used to infer the preferred orientation of structures present in the input image. It computes a histogram indicating the amount of structures in a given direction. Images with completely isotropic content are expected to give a flat histogram, whereas images in which there is a preferred orientation are expected to give a histogram with a peak at that orientation.
Angles are reported in their common mathematical sense. That is: 0º is the East direction, and the orientation is counterclockwise.
It is possible to limit the analysis to a range of angles lower than the default 180 degrees.
Statistics generated
On top of the histogram, the plugin tries to generate statistics on the highest peak found.
The highest peak is fitted by a Gaussian function, taking into account the periodic nature of the histogram. The 'Direction (º)' column reports the center of the gaussian. The 'Dispersion (º)' column reports the standard deviation of the gaussian. The 'Amount' column is the sum of the histogram from the center of the peak to two standard deviation away, divided by the total sum of the histogram. The real histogram values are used for the summation, not the gaussian fit. The 'Goodness' column reports the goodness of the fit; 1 is good, 0 is bad.
A study made on artificial images reveal that the 'Amount' value as calculated here underestimates the real proportion of structures with the preferred orientation.
Analysis methods
Two methods are implemented:
Fourier components analysis
This method is based on Fourier spectrum analysis. For a square image, structures with a preferred orientation generate a periodic pattern at +90º orientation in the Fourier transform of the image, compared to the direction of the objects in the input image.
This plugin chops the image into square pieces, and computes their Fourier power spectra. The later are analyzed in polar coordinates, and the power is measured for each angle using the spatial filters proposed in [1].
Local gradient orientation
This method is a local analysis. The gradient of the image is calculated using a 5x5 Sobel filter, and is used to derive the local gradient orientation. This orientation is then used to build the histogram, by putting the square of the gradient norm in the adequate bin. The square of the norm was retained, so as to have an histogram with the same dimension that for the Fourier analysis.
Orientation map
Since version 2.0, the plugin offers the possibility to generate an orientation map, where the image is colored according to its local directionality, or location orientation. This has a well an easily defined meaning in the case of the local gradient orientation method, but things are a bit more complicated in the case of the Fourier component, which is a global method.
In the later case, the image is filtered using the Fourier filters described above, and transformed back using inverse Fourier transform. For each pixel, the direction retained is the one that has the strongest intensity when filtered in this orientation.
To generate the orientation map image, a HSB image is made by taking
- the local orientation as hue
- the original image gray value as brightness
- for saturation:
  - the power spectrum value for the Fourier component method
  - the gradient magnitude square for the Local gradient orientation method
Code structure
This plugin is written as a classical ImageJ plugin. It implements PlugIn.
String arguments can be passed to it, using the run(String) method. For instance:
```
 ImagePlus imp = IJ.openImage( "./TwoLines.tif" );
 imp.show();
 Directionality_ da = new Directionality_();
 da.run( "nbins=60, start=-90, end=90, method=gradient" );
 
```
It is also possible to run the plugin non-interactively from another class, or even in a script. For instance in Python:
```
        import fiji.analyze.directionality.Directionality_
 
        # Instantiate plugin
        dir = fiji.analyze.directionality.Directionality_()
 
        # Set fields and settings
        dir.setImagePlus(WindowManager.getCurrentImage())
        # dir.setMethod(fiji.analyze.directionality.Directionality_.AnalysisMethod.LOCAL_GRADIENT_ORIENTATION)
        dir.setMethod(fiji.analyze.directionality.Directionality_.AnalysisMethod.FOURIER_COMPONENTS)
        dir.setBinNumber(30)
        dir.setBinStart(-60)
  # Alternatively set a range
  # dir.setBinRange(-60,60)
        dir.setBuildOrientationMapFlag(True)

        # Do calculation
        dir.computeHistograms()
        dir.fitHistograms()

        # Display plot frame
        plot_frame = dir.plotResults()
        plot_frame.setVisible(True)

        # Display fit analysis
        data_frame = dir.displayFitAnalysis()
        data_frame.setVisible(True) 

        # Display results table
        table = dir.displayResultsTable()
        table.show("Directionality histograms")

        # Display orientation map
        stack = dir.getOrientationMap()
        ImagePlus("Orientation map", stack).show()

        # Generate a color wheel
        fiji.analyze.directionality.Directionality_.generateColorWheel(dir.getBinStart(), dir.getBinEnd()).show()
 
```
Version history
- v2.0 - 2010-06-08: After a lot of mistakes and problems, each method now propose to generate an orientation map, which colors the image according to the local directionality.
- v1.3 - 2010-03-17: Heavy refactoring, made it implement Plugin interface, so has to be conveniently called from a script.
- v1.2 - 2010-03-10: Added a new analysis method based on local gradient orientation.
- v1.1 - 2010-03-05: Added an option to export the histogram as a table, and option to circular-shifts the histogram.
- v1.0 - 2010-03-01: First working commit with the Fourier method.
References
[1] Liu. Scale space approach to directional analysis of images. Appl. Opt. (1991) vol. 30 (11) pp. 1369-1373
A discussion with A. Leroy and another one with J. Schindelin are greatly acknowledged.
Version:

2.0

Author:

Jean-Yves Tinevez jeanyves.tinevez@gmail.com

Nested Class Summary

Nested Classes
Modifier and Type Class and Description

static class Directionality_.AnalysisMethod

Nested Classes
Modifier and Type	Class and Description
`static class`	`Directionality_.AnalysisMethod`

Field Summary

Fields
Modifier and Type	Field and Description
`protected double[]`	`bins` The bin centers, in radians.
`protected boolean`	`debug` If true, will display FFTs and filters.
`protected ij.ImageStack`	`filters` Fourier filters are stored as a stack
`protected String`	`fit_string` Store a String representing the fitting function.
`protected double[]`	`goodness_of_fit` Store goodness of fit results when fit method is called.
`protected int`	`height`
`protected ArrayList<double[]>`	`histograms` The directionality histogram, one array per processor (3 in the case of a ColorProcessor).
`protected ij.ImagePlus`	`imp` The ImagePlus this plugin operates on.
`protected int`	`long_side`
`protected int`	`nbins` The number of bins to create.
`protected int`	`npadx`
`protected int`	`npady`
`protected int`	`pad_size`
`protected ArrayList<double[]>`	`params_from_fit` Store fit results when fit method is called.
`protected ij.process.FloatProcessor`	`r` Polar coordinates, stored as a FloatProcessor.
`protected int`	`small_side`
`protected int`	`step`
`protected ij.process.FloatProcessor`	`theta` Polar coordinates, stored as a FloatProcessor.
`protected int`	`width`
`protected ij.process.FloatProcessor`	`window` Polar coordinates, stored as a FloatProcessor.

Constructor Summary

Constructors
Constructor and Description

Directionality_()

Constructors
Constructor and Description
`Directionality_()`

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`protected static void`	`addColorMouseListener(ImageCanvas canvas, double angle_start, double angle_end)`
`void`	`computeHistograms()` This method runs the analysis on all slices, and store resulting histograms in the histogram fields.
`protected static LookupPaintScale`	`createLUT(int ncol)` Generate a bluish to greenish to redish LUT for the display of histograms.
`JFrame`	`displayFitAnalysis()` This method displays the fit analysis results in a `JTable`.
`protected static ij.process.FloatProcessor`	`displayLog(ij.process.FloatProcessor ip)` This utility method returns a FloatProcessor with the log10 of each pixel in the `FloatProcessor` given in argument.
`ij.measure.ResultsTable`	`displayResultsTable()` This method generates a `ResultsTable` containing the histogram data for display in ImageJ.
`void`	`fitHistograms()` This method tries to fit a gaussian to the highest peak of each directionality histogram, and store fit results in the `params_from_fit` field.
`static ij.ImagePlus`	`generateColorWheel(double angle_start, double angle_end)`
`double`	`getBinEnd()` Returns the current value for angle bin end, in degrees.
`int`	`getBinNumber()` Returns the current number of bins for this instance.
`double[]`	`getBins()` Returns the center of the bins for the directionality histograms.
`double`	`getBinStart()` Returns the current value for angle bin start, in degrees.
`protected static double[]`	`getBlackmanPeriodicWindow1D(int n)` This utility generates a periodic Blackman window over n points.
`protected static ij.process.FloatProcessor`	`getBlackmanProcessor(int nx, int ny)` Generate a 2D Blackman window used in this plugin before computing FFT, so as to avoid the cross artifact at x=0 and y=0.
`ArrayList<double[]>`	`getFitAnalysis()` Return the result of analyzing the gaussian fit of the peak.
`ArrayList<double[]>`	`getFitParameters()` Returns the parameters of the gaussian fit of the main peak in histogram.
`double[]`	`getGoodnessOfFit()` Returns the goodness of fit for the gaussian fit; 1 is good, 0 is bad.
`ArrayList<double[]>`	`getHistograms()` Returns the directionality histograms as an ArrayList of double[], one array per slice.
`ij.ImagePlus`	`getImagePlus()` Gets the image analyzed.
`Directionality_.AnalysisMethod`	`getMethod()` Returns the analysis method used by this instance.
`ij.ImageStack`	`getOrientationMap()` Returns the orientation map as an `ImageStack`, one slice per slice in the source image.
`static void`	`main(String[] args)`
`protected static ij.process.FloatProcessor`	`makeRMatrix(int nx, int ny)` Generate a 2D matrix of the radius polar coordinates, centered in the middle of the image.
`protected static ij.process.FloatProcessor`	`makeThetaMatrix(int nx, int ny)` Generate a 2D matrix of the angle polar coordinates, centered in the middle of the image.
`protected static String`	`parseArgumentString(String argument_string, String command_str)` Utility method to analyze the content of the argument string passed by ImageJ to this plugin using the `setup(String, ImagePlus)` method.
`JFrame`	`plotResults()` This method is called to draw the histograms resulting from image analysis.
`protected static double[]`	`prepareBins(int n, double first, double last)` Generate a bin array of angle in radians, from -pi/2 to pi/2.
`void`	`run(String arg)` Called when this plugin is launched from ImageJ.
`void`	`setBinNumber(int nbins)` Sets the desired number of bins.
`void`	`setBinRange(double bin_start, double bin_end)` Sets the desired end for the angle bins, in degrees.
`void`	`setBinStart(double bin_start)` Sets the desired start for the angle bins, in degrees.
`void`	`setBuildOrientationMapFlag(boolean flag)` Sets the build orientation map flag
`void`	`setDebugFlag(boolean flag)` Sets the debug flag.
`void`	`setImagePlus(ij.ImagePlus imp)` Sets the image for analysis.
`void`	`setMethod(Directionality_.AnalysisMethod method)` Sets the desired method for analysis.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - imp
```
protected ij.ImagePlus imp
```
    The ImagePlus this plugin operates on.
  - debug
```
protected boolean debug
```
    If true, will display FFTs and filters.
  - nbins
```
protected int nbins
```
    The number of bins to create.
  - filters
```
protected ij.ImageStack filters
```
    Fourier filters are stored as a stack
  - window
```
protected ij.process.FloatProcessor window
```
    Polar coordinates, stored as a FloatProcessor.
  - r
```
protected ij.process.FloatProcessor r
```
    Polar coordinates, stored as a FloatProcessor.
  - theta
```
protected ij.process.FloatProcessor theta
```
    Polar coordinates, stored as a FloatProcessor.
  - width
```
protected int width
```
  - height
```
protected int height
```
  - small_side
```
protected int small_side
```
  - long_side
```
protected int long_side
```
  - npady
```
protected int npady
```
  - npadx
```
protected int npadx
```
  - step
```
protected int step
```
  - pad_size
```
protected int pad_size
```
  - bins
```
protected double[] bins
```
    The bin centers, in radians. Internally, they always range from -pi/2 to pi/2.
  - histograms
```
protected ArrayList<double[]> histograms
```
    The directionality histogram, one array per processor (3 in the case of a ColorProcessor).
  - params_from_fit
```
protected ArrayList<double[]> params_from_fit
```
    Store fit results when fit method is called.
  - goodness_of_fit
```
protected double[] goodness_of_fit
```
    Store goodness of fit results when fit method is called.
  - fit_string
```
protected String fit_string
```
    Store a String representing the fitting function.
- Constructor Detail
  - Directionality_
```
public Directionality_()
```
- Method Detail
  - run
```
public void run(String arg)
```
    Called when this plugin is launched from ImageJ. This method
    1. grabs the current ImagePlus
    2. displays the user dialog and sets setting fields accordingly
    3. calls the computeHistograms() method, which computes the histograms
    4. calls the fitHistograms() method, which fits the histograms
    5. display the results
    If the method is called with String arguments, fields are set according to it, and no dialog are displayed (macro recordable).
    Specified by:
    
    run in interface ij.plugin.PlugIn
    
    Parameters:
    
    arg - the string argument, for instance "nbins=90, start=-90, end=90, method=gradient"
  - computeHistograms
```
public void computeHistograms()
```
    This method runs the analysis on all slices, and store resulting histograms in the histogram fields. Calling this method resets the aforementioned field.
  - displayResultsTable
```
public ij.measure.ResultsTable displayResultsTable()
```
    This method generates a ResultsTable containing the histogram data for display in ImageJ. It can be used to export the data to a CSV file.
    
    Returns:
    
    the result table, which show() method must be called to become visible.
  - getFitAnalysis
```
public ArrayList<double[]> getFitAnalysis()
```
    Return the result of analyzing the gaussian fit of the peak. Results are returned in the shape of an ArrayList of double[], one element per slice. The content of the double arrays is as follow:
    1. gaussian peak center
    2. gaussian standard deviation
    3. amount, that is: the sum of the histogram data from the gaussian center until SIGMA_NUMBER times its standard deviation away
    4. the goodness of fit
    The periodic nature of the data is taken into account. For the amount value, the actual values of the histogram are summed, not the values from the fit.
    Returns:
    
    the fit analysis
  - plotResults
```
public JFrame plotResults()
```
    This method is called to draw the histograms resulting from image analysis. It reads the result in the histogram list field, and use the JFreeChart library to draw a nice plot window. If the fitResults() method was called before, the fits are also drawn.
    
    Returns:
    
    a JFrame containing the histogram plots, which setVisible(boolean) method must be called in order to be displayed
  - fitHistograms
```
public void fitHistograms()
```
    This method tries to fit a gaussian to the highest peak of each directionality histogram, and store fit results in the params_from_fit field. The goodness of fit will be stored in goodness_of_fit.
  - displayFitAnalysis
```
public JFrame displayFitAnalysis()
```
    This method displays the fit analysis results in a JTable.
    
    Returns:
    
    a JFrame containing the table; its setVisible(boolean) method must be called in order to be displayed
  - setImagePlus
```
public void setImagePlus(ij.ImagePlus imp)
```
    Sets the image for analysis. Calling this method resets the field histograms to null.
    
    Parameters:
    
    imp - the image.
  - getImagePlus
```
public ij.ImagePlus getImagePlus()
```
    Gets the image analyzed.
    
    Returns:
    
    the image.
  - getFitParameters
```
public ArrayList<double[]> getFitParameters()
```
    Returns the parameters of the gaussian fit of the main peak in histogram. Results are arranged in an ArrayList of double[], one array per slice analyzed. If the fit was not done prior to this method call, it is called. If the method computeHistograms() was not called, null is returned.
    The double array is organized as follow, for the fitting model y = a + (b-a)*exp(-(x-c)*(x-c)/(2*d*d))
    1. a
    2. b
    3. x
    4. d
    Returns:
    
    the fitting parameters.
    
    See Also:
    
    getGoodnessOfFit(), getHistograms(), getBins()
  - getGoodnessOfFit
```
public double[] getGoodnessOfFit()
```
    Returns the goodness of fit for the gaussian fit; 1 is good, 0 is bad. One value per slice. If the fit was not done prior to this method call, it is called. If the method computeHistograms() was not called, null is returned.
    
    Returns:
    
    the goodness of fit.
    
    See Also:
    
    getFitParameters(), getHistograms(), getBins()
  - getHistograms
```
public ArrayList<double[]> getHistograms()
```
    Returns the directionality histograms as an ArrayList of double[], one array per slice.
    
    Returns:
    
    the directionality histograms; is null if the method computeHistograms() was not called before.
    
    See Also:
    
    getBins(), getFitParameters(), getGoodnessOfFit()
  - getBins
```
public double[] getBins()
```
    Returns the center of the bins for the directionality histograms. They are in degrees.
    
    Returns:
    
    the bin centers, in degrees.
    
    See Also:
    
    getHistograms(), getFitParameters(), getGoodnessOfFit()
  - setBinNumber
```
public void setBinNumber(int nbins)
```
    Sets the desired number of bins. This resets the histograms field to null.
    
    Parameters:
    
    nbins - the number of bins.
  - getBinNumber
```
public int getBinNumber()
```
    Returns the current number of bins for this instance.
    
    Returns:
    
    the number of bins.
  - setBinStart
```
public void setBinStart(double bin_start)
```
    Sets the desired start for the angle bins, in degrees. This resets the histograms field to null.
    
    Parameters:
    
    bin_start - the bin start.
  - getBinStart
```
public double getBinStart()
```
    Returns the current value for angle bin start, in degrees.
    
    Returns:
    
    the bin start.
  - setBinRange
```
public void setBinRange(double bin_start,
                        double bin_end)
```
    Sets the desired end for the angle bins, in degrees. This resets the histograms field to null.
    
    Parameters:
    
    bin_start - the bin start.
    
    bin_end - the bin end.
  - getBinEnd
```
public double getBinEnd()
```
    Returns the current value for angle bin end, in degrees.
    
    Returns:
    
    the bin end.
  - setMethod
```
public void setMethod(Directionality_.AnalysisMethod method)
```
    Sets the desired method for analysis. This resets the histograms field to null.
    
    Parameters:
    
    method - the analysis method.
    
    See Also:
    
    Directionality_.AnalysisMethod
  - getMethod
```
public Directionality_.AnalysisMethod getMethod()
```
    Returns the analysis method used by this instance.
    
    Returns:
    
    the analysis method.
  - setDebugFlag
```
public void setDebugFlag(boolean flag)
```
    Sets the debug flag.
    
    Parameters:
    
    flag - the debug flag.
  - setBuildOrientationMapFlag
```
public void setBuildOrientationMapFlag(boolean flag)
```
    Sets the build orientation map flag
    
    Parameters:
    
    flag - whether the orientation map shall be built.
  - getOrientationMap
```
public ij.ImageStack getOrientationMap()
```
    Returns the orientation map as an ImageStack, one slice per slice in the source image. Return null if the orientation map flag was not set, or if computation was not done.
    
    Returns:
    
    the orientation map.
  - generateColorWheel
```
public static final ij.ImagePlus generateColorWheel(double angle_start,
                                                    double angle_end)
```
  - addColorMouseListener
```
protected static final void addColorMouseListener(ImageCanvas canvas,
                                                  double angle_start,
                                                  double angle_end)
```
  - prepareBins
```
protected static final double[] prepareBins(int n,
                                            double first,
                                            double last)
```
    Generate a bin array of angle in radians, from -pi/2 to pi/2.
    
    Parameters:
    
    n - the number of elements to generate
    
    first - the angle of the first bin, in degrees
    
    last - the angle of the last bin, in degrees
    
    Returns:
    
    a double array of n elements, the angles in radians
  - parseArgumentString
```
protected static final String parseArgumentString(String argument_string,
                                                  String command_str)
```
    Utility method to analyze the content of the argument string passed by ImageJ to this plugin using the setup(String, ImagePlus) method. Not as clever as it could be.
    
    Parameters:
    
    argument_string - the argument string to parse
    
    command_str - the command to search for
    
    Returns:
    
    a string containing the value after the command string, null if the command string was not found
  - displayLog
```
protected static final ij.process.FloatProcessor displayLog(ij.process.FloatProcessor ip)
```
    This utility method returns a FloatProcessor with the log10 of each pixel in the FloatProcessor given in argument. Usefull to display power spectrum.
    
    Parameters:
    
    ip - the source FloatProcessor
    
    Returns:
    
    a new FloatProcessor
  - getBlackmanPeriodicWindow1D
```
protected static final double[] getBlackmanPeriodicWindow1D(int n)
```
    This utility generates a periodic Blackman window over n points.
    
    Parameters:
    
    n - the number of point in the window
    
    Returns:
    
    a double array containing the Blackman window
    
    See Also:
    
    getBlackmanProcessor(int, int)
  - getBlackmanProcessor
```
protected static final ij.process.FloatProcessor getBlackmanProcessor(int nx,
                                                                      int ny)
```
    Generate a 2D Blackman window used in this plugin before computing FFT, so as to avoid the cross artifact at x=0 and y=0.
    
    Parameters:
    
    nx - the width in pixel of the desired window
    
    ny - the hirght in pixel of the desired window
    
    Returns:
    
    the window, as a FloatProcessor
    
    See Also:
    
    getBlackmanPeriodicWindow1D(int)
  - makeRMatrix
```
protected static final ij.process.FloatProcessor makeRMatrix(int nx,
                                                             int ny)
```
    Generate a 2D matrix of the radius polar coordinates, centered in the middle of the image.
    
    Parameters:
    
    nx - the width in pixel of the desired matrix
    
    ny - the height in pixel of the desired matrix
    
    Returns:
    
    the coordinate matrix, as a FloatProcessor, where values range from 0 to sqrt(nx^2+ny^2)/2
    
    See Also:
    
    makeThetaMatrix(int, int)
  - makeThetaMatrix
```
protected static final ij.process.FloatProcessor makeThetaMatrix(int nx,
                                                                 int ny)
```
    Generate a 2D matrix of the angle polar coordinates, centered in the middle of the image.
    
    Parameters:
    
    nx - the width in pixel of the desired matrix
    
    ny - the height in pixel of the desired matrix
    
    Returns:
    
    the coordinate matrix, as a FloatProcessor, where angles are in radians, and range from -pi to pi
    
    See Also:
    
    makeRMatrix(int, int)
  - createLUT
```
protected static final LookupPaintScale createLUT(int ncol)
```
    Generate a bluish to greenish to redish LUT for the display of histograms.
    
    Parameters:
    
    ncol - the number of colors in the LUT
    
    Returns:
    
    the LUT
  - main
```
public static void main(String[] args)
```

Class Directionality_

Usage

Statistics generated

Analysis methods

Fourier components analysis

Local gradient orientation

Orientation map

Code structure

Version history

References

Nested Class Summary

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

imp

debug

nbins

filters

window

r

theta

width

height

small_side

long_side

npady

npadx

step

pad_size

bins

histograms

params_from_fit

goodness_of_fit

fit_string

Constructor Detail

Directionality_

Method Detail

run

computeHistograms

displayResultsTable

getFitAnalysis

plotResults

fitHistograms

displayFitAnalysis

setImagePlus

getImagePlus

getFitParameters

getGoodnessOfFit

getHistograms

getBins

setBinNumber

getBinNumber

setBinStart

getBinStart

setBinRange

getBinEnd

setMethod

getMethod

setDebugFlag

setBuildOrientationMapFlag

getOrientationMap

generateColorWheel

addColorMouseListener

prepareBins

parseArgumentString

displayLog

getBlackmanPeriodicWindow1D

getBlackmanProcessor

makeRMatrix

makeThetaMatrix

createLUT

main