de.unihalle.informatik.MiToBo.apps.neurites2D
Class NeuriteExtractor2D

java.lang.Object
  extended by de.unihalle.informatik.Alida.operator.ALDOperator
      extended by de.unihalle.informatik.MiToBo.core.operator.MTBOperator
          extended by de.unihalle.informatik.MiToBo.apps.neurites2D.NeuriteExtractor2D
All Implemented Interfaces:
de.unihalle.informatik.Alida.datatypes.ALDConfigurationValidator

@ALDAOperator(genericExecutionMode=NONE,
              level=STANDARD,
              allowBatchMode=false)
public class NeuriteExtractor2D
extends MTBOperator

The Neurite Extractor 2D application offers advanced functionality to extract neurite regions in 2D binary neuron images of neurons. The neurites are separated from the soma. In addition, the borderlines between the soma and the neurite shafts, as well as between the neurite shaft and their growth cone is extracted. The exact localization of neurites without the soma (cell body) region is calculated via a wavelet based detection approach from the R script "MTBNeuriteFeatureDetection.R". Neurites are returned as MTBNeurite2D objects. Note: Don't know why operator cannot run twice without restart of MiToBo. Maybe a threading problem of the R engine.

Author:
Danny Misiak
See Also:
MTBNeuriteSkelGraph, MTBNeurite2DSet

Nested Class Summary
static class NeuriteExtractor2D.NeuronColor
          Color of binary neuron image foreground.
 
Nested classes/interfaces inherited from class de.unihalle.informatik.Alida.operator.ALDOperator
de.unihalle.informatik.Alida.operator.ALDOperator.HidingMode
 
Field Summary
private  java.util.Vector<java.util.Vector<java.lang.Double>> avgNeuriteWidths
          Vector of neurite widths, containing 3 elements. 1. average width of whole neurite, 2. average width of neurite shaft, and 3. average width of growth cone.
private  MTBNeurite2DSet extractedNeurites
           
private  java.util.Vector<java.util.Vector<java.util.Vector<java.awt.geom.Point2D.Double>>> featurePoints
          Vector of detected feature points for each neurite.
private  int height
          Height of the binary neuron image.
private  int maxSpineLength
           
private  java.util.Vector<MTBNeuriteSkelGraph> neuriteGraphs
          Vector of neurite graphs, one for each localized neurite.
private  int neuriteMaskSize
           
private  int[] neuriteShaftLengths
          Array of detected lengths of the neurite shafts, without growth cone regions.
private  MTBRegion2D neuronCoarseSoma
          2D region of the coarse cell body region (soma).
private  NeuriteExtractor2D.NeuronColor neuronColor
           
private  MTBImageByte neuronImage
          Define extractor parameters.
private  MTBNeuriteSkelGraph neuronSkelGraph
          NSG of the whole neuron.
private  de.unihalle.informatik.Alida.datatypes.ALDDirectoryString outputDir
           
private  org.rosuda.JRI.Rengine rEngine
          R engine to call R scripts.
private  MTBImageByte skelImage
          Binary skeleton image of the whole neuron.
private  int width
          Width of the binary neuron image.
 
Fields inherited from class de.unihalle.informatik.Alida.operator.ALDOperator
completeDAG, name, portHashAccess, verbose, versionProvider
 
Constructor Summary
NeuriteExtractor2D()
          Standard constructor.
NeuriteExtractor2D(MTBImageByte _neuronImage, NeuriteExtractor2D.NeuronColor _neuronColor, int _neuriteMaskSize, int _maxSpineLength, org.rosuda.JRI.Rengine _rEngine, java.lang.String _outputDir)
          Constructor to create a new neurite extraction object.
 
Method Summary
private  boolean callNeuriteScript(java.lang.String sourceFile, java.lang.String scriptArg)
          Call a specified R script for neurite calculations.
 void cleanNeurites(MTBNeurite2DSet tmpNeuriteSet)
          Method to clean up the extracted neurites, due to multiple features along a NSG path or feature shifts at the start point due to different NSG lengths.
