Linear Algebra

Euclidean linear algebra functions. More...

Collaboration diagram for Linear Algebra:

Files
file	linear_algebra.scad
	Linear algebra mathematical functions.

Functions and/or Modules
function	multmatrix_p (c, m)
	Multiply all coordinates by a 4x4 transformation matrix in 3D. More...
function	translate_p (c, v)
	Translate all coordinates dimensions. More...
function	mirror_p (c, m, o)
	Mirror all coordinates about a plane or line defined by a normal vector. More...
function	rotate_p (c, a, av, center=false, o)
	Rotate all coordinates about one or more axes in 2D or 3D. More...
function	transform_p (c, m, a, av, center=false, o, t)
	Apply an optional mirror, rotation, and translation to a list of 2D or 3D coordinates. More...
function	shear_p (c, s, center=false, o)
	Shear all coordinates in 2D or 3D. More...
function	scale_p (c, v, center=false, o)
	Scale all coordinates dimensions. More...
function	resize_p (c, v, center=false, o)
	Scale all coordinates dimensions proportionately to fit inside a region. More...
function	center_p (c)
	Center all coordinates about the origin. More...

Usage Details

Euclidean linear algebra functions.

Validation Summary

file	group	script	results	no test	skipped	passed	failed	warning
math/linear_algebra.scad	Linear Algebra	Script	Results	9	0	0	0	0

No Failures

See complete validation results.

Requires:
include <omdl-base.scad>;

Conventions

The following conventions apply to all functions in this group.

• The first parameter is always c (a list of nd coordinate points). All functions return a list of the same length and dimensionality as c.
• Dimensionality d is auto-detected from the first element of c using len(first(c)). Passing an empty list always returns an empty list. Mixing point dimensions within c is undefined behaviour.
• The origin parameter o is optional in all spatial functions that have a fixed point (mirror, rotate, scale, shear, resize). When undef (default), o is set to origin2d or origin3d based on d. Exception: in the 3D Euler rotation branch of rotate_p(), o is silently ignored — see rotate_p() for details. When center is true, o is also ignored — see below.
• The optional center parameter (default false) is available on all spatial functions that have a fixed point (rotate_p(), transform_p(), shear_p(), scale_p(), resize_p()). When true, the transformed result is passed through center_p() so that the output bounding box is centered about the coordinate origin. Centering is always the last step in the pipeline, applied after all other transformations including translation. When center is true, o is ignored.
• When a transformation parameter (v, a, m, s, av) is undef, that transformation is a no-op and c is returned unchanged. This allows safe use in composed pipelines without conditional wrappers at the call site.
• The parameter name m is overloaded by role across the group: a 4x4 homogeneous matrix in multmatrix_p(); a mirror-plane or mirror-line normal vector in mirror_p() and transform_p(); and a shear-factor list in shear_p() (where the parameter has been renamed s). The type is stated explicitly in each function's m or s parameter entry.
• The parameter name v is overloaded by role across the group: a per-dimension translation list or scalar in translate_p(); a per-dimension scale list or scalar in scale_p(); and a per-dimension target-extent list or scalar in resize_p(). In rotate_p() and transform_p() the rotation axis vector uses the distinct name av to avoid ambiguity.
• All angles are in degrees, following OpenSCAD convention.
• No input validation is performed unless an explicit assert is present. Wrong-dimension inputs, non-numeric values, or zero vectors produce undef, nan, or inf without warning.

Function and/or Module Documentation

multmatrix_p()

function multmatrix_p	(	c	,
		m
	)

Multiply all coordinates by a 4x4 transformation matrix in 3D.

Parameters

c	<points-3d> A list of 3d coordinate points.
m	<matrix-4x4> A 4x4 transformation matrix. Only the first three rows are used; the fourth row of the standard homogeneous matrix [0, 0, 0, 1] is implicit and need not be supplied, so a 3x4 matrix is sufficient.

Returns

<points-3d> A list of 3d coordinate points multiplied by the transformation matrix.

Applies a homogeneous transformation matrix m to a list of 3D coordinate points. Each input point [x, y, z] is treated as a homogeneous vector [x, y, z, 1] (i.e. w = 1 is implicit — no perspective divide is performed). The output is the 3-component result of multiplying the upper 3×4 block of m by each homogeneous input vector:

