Length Units

Length units and conversions. More...

Collaboration diagram for Length Units:

Files
file	length.scad
	Length units and conversions.

Shorts
Convenience wrappers around length that fix the from unit to a named unit and the to unit to length_unit_base. The d parameter is forwarded (default 1). Use length directly when a non-default target unit or list input with d > 1 is required.
function	l_mm (v, d=1)
	Shorthand length conversion for millimeters. More...
function	l_in (v, d=1)
	Shorthand length conversion for inches. More...

Functions and/or Modules
function	length_unit_name (u=length_unit_default, d=1, w=false)
	Return the name for a length unit identifier with dimension. More...
function	length (v, from=length_unit_default, to=length_unit_base, d=1)
	Convert a length value from one unit to another, with optional dimensional scaling. More...
function	length_inv (v, from=length_unit_base, to=length_unit_default, d=1)
	Recover a linear length from an area or volume value, then convert units. More...

Variables
	length_unit_base = "mm"
	length_unit_default = "mm"

Usage Details

Length units and conversions.

Validation Summary

file	group	script	results	no test	skipped	passed	failed	warning
units/length.scad	Length Units	Script	Results	3	0	0	0	0

No Failures

See complete validation results.

Requires:
include <omdl-base.scad>;

Conventions

Parameter naming

• v is the numeric value to convert. It has no default and must always be supplied by the caller. For d = 1 it may be a scalar or a list; the conversion is applied element-wise. For d = 2 or d = 3 it must be a scalar.
• from identifies the source unit; defaults to length_unit_default.
• to identifies the target unit; defaults to length_unit_base.
• d is the dimensional exponent: 1 (linear), 2 (area), 3 (volume). Values outside [1|2|3] yield undef.
• u is a unit-identifier string used in name-lookup functions; defaults to length_unit_default.
• w selects word (true) vs symbol (false) format in name-return functions; defaults to false.

Return values

• All functions return undef for unrecognised unit identifiers or out-of-range dimension values. Callers are responsible for testing return values when inputs may be dynamic.

Global configuration

• length_unit_base sets the storage base unit for the entire design. It defaults to "mm" and is intended to be overridden at the top of a design file or within a child scope before any length function is called.
• length_unit_default sets the assumed input unit when from or u is not specified. It also defaults to "mm" and may be overridden in the same way.
• Both variables must be assigned before any length function is called; changing them after assignments that depend on them have already been evaluated has no effect on those prior results.

Unit identifiers

• Unit identifier strings are case-sensitive and lowercase (e.g. "mm", "in").
• The identifiers "thou" and "mil" denote the same physical unit (one thousandth of an inch, 0.0254 mm) and are interchangeable in all conversion functions.

Shorthand functions

• The l_mm() and l_in() helpers are convenience wrappers that fix from to their named unit and to to length_unit_base. The d parameter is forwarded and defaults to 1. Use the full length function when a non-default target unit is required.

These functions allow for lengths to be specified with units. Lengths specified with units are independent of (length_unit_base). There are also unit conversion functions for converting from one unit to another.

The table below enumerates the supported units.

units id	description
pm	picometer
nm	nanometer
um	micrometer
mm	millimeter
cm	centimeter
dm	decimeter
m	meter
km	kilometer
thou, mil	thousandth of an inch
in	inch
ft	feet
yd	yard
mi	mile

Length base units example script

    include <omdl-base.scad>;
 
    length_unit_base = "mm";
    length_unit_default = "in";
 
    // get unit names
    bu = length_unit_name(length_unit_base);
    du = length_unit_name();
 
    // absolute length measurements in base unit.
    c1 = length(1/8);
    c2 = length(3.175, "mm");
    c3 = length(25, "mil");
    c4 = length(1, "ft", d=3);
 
    // convert between units.
    c5 = length(10, from="mil", to="in");
    c6 = length(10, from="ft", to="mm");
 
    // end_include

length_unit_base=mm script output

