agi.foundation

(agi.foundation.core-2024r3.jar)

Class Trig

java.lang.Object

agi.foundation.Trig

public final class Trig
extends Object

Provides functions and constants which are useful when working with angles and solving problems related to trigonometry.

Field Summary

Fields

Modifier and Type	Field and Description
static double	AngleEpsilon Represents the smallest positive angle greater than zero for which the Math.cos(double) function will produce a distinct value.

Method Summary

Modifier and Type	Method and Description
static boolean	areAnglesEquivalent(double firstAngle, double secondAngle, double tolerance) Checks to see whether the two given angles represent the same direction in the unit circle, regardless of any multiples of Constants.TwoPi.
static double	degreesMinutesSecondsToRadians(DegreesMinutesSeconds dms) Converts the specified number of revolutions, degrees, minutes, and seconds to radians.
static double	degreesMinutesSecondsToRadians(int revolutions, int degrees, int minutes, double seconds) Converts the specified number of revolutions, degrees, minutes, and seconds to radians.
static double	degreesToRadians(double angle) Converts degrees to radians.
static double	getSmallSpan(double startAngle, double stopAngle) Get the signed small span between two arbitrary angles, in radians.
static boolean	isAngleInRange(double minimum, double maximum, double angle) Checks to see if an angle is within the indicated range of values.
static double	negativePiToPi(double angle) Produces an angle in the range -π < angle <= π which is equivalent to the provided angle.
static double	putAngleInRange(double minimum, double maximum, double angle) Attempts to put an angle within the indicated range of values.
static double	radiansToDegrees(double angle) Converts radians to degrees.
static DegreesMinutesSeconds	radiansToDegreesMinutesSeconds(double radians) Converts the specified angle in radians to revolutions, degrees, minutes, and seconds.
static boolean	tryPutAngleInRange(double minimum, double maximum, double angle, double[] result) Attempts to put an angle within the indicated range of values.
static double	zeroToTwoPi(double angle) Produces an angle in the range 0 <= angle < 2π which is equivalent to the provided angle.

Methods inherited from class java.lang.Object

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

Field Detail

AngleEpsilon

public static final double AngleEpsilon

Represents the smallest positive angle greater than zero for which the Math.cos(double) function will produce a distinct value.

For angles smaller than this value, the Math.cos(double) function returns 1.0.

See Also:

Constant Field Values

Method Detail

degreesToRadians

public static double degreesToRadians(double angle)

Converts degrees to radians.

Parameters:

angle - The angle to convert in degrees.

Returns:

The corresponding angle in radians.

radiansToDegrees

public static double radiansToDegrees(double angle)

Converts radians to degrees.

Parameters:

angle - The angle to convert in radians.

Returns:

The corresponding angle in degrees.

degreesMinutesSecondsToRadians

public static double degreesMinutesSecondsToRadians(int revolutions,
                                                    int degrees,
                                                    int minutes,
                                                    double seconds)

Converts the specified number of revolutions, degrees, minutes, and seconds to radians.

Parameters:

revolutions - The number of complete (360 degree) revolutions.

degrees - The number of degrees.

minutes - The number of minutes.

seconds - The number of seconds.

Returns:

The corresponding angle in radians.

degreesMinutesSecondsToRadians

public static double degreesMinutesSecondsToRadians(@Nonnull
                                                    DegreesMinutesSeconds dms)

Converts the specified number of revolutions, degrees, minutes, and seconds to radians.

Parameters:

dms - The DegreesMinutesSeconds to be converted to radians.

Returns:

The corresponding angle in radians.

radiansToDegreesMinutesSeconds

@Nonnull
public static DegreesMinutesSeconds radiansToDegreesMinutesSeconds(double radians)

Converts the specified angle in radians to revolutions, degrees, minutes, and seconds.

Parameters:

radians - The angle in radians

Returns:

The corresponding angle in DMS.

zeroToTwoPi

public static double zeroToTwoPi(double angle)

Produces an angle in the range 0 <= angle < 2π which is equivalent to the provided angle.

Parameters:

angle - The angle to be adjusted.

Returns:

The adjusted angle.

negativePiToPi

public static double negativePiToPi(double angle)

Produces an angle in the range -π < angle <= π which is equivalent to the provided angle.

Parameters:

angle - The angle to be adjusted.

Returns:

The adjusted angle.

tryPutAngleInRange

public static boolean tryPutAngleInRange(double minimum,
                                         double maximum,
                                         double angle,
                                         @Nonnull
                                         double[] result)

Attempts to put an angle within the indicated range of values.

The range of values is considered to be an open interval and therefore does not include the actual minimum and maximum values.

Parameters:

minimum - The minimum angle value.

maximum - The maximum angle value.

angle - The angle value being checked.

result - On input, an array with one element. On return, the array is populated with the final angle value after attempting to place it within the indicated range.

Returns:

true if result is within the indicated range of values; otherwise false.

See Also:

Trig.isAngleInRange(double, double, double), Trig.putAngleInRange(double, double, double)

isAngleInRange

public static boolean isAngleInRange(double minimum,
                                     double maximum,
                                     double angle)

Checks to see if an angle is within the indicated range of values.

The range of values is considered to be an open interval and therefore does not include the actual minimum and maximum values.

Parameters:

minimum - The minimum angle value.

maximum - The maximum angle value.

angle - The angle value being checked.

Returns:

true if angle is within the indicated range of values; otherwise false.

See Also:

Trig.putAngleInRange(double, double, double), Trig.tryPutAngleInRange(double, double, double, double[])

putAngleInRange

public static double putAngleInRange(double minimum,
                                     double maximum,
                                     double angle)

Attempts to put an angle within the indicated range of values.

The range of values is considered to be an open interval and therefore does not include the actual minimum and maximum values.

Parameters:

minimum - The minimum angle value.

maximum - The maximum angle value.

angle - The angle value being checked.

Returns:

The final angle value after attempting to place it within the indicated range.

Throws:

ArgumentOutOfRangeException - Thrown if the value of angle cannot be placed within the open interval defined by the specified minimum and maximum.

See Also:

Trig.isAngleInRange(double, double, double), Trig.tryPutAngleInRange(double, double, double, double[])

getSmallSpan

public static double getSmallSpan(double startAngle,
                                  double stopAngle)

Get the signed small span between two arbitrary angles, in radians. This will return the angle in radians between -π and π representing the angular distance between the two given angles. It will remove the effect of 'winding' and compare the angular distance on the unit circle.

As an example, if startAngle is 1.0 and stopAngle is 2π, then the simple difference will be 2π - 1.0 and the "small span" would be -1.0.

Parameters:

startAngle - The first angle, in radians.

stopAngle - The second angle, in radians.

Returns:

The signed small span between the two angles, in radians.

areAnglesEquivalent

public static boolean areAnglesEquivalent(double firstAngle,
                                          double secondAngle,
                                          double tolerance)

Checks to see whether the two given angles represent the same direction in the unit circle, regardless of any multiples of Constants.TwoPi.

Parameters:

firstAngle - The first angle to check, in radians.

secondAngle - The second angle to check, in radians.

tolerance - The tolerance to use when comparing the two angles, in radians.

Returns:

True if the two angles represent the same angular direction in the unit circle.