javax.media.jai
Class ROI

java.lang.Object
  |
  +--javax.media.jai.ROI

All Implemented Interfaces:

Serializable

Direct Known Subclasses:

ROIShape

public class ROI

extends Object

implements Serializable

The parent class for representations of a region of interest of an image (currently only single band images with integral data types are supported). This class represents region information in image form, and can thus be used as a fallback where a Shape representation is unavailable. Where possible, subclasses such as ROIShape are used since they provide a more compact means of storage for large regions.

The getAsShape() method may be called optimistically on any instance of ROI; however, it may return null to indicate that a Shape representation of the ROI is not available. In this case, getAsImage() should be called as a fallback.

Inclusion and exclusion of pixels is defined by a threshold value. Pixel values greater than or equal to the threshold indicate inclusion.

See Also:

Serialized Form

Constructor Summary

protected	ROI() The default constructor.
	ROI(RenderedImage im) Constructs an ROI from a RenderedImage.
	ROI(RenderedImage im, int threshold) Constructs an ROI from a RenderedImage.

Method Summary

ROI	add(ROI roi) Adds another ROI to this one and returns the result as a new ROI.
boolean	contains(double x, double y) Returns true if the ROI contain the point (x, y).
boolean	contains(double x, double y, double w, double h) Returns true if a given rectangle (x, y, w, h) is entirely included within the ROI.
boolean	contains(int x, int y) Returns true if the ROI contains the point (x, y).
boolean	contains(int x, int y, int w, int h) Returns true if a given rectangle (x, y, w, h) is entirely included within the ROI.
boolean	contains(Point p) Returns true if the ROI contains a given Point.
boolean	contains(Point2D p) Returns true if the ROI contains a given Point2D.
boolean	contains(Rectangle rect) Returns true if a given Rectangle is entirely included within the ROI.
boolean	contains(Rectangle2D rect) Returns true if a given Rectangle2D is entirely included within the ROI.
ROI	exclusiveOr(ROI roi) Exclusive-ors the ROI with another ROI and returns the result as a new ROI.
int[][]	getAsBitmask(int x, int y, int width, int height, int[][] mask) Returns a bitmask for a given rectangular region of the ROI indicating whether the pixel is included in the region of interest.
PlanarImage	getAsImage() Returns a PlanarImage representation of the ROI.
LinkedList	getAsRectangleList(int x, int y, int width, int height) Returns a LinkedList of Rectangles for a given rectangular region of the ROI.
protected LinkedList	getAsRectangleList(int x, int y, int width, int height, boolean mergeRectangles) Returns a LinkedList of Rectangles for a given rectangular region of the ROI.
Shape	getAsShape() Returns a Shape representation of the ROI, if possible.
Rectangle	getBounds() Returns the bounds of the ROI as a Rectangle.
Rectangle2D	getBounds2D() Returns the bounds of the ROI as a Rectangle2D.
int	getThreshold() Returns the inclusion/exclusion threshold value.
ROI	intersect(ROI roi) Intersects the ROI with another ROI and returns the result as a new ROI.
boolean	intersects(double x, double y, double w, double h) Returns true if a given rectangular region intersects the ROI.
boolean	intersects(int x, int y, int w, int h) Returns true if a given rectangular region intersects the ROI.
boolean	intersects(Rectangle rect) Returns true if a given Rectangle intersects the ROI.
boolean	intersects(Rectangle2D r) Returns true if a given Rectangle2D intersects the ROI.
protected static LinkedList	mergeRunLengthList(LinkedList rectList) Merge a LinkedList of Rectangles representing run lengths of pixels in the ROI into a minimal list wherein vertically abutting Rectangles are merged.
ROI	performImageOp(RenderedImageFactory RIF, ParameterBlock paramBlock, int sourceIndex, RenderingHints renderHints) Transforms an ROI using an imaging operation.
ROI	performImageOp(String name, ParameterBlock paramBlock, int sourceIndex, RenderingHints renderHints) Transforms an ROI using an imaging operation.
void	setThreshold(int threshold) Sets the inclusion/exclusion threshold value.
ROI	subtract(ROI roi) Subtracts another ROI from this one and returns the result as a new ROI.
ROI	transform(AffineTransform at) Performs an affine transformation and returns the result as a new ROI.
ROI	transform(AffineTransform at, Interpolation interp) Performs an affine transformation and returns the result as a new ROI.

