Module ij
Package ij.gui

# Class ShapeRoi

java.lang.Object
ij.gui.Roi
ij.gui.ShapeRoi

All Implemented Interfaces:
  `Serializable`, `Cloneable`, `Iterable<Point>`

public class ShapeRoi extends Roi
A subclass of `ij.gui.Roi` (2D Regions Of Interest) implemented in terms of java.awt.Shape. A ShapeRoi is constructed from a `ij.gui.Roi` object, or as a result of logical operators (i.e., union, intersection, exclusive or, and subtraction) provided by this class. These operators use the package `java.awt.geom` as a backend.
This code is in the public domain.

Author:
  Cezar M.Tigaret invalid input: '<'c.tigaret@ucl.ac.uk>
See Also:
  - Serialized Form

## Field Summary

### Fields inherited from class ij.gui.Roi

`ANGLE, asp_bk, aspect, cachedMask, center, clipboard, clipHeight, clipWidth, clipX, clipY, COMPOSITE, constrain, CONSTRUCTING, defaultColor, defaultFillColor, FERET_ARRAY_POINTOFFSET, FERET_ARRAYSIZE, fillColor, flattenScale, FREELINE, FREEROI, HANDLE_SIZE, handleColor, ic, ignoreClipRect, imp, instanceColor, LINE, lineWidth, mag, MOVING, MOVING_HANDLE, nonScalable, NORMAL, NOT_PASTING, oldHeight, oldWidth, oldX, oldY, onePixelWide, OVAL, overlay, pasteMode, POINT, POLYGON, POLYLINE, previousRoi, RECTANGLE, RESIZING, ROIColor, stroke, strokeColor, TRACED_ROI, type, updateFullWindow, wideLine, xMax, yMax`

## Constructor Summary

Constructors
Constructor
Description
`ShapeRoi(float[] shapeArray)`
Constructs a ShapeRoi from an array of variable length path segments.
`ShapeRoi(int x, int y, Shape s)`
Constructs a ShapeRoi from a Shape.
`ShapeRoi(Roi r)`
Constructs a ShapeRoi from an Roi.
`ShapeRoi(Shape s)`
Constructs a ShapeRoi from a Shape.

## Method Summary

Modifier and Type
Method
Description
`ShapeRoi`
`and(ShapeRoi sr)`
Unary intersection operator.
`Object`
`clone()`
Returns a deep copy of this.
`boolean`
`contains(int x, int y)`
Checks whether the center of the specified pixel inside of this ROI's shape boundaries.
`boolean`
`containsPoint(double x, double y)`
Returns whether coordinate (x,y) is contained in the Roi.
`void`
`draw(Graphics g)`
Non-destructively draws the shape of this object on the associated ImagePlus.
`void`
`drawPixels(ImageProcessor ip)`
Draws the shape of this object onto the specified ImageProcessor.
`void`
`drawRoiBrush(Graphics g)`
`FloatPolygon`
`getFloatConvexHull()`
Returns the convex hull of this Roi as a FloatPolygon.
`FloatPolygon`
`getFloatPolygon()`
Returns all vertex points of the shape as approximated by polygons, in image pixel coordinates
`FloatPolygon`
`getFloatPolygon(double flatness, boolean separateSubpaths, boolean addPointForClose, boolean absoluteCoord)`
Returns a FloatPolygon with all vertices of the flattened shape, i.e., the shape approximated by straight line segments.
`FloatPolygon`
`getFloatPolygon(Shape shape, double flatness, boolean separateSubpaths, boolean addPointForClose, boolean absoluteCoord)`
`FloatPolygon`
`getFloatPolygon(String options)`
Returns all vertex points of the shape as approximated by polygons, where options may include "close" to add points to close each subpath, and "separate" to insert NaN values between subpaths (= individual polygons)
`double`
`getLength()`
Returns the perimeter of this ShapeRoi.
`ImageProcessor`
`getMask()`
Returns this ROI's mask pixels as a ByteProcessor with pixels "in" the mask set to white (255) and pixels "outside" the mask set to black (0).
`Polygon`
`getPolygon()`
Returns the outline of this selection as a Polygon.
`Roi[]`
`getRois()`
Converts a Shape into Roi object(s).
`FloatPolygon`
`getSelectionCoordinates()`
Used by the getSelectionCoordinates macro function
`Shape`
`getShape()`
Returns a reference to the Shape object encapsulated by this ShapeRoi.
`float[]`
`getShapeAsArray()`
Retrieves the end points and control points of the path as a float array.
`int`
`isHandle(int sx, int sy)`
Always returns -1 since ShapeRois do not have handles.
`ShapeRoi`
`not(ShapeRoi sr)`
Unary subtraction operator.
`ShapeRoi`
`or(ShapeRoi sr)`
Unary union operator.
`Roi`
`shapeToRoi()`
Attempts to convert this ShapeRoi into a single non-composite Roi.
`int`
`size()`
Retuns the number of vertices, of this shape as approximated by straight lines.
`Roi`
`trySimplify()`
Attempts to convert this ShapeRoi into a single non-composite Roi.
`ShapeRoi`
`xor(ShapeRoi sr)`
Unary exclusive or operator.