| m[0][0]  m[0][1]  m[0][2]  m[0][3] |   | x |   | x' |
| m[1][0]  m[1][1]  m[1][2]  m[1][3] | × | y | = | y' |
| m[2][0]  m[2][1]  m[2][2]  m[2][3] |   | z |   | z' |
                                          | 1 |

The fourth row of m (normally [0, 0, 0, 1] for affine transforms) is never read, so a 3×4 matrix is sufficient. Combined rotation and translation can be encoded as:

• Columns 0–2: the 3×3 rotation/scale/shear sub-matrix.
• Column 3: the translation vector [tx, ty, tz].

See Wikipedia and multmatrix for more information.

Note

Unlike the other spatial functions in this group, multmatrix_p() takes no o origin parameter. Any origin offset for the transformation is encoded directly in the fourth column of m (i.e. m[0][3], m[1][3], m[2][3]), as is standard for homogeneous transformation matrices.

translate_p()

function translate_p	(	c	,
		v
	)

Translate all coordinates dimensions.

Parameters

c	<points-nd> A list of nd coordinate points.
v	<decimal-list-n | decimal> A list of translations for each dimension, or a single decimal to translate uniformly across all dimensions.

Returns

<points-nd> A list of translated coordinate points.

When v is a scalar, the same translation is applied to every dimension. When v is a list shorter than the point dimensionality, missing elements default to zero. When v is undef the point list is returned unchanged.

Note

Unlike the other spatial functions in this group, translate_p() takes no o origin parameter. Translation has no fixed point — every point moves by the same vector v regardless of position, so an origin offset would have no effect.

See Wikipedia for more information and transformation matrix.

Here is the caller graph for this function:

mirror_p()

function mirror_p	(	c	,
		m	,
		o
	)

Mirror all coordinates about a plane or line defined by a normal vector.

Parameters

c	<points-3d | points-2d> A list of 3d or 2d coordinate points.
m	<vector-3d | vector-2d> The normal vector of the mirror plane or line. A 2D vector [nx, ny] defines the normal to the mirror line; a 3D vector [nx, ny, nz] defines the normal to the mirror plane. Follows the same convention as OpenSCAD's built-in mirror() module.
o	<point-3d | point-2d> The point through which the mirror plane or line passes. When undef (default), the origin is set automatically to origin2d or origin3d based on the dimensionality of c.

Returns

<points-3d | points-2d> A list of mirrored coordinate points.

Reflects points about the plane or line defined by the normal vector m passing through o using the standard reflection matrix M = I - 2*(n*nT)/|n|^2. When m is a zero vector or undef the point list is returned unchanged.

See Wikipedia for more information on reflection matrix.

rotate_p()

function rotate_p	(	c	,
		a	,
		av	,
		center	= false,
		o
	)

Rotate all coordinates about one or more axes in 2D or 3D.

Parameters

c	<points-3d | points-2d> A list of 3d or 2d coordinate points.
a	<decimal-list-3 | decimal> The axis rotation angle; A list [ax, ay, az] or a single decimal to specify az only. When undef the point list is returned unchanged.
av	<vector-3d> An arbitrary axis for the rotation. When specified, the rotation angle will be a or az about the line av that passes through point o.
center	<boolean> When true, the rotated result is passed through center_p() so that the output bounding box is centered about the origin. When false (default), the result is positioned as determined by o.
o	<point-3d | point-2d> The origin for the rotation. In 2D, the center of rotation. In 3D, used only when av is specified. When undef (default), the origin is set automatically to origin2d or origin3d based on the dimensionality of c. Ignored when center is true.

Returns

<points-3d | points-2d> A list of rotated coordinate points.

Three rotation branches are selected based on dimensionality and the presence of av:

• 2D (d = 2): rotates about point o by angle az (extracted as a[2], or a itself when scalar). o is the center of rotation.
• 3D Euler (d = 3, av undef or a is a list): applies extrinsic rotations in the order Z (az), Y (ay), X (ax), equivalent to the standard OpenSCAD rotate([ax, ay, az]) convention. Missing angle components default to 0.
• 3D arbitrary axis (d = 3, av defined, a scalar): rotates by az about the line through o with direction av, using the Rodrigues rotation formula. av need not be a unit vector; it is normalised internally.

