Download the PHP package marcoconsiglio/goniometry without Composer

goniometry

A PHP support for string, decimal, radian and object angles, providing goniometric algebra and comparison between angles.

Index

• Requirements
• Installation
• Quick Start
• Usage
  • Creating an AngularMeasure object
  • Sexagesimal (int degrees, int minutes, float seconds, Rotation direction)
  • Sexagesimal string
  • Sexadecimal float
  • Radian float
  • Getting angle values
  • Rotation direction
  • Opposite direction
  • Casting
  • To sexadecimal (float)
  • To sexadecimal (object)
  • To radian (float)
  • To string
  • Comparison
  • $\alpha \gt \beta$ (greater than)
  • $\alpha \ge \beta$ (greater than or equal)
  • $\alpha \lt \beta$ (less than)
  • $\alpha \le \beta$ (less than or equal)
  • $\alpha \cong \beta$ (equal)
  • $\alpha \ncong \beta$ (different)
  • Fuzzy Comparison
  • $\alpha \approxeq \beta$ (almost equal)
  • Algebraic sum between two angles
  • Relative sum
  • Absolute sum
• FakerPHP support
• API documentation

Requirements

• PHP v8.4+
• BC Math PHP extension

  Installation

  composer require marcoconsiglio/goniometry

  Quick Start

  Import this class to represent angles.

Create an Angle object (-360°/+360°).

Create an AngularDistance object (-180°/+180°).

Both Angle and AngularDistance are AngularMeasure types that implement the Angle interface.

Usage

Creating an AngularMeasure object

Sexagesimal (int degrees, int minutes, float seconds, Rotation direction)

This creates an angle from its values in degrees, minutes and seconds:

Rotation::COUNTER_CLOCKWISE is the plus sign, Rotation::CLOCKWISE is the minus sign.

A null angle (exactly $0^\circ\space0'\space0"$) will always have a Rotation::COUNTER_CLOCKWISE.

Sexagesimal (string)

This creates an angle from its textual representation:

This is possible thanks to the regular expressions

These regex expressions treat degrees and minutes as int type, but seconds are treated as a float type.

You can create a negative Angle if the string representation start with the minus (-) sign.

The NoMatchException is thrown when you try to create an AngularMeasure with a bad formatted string.

Sexadecimal (float)

This create an angle from its decimal representation:

Radian (float)

This create an angle from its radian representation:

If you need a precise $\pi$ value, you can pass a Radian object constructed with the Number::π() static method that return the π constant with an arbitrary precision up to 54 digits.

The Radian class extend the ModularNumber class, whose API is documented in marcoconsiglio/modular-arithmetic.

For more info on Number::π() check the API of marcoconsiglio/bcmath-extended.

Getting angle values

You can obtain sexagesimal values separated in an array (simple by default, or associative):

The angle's direction determines the sign of the degrees value.

There are read-only properties too:

The Degrees, Minutes, and Seconds classes extends ModularNumber, whose API is documented in marcoconsiglio/modular-arithmetic.

You can cast Degrees, Minutes, and Seconds to string automatically putting their variables in a string.

Rotation direction

Positive angles are represented by the enum constant

while negative angles are represented by the opposite enum constant:

You can toggle the rotation direction:

Since the Angle instance is immutable, the toggleRotation() method returns a copy with the opposite sign.

You can check if an Angle is clockwise or counterclockwise.

Opposite direction

You can calc the opposite direction of an AngulaMeasure interface with the method oppositeDirection().

Absolute value

The absolute() method return a copy of the AngularMeasure without the negative sign.

Casting

To float sexadecimal degrees

You can cast the angle to float type, with optional precision up to PHP_FLOAT_DIG decimal places:

You can specify a precision up to PHP_FLOAT_DIG decimal places. If the number of decimal places is not set, PHP_FLOAT_DIG is used.

To SexadecimalDegrees type

If you need an arbitrary precision, you can obtain a SexadecimalDegrees instance representing the sexadecimal value of the angle.

The $value property is a Number object extending the BCMath\Number class, whose API is documented in marcoconsiglio/bcmath-extended.

The value() method cast the SexadecimalDegrees object to float. You can specify a precision up to PHP_FLOAT_DIG decimal places. If the number of decimal places is not set, PHP_FLOAT_DIG is used.

To float radian

You can cast the angle to radian (float), with optional precision up to PHP_FLOAT_DIG decimal places:

You can specify a precision up to PHP_FLOAT_DIG decimal places. If the number of decimal places is not set, PHP_FLOAT_DIG is used.

To string sexagesimal

You can cast the angle to a string representation:

WARNING! In this case, maximum precision is unknown. The Seconds class uses the BCMath extension behind the scenes. The seconds value is stored with arbitrary precision, so in some cases the number of seconds could potentially have many digits, making the string very long.

Comparison

You can compare an Angle or AngularDistance object against a sexadecimal or sexagesimal value.

Comparisons are performed with absolute values (congruent comparison) when comparing Angles, meaning that $-90^\circ\cong+90^\circ$, while are performed with relative values when comparing AngularDistances, meaning that $-90^\circ\ncong+90^\circ$

If you need a relative comparison for Angles, you should cast the angle to a sexadecimal float and then perform the arithmetic comparison, meaning that $-90.0^\circ\lt+90.0^\circ$, but you will lose the benefit of arbitrary precision math provided by BcMath extension.

Each comparison can be performed against

• a string angle (sexagesimal),
• an int (sexagesimal degrees),
• a float (sexadecimal degrees),
• or another instance implementing the Angle interface.

Comparisons via radian values ​​are not available.

You can specify an optional precision expressed as the number of decimal places used to round the angle value. The precision is only used when comparing against a float (sexadecimal).

$\alpha > \beta$ (greater than)

$\alpha ≧ \beta$ (greater than or equal)

$\alpha < \beta$ (less than)

$\alpha ≦ \beta$ (less than or equal)

$\alpha \cong \beta$ (equal)

$\alpha \ncong \beta$ (different)

Fuzzy Comparison

When comparing two Angles sometimes their difference is negligible. In this case you can use a fuzzy comparison specifing a delta error Angle within which the comparison will be succesful.

Delta (Δ) is the double of epsilon error (±ε).

$\alpha \approxeq \beta$ (almost equal)

Algebraic sum between two angles

You can sum two angles. An angle of type AngularDistance do not have the absSum() methods.

Relative sum

The relative sum can return both positive or negative angle.

Absolute sum

The absolute sum will always return a positive angle.

Relative distance

You can calculate the relative distance between two Angles.

FakerPHP support

This library provides support to FakerPHP through the WithAngleFaker trait. Here's a list of the available methods.

Check the API documentation to find out more info about these methods.

API documentation

You can read the code documentation in ./docs/html/index.html.