Angle Mathematics & Trigonometry

/**
 * Converts angle from radians to degrees
 * @param theta - Angle in radians
 * @returns Angle in degrees
 */
function deg(theta: number): number;

/**
 * Converts angle from degrees to radians
 * @param theta - Angle in degrees
 * @returns Angle in radians
 */
function rad(theta: number): number;

/**
 * Converts angle from DMS (degrees, minutes, seconds) to decimal degrees
 * @param deg - Degrees component
 * @param min - Minutes component (0-59)
 * @param sec - Seconds component (0-59)
 * @returns Decimal angle in degrees
 */
function fromDMS(deg: number, min: number, sec: number): number;

/**
 * Converts decimal angle to DMS format
 * @param theta - Decimal angle in degrees
 * @returns 3-tuple [degrees, minutes, seconds] with sign preserved in degrees
 */
function toDMS(theta: number): [number, number, number];

import { deg, rad, fromDMS, toDMS } from "@thi.ng/math/angle";

// Basic conversions
const degrees = deg(Math.PI); // 180
const radians = rad(90); // 1.5707...

// DMS conversions
const decimal = fromDMS(45, 30, 0); // 45.5 degrees
const dms = toDMS(45.75); // [45, 45, 0]

/**
 * Projects theta into [0, 2π] interval
 * @param theta - Input angle in radians
 * @returns Angle normalized to [0, 2π]
 */
function absTheta(theta: number): number;

/**
 * Returns smallest absolute angle difference between a and b
 * Result will be in [0, π] interval
 * @param a - First angle in radians
 * @param b - Second angle in radians
 * @returns Smallest angle difference
 */
function angleDist(a: number, b: number): number;

/**
 * Like Math.atan2, but always returns angle in [0, TAU) interval
 * @param y - Y coordinate
 * @param x - X coordinate
 * @returns Absolute angle in [0, 2π] range
 */
function atan2Abs(y: number, x: number): number;

/**
 * Returns quadrant ID (0-3) of given angle
 * @param theta - Angle in radians
 * @returns Quadrant number: 0=I, 1=II, 2=III, 3=IV
 */
function quadrant(theta: number): number;

import { absTheta, angleDist, atan2Abs, quadrant } from "@thi.ng/math/angle";
import { PI } from "@thi.ng/math/api";

// Normalize to positive range
const normalized = absTheta(-PI / 4); // 7π/4

// Find shortest rotation between angles
const shortestPath = angleDist(PI / 6, 5 * PI / 6); // 2π/3

// Get absolute arctangent
const absAtan = atan2Abs(-1, 1); // 7π/4 instead of -π/4

// Determine quadrant
const quad = quadrant(3 * PI / 2); // 3 (fourth quadrant)

/**
 * Returns vector of [sin(theta)*n, cos(theta)*n]
 * @param theta - Angle in radians
 * @param n - Scale factor (default: 1)
 * @returns [sin*n, cos*n] tuple
 */
function sincos(theta: number, n?: number): [number, number];

/**
 * Returns vector of [cos(theta)*n, sin(theta)*n]
 * @param theta - Angle in radians
 * @param n - Scale factor (default: 1)
 * @returns [cos*n, sin*n] tuple
 */
function cossin(theta: number, n?: number): [number, number];

/**
 * Cosecant function: 1/sin(theta)
 * Approaches ±Infinity for theta near multiples of π
 * @param theta - Angle in radians
 * @returns Cosecant value
 */
function csc(theta: number): number;

/**
 * Secant function: 1/cos(theta)
 * Approaches ±Infinity for theta near π/2 ± nπ
 * @param theta - Angle in radians
 * @returns Secant value
 */
function sec(theta: number): number;

/**
 * Cotangent function: cos/sin
 * Approaches ±Infinity for theta near multiples of π
 * @param theta - Angle in radians
 * @returns Cotangent value
 */
function cot(theta: number): number;

/**
 * Approximates cos(xπ) for x in [-1, 1]
 * @param x - Normalized input [-1, 1]
 * @returns Approximate cosine value
 */
function normCos(x: number): number;

/**
 * Fast cosine approximation using polynomial
 * Maximum error ~0.00059693
 * @param theta - Angle in radians
 * @returns Approximate cosine value
 */
function fastCos(theta: number): number;

/**
 * Fast sine approximation using fastCos
 * @param theta - Angle in radians
 * @returns Approximate sine value
 */
function fastSin(theta: number): number;

import { sincos, fastCos, fastSin, csc } from "@thi.ng/math/angle";

// Simultaneous sin/cos calculation (more efficient)
const [s, c] = sincos(Math.PI / 4); // [0.707..., 0.707...]

// Fast approximations for performance-critical code
const approxCos = fastCos(1.5); // Fast but less accurate
const approxSin = fastSin(1.5);

// Extended trigonometric functions
const cosecant = csc(Math.PI / 6); // 2

/**
 * Law of Cosines: calculates third side of triangle
 * @param a - Length of first side
 * @param b - Length of second side
 * @param gamma - Inner angle between sides a and b (in radians)
 * @returns Length of third side
 */
function loc(a: number, b: number, gamma: number): number;

import { loc } from "@thi.ng/math/angle";
import { PI } from "@thi.ng/math/api";

// Triangle with sides 3, 4 and 90° angle between them
const hypotenuse = loc(3, 4, PI / 2); // 5 (Pythagorean theorem)

// General triangle calculation
const thirdSide = loc(7, 10, PI / 3); // Side opposite to 60° angle