Package org.djutils.base

Class AngleUtil

  • public final class AngleUtil
extends Object
    AngleUtil has some base methods to deal with angles, such as normalization between -PI and PI, and between 0 and 2*PI.

    Copyright (c) 2020-2021 Delft University of Technology, Jaffalaan 5, 2628 BX Delft, the Netherlands. All rights reserved. See for project information https://djutils.org. The DJUTILS project is distributed under a three-clause BSD-style license, which can be found at https://djutils.org/docs/license.html.
    Author:
    Alexander Verbraeck, Peter Knoppers

    • Field Summary

      Fields 
      Modifier and Type Field Description
      static double PI2
      The value 2π.

    • Method Summary

      All Methods Static Methods Concrete Methods 
      Modifier and Type Method Description
      static boolean epsilonEquals​(double angle1, double angle2, double epsilon)
      Return whether two angles (in radians) are less than epsilon apart.
      static double interpolateClockwise​(double angle1, double angle2, double fraction)
      Interpolate between two angles that will first be normalized between 0 and 2π, and take the interpolated angle when going clockwise from the first angle to the second angle.
      static double interpolateShortest​(double angle1, double angle2, double fraction)
      Interpolate between two angles taking the shortest way.
      static double normalizeAroundPi​(double angle)
      Normalize an angle (in radians) in a 2π wide interval around π, resulting in angles in the 0 to 2π interval.
      static double normalizeAroundZero​(double angle)
      Normalize an angle (in radians) in a 2π wide interval around 0, resulting in angles in the -π to π interval.

    • Method Detail

      • normalizeAroundPi

        public static double normalizeAroundPi​(double angle)
        Normalize an angle (in radians) in a 2π wide interval around π, resulting in angles in the 0 to 2π interval. An angle value of NaN or Infinity returns NaN.
        Parameters:
        angle - double; the angle in radians to normalize
        Returns:
        double; the normalized angle in radians

      • normalizeAroundZero

        public static double normalizeAroundZero​(double angle)
        Normalize an angle (in radians) in a 2π wide interval around 0, resulting in angles in the -π to π interval. An angle value of NaN or Infinity returns NaN.
        Parameters:
        angle - double; the angle in radians to normalize
        Returns:
        double; the normalized angle in radians

      • epsilonEquals

        public static boolean epsilonEquals​(double angle1,
                                    double angle2,
                                    double epsilon)
        Return whether two angles (in radians) are less than epsilon apart. The method returns true, for instance when epsilonEquals(-Math.PI, Math.PI, 1E-6) is called, since the -PI and +PI angles have the same angle.
        Parameters:
        angle1 - double; the first angle in radians
        angle2 - double; the second angle in radians
        epsilon - double; the precision
        Returns:
        whether the two angles are less than epsilon apart

      • interpolateClockwise

        public static double interpolateClockwise​(double angle1,
                                          double angle2,
                                          double fraction)
        Interpolate between two angles that will first be normalized between 0 and 2π, and take the interpolated angle when going clockwise from the first angle to the second angle. The fraction indicates where the angle between angle1 and angle2 will be. A fraction of 0.0 returns angle1, a fraction of 1.0 returns angle2, and a fraction of 0.5 returns the shortest angle halfway. A fraction of less than 0 or larger than 1 can be used for extrapolation. The resulting angle is normalized between -π and π. This means that the halfway interpolation between 0 and 2π and between 2π and 0 are both 0, since the two angles are the same. Likewise, the halfway interpolation between -π and π is +/- π where the sign depends on rounding.
        Parameters:
        angle1 - double; the first angle in radians
        angle2 - double; the second angle in radians
        fraction - double; the fraction for interpolation; 0.5 is halfway
        Returns:
        the normalized angle between angle1 and angle2

      • interpolateShortest

        public static double interpolateShortest​(double angle1,
                                         double angle2,
                                         double fraction)
        Interpolate between two angles taking the shortest way.
        Parameters:
        angle1 - double; the first angle in radians
        angle2 - double; the second angle in radians
        fraction - double; the fraction for interpolation; 0.5 is halfway, 0.0 returns angle1, 1.0 returns angle2.
        Returns:
        double; The interpolated angle, normalized around zero. If any input angle is not normalized around zero the result will still be normalized, and the exact equality at fraction is 0.0 or 1.0 may not hold. When the difference between angle1 and angle2 is very close to an odd multiple of PI, the shortest way between those angles is ill-defined. The result of this method reflects this (fundamental) problem.