Euclidean

Tests and operations for Euclidean 3d space. More...

Collaboration diagram for Euclidean:

Files
file	euclidean.scad
	Tests and operations for Euclidean 3d space.

Functions
function	is_point (v)
	Test if a value defines a point. More...
function	is_vector (v)
	Test if a value defines a Euclidean vector. More...
function	is_line (v)
	Test if a value defines a line. More...
function	is_vol (v)
	Test if a value defines a vector or a line. More...
function	is_plane (v)
	Test if a value defines a plane. More...
function	distance_pp (p1, p2)
	Compute the distance between two points. More...
function	distance_pl (p, l)
	Compute the shortest distance between a point and a line. More...
function	distance_pn (p, n, np)
	Compute the shortest distance between a point and a plane. More...
function	is_left_ppp (p1, p2, p3)
	Test if a point is left, on, or right of an infinite line in a 2d-space. More...
function	point_closest_pl (p, l)
	Compute the coordinates of the closest point on a line to a given point. More...
function	point_closest_pn (p, n, np)
	Compute the coordinates of the closest point on a plane to a given point. More...
function	point_to_3d (p)
	Return 3d point unchanged or add a zeroed third dimension to 2d point. More...
function	interpolate2d_l_pp (p1, p2, x, y)
	Linearly interpolate along a line established by two points in 2d. More...
function	line2d_new (m=1, a=0, p1=origin2d, p2, v)
	Construct a 2 dimensional directed line. More...
function	line3d_new (m=1, a=0, t=90, p1=origin3d, p2, v)
	Construct a 3 dimensional directed line. More...
function	line_new (m=1, a=0, t, p1, p2, v)
	Construct a directed line. More...
function	line_dim (l)
	Return the number of dimensions of a line or vector. More...
function	line_tp (l)
	Return the terminal point of a line or vector. More...
function	line_ip (l)
	Return the initial point of a line or vector. More...
function	vol_to_origin (l)
	Convert line to vector by shifting it to the origin. More...
function	vol_to_point (l, p)
	Convert a vector to a line or move a line to another coordinate point. More...
function	dot_ll (l1, l2)
	Compute the dot product of two lines or vectors in a 3d or 2d-space. More...
function	cross_ll (l1, l2)
	Compute the cross product of two lines or vectors in a 3d or 2d-space. More...
function	striple_lll (l1, l2, l3)
	Compute the scalar triple product of three lines or vectors in a 3d or 2d-space. More...
function	angle_ll (l1, l2, s=true)
	Compute the angle between two lines or vectors in a 3d or 2d-space. More...
function	angle_lll (l1, l2, n)
	Compute the angle between two lines or vectors in a 3d-space. More...
function	unit_l (l)
	Compute the normalized unit vector of a line or vector. More...
function	are_coplanar_lll (l1, l2, l3, d=6)
	Test if three lines or vectors are coplanar in 3d-space. More...
function	plane_to_normal (n, cw=true)
	Convert a planes' normal specification into a normal vector. More...

Detailed Description

Tests and operations for Euclidean 3d space.

Requires:
include <omdl-base.scad>;

Validation Summary

file	group	script	results	no test	skipped	passed	failed	warning
datatypes/euclidean.scad	Euclidean	Script	Results	0	26	109	0	0

No Failures

See complete validation results.

Function Documentation

angle_ll()

function angle_ll	(	l1	,
		l2	,
		s	= true
	)

Compute the angle between two lines or vectors in a 3d or 2d-space.

Parameters

l1	<line-3d | line-2d> A 3d or 2d line or vector 1.
l2	<line-3d | line-2d> A 3d or 2d line or vector 2.
s	<boolean> Return the 2d signed angle.

Returns

(1) <decimal> The angle between the two lines or vectors in degrees. (2) Returns undef when l1 or l2 is not a line or vector or have different dimensions or when they do not intersect.

For 2d lines or vectors, the signed angle is calculated. The parameter s determines if the signed (s == true) or positive (s == false) angle is returned. For 3d lines or vectors, a normal is required to uniquely identify the perpendicular plane and axis of rotation. This function calculates the positive angle, and the plane and axis of rotation will be that which fits this assumed positive angle.

See Lines and vectors for argument specification and conventions.

See also

angle_lll().

Here is the caller graph for this function:

angle_lll()

function angle_lll	(	l1	,
		l2	,
		n
	)

Compute the angle between two lines or vectors in a 3d-space.

Parameters

