Coordinates

Coordinate systems and conversions. More...

Collaboration diagram for Coordinates:

Files
file	units_coordinate.scad
	Coordinate systems and conversions.

Functions
function	coordinates_name (s=base_coordinates)
	Return the name of the given coordinate system identifier. More...
function	convert_coordinate (c, from=base_coordinates, to=base_coordinates)
	Convert point from one coordinate system to another. More...
function	coordinates_cpc (c, r, t=false)
	Radially scale a list of 2d cartesian coordinates. More...
function	coordinates_pc (p, r, t=false)
	Radially scale and convert a list of 2d polar coordinates to cartesian. More...
function	coordinates_csc (c, r, t=false)
	Radially scale a list of 3d cartesian coordinates. More...
function	coordinates_sc (s, r, t=false)
	Radially scale and convert a list of 3d spherical coordinates to cartesian. More...

Variables
	base_coordinates = "c"
	<string> The base coordinate system.
	coordinates_positive_angles = true
	<boolean> When converting to angular measures add 360 to negative angles.

Detailed Description

Coordinate systems and conversions.

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.

Example

    include <units/units_coordinate.scad>;

    base_coordinates = "c";

    // get the base coordinate system name
    cs = coordinates_name();

    // absolute coordinates in a specified coordinate system.
    c1 = convert_coordinate([1, 1, 1], "c");
    c2 = convert_coordinate([1, 180], "p");
    c3 = convert_coordinate([1, 90, -1], "y");
    c4 = convert_coordinate([1, 5, 50], "s");

    // convert between system.
    c5 = convert_coordinate([10*sqrt(2), 45, 45], from="s", to="y");
    c6 = convert_coordinate([sqrt(2), 45], from="p", to="c");

Result (base_coordinates = c):

ECHO: cs = "cartesian"
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]

Result (base_coordinates = p):

ECHO: cs = "polar"
ECHO: c1 = [1.41421, 45]
ECHO: c2 = [1, 180]
ECHO: c3 = [1, 90]
ECHO: c4 = [0.766044, 5]
ECHO: c5 = [10, 45, 10]
ECHO: c6 = [1, 1]

Result (base_coordinates = y):

ECHO: cs = "cylindrical"
ECHO: c1 = [1.41421, 45, 1]
ECHO: c2 = [1, 180, 0]
ECHO: c3 = [1, 90, -1]
ECHO: c4 = [0.766044, 5, 0.642788]
ECHO: c5 = [10, 45, 10]
ECHO: c6 = [1, 1]

Result (base_coordinates = s):

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

Function Documentation

function convert_coordinate	(	c	,
		from	= base_coordinates,
		to	= base_coordinates
	)

Convert point from one coordinate system to another.

Parameters

c	<point> A point to convert.
from	<string> The coordinate system identifier of the point to be converted.
to	<string> The coordinate system identifier to which the point should be converted.

Returns

<point> The converted result. Returns undef for identifiers that are not defined.

function coordinates_cpc	(	c	,
		r	,
		t	= false
	)

Radially scale a list of 2d cartesian coordinates.

Parameters

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

Returns

<coords-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.

function coordinates_csc	(	c	,
		r	,
		t	= false
	)

Radially scale a list of 3d cartesian coordinates.

Parameters

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

Returns

<coords-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.

function coordinates_name

(

s

= base_coordinates

)

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.

function coordinates_pc	(	p	,
		r	,
		t	= false
	)

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

Parameters

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

Returns

<coords-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.

function coordinates_sc	(	s	,
		r	,
		t	= false
	)

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

Parameters

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

Returns

<coords-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.