private  org.rosuda.JRI.Rengine createRengine()
          Method to generate a R thread inside the java application.
 MTBImageByte drawLine2D(java.awt.geom.Line2D.Double line, java.awt.geom.Point2D.Double point)
          Draws a 2D line into the neuron image.
private  MTBRegion2D generateCoarseSoma()
          Compute a coarse neuron cell body region (soma).
private  MTBRegion2DSet generateNeuriteRegions(java.util.Vector<java.util.Vector<java.util.Vector<java.awt.geom.Line2D.Double>>> lines, java.util.Vector<java.util.Vector<java.util.Vector<java.awt.geom.Point2D.Double>>> points)
          Generate neurite region from calculated features.
private  MTBNeuriteSkelGraph generateSkelGraph()
          Compute the skeleton graph for the complete neuron region.
private  java.awt.geom.Line2D.Double getBorderLine(java.awt.geom.Point2D.Double p, java.awt.geom.Point2D.Double normalVec)
          Get borderlines between soma/neurite shaft and neurite shaft/growth cone.
 MTBNeurite2DSet getExtractedNeurites()
          Get extracted neurites as result of the NeuriteExtraction2D operator.
 int getMaxSpineLength()
          Get maximum length of a spine (filopodia-like protrusion) in pixel.
private  java.util.Vector<java.util.Vector<java.util.Vector<java.awt.geom.Line2D.Double>>> getNeuriteFeatures(java.util.Vector<java.awt.geom.Point2D.Double> startPoints)
          Method to calculate the neurite features from the neurite width profile.
 int getNeuriteMaskSize()
          Get neurite mask size in pixel.
 NeuriteExtractor2D.NeuronColor getNeuronColor()
          Get binary neuron color.
 MTBImageByte getNeuronImage()
          Get input image of the binary neuron.
private  java.awt.geom.Point2D.Double getNormal(java.awt.geom.Point2D.Double p1, java.awt.geom.Point2D.Double p2)
          Get normal vector between two points.
 org.rosuda.JRI.Rengine getREngine()
          Get R engine.
private  java.util.Vector<java.awt.geom.Point2D.Double> getStartPoints()
          Get the skeleton start points of every single neurite from the inside of the coarse cell body region.
private  void init()
          Initialization method.
protected  void operate()
           
private static boolean saveNeuriteWidthList(java.util.Vector<java.lang.Double[]> neuriteWidths, java.lang.String file)
          Method to save the neurites width profile in a file.
 void setMaxSpineLength(int _maxSpineLength)
          Set maximum length of a spine (filopodia-like protrusion) in pixel.
 void setNeuronColor(NeuriteExtractor2D.NeuronColor _neuronColor)
          Set binary neuron color.
 void setNeuronImage(MTBImageByte _neuronImage)
          Set input image of the binary neuron.
 void setNuriteMaskSize(int _neuriteMaskSize)
          Set neurite mask size in pixel.
 void setREngine(org.rosuda.JRI.Rengine _rEngine)
          Set R engine.
private  java.awt.geom.Point2D.Double standardization(java.awt.geom.Point2D.Double p)
          Get unit vector.
 void validateCustom()
          Custom validation of some input parameters.
 
Methods inherited from class de.unihalle.informatik.MiToBo.core.operator.MTBOperator
readResolve
 
