org.tinfour.common

Interface IConstraint

All Superinterfaces:

IPolyline, Iterable<Vertex>

All Known Implementing Classes:

LinearConstraint, PolygonConstraint, PolyLineConstraintAdapter

public interface IConstraint
extends IPolyline

Defines the interface for constraints that can be added to instances of the Incremental TIN classes.

About Constrained Regions
In plane geometry, a simple non-self-intersecting polygon divides the plane into two disjoint regions. So a polygon constraint has the feature that it defines regions. On the other hand, a finite linear constraint does not exhibit this feature.

When one or more polygon constraints are added to a TIN, Tinfour implements a special behavior in which any ordinary edges falling in the interior of the associated regions are marked as being members of a constrained region. Here, the word "interior" actually means the region of the plane lying to the left of an polygon edge. So for a polygon given as a simple loop of vertices taken in counterclockwise order, the left side of each edge is to the inside of the loop and thus the usage of the word "interior" agrees with the ordinary idea of interior being the region inside the polygon. However, if the polygon were taken in clockwise order, the left side of each edge would be to the outside of the polygon. So the polygon would essentially represent a "hole" in a constrained region.

The edges associated with a constrained region fall into 3 categories:

• Border Edges on the border of the constrained region. These edges are constrained and are defined by the polygon constraint.
• Interior Edges that lie within the constrained region. The edges are not constrained, but are marked as interior members due to the fact that they lie within the polygon region.
• Member Both border and interior edges are classified as members

An interior edge is populated with the constraint-index of the constraint. Because interior edges are unambiguously members of a single constrained region, the index can be used to trace the edge back to its containing constraint instance. It is possible for two adjacent polygons to share common border edges. In such cases, the edge preserves the index of only one of the constraint polygons. Thus the mapping from border edge to constraint is ambiguous.

Tinfour allows non-polygon constraints to be specified with a geometry that lines in the interior of a constrained region polygon. In such cases, the edge-marking operation does not mark the constrained edges from the linear constraints as being members of the polygon. Instead, the operation simply passes over them. A real-world example might include a road (a linear constraint) passing through a forested area (a polygon constraint). Edges derived from a linear constraint maintain the index of the constraint that specified them.

Method Summary

Modifier and Type	Method and Description
boolean	definesConstrainedRegion() Indicates whether the constraint applies a constrained region behavior when added to a TIN.
Object	getApplicationData() Gets the application data (if any) stored in the constraint.
int	getConstraintIndex() Gets an index value used for internal bookkeeping by Tinfour code.
IQuadEdge	getConstraintLinkingEdge()
IConstraint	getConstraintWithNewGeometry(List<Vertex> geometry) Gets a new constraint that has the attributes of this constraint and the specified geometry.
IIncrementalTin	getManagingTin() Gets the instance of the incremental TIN interface that is managing this constraint, if any.
boolean	isPointInsideConstraint(double x, double y) Indicates if a point at the specified coordinates is unambiguously inside the constraint.
void	setApplicationData(Object object) Permits an application to add data elements to the constraint for its own uses.
void	setConstraintIndex(IIncrementalTin tin, int index) Sets an index value used for internal bookkeeping by Tinfour code; not intended for use by application code.
void	setConstraintLinkingEdge(IQuadEdge linkingEdge) Sets a reference to an arbitrarily selected edge that was produced when the constraint was added to a TIN.

Methods inherited from interface org.tinfour.common.IPolyline

add, complete, getBounds, getLength, getNominalPointSpacing, getVertices, isPolygon, isValid, refactor

Methods inherited from interface java.lang.Iterable

forEach, iterator, spliterator

Method Detail

definesConstrainedRegion

boolean definesConstrainedRegion()

Indicates whether the constraint applies a constrained region behavior when added to a TIN.

Returns:

true if the constraint is a data-region definition; otherwise false.

setApplicationData

void setApplicationData(Object object)

Permits an application to add data elements to the constraint for its own uses. The reference stored in this instance is not accessed by the Tinfour classes.

Parameters:

object - an object or null according to the needs of the calling application.

getApplicationData

Object getApplicationData()

Gets the application data (if any) stored in the constraint. The reference stored in this instance is not accessed by the Tinfour classes.

Returns:

an object or null according to the needs of the calling application.

getConstraintIndex

int getConstraintIndex()

Gets an index value used for internal bookkeeping by Tinfour code. The index value is assigned to a constraint when it is inserted into a Tinfour IIncrementalTin implementation. If an application used a getConstraints() call to get a list of the constraints stored in an IIncrementalTin, the constraint index can be used to get the constraint from that list.

Returns:

the index of the constraint associated with the edge; undefined if the edge is not constrained or an interior member of a constrained region.

getConstraintLinkingEdge

IQuadEdge getConstraintLinkingEdge()

getConstraintWithNewGeometry

IConstraint getConstraintWithNewGeometry(List<Vertex> geometry)

Gets a new constraint that has the attributes of this constraint and the specified geometry. This method is primarily used in cases where a geometry is very similar (or identical) to the input but either simplified or with replacement vertices.

Parameters:

geometry - a valid set of vertices.

Returns:

a new constraint.

setConstraintIndex

void setConstraintIndex(IIncrementalTin tin,
                        int index)

Sets an index value used for internal bookkeeping by Tinfour code; not intended for use by application code. Application code that sets a constraint index runs the risk of damaging the internal data relations maintained by Tinfour.

Parameters:

tin - the IIncrementalTin instance to while this constraint has been added (or null if not applicable).

index - a positive integer.

setConstraintLinkingEdge

void setConstraintLinkingEdge(IQuadEdge linkingEdge)

Sets a reference to an arbitrarily selected edge that was produced when the constraint was added to a TIN. In effect, this reference links the constraint to the TIN. In the case of constraints that define a constrained region, the edge will be the interior side of the edge.

This method is not intended for use by application code. Application code that sets a constraint index runs the risk of damaging the internal data relations maintained by Tinfour.

Parameters:

linkingEdge - a valid edge reference

getManagingTin

IIncrementalTin getManagingTin()

Gets the instance of the incremental TIN interface that is managing this constraint, if any.

Returns:

if under management, a valid instance; otherwise, a null.

isPointInsideConstraint

boolean isPointInsideConstraint(double x,
                                double y)

Indicates if a point at the specified coordinates is unambiguously inside the constraint. Points on the constraint border are not treated as inside the constraint.

This method will only return true for polygon constraints. For all other constraint implementations, it will return a value of false.

Parameters:

x - the Cartesian coordinate for the point

y - the Cartesian coordinate for the point

Returns:

true if the point is in the interior of the constraint.