com.vividsolutions.jts.geom

Class PrecisionModel

java.lang.Object

com.vividsolutions.jts.geom.PrecisionModel

All Implemented Interfaces:

Serializable, Comparable

public class PrecisionModel
extends 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(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

For example, to specify 3 decimal places of precision, use a scale factor of 1000. To specify -3 decimal places of precision (i.e. rounding to the nearest 1000), use a scale factor of 0.001.

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 and Description
static class	PrecisionModel.Type The types of Precision Model which JTS supports.

Field Summary

Fields

Modifier and Type	Field and 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 standard
static 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

Constructors

Constructor and Description
PrecisionModel() Creates a PrecisionModel with a default precision of FLOATING.
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
PrecisionModel(PrecisionModel.Type modelType) Creates a PrecisionModel that specifies an explicit precision model type.
PrecisionModel(PrecisionModel pm) Copy constructor to create a new PrecisionModel from an existing one.

Method Summary

Methods

Modifier and Type	Method and Description
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 scale factor used to specify a fixed precision model.
PrecisionModel.Type	getType() Gets the type of this precision model
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.
static PrecisionModel	mostPrecise(PrecisionModel pm1, PrecisionModel pm2) Determines which of two PrecisionModels 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 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()

Methods inherited from class java.lang.Object

clone, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

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 a PrecisionModel with a default precision of FLOATING.

PrecisionModel

public PrecisionModel(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,
              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.

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(PrecisionModel pm)

Copy constructor to create a new PrecisionModel from an existing one.

Method Detail

mostPrecise

public static PrecisionModel mostPrecise(PrecisionModel pm1,
                         PrecisionModel pm2)

Determines which of two PrecisionModels is the most precise (allows the greatest number of significant digits).

Parameters:

pm1 - a PrecisionModel

pm2 - 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 as WKTWriter).

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

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

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

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

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 String toString()

Overrides:

toString in class Object

equals

public boolean equals(Object other)

Overrides:

equals in class Object

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.

Specified by:

compareTo in interface Comparable

Parameters:

o - the PrecisionModel with which this PrecisionModel is being compared

Returns:

a negative integer, zero, or a positive integer as this PrecisionModel is less than, equal to, or greater than the specified PrecisionModel