Package org.djutils.base

Class AngleUtil

java.lang.Object
org.djutils.base.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-2024 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 final double
    PI2
    The value 2π.

  • Method Summary

    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.

    Methods inherited from class java.lang.Object

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

  • Field Details

  • Method Details

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