de.unihalle.informatik.MiToBo.apps.neurites2D

Class NeuriteExtractor2D

java.lang.Object

de.unihalle.informatik.Alida.operator.ALDOperator

de.unihalle.informatik.MiToBo.core.operator.MTBOperator

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

All Implemented Interfaces:

de.unihalle.informatik.Alida.datatypes.ALDConfigurationValidator, de.unihalle.informatik.Alida.operator.events.ALDOperatorExecutionProgressEventListener, EventListener

@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

Nested Classes

Modifier and Type	Class and Description
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, de.unihalle.informatik.Alida.operator.ALDOperator.HistoryConstructionMode

Field Summary

Fields

Modifier and Type	Field and Description
private Vector<Vector<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 Vector<Vector<Vector<Point2D.Double>>>	featurePoints Vector of detected feature points for each neurite.
private int	height Height of the binary neuron image.
private int	maxSpineLength
private 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, operatorExecutionEventlistenerList, portHashAccess, verbose, versionProvider

Constructor Summary

Constructors

Constructor and Description
NeuriteExtractor2D() Standard constructor.
NeuriteExtractor2D(MTBImageByte _neuronImage, NeuriteExtractor2D.NeuronColor _neuronColor, int _neuriteMaskSize, int _maxSpineLength, org.rosuda.JRI.Rengine _rEngine, String _outputDir) Constructor to create a new neurite extraction object.

Method Summary

Modifier and Type	Method and Description
private boolean	callNeuriteScript(String sourceFile, 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(Line2D.Double line, 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(Vector<Vector<Vector<Line2D.Double>>> lines, Vector<Vector<Vector<Point2D.Double>>> points) Generate neurite region from calculated features.
private MTBNeuriteSkelGraph	generateSkelGraph() Compute the skeleton graph for the complete neuron region.
private Line2D.Double	getBorderLine(Point2D.Double p, 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 Vector<Vector<Vector<Line2D.Double>>>	getNeuriteFeatures(Vector<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 Point2D.Double	getNormal(Point2D.Double p1, Point2D.Double p2) Get normal vector between two points.
org.rosuda.JRI.Rengine	getREngine() Get R engine.
private Vector<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(Vector<Double[]> neuriteWidths, 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	setNeuriteMaskSize(int _neuriteMaskSize) Set neurite mask size in pixel.
void	setNeuronColor(NeuriteExtractor2D.NeuronColor _neuronColor) Set binary neuron color.
void	setNeuronImage(MTBImageByte _neuronImage) Set input image of the binary neuron.
void	setREngine(org.rosuda.JRI.Rengine _rEngine) Set R engine.
private Point2D.Double	standardization(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

addOperatorExecutionProgressEventListener, addParameter, addParameter, addParameterUnconditioned, fieldContained, fireOperatorExecutionProgressEvent, getALDPortHashAccessKey, getConstructionMode, getDocumentation, getHidingMode, getInactiveParameterNames, getInInoutNames, getInInoutNames, getInNames, getInOutNames, getMissingRequiredInputs, getName, getNumParameters, getOutInoutNames, getOutNames, getParameter, getParameterDescriptor, getParameterDescriptorUnconditioned, getParameterNames, getParameterUnconditioned, getSupplementalNames, getVerbose, getVersion, handleOperatorExecutionProgressEvent, hasInOutParameters, hasParameter, isAnnotatedParameter, isConfigured, print, print, print, printInterface, printInterface, readHistory, reinitializeParameterDescriptors, removeOperatorExecutionProgressEventListener, removeParameter, runOp, runOp, runOp, setConstructionMode, setConstructionMode, setConstructionMode, setHidingMode, setName, setParameter, setParameterUnconditioned, setVerbose, toStringVerbose, unconfiguredItems, validate, validateGeneric, writeHistory, writeHistory, writeHistory

Methods inherited from class java.lang.Object

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

Field Detail

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.

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

neuriteMaskSize

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

neuronColor

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

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

extractedNeurites

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

width

private transient int width

Width of the binary neuron image.

height

private transient int height

Height of the binary neuron image.

rEngine

private transient org.rosuda.JRI.Rengine rEngine

R engine to call R scripts.

neuronCoarseSoma

private transient MTBRegion2D neuronCoarseSoma

2D region of the coarse cell body region (soma).

neuronSkelGraph

private transient MTBNeuriteSkelGraph neuronSkelGraph

NSG of the whole neuron.

skelImage

private transient MTBImageByte skelImage

Binary skeleton image of the whole neuron.

neuriteGraphs

private transient Vector<MTBNeuriteSkelGraph> neuriteGraphs

Vector of neurite graphs, one for each localized neurite.

featurePoints

private transient Vector<Vector<Vector<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.

neuriteShaftLengths

private transient int[] neuriteShaftLengths

Array of detected lengths of the neurite shafts, without growth cone regions.

avgNeuriteWidths

private transient Vector<Vector<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.

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,
                          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

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

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.

setNeuronImage

public void setNeuronImage(MTBImageByte _neuronImage)

Set input image of the binary neuron.

getNeuronColor

public NeuriteExtractor2D.NeuronColor getNeuronColor()

Get binary neuron color. WHITE = 255 and BLACK = 0.

setNeuronColor

public void setNeuronColor(NeuriteExtractor2D.NeuronColor _neuronColor)

Set binary neuron color. WHITE = 255 and BLACK = 0.

getNeuriteMaskSize

public int getNeuriteMaskSize()

Get neurite mask size in pixel. This value defines the maximum average width of a neurite.

setNeuriteMaskSize

public void setNeuriteMaskSize(int _neuriteMaskSize)

Set neurite mask size in pixel. This value defines the maximum average width of a neurite.

getREngine

public org.rosuda.JRI.Rengine getREngine()

Get R engine.

setREngine

public void setREngine(org.rosuda.JRI.Rengine _rEngine)

Set R engine.

getMaxSpineLength

public int getMaxSpineLength()

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

setMaxSpineLength

public void setMaxSpineLength(int _maxSpineLength)

Set maximum length of a spine (filopodia-like protrusion) in pixel.

getExtractedNeurites

public MTBNeurite2DSet getExtractedNeurites()

Get extracted neurites as result of the NeuriteExtraction2D operator.

Returns:

Set of MTBNeurite2D objects.

init

private void init()

Initialization method.

createRengine

private org.rosuda.JRI.Rengine createRengine()

Method to generate a R thread inside the java application.

Returns:

Generated R engine.

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(Vector<Double[]> neuriteWidths,
                                            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.

callNeuriteScript

private boolean callNeuriteScript(String sourceFile,
                                  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.

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.

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.

getStartPoints

private Vector<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

getNeuriteFeatures

private Vector<Vector<Vector<Line2D.Double>>> getNeuriteFeatures(Vector<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).

getBorderLine

private Line2D.Double getBorderLine(Point2D.Double p,
                                    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.

getNormal

private Point2D.Double getNormal(Point2D.Double p1,
                                 Point2D.Double p2)

Get normal vector between two points.

Parameters:

p1 - first point

p2 - second point

Returns:

Point of normal vector.

standardization

private Point2D.Double standardization(Point2D.Double p)

Get unit vector.

Parameters:

p - point of vector, other coordinate is (0,0)

Returns:

Unit vector.

generateNeuriteRegions

private MTBRegion2DSet generateNeuriteRegions(Vector<Vector<Vector<Line2D.Double>>> lines,
                                              Vector<Vector<Vector<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.

drawLine2D

public MTBImageByte drawLine2D(Line2D.Double line,
                               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.

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