Class PrecisionModel
- java.lang.Object
-
- org.locationtech.jts.geom.PrecisionModel
-
- All Implemented Interfaces:
java.io.Serializable
,java.lang.Comparable
public class PrecisionModel extends java.lang.Object implements java.io.Serializable, java.lang.Comparable
Specifies the precision model of theCoordinate
s in aGeometry
. In other words, specifies the grid of allowable points for allGeometry
s.The
makePrecise(Coordinate)
method allows rounding a coordinate to a "precise" value; that is, one whose precision is known exactly.Coordinates are assumed to be precise in geometries. That is, the coordinates are assumed to be rounded to the precision model given for the geometry. JTS input routines automatically round coordinates to the precision model before creating Geometries. All internal operations assume that coordinates are rounded to the precision model. Constructive methods (such as boolean operations) always round computed coordinates to the appropriate precision model.
Currently three types of precision model are supported:
- FLOATING - represents full double precision floating point. This is the default precision model used in JTS
- FLOATING_SINGLE - represents single precision floating point.
- FIXED - represents a model with a fixed number of decimal places.
A Fixed Precision Model is specified by a scale factor.
The scale factor specifies the size of the grid which numbers are rounded to.
Input coordinates are mapped to fixed coordinates according to the following
equations:
- jtsPt.x = round( (inputPt.x * scale ) / scale
- jtsPt.y = round( (inputPt.y * scale ) / scale
Coordinates are represented internally as Java double-precision values. Since Java uses the IEEE-394 floating point standard, this provides 53 bits of precision. (Thus the maximum precisely representable integer is 9,007,199,254,740,992 - or almost 16 decimal digits of precision).
JTS binary methods currently do not handle inputs which have different precision models. The precision model of any constructed geometric value is undefined.
- Version:
- 1.7
- See Also:
- Serialized Form
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description static class
PrecisionModel.Type
The types of Precision Model which JTS supports.
-
Field Summary
Fields Modifier and Type Field Description static PrecisionModel.Type
FIXED
Fixed Precision indicates that coordinates have a fixed number of decimal places.static PrecisionModel.Type
FLOATING
Floating precision corresponds to the standard Java double-precision floating-point representation, which is based on the IEEE-754 standardstatic PrecisionModel.Type
FLOATING_SINGLE
Floating single precision corresponds to the standard Java single-precision floating-point representation, which is based on the IEEE-754 standardstatic double
maximumPreciseValue
The maximum precise value representable in a double.
-
Constructor Summary
Constructors Constructor Description PrecisionModel()
Creates aPrecisionModel
with a default precision of FLOATING.PrecisionModel(double scale)
Creates aPrecisionModel
that specifies Fixed precision.PrecisionModel(double scale, double offsetX, double offsetY)
Deprecated.offsets are no longer supported, since internal representation is rounded floating pointPrecisionModel(PrecisionModel pm)
Copy constructor to create a newPrecisionModel
from an existing one.PrecisionModel(PrecisionModel.Type modelType)
Creates aPrecisionModel
that specifies an explicit precision model type.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods Modifier and Type Method Description int
compareTo(java.lang.Object o)
Compares thisPrecisionModel
object with the specified object for order.boolean
equals(java.lang.Object other)
int
getMaximumSignificantDigits()
Returns the maximum number of significant digits provided by this precision model.double
getOffsetX()
Deprecated.Offsets are no longer useddouble
getOffsetY()
Deprecated.Offsets are no longer useddouble
getScale()
Returns the scale factor used to specify a fixed precision model.PrecisionModel.Type
getType()
Gets the type of this precision modelboolean
isFloating()
Tests whether the precision model supports floating pointdouble
makePrecise(double val)
Rounds a numeric value to the PrecisionModel grid.void
makePrecise(Coordinate coord)
Rounds a Coordinate to the PrecisionModel grid.static PrecisionModel
mostPrecise(PrecisionModel pm1, PrecisionModel pm2)
Determines which of twoPrecisionModel
s is the most precise (allows the greatest number of significant digits).Coordinate
toExternal(Coordinate internal)
Deprecated.no longer needed, since internal representation is same as external representationvoid
toExternal(Coordinate internal, Coordinate external)
Deprecated.no longer needed, since internal representation is same as external representationCoordinate
toInternal(Coordinate external)
Deprecated.use makePrecise insteadvoid
toInternal(Coordinate external, Coordinate internal)
Deprecated.use makePrecise insteadjava.lang.String
toString()
-
-
-
Field Detail
-
FIXED
public static final PrecisionModel.Type FIXED
Fixed Precision indicates that coordinates have a fixed number of decimal places. The number of decimal places is determined by the log10 of the scale factor.
-
FLOATING
public static final PrecisionModel.Type FLOATING
Floating precision corresponds to the standard Java double-precision floating-point representation, which is based on the IEEE-754 standard
-
FLOATING_SINGLE
public static final PrecisionModel.Type FLOATING_SINGLE
Floating single precision corresponds to the standard Java single-precision floating-point representation, which is based on the IEEE-754 standard
-
maximumPreciseValue
public static final double maximumPreciseValue
The maximum precise value representable in a double. Since IEE754 double-precision numbers allow 53 bits of mantissa, the value is equal to 2^53 - 1. This provides almost 16 decimal digits of precision.- See Also:
- Constant Field Values
-
-
Constructor Detail
-
PrecisionModel
public PrecisionModel()
Creates aPrecisionModel
with a default precision of FLOATING.
-
PrecisionModel
public PrecisionModel(PrecisionModel.Type modelType)
Creates aPrecisionModel
that specifies an explicit precision model type. If the model type is FIXED the scale factor will default to 1.- Parameters:
modelType
- the type of the precision model
-
PrecisionModel
public PrecisionModel(double scale, double offsetX, double offsetY)
Deprecated.offsets are no longer supported, since internal representation is rounded floating pointCreates aPrecisionModel
that specifies Fixed precision. Fixed-precision coordinates are represented as precise internal coordinates, which are rounded to the grid defined by the scale factor.- Parameters:
scale
- amount by which to multiply a coordinate after subtracting the offset, to obtain a precise coordinateoffsetX
- not used.offsetY
- not used.
-
PrecisionModel
public PrecisionModel(double scale)
Creates aPrecisionModel
that specifies Fixed precision. Fixed-precision coordinates are represented as precise internal coordinates, which are rounded to the grid defined by the scale factor.- Parameters:
scale
- amount by which to multiply a coordinate after subtracting the offset, to obtain a precise coordinate
-
PrecisionModel
public PrecisionModel(PrecisionModel pm)
Copy constructor to create a newPrecisionModel
from an existing one.
-
-
Method Detail
-
mostPrecise
public static PrecisionModel mostPrecise(PrecisionModel pm1, PrecisionModel pm2)
Determines which of twoPrecisionModel
s is the most precise (allows the greatest number of significant digits).- Parameters:
pm1
- a PrecisionModelpm2
- a PrecisionModel- Returns:
- the PrecisionModel which is most precise
-
isFloating
public boolean isFloating()
Tests whether the precision model supports floating point- Returns:
true
if the precision model supports floating point
-
getMaximumSignificantDigits
public int getMaximumSignificantDigits()
Returns the maximum number of significant digits provided by this precision model. Intended for use by routines which need to print out decimal representations of precise values (such asWKTWriter
).This method would be more correctly called getMinimumDecimalPlaces, since it actually computes the number of decimal places that is required to correctly display the full precision of an ordinate value.
Since it is difficult to compute the required number of decimal places for scale factors which are not powers of 10, the algorithm uses a very rough approximation in this case. This has the side effect that for scale factors which are powers of 10 the value returned is 1 greater than the true value.
- Returns:
- the maximum number of decimal places provided by this precision model
-
getScale
public double getScale()
Returns the scale factor used to specify a fixed precision model. The number of decimal places of precision is equal to the base-10 logarithm of the scale factor. Non-integral and negative scale factors are supported. Negative scale factors indicate that the places of precision is to the left of the decimal point.- Returns:
- the scale factor for the fixed precision model
-
getType
public PrecisionModel.Type getType()
Gets the type of this precision model- Returns:
- the type of this precision model
- See Also:
PrecisionModel.Type
-
getOffsetX
public double getOffsetX()
Deprecated.Offsets are no longer usedReturns the x-offset used to obtain a precise coordinate.- Returns:
- the amount by which to subtract the x-coordinate before multiplying by the scale
-
getOffsetY
public double getOffsetY()
Deprecated.Offsets are no longer usedReturns the y-offset used to obtain a precise coordinate.- Returns:
- the amount by which to subtract the y-coordinate before multiplying by the scale
-
toInternal
public void toInternal(Coordinate external, Coordinate internal)
Deprecated.use makePrecise insteadSetsinternal
to the precise representation ofexternal
.- Parameters:
external
- the original coordinateinternal
- the coordinate whose values will be changed to the precise representation ofexternal
-
toInternal
public Coordinate toInternal(Coordinate external)
Deprecated.use makePrecise insteadReturns the precise representation ofexternal
.- Parameters:
external
- the original coordinate- Returns:
- the coordinate whose values will be changed to the precise
representation of
external
-
toExternal
public Coordinate toExternal(Coordinate internal)
Deprecated.no longer needed, since internal representation is same as external representationReturns the external representation ofinternal
.- Parameters:
internal
- the original coordinate- Returns:
- the coordinate whose values will be changed to the
external representation of
internal
-
toExternal
public void toExternal(Coordinate internal, Coordinate external)
Deprecated.no longer needed, since internal representation is same as external representationSetsexternal
to the external representation ofinternal
.- Parameters:
internal
- the original coordinateexternal
- the coordinate whose values will be changed to the external representation ofinternal
-
makePrecise
public double makePrecise(double val)
Rounds a numeric value to the PrecisionModel grid. Asymmetric Arithmetic Rounding is used, to provide uniform rounding behaviour no matter where the number is on the number line.This method has no effect on NaN values.
Note: Java's
Math#rint
uses the "Banker's Rounding" algorithm, which is not suitable for precision operations elsewhere in JTS.
-
makePrecise
public void makePrecise(Coordinate coord)
Rounds a Coordinate to the PrecisionModel grid.
-
toString
public java.lang.String toString()
- Overrides:
toString
in classjava.lang.Object
-
equals
public boolean equals(java.lang.Object other)
- Overrides:
equals
in classjava.lang.Object
-
compareTo
public int compareTo(java.lang.Object o)
Compares thisPrecisionModel
object with the specified object for order. A PrecisionModel is greater than another if it provides greater precision. The comparison is based on the value returned by thegetMaximumSignificantDigits()
method. This comparison is not strictly accurate when comparing floating precision models to fixed models; however, it is correct when both models are either floating or fixed.- Specified by:
compareTo
in interfacejava.lang.Comparable
- Parameters:
o
- thePrecisionModel
with which thisPrecisionModel
is being compared- Returns:
- a negative integer, zero, or a positive integer as this
PrecisionModel
is less than, equal to, or greater than the specifiedPrecisionModel
-
-