SemiVirtualIncrementalTin (Core 2.0 API)

java.lang.Object
- org.tinfour.semivirtual.SemiVirtualIncrementalTin

All Implemented Interfaces:

IIncrementalTin
```
public class SemiVirtualIncrementalTin
extends Object
implements IIncrementalTin
```
Provides a memory-conserving variation on the IncrementalTin class for building and maintaining a Triangulated Irregular Network (TIN) that is optimal with regard to the Delaunay criterion. For background information and tactics for using this class, see the documentation for the IncrementalTin class.
The IncrementalTin class uses an implementation of the quad-edge structure popularized by Guibas and Stolfi. While this structure leads to elegant code, the nature of the Java language (and object-oriented coding in general) results in relatively expensive memory requirements, approximately 244 bytes per vertex inserted into the TIN (counting the storage for both edges and vertices). Since it is common for lidar data sets to include multiple-millions of points, that memory use adds up fast.
This implementation reduces memory requirements by representing the edge-link relationships with internal integer arrays and numerical indexing rather than object references. By keeping the edge relationship data in "virtual form", the implementation reduces the memory use for the edges to about 120 bytes per vertex. The implementation is "semi-virtual" in that all data is still kept in core, but the amount of memory is reduced by a virtual representation of the edge structures.
Unfortunately, this reduction comes with a cost. In testing, the virtual implementation requires approximately 60 percent more runtime to process vertices than the direct implementation. Both implementations experience a degradation of throughput when the memory use approaches the maximum allowed by the JVM (specified on the command line using the -Xmx#### option). But since the virtual implementation uses half the memory of the direct implementation, the onset of degraded conditions when working with a fixed memory size can be pushed back considerably using the virtual implementation.
This class also dramatically reduces the number of objects that are used to represent the TIN. The IncrementalTIN class uses about 7.005 objects per vertex (including vertices and edges) while the virtual implementation uses only about 1.012. This reduction can be valuable in reducing the impact of garbage collection when processing large data sets.
Support for the Constrained Delaunay Triangulation (CDT)
Support for the Constrained Delaunay Triangulation (CDT) is not yet implemented for this class. Please use the Standard IncrementalTin class when constraints are required.
Methods and References
A good review of point location using a stochastic Lawson's walk is provided by Soukal, R.; Málková, Kolingerová (2012) "Walking algorithms for point location in TIN models", Computational Geoscience 16:853-869.
The Bower-Watson algorithm for point insertion is discussed in Cheng, Siu-Wing; Dey, T.; Shewchuk, J. (2013) "Delaunay mesh generation", CRC Press, Boca Raton, FL. This is a challenging book that provides an overview of both 2D and solid TIN models. Jonathan Shewchuk is pretty much the expert on Delaunay Triangulations and his writings were a valuable resource in the creation of this class. You can also read Bowyer's and Watson's original papers both of which famously appeared in the same issue of the same journal in 1981. See Bowyer, A. (1981) "Computing Dirichlet tesselations", The Computer Journal" Vol 24, No 2., p. 162-166. and Watson, D. (1981) "Computing the N-dimensional tesselation with application to Voronoi Diagrams", The Computer Journal" Vol 24, No 2., p. 167-172.
The point-removal algorithm is due to Devillers. See Devillers, O. (2002), "On deletion in delaunay triangulations", International Journal of Computational Geometry & Applications 12.3 p. 123-2005.
The QuadEdge concept is based on the structure popularized by Guibas, L. and Stolfi, J. (1985) "Primitives for the manipulation of subdivisions and the computation of Voronoi diagrams" ACM Transactions on Graphics, 4(2), 1985, p. 75-123.

Constructor Summary

Constructors
Constructor and Description
`SemiVirtualIncrementalTin()` Constructs an incremental TIN using numerical thresholds appropriate for the default nominal point spacing of 1 unit.
`SemiVirtualIncrementalTin(double nominalPointSpacing)` Constructs an incremental TIN using numerical thresholds appropriate for the specified nominal point spacing.

Method Summary

All Methods Instance Methods Concrete Methods
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 triangle 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.
`SemiVirtualEdge`	`getStartingEdge()` Obtains an arbitrary edge to serve as the start of a search or traversal operation.
`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.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Constructor Detail
  - SemiVirtualIncrementalTin
```
public SemiVirtualIncrementalTin()
```
    Constructs an incremental TIN using numerical thresholds appropriate for the default nominal point spacing of 1 unit.
  - SemiVirtualIncrementalTin
```
public SemiVirtualIncrementalTin(double nominalPointSpacing)
```
    Constructs an incremental TIN using numerical thresholds appropriate for the specified nominal point spacing. This value is an estimated spacing used for determining 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.
    
    Parameters:
    
    nominalPointSpacing - the nominal distance between points.
- Method Detail
  - add
```
public 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.
    
    Specified by:
    
    add in interface IIncrementalTin
    
    Parameters:
    
    v - a valid vertex
    
    Returns:
    
    true if the TIN is bootstrapped; otherwise false
  - add
```
public 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. The initialization will make a small number of selection attempts and select the triangle with the largest number. In the event that this process does not find three points that 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.
    
    Specified by:
    
    add in interface IIncrementalTin
    
    Parameters:
    
    list - a valid list of vertices to be added to the TIN.
    
    monitor - an optional instance of a monitoring implementation; null if not used
    
    Returns:
    
    true if the TIN is bootstrapped; otherwise false
  - preAllocateEdges
```
public void preAllocateEdges(int nVertices)
```
    Allocates a number of vertices roughly sufficient to represent a TIN containing the specified number of vertices. This method serves as a diagnostic tool, allowing a test-application to separate the portion of processing time consumed by Java object construction from that spent processing the vertex data.
    
    Specified by:
    
    preAllocateEdges in interface IIncrementalTin
    
    Parameters:
    
    nVertices - the number of vertices expected to be added to the TIN.
  - getBounds
```
public Rectangle2D getBounds()
```
    Gets the bounds of the TIN. If the TIN is not initialized (bootstrapped), this method returns a null.
    
    Specified by:
    
    getBounds in interface IIncrementalTin
    
    Returns:
    
    if available, a valid rectangle giving the bounds of the TIN; otherwise, a null
  - printEdges
```
public void printEdges(PrintStream ps)
```
    Provides a diagnostic print out of the edges comprising the TIN.
    
    Specified by:
    
    printEdges in interface IIncrementalTin
    
    Parameters:
    
    ps - A valid print stream.
  - countTriangles
```
public TriangleCount countTriangles()
```
    Performs a survey of the TIN to gather statistics about the triangle formed during its construction.
    
    Specified by:
    
    countTriangles in interface IIncrementalTin
    
    Returns:
    
    A valid instance of the TriangleCount class.
  - getPerimeter
```
public 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.
    
    Specified by:
    
    getPerimeter in interface IIncrementalTin
    
    Returns:
    
    a valid, potentially empty list.
  - printDiagnostics
```
public 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.
    
    Specified by:
    
    printDiagnostics in interface IIncrementalTin
    
    Parameters:
    
    ps - A valid instance of a PrintStream to receive the output.
  - getEdges
```
public 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.
    
    Specified by:
    
    getEdges in interface IIncrementalTin
    
    Returns:
    
    a valid, potentially empty list.
  - getEdgeIterator
```
public Iterator<IQuadEdge> getEdgeIterator()
```
    Description copied from interface: IIncrementalTin
    
    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.
    
    Specified by:
    
    getEdgeIterator in interface IIncrementalTin
    
    Returns:
    
    a valid iterator.
  - edges
```
public Iterable<IQuadEdge> edges()
```
    Description copied from interface: IIncrementalTin
    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.
    Specified by:
    
    edges in interface IIncrementalTin
    
    Returns:
    
    a valid instance.
  - getMaximumEdgeAllocationIndex
```
public int getMaximumEdgeAllocationIndex()
```
    Description copied from interface: IIncrementalTin
    
    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.
    
    Specified by:
    
    getMaximumEdgeAllocationIndex in interface IIncrementalTin
    
    Returns:
    
    a positive value or zero if the TIN is not bootstrapped.
  - getNominalPointSpacing
```
public 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.
    
    Specified by:
    
    getNominalPointSpacing in interface IIncrementalTin
    
    Returns:
    
    a positive floating-point value greater than zero.
  - getThresholds
```
public Thresholds getThresholds()
```
    Description copied from interface: IIncrementalTin
    
    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.
    
    Specified by:
    
    getThresholds in interface IIncrementalTin
    
    Returns:
    
    a valid instance
  - dispose
```
public void dispose()
```
    Description copied from interface: IIncrementalTin
    
    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.
    
    Specified by:
    
    dispose in interface IIncrementalTin
  - clear
```
public void clear()
```
    Description copied from interface: IIncrementalTin
    
    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.
    
    Specified by:
    
    clear in interface IIncrementalTin
  - isBootstrapped
```
public 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.
    
    Specified by:
    
    isBootstrapped in interface IIncrementalTin
    
    Returns:
    
    true if the TIN is successfully initialized; otherwise, false.
  - remove
```
public 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.
    At this time, this method does not handle the case where all vertices are removed from the TIN.
    
    Specified by:
    
    remove in interface IIncrementalTin
    
    Parameters:
    
    vRemove - the vertex to be removed
    
    Returns:
    
    true if the vertex was found in the TIN and removed.
  - getStartingEdge
```
public SemiVirtualEdge getStartingEdge()
```
    Obtains an arbitrary edge to serve as the start of a search or traversal operation.
    
    Returns:
    
    An ordinary (non-ghost) edge.
  - setResolutionRuleForMergedVertices
```
public 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.
    
    Specified by:
    
    setResolutionRuleForMergedVertices in interface IIncrementalTin
    
    Parameters:
    
    resolutionRule - The rule to be used for interpreting merged vertices.
  - getVertices
```
public 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.
    
    Specified by:
    
    getVertices in interface IIncrementalTin
    
    Returns:
    
    a valid list of vertices, potentially empty if the TIN has not been initialized.
  - getNeighborEdgeLocator
```
public INeighborEdgeLocator getNeighborEdgeLocator()
```
    Description copied from interface: IIncrementalTin
    
    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.
    
    Specified by:
    
    getNeighborEdgeLocator in interface IIncrementalTin
    
    Returns:
    
    an edge locator tied to this TIN.
  - getNeighborhoodPointsCollector
```
public INeighborhoodPointsCollector getNeighborhoodPointsCollector()
```
    Description copied from interface: IIncrementalTin
    
    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.
    
    Specified by:
    
    getNeighborhoodPointsCollector in interface IIncrementalTin
    
    Returns:
    
    an points collector tied to this TIN.
  - getIntegrityCheck
```
public IIntegrityCheck getIntegrityCheck()
```
    Description copied from interface: IIncrementalTin
    
    Gets an implementation of the integrity check interface suitable for the referenced TIN implementation.
    
    Specified by:
    
    getIntegrityCheck in interface IIncrementalTin
    
    Returns:
    
    a valid integrity check implementation.
  - isPointInsideTin
```
public boolean isPointInsideTin(double x,
                                double y)
```
    Description copied from interface: IIncrementalTin
    
    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.
    
    Specified by:
    
    isPointInsideTin in interface IIncrementalTin
    
    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.
  - addConstraints
```
public void addConstraints(List<IConstraint> constraints,
                           boolean restoreConformity)
```
    Description copied from interface: IIncrementalTin
    
    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.
    
    Specified by:
    
    addConstraints in interface IIncrementalTin
    
    Parameters:
    
    constraints - a valid, potentially empty list.
    
    restoreConformity - restores conformity
  - getConstraints
```
public List<IConstraint> getConstraints()
```
    Description copied from interface: IIncrementalTin
    
    Gets a shallow copy of the list of constraints currently stored in the TIN.
    
    Specified by:
    
    getConstraints in interface IIncrementalTin
    
    Returns:
    
    a valid, potentially empty list of constraint instances.
  - getConstraint
```
public IConstraint getConstraint(int index)
```
    Description copied from interface: IIncrementalTin
    
    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.
    
    Specified by:
    
    getConstraint in interface IIncrementalTin
    
    Parameters:
    
    index - an arbitrary integer index
    
    Returns:
    
    if found, a valid constraint; otherwise a null.
  - getSyntheticVertexCount
```
public int getSyntheticVertexCount()
```
    Description copied from interface: IIncrementalTin
    
    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.
    
    Specified by:
    
    getSyntheticVertexCount in interface IIncrementalTin
    
    Returns:
    
    a positive integer, potentially zero.

Class SemiVirtualIncrementalTin

Support for the Constrained Delaunay Triangulation (CDT)

Methods and References

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

SemiVirtualIncrementalTin

SemiVirtualIncrementalTin

Method Detail

add

add

Performance Consideration Related to List

preAllocateEdges

getBounds

printEdges

countTriangles

getPerimeter

printDiagnostics

getEdges

getEdgeIterator

edges

getMaximumEdgeAllocationIndex

getNominalPointSpacing

getThresholds

dispose

clear

isBootstrapped

remove

getStartingEdge

setResolutionRuleForMergedVertices

getVertices

getNeighborEdgeLocator

getNeighborhoodPointsCollector

getIntegrityCheck

isPointInsideTin

addConstraints

getConstraints

getConstraint

getSyntheticVertexCount