Top Description Fields Constructors Methods
org.apache.commons.math3.geometry.partitioning

public abstract Class AbstractRegion<S extends Space, T extends Space>

extends Object
implements Region<S extends Space>
Class Inheritance
All Implemented Interfaces
org.apache.commons.math3.geometry.partitioning.Region
Known Direct Subclasses
org.apache.commons.math3.geometry.spherical.oned.ArcsSet, org.apache.commons.math3.geometry.spherical.twod.SphericalPolygonsSet, org.apache.commons.math3.geometry.euclidean.oned.IntervalsSet, org.apache.commons.math3.geometry.euclidean.threed.PolyhedronsSet, org.apache.commons.math3.geometry.euclidean.twod.PolygonsSet
Type Parameters
<S>
Type of the space.
<T>
Type of the sub-space.
Imports
java.util.ArrayList, .Collection, .Comparator, .HashMap, .Iterator, .Map, .TreeSet, org.apache.commons.math3.geometry.Point, .Space, .Vector

Abstract class for all regions, independently of geometry type or dimension.
Since
3.0

Field Summary

Modifier and TypeField and Description
private Point<S>
barycenter

Barycenter.

private double
size

Size of the instance.

private final double
tolerance

Tolerance below which points are considered to belong to hyperplanes.

private BSPTree<S>
tree

Inside/Outside BSP tree.

Constructor Summary

AccessConstructor and Description
protected
AbstractRegion(final double
tolerance below which points are considered identical.
tolerance
)

Build a region representing the whole space.

protected
AbstractRegion(final BSPTree<S>
inside/outside BSP tree representing the region
tree
,
final double
tolerance below which points are considered identical.
tolerance
)

Build a region from an inside/outside BSP tree.

protected
AbstractRegion(final Collection<SubHyperplane<S>>
collection of boundary elements, as a collection of SubHyperplane objects
boundary
,
final double
tolerance below which points are considered identical.
tolerance
)

Build a Region from a Boundary REPresentation (B-rep).

public
AbstractRegion(final Hyperplane<S>[]
array of bounding hyperplanes (if null, an empty region will be built)
hyperplanes
,
final double
tolerance below which points are considered identical.
tolerance
)

Build a convex region from an array of bounding hyperplanes.

Method Summary

Modifier and TypeMethod and Description
public AbstractRegion<S, T>

Returns:

a new region, resulting from the application of the transform to the instance
applyTransform
(final Transform<S, T>
transform to apply
transform
)

Transform a region.

public abstract AbstractRegion<S, T>
buildNew(BSPTree<S>
inside/outside BSP tree representing the new region
newTree
)

Redeclares org.apache.commons.math3.geometry.partitioning.Region.buildNew.

Build a region using the instance as a prototype.

public Region.Location

Returns:

a code representing the point status: either Region.Location#INSIDE, Region.Location#OUTSIDE or Region.Location#BOUNDARY
checkPoint
(final Vector<S>
point to check
point
)

Check a point with respect to the region.

public Region.Location
checkPoint(final Point<S>
point to check
point
)

Implements org.apache.commons.math3.geometry.partitioning.Region.checkPoint.

Check a point with respect to the region.

protected Region.Location

Returns:

a code representing the point status: either INSIDE, OUTSIDE or BOUNDARY
checkPoint
(final BSPTree<S>
root node of the region
node
,
final Vector<S>
point to check
point
)

Check a point with respect to the region starting at a given node.

protected Region.Location

Returns:

a code representing the point status: either INSIDE, OUTSIDE or BOUNDARY
checkPoint
(final BSPTree<S>
root node of the region
node
,
final Point<S>
point to check
point
)

Check a point with respect to the region starting at a given node.

protected abstract void
computeGeometricalProperties()

Compute some geometrical properties.

public boolean
contains(final Region<S>
region to check against the instance
region
)

Implements org.apache.commons.math3.geometry.partitioning.Region.contains.

Check if the instance entirely contains another region.

public AbstractRegion<S, T>
public Point<S>
public double
public double
public double

Returns:

tolerance below which points are considered to belong to hyperplanes
getTolerance
()

Get the tolerance below which points are considered to belong to hyperplanes.

