Class ROI

java.lang.Object
com.xinapse.multisliceimage.roi.ROI
Direct Known Subclasses:
EllipticalROI, HollowROI, IrregularROI, LineROI, Marker, RadialDivider, RectangularROI, SplineROI
public abstract class ROI extends Object
A Class representing a region of interest. A region of interest's shape is stored internally in real-space (mm) coordinates and it has space-related statistics, such as area (in square mm) and length (in mm). However, when a region is associated with an image, it may be drawn onto a slice of that image, and its intensity-related statistics may be computed. Methods that associate an ROI with an image will always supply the dimensions of the image pixel matrix, and the pixel sizes.

An ROI has three representations:

  • The shape is fundamentally represented in mm coordinate space.
  • When associated with an image slice, there is a cached representation in image pixel coordinates.
  • When an ROI is visible on-screen, there is a cached representation in screen coordinates.
Whenever the ROI is moved, or the shape is changed, the caches are cleared, and the representations in pixel and screen coordinates are recalculated as needed.

The origin of the real-space (mm) coordinates is at the centre of the field of view.

An ROI has an audit-trail history, consisting of a creation history item, a list of modfication items, and if deleted, a deletion history item.

  • Field Details

    • PREFERENCES_NODE_NAME

      public static final String PREFERENCES_NODE_NAME
      The node name for all Preferences to do with ROIs.
      See Also:

    • BUTTON_ICON_SCALE

      public static final float BUTTON_ICON_SCALE
      The standard (square) size for icons on ROI creation buttons.
      See Also:

    • XTOKEN

      public static final String XTOKEN
      The token written to ROI output files to represent an x-coordinate.
      See Also:

    • YTOKEN

      public static final String YTOKEN
      The token written to ROI output files to represent a y-coordinate.
      See Also:

  • Method Details

    • getTextColor

      public static Color getTextColor()
      Returns the Color with which ROI annotation text should be rendered.
      Returns:
      the Color with which ROI annotation text should be rendered.

    • getDesignTextFontSize

      public static int getDesignTextFontSize()
      Returns the font size at which ROI annotation text should be rendered.
      Returns:
      the font size at which ROI annotation text should be rendered.

    • clearDeletionHistory

      public void clearDeletionHistory()
      Removes the deletion HistoryItem for this ROI. Needed to "undelete" an ROI.

    • getDescription

      public abstract String getDescription()
      Return a description of this type of ROI.
      Returns:
      a String describing the type of this ROI.

    • move

      public abstract void move(double dx, double dy)
      Move this ROI by specified distances (in mm) in the x and y directions.
      Parameters:
      dx - the distance to move in the x-direction.
      dy - the distance to move in the y-direction.

    • stretch

      public abstract void stretch(double dx, double dy, double stretchX, double stretchY)
      Moves and stretches an ROI. A stretch value is a scaling factor for dimensions in either the horizontal or vertical directions. A stretch of 1.0 means no stretch.
      Parameters:
      dx - the distance (in mm) to move the centre of the ROI in the horizontal direction.
      dy - the distance (in mm) to move the centre of the ROI in the vertical direction.
      stretchX - the stretch in the horizontal direction.
      stretchY - the stretch in the vertical direction.

    • flipVertical

      public abstract void flipVertical(Point2D flipPoint)
      Flip this ROI vertically about a given location.
      Parameters:
      flipPoint - the point about which the ROI will be flipped.

    • flipHorizontal

      public abstract void flipHorizontal(Point2D flipPoint)
      Flip this ROI horizontally about a given location.
      Parameters:
      flipPoint - the point about which the ROI will be flipped.

    • union

      public List<ROI> union(ROI roi, IndeterminateProgressMonitor progressMonitor) throws ROIException, CancelledException
      Logically add (forms the union) an ROI to this ROI to create a new List<ROI> of ROIs that is the result of adding the shapes of the two ROIs.
      Parameters:
      roi - the ROI to add.
      progressMonitor - if non-null, the IndeterminateProgressMonitor that can be used to cancel the operation.
      Returns:
      a List<ROI> of ROIs that results from the addition of the shape.
      Throws:
      ROIException - if an error occurs while constructing the new ROIs.
      CancelledException - if the operation is cancelled by the user.

    • logicalUnion

      public static List<ROI> logicalUnion(List<ROI> rois, IndeterminateProgressMonitor progressMonitor) throws ROIException, CancelledException
      Logically adds a List of ROIs to create a new List<ROI> of ROIs that is the result of logically adding (forming the union of) the shapes of the ROIs.
      Parameters:
      rois - the ROIs to add.
      progressMonitor - if non-null, the IndeterminateProgressMonitor that can be used to cancel the operation.
      Returns:
      a List<ROI> of ROIs that results from the addition of the shape.
      Throws:
      ROIException - if creation of the new ROIs generates an error.
      CancelledException - if the operation is cancelled by the user.

    • union

      public List<ROI> union(List<ROI> rois, IndeterminateProgressMonitor progressMonitor) throws ROIException, CancelledException
      Logically forms the union of a List of ROIs and this ROI to create a new List<ROI> of ROIs that is the result of adding (forming the union of) the shapes of the ROIs to this ROI.
      Parameters:
      rois - the ROIs to add.
      progressMonitor - if non-null, the IndeterminateProgressMonitor that can be used to cancel the operation.
      Returns:
      a List<ROI> of ROIs that results from the addition of the shapes.
      Throws:
      ROIException - if creation of the new ROIs generates an error.
      CancelledException - if the operation is cancelled by the user.

    • andNot

      public List<ROI> andNot(ROI roi) throws ROIException
      Logically AND NOTs (subtracts) an ROI from this ROI to create a new List<ROI> of ROIs that is the result of subtracting the shape of the supplied ROI from this ROI.
      Parameters:
      roi - the ROI to subtract.
      Returns:
      a List<ROI> of ROIs that results from the subtraction of the ROI.
      Throws:
      ROIException - if creation of the new ROIs generates an error.

    • andNot

      public List<ROI> andNot(ROI roi, IndeterminateProgressMonitor progressMonitor) throws ROIException, CancelledException
      Logically AND NOTs (subtracts) an ROI from this ROI to create a new List<ROI> of ROIs that is the result of subtracting the shape of the supplied ROI from this ROI.
      Parameters:
      roi - the ROI to subtract.
      progressMonitor - if non-null, the IndeterminateProgressMonitor that can be used to cancel the operation.
      Returns:
      a List<ROI> of ROIs that results from the subtraction of the ROI.
      Throws:
      ROIException - if creation of the new ROIs generates an error.
      CancelledException - if the operation is cancelled by the user.

    • andNot

      public List<ROI> andNot(List<ROI> rois, IndeterminateProgressMonitor progressMonitor) throws ROIException, CancelledException
      Logically AND NOTs (subtracts) a List of ROIs from this ROI to create a new List<ROI> of ROIs that is the result of subtracting the shapes of the ROIs.

      ROIs are subtracted in the same order as they appear in the list.

      Parameters:
      rois - the ROIs to subtract.
      progressMonitor - if non-null, the IndeterminateProgressMonitor that can be used to cancel the operation.
      Returns:
      a List<ROI> of ROIs that results from the subtraction of the ROIs.
      Throws:
      ROIException - if creation of the new ROIs generates an error.
      CancelledException - if the operation is cancelled by the user.

    • intersects

      public boolean intersects(ROI roi)
      Tests whether this ROI intersects another ROI.

      Note that the ROIs may intersect, but the area of intersection may be zero if one or other (or both) of the ROIs contains no area.

      Parameters:
      roi - the ROI to be tested for intersection.
      Returns:
      true in the two ROIs intersect; false otherwise.

    • intersect

      public List<ROI> intersect(ROI roi) throws ROIException
      Intersects this ROI with another ROI.
      Parameters:
      roi - the ROI to intersect with this ROI.
      Returns:
      the resulting List<ROI> of ROIs that result from the operation.
      Throws:
      ROIException - if the operation cannot be performed.

    • intersect

      public List<ROI> intersect(ROI roi, IndeterminateProgressMonitor progressMonitor) throws ROIException, CancelledException
      Performs an intersection operation on the shape of this ROI with another ROI.
      Parameters:
      roi - the ROI with which to perform the intersection operation.
      progressMonitor - if non-null, the IndeterminateProgressMonitor that can be used to cancel the operation.
      Returns:
      a List<ROI> of ROIs that result from the operation.
      Throws:
      ROIException - if the operation cannot be performed.
      CancelledException - if the operation is cancelled by the user.

    • intersect

      public List<ROI> intersect(List<ROI> rois, IndeterminateProgressMonitor progressMonitor) throws ROIException, CancelledException
      Performs an intersection operation on the shape of this ROI with a List of other ROIs.
      Parameters:
      rois - the List of ROIs with which to perform the intersection operation.
      progressMonitor - if non-null, the IndeterminateProgressMonitor that can be used to cancel the operation.
      Returns:
      a List<ROI> of ROIs that result from the operation.
      Throws:
      ROIException - if the operation cannot be performed.
      CancelledException - if the operation is cancelled by the user.

    • exclusiveOr

      public List<ROI> exclusiveOr(ROI roi, IndeterminateProgressMonitor progressMonitor) throws ROIException, CancelledException
      Performs an exclusive OR operation on the shape of this ROI with another ROI.
      Parameters:
      roi - the ROI with which to perform the XOR operation.
      progressMonitor - if non-null, the IndeterminateProgressMonitor that can be used to cancel the operation.
      Returns:
      a List<ROI> of ROIs that result from the operation.
      Throws:
      ROIException - if the operation cannot be performed.
      CancelledException - if the operation is cancelled by the user.

    • exclusiveOr

      public List<ROI> exclusiveOr(List<ROI> rois, IndeterminateProgressMonitor progressMonitor) throws ROIException, CancelledException
      Performs an exclusive OR (XOR) operation on the shape of this ROI with another ROI.
      Parameters:
      rois - the ROI with which to perform the XOR operations.
      progressMonitor - if non-null, the IndeterminateProgressMonitor that can be used to cancel the operation.
      Returns:
      a List<ROI> of ROIs that result from the operation.
      Throws:
      ROIException - if the operation cannot be performed.
      CancelledException - if the operation is cancelled by the user.

    • dilate

      public List<ROI> dilate(double radius)
      Dilates this ROI by the specified distance.
      Parameters:
      radius - the radius of dilation. A positive radius will result in a dilation, while a negative radius will result in an erosion.
      Returns:
      a List of ROIs that result from the operation. The List will be empty if the dilation results in an empty region.

    • markDeleted

      public void markDeleted()
      Mark this ROI as deleted.

    • group

      public static void group(List<ROI> rois)
      Form an ROI group from a List of ROIs.
      Parameters:
      rois - the ROIs to group.

    • ungroup

      public static void ungroup(List<ROI> rois, com.xinapse.dicom.Uid uid)
      Ungroups the ROIs belonging to a particular ROI group.
      Parameters:
      rois - a List of ROIs.
      uid - the UID for the group to be ungrouped.

    • ungroup

      public static int ungroup(List<ROI> rois)
      Ungroups all ROIs in the list.
      Parameters:
      rois - a List of ROIs.
      Returns:
      the number of groups that were ungrouped.

    • getGroupUid

      public com.xinapse.dicom.Uid getGroupUid()
      Returns the group UID for this ROI.
      Returns:
      the group uid for this ROI, or null if it not part of a group.

    • setGroupUid

      public void setGroupUid(com.xinapse.dicom.Uid uid)
      Sets the group UID for this ROI.
      Parameters:
      uid - the group uid for this ROI, or null if it not to be part of a group.

    • isGroup

      public static boolean isGroup(List<ROI> roiList)
      Tests whether all the ROIs supplied are members of the same group (i.e., they all have the same Group UID).
      Parameters:
      roiList - the List of ROIs to test for group membership.
      Returns:
      true if all the ROIs are members of one group; false otherwise.

    • getGroupUid

      public static com.xinapse.dicom.Uid getGroupUid(List<ROI> roiList)
      Returns the Group UID of the ROIs supplied if they are all members of the same group (i.e., they all have the same Group UID).
      Parameters:
      roiList - the List of ROIs for which to return the group UID.
      Returns:
      Returns the Group UID of the ROIs supplied, or null if they are not all members of the same group.

    • isSameAnnotation

      public static boolean isSameAnnotation(List<ROI> roiList)
      Tests whether all the ROIs supplied have the same annotation.
      Parameters:
      roiList - the List of ROIs to see whether thy all have the same annotation.
      Returns:
      true if all the ROIs have the same annotation; false otherwise.

    • isSameColour

      public static boolean isSameColour(List<ROI> roiList)
      Tests whether all the ROIs supplied have the same colour.
      Parameters:
      roiList - the List of ROIs to see whether thy all have the same colour.
      Returns:
      true if all the ROIs have the same colour; false otherwise.

    • contains

      public abstract boolean contains(ROI roi)
      Indicates whether this ROI entirely contains another ROI entirely within its borders. If the supplied ROI just touches the border, then it is not contained within this ROI.
      Parameters:
      roi - the ROI to be tested for containment within this ROI.
      Returns:
      true if the supplied ROI is contained within this ROI; false otherwise.

    • equals

      public abstract boolean equals(Object o)
      Indicates whether some Object is equal to this ROI. To be equal, the Object must be an ROI of the same type, and of the same shape and location as this ROI.
      Overrides:
      equals in class Object
      Parameters:
      o - the Object to be tested for equality to this ROI.
      Returns:
      true if the supplied Object is an ROI of the same type, shape and location as this ROI; false otherwise.

    • hashCode

      public int hashCode()
      Returns a hash code value for the ROI. This method is supported for the benefit of hashtables such as those provided by Hashtable.
      Overrides:
      hashCode in class Object
      Returns:
      a hash code value for this ROI.

    • set

      public abstract void set(ROI roi) throws ClassCastException
      Sets the shape of this ROI to the shape of the supplied argument ROI.
      Parameters:
      roi - the ROI from which the shape is set.
      Throws:
      ClassCastException - if the sub-class of the argument ROI is not the same as this ROI.

    • getCopy

      public abstract ROI getCopy()
      Returns a copy of this ROI. The copy will be identical in shape and annotation as the original ROI, but with a history of that of a newly-created ROI.
      Returns:
      a copy of this ROI.

    • toString

      public abstract String toString()
      Returns a String describing this ROI.
      Overrides:
      toString in class Object
      Returns:
      a String describing this ROI.

    • getHandleUnderPoint

      public Handle getHandleUnderPoint(Point point)
      Returns the Handle of this ROI that is under the point supplied (in screen coordinates).
      Parameters:
      point - the point to test whether there is a handle there.
      Returns:
      the Handle under the point, or null if there is no Handle under the point.

    • getHandles

      public Handle[] getHandles()
      Returns an array of Handles that this ROI has.
      Returns:
      the Handles for this ROI, or null if it has none.

    • getState

      public ROIState getState()
      Returns the state of this ROI.
      Returns:
      the ROIState of this ROI. One of: ROIState.DELETED, ROIState.DELETED_SELECTED, ROIState.NORMAL, ROIState.SELECTED, ROIState.EDITABLE, ROIState.EDIT_OUTLINE.

    • setState

      public void setState(ROIState state)
      Sets the state of this ROI.
      Parameters:
      state - the ROIState of this ROI to be set. One of: ROIState.DELETED, ROIState.DELETED_SELECTED, ROIState.NORMAL, ROIState.SELECTED, ROIState.EDITABLE, ROIState.EDIT_OUTLINE.

    • isSelected

      public boolean isSelected()
      Returns true if this ROI is currently selected.
      Returns:
      true if this ROI is currently selected; false otherwise.

    • isEditable

      public boolean isEditable()
      Returns true if this ROI is currently editable.
      Returns:
      true if this ROI is currently editable; false otherwise.

    • isDeleted

      public boolean isDeleted()
      Returns true if this ROI has been deleted.
      Returns:
      true if this ROI has been deleted; false otherwise.

    • getImageSource

      public String getImageSource()
      Returns the image source of this ROI. Normally the path name of the image on which this ROI was defined.
      Returns:
      the image source of this ROI.

    • isReloaded

      public boolean isReloaded()
      Returns true if this ROI has been reloaded from disk.
      Returns:
      true if this ROI has been reloaded from disk; false otherwise.

    • getStats

      public static ROIStats getStats(List<? extends ROI> ROIs, Object pix, PixelDataType dataType, int nCols, int nRows, int offset, float pixelXSize, float pixelYSize, CombineMode combineMode, MaskAction maskAction, MaskMode maskMode, double maskValue, ComplexMode complexMode)
      Find combined statistics about a list of ROIs. The ROI statistics are returned for the shape that is combination of all the individual ROIs in the List, when they are combined using the specified CombineMode.
      Parameters:
      ROIs - a List of ROIs.
      pix - the whole image pixel value array. If pix is null, then the intensity-related stats will all be set to zero.
      dataType - the type of pixels.
      nCols - the number of columns in the slice.
      nRows - the number of rows in the slice.
      offset - an offset (in pixels) into the pixel value array for the starting pixel of the slice on which this ROI is defined.
      pixelXSize - the size of image pixels in the horizontal direction.
      pixelYSize - the size of image pixels in the vertical direction.
      combineMode - one of CombineMode.UNION for creating statistics about the union of all ROIs. CombineMode.INTERSECTION for creating statistics about the intersection of all ROIs. CombineMode.XOR for creating statistics about the sequential exclusive OR of all all ROIs. Starting with the first pair of ROIs in the list, an exclusive OR operation is applied pair-wise to the ROIs, and the resulting ROIs is exclusive OR'd with the next ROI in the list until the list is exhausted.
      maskAction - one of:
      maskMode - how much of a pixel must be inside ROIs for the pixel to be part of the mask.
      maskValue - the pixel value to set outside/inside the shape when performing masking ops.
      complexMode - the calculation mode for Complex images. The statistics returned will correspond to the mode: the real part, imaginary part, magnitude or phase.
      Returns:
      statistics about the combined shape. If list is empty, or the combined shape is an empty (null) area, then null will be returned.

    • getStats

      public ROIStats getStats(Object pix, PixelDataType dataType, int nCols, int nRows, int offset, float pixelXSize, float pixelYSize, ComplexMode complexMode)
      Returns statistics about this ROI.
      Parameters:
      pix - the whole image pixel value array. If pix is null, then the intensity-related stats will all be set to zero.
      dataType - the PixelDataType of the image pixels.
      nCols - the number of columns in the slice.
      nRows - the number of rows in the slice.
      offset - an offset (in pixels) into the pixel value array for the starting pixel of the slice on which this ROI is defined.
      pixelXSize - the size of image pixels in the horizontal direction.
      pixelYSize - the size of image pixels in the vertical direction.
      complexMode - the calculation mode for Complex images. The statistics returned will correspond to the mode: the real part, imaginary part, magnitude or phase.
      Returns:
      statistics about the ROI.

    • getStats

      public ROIStats getStats(Object pix, PixelDataType dataType, int nCols, int nRows, int offset, float pixelXSize, float pixelYSize, MaskAction maskAction, MaskMode maskMode, double maskValue, PrintStream intensityOutputStream, boolean isUnitsMM, ComplexMode complexMode)
      Returns statistics about this ROI, and (optionally) performs a masking operation.
      Parameters:
      pix - the whole image pixel value array. If pix is null, then the intensity-related stats will all be set to zero.
      dataType - the type of pixels.
      nCols - the number of columns in the slice.
      nRows - the number of rows in the slice.
      offset - an offset (in pixels) into the pixel value array for the starting pixel of the slice on which this ROI is defined.
      pixelXSize - the size of image pixels in the horizontal direction.
      pixelYSize - the size of image pixels in the vertical direction.
      maskAction - one of:
      maskMode - how much of a pixel must be inside ROIs for the pixel to be part of the mask.
      maskValue - the pixel value to set outside/inside the shape when performing masking ops.
      intensityOutputStream - if non-null, pixel intensities within the ROI will be printed to this PrintStream.
      isUnitsMM - true if the (x,y) coordinates of the pixel intensities are to be written in mm, false if the coordinates are to be writtn in pixel units.
      complexMode - the calculation mode for PixelDataType.COMPLEX images. The statistics returned will correspond to the mode: the real part, imaginary part, magnitude or phase.
      Returns:
      statistics about the ROI.

    • writeCoordinates

      public void writeCoordinates(AffineTransform3D atx, int nCols, int nRows, int nSlices, float pixelXSize, float pixelYSize, float pixelZSize, int slice, com.xinapse.geom3d.CoordinateSystem coordSystem, PrintStream ps) throws InvalidImageException
      Write the coordinates of the centre of pixels within an ROI.
      Parameters:
      atx - the AffineTransform3D that transforms pixel column/row/slice coordinates to patient-centred L,P,S coordinates.
      nCols - the number of image columns.
      nRows - the number of image rows.
      nSlices - the number of physical image slice locations.
      pixelXSize - the size of image pixels in the horizontal direction.
      pixelYSize - the size of image pixels in the vertical direction.
      pixelZSize - the image pixel thickness.
      slice - the physical slice number.
      coordSystem - CoordinateSystem in which to write the coordinates.
      ps - the PrintStream to write to.
      Throws:
      InvalidImageException - if the AffineTransform3D to the patient-centred coordinate system is required but not supplied.

    • getSlice

      public int getSlice()
      Returns the slice number for this ROI. Slice numbers are indexed from zero.
      Returns:
      the slice number for this ROI.

    • setSlice

      public void setSlice(int s)
      Sets the slice number for this ROI. Slice numbers are indexed from zero.
      Parameters:
      s - the new slice number for this ROI.

    • getFeret

      public abstract Feret getFeret()
      Returns the minimum and maximum Feret's diameter for this ROI, in mm.
      Returns:
      the minimum and maximum Feret's diameter (in mm) as a Feret object.

    • getFeret

      public static Feret getFeret(List<ROI> ROIs)
      Returns the minimum and maximum Feret's diameter for a List of ROI, in mm.
      Parameters:
      ROIs - the List of ROI for which to return the Feret's diameters.
      Returns:
      the minimum and maximum Feret's diameter (in mm) as a Feret object.

    • getPerimeter

      public abstract double getPerimeter()
      Returns the perimeter length of this ROI.
      Returns:
      the perimeter length of this ROI.

    • getCentroid

      public abstract org.jogamp.vecmath.Point2d getCentroid()
      Returns the centroid (centre of area) of this ROI.
      Returns:
      the centroid of this ROI.

    • getCentroid

      public static Point2D getCentroid(ROI[] rois)
      Returns the centroid (centre of area) of an array of ROIs.
      Parameters:
      rois - the set of ROIs for which to find the centroid.
      Returns:
      the centroid of the array of ROI.

    • write

      public static void write(List<? extends ROI> rois, Writer w, String source, Object pix, int nCols, int nRows, float pixelXSize, float pixelYSize, PixelDataType dataType, ComplexMode complexMode) throws IOException
      Write a List of ROIs using the specified writer.
      Parameters:
      rois - a List<ROI> of ROIs to write.
      w - the Writer using which the ROIs will be written.
      source - a String describing the where the ROIs came from.
      pix - the image pixels used to calculate intensity-related statistics if non-null.
      nCols - the number of columns in the source image.
      nRows - the number of rows in the source image.
      pixelXSize - the size of image pixels in the horizontal direction.
      pixelYSize - the size of image pixels in the vertical direction.
      dataType - the type of pixels for the image on which this ROI was created. This is needed in case the image is Complex, so that the intensity can be correctly annotated.
      complexMode - for Complex images, this affects the way the intensity is annotated, but has no effect for other types of image.
      Throws:
      IOException - if the ROIs cannot be written.

    • write

      public void write(Writer w, String source, Object pix, int nCols, int nRows, float pixelXSize, float pixelYSize, PixelDataType dataType, ComplexMode complexMode) throws IOException
      Writes this ROI in output format using the specified writer.
      Parameters:
      w - the Writer with which this ROI will be written.
      source - a String describing where this ROI came from.
      pix - the image pixels used to calculate intensity-related statistics if non-null.
      nCols - the number of columns in the source image.
      nRows - the number of rows in the source image.
      pixelXSize - the size of image pixels in the horizontal direction.
      pixelYSize - the size of image pixels in the vertical direction.
      dataType - the type of pixels for the image on which this ROI was created. This is needed in case the image is Complex, so that the intensity can be correctly annotated.
      complexMode - for PixelDataType.COMPLEX images, this affects the way the intensity is annotated but has no effect for other types of image.
      Throws:
      IOException - if an I/O error occurs.

    • printStats

      public void printStats(PrintStream s, Object pixels, int nCols, int nRows, float pixelXSize, float pixelYSize, PixelDataType dataType, ComplexMode complexMode, boolean writeColour, boolean writeAnnotation, boolean writeSlice, boolean writeArea, boolean writeMean, boolean writeStddev, boolean writeMin, boolean writeMax, boolean writeMedian, boolean writeLength, boolean writePerimeter, boolean writeFeretMin, boolean writeFeretMax, String separator)
      Prints the statistics about this ROI in output format to a PrintStream.
      Parameters:
      s - the PrintStream to which this ROI will be printed.
      pixels - the image pixel values for the whole image, from which intensity statistics will be calculated.
      nCols - the number of image columns.
      nRows - the number of image rows.
      pixelXSize - the size of image pixels in the horizontal direction.
      pixelYSize - the size of image pixels in the vertical direction.
      dataType - the type of pixels for the image on which this ROI was created. This is needed in case the image is PixelDataType.COMPLEX, so that the intensity can be correctly annotated.
      complexMode - for PixelDataType.COMPLEX images, this affects th e way the intensity is annotated, but has no effect for other types of image.
      writeColour - a flag to indicate that the ROI colour should be written.
      writeAnnotation - a flag to indicate that ROI annotation should be written.
      writeSlice - a flag to indicate that slice number should be written.
      writeArea - a flag to indicate that ROI area should be written.
      writeMean - a flag to indicate that mean intensity should be written.
      writeStddev - a flag to indicate that intensity standard deviation should be written.
      writeMin - a flag to indicate that minimum intensity should be written.
      writeMax - a flag to indicate that maximum intensity should be written.
      writeMedian - a flag to indicate that median intensity of the ROI should be written.
      writeLength - a flag to indicate that length of the ROI should be written. Only applied to LineROI and CurvedLineROI ROIs.
      writePerimeter - a flag to indicate that perimeter length of the ROI should be written.
      writeFeretMin - a flag to indicate that minimum Feret diameter of the ROI should be written.
      writeFeretMax - a flag to indicate that maximum Feret diameter of the ROI should be written.
      separator - the separator to be used to separate the individual statistics.

    • getROIs

      public static List<ROI> getROIs(File f, Float pixelXSize, Float pixelYSize, Integer nCols, Integer nRows) throws IOException
      Returns a List of ROIs read from an input File. If non-null values for the horizontal and vertical fields of view are supplied, then reading of ROI files from dispim is possible. The fields of view must be known since the coordinate system origin for dispim ROIs is at the top left of the image, while for the roi package it is in the centre of the field of view and a coordinate translation must be performed when reading in the ROIs.
      Parameters:
      f - the input File.
      pixelXSize - the pixel size in the horizontal direction (pixel width).
      pixelYSize - the pixel size in the vertical direction (pixel height).
      nCols - the number of image columns (number of samples in the horizontal direction).
      nRows - the number of image rows (number of samples in the vertical direction).
      Returns:
      a List of ROIs read from the File.
      Throws:
      IOException - if there is an error reading the ROIs from the File.

    • getROIs

      public static List<ROI> getROIs(File f, Float pixelXSize, Float pixelYSize, Integer nCols, Integer nRows, MonitorWorker worker) throws IOException, CancelledException
      Returns a List of ROIs read from an input File. If non-null values for the horizontal and vertical fields of view are supplied, then reading of ROI files from dispim is possible. The fields of view must be known since the coordinate system origin for dispim ROIs is at the top left of the image, while for the roi package it is in the centre of the field of view and a coordinate translation must be performed when reading in the ROIs.
      Parameters:
      f - the input File.
      pixelXSize - the pixel size in the horizontal direction (pixel width).
      pixelYSize - the pixel size in the vertical direction (pixel height).
      nCols - the number of image columns (number of samples in the horizontal direction).
      nRows - the number of image rows (number of samples in the vertical direction).
      worker - if non-null the MonitorWorker that can be used to cancel the operation.
      Returns:
      a List of ROIs read from the File.
      Throws:
      IOException - if there is an error reading the ROIs from the File.
      CancelledException - if the operation is cancelled by the user.

    • getROIs

      public static List<ROI> getROIs(InputStream s) throws IOException
      Returns a List of ROIs read from an InputStream.
      Parameters:
      s - the InputStream.
      Returns:
      a List<ROI> of ROIs read from the InputStream.
      Throws:
      IOException - if there is an error reading the ROIs from the InputStream.

    • getROIs

      public static List<ROI> getROIs(InputStream s, Float pixelXSize, Float pixelYSize, Integer nCols, Integer nRows) throws IOException
      Returns a List of ROIs read from an InputStream. If non-null values for the horizontal and vertical fields of view are supplied, then reading of ROI files from dispim is possible. The fields of view must be known since the coordinate system origin for dispim ROIs is at the top left of the image, while for the roi package it is in the centre of the field of view and a coordinate translation must be performed when reading in the ROIs.
      Parameters:
      s - the InputStream.
      pixelXSize - the pixel size in the horizontal direction (pixel width).
      pixelYSize - the pixel size in the vertical direction (pixel height).
      nCols - the number of image columns (number of samples in the horizontal direction).
      nRows - the number of image rows (number of samples in the vertical direction).
      Returns:
      a List of ROIs read from the InputStream.
      Throws:
      IOException - if there is an error reading the ROIs from the InputStream.

    • getROIs

      public static List<ROI> getROIs(InputStream s, Float pixelXSize, Float pixelYSize, Integer nCols, Integer nRows, MonitorWorker worker) throws IOException, CancelledException
      Returns a List of ROIs read from an InputStream. If non-null values for the horizontal and vertical fields of view are supplied, then reading of ROI files from dispim is possible. The fields of view must be known since the coordinate system origin for dispim ROIs is at the top left of the image, while for the roi package it is in the centre of the field of view and a coordinate translation must be performed when reading in the ROIs.
      Parameters:
      s - the InputStream.
      pixelXSize - the pixel size in the horizontal direction (pixel width).
      pixelYSize - the pixel size in the vertical direction (pixel height).
      nCols - the number of image columns (number of samples in the horizontal direction).
      nRows - the number of image rows (number of samples in the vertical direction).
      worker - if non-null the MonitorWorker that can be used to cancel the operation.
      Returns:
      a List<ROI> of ROIs read from the InputStream.
      Throws:
      IOException - if there is an error reading the ROIs from the InputStream.
      CancelledException - if the operation is cancelled by the user.

    • moveROIs

      public static void moveROIs(List<ROI> ROIList, double dx, double dy)
      Move a List of ROIs by specified distances (in mm) in the x and y directions.
      Parameters:
      ROIList - a List<ROI< of ROIs to move.
      dx - the distance to move in the x-direction.
      dy - the distance to move in the y-direction.

    • join

      public static List<ROI> join(List<ROI> ROIList) throws ROIException
      Joins a List of ROIs with a waisted join at the nearest point. Only IrregularROIs will be joined; all other types of ROI will be unchanged.
      Parameters:
      ROIList - a List<ROI> of ROIs to join.
      Returns:
      a List<ROI> of ROIs resulting from the join operation.
      Throws:
      ROIException - if an error occurs during the join operation.

    • getAnnotation

      public String getAnnotation()
      Gets the anotation string for this ROI.
      Returns:
      the annotation string for this ROI, or null if there is no annotation.

    • setAnnotation

      public void setAnnotation(String annotation)
      Sets the anotation string for this ROI.
      Parameters:
      annotation - the new annotation string for this ROI, or null to unset the annotation.

    • getClasses

      public static List<Class<? extends ROI>> getClasses()
      Returns an array of all known sub-classes of ROI.
      Returns:
      an array of all known sub-classes of ROI.

    • mmPosToPix

      public static double mmPosToPix(double posMM, float pixelSize, int nPixels)
      Convert from a position in mm to a pixel number coordinate. The centre of the field of view has a mm coordinate of zero. The pixel coordinate of zero is at the edge of the field of view (not the centre of the first sample).
      Parameters:
      posMM - the position in mm coordinates in this dimension of the image.
      pixelSize - the pixel size in mm in this dimension of the image.
      nPixels - the number of samples in this dimension of the image.
      Returns:
      real-space (mm) position, in pixels.

    • pixPosToMm

      public static double pixPosToMm(double pixel, int nPixels, float pixelSize)
      Convert from a pixel number to a position in mm. The centre of the field of view has a mm coordinate of zero. The pixel coordinate of zero is at the edge of the field of view (not the centre of the first sample).
      Parameters:
      pixel - the position in pixel coordinates in this dimension of the image.
      nPixels - the number of samples in this dimension of the image.
      pixelSize - the pixel size in mm in this dimension of the image.
      Returns:
      the position of the pixel, in mm.

    • getPixelValue

      public static double getPixelValue(Object pix, PixelDataType dataType, ComplexMode complexMode, int col, int row, int nCols, int nRows, int offset)
      Returns the pixel value at a particular (column,row) of an array of pixels. If the PixelDataType is a colour type, then the luminance value (= (0.299 * Red) + (0.587 * Green) + (0.114 * Blue)) is returned.
      Parameters:
      pix - the array of pixel values.
      dataType - the type of pixels.
      complexMode - the calculation mode for PixelDataType.COMPLEX images. The value returned will correspond to the mode: the real part, imaginary part, magnitude or phase.
      col - the column number of the pixel.
      row - the row number of the pixel.
      nCols - the number of columns in the array.
      nRows - the number of rows in the array.
      offset - an offset (in pixels) into the pixel value array for the starting pixel of the slice on which this ROI is defined.
      Returns:
      the pixel value at a particular (column,row) of an array of pixels as a double value.

    • getDisplayedBounds2D

      public static Rectangle2D getDisplayedBounds2D(List<ROI> ROIList)
      Returns a high-precision rectangle (in screen coordinates) that bounds all the ROIs in the ROIList.
      Parameters:
      ROIList - a List<ROI> of ROIs.
      Returns:
      a Rectangle2D that just bounds the List of ROIs.

    • getDisplayedBounds2D

      public Rectangle2D getDisplayedBounds2D()
      Returns a high-precision rectangle (in screen coordinates) that just bounds this ROI.
      Returns:
      a Rectangle2D that just bounds this ROI in screen coordinates.

    • getBoundingRectangle

      public static Rectangle2D getBoundingRectangle(List<ROI> ROIList, int nCols, int nRows, float pixelXSize, float pixelYSize)
      Returns a high-precision rectangle (in image pixel coordinates) that bounds all the ROIs in the ROIList.
      Parameters:
      ROIList - a List<ROI> of ROIs.
      nCols - the number of columns in the image on which this ROI is defined.
      nRows - the number of rows in the image on which this ROI is defined.
      pixelXSize - pixel width for the image on which this ROI is defined.
      pixelYSize - pixel height for the image on which this ROI is defined.
      Returns:
      a Rectangle2D that just bounds the List<ROI> of ROIs, in pixel coordinates.

    • getBoundingRectangle

      public Rectangle2D getBoundingRectangle(int nCols, int nRows, float pixelXSize, float pixelYSize)
      Returns a high-precision rectangle (in image pixel coordinates) that just bounds this ROI.
      Parameters:
      nCols - the number of columns in the image on which this ROI is defined.
      nRows - the number of rows in the image on which this ROI is defined.
      pixelXSize - pixel width for the image on which this ROI is defined.
      pixelYSize - pixel height for the image on which this ROI is defined.
      Returns:
      a Rectangle2D that just bounds this ROI.

    • selectDeselect

      public boolean selectDeselect(Point point, boolean editMode, boolean showDeleted, int nAlreadySelected)
      Selects or deselects an ROI after a user click at the point.
      Parameters:
      point - the Point at which the user has clicked.
      editMode - true if the tool working with ROIs is in edit mode; false if it is in view mode.
      showDeleted - true if the tool working with ROIs is set to show deleted ROIs; false if it is not.
      nAlreadySelected - the number of ROIs already selected. This determines the exact selection/deselection behaviour.
      Returns:
      true if the selection was changed.

    • draw

      public boolean draw(Graphics g, Rectangle visibleRectangle, int imageDrawCols, int imageDrawRows, int xOffset, int yOffset, int nCols, int nRows, float pixelXSize, float pixelYSize, boolean drawAnnotation)
      Draws this ROI if it needs to be be drawn on screen.
      Parameters:
      g - the graphics context for the drawing operation.
      visibleRectangle - the part of the image that can be seen on-screen.
      imageDrawCols - width of the area in which this portion of the image is to be drawn.
      imageDrawRows - height of the area in which this portion of the image is to be drawn.
      xOffset - a horizontal offset for drawing operations.
      yOffset - a vertical offset for drawing operations.
      nCols - the number of columns in the image on which this ROI is defined.
      nRows - the number of rows in the image on which this ROI is defined.
      pixelXSize - pixel width for the image on which this ROI is defined.
      pixelYSize - pixel height for the image on which this ROI is defined.
      drawAnnotation - a flag to indicate whether annotation should be drawn.
      Returns:
      true if the ROI is visible and been drawn on screen; false otherwise.

    • drawInOrthoView

      public abstract void drawInOrthoView(Image orthoView, org.jogamp.vecmath.Point3f viewPosition, org.jogamp.java3d.Transform3D imageToViewTx, int offsetX, int offsetY, int nCols, int nRows, int nSlices, float pixelXSize, float pixelYSize, boolean filled)
      Draws this ROI on top of an orthogonal view of an image.
      Parameters:
      orthoView - the Image into which the ROI is to be drawn.
      viewPosition - the coordinates (col, row, slice position) of the orthogonal view in the original image.
      imageToViewTx - the Transform3D that maps original image pixel coordinates to pixel coordinates in the orthogonal view.
      offsetX - the offset in the horizontal direction of the orthoView image, relative to the JPanel into which it will be drawn.
      offsetY - the offset in the vertical direction of the orthoView image, relative to the JPanel into which it will be drawn.
      nCols - the number of columns in the original image.
      nRows - the number of rows in the original image.
      nSlices - the number of slices in the original image.
      pixelXSize - the pixel width in the original image.
      pixelYSize - the pixel height in the original image.
      filled - whether the ROI should be drawn filled (effective only for ROIs that enclose an area).

    • getColor

      public Color getColor()
      Returns the Color in which this ROI should be drawn. The drawn colour of an ROI depends on its state.
      Returns:
      the Color with which this ROI should be drawn.

    • getUserColour

      public byte getUserColour()
      Returns the user-defined colour for this ROI.
      Returns:
      a value which is an index to the user-defined colour. A return value of 0 indicates the a user-defined colour hasn't been set; values greater than zero are the index into the user-defined colour palette.

    • setUserColour

      public void setUserColour(byte index)
      Sets the user-defined colour for this ROI.
      Parameters:
      index - a value which is an index to the user-defined colour. A value of 0 indicates the a user-defined colour is to be unset; values greater than zero are the index into the user-defined colour palette of user-settable ROI colours.

    • setTextColor

      public static void setTextColor(Color c)
      Sets the colour with which ROI annotation text should be drawn.
      Parameters:
      c - the colour with which ROI annotation text is to be drawn.

    • setTextSize

      public static void setTextSize(int size)
      Sets the font size at which ROI annotation text should be drawn.
      Parameters:
      size - the font size at which ROI annotation text is to be drawn.

    • getXMLDeclaration

      public static String getXMLDeclaration(String elementName)
      Returns the XML delaration for writing an array of ROIs to a Document.
      Parameters:
      elementName - the name of the Document Element.
      Returns:
      the XML delaration for writing an array of ROIs.

    • createXMLElement

      public static Element createXMLElement(Document doc, String elementName, ROI[] rois)
      Creates a Document Element for an array of ROIs.
      Parameters:
      doc - the Document.
      elementName - the name of the Element.
      rois - the array of ROIs.
      Returns:
      the Element containing the array of ROIs.

    • getROIs

      public static ROI[] getROIs(Element element) throws ParseException
      Returns an array of ROIs read from a document Element.
      Parameters:
      element - the document Element.
      Returns:
      an array of ROIs read from the supplied document Element.
      Throws:
      ParseException - if the ROIs cannot be read from the Element.

    • main

      public static void main(String[] args)
      Run the self-test for the ROI class.
      Parameters:
      args - ignored.