l1	<line-3d> A 3d line or vector 1.
l2	<line-3d> A 3d line or vector 2.
n	<line-3d> A 3d normal line or vector.

Returns

(1) <decimal> The angle between the two lines or vectors in degrees. (2) Returns undef when l1, l2, or n is not a line or vector or have different dimensions or when they do not intersect.

See Lines and vectors for argument specification and conventions.

See also

angle_ll().

are_coplanar_lll()

function are_coplanar_lll	(	l1	,
		l2	,
		l3	,
		d	= 6
	)

Test if three lines or vectors are coplanar in 3d-space.

Parameters

l1	<line-3d> A 3d line or vector 1.
l2	<line-3d> A 3d line or vector 2.
l3	<line-3d> A 3d line or vector 3.
d	<integer> The number of decimal places to consider.

Returns

(1) <boolean> true when all three lines or vectors are coplanar, and false otherwise. (2) Returns undef when l1, l2, or l3 is not a line or vector or have different dimensions,

See Lines and vectors for argument specification and conventions. See Wikipedia for more information.

Note

When lines or vectors are specified with start and end points, this function tests if they are in a planes parallel to the coplanar.

cross_ll()

function cross_ll	(	l1	,
		l2
	)

Compute the cross product of two lines or vectors in a 3d or 2d-space.

Parameters

l1	<line-3d | line-2d> A 3d or 2d line or vector 1.
l2	<line-3d | line-2d> A 3d or 2d line or vector 2.

Returns

(1) <decimal | vector-2d> The cross product of l1 with l2. (2) Returns undef when l1 or l2 is not a line or vector or have different dimensions.

This function supports the abstraction outlined in Lines and vectors. The built-in operation will be more efficient in situations that do not make use of the aforementioned abstraction.

See Lines and vectors for argument specification and conventions. See Wikipedia cross and determinant for more information.

Note

This function returns the 2x2 determinant for 2d vectors.

Here is the caller graph for this function:

distance_pl()

function distance_pl	(	p	,
		l
	)

Compute the shortest distance between a point and a line.

Parameters

p	<point> A point coordinate.
l	<line> A line or vector.

Returns

(1) <decimal> The shortest distance between the point and the line. (2) Returns undef when p is not a point or l is not a line.

See also

point_closest_pl().

distance_pn()

function distance_pn	(	p	,
		n	,
		np
	)

Compute the shortest distance between a point and a plane.

Parameters

p	<point> A point coordinate.
n	<pnorm> A plane normal specification.
np	<point> A point coordinate on the plane n.

Returns

(1) <decimal> The shortest distance between the point and the plane. (2) Returns undef when p is not a point or l is not a line.

See also

point_closest_pn().

distance_pp()

function distance_pp	(	p1	,
		p2
	)

Compute the distance between two points.

Parameters

p1	<point> A point coordinate 1.
p2	<point> A point coordinate 2.

Returns

(1) <decimal> The distance between the two points. (2) Returns undef when p1 or p2 are not points or do not have equal dimensions.

When p2 is not given, it is assumed to be at the origin. This function is similar to norm.

Here is the caller graph for this function:

dot_ll()

function dot_ll	(	l1	,
		l2
	)

Compute the dot product of two lines or vectors in a 3d or 2d-space.

Parameters

l1	<line-3d | line-2d> A 3d or 2d line or vector 1.
l2	<line-3d | line-2d> A 3d or 2d line or vector 2.

Returns

(1) <decimal> The dot product of l1 with l2. (2) Returns undef when l1 or l2 is not a line or vector or have different dimensions.

This function supports the abstraction outlined in Lines and vectors. The built-in operation will be more efficient in situations that do not make use of this abstraction.

See Lines and vectors for argument specification and conventions. See Wikipedia for more information.

interpolate2d_l_pp()

function interpolate2d_l_pp	(	p1	,
		p2	,
		x	,
		y
	)

Linearly interpolate along a line established by two points in 2d.

Parameters

p1	<point-2d> The line initial coordinate [x, y].
p2	<point-2d> The line terminal coordinate [x, y].
y	<decimal> The y coordinate at which to interpolate along the line.
x	<decimal> The x coordinate at which to interpolate along the line.

Returns

(1) <point-2d> The interpolated coordinates point [x, y]. (2) Returns undef when p1 or p2 is not a point or when x or y are not numbers.

The order of precedence for interpolation is: y, x. See Wikipedia for more information.

is_left_ppp()