### Methods inherited from class ij.gui.Roi

`abortModification, abortPaste, addRoiListener, clipRectMargin, convertLineToArea, convertToPolygon, copyAttributes, create, create, drawOverlay, drawPixels, enableSubPixelResolution, endPaste, equals, getAngle, getAngle, getAntiAlias, getBoundingRect, getBounds, getColor, getContainedFloatPoints, getContainedPoints, getContourCentroid, getConvexHull, getCornerDiameter, getCPosition, getCurrentPasteMode, getDebugInfo, getDefaultFillColor, getDefaultGroup, getDefaultHandleSize, getDefaultStrokeWidth, getDrawOffset, getFeretsDiameter, getFeretValues, getFillColor, getFloatAngle, getFloatBounds, getFloatHeight, getFloatWidth, getGroup, getGroupName, getGroupNames, getHandleSize, getHashCode, getImage, getImageID, getInterpolatedPolygon, getInterpolatedPolygon, getInterpolatedPolygon, getInverse, getListeners, getMagnification, getName, getPasteMode, getPosition, getPreviousRoi, getProperties, getProperty, getPropertyCount, getPrototypeOverlay, getRotationCenter, getRoundRectArcSize, getScaledStroke, getScaleStrokeWidth, getState, getStatistics, getStroke, getStrokeColor, getStrokeWidth, getTPosition, getType, getTypeAsString, getXBase, getYBase, getZPosition, grow, handleMouseDown, handleMouseDrag, handleMouseUp, hasHyperStackPosition, isActiveOverlayRoi, isArea, isCursor, isDrawingTool, isInteger, isLine, isLineOrPoint, isVisible, iterator, lineCircleIntersection, magnificationForSubPixel, magnificationForSubPixel, mouseDownInHandle, mouseDragged, mouseMoved, mouseReleased, moveHandle, notifyListeners, nudge, nudgeCorner, offScreenX, offScreenXD, offScreenY, offScreenYD, removeRoiListener, resetDefaultHandleSize, saveGroupNames, screenX, screenXD, screenY, screenYD, setAntiAlias, setBounds, setColor, setCornerDiameter, setDefaultColor, setDefaultFillColor, setDefaultGroup, setDefaultStrokeWidth, setDrawOffset, setFillColor, setFlattenScale, setGroup, setGroupName, setGroupNames, setHandleSize, setIgnoreClipRect, setImage, setInstanceColor, setIsCursor, setLineWidth, setLocation, setLocation, setName, setNonScalable, setPasteMode, setPosition, setPosition, setPosition, setPreviousRoi, setProperties, setProperty, setPrototypeOverlay, setRenderingHint, setRotationCenter, setRoundRectArcSize, setStroke, setStrokeColor, setStrokeWidth, setStrokeWidth, setUnscalableStrokeWidth, showStatus, startPaste, subPixelResolution, temporarilyHide, toFloat, toInt, toInt, toIntR, toString, translate, update, updateClipRect, updateWideLine, useLineSubpixelConvention, xor`

### Methods inherited from class java.lang.Object

`finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

### Methods inherited from interface java.lang.Iterable

`forEach, spliterator`

## Constructor Details

### ShapeRoi

public ShapeRoi(Roi r)
Constructs a ShapeRoi from an Roi.

### ShapeRoi

public ShapeRoi(Shape s)
Constructs a ShapeRoi from a Shape.

### ShapeRoi

public ShapeRoi(int x, int y, Shape s)
Constructs a ShapeRoi from a Shape.

### ShapeRoi

public ShapeRoi(float[] shapeArray)
Constructs a ShapeRoi from an array of variable length path segments. Each segment consists of the segment type followed by 0-6 coordintes (0-3 end points and control points). Depending on the type, a segment uses from 1 to 7 elements of the array.

## Method Details

### clone

public Object clone()
Returns a deep copy of this.

Overrides:
  `clone` in class `Roi`

### or

public ShapeRoi or(ShapeRoi sr)
Unary union operator. The caller is set to its union with the argument.

Returns:
  the union of `this` and `sr`

### and

public ShapeRoi and(ShapeRoi sr)
Unary intersection operator. The caller is set to its intersection with the argument (i.e., the overlapping regions between the operands).

Returns:
  the overlapping regions between `this` and `sr`

### xor

public ShapeRoi xor(ShapeRoi sr)
Unary exclusive or operator. The caller is set to the non-overlapping regions between the operands.

Returns:
  the union of the non-overlapping regions of `this` and `sr`
See Also:
  - `Roi.xor(Roi[])`
  - `Overlay.xor(int[])`

### not

public ShapeRoi not(ShapeRoi sr)
Unary subtraction operator. The caller is set to the result of the operation between the operands.

Returns:
  `this` subtracted from `sr`

### getRois

public Roi[] getRois()
Converts a Shape into Roi object(s).
This method parses the shape into (possibly more than one) Roi objects and returns them in an array.
A simple, "regular" path results in a single Roi following these simple rules:

Shape type | Roi class | Roi type
--- | --- | ---
java.awt.geom.Rectangle2D.Double | ij.gui.Roi | Roi.RECTANGLE
java.awt.geom.Ellipse2D.Double | ij.gui.OvalRoi | Roi.OVAL
java.awt.geom.Line2D.Double | ij.gui.Line | Roi.LINE
java.awt.Polygon | ij.gui.PolygonRoi | Roi.POLYGON

Each subpath of a `java.awt.geom.GeneralPath` is converted following these rules:

Segment types | Number of segments | Closed path | Value of forceAngle | Value of forceTrace | Roi type
--- | --- | --- | --- | --- | ---
lines only: | 0 |  |  |  | ShapeRoi.NO_TYPE
| 1 |  |  |  | ShapeRoi.NO_TYPE
| 2 | Y |  |  | ShapeRoi.NO_TYPE
|  | N |  |  | Roi.LINE
| 3 | Y | N |  | Roi.POLYGON
|  | N | Y |  | Roi.ANGLE
|  | N | N |  | Roi.POLYLINE
| 4 | Y | invalid input: '<'/td |  | Roi.RECTANGLE
|  | N |  |  | Roi.POLYLINE
| <= MAXPOLY | Y |  |  | Roi.POLYGON
|  | N |  |  | Roi.POLYLINE
| > MAXPOLY | Y |  | Y | Roi.TRACED_ROI
|  |  |  | N | Roi.FREEROI
|  | N |  |  | Roi.FREELINE
anything else: | <= 2 |  |  |  | ShapeRoi.NO_TYPE
| > 2 |  |  |  | ShapeRoi.SHAPE_ROI

Returns:
  an array of ij.gui.Roi objects.

### shapeToRoi

public Roi shapeToRoi()
Attempts to convert this ShapeRoi into a single non-composite Roi.

Returns:
  an ij.gui.Roi object or null if it cannot be simplified to become a non-composite roi.

### trySimplify

public Roi trySimplify()
Attempts to convert this ShapeRoi into a single non-composite Roi. For showing as a Roi, one should apply copyAttributes

Returns:
  an ij.gui.Roi object, which is either the non-composite roi, or this ShapeRoi (if such a conversion is not possible) or null if this is an empty roi.

### contains

public boolean contains(int x, int y)
Checks whether the center of the specified pixel inside of this ROI's shape boundaries. Note the ImageJ convention of 0.5 pixel shift between outline and pixel center, i.e., pixel (0,0) is enclosed by the rectangle spanned between (0,0) and (1,1). The value slightly below 0.5 is for rounding according to the ImageJ convention (which is opposite to that of the java.awt.Shape class): In ImageJ, points exactly at the left (right) border are considered outside (inside); points exactly on horizontal borders, are considered outside (inside) at the border with the lower (higher) y.

Overrides:
  `contains` in class `Roi`

### containsPoint

public boolean containsPoint(double x, double y)
Returns whether coordinate (x,y) is contained in the Roi. Note that the coordinate (0,0) is the top-left corner of pixel (0,0). Use contains(int, int) to determine whether a given pixel is contained in the Roi.

Overrides:
  `containsPoint` in class `Roi`

### getLength

public double getLength()
Returns the perimeter of this ShapeRoi.

Overrides:
  `getLength` in class `Roi`

### getShapeAsArray

public float[] getShapeAsArray()
Retrieves the end points and control points of the path as a float array. The array contains a sequence of variable length segments that use from from one to seven array elements. The first element of a segment is the type as defined in the PathIterator interface. SEG_MOVETO and SEG_LINETO segments also include two coordinates (one end point), SEG_QUADTO segments include four coordinates and SEG_CUBICTO segments include six coordinates (three points). Coordinates are with respect to the image bounds, not the Roi bounds.

### draw

public void draw(Graphics g)
Non-destructively draws the shape of this object on the associated ImagePlus.

Overrides:
  `draw` in class `Roi`

### drawRoiBrush

public void drawRoiBrush(Graphics g)

### drawPixels

public void drawPixels(ImageProcessor ip)
Draws the shape of this object onto the specified ImageProcessor.
This method will always draw a flattened version of the actual shape (i.e., all curve segments will be approximated by line segments).

Overrides:
  `drawPixels` in class `Roi`
See Also:
  - `ImageProcessor.setColor(java.awt.Color)`
  - `ImageProcessor.setLineWidth(int)`

### getMask

public ImageProcessor getMask()
Returns this ROI's mask pixels as a ByteProcessor with pixels "in" the mask set to white (255) and pixels "outside" the mask set to black (0). Takes into account the usual ImageJ convention of 0.5 pxl shift between the outline and pixel coordinates; e.g., pixel (0,0) is surrounded by the rectangle spanned between (0,0) and (1,1). Note that apart from the 0.5 pixel shift, ImageJ has different convention for the border points than the java.awt.Shape class: In ImageJ, points exactly at the left (right) border are considered outside (inside); points exactly on horizontal borders, are considered outside (inside) at the border with the lower (higher) y.

Overrides:
  `getMask` in class `Roi`

### getShape

public Shape getShape()
Returns a reference to the Shape object encapsulated by this ShapeRoi.

### isHandle

public int isHandle(int sx, int sy)
Always returns -1 since ShapeRois do not have handles.

Overrides:
  `isHandle` in class `Roi`

### getSelectionCoordinates

public FloatPolygon getSelectionCoordinates()
Used by the getSelectionCoordinates macro function

### getFloatPolygon

public FloatPolygon getFloatPolygon(double flatness, boolean separateSubpaths, boolean addPointForClose, boolean absoluteCoord)
Returns a FloatPolygon with all vertices of the flattened shape, i.e., the shape approximated by straight line segments. This method is for listing the coordinates and creating the convex hull.

Parameters:
  `flatness` - Roughly the maximum allowable distance between the shape and the approximate polygon
  `separateSubpaths` - whether individual subpaths should be separated by NaN coordinates
  `addPointForClose` - whether the starting point of a closed subpath should be repeated at its end. Note that with `addPointForClose = false`, there is no distinction between open and closed subpaths.
  `absoluteCoord` - specifies whether the coordinates should be with respect to image bounds, not Roi bounds.

### getFloatPolygon

public FloatPolygon getFloatPolygon(Shape shape, double flatness, boolean separateSubpaths, boolean addPointForClose, boolean absoluteCoord)

### getFloatConvexHull

public FloatPolygon getFloatConvexHull()
Description copied from class: `Roi`
Returns the convex hull of this Roi as a FloatPolygon. Coordinates of the convex hull are image pixel coordinates.

Overrides:
  `getFloatConvexHull` in class `Roi`

### getPolygon

public Polygon getPolygon()
Description copied from class: `Roi`
Returns the outline of this selection as a Polygon.

Overrides:
  `getPolygon` in class `Roi`
See Also:
  - `ImageProcessor.setRoi(java.awt.Rectangle)`
  - `ImageProcessor.drawPolygon(java.awt.Polygon)`
  - `ImageProcessor.fillPolygon(java.awt.Polygon)`

### getFloatPolygon

public FloatPolygon getFloatPolygon()
Returns all vertex points of the shape as approximated by polygons, in image pixel coordinates

Overrides:
  `getFloatPolygon` in class `Roi`

### getFloatPolygon

public FloatPolygon getFloatPolygon(String options)
Returns all vertex points of the shape as approximated by polygons, where options may include "close" to add points to close each subpath, and "separate" to insert NaN values between subpaths (= individual polygons)

Overrides:
  `getFloatPolygon` in class `Roi`

### size

public int size()
Retuns the number of vertices, of this shape as approximated by straight lines. Note that points might be counted twice where the shape gets closed.

Overrides:
  `size` in class `Roi`