Methods inherited from class java.lang.Object

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

Constructor Detail

ROI

protected ROI()

The default constructor. Using this constructor means that the subclass must override all methods that reference theImage.

ROI

public ROI(RenderedImage im)

Constructs an ROI from a RenderedImage. The inclusion threshold is taken to be halfway between the minimum and maximum sample values specified by the image's SampleModel.

Parameters:

im - A single-banded RenderedImage.

Throws:

IllegalArgumentException - if im is null.

IllegalArgumentException - if im does not have exactly one band

ROI

public ROI(RenderedImage im,
           int threshold)

Constructs an ROI from a RenderedImage. The inclusion threshold is specified explicitly.

Parameters:

im - A single-banded RenderedImage.

threshold - The desired inclusion threshold.

Throws:

IllegalArgumentException - if im is null.

IllegalArgumentException - if im does not have exactly one band

Method Detail

mergeRunLengthList

protected static LinkedList mergeRunLengthList(LinkedList rectList)

Merge a LinkedList of Rectangles representing run lengths of pixels in the ROI into a minimal list wherein vertically abutting Rectangles are merged. The operation is effected in place.

Parameters:

rectList - The list of run length Rectangles.

Returns:

The merged list.

Throws:

IllegalArgumentException - if rectList is null.

getThreshold

public int getThreshold()

Returns the inclusion/exclusion threshold value.

setThreshold

public void setThreshold(int threshold)

Sets the inclusion/exclusion threshold value.

getBounds

public Rectangle getBounds()

Returns the bounds of the ROI as a Rectangle.

getBounds2D

public Rectangle2D getBounds2D()

Returns the bounds of the ROI as a Rectangle2D.

contains

public boolean contains(Point p)

Returns true if the ROI contains a given Point.

Parameters:

p - A Point identifying the pixel to be queried.

Returns:

true if the pixel lies within the ROI.

Throws:

IllegalArgumentException - if p is null.

contains

public boolean contains(Point2D p)

Returns true if the ROI contains a given Point2D.

Parameters:

p - A Point2D identifying the pixel to be queried.

Returns:

true if the pixel lies within the ROI.

Throws:

IllegalArgumentException - if p is null.

contains

public boolean contains(int x,
                        int y)

Returns true if the ROI contains the point (x, y).

Parameters:

x - An int specifying the X coordinate of the pixel to be queried.

y - An int specifying the Y coordinate of the pixel to be queried.

Returns:

true if the pixel lies within the ROI.

contains

public boolean contains(double x,
                        double y)

Returns true if the ROI contain the point (x, y).

Parameters:

x - A double specifying the X coordinate of the pixel to be queried.

y - A double specifying the Y coordinate of the pixel to be queried.

Returns:

true if the pixel lies within the ROI.

contains

public boolean contains(Rectangle rect)

Returns true if a given Rectangle is entirely included within the ROI.

Parameters:

rect - A Rectangle specifying the region to be tested for inclusion.

Returns:

true if the rectangle is entirely contained within the ROI.

Throws:

IllegalArgumentException - if rect is null.

contains

public boolean contains(Rectangle2D rect)

Returns true if a given Rectangle2D is entirely included within the ROI.

Parameters:

rect - A Rectangle2D specifying the region to be tested for inclusion.

Returns:

true if the rectangle is entirely contained within the ROI.

Throws:

IllegalArgumentException - if rect is null.

contains

public boolean contains(int x,
                        int y,
                        int w,
                        int h)

Returns true if a given rectangle (x, y, w, h) is entirely included within the ROI.

Parameters:

x - The int X coordinate of the upper left corner of the region.

y - The int Y coordinate of the upper left corner of the region.

w - The int width of the region.

h - The int height of the region.

Returns:

true if the rectangle is entirely contained within the ROI.

contains

public boolean contains(double x,
                        double y,
                        double w,
                        double h)

Returns true if a given rectangle (x, y, w, h) is entirely included within the ROI.

Parameters:

