Coordinates Systems

Coordinate systems and conversions. More...

Collaboration diagram for Coordinates Systems:

Files
file	coordinate.scad
	Coordinate systems and conversions.

Functions and/or Modules
function	coordinate_unit_name (s=coordinate_unit_default)
	Return the name of the given coordinate system identifier. More...
function	coordinate (c, from=coordinate_unit_default, to=coordinate_unit_base)
	Convert a point from one coordinate system to another. More...
function	coordinate_inv (c, from=coordinate_unit_base, to=coordinate_unit_default)
	Convert a point from one coordinate system to another (direction-swapped defaults). More...
function	coordinate_scale2d_cpc (c, r, t=false)
	Radially scale a list of 2d cartesian coordinates. More...
function	coordinate_scale2d_p2c (c, r, t=false)
	Radially scale and convert a list of 2d polar coordinates to cartesian. More...
function	coordinate_scale3d_csc (c, r, t=false)
	Spherically scale a list of 3d cartesian coordinates. More...
function	coordinate_scale3d_s2c (c, r, t=false)
	Spherically scale and convert a list of 3d spherical coordinates to cartesian. More...

Variables
	coordinate_unit_base = "c"
	coordinate_unit_default = "c"
	coordinate_positive_angle = true

Usage Details

Coordinate systems and conversions.

Validation Summary

file	group	script	results	no test	skipped	passed	failed	warning
units/coordinate.scad	Coordinates Systems	Script	Results	7	0	0	0	0

No Failures

See complete validation results.

Requires:
include <omdl-base.scad>;
include <units/coordinate.scad>;

Conventions

Parameter naming

• c is the coordinate point (or list of coordinate points for the scale utility functions) to convert. It has no default and must always be supplied by the caller. Its required dimensionality depends on the target or source system (see Dimension requirements below).
• from identifies the source coordinate system; defaults to coordinate_unit_default.
• to identifies the target coordinate system; defaults to coordinate_unit_base.
• s is the coordinate system identifier string used in coordinate_unit_name. It is distinct from c (a numeric point) in both type and role; defaults to coordinate_unit_default.
• r is a radial scale factor used in the scale utility functions.
• t is a boolean flag in the scale utility functions: true translates all points to exactly radius r; false scales each point's existing radius by r.

Return values

• All conversion functions return undef for unrecognised system identifiers, for input points of wrong dimensionality, or for inputs that are not valid points.

Dimension requirements

• "c" (cartesian) accepts both 2d [x,y] and 3d [x,y,z].
• "p" (polar) requires a 2d point [r,aa]; a 3d input returns undef.
• "y" (cylindrical) and "s" (spherical) require a 3d point; a 2d input returns undef.

Angular convention

• All angular components (aa, pa) are in degrees.
• The azimuthal angle aa is measured from the positive x-axis in the xy-plane. When coordinate_positive_angle is true, negative azimuthal results are shifted by +360° so that aa is always in [0°, 360°). This applies to polar, cylindrical, and spherical output.
• The polar angle pa (spherical only) is always in [0°, 180°] and is not affected by coordinate_positive_angle.
• When the input point is the origin [0,0,0], the polar angle pa is defined as 0° by convention.

Global configuration

• coordinate_unit_base sets the target system when to is omitted. Defaults to "c". Intended to be overridden at the top of a design file or child scope before any coordinate function is called.
• coordinate_unit_default sets the assumed source system when from or s is omitted. Defaults to "c".
• coordinate_positive_angle controls whether negative azimuthal angles are normalised to [0°, 360°). Defaults to true. Unlike coordinate_unit_base and coordinate_unit_default, this variable may be changed between individual calls to alter angle normalisation on a per-conversion basis.

These functions allow for geometric points in space to be specified using multiple coordinate systems. Some geometric calculations are specified more naturally in one or another coordinate system. These conversion functions allow for the movement between the most convenient for a particular application.

For more information see Wikipedia on coordinate system.

The table below enumerates the supported coordinate systems.

system id	description	dimensions	point convention
c	cartesian	2d or 3d	[x, y] or [x, y, z]
p	polar	2d	[r, aa]
y	cylindrical	3d	[r, aa, z]
s	spherical	3d	[r, aa, pa]

The symbols used in the convention column are as follows:

symbol	description	units	reference
x, y, z	coordinate distance	any	xyz-axis
r	radial distance	any	z-axis / xyz-origin
aa	azimuthal angle	degrees	positive x-axis
pa	polar / zenith angle	degrees	positive z-axis

Note

The azimuthal angle is a measure of the radial vector orthogonal projection onto the xy-plane measured from the positive x-axis. The polar angle is measured from the z-axis (zenith) to the radial vector.

Coordinate system base example script

    include <omdl-base.scad>;
    include <units/coordinate.scad>;
 
    coordinate_unit_base = "c";
    coordinate_unit_default = "p";
 
    // get unit names
    bu = coordinate_unit_name(coordinate_unit_base);
    du = coordinate_unit_name();
 
    // absolute coordinates in a specified coordinate system.
    c1 = coordinate([1, 1, 1], "c");
    c2 = coordinate([1, 180]);
    c3 = coordinate([1, 90, -1], "y");
    c4 = coordinate([1, 5, 50], "s");
 
    // convert between system.
    c5 = coordinate([10*sqrt(2), 45, 45], from="s", to="y");
    c6 = coordinate([sqrt(2), 45], to="c");
 
    // end_include

coordinate_unit_base=c script output

ECHO: bu = "cartesian"
ECHO: du = "polar"
ECHO: 
ECHO: c1 = [1, 1, 1]
ECHO: c2 = [-1, 0]
ECHO: c3 = [0, 1, -1]
ECHO: c4 = [0.763129, 0.0667652, 0.642788]
ECHO: c5 = [10, 45, 10]
ECHO: c6 = [1, 1]

