org.tinfour.common

Interface IIncrementalTin

All Known Implementing Classes:

IncrementalTin, SemiVirtualIncrementalTin

public interface IIncrementalTin

Defines the primary methods used by an incremental TIN implementation. The intended purpose of this interface is to support automatic testing of different TIN implementations or to compare the results of experimental changes.

Method Summary

Modifier and Type	Method and Description
boolean	add(List<Vertex> list, IMonitorWithCancellation monitor) Inserts a list of vertices into the collection of vertices managed by the TIN.
boolean	add(Vertex v) Insert a vertex into the collection of vertices managed by the TIN.
void	addConstraints(List<IConstraint> constraints, boolean restoreConformity) Adds constraints to the TIN.
void	clear() Clears all internal state data of the TIN, preparing any allocated resources for re-use.
TriangleCount	countTriangles() Performs a survey of the TIN to gather statistics about the triangles formed during its construction.
void	dispose() Nullifies all internal data and references, preparing the instance for garbage collection.
Iterable<IQuadEdge>	edges() Provides a convenience implementation of a wrapper class that can be used in a Java enhanced-loop statement.
Rectangle2D	getBounds() Gets the bounds of the TIN.
IConstraint	getConstraint(int index) Gets the constraint associated with the index, or a null if no such constraint exists.
List<IConstraint>	getConstraints() Gets a shallow copy of the list of constraints currently stored in the TIN.
Iterator<IQuadEdge>	getEdgeIterator() Gets an iterator for stepping through the collection of edges currently stored in the TIN.
List<IQuadEdge>	getEdges() Gets a list of edges currently allocated by an instance.
IIntegrityCheck	getIntegrityCheck() Gets an implementation of the integrity check interface suitable for the referenced TIN implementation.
int	getMaximumEdgeAllocationIndex() Gets the maximum index of the currently allocated edges.
INeighborEdgeLocator	getNeighborEdgeLocator() Gets a new instance of the INeighborEdgeLocator interface.
INeighborhoodPointsCollector	getNeighborhoodPointsCollector() Gets a new instance of a neighborhood points collector.
double	getNominalPointSpacing() Gets the nominal point spacing used to determine numerical thresholds for various proximity and inclusion tests.
List<IQuadEdge>	getPerimeter() Gets a list of edges currently defining the perimeter of the TIN.
int	getSyntheticVertexCount() Gets the number of synthetic vertices added to the TIN.
Thresholds	getThresholds() Gets the Thresholds object that is associated with this instance.
List<Vertex>	getVertices() Gets a list of vertices currently stored in the TIN.
boolean	isBootstrapped() Indicates whether the instance contains sufficient information to represent a TIN.
boolean	isPointInsideTin(double x, double y) Determines whether the point is inside the convex polygon boundary of the TIN.
void	preAllocateEdges(int nVertices) Allocates a number of vertices roughly sufficient to represent a TIN containing the specified number of vertices.
void	printDiagnostics(PrintStream ps) Print statistics and diagnostic information collected during the TIN construction process.
void	printEdges(PrintStream ps) Provides a diagnostic print out of the edges comprising the TIN.
boolean	remove(Vertex vRemove) Removes the specified vertex from the TIN.
void	setResolutionRuleForMergedVertices(VertexMergerGroup.ResolutionRule resolutionRule) Specifies a rule for interpreting the Z value of a group of vertices that were merged due to being coincident, or nearly coincident.

Method Detail

clear

void clear()

Clears all internal state data of the TIN, preparing any allocated resources for re-use. When processing multiple sets of input data the clear() method has an advantage in that it can be used to reduce the overhead related to multiple edge object implementation.

countTriangles

TriangleCount countTriangles()

Performs a survey of the TIN to gather statistics about the triangles formed during its construction.

Returns:

A valid instance of the TriangleCount class.

dispose

void dispose()

Nullifies all internal data and references, preparing the instance for garbage collection. Because of the complex relationships between objects in a TIN, Java garbage collection may require an above average number of passes to clean up memory when an instance of this class goes out-of-scope. The dispose() method can be used to expedite garbage collection. Do not confuse the dispose() method with the clear() method. The clear() method prepares a TIN instance for reuse. The dispose() method prepares a TIN instance for garbage collection. Once the dispose() method is called on a TIN, it cannot be reused.

getBounds

Rectangle2D getBounds()

Gets the bounds of the TIN. If the TIN is not initialized (bootstrapped), this method returns a null.

Returns:

if available, a valid rectangle giving the bounds of the TIN; otherwise, a null

getEdges

List<IQuadEdge> getEdges()

Gets a list of edges currently allocated by an instance. The list may be empty if the TIN is not initialized (bootstrapped).

Warning: For efficiency purposes, the edges return by this routine are the same objects as those currently being used in the instance. Any modification of the edge objects will damage the TIN. Therefore, applications must not modify the edges returned by this method.

Returns:

a valid, potentially empty list.