ECHO: bu = "millimeter"
ECHO: du = "inch"
ECHO: 
ECHO: c1 = 3.175
ECHO: c2 = 3.175
ECHO: c3 = 0.635
ECHO: c4 = 2.83168e+7
ECHO: c5 = 0.01
ECHO: c6 = 3048

length_unit_base=cm script output

ECHO: bu = "centimeter"
ECHO: du = "inch"
ECHO: 
ECHO: c1 = 0.3175
ECHO: c2 = 0.3175
ECHO: c3 = 0.0635
ECHO: c4 = 28316.8
ECHO: c5 = 0.01
ECHO: c6 = 3048

length_unit_base=mil script output

ECHO: bu = "mil (thousandth)"
ECHO: du = "inch"
ECHO: 
ECHO: c1 = 125
ECHO: c2 = 125
ECHO: c3 = 25
ECHO: c4 = 1.728e+12
ECHO: c5 = 0.01
ECHO: c6 = 3048

length_unit_base=in script output

ECHO: bu = "inch"
ECHO: du = "inch"
ECHO: 
ECHO: c1 = 0.125
ECHO: c2 = 0.125
ECHO: c3 = 0.025
ECHO: c4 = 1728
ECHO: c5 = 0.01
ECHO: c6 = 3048

Equivalent lengths diagram

top

Function and/or Module Documentation

length_unit_name()

function length_unit_name	(	u	= length_unit_default,
		d	= 1,
		w	= false
	)

Return the name for a length unit identifier with dimension.

Parameters

u	<string> A length unit identifier.
d	<integer> The unit dimension. One of [1|2|3].
w	<boolean> true for word and false for symbol format.

Returns

<string> The long name for a length unit identifier with dimension. Returns undef for identifiers or dimensions that are not defined.

length()

function length	(	v	,
		from	= length_unit_default,
		to	= length_unit_base,
		d	= 1
	)

Convert a length value from one unit to another, with optional dimensional scaling.

Parameters

v	<decimal-list | decimal> The value to convert. May be a list when d = 1; must be a scalar when d = 2 or 3.
from	<string> The units of the value to be converted. Defaults to length_unit_default.
to	<string> The units to which the value should be converted. Defaults to length_unit_base.
d	<integer> The unit dimension. One of [1|2|3].

Returns

<decimal> The conversion result. For d = 1 returns the converted value; for d = 2 or 3 returns the converted linear value raised to the corresponding power. Returns undef for identifiers, dimensions, or input types that are not defined.

Here is the caller graph for this function:

length_inv()

function length_inv	(	v	,
		from	= length_unit_base,
		to	= length_unit_default,
		d	= 1
	)

Recover a linear length from an area or volume value, then convert units.

Parameters

v	<decimal> The area or volume value to invert. Must be a scalar for d = 2 or 3; may be a list for d = 1.
from	<string> The units of the input value v. Defaults to length_unit_base.
to	<string> The units to which the recovered linear value should be converted. Defaults to length_unit_default.
d	<integer> The unit dimension. One of [1|2|3].

Returns

<decimal> The linear conversion result. For d = 1 converts v directly; for d = 2 takes the square root of v before converting; for d = 3 takes the cube root. Returns undef for identifiers, dimensions, or input types that are not defined.

l_mm()

function l_mm	(	v	,
		d	= 1
	)

Shorthand length conversion for millimeters.

Parameters

v	<decimal> The value to convert.
d	<integer> The unit dimension. One of [1|2|3].

Returns

<decimal> The conversion result.

l_in()

function l_in	(	v	,
		d	= 1
	)

Shorthand length conversion for inches.

Parameters

v	<decimal> The value to convert.
d	<integer> The unit dimension. One of [1|2|3].

Returns

<decimal> The conversion result.

Variable Documentation

length_unit_base

length_unit_base = "mm"

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

Definition at line 982 of file length.scad.

length_unit_default

length_unit_default = "mm"

<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 length functions that omit the from or u parameter will assume this unit.

Definition at line 988 of file length.scad.