coordinate_unit_base=p script output

ECHO: bu = "polar"
ECHO: du = "polar"
ECHO: 
ECHO: c1 = undef
ECHO: c2 = [1, 180]
ECHO: c3 = undef
ECHO: c4 = undef
ECHO: c5 = [10, 45, 10]
ECHO: c6 = [1, 1]

coordinate_unit_base=y script output

ECHO: bu = "cylindrical"
ECHO: du = "polar"
ECHO: 
ECHO: c1 = [1.41421, 45, 1]
ECHO: c2 = undef
ECHO: c3 = [1, 90, -1]
ECHO: c4 = [0.766044, 5, 0.642788]
ECHO: c5 = [10, 45, 10]
ECHO: c6 = [1, 1]

coordinate_unit_base=s script output

ECHO: bu = "spherical"
ECHO: du = "polar"
ECHO: 
ECHO: c1 = [1.73205, 45, 54.7356]
ECHO: c2 = undef
ECHO: c3 = [1.41421, 90, 135]
ECHO: c4 = [1, 5, 50]
ECHO: c5 = [10, 45, 10]
ECHO: c6 = [1, 1]

Function and/or Module Documentation

coordinate_unit_name()

function coordinate_unit_name

(

s

= coordinate_unit_default

)

Return the name of the given coordinate system identifier.

Parameters

s	<string> A coordinate system identifier.

Returns

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

coordinate()

function coordinate	(	c	,
		from	= coordinate_unit_default,
		to	= coordinate_unit_base
	)

Convert a point from one coordinate system to another.

Parameters

c	<point> A point to convert. Dimensionality must satisfy the requirements of both from and to.
from	<string> The coordinate system identifier of the point to be converted. Defaults to coordinate_unit_default.
to	<string> The coordinate system identifier to which the point should be converted. Defaults to coordinate_unit_base.

Returns

<point> The converted result. Returns undef for unrecognised identifiers, invalid points, or dimensionality mismatches.

Note

"p" requires 2d input; "y" and "s" require 3d input; "c" accepts both. See conventions for full details.

coordinate_inv()

function coordinate_inv	(	c	,
		from	= coordinate_unit_base,
		to	= coordinate_unit_default
	)

Convert a point from one coordinate system to another (direction-swapped defaults).

Parameters

c	<point> A point to convert. Dimensionality must satisfy the requirements of both from and to.
from	<string> The coordinate system identifier of the point to be converted. Defaults to coordinate_unit_base.
to	<string> The coordinate system identifier to which the point should be converted. Defaults to coordinate_unit_default.

Returns

<point> The converted result. Returns undef for unrecognised identifiers, invalid points, or dimensionality mismatches.

Note

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

coordinate_scale2d_cpc()

function coordinate_scale2d_cpc	(	c	,
		r	,
		t	= false
	)

Radially scale a list of 2d cartesian coordinates.

Parameters

c	<points-2d> A list of cartesian coordinates [[x, y], ...].
r	<decimal> A polar radius.
t	<boolean> Translate or scale radius.

Returns

<points-2d> A list of scaled cartesian coordinates.

When t is true, all coordinates will terminate on a circle of radius r. When t is false, the radius of each coordinate is scaled by r.

coordinate_scale2d_p2c()

function coordinate_scale2d_p2c	(	c	,
		r	,
		t	= false
	)

Radially scale and convert a list of 2d polar coordinates to cartesian.

Parameters

c	<points-2d> A list of polar coordinates [[r, aa], ...].
r	<decimal> A polar radius.
t	<boolean> Translate or scale radius.

Returns

<points-2d> A list of scaled cartesian coordinates.

When t is true, all coordinates will terminate on a circle of radius r. When t is false, the radius of each coordinate is scaled by r.

coordinate_scale3d_csc()

function coordinate_scale3d_csc	(	c	,
		r	,
		t	= false
	)

Spherically scale a list of 3d cartesian coordinates.

Parameters

c	<points-3d> A list of cartesian coordinates [[x, y, z], ...].
r	<decimal> A spherical radius.
t	<boolean> Translate or scale radius.

Returns

<points-3d> A list of scaled cartesian coordinates.

When t is true, all coordinates will terminate on a sphere of radius r. When t is false, the radius of each coordinate is scaled by r.

coordinate_scale3d_s2c()

function coordinate_scale3d_s2c	(	c	,
		r	,
		t	= false
	)

Spherically scale and convert a list of 3d spherical coordinates to cartesian.

Parameters

c	<points-3d> A list of spherical coordinates [[r, aa, pa], ...].
r	<decimal> A spherical radius.
t	<boolean> Translate or scale radius.

Returns

<points-3d> A list of scaled cartesian coordinates.

When t is true, all coordinates will terminate on a sphere of radius r. When t is false, the radius of each coordinate is scaled by r.

Variable Documentation

coordinate_unit_base

coordinate_unit_base = "c"

<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 coordinate functions that omit the to parameter will convert to this system.

Definition at line 855 of file coordinate.scad.

coordinate_unit_default

coordinate_unit_default = "c"

<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 coordinate functions that omit the from or s parameter will assume this system.

Definition at line 861 of file coordinate.scad.

coordinate_positive_angle

coordinate_positive_angle = true

<boolean> When converting to angular measures add 360 to negative angles.

Note

When true, any negative azimuthal angle aa produced during conversion is shifted by +360° so that aa is always in [0°, 360°). Applies to polar, cylindrical, and spherical output. May be changed between individual calls; does not affect the polar angle pa.

Definition at line 868 of file coordinate.scad.