Types and Values

OpenSCAD defines a value as one of the following: a number, boolean, string, range, vector, or the undefined value. Within omdl, what the OpenSCAD types documentation calls a vector is referred to as a list. This distinction helps differentiate between sequential collections of general or compound values and Euclidean vectors representing numeric coordinates.

Base types

type	description
boolean	a binary logic value (`true` or `false`)
number	a numerical value
string	an iterable sequence of of character values
list	an iterable sequence of arbitrary values
range	an arithmetic sequence
function	a function literal or variable containing functions

Special values

value	description
undef	a value with no definition
""	a string with no characters, the empty string
[]	a list with no element-values, the empty list
nan	a numerical value which is not a number
inf	a numerical value which is infinite

Type naming conventions

For clarity and consistency, the following naming conventions are used when referring to common data types within the library.

name	description
value	any datum that can be stored in OpenSCAD
scalar	a single non-iterable value
iterable	any value with iterable elements
empty	any iterable value with zero elements
bit	a binary numerical value ( `0` or `1` )
integer	a positive, negative, or zero whole number
even	an even integer
odd	an odd integer
decimal	a real number with a fractional part
index	a list index sequence
datastruct	a defined data structure
data	an arbitrary data structure
map	data store of keys mapped to values
table	data store of values arranged in rows and columns

List naming conventions

When a value is a list and has an expected number of elements, the suffix -n is appended to indicate the required element count. If a range of acceptable elements is allowed, the lower and upper bounds are appended using the form l:u.

When values list elements are expected to be of a specific data type, the element type is prefixed to the value list name. These conventions provide a concise way to describe parameter value contracts and expected data structures throughout the documentation.

See the tables below for examples.

name	description
list-n	a list of `n` values
list-l:u	a list of `l` to `u` values
typed-list	a list of `typed` values
typed-list-n	a list of `n` `typed` values
typed-list-m-list-n	`m` lists of `n` `typed` value lists

Euclidean Space Types

For geometric specifications and geometric algebra, omdl adopts the following type definitions and conventions.

name	description
point	a list of numbers to identify a location in space
vector	a direction and magnitude in space
line	a start and end point in space (line wiki)
normal	a vector that is perpendicular to a given object
pnorm	a vector that is perpendicular to a plane
plane	a flat 2d infinite surface (plane wiki)
matrix	a rectangular array of values

When a particular dimension is expected, the dimensional expectation is appended to the end of the name after a '-' dash as in the following table.

name	description
point-nd	a point in an `n` dimensional space
vector-nd	a vector in an `n` dimensional space
line-nd	a line in an `n` dimensional space
matrix-mxn	an `m` by `n` matrix of values

When a type is specified in plural form, such as points, it implies a list of the specified type. For example, points is equivalent to a point-list.

Lines and vectors

A vector has both direction and magnitude in space. A line likewise has direction and magnitude, but also includes location, as it begins at one point in space and ends at another. Although a line may be defined in one dimension, most library functions operate on two- and/or three-dimensional lines. Operators in omdl follow a common convention for representing Euclidean vectors and straight lines, as summarized in the following table:

Given two points p1 and p2, in space:

no.	form	description
1	p2	a vector from the origin to `p2`
2	[p2]	a vector from the origin to `p2`
3	[p1, p2]	a line from `p1` to `p2`

The functions is_point(), is_vector(), is_line(), line_dim(), line_tp(), line_ip(), vol_to_point(), and vol_to_origin(), are available for type identification and conversion.

Examples

// points
p1 = [a,b,c]
p2 = [d,e,f]
 
// vectors
v1 = p2       = [d,e,f]
v2 = [p2]     = [[d,e,f]]
 
// lines
v3 = [p1, p2] = [[a,b,c], [d,e,f]]
 
v1 == v2
v1 == v2 == v3, iff p1 == origin3d

Planes

Operators in omdl follow a common convention for defining planes. A plane is specified by a point located on its surface together with a normal vector, denoted by pnorm, which is described in the following section. The plane definition is therefore represented as a list containing both the point and its corresponding normal vector, as shown below:

name	form
plane	[point, pnorm]

Planes' normal

The data type pnorm defines a convention for specifying a direction vector that is perpendicular to a plane. Given three points p1, p2, p3, and three vectors v1, v2, vn, the plane normal may be expressed using any of the following equivalent forms:

no.	form	description
1	vn	the predetermined normal vector to the plane
2	[vn]	the predetermined normal vector to the plane
3	[v1, v2]	two distinct but intersecting vectors
4	[p1, p2, p3]	three (or more) non-collinear coplanar points

The functions is_plane() and plane_to_normal() are available for type identification and conversion.

Example

// points
p1 = [a,b,c];
p2 = [d,e,f];
p3 = [g,h,i];
 
// lines and vectors
v1 = [p1, p2] = [[a,b,c], [d,e,f]]
v2 = [p1, p3] = [[a,b,c], [g,h,i]]
vn = cross_ll(v1, v2)
 
// planes' normal
n1 = vn           = cross_ll(v1, v2)
n2 = [vn]         = cross_ll(v1, v2)
n3 = [v1, v2]     = [[[a,b,c],[d,e,f]], [[a,b,c],[g,h,i]]]
n4 = [p1, p2, p3] = [[a,b,c], [d,e,f], [g,h,i]]
 
n1 || n2 || n3 || n4
 
// planes
pn1 = [p1, n1]
pn2 = [p2, n2]
pn3 = [p3, n3]
pn4 = [n4[0], n4]
pn5 = [mean(n4), n4]
 
pn1 == pn4