function is_left_ppp	(	p1	,
		p2	,
		p3
	)

Test if a point is left, on, or right of an infinite line in a 2d-space.

Parameters

p1	<point-2d> A 2d point coordinate 1.
p2	<point-2d> A 2d point coordinate 2.
p3	<point-2d> A 2d point coordinate 3.

Returns

(1) <decimal> (> 0) for p3 left of the line through p1 and p2, (= 0) for p3 on the line, and (< 0) for p3 right of the line. (2) Returns undef when p1, p2, or p3 is not a point.

Function patterned after Dan Sunday, 2012.

is_line()

function is_line

(

v

)

Test if a value defines a line.

Parameters

v	<list-2d | list-3d> A 2d or 3d list of numbers.

Returns

(1) <boolean> true when the v can be interpreted as a line and false otherwise.

See Lines and vectors for argument specification and conventions.

is_plane()

function is_plane

(

v

)

Test if a value defines a plane.

Parameters

v	<list-2d | list-3d> A 2d or 3d list of numbers.

Returns

(1) <boolean> true when the v can be interpreted as a plane and false otherwise.

See Lines and vectors for argument specification and conventions.

is_point()

function is_point

(

v

)

Test if a value defines a point.

Parameters

v	<list-2d | list-3d> A 2d or 3d list of numbers.

Returns

(1) <boolean> true when the v can be interpreted as a point and false otherwise.

See Lines and vectors for argument specification and conventions.

Here is the caller graph for this function:

is_vector()

function is_vector

(

v

)

Test if a value defines a Euclidean vector.

Parameters

v	<list-2d | list-3d> A 2d or 3d list of numbers.

Returns

(1) <boolean> true when the v can be interpreted as a Euclidean vector and false otherwise.

See Lines and vectors for argument specification and conventions.

is_vol()

function is_vol

(

v

)

Test if a value defines a vector or a line.

Parameters

v	<list-2d | list-3d> A 2d or 3d list of numbers.

Returns

(1) <boolean> true when the v can be interpreted as a vector or a line and false otherwise.

See Lines and vectors for argument specification and conventions.

line2d_new()

function line2d_new	(	m	= 1,
		a	= 0,
		p1	= origin2d,
		p2	,
		v
	)

Construct a 2 dimensional directed line.

Parameters

m	<decimal> The magnitude.
a	<decimal> The azmuthal angle.
p1	<point-2d> The initial point.
p2	<point-2d> The terminal point.
v	<vector-2d> An orientation line or vector.

Returns

(1) <line-2d> The 2d directed line. (2) Returns undef when required parameters are not defined.

The initial point (or tail) of the line is specified by p1. The terminal point (or head) can be specified by one of, in order of precedence, p2, v, or a.

See Lines and vectors for argument specification and conventions.

Here is the caller graph for this function:

line3d_new()

function line3d_new	(	m	= 1,
		a	= 0,
		t	= 90,
		p1	= origin3d,
		p2	,
		v
	)

Construct a 3 dimensional directed line.

Parameters

m	<decimal> The magnitude.
a	<decimal> The azmuthal angle.
t	<decimal> The polar angle.
p1	<point-3d> The initial point.
p2	<point-3d> The terminal point.
v	<vector-3d> An orientation line or vector.

Returns

(1) <line-3d> The 3d directed line. (2) Returns undef when required parameters are not defined.

The initial point (or tail) of the line is specified by p1. The terminal point (or head) can be specified by one of, in order of precedence, p2, v, or a and t.

See Lines and vectors for argument specification and conventions.

line_dim()

function line_dim

(

l

)

Return the number of dimensions of a line or vector.

Parameters

l	<line> A line or vector.

Returns

(1) <integer> The line or vector dimensions. (2) Returns undef when l is not a line or vector.

See Lines and vectors for argument specification and conventions.

line_ip()

function line_ip

(

l

)

Return the initial point of a line or vector.

Parameters

l	<line> A line or vector.

Returns

(1) <point> The initial point of the line or vector. (2) Returns undef when l is not a line or vector.

See Lines and vectors for argument specification and conventions.

Here is the caller graph for this function:

line_new()

function line_new	(	m	= 1,
		a	= 0,
		t	,
		p1	,
		p2	,
		v
	)

Construct a directed line.

Parameters

m	<decimal> The magnitude.
a	<decimal> The azmuthal angle.
t	<decimal> The polar angle.
p1	<point> The initial point.
p2	<point> The terminal point.
v	<vector> An orientation line or vector.

