com.vividsolutions.jts.geom

Class PrecisionModel

Implemented Interfaces:
Comparable, Serializable

public class PrecisionModel
extends java.lang.Object
implements Serializable, Comparable

Specifies the precision model of the Coordinates in a Geometry. In other words, specifies the grid of allowable points for all Geometrys.

The makePrecise 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:

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).

JTS methods currently do not handle inputs with different precision models.

Version:
1.7

Field Summary

static com.vividsolutions.jts.geom.PrecisionModel.Type
FIXED
Fixed Precision indicates that coordinates have a fixed number of decimal places.
static com.vividsolutions.jts.geom.PrecisionModel.Type
FLOATING
Floating precision corresponds to the standard Java double-precision floating-point representation, which is based on the IEEE-754 standard
static com.vividsolutions.jts.geom.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
static double
maximumPreciseValue
The maximum precise value representable in a double.

Constructor Summary

PrecisionModel()
Creates a PrecisionModel with a default precision of FLOATING.
PrecisionModel(PrecisionModel pm)
Copy constructor to create a new PrecisionModel from an existing one.
PrecisionModel(com.vividsolutions.jts.geom.PrecisionModel.Type modelType)
Creates a PrecisionModel that specifies an explicit precision model type.
PrecisionModel(double scale)
Creates a PrecisionModel that specifies Fixed precision.
PrecisionModel(double scale, double offsetX, double offsetY)
Deprecated. offsets are no longer supported, since internal representation is rounded floating point

Method Summary

int
compareTo(Object o)
Compares this PrecisionModel object with the specified object for order.
boolean
equals(Object other)
int
getMaximumSignificantDigits()
Returns the maximum number of significant digits provided by this precision model.
double
getOffsetX()
Deprecated. Offsets are no longer used
double
getOffsetY()
Deprecated. Offsets are no longer used
double
getScale()
Returns the multiplying factor used to obtain a precise coordinate.
com.vividsolutions.jts.geom.PrecisionModel.Type
getType()
Gets the type of this PrecisionModel
boolean
isFloating()
Tests whether the precision model supports floating point
void
makePrecise(Coordinate coord)
Rounds a Coordinate to the PrecisionModel grid.
double
makePrecise(double val)
Rounds a numeric value to the PrecisionModel grid.
Coordinate
toExternal(Coordinate internal)
Deprecated. no longer needed, since internal representation is same as external representation
void
toExternal(Coordinate internal, Coordinate external)
Deprecated. no longer needed, since internal representation is same as external representation
Coordinate
toInternal(Coordinate external)
Deprecated. use makePrecise instead
void
toInternal(Coordinate external, Coordinate internal)
Deprecated. use makePrecise instead
String
toString()

Field Details

FIXED

public static final com.vividsolutions.jts.geom.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 com.vividsolutions.jts.geom.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 com.vividsolutions.jts.geom.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.
Field Value:
2.147483647E9

Constructor Details

PrecisionModel

public PrecisionModel()
Creates a PrecisionModel with a default precision of FLOATING.

PrecisionModel

public PrecisionModel(PrecisionModel pm)
Copy constructor to create a new PrecisionModel from an existing one.

PrecisionModel

public PrecisionModel(com.vividsolutions.jts.geom.PrecisionModel.Type modelType)
Creates a PrecisionModel 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)
Creates a PrecisionModel 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(double scale,
                      double offsetX,
                      double offsetY)

Deprecated. offsets are no longer supported, since internal representation is rounded floating point

Creates a PrecisionModel 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
offsetX - not used.
offsetY - not used.

Method Details

compareTo

public int compareTo(Object o)
Compares this PrecisionModel 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 the getMaximumSignificantDigits) 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. @param o the PrecisionModel with which this PrecisionModel is being compared @return a negative integer, zero, or a positive integer as this PrecisionModel is less than, equal to, or greater than the specified PrecisionModel

equals

public boolean equals(Object other)

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 precise values.
Returns:
the maximum number of decimal places provided by this precision model

getOffsetX

public double getOffsetX()

Deprecated. Offsets are no longer used

Returns 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 used

Returns the y-offset used to obtain a precise coordinate.
Returns:
the amount by which to subtract the y-coordinate before multiplying by the scale

getScale

public double getScale()
Returns the multiplying factor used to obtain a precise coordinate. This method is private because PrecisionModel is intended to be an immutable (value) type.
Returns:
the amount by which to multiply a coordinate after subtracting the offset

getType

public com.vividsolutions.jts.geom.PrecisionModel.Type getType()
Gets the type of this PrecisionModel
Returns:
the type of this PrecisionModel

isFloating

public boolean isFloating()
Tests whether the precision model supports floating point
Returns:
true if the precision model supports floating point

makePrecise

public void makePrecise(Coordinate coord)
Rounds a Coordinate to the PrecisionModel grid.

makePrecise

public double makePrecise(double val)
Rounds a numeric value to the PrecisionModel grid. Symmetric Arithmetic Rounding is used, to provide uniform rounding behaviour no matter where the number is on the number line.

Note: Java's Math#rint uses the "banker's rounding" algorithm, which is not suitable for precision operations elsewhere in JTS.


toExternal

public Coordinate toExternal(Coordinate internal)

Deprecated. no longer needed, since internal representation is same as external representation

Returns the external representation of internal.
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 representation

Sets external to the external representation of internal .
Parameters:
internal - the original coordinate
external - the coordinate whose values will be changed to the external representation of internal

toInternal

public Coordinate toInternal(Coordinate external)

Deprecated. use makePrecise instead

Returns the precise representation of external.
Parameters:
external - the original coordinate
Returns:
the coordinate whose values will be changed to the precise representation of external

toInternal

public void toInternal(Coordinate external,
                       Coordinate internal)

Deprecated. use makePrecise instead

Sets internal to the precise representation of external.
Parameters:
external - the original coordinate
internal - the coordinate whose values will be changed to the precise representation of external

toString

public String toString()