Methods inherited from class de.unihalle.informatik.Alida.operator.ALDOperator
deserializeFromXmlFile, fieldContained, getALDPortHashAccessKey, getConstructionMode, getInInoutNames, getInInoutNames, getInNames, getInOutNames, getMissingRequiredInputs, getName, getNumParameters, getOutInoutNames, getOutNames, getParameter, getParameterDescriptor, getParameterNames, getSupplementalNames, getVerbose, getVersion, isConfigured, parametersToXmlObject, print, print, print, printInterface, printInterface, readHistory, reinitializeParameterDescriptors, runOp, runOp, runOp, serializeToXmlFile, setConstructionMode, setName, setParameter, setParametersFromXml, setParametersFromXml, setVerbose, toStringVerbose, unconfiguredItems, validate, validateGeneric, writeHistory, writeHistory, writeHistory, writeParametersToXml
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

avgNeuriteWidths

private transient java.util.Vector<java.util.Vector<java.lang.Double>> avgNeuriteWidths
Vector of neurite widths, containing 3 elements. 1. average width of whole neurite, 2. average width of neurite shaft, and 3. average width of growth cone.


extractedNeurites

@Parameter(label="Extracted Neurites",
           required=true,
           direction=OUT,
           description="Set of extracted neurites.")
private transient MTBNeurite2DSet extractedNeurites

featurePoints

private transient java.util.Vector<java.util.Vector<java.util.Vector<java.awt.geom.Point2D.Double>>> featurePoints
Vector of detected feature points for each neurite. Each extracted neurite has at least 2 features. One for the borderline between soma and neurite shaft and o0ne for the borderline between neurite shaft and growth cone.


height

private transient int height
Height of the binary neuron image.


maxSpineLength

@Parameter(label="Maximum Spine Length",
           required=true,
           direction=IN,
           description="Maximum length of a spine in pixel.",
           mode=STANDARD,
           dataIOOrder=4)
private int maxSpineLength

neuriteGraphs

private transient java.util.Vector<MTBNeuriteSkelGraph> neuriteGraphs
Vector of neurite graphs, one for each localized neurite.


neuriteMaskSize

@Parameter(label="Neurite Mask Size",
           required=true,
           direction=IN,
           description="Neurite mask size in pixel.",
           mode=STANDARD,
           dataIOOrder=2)
private int neuriteMaskSize

neuriteShaftLengths

private transient int[] neuriteShaftLengths
Array of detected lengths of the neurite shafts, without growth cone regions.


neuronCoarseSoma

private transient MTBRegion2D neuronCoarseSoma
2D region of the coarse cell body region (soma).


neuronColor

@Parameter(label="Binary Neuron Color",
           required=true,
           direction=IN,
           description="Binary color of the neuron.",
           mode=STANDARD,
           dataIOOrder=3)
private NeuriteExtractor2D.NeuronColor neuronColor

neuronImage

@Parameter(label="Binary Neuron Image",
           required=true,
           direction=IN,
           description="Binary neuron input image.",
           mode=STANDARD,
           dataIOOrder=0)
private transient MTBImageByte neuronImage
Define extractor parameters.


neuronSkelGraph

private transient MTBNeuriteSkelGraph neuronSkelGraph
NSG of the whole neuron.


outputDir

@Parameter(label="Output Directory",
           required=true,
           direction=IN,
           description="Output directory for neurite extraction.",
           mode=STANDARD,
           dataIOOrder=1)
private de.unihalle.informatik.Alida.datatypes.ALDDirectoryString outputDir

rEngine

private transient org.rosuda.JRI.Rengine rEngine
R engine to call R scripts.


skelImage

private transient MTBImageByte skelImage
Binary skeleton image of the whole neuron.


width

private transient int width
Width of the binary neuron image.

Constructor Detail

NeuriteExtractor2D

public NeuriteExtractor2D()
                   throws de.unihalle.informatik.Alida.exceptions.ALDOperatorException
Standard constructor.

Throws:
de.unihalle.informatik.Alida.exceptions.ALDOperatorException

NeuriteExtractor2D

public NeuriteExtractor2D(MTBImageByte _neuronImage,
                          NeuriteExtractor2D.NeuronColor _neuronColor,
                          int _neuriteMaskSize,
                          int _maxSpineLength,
                          org.rosuda.JRI.Rengine _rEngine,
                          java.lang.String _outputDir)
                   throws de.unihalle.informatik.Alida.exceptions.ALDOperatorException
