Angle Units

Angle units and conversions. More...

Collaboration diagram for Angle Units:

Files
file	angle.scad
	Angle units and conversions.

Shorts
Convenience wrappers around angle that fix the from unit to a named unit. The to parameter defaults to angle_unit_base and may be overridden when a non-default target unit is needed. Use angle directly when the source unit is also non-default.
function	a_deg (a, to=angle_unit_base)
	Shorthand angle conversion for degrees. More...
function	a_rad (a, to=angle_unit_base)
	Shorthand angle conversion for radians. More...

Functions and/or Modules
function	angle_unit_name (u=angle_unit_default)
	Return the name of an angle unit identifier. More...
function	angle (a, from=angle_unit_default, to=angle_unit_base)
	Convert an angle value from one unit to another. More...
function	angle_inv (a, from=angle_unit_base, to=angle_unit_default)
	Convert an angle value from one unit to another (direction-swapped defaults). More...

Variables
	angle_unit_base = "d"
	angle_unit_default = "d"

Usage Details

Angle units and conversions.

Validation Summary

file	group	script	results	no test	skipped	passed	failed	warning
units/angle.scad	Angle Units	Script	Results	3	0	0	0	0

No Failures

See complete validation results.

Requires:
include <omdl-base.scad>;

Conventions

Parameter naming

• a is the angle value to convert. It has no default and must always be supplied by the caller. It may be a scalar for "r" or "d", or a 3-element list for "dms"; the required type depends on the source unit.
• from identifies the source unit; defaults to angle_unit_default.
• to identifies the target unit; defaults to angle_unit_base.
• u is a unit-identifier string used in name-lookup functions; defaults to angle_unit_default.

Return values

• All functions return undef for unrecognised unit identifiers. Callers are responsible for testing return values when inputs may be dynamic.
• The return type matches the target unit: a scalar for "r" or "d", and a 3-element list for "dms".

DMS format

• The "dms" (degree, minute, second) type is represented as a 3-element list [degrees, minutes, seconds].
• The sign of the angle is carried exclusively by the degrees component. The minutes and seconds components are always non-negative. For example, −30°15′20″ is encoded as [-30, 15, 20].
• Supplying a "dms" value with mixed signs (e.g. [-30,-15,0]) is not supported and produces undefined results.

Global configuration

• angle_unit_base sets the storage base unit for the entire design. It defaults to "d" and is intended to be overridden at the top of a design file or within a child scope before any angle function is called.
• angle_unit_default sets the assumed input unit when from or u is not specified. It also defaults to "d".
• Both variables must be assigned before any angle function is called; changing them after dependent assignments have already been evaluated has no effect on those prior results.

Unit identifiers

• Unit identifier strings are case-sensitive and lowercase (e.g. "r", "d", "dms").

Shorthand functions

• The a_deg() and a_rad() helpers are convenience wrappers that fix from to their named unit. The to parameter defaults to angle_unit_base and may be overridden when a non-default target unit is needed.

These functions allow for angles to be specified with units. Angles specified with units are independent of (angle_unit_base). There are also unit conversion functions for converting from one unit to another.

The table below enumerates the supported units.

units id	description	type
r	radian	decimal
d	degree	decimal
dms	degree, minute, second	decimal-list-3

Angle base unit example script

    include <omdl-base.scad>;
 
    angle_unit_base = "d";
    angle_unit_default = "r";
 
    // get unit names
    bu = angle_unit_name(angle_unit_base);
    du = angle_unit_name();
 
    // absolute angle measurements in base unit.
    c1 = angle(pi/6);
    c2 = angle(pi/4);
    c3 = angle(180, "d");
    c4 = angle([30, 15, 50], "dms");
 
    // convert between units.
    c5 = angle([30, 15, 50], from="dms", to="r");
    c6 = angle(0.528205, to="dms");
 
    // end_include

angle_unit_base=r script output

ECHO: bu = "radian"
ECHO: du = "radian"
ECHO: 
ECHO: c1 = 0.523599
ECHO: c2 = 0.785398
ECHO: c3 = 3.14159
ECHO: c4 = 0.528205
ECHO: c5 = 0.528205
ECHO: c6 = [30, 15, 50.102]

angle_unit_base=d script output

ECHO: bu = "degree"
ECHO: du = "radian"
ECHO: 
ECHO: c1 = 30
ECHO: c2 = 45
ECHO: c3 = 180
ECHO: c4 = 30.2639
ECHO: c5 = 0.528205
ECHO: c6 = [30, 15, 50.102]

angle_unit_base=dms script output

ECHO: bu = "degree, minute, second"
ECHO: du = "radian"
ECHO: 
ECHO: c1 = [29, 59, 60]
ECHO: c2 = [45, 0, 0]
ECHO: c3 = [180, 0, 0]
ECHO: c4 = [30, 15, 50]
ECHO: c5 = 0.528205
ECHO: c6 = [30, 15, 50.102]

Function and/or Module Documentation

angle_unit_name()

function angle_unit_name

(

u

= angle_unit_default

)

Return the name of an angle unit identifier.

Parameters

u	<string> An angle unit identifier.

Returns

<string> The units name for the given angle unit identifier. Returns undef for identifiers that are not defined.

angle()

function angle	(	a	,
		from	= angle_unit_default,
		to	= angle_unit_base
	)

Convert an angle value from one unit to another.

Parameters

a	<decimal | decimal-list-3> The angle to convert.
from	<string> The units of the angle to be converted. Defaults to angle_unit_default.
to	<string> The units to which the angle should be converted. Defaults to angle_unit_base. Conversion to "d" is short-circuited: the intermediate d to step is skipped.

Returns

<decimal | decimal-list-3> The conversion result. Return type is a scalar for "r" or "d", and a 3-element list for "dms". Returns undef for identifiers that are not defined.

Here is the caller graph for this function:

angle_inv()

function angle_inv	(	a	,
		from	= angle_unit_base,
		to	= angle_unit_default
	)

Convert an angle value from one unit to another (direction-swapped defaults).

Parameters

a	<decimal | decimal-list-3> The angle to convert.
from	<string> The units of the angle to be converted. Defaults to angle_unit_base.
to	<string> The units to which the angle should be converted. Defaults to angle_unit_default.

Returns

<decimal | decimal-list-3> The conversion result. Return type is a scalar for "r" or "d", and a 3-element list for "dms". Returns undef for identifiers that are not defined.

Note

This is a convenience alias for angle with from and to defaults swapped. It is useful when the natural direction of a design is from the base unit back to a display or input unit.

a_deg()

function a_deg	(	a	,
		to	= angle_unit_base
	)

Shorthand angle conversion for degrees.

Parameters

a	<decimal> The angle to convert.
to	<string> The units to which the angle should be converted. Defaults to angle_unit_base.

Returns

<decimal> The conversion result.

a_rad()

function a_rad	(	a	,
		to	= angle_unit_base
	)

Shorthand angle conversion for radians.

Parameters

a	<decimal> The angle to convert.
to	<string> The units to which the angle should be converted. Defaults to angle_unit_base.

Returns

<decimal> The conversion result.

Variable Documentation

angle_unit_base

angle_unit_base = "d"

<string> The base units for value storage.

Note

This variable is intended to be overridden at the top of a design file or in a child scope. All angle functions that omit the to parameter will convert to this unit.

Definition at line 741 of file angle.scad.

angle_unit_default

angle_unit_default = "d"

<string> The default units when unspecified.

Note

This variable is intended to be overridden at the top of a design file or in a child scope. All angle functions that omit the from or u parameter will assume this unit.

Definition at line 747 of file angle.scad.