getEdgeIterator

Iterator<IQuadEdge> getEdgeIterator()

Gets an iterator for stepping through the collection of edges currently stored in the TIN.

Warning: For efficiency purposes, the edges returned by this routine are the same objects as those currently being used in the instance. Any modification of the edge objects will damage the TIN. Therefore, applications must not modify the edges returned by this method. Caution: For reasons of efficiency, the iterator does not offer any protection against concurrent modification. Therefore applications using this iterator must never modify the TIN during iteration.

Returns:

a valid iterator.

edges

Iterable<IQuadEdge> edges()

Provides a convenience implementation of a wrapper class that can be used in a Java enhanced-loop statement. The edges produced by this Iterator are filtered so that the fictitious edges (ghost edges) are not produced by the iteration. For example, this method could be used in the following manner:

     IIncremntal tin = // some implementation
     for(IQuadEdge e: tin.edges(){
            // some processing logic
     }
 

Please see the API documentation for getEdgeIterator() for cautions regarding the use of this method.

Returns:

a valid instance.

getMaximumEdgeAllocationIndex

int getMaximumEdgeAllocationIndex()

Gets the maximum index of the currently allocated edges. This method can be used in support of applications that require the need to survey the edge set and maintain a parallel array or collection instance that tracks information about the edges. In such cases, the maximum edge index provides a way of knowing how large to size the array or collection.

Internally, Tinfour uses edge index values to manage edges in memory. The while there can be small gaps in the indexing sequence, this method provides a way of obtaining the absolute maximum value of currently allocated edges.

Returns:

a positive value or zero if the TIN is not bootstrapped.

getNominalPointSpacing

double getNominalPointSpacing()

Gets the nominal point spacing used to determine numerical thresholds for various proximity and inclusion tests. For best results, it should be within one to two orders of magnitude of the actual value for the samples. In practice, this value is usually chosen to be close to the mean point spacing for a sample. But for samples with varying density, a mean value from the set of smaller point spacings may be used.

Lidar applications sometimes refer to the point-spacing concept as "nominal pulse spacing", a term that reflects the origin of the data in a laser-based measuring system.

Returns:

a positive floating-point value greater than zero.

getThresholds

Thresholds getThresholds()

Gets the Thresholds object that is associated with this instance. Because all elements in Thresholds are declared final (immutable), it can be shared safely between multiple threads or other classes.

Returns:

a valid instance

getPerimeter

List<IQuadEdge> getPerimeter()

Gets a list of edges currently defining the perimeter of the TIN. The list may be empty if the TIN is not initialized (bootstrapped).

Warning: For efficiency purposes, the edges return by this routine are the same objects as those currently being used in the instance. Any modification of the edge objects will damage the TIN. Therefore, applications must not modify the edges returned by this method.

Returns:

a valid, potentially empty list.

getNeighborEdgeLocator

INeighborEdgeLocator getNeighborEdgeLocator()

Gets a new instance of the INeighborEdgeLocator interface. Instances observe the contract of the IProcessUsingTin interface in that they access the TIN on a readonly basis and may be used in parallel threads provided that the TIN is not modified.

Returns:

an edge locator tied to this TIN.

getNeighborhoodPointsCollector

INeighborhoodPointsCollector getNeighborhoodPointsCollector()

Gets a new instance of a neighborhood points collector. Instances observe the contract of the IProcessUsingTin interface in that they access the TIN on a readonly basis and may be used in parallel threads provided that the TIN is not modified.

Returns:

an points collector tied to this TIN.

getIntegrityCheck

IIntegrityCheck getIntegrityCheck()

Gets an implementation of the integrity check interface suitable for the referenced TIN implementation.

Returns:

a valid integrity check implementation.

add

boolean add(Vertex v)

Insert a vertex into the collection of vertices managed by the TIN. If the TIN is not yet bootstrapped, the vertex will be retained in a simple list until enough vertices are received in order to bootstrap the TIN.

Parameters:

v - a valid vertex

Returns:

true if the TIN is bootstrapped; otherwise false

add

boolean add(List<Vertex> list,
            IMonitorWithCancellation monitor)

Inserts a list of vertices into the collection of vertices managed by the TIN. If the TIN is not yet bootstrapped, the vertices will be retained in a simple list until enough vertices are received in order to bootstrap the TIN.

Performance Consideration Related to List

In the bootstrap phase, three points are chosen at random from the vertex list to create the initial triangle for insertion. In the event that the three points are not a suitable choice (as when they are collinear or nearly collinear), the process will be repeated until a valid initial triangle is selected. Thus, there is a small performance advantage in supplying the vertices using a list that can be accessed efficiently in a random order (see the discussion of the Java API for the List and java.util.RandomAccess interfaces). Once the initial triangle is established, the list will be traversed sequentially to build the TIN and random access considerations will no longer apply.

Parameters:

list - a valid list of vertices to be added to the TIN.

monitor - an optional monitoring implementation; null if not used.

Returns:

true if the TIN is bootstrapped; otherwise false

preAllocateEdges

void preAllocateEdges(int nVertices)

Allocates a number of vertices roughly sufficient to represent a TIN containing the specified number of vertices. This method also serves as a diagnostic tool, allowing a test-application to separate the portion of processing time consumed by Java object construction from that spent on processing the vertex data.

Parameters:

nVertices - the number of vertices expected to be added to the TIN.

printDiagnostics

void printDiagnostics(PrintStream ps)

Print statistics and diagnostic information collected during the TIN construction process. This information will be removed and reset by a call to the clear() method.

Parameters:

ps - A valid instance of a PrintStream to receive the output.

getVertices

List<Vertex> getVertices()

Gets a list of vertices currently stored in the TIN. This list of objects is not necessarily equivalent to the set of objects that were input because some vertices may have been incorporated into one or more vertex-merger groups. Note that the list of vertices is not sorted and will usually not be returned in the same order as the original input set.

Note: For efficiency purposes, the vertices return by this routine are the same objects as those currently being used in the instance. The index and "reserved" elements of the Vertex class are not used by the TIN and may be modified by application code as required. However, the geometry related fields must not be modified once a vertex is added to a TIN.

Returns:

a valid list of vertices, potentially empty if the TIN has not been initialized.

isBootstrapped

boolean isBootstrapped()

Indicates whether the instance contains sufficient information to represent a TIN. Bootstrapping requires the input of at least three distinct, non-collinear vertices. If the TIN is not bootstrapped methods that access its content may return empty or null results.

Returns:

true if the TIN is successfully initialized; otherwise, false.

isPointInsideTin

boolean isPointInsideTin(double x,
                         double y)

Determines whether the point is inside the convex polygon boundary of the TIN. If the TIN is not bootstrapped, this method will return a value of false.

Parameters:

x - The x coordinate of interest

y - THe y coordinate of interest

Returns:

true if the coordinates identify a point inside the boundary of the TIN; otherwise, false.

printEdges

void printEdges(PrintStream ps)

Provides a diagnostic print out of the edges comprising the TIN.

Parameters:

ps - A valid print stream.

remove

boolean remove(Vertex vRemove)

Removes the specified vertex from the TIN. If the vertex is part of a merged-group, it is removed from the group by the structure of the TIN is unchanged.

Parameters:

vRemove - the vertex to be removed

Returns:

true if the vertex was found in the TIN and removed.

setResolutionRuleForMergedVertices

void setResolutionRuleForMergedVertices(VertexMergerGroup.ResolutionRule resolutionRule)

Specifies a rule for interpreting the Z value of a group of vertices that were merged due to being coincident, or nearly coincident.

Parameters:

resolutionRule - The rule to be used for interpreting merged vertices.

addConstraints

void addConstraints(List<IConstraint> constraints,
                    boolean restoreConformity)

Adds constraints to the TIN.

Using Constraints

There are a number of important restrictions to the use of constraints. Constraints must only be added to the TIN once, after all other vertices have already been added. Furthermore, the addConstraint method can only be called once. Logic is implemented as a safety measure to ensure that these restrictions are not accidentally violated.

There are also important restrictions on the geometry of constraints. Most importantly, constraints must never intersect each other except at the endpoints of the segments that define them (i.e. segments in constraints must never cross each other). Due to the high cost of processing required to check that this restriction is observed, it is not directly enforced by the Tinfour implementations.

Restoring Conformity

When constraints are added to a Delaunay triangulation, they often violate the Delaunay criterion and result in a non-conforming mesh. The addConstraint method can optionally restore conformity by inserting synthetic points into the the constraint edges. The cost of this process is additional processing time and an increase in the number of points in the TIN.

When points are synthesized, it is necessary to interpolate a value for the z-coordinate. At this time, the specific interpolation process is undefined. The current Tinfour implementations use linear interpolation between constraint points. While no viable alternative approach is currently under consideration, the choice of interpolation method is subject to change in the future.

Parameters:

constraints - a valid, potentially empty list.

restoreConformity - restores conformity

getConstraints

List<IConstraint> getConstraints()

Gets a shallow copy of the list of constraints currently stored in the TIN.

Returns:

a valid, potentially empty list of constraint instances.

getConstraint

IConstraint getConstraint(int index)

Gets the constraint associated with the index, or a null if no such constraint exists. Note that there is no out-of-bounds range for the input index. An invalid index simply yields a null reference.

Parameters:

index - an arbitrary integer index

Returns:

if found, a valid constraint; otherwise a null.

getSyntheticVertexCount

int getSyntheticVertexCount()

Gets the number of synthetic vertices added to the TIN. Vertices can be synthesized as part of the Delaunay restoration process when adding constraints. Future implementations of additional functions (such as Delaunay refinement) may also add synthetic points.

Returns:

a positive integer, potentially zero.