x - The double X coordinate of the upper left corner of the region.

y - The double Y coordinate of the upper left corner of the region.

w - The double width of the region.

h - The double height of the region.

Returns:

true if the rectangle is entirely contained within the ROI.

intersects

public boolean intersects(Rectangle rect)

Returns true if a given Rectangle intersects the ROI.

Parameters:

rect - A Rectangle specifying the region to be tested for inclusion.

Returns:

true if the rectangle intersects the ROI.

Throws:

IllegalArgumentException - if rect is null.

intersects

public boolean intersects(Rectangle2D r)

Returns true if a given Rectangle2D intersects the ROI.

Parameters:

r - A Rectangle2D specifying the region to be tested for inclusion.

Returns:

true if the rectangle intersects the ROI.

Throws:

IllegalArgumentException - if r is null.

intersects

public boolean intersects(int x,
                          int y,
                          int w,
                          int h)

Returns true if a given rectangular region intersects the ROI.

Parameters:

x - The int X coordinate of the upper left corner of the region.

y - The int Y coordinate of the upper left corner of the region.

w - The int width of the region.

h - The int height of the region.

Returns:

true if the rectangle intersects the ROI.

intersects

public boolean intersects(double x,
                          double y,
                          double w,
                          double h)

Returns true if a given rectangular region intersects the ROI.

Parameters:

x - The double X coordinate of the upper left corner of the region.

y - The double Y coordinate of the upper left corner of the region.

w - The double width of the region.

h - The double height of the region.

Returns:

true if the rectangle intersects the ROI.

add

public ROI add(ROI roi)

Adds another ROI to this one and returns the result as a new ROI. The supplied ROI will be converted to a rendered form if necessary. The bounds of the resultant ROI will be the union of the bounds of the two ROIs being merged.

Parameters:

roi - An ROI.

Returns:

A new ROI containing the new ROI data.

Throws:

IllegalArgumentException - if roi is null.

subtract

public ROI subtract(ROI roi)

Subtracts another ROI from this one and returns the result as a new ROI. The supplied ROI will be converted to a rendered form if necessary. The bounds of the resultant ROI will be the same as this ROI.

Parameters:

roi - An ROI.

Returns:

A new ROI containing the new ROI data.

Throws:

IllegalArgumentException - if roi is null.

intersect

public ROI intersect(ROI roi)

Intersects the ROI with another ROI and returns the result as a new ROI. The supplied ROI will be converted to a rendered form if necessary. The bounds of the resultant ROI will be the intersection of the bounds of the two ROIs being merged.

Parameters:

roi - An ROI.

Returns:

A new ROI containing the new ROI data.

Throws:

IllegalArgumentException - if roi is null.

exclusiveOr

public ROI exclusiveOr(ROI roi)

Exclusive-ors the ROI with another ROI and returns the result as a new ROI. The supplied ROI will be converted to a rendered form if necessary. The bounds of the resultant ROI will be the union of the bounds of the two ROIs being merged.

Parameters:

roi - An ROI.

Returns:

A new ROI containing the new ROI data.

Throws:

IllegalArgumentException - if roi is null.

transform

public ROI transform(AffineTransform at,
                     Interpolation interp)

Performs an affine transformation and returns the result as a new ROI. The transformation is performed by an "Affine" RIF using the indicated interpolation method.

Parameters:

at - an AffineTransform specifying the transformation.

interp - the Interpolation to be used.

Returns:

a new ROI containing the transformed ROI data.

Throws:

IllegalArgumentException - if at is null.

IllegalArgumentException - if interp is null.

transform

public ROI transform(AffineTransform at)

Performs an affine transformation and returns the result as a new ROI. The transformation is performed by an "Affine" RIF using nearest neighbor interpolation.

Parameters:

at - an AffineTransform specifying the transformation.

Returns:

a new ROI containing the transformed ROI data.

Throws:

IllegalArgumentException - if at is null.

performImageOp

public ROI performImageOp(RenderedImageFactory RIF,
                          ParameterBlock paramBlock,
                          int sourceIndex,
                          RenderingHints renderHints)

