geos::geom::PrecisionModel Class Reference

Specifies the precision model of the Coordinate in a Geometry. More...

`#include <geos.h>`

## Public Types

enum | Type { FIXED , FLOATING , FLOATING_SINGLE }
| The types of Precision Model which GEOS supports. More...

## Public Member Functions

| PrecisionModel (void)
| Creates a PrecisionModel with a default precision of FLOATING.
| PrecisionModel (Type nModelType)
| PrecisionModel (double newScale, double newOffsetX, double newOffsetY)
| Creates a `PrecisionModel` with Fixed precision.
| PrecisionModel (double newScale)
| Creates a PrecisionModel with Fixed precision.
double | makePrecise (double val) const
| Rounds a numeric value to the PrecisionModel grid.
void | makePrecise (CoordinateXY &coord) const
| Rounds the given Coordinate to the PrecisionModel grid.
void | makePrecise (CoordinateXY *coord) const
bool | isFloating () const
int | getMaximumSignificantDigits () const
| Returns the maximum number of significant digits provided by this precision model.
Type | getType () const
double | getScale () const
| Returns the multiplying factor used to obtain a precise coordinate.
double | getGridSize () const
double | getOffsetX () const
double | getOffsetY () const
std::string | toString () const
int | compareTo (const PrecisionModel *other) const
| Compares this PrecisionModel object with the specified object for order.

## Static Public Attributes

static const double | maximumPreciseValue

## Detailed Description

Specifies the precision model of the Coordinate in a Geometry.

In other words, specifies the grid of allowable points for a `Geometry`. A precision model may be floating (PrecisionModel::Type::FLOATING or PrecisionModel::Type::FLOATING_SINGLE), in which case normal floating-point value semantics apply.

For a PrecisionModel::Type::FIXED precision model the makePrecise(geom::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. 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.

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

It is also supported to specify a precise grid size by providing it as a negative scale factor. For example, to specify rounding to the nearest 1000 use a scale factor of -1000.

Coordinates are represented internally as Java double-precision values. Java uses the IEEE-394 floating point standard, which provides 53 bits of precision. (Thus the maximum precisely representable integer is 9,007,199,254,740,992).

## Member Enumeration Documentation

## Type

enum geos::geom::PrecisionModel::Type

The types of Precision Model which GEOS supports.

Enumerator
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 | Floating precision corresponds to the standard Java double-precision floating-point representation, which is based on the IEEE-754 standard
FLOATING_SINGLE | Floating single precision corresponds to the standard Java single-precision floating-point representation, which is based on the IEEE-754 standard

## Constructor & Destructor Documentation

## PrecisionModel() [1/3]

geos::geom::PrecisionModel::PrecisionModel | ( | Type | nModelType | ) |

Creates a PrecisionModel specifying an explicit precision model type.

If the model type is FIXED the scale factor will default to 1.

Parameters

  nModelType | the type of the precision model

## PrecisionModel() [2/3]

geos::geom::PrecisionModel::PrecisionModel | ( | double | newScale,
|  | double | newOffsetX,
|  | double | newOffsetY )

Creates a `PrecisionModel` with Fixed precision.

Fixed-precision coordinates are represented as precise internal coordinates, which are rounded to the grid defined by the scale factor.

Parameters

  newScale | amount by which to multiply a coordinate after subtracting the offset, to obtain a precise coordinate
  newOffsetX | not used.
  newOffsetY | not used.

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

## PrecisionModel() [3/3]

geos::geom::PrecisionModel::PrecisionModel | ( | double | newScale | ) |

Creates a PrecisionModel with Fixed precision.

Fixed-precision coordinates are represented as precise internal coordinates which are rounded to the grid defined by the scale factor. The provided scale may be negative, to specify an exact grid size. The scale is then computed as the reciprocal.

Parameters

  newScale | amount by which to multiply a coordinate after subtracting the offset, to obtain a precise coordinate. Must be non-zero.

## Member Function Documentation

## compareTo()

int geos::geom::PrecisionModel::compareTo | ( | const PrecisionModel * | other | ) | const

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.

Parameters

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

References PrecisionModel().

## getGridSize()

double geos::geom::PrecisionModel::getGridSize | ( |  | ) | const

inline

Computes the grid size for a fixed precision model. This is equal to the reciprocal of the scale factor. If the grid size has been set explicitly (via a negative scale factor) it will be returned.

Returns
  the grid size at a fixed precision scale.

References isFloating().

## getMaximumSignificantDigits()

int geos::geom::PrecisionModel::getMaximumSignificantDigits | ( |  | ) | const

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

double geos::geom::PrecisionModel::getOffsetX | ( |  | ) | const

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

Deprecated
  Offsets are no longer used

## getOffsetY()

double geos::geom::PrecisionModel::getOffsetY | ( |  | ) | const

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

Deprecated
  Offsets are no longer used

## getType()

Type geos::geom::PrecisionModel::getType | ( |  | ) | const

inline

Gets the type of this PrecisionModel

Returns
  the type of this PrecisionModel

## isFloating()

bool geos::geom::PrecisionModel::isFloating | ( |  | ) | const

Tests whether the precision model supports floating point

Returns
  `true` if the precision model supports floating point

Referenced by getGridSize().

## makePrecise()

double geos::geom::PrecisionModel::makePrecise | ( | double | val | ) | const

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.

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

Referenced by makePrecise().

## Member Data Documentation

## maximumPreciseValue

const double geos::geom::PrecisionModel::maximumPreciseValue

static

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.

The documentation for this class was generated from the following file:

- PrecisionModel.h