Constructor to create a new neurite extraction object.

Parameters:
_neuronImage - binary neuron image
_neuronColor - binary neuron color, e.g. 0 (black) or 255 (white)
_neuriteMaskSize - mask size of average neurite width, in pixel
_maxSpineLength - maximum length of a branch to define it as spine, in pixel
_rEngine - engine to call R scripts
_outputFile - file path for feature output
Throws:
de.unihalle.informatik.Alida.exceptions.ALDOperatorException
Method Detail

callNeuriteScript

private boolean callNeuriteScript(java.lang.String sourceFile,
                                  java.lang.String scriptArg)
Call a specified R script for neurite calculations.

Parameters:
sourceFile - neurite calculation R script file
scriptArg - input directory path for the R script
Returns:
True if R call is done successfully.

cleanNeurites

public void cleanNeurites(MTBNeurite2DSet tmpNeuriteSet)
Method to clean up the extracted neurites, due to multiple features along a NSG path or feature shifts at the start point due to different NSG lengths.

Parameters:
tmpNeuriteSet - current temporary neurite set

createRengine

private org.rosuda.JRI.Rengine createRengine()
Method to generate a R thread inside the java application.

Returns:
Generated R engine.

drawLine2D

public MTBImageByte drawLine2D(java.awt.geom.Line2D.Double line,
                               java.awt.geom.Point2D.Double point)
Draws a 2D line into the neuron image.

This function implements the Bresenham algorithm. Code was 'stolen' from Wikipedia, http://de.wikipedia.org/wiki/Bresenham-Algorithmus, and then translated into Java (German comments where kept).

Parameters:
xstart - x-coordinate of start point.
ystart - y-coordinate of start point.
xend - x-coordinate of end point.
yend - y-coordinate of end point.
value - Color/gray-scale value of the polygon.

generateCoarseSoma

private MTBRegion2D generateCoarseSoma()
Compute a coarse neuron cell body region (soma). This region is later used to compute an more exact soma region of the neuron and split off the neurites from the soma area.


generateNeuriteRegions

private MTBRegion2DSet generateNeuriteRegions(java.util.Vector<java.util.Vector<java.util.Vector<java.awt.geom.Line2D.Double>>> lines,
                                              java.util.Vector<java.util.Vector<java.util.Vector<java.awt.geom.Point2D.Double>>> points)
Generate neurite region from calculated features. The soma is excluded, so that only the neurite regions remain.

Parameters:
lines - detected feature lines for every neurite
points - detected feature points for every feature line
Returns:
Set of neurite regions.

generateSkelGraph

private MTBNeuriteSkelGraph generateSkelGraph()
Compute the skeleton graph for the complete neuron region. After the skeleton was calculated, the skeleton graph is computed due to one end point of the skeleton and then build up the graph, starting at this point.

Returns:
The computed neuron skeleton graph.

getBorderLine

private java.awt.geom.Line2D.Double getBorderLine(java.awt.geom.Point2D.Double p,
                                                  java.awt.geom.Point2D.Double normalVec)
Get borderlines between soma/neurite shaft and neurite shaft/growth cone. The borderline is extracted using the feature point and the normal vector, using a point before and after the feature point.

Parameters:
p - feature point
normalVec - normal vector for feature point
Returns:
Borderline as Line.2D.double object.

getExtractedNeurites

public MTBNeurite2DSet getExtractedNeurites()
Get extracted neurites as result of the NeuriteExtraction2D operator.

Returns:
Set of MTBNeurite2D objects.

getMaxSpineLength

public int getMaxSpineLength()
Get maximum length of a spine (filopodia-like protrusion) in pixel.


getNeuriteFeatures