Transforms an ROI using an imaging operation. The operation is specified by a RenderedImageFactory. The operation's ParameterBlock, minus the image source itself is supplied, along with an index indicating where to insert the ROI image. The renderHints argument allows rendering hints to be passed in.

Parameters:

RIF - A RenderedImageFactory that will be used to create the op.

paramBlock - A ParameterBlock containing all sources and parameters for the op except for the ROI itself.

sourceIndex - The index of the ParameterBlock's sources where the ROI is to be inserted.

renderHints - A RenderingHints object containing rendering hints, or null.

Throws:

IllegalArgumentException - if RIF is null.

IllegalArgumentException - if paramBlock is null.

performImageOp

public ROI performImageOp(String name,
                          ParameterBlock paramBlock,
                          int sourceIndex,
                          RenderingHints renderHints)

Transforms an ROI using an imaging operation. The operation is specified by name; the default JAI registry is used to resolve this into a RIF. The operation's ParameterBlock, minus the image source itself is supplied, along with an index indicating where to insert the ROI image. The renderHints argument allows rendering hints to be passed in.

Parameters:

name - The name of the operation to perform.

paramBlock - A ParameterBlock containing all sources and parameters for the op except for the ROI itself.

sourceIndex - The index of the ParameterBlock's sources where the ROI is to be inserted.

renderHints - A RenderingHints object containing rendering hints, or null.

Throws:

IllegalArgumentException - if name is null.

IllegalArgumentException - if paramBlock is null.

getAsShape

public Shape getAsShape()

Returns a Shape representation of the ROI, if possible. If none is available, null is returned. A proper instance of ROI (one that is not an instance of any subclass of ROI) will always return null.

Returns:

The ROI as a Shape.

getAsImage

public PlanarImage getAsImage()

Returns a PlanarImage representation of the ROI. This method will always succeed. This method returns a (bilevel) image whose SampleModel is an instance of MultiPixelPackedSampleModel.

Returns:

The ROI as a PlanarImage.

getAsBitmask

public int[][] getAsBitmask(int x,
                            int y,
                            int width,
                            int height,
                            int[][] mask)

Returns a bitmask for a given rectangular region of the ROI indicating whether the pixel is included in the region of interest. The results are packed into 32-bit integers, with the MSB considered to lie on the left. The last entry in each row of the result may have bits that lie outside of the requested rectangle. These bits are guaranteed to be zeroed.

The mask array, if supplied, must be of length equal to or greater than height and each of its subarrays must have length equal to or greater than (width + 31)/32. If null is passed in, a suitable array will be constructed. If the mask is non-null but has insufficient size, an exception will be thrown.

Parameters:

x - The X coordinate of the upper left corner of the rectangle.

y - The Y coordinate of the upper left corner of the rectangle.

width - The width of the rectangle.

height - The height of the rectangle.

mask - A two-dimensional array of ints at least (width + 31)/32 entries wide and (height) entries tall, or null.

Returns:

A reference to the mask parameter, or to a newly constructed array if mask is null. If the specified rectangle does intersect with the image bounds then a null is returned.

getAsRectangleList

public LinkedList getAsRectangleList(int x,
                                     int y,
                                     int width,
                                     int height)

Returns a LinkedList of Rectangles for a given rectangular region of the ROI. The Rectangles in the list are merged into a minimal set.

Parameters:

x - The X coordinate of the upper left corner of the rectangle.

y - The Y coordinate of the upper left corner of the rectangle.

width - The width of the rectangle.

height - The height of the rectangle.

Returns:

A LinkedList of Rectangles. If the specified rectangle does intersect with the image bounds then a null is returned.

getAsRectangleList

protected LinkedList getAsRectangleList(int x,
                                        int y,
                                        int width,
                                        int height,
                                        boolean mergeRectangles)

Returns a LinkedList of Rectangles for a given rectangular region of the ROI.

Parameters:

x - The X coordinate of the upper left corner of the rectangle.

y - The Y coordinate of the upper left corner of the rectangle.

width - The width of the rectangle.

height - The height of the rectangle.

mergeRectangles - true if the Rectangles are to be merged into a minimal set.

Returns:

A LinkedList of Rectangles. If the specified rectangle does intersect with the image bounds then a null is returned.