Returns

(1) <line> The directed line. (2) Returns undef when required parameters are not defined.

The initial point (or tail) of the line is specified by p1. The terminal point (or head) can be specified by one of, in order of precedence, p2, v, or a and t.

This function will construct a 2d or 3d line as required based on the supplied arguments. A 3d line is constructed only when required. Because the argument dimensions are inspected, this function has more overhead when compared to line2d_new() and line3d_new().

See Lines and vectors for argument specification and conventions.

line_tp()

function line_tp

(

l

)

Return the terminal point of a line or vector.

Parameters

l	<line> A line or vector.

Returns

(1) <point> The terminal point of the line or vector. (2) Returns undef when l is not a line or vector.

See Lines and vectors for argument specification and conventions.

Here is the caller graph for this function:

plane_to_normal()

function plane_to_normal	(	n	,
		cw	= true
	)

Convert a planes' normal specification into a normal vector.

Parameters

n	<pnorm> A plane normal specification.
cw	<boolean> Point ordering. When the plane specified as non-collinear points, this indicates ordering.

Returns

(1) <normal> A vector-3d normal to the plane. (2) Returns undef when n is not a plane.

When n is not a valid plane, undef is returned. The computed normal vector is not normalized to its unit vector.

See Planes' normal for argument specification and conventions.

point_closest_pl()

function point_closest_pl	(	p	,
		l
	)

Compute the coordinates of the closest point on a line to a given point.

Parameters

p	<point> A point coordinate.
l	<line> A line or vector.

Returns

(1) <point-3d> The coordinates of the point on the line closest to the given point. (2) Returns undef when p is not a point or l is not a line.

Here is the caller graph for this function:

point_closest_pn()

function point_closest_pn	(	p	,
		n	,
		np
	)

Compute the coordinates of the closest point on a plane to a given point.

Parameters

p	<point> A point coordinate.
n	<pnorm> A plane normal specification.
np	<point> A point coordinate on the plane n.

Returns

(1) <point-3d> The coordinates of the point on the plane closest to the given point. (2) Returns undef when p or np is not a point or when n is not a plane.

point_to_3d()

function point_to_3d

(

p

)

Return 3d point unchanged or add a zeroed third dimension to 2d point.

Parameters

p	<point-3d | point-2d> A point.

Returns

(1) <point-3d> The 3d point or the 2d point converted to 3d with its third dimension assigned zero. (2) Returns undef when p is not a point.

This function assumes any point that is not 3d to be 2d.

Here is the caller graph for this function:

striple_lll()

function striple_lll	(	l1	,
		l2	,
		l3
	)

Compute the scalar triple product of three lines or vectors in a 3d or 2d-space.

Parameters

l1	<line-3d | line-2d> A 3d or 2d line or vector 1.
l2	<line-3d | line-2d> A 3d or 2d line or vector 2.
l3	<line-3d | line-2d> A 3d or 2d line or vector 3.

Returns

(1) <decimal | vector-2d> The scalar triple product. (2) Returns undef when l1, l2, or l3 is not a line or vector or have different dimensions,

Returns a 2d vector result for 2d vectors. The cross product computes the 2x2 determinant of the vectors (l2 x l3), a scalar value, which is then multiplied by l1.

  [l1, l2, l3] = l1 * (l2 x l3)

See Lines and vectors for argument specification and conventions. See Wikipedia for more information.

unit_l()

function unit_l

(

l

)

Compute the normalized unit vector of a line or vector.

Parameters

l	<line> A line or vector.

Returns

(1) <vector> The normalized unit vector. (2) Returns undef when l is not a line or vector.

See Lines and vectors for argument specification and conventions.

vol_to_origin()

function vol_to_origin

(

l

)

Convert line to vector by shifting it to the origin.

Parameters

l	<line> A line or vector.

Returns

(1) <vector> The line shifted to the origin. (2) Returns undef when l is not a line or vector.

See Lines and vectors for argument specification and conventions.

Here is the caller graph for this function:

vol_to_point()

function vol_to_point	(	l	,
		p
	)

Convert a vector to a line or move a line to another coordinate point.

Parameters

l	<line> A line or vector.
p	<point> The new initial point.

Returns

(1) <line> The line or vector moved to p. (2) Returns undef when l is not a line or vector or when p is not a point.

When p is not specified, the line or vector is moved to the origin.

See Lines and vectors for argument specification and conventions.