private java.util.Vector<java.util.Vector<java.util.Vector<java.awt.geom.Line2D.Double>>> getNeuriteFeatures(java.util.Vector<java.awt.geom.Point2D.Double> startPoints)
Method to calculate the neurite features from the neurite width profile. The neurite width profile is generated from the neurite skeleton graphs of every single detected neurite. The neurite graphs built up from the given start points.

Parameters:
startPoints - points to build up the single neurite graphs
Returns:
Vector with neurite features. First element is the soma feature position (borderline between soma region and neurite shaft), second is the growth cone feature position (borderline between neurite shaft and growth cone region).

getNeuriteMaskSize

public int getNeuriteMaskSize()
Get neurite mask size in pixel. This value defines the maximum average width of a neurite.


getNeuronColor

public NeuriteExtractor2D.NeuronColor getNeuronColor()
Get binary neuron color. WHITE = 255 and BLACK = 0.


getNeuronImage

public MTBImageByte getNeuronImage()
Get input image of the binary neuron. Maybe the binary colors have changed. The default is black for background and white for foreground pixels.


getNormal

private java.awt.geom.Point2D.Double getNormal(java.awt.geom.Point2D.Double p1,
                                               java.awt.geom.Point2D.Double p2)
Get normal vector between two points.

Parameters:
p1 - first point
p2 - second point
Returns:
Point of normal vector.

getREngine

public org.rosuda.JRI.Rengine getREngine()
Get R engine.


getStartPoints

private java.util.Vector<java.awt.geom.Point2D.Double> getStartPoints()
                                                               throws NeuriteExtractor2DException
Get the skeleton start points of every single neurite from the inside of the coarse cell body region. Every start point will be used to build up an MTBNeuriteSkelGraph for every neurite of the neuron.

Returns:
Vector of starting points for every neurite region.
Throws:
NeuriteExtractor2DException

init

private void init()
Initialization method.


operate

protected void operate()
                throws de.unihalle.informatik.Alida.exceptions.ALDOperatorException,
                       de.unihalle.informatik.Alida.exceptions.ALDProcessingDAGException
Specified by:
operate in class de.unihalle.informatik.Alida.operator.ALDOperator
Throws:
de.unihalle.informatik.Alida.exceptions.ALDOperatorException
de.unihalle.informatik.Alida.exceptions.ALDProcessingDAGException

saveNeuriteWidthList

private static boolean saveNeuriteWidthList(java.util.Vector<java.lang.Double[]> neuriteWidths,
                                            java.lang.String file)
Method to save the neurites width profile in a file.

Parameters:
neuriteWidths - width values of the neurite
file - file name for storing the data
Returns:
Saved file true or false.

setMaxSpineLength

public void setMaxSpineLength(int _maxSpineLength)
Set maximum length of a spine (filopodia-like protrusion) in pixel.


setNeuronColor

public void setNeuronColor(NeuriteExtractor2D.NeuronColor _neuronColor)
Set binary neuron color. WHITE = 255 and BLACK = 0.


setNeuronImage

public void setNeuronImage(MTBImageByte _neuronImage)
Set input image of the binary neuron.


setNuriteMaskSize

public void setNuriteMaskSize(int _neuriteMaskSize)
Set neurite mask size in pixel. This value defines the maximum average width of a neurite.


setREngine

public void setREngine(org.rosuda.JRI.Rengine _rEngine)
Set R engine.


standardization

private java.awt.geom.Point2D.Double standardization(java.awt.geom.Point2D.Double p)
Get unit vector.

Parameters:
p - point of vector, other coordinate is (0,0)
Returns:
Unit vector.

validateCustom

public void validateCustom()
                    throws de.unihalle.informatik.Alida.exceptions.ALDOperatorException
Custom validation of some input parameters.

Overrides:
validateCustom in class de.unihalle.informatik.Alida.operator.ALDOperator
Throws:
de.unihalle.informatik.Alida.exceptions.ALDOperatorException