public BSPTree<S>
getTree(final boolean
if true, the boundary attributes at internal nodes are guaranteed to be included (they may be included even if the argument is false, if they have already been computed due to a previous call)
includeBoundaryAttributes
)

Implements org.apache.commons.math3.geometry.partitioning.Region.getTree.

Get the underlying BSP tree.

private void
insertCuts(final BSPTree<S>
current tree node (it is a leaf node at the beginning of the call)
node
,
final Collection<SubHyperplane<S>>
collection of edges belonging to the cell defined by the node
boundary
)

Recursively build a tree by inserting cut sub-hyperplanes.

public SubHyperplane<S>
intersection(final SubHyperplane<S>
sub-hyperplane traversing the region
sub
)

Implements org.apache.commons.math3.geometry.partitioning.Region.intersection.

Get the parts of a sub-hyperplane that are contained in the region.

public boolean
isEmpty()

Implements org.apache.commons.math3.geometry.partitioning.Region.isEmpty.

Check if the instance is empty.

public boolean
isEmpty(final BSPTree<S>
root node of the sub-tree (must have Region tree semantics, i.e. the leaf nodes must have Boolean attributes representing an inside/outside property)
node
)

Implements org.apache.commons.math3.geometry.partitioning.Region.isEmpty.

Check if the sub-tree starting at a given node is empty.

public boolean
isFull()

Implements org.apache.commons.math3.geometry.partitioning.Region.isFull.

Check if the instance covers the full space.

public boolean
isFull(final BSPTree<S>
root node of the sub-tree (must have Region tree semantics, i.e. the leaf nodes must have Boolean attributes representing an inside/outside property)
node
)

Implements org.apache.commons.math3.geometry.partitioning.Region.isFull.

Check if the sub-tree starting at a given node covers the full space.

public BoundaryProjection<S>
projectToBoundary(final Point<S>
point to check
point
)

Implements org.apache.commons.math3.geometry.partitioning.Region.projectToBoundary.

Project a point on the boundary of the region.

private SubHyperplane<S>

Returns:

filtered sub-hyperplane
recurseIntersection
(final BSPTree<S>
current BSP tree node
node
,
final SubHyperplane<S>
sub-hyperplane traversing the region
sub
)

Recursively compute the parts of a sub-hyperplane that are contained in the region.

private BSPTree<S>

Returns:

a new tree
recurseTransform
(final BSPTree<S>
current BSP tree node
node
,
final Transform<S, T>
transform to apply
transform
,
final Map<BSPTree<S>, BSPTree<S>>
transformed nodes map
map
)

Recursively transform an inside/outside BSP-tree.

protected void
setBarycenter(final Vector<S>
barycenter of the instance
barycenter
)

Set the barycenter of the instance.

protected void
setBarycenter(final Point<S>
barycenter of the instance
barycenter
)

Set the barycenter of the instance.

protected void
setSize(final double
size of the instance
size
)

Set the size of the instance.

public Side
side(final Hyperplane<S>
reference hyperplane
hyperplane
)

Implements org.apache.commons.math3.geometry.partitioning.Region.side.

Deprecated

Compute the relative position of the instance with respect to an hyperplane.

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

barycenterback to summary
private Point<S> barycenter

Barycenter.

sizeback to summary
private double size

Size of the instance.

toleranceback to summary
private final double tolerance

Tolerance below which points are considered to belong to hyperplanes.

treeback to summary
private BSPTree<S> tree

Inside/Outside BSP tree.

Constructor Detail

AbstractRegionback to summary
protected AbstractRegion(final double tolerance)

Build a region representing the whole space.

Parameters
tolerance:double

tolerance below which points are considered identical.

AbstractRegionback to summary
protected AbstractRegion(final BSPTree<S> tree, final double tolerance)

Build a region from an inside/outside BSP tree.

The leaf nodes of the BSP tree must have a Boolean attribute representing the inside status of the corresponding cell (true for inside cells, false for outside cells). In order to avoid building too many small objects, it is recommended to use the predefined constants Boolean.TRUE and Boolean.FALSE. The tree also must have either null internal nodes or internal nodes representing the boundary as specified in the getTree method).

Parameters
tree:BSPTree<S>

inside/outside BSP tree representing the region

tolerance:double

tolerance below which points are considered identical.