When center is true, center_p() is called on the rotated result to center the output bounding box about the origin.

Note

In the 3D Euler branch the origin o is silently ignored — rotation always occurs about the world origin. Only the 2D branch and the 3D arbitrary-axis branch respect o.

See Wikipedia for more information on transformation matrix and axis rotation.

transform_p()

function transform_p	(	c	,
		m	,
		a	,
		av	,
		center	= false,
		o	,
		t
	)

Apply an optional mirror, rotation, and translation to a list of 2D or 3D coordinates.

Parameters

c	<points-3d | points-2d> A list of 3d or 2d coordinate points.
m	<vector-3d | vector-2d> The normal vector of the mirror plane or line. The mirror is applied about the plane or line passing through o with the given normal. When undef (default), no mirror is applied.
a	<decimal-list-3 | decimal> The axis rotation angle; A list [ax, ay, az] or a single decimal to specify az only. When undef, no rotation is applied.
av	<vector-3d> An arbitrary axis for the rotation. When specified, the rotation angle will be a or az about the line av that passes through point o.
center	<boolean> When true, the fully transformed result is passed through center_p() so that the output bounding box is centered about the origin. Centering is applied after mirror, rotation, and translation. When false (default), the result is positioned as determined by o and t.
o	<point-3d | point-2d> The origin for the rotation and mirror. In 2D, the center of rotation. In 3D, used only when av is specified. When undef (default), the origin is set automatically to origin2d or origin3d based on the dimensionality of c.
t	<point-3d | point-2d> A translation vector applied after mirror and rotation. When undef (default), no translation is applied. Translation is always applied last before centering.

Returns

<points-3d | points-2d> A list of 3d or 2d transformed coordinates. Operations are applied in order: mirror about o, rotate about o, translate by t, then optionally center via center_p(). In 3D Euler mode, rotation order is extrinsic Z, Y, X (equivalent to OpenSCAD rotate([ax,ay,az])).

Applies a transformation to a list of coordinate points by composing mirror_p(), rotate_p(), and translate_p() in sequence. The mirror m, when specified, reflects points about the plane or line defined by the normal vector m passing through o. Rotation a is then applied about o, followed by the optional translation t. Any combination of the three operations may be used independently — in particular, m and t may be specified without a to mirror and then translate without rotation. When center is true, center_p() is called on the final result to center the output bounding box about the origin.

The mirror normal m follows the same convention as OpenSCAD's built-in mirror() module: a 2D vector [nx, ny] defines the normal to the mirror line, and a 3D vector [nx, ny, nz] defines the normal to the mirror plane.

When a, m, t, and center are all undef or false the point list is returned unchanged.

See Wikipedia for more information on transformation matrix, axis rotation, and reflection matrix.

shear_p()

function shear_p	(	c	,
		s	,
		center	= false,
		o
	)

Shear all coordinates in 2D or 3D.

Parameters

c	<points-3d | points-2d> A list of 3d or 2d coordinate points.
s	<decimal-list> The shear factors. In 2D, a list [sxy, syx] where sxy shifts x proportional to y and syx shifts y proportional to x. In 3D, a list [sxy, sxz, syx, syz, szx, szy] following the standard shear matrix convention.
center	<boolean> When true, the sheared result is passed through center_p() so that the output bounding box is centered about the origin. When false (default), the result is positioned as determined by o.
o	<point-3d | point-2d> The origin about which shearing is applied. When undef (default), the origin is set automatically to origin2d or origin3d based on the dimensionality of c. Shearing about an explicit origin is equivalent to translating by -o, shearing, then translating back by +o. Ignored when center is true.

Returns

<points-3d | points-2d> A list of sheared coordinate points.

Applies a shear transformation to a list of coordinate points. Shearing displaces each coordinate in one axis proportionally to its position along another axis, leaving the shear origin fixed.

The 2D shear matrix for factors [sxy, syx] is:

| 1    sxy |
| syx  1   |

