Class PrecisionUtil


  • public class PrecisionUtil
    extends java.lang.Object
    Functions for computing precision model scale factors that ensure robust geometry operations. In particular, these can be used to automatically determine appropriate scale factors for operations using limited-precision noding (such as OverlayNG).

    WARNING: the inherentScale and robustScale functions can be very slow, due to the method used to determine number of decimal places of a number. These are not recommended for production use.

    Author:
    Martin Davis
    • Field Summary

      Fields 
      Modifier and Type Field Description
      static int MAX_ROBUST_DP_DIGITS
      A number of digits of precision which leaves some computational "headroom" to ensure robust evaluation of certain double-precision floating point geometric operations.
    • Constructor Summary

      Constructors 
      Constructor Description
      PrecisionUtil()  
    • Method Summary

      All Methods Static Methods Concrete Methods 
      Modifier and Type Method Description
      static double inherentScale​(double value)
      Computes the inherent scale of a number.
      static double inherentScale​(Geometry geom)
      Computes the inherent scale of a geometry.
      static double inherentScale​(Geometry a, Geometry b)
      Computes the inherent scale of two geometries.
      static PrecisionModel robustPM​(Geometry a)
      Determines a precision model to use for robust overlay operations for one geometry.
      static PrecisionModel robustPM​(Geometry a, Geometry b)
      Determines a precision model to use for robust overlay operations.
      static double robustScale​(Geometry a)
      Determines a scale factor which maximizes the digits of precision and is safe to use for overlay operations.
      static double robustScale​(Geometry a, Geometry b)
      Determines a scale factor which maximizes the digits of precision and is safe to use for overlay operations.
      static double safeScale​(double value)
      Computes a safe scale factor for a numeric value.
      static double safeScale​(Geometry geom)
      Computes a safe scale factor for a geometry.
      static double safeScale​(Geometry a, Geometry b)
      Computes a safe scale factor for two geometries.
      • Methods inherited from class java.lang.Object

        equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Field Detail

      • MAX_ROBUST_DP_DIGITS

        public static int MAX_ROBUST_DP_DIGITS
        A number of digits of precision which leaves some computational "headroom" to ensure robust evaluation of certain double-precision floating point geometric operations. This value should be less than the maximum decimal precision of double-precision values (16).
    • Constructor Detail

      • PrecisionUtil

        public PrecisionUtil()
    • Method Detail

      • robustPM

        public static PrecisionModel robustPM​(Geometry a,
                                              Geometry b)
        Determines a precision model to use for robust overlay operations. The precision scale factor is chosen to maximize output precision while avoiding round-off issues.

        NOTE: this is a heuristic determination, so is not guaranteed to eliminate precision issues.

        WARNING: this is very slow.

        Parameters:
        a - a geometry
        b - a geometry
        Returns:
        a suitable precision model for overlay
      • safeScale

        public static double safeScale​(double value)
        Computes a safe scale factor for a numeric value. A safe scale factor ensures that rounded number has no more than MAX_ROBUST_DP_DIGITS digits of precision.
        Parameters:
        value - a numeric value
        Returns:
        a safe scale factor for the value
      • safeScale

        public static double safeScale​(Geometry geom)
        Computes a safe scale factor for a geometry. A safe scale factor ensures that the rounded ordinates have no more than MAX_ROBUST_DP_DIGITS digits of precision.
        Parameters:
        geom - a geometry
        Returns:
        a safe scale factor for the geometry ordinates
      • safeScale

        public static double safeScale​(Geometry a,
                                       Geometry b)
        Computes a safe scale factor for two geometries. A safe scale factor ensures that the rounded ordinates have no more than MAX_ROBUST_DP_DIGITS digits of precision.
        Parameters:
        a - a geometry
        b - a geometry (which may be null)
        Returns:
        a safe scale factor for the geometry ordinates
      • inherentScale

        public static double inherentScale​(double value)
        Computes the inherent scale of a number. The inherent scale is the scale factor for rounding which preserves all digits of precision (significant digits) present in the numeric value. In other words, it is the scale factor which does not change the numeric value when rounded:
           num = round( num, inherentScale(num) )
         
        Parameters:
        value - a number
        Returns:
        the inherent scale factor of the number
      • inherentScale

        public static double inherentScale​(Geometry geom)
        Computes the inherent scale of a geometry. The inherent scale is the scale factor for rounding which preserves all digits of precision (significant digits) present in the geometry ordinates.

        This is the maximum inherent scale of all ordinate values in the geometry.

        WARNING: this is very slow.

        Parameters:
        geom - geometry
        Returns:
        inherent scale of a geometry
      • inherentScale

        public static double inherentScale​(Geometry a,
                                           Geometry b)
        Computes the inherent scale of two geometries. The inherent scale is the scale factor for rounding which preserves all digits of precision (significant digits) present in the geometry ordinates.

        This is the maximum inherent scale of all ordinate values in the geometries.

        WARNING: this is very slow.

        Parameters:
        a - a geometry
        b - a geometry
        Returns:
        the inherent scale factor of the two geometries
      • robustPM

        public static PrecisionModel robustPM​(Geometry a)
        Determines a precision model to use for robust overlay operations for one geometry. The precision scale factor is chosen to maximize output precision while avoiding round-off issues.

        NOTE: this is a heuristic determination, so is not guaranteed to eliminate precision issues.

        WARNING: this is very slow.

        Parameters:
        a - a geometry
        Returns:
        a suitable precision model for overlay
      • robustScale

        public static double robustScale​(Geometry a,
                                         Geometry b)
        Determines a scale factor which maximizes the digits of precision and is safe to use for overlay operations. The robust scale is the minimum of the inherent scale and the safe scale factors.

        WARNING: this is very slow.

        Parameters:
        a - a geometry
        b - a geometry
        Returns:
        a scale factor for use in overlay operations
      • robustScale

        public static double robustScale​(Geometry a)
        Determines a scale factor which maximizes the digits of precision and is safe to use for overlay operations. The robust scale is the minimum of the inherent scale and the safe scale factors.
        Parameters:
        a - a geometry
        Returns:
        a scale factor for use in overlay operations