AbstractRegionback to summary
protected AbstractRegion(final Collection<SubHyperplane<S>> boundary, final double tolerance)

Build a Region from a Boundary REPresentation (B-rep).

The boundary is provided as a collection of sub-hyperplanes. Each sub-hyperplane has the interior part of the region on its minus side and the exterior on its plus side.

The boundary elements can be in any order, and can form several non-connected sets (like for example polygons with holes or a set of disjoints polyhedrons considered as a whole). In fact, the elements do not even need to be connected together (their topological connections are not used here). However, if the boundary does not really separate an inside open from an outside open (open having here its topological meaning), then subsequent calls to the checkPoint method will not be meaningful anymore.

If the boundary is empty, the region will represent the whole space.

Parameters
boundary:Collection<SubHyperplane<S>>

collection of boundary elements, as a collection of SubHyperplane objects

tolerance:double

tolerance below which points are considered identical.

AbstractRegionback to summary
public AbstractRegion(final Hyperplane<S>[] hyperplanes, final double tolerance)

Build a convex region from an array of bounding hyperplanes.

Parameters
hyperplanes:Hyperplane<S>[]

array of bounding hyperplanes (if null, an empty region will be built)

tolerance:double

tolerance below which points are considered identical.

Method Detail

applyTransformback to summary
public AbstractRegion<S, T> applyTransform(final Transform<S, T> transform)

Transform a region.

Applying a transform to a region consist in applying the transform to all the hyperplanes of the underlying BSP tree and of the boundary (and also to the sub-hyperplanes embedded in these hyperplanes) and to the barycenter. The instance is not modified, a new instance is built.

Parameters
transform:Transform<S, T>

transform to apply

Returns:AbstractRegion<S, T>

a new region, resulting from the application of the transform to the instance

buildNewback to summary
public abstract AbstractRegion<S, T> buildNew(BSPTree<S> newTree)

Redeclares org.apache.commons.math3.geometry.partitioning.Region.buildNew.

Doc from org.apache.commons.math3.geometry.partitioning.Region.buildNew.

Build a region using the instance as a prototype.

This method allow to create new instances without knowing exactly the type of the region. It is an application of the prototype design pattern.

The leaf nodes of the BSP tree must have a Boolean attribute representing the inside status of the corresponding cell (true for inside cells, false for outside cells). In order to avoid building too many small objects, it is recommended to use the predefined constants Boolean.TRUE and Boolean.FALSE. The tree also must have either null internal nodes or internal nodes representing the boundary as specified in the getTree method).

Parameters
newTree:BSPTree<S>

inside/outside BSP tree representing the new region

Returns:AbstractRegion<S, T>

the built region

checkPointback to summary
public Region.Location checkPoint(final Vector<S> point)

Check a point with respect to the region.

Parameters
point:Vector<S>

point to check

Returns:Region.Location

a code representing the point status: either Region.Location#INSIDE, Region.Location#OUTSIDE or Region.Location#BOUNDARY

checkPointback to summary
public Region.Location checkPoint(final Point<S> point)

Implements org.apache.commons.math3.geometry.partitioning.Region.checkPoint.

Doc from org.apache.commons.math3.geometry.partitioning.Region.checkPoint.

Check a point with respect to the region.

Parameters
point:Point<S>

point to check

Returns:Region.Location

a code representing the point status: either Location#INSIDE, Location#OUTSIDE or Location#BOUNDARY

checkPointback to summary
protected Region.Location checkPoint(final BSPTree<S> node, final Vector<S> point)

Check a point with respect to the region starting at a given node.

Parameters
node:BSPTree<S>

root node of the region

point:Vector<S>

point to check

Returns:Region.Location

a code representing the point status: either INSIDE, OUTSIDE or BOUNDARY

checkPointback to summary
protected Region.Location checkPoint(final BSPTree<S> node, final Point<S> point)

Check a point with respect to the region starting at a given node.

Parameters
node:BSPTree<S>

root node of the region

point:Point<S>

point to check

Returns:Region.Location

a code representing the point status: either INSIDE, OUTSIDE or BOUNDARY

computeGeometricalPropertiesback to summary
protected abstract void computeGeometricalProperties()

Compute some geometrical properties.

The properties to compute are the barycenter and the size.

containsback to summary
public boolean contains(final Region<S> region)

