Class OverlayNG
- java.lang.Object
-
- org.locationtech.jts.operation.overlayng.OverlayNG
-
public class OverlayNG extends java.lang.Object
Computes the geometric overlay of twoGeometry
s, using an explicit precision model to allow robust computation.The overlay can be used to determine any of the following set-theoretic operations (boolean combinations) of the geometries:
INTERSECTION
- all points which lie in both geometriesUNION
- all points which lie in at least one geometryDIFFERENCE
- all points which lie in the first geometry but not the secondSYMDIFFERENCE
- all points which lie in one geometry but not both
The precision model used for the computation can be supplied independent of the precision model of the input geometry. The main use for this is to allow using a fixed precision for geometry with a floating precision model. This does two things: ensures robust computation; and forces the output to be validly rounded to the precision model.
For fixed precision models noding is performed using a
SnapRoundingNoder
. This provides robust computation (as long as precision is limited to around 13 decimal digits).For floating precision an
MCIndexNoder
is used. This is not fully robust, so can sometimes result inTopologyException
s being thrown. For robust full-precision overlay seeOverlayNGRobust
.A custom
Noder
can be supplied. This allows using a more performant noding strategy in specific cases, for instance inCoverageUnion
.Note:
SnappingNoder
is used it is best to specify a fairly small snap tolerance, since the intersection clipping optimization can interact with the snapping to alter the result.Optionally the overlay computation can process using strict mode (via
setStrictMode(boolean)
. In strict mode result semantics are:- Lines and Points resulting from topology collapses are not included in the result
- Result geometry is homogeneous
for the
INTERSECTION
andDIFFERENCE
operations. - Result geometry is homogeneous
for the
UNION
andSYMDIFFERENCE
operations if the inputs have the same dimension
Strict mode has the following benefits:
- Results are simpler
- Overlay operations are chainable without needing to remove lower-dimension elements
The original JTS overlay semantics corresponds to non-strict mode.
If a robustness error occurs, a
TopologyException
is thrown. These are usually caused by numerical rounding causing the noding output to not be fully noded. For robust computation with full-precisionOverlayNGRobust
can be used.- Author:
- mdavis
- See Also:
OverlayNGRobust
-
-
Field Summary
Fields Modifier and Type Field Description static int
DIFFERENCE
The code for the Difference overlay operation.static int
INTERSECTION
The code for the Intersection overlay operation.static int
SYMDIFFERENCE
The code for the Symmetric Difference overlay operation.static int
UNION
The code for the Union overlay operation.
-
Constructor Summary
Constructors Constructor Description OverlayNG(Geometry geom0, Geometry geom1, int opCode)
Creates an overlay operation on the given geometries using the precision model of the geometries.OverlayNG(Geometry geom0, Geometry geom1, PrecisionModel pm, int opCode)
Creates an overlay operation on the given geometries, with a defined precision model.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description Geometry
getResult()
Gets the result of the overlay operation.static Geometry
overlay(Geometry geom0, Geometry geom1, int opCode)
Computes an overlay operation on the given geometry operands, using the precision model of the geometry.static Geometry
overlay(Geometry geom0, Geometry geom1, int opCode, PrecisionModel pm)
Computes an overlay operation for the given geometry operands, with the noding strategy determined by the precision model.static Geometry
overlay(Geometry geom0, Geometry geom1, int opCode, PrecisionModel pm, Noder noder)
Computes an overlay operation on the given geometry operands, using a suppliedNoder
.static Geometry
overlay(Geometry geom0, Geometry geom1, int opCode, Noder noder)
Computes an overlay operation on the given geometry operands, using a suppliedNoder
.void
setOptimized(boolean isOptimized)
Sets whether overlay processing optimizations are enabled.void
setOutputEdges(boolean isOutputEdges)
void
setOutputNodedEdges(boolean isOutputNodedEdges)
void
setOutputResultEdges(boolean isOutputResultEdges)
void
setStrictMode(boolean isStrictMode)
Sets whether the overlay results are computed according to strict mode semantics.
-
-
-
Field Detail
-
INTERSECTION
public static final int INTERSECTION
The code for the Intersection overlay operation.- See Also:
- Constant Field Values
-
UNION
public static final int UNION
The code for the Union overlay operation.- See Also:
- Constant Field Values
-
DIFFERENCE
public static final int DIFFERENCE
The code for the Difference overlay operation.- See Also:
- Constant Field Values
-
SYMDIFFERENCE
public static final int SYMDIFFERENCE
The code for the Symmetric Difference overlay operation.- See Also:
- Constant Field Values
-
-
Constructor Detail
-
OverlayNG
public OverlayNG(Geometry geom0, Geometry geom1, PrecisionModel pm, int opCode)
Creates an overlay operation on the given geometries, with a defined precision model. The noding strategy is determined by the precision model.- Parameters:
geom0
- the A operand geometrygeom1
- the B operand geometry (may be null)pm
- the precision model to useopCode
- the overlay opcode
-
OverlayNG
public OverlayNG(Geometry geom0, Geometry geom1, int opCode)
Creates an overlay operation on the given geometries using the precision model of the geometries.The noder is chosen according to the precision model specified.
- For
PrecisionModel.FIXED
a snap-rounding noder is used, and the computation is robust. - For
PrecisionModel.FLOATING
a non-snapping noder is used, and this computation may not be robust. If errors occur aTopologyException
is thrown.
- Parameters:
geom0
- the A operand geometrygeom1
- the B operand geometry (may be null)opCode
- the overlay opcode
- For
-
-
Method Detail
-
overlay
public static Geometry overlay(Geometry geom0, Geometry geom1, int opCode, PrecisionModel pm)
Computes an overlay operation for the given geometry operands, with the noding strategy determined by the precision model.- Parameters:
geom0
- the first geometry argumentgeom1
- the second geometry argumentopCode
- the code for the desired overlay operationpm
- the precision model to use- Returns:
- the result of the overlay operation
-
overlay
public static Geometry overlay(Geometry geom0, Geometry geom1, int opCode, PrecisionModel pm, Noder noder)
Computes an overlay operation on the given geometry operands, using a suppliedNoder
.- Parameters:
geom0
- the first geometry argumentgeom1
- the second geometry argumentopCode
- the code for the desired overlay operationpm
- the precision model to use (which may be null if the noder does not use one)noder
- the noder to use- Returns:
- the result of the overlay operation
-
overlay
public static Geometry overlay(Geometry geom0, Geometry geom1, int opCode, Noder noder)
Computes an overlay operation on the given geometry operands, using a suppliedNoder
.- Parameters:
geom0
- the first geometry argumentgeom1
- the second geometry argumentopCode
- the code for the desired overlay operationnoder
- the noder to use- Returns:
- the result of the overlay operation
-
overlay
public static Geometry overlay(Geometry geom0, Geometry geom1, int opCode)
Computes an overlay operation on the given geometry operands, using the precision model of the geometry. and an appropriate noder.The noder is chosen according to the precision model specified.
- For
PrecisionModel.FIXED
a snap-rounding noder is used, and the computation is robust. - For
PrecisionModel.FLOATING
a non-snapping noder is used, and this computation may not be robust. If errors occur aTopologyException
is thrown.
- Parameters:
geom0
- the first argument geometrygeom1
- the second argument geometryopCode
- the code for the desired overlay operation- Returns:
- the result of the overlay operation
- For
-
setStrictMode
public void setStrictMode(boolean isStrictMode)
Sets whether the overlay results are computed according to strict mode semantics.- Lines resulting from topology collapse are not included
- Result geometry is homogeneous
for the
INTERSECTION
andDIFFERENCE
operations. - Result geometry is homogeneous
for the
UNION
andSYMDIFFERENCE
operations if the inputs have the same dimension
- Parameters:
isStrictMode
- true if strict mode is to be used
-
setOptimized
public void setOptimized(boolean isOptimized)
Sets whether overlay processing optimizations are enabled. It may be useful to disable optimizations for testing purposes. Default is TRUE (optimization enabled).- Parameters:
isOptimized
- whether to optimize processing
-
setOutputEdges
public void setOutputEdges(boolean isOutputEdges)
- Parameters:
isOutputEdges
-
-
setOutputNodedEdges
public void setOutputNodedEdges(boolean isOutputNodedEdges)
-
setOutputResultEdges
public void setOutputResultEdges(boolean isOutputResultEdges)
-
getResult
public Geometry getResult()
Gets the result of the overlay operation.- Returns:
- the result of the overlay operation.
- Throws:
java.lang.IllegalArgumentException
- if the input is not supported (e.g. a mixed-dimension geometry)TopologyException
- if a robustness error occurs
-
-