The 3D shear matrix for factors [sxy, sxz, syx, syz, szx, szy] is:

| 1    sxy  sxz |
| syx  1    syz |
| szx  szy  1   |

Missing list elements default to 0 (no shear in that direction). When center is true, center_p() is called on the sheared result to center the output bounding box about the origin, and o is ignored. When s is undef the point list is returned unchanged.

See Wikipedia for more information on shear mapping.

scale_p()

function scale_p	(	c	,
		v	,
		center	= false,
		o
	)

Scale all coordinates dimensions.

Parameters

c	<points-nd> A list of nd coordinate points.
v	<decimal-list-n | decimal> A list of scale factors for each dimension, or a single decimal to scale uniformly across all dimensions.
center	<boolean> When true, the scaled result is passed through center_p() so that the output bounding box is centered about the origin. When false (default), the result is positioned as determined by o.
o	<point-nd> The origin about which scaling is applied. When undef (default), the origin is set automatically to origin2d or origin3d based on the dimensionality of c. Scaling about an explicit origin is equivalent to translating by -o, scaling, then translating back by +o. Ignored when center is true.

Returns

<points-nd> A list of scaled coordinate points.

When v is a scalar, the same scale factor is applied to every dimension. When v is a list shorter than the point dimensionality, missing elements default to 1 (no scaling). When o is the origin the result is identical to scaling about the origin. When center is true, center_p() is called on the scaled result to center the output bounding box about the origin, and o is ignored. When v is undef the point list is returned unchanged.

See Wikipedia for more information on transformation matrix.

resize_p()

function resize_p	(	c	,
		v	,
		center	= false,
		o
	)

Scale all coordinates dimensions proportionately to fit inside a region.

Parameters

c	<points-nd> A list of nd coordinate points.
v	<decimal-list-n | decimal> A list of target extents for each dimension. When a scalar, the same target extent is applied to every dimension (the aspect ratio of the input is not preserved). When a list shorter than the point dimensionality, missing elements default to 1.
center	<boolean> When true, the scaled result is centered about the origin by passing the scaled point list through center_p(). When false (default), the bounding box minimum is placed at the origin before scaling so that the result spans [0, v[i]] in each dimension.
o	<point-nd> The origin to which the bounding box minimum is aligned before scaling. When undef (default), the origin is set automatically to origin2d or origin3d based on the dimensionality of c. Ignored when center is true — the result is centered about the coordinate origin regardless of o.

Returns

<points-nd> A list of proportionately scaled coordinate points which exactly fit the region bounds v.

Points are first translated so that the bounding box minimum of each dimension is aligned to o, then scaled to fit v. This ensures a consistent result regardless of where the input points are positioned. When a dimension has zero extent (all points share the same coordinate), that dimension is left unchanged to avoid division by zero. When center is true, the scaled result is passed through center_p() to center it about the coordinate origin, and o is ignored. When v is undef the point list is returned unchanged.

Note

The bounding box is computed by iterating c once per dimension, giving O(n*d) total work where n = len(c) and d = len(first(c)). When center is true an additional O(n*d) pass is performed by center_p(). For typical 2D or 3D inputs this is negligible, but callers passing very large point lists should be aware of the linear scaling with both n and d.

See Wikipedia for more information on transformation matrix.

Here is the caller graph for this function:

center_p()

function center_p

(

c

)

Center all coordinates about the origin.

Parameters

c	<points-nd> A list of nd coordinate points.

Returns

<points-nd> A list of coordinate points translated so that the bounding box of the result is centered about the origin.

Computes the per-dimension bounding box midpoint of c and translates all points by the negation of that midpoint, so that the output bounding box is symmetric about the origin in every dimension. The shape, size, and relative positions of all points are preserved — only the position of the point cloud as a whole changes.

Centering is performed by a single bounding-box pass (O(n*d) where n = len(c) and d = len(first(c))) followed by a single translation pass, making the total work O(n*d). Passing an empty list returns an empty list unchanged.

Note

This function is called directly by resize_p when its center parameter is true. It may be composed freely with any other spatial function in this group to post-center the result of an arbitrary transformation pipeline.

See Wikipedia for more information on translation.