Implements org.apache.commons.math3.geometry.partitioning.Region.contains.

Doc from org.apache.commons.math3.geometry.partitioning.Region.contains.

Check if the instance entirely contains another region.

Parameters
region:Region<S>

region to check against the instance

Returns:boolean

true if the instance contains the specified tree

copySelfback to summary
public AbstractRegion<S, T> copySelf()

Implements org.apache.commons.math3.geometry.partitioning.Region.copySelf.

Doc from org.apache.commons.math3.geometry.partitioning.Region.copySelf.

Copy the instance.

The instance created is completely independant of the original one. A deep copy is used, none of the underlying objects are shared (except for the underlying tree Boolean attributes and immutable objects).

Returns:AbstractRegion<S, T>

a new region, copy of the instance

getBarycenterback to summary
public Point<S> getBarycenter()

Implements org.apache.commons.math3.geometry.partitioning.Region.getBarycenter.

Doc from org.apache.commons.math3.geometry.partitioning.Region.getBarycenter.

Get the barycenter of the instance.

Returns:Point<S>

an object representing the barycenter

getBoundarySizeback to summary
public double getBoundarySize()

Implements org.apache.commons.math3.geometry.partitioning.Region.getBoundarySize.

Doc from org.apache.commons.math3.geometry.partitioning.Region.getBoundarySize.

Get the size of the boundary.

Returns:double

the size of the boundary (this is 0 in 1D, a length in 2D, an area in 3D ...)

getSizeback to summary
public double getSize()

Implements org.apache.commons.math3.geometry.partitioning.Region.getSize.

Doc from org.apache.commons.math3.geometry.partitioning.Region.getSize.

Get the size of the instance.

Returns:double

the size of the instance (this is a length in 1D, an area in 2D, a volume in 3D ...)

getToleranceback to summary
public double getTolerance()

Get the tolerance below which points are considered to belong to hyperplanes.

Returns:double

tolerance below which points are considered to belong to hyperplanes

getTreeback to summary
public BSPTree<S> getTree(final boolean includeBoundaryAttributes)

Implements org.apache.commons.math3.geometry.partitioning.Region.getTree.

Doc from org.apache.commons.math3.geometry.partitioning.Region.getTree.

Get the underlying BSP tree.

Regions are represented by an underlying inside/outside BSP tree whose leaf attributes are Boolean instances representing inside leaf cells if the attribute value is true and outside leaf cells if the attribute is false. These leaf attributes are always present and guaranteed to be non null.

In addition to the leaf attributes, the internal nodes which correspond to cells split by cut sub-hyperplanes may contain BoundaryAttribute objects representing the parts of the corresponding cut sub-hyperplane that belong to the boundary. When the boundary attributes have been computed, all internal nodes are guaranteed to have non-null attributes, however some BoundaryAttribute instances may have their getPlusInside and getPlusOutside methods both returning null if the corresponding cut sub-hyperplane does not have any parts belonging to the boundary.

Since computing the boundary is not always required and can be time-consuming for large trees, these internal nodes attributes are computed using lazy evaluation only when required by setting the includeBoundaryAttributes argument to true. Once computed, these attributes remain in the tree, which implies that in this case, further calls to the method for the same region will always include these attributes regardless of the value of the includeBoundaryAttributes argument.

Parameters
includeBoundaryAttributes:boolean

if true, the boundary attributes at internal nodes are guaranteed to be included (they may be included even if the argument is false, if they have already been computed due to a previous call)

Returns:BSPTree<S>

underlying BSP tree

insertCutsback to summary
private void insertCuts(final BSPTree<S> node, final Collection<SubHyperplane<S>> boundary)

Recursively build a tree by inserting cut sub-hyperplanes.

Parameters
node:BSPTree<S>

current tree node (it is a leaf node at the beginning of the call)

boundary:Collection<SubHyperplane<S>>

collection of edges belonging to the cell defined by the node

intersectionback to summary
public SubHyperplane<S> intersection(final SubHyperplane<S> sub)

Implements org.apache.commons.math3.geometry.partitioning.Region.intersection.

Doc from org.apache.commons.math3.geometry.partitioning.Region.intersection.

Get the parts of a sub-hyperplane that are contained in the region.

The parts of the sub-hyperplane that belong to the boundary are not included in the resulting parts.

Parameters
sub:SubHyperplane<S>

sub-hyperplane traversing the region

Returns:SubHyperplane<S>

filtered sub-hyperplane

isEmptyback to summary
public boolean isEmpty()

Implements org.apache.commons.math3.geometry.partitioning.Region.isEmpty.

Doc from org.apache.commons.math3.geometry.partitioning.Region.isEmpty.

Check if the instance is empty.

Returns:boolean

true if the instance is empty

isEmptyback to summary
public boolean isEmpty(final BSPTree<S> node)

Implements org.apache.commons.math3.geometry.partitioning.Region.isEmpty.

Doc from org.apache.commons.math3.geometry.partitioning.Region.isEmpty.

Check if the sub-tree starting at a given node is empty.

Parameters
node:BSPTree<S>

root node of the sub-tree (must have Region tree semantics, i.e. the leaf nodes must have Boolean attributes representing an inside/outside property)

Returns:boolean

true if the sub-tree starting at the given node is empty

isFullback to summary
public boolean isFull()

Implements org.apache.commons.math3.geometry.partitioning.Region.isFull.

Doc from org.apache.commons.math3.geometry.partitioning.Region.isFull.

Check if the instance covers the full space.

Returns:boolean

true if the instance covers the full space

isFullback to summary
public boolean isFull(final BSPTree<S> node)

Implements org.apache.commons.math3.geometry.partitioning.Region.isFull.

Doc from org.apache.commons.math3.geometry.partitioning.Region.isFull.

Check if the sub-tree starting at a given node covers the full space.

Parameters
node:BSPTree<S>

root node of the sub-tree (must have Region tree semantics, i.e. the leaf nodes must have Boolean attributes representing an inside/outside property)

Returns:boolean

true if the sub-tree starting at the given node covers the full space

projectToBoundaryback to summary
public BoundaryProjection<S> projectToBoundary(final Point<S> point)

Implements org.apache.commons.math3.geometry.partitioning.Region.projectToBoundary.

Doc from org.apache.commons.math3.geometry.partitioning.Region.projectToBoundary.

Project a point on the boundary of the region.

Parameters
point:Point<S>

point to check

Returns:BoundaryProjection<S>

projection of the point on the boundary

Since
3.3
recurseIntersectionback to summary
private SubHyperplane<S> recurseIntersection(final BSPTree<S> node, final SubHyperplane<S> sub)

Recursively compute the parts of a sub-hyperplane that are contained in the region.

Parameters
node:BSPTree<S>

current BSP tree node

sub:SubHyperplane<S>

sub-hyperplane traversing the region

Returns:SubHyperplane<S>

filtered sub-hyperplane

recurseTransformback to summary
private BSPTree<S> recurseTransform(final BSPTree<S> node, final Transform<S, T> transform, final Map<BSPTree<S>, BSPTree<S>> map)

Recursively transform an inside/outside BSP-tree.

Parameters
node:BSPTree<S>

current BSP tree node

transform:Transform<S, T>

transform to apply

map:Map<BSPTree<S>, BSPTree<S>>

transformed nodes map

Returns:BSPTree<S>

a new tree

Annotations
@SuppressWarnings:unchecked
setBarycenterback to summary
protected void setBarycenter(final Vector<S> barycenter)

Set the barycenter of the instance.

Parameters
barycenter:Vector<S>

barycenter of the instance

setBarycenterback to summary
protected void setBarycenter(final Point<S> barycenter)

Set the barycenter of the instance.

Parameters
barycenter:Point<S>

barycenter of the instance

setSizeback to summary
protected void setSize(final double size)

Set the size of the instance.

Parameters
size:double

size of the instance

sideback to summary
public Side side(final Hyperplane<S> hyperplane)

Implements org.apache.commons.math3.geometry.partitioning.Region.side.

Doc from org.apache.commons.math3.geometry.partitioning.Region.side.

Deprecated

Compute the relative position of the instance with respect to an hyperplane.

Parameters
hyperplane:Hyperplane<S>

reference hyperplane

Returns:Side

one of Side.PLUS, Side.MINUS, Side.BOTH or Side.HYPER (the latter result can occur only if the tree contains only one cut hyperplane)

Annotations
@Deprecated