A lightweight library for converting units of length

another-dimension helps to convert between various units of length, with a focus on units used for screen presentation (physical screen pixels) and visual perception experiments (arcminutes, arcseconds).

Why another unit conversion library?

Lightweight, only supporting length units, no dependencies. If you are looking for general conversion of various units, consider js-quantities, convert-units, convert or others.
Support for angular dimensions (degrees, arcminutes and arcseconds) which depend on viewing distance and involve trigonometric calculations in the conversion.
Support for physical screen pixels taking into account the (configurable) pixel density.
Global configuration of pixel density and viewing distance for accurate conversion from/to physical screen pixels and angular length units, as often needed for accurate reproduction of perceptual experiments and user studies.
Modern-style, function-based, highly configurable implementation.
100% test coverage.

another-dimension was created as part of the stimsrv project to support the accurate specification of dimensions for screen-based psychological experiments.

`another-dimension` in a Nutshell

const Dimension = require('another-dimension');

// Simple use case: unit conversion

// Create some dimensions
let width  = Dimension("10mm");       // 10 mm
let length = Dimension("1.8in");      // 1.8 inch

console.log("Metric length: " + length.toString("mm"));
// => "Metric length: 45.72mm"

// Optional: Configuration of global settings
Dimension.configure({
  defaultOutputUnit: "px", // convert to pixels when value is used as Number
  defaultUnit: "px",       // default unit to use if no unit is specified
  pixelDensity: 440,       // 440ppi, pixel density of HiDPI smartphone 
                           //   (used to convert pixel sizes)
  viewingDistance: 350     // 350mm viewing distance (typical for smartphone use),
                           //   (used to convert angular dimensions)
});

// Create more dimensions
let height = Dimension(50, "arcmin"); // 50 angular minutes
let depth  = Dimension(50);           // 50 pixels (as per defaultUnit specified above)

// Dimension objects can be used in place of numeric primitives, 
// and will implicitly be converted to pixels (as configured above per defaultOutputUnit)
// This will draw a 173.2 x 88.2 pixel rectangle!
canvasContext2D.fillRect(0, 0, width, height);

// Dimension containing the length of the diagonal in pixels (set as defaultUnit above)
let diagonal = Dimension(Math.sqrt(width ** 2 + height ** 2));

// Ouptut diagonal length in mm, using 2 digits precision
console.log("Diagonal length: " + diagonal.toString("mm",2));
// => "Diagonal length: 11.22mm"

Installation & Import

Node.js

npm install another-dimension

CommonJS require() syntax:

const Dimension = require('another-dimension');

ES module import syntax:

import Dimension from 'another-dimension';

Browser

For direct use in the browser, download the file another-dimension.js and load it using a <script> tag.

<script src="another-dimension.js"></script>

<script>
let dim = Dimension("1in");
console.log(dim.toString("mm")); // -> 25.4mm
</script>

By default, another-dimension is made available as a global variable named Dimension. You can change the name of the global variable by adding an attribute data-another-dimension-global to the script tag, specifying the global name to use for the Dimension object.

<script src="another-dimension.js" data-another-dimension-global="AnotherDimension"></script>

<script>
let dim = AnotherDimension("1in");
console.log(dim.toString("mm")); // -> 25.4mm
</script>

Note: another-dimension works out of the box like this for prototyping in modern browsers. For compatibility with older browsers and optimized delivery consider compiling your project code, including this library, using Babel or similar tools.

API Documentation

Creating Dimensions

`Dimension(spec[, options])`

Can be used with new as constructor, or without as a factory function.

let lengthA = new Dimension("12mm");   // Constructor syntax

let lengthB = Dimension("12mm");       // Factory syntax

spec can be a Number, a String, or an Object providing a value and optional unit entry.

// String providing value + unit
let lengthA = Dimension("12mm");   

// Object providing value and (optionally) unit
let lengthB = Dimension({value: 12, unit: "mm"});

// Number will use default unit (initially "mm")
let lengthC = Dimension(12);

options can be a String specifying the unit, or an object with some of the following entries:

options.defaultUnit Unit to use if not specified, overrides global default unit.

// specify value and unit separately
let lengthA = Dimension(12, "mm");   

// specify defaultUnit in options
let lengthB = Dimension(12, {defaultUnit: "in"});  // => 12 inches

// specified unit takes precedence over options.defaultUnit
let lengthC = Dimension("12mm", {defaultUnit: "in"});  // => 12 mm

Retrieving and converting Dimensions

`dimensionInstance.toDimension(targetUnit)`

Returns a new Dimension instance, converted to the targetUnit.

let dim = Dimension("1in");

let dimMM = dim.toDimension("mm");  // Dimension with value: 25.4 and unit: "mm"

`dimensionInstance.toNumber(targetUnit)`

Returns the dimension converted to targetUnit, as a Number. If targetUnit is not specified, return the unconverted value.

let dim = Dimension("1in");

let mm = dim.toNumber("mm");  // 25.4
let inches = dim.toNumber();  // 1

`dimensionInstance.toString([targetUnit], [digits])`

Returns a String representation of the dimension (e.g. "12.1mm").

targetUnit Unit to convert to.

digits Number of digits after the comma to include.

let dim = Dimension("1.8in");

let mmStr = dim.toString("mm");       // "45.72mm"
let mmRound = dim.toString("mm", 1);  // "45.7mm"
let round = dim.toString(2);          // "1.80in"

`dimensionInstance.toFixed([digits[, targetUnit]])`

Returns a String representation of the numeric value of the dimension with fixed precision (e.g. "12.1"), similar to the JavaScript builtin `Number.toFixed().

digits Number of digits after the comma to include. If omitted, it is considered 0, i.e. rounding to full integer.

targetUnit Unit to convert to.

let dim = Dimension("1.8in");

let fixed = dim.toFixed(2);          // "1.80"
let mmFixed = dim.toFixed(1, "mm");  // "45.7"
let round = dim.toFixed();           // "2"

`dimensionInstance.toJSON()`

Returns a plain JavaScript object containing entries for value and unit, unless configured otherwise by setting the toJSON option with Dimension.configure().

`dimensionInstance.valueOf()`

Returns the numeric value of the dimension converted to the globally configured defaultOutputUnit, or the unconverted value if defaultOutputUnit has not been set.

This method is called internally by the JavaScript interpreter when a Dimension object is used in place of a primitive value, and is provided for this purpose. It should generally rarely be called explicitly (use dimensionInstance.toNumber(), dimensionInstance.toFixed() or dimensionInstance.toString() for better control over the output instead).

Using Dimensions as primitives

For Objects involved in numeric calculations, the JavaScript interpreter internally calls .valueOf() on the Object before performing the operation. By default, valueOf() of Dimension instances returns their (unconverted) numerical value. If the global option defaultOutputUnit is set, the value is converted to the specified unit first.

let dim = Dimension("1in");

console.log(dim + dim);  // 2

Dimension.configure({
  defaultOutputUnit: "mm"
});

console.log(dim + dim);  // 50.8

Global Configuration

`Dimension.configure(options)`

Set global configuration options.

options is an object containing global configuration options.

Option	Default	Description
`defaultUnit`	`"mm"`	Default unit to use when creating Dimension instances.
`defaultOutputUnit`	`null`	Unit to convert to when a Dimension instance is used as a primitive value. `null` uses the object's specified unit (so no conversion takes place).
`anchorUnit`	`"mm"`	Unit to try as intermediate unit when no direct conversion from source to target unit is available.
`pixelDensity`	`96`	Pixel density (in pixels-per-inch) to use for converting pixel values.
`viewingDistance`	`600`	Viewing distance (in mm) to use for converting angular dimensions. The default of 600mm is often used for "Desktop" settings, for mobile phones use 300-350mm.
`aliases`	see Supported Units	A key-value map of unit aliases, e.g. `{'"': 'in'}` to use the " character as an alias for inches. Warning: setting this here will overwrite the internal alias table. Use `Dimension.addAlias()` to add aliases to the internal alias table.
`toJSON`	see above	Function to use for `.toJSON()` of Dimension instances. Takes a Dimensions object as parameter, returns its JSON representation (plain JS Object).
`dimensionRegEx`	see below	The regular expression used to parse dimension Strings. Has to define two named groups `value` and `unit`, which will be used to extract the numeric value and unit specifier from the String.

Default config.dimensionRegEx: /^\s*(?<value>-?[0-9]*\.?[0-9]+)\s*(?<unit>[^\s\d]+)\s*$/

(This allows for padding whitespace, whitespace separating value and unit, and special characters (but no digits) in the unit specifier.)

`Dimension.addConversion(fromUnit, toUnit, factorOrFunction)`

Add a conversion, specified as a fixed conversion factor or a function.

fromUnit String specifying the unit to convert from.

toUnit String specifying the unit to convert to.

factorOrFunction either a Number, specifying a fixed conversion factor, or a Function that will be called for each conversion with the following parameters:

value the value to convert.
config the global configuration object (see Dimension.configure()).

To introduce a new unit, you only need to supply a conversion to and from the anchorUnit (by default: "mm") as a bare minimum.

Example:

// (these conversions are already built in and serve only for illustration purposes)

// to convert from inch to mm, multiply with 25.4
Dimension.addConversion("in", "mm", 25.4);

// to convert from inches to pixels, multiply with config.pixelDensity
Dimension.addConversion("in", "px", (v, config) => v * config.pixelDensity);

`Dimension.addAlias(unit, alias)`

Add an alias (alternative name) for a unit. The aliases will be considered before any conversion. Warning: Aliases are not looked up recursively, so each alias has to refer to a unit which is actually specified (i.e. for which conversions are either built in or have been specified using Dimension.addConversion()).

unit A String specifying the base unit.

alias A String or an Array of Strings, specifying alias name(s).

Example:

// " is not configured as an alias for inches by default, as it may be confused with arcseconds.

// to use " as an alias for inches
Dimension.addAlias("in", '"');

let length = Dimension('12"');

console.log(length.toString());
// => 12in

Global Helpers

`Dimension.getConversionFunction(fromUnit, toUnit[, options])`

Return a specific conversion function. The returned function will accept a single parameter - the value to convert - and will return the converted value.

fromUnit String specifying the unit to convert from.

toUnit String specifying the unit to convert to.

options Object with some of the following entries:

options.freezeConfig: If set to true, the current configuration (e.g. pixelDensity, viewingDistance) will be "frozen", so that subsequent changes to those parameters won't affect the conversion function. If not set (the default), changes to the global configuration will affect the conversion performed by the returned function, if applicable.

let conv = Dimension.getConversionFunction("in", "mm");

let mm = conv(1);   // 25.4

`Dimension.unAlias(unit)`

Returns the canonical unit referenced by the given alias, or the unit passed in if no such alias is defined.

let unit = Dimension.unAlias("°");

console.log(unit);
// => "deg"

`Dimension.parseDimensionString(dimensionString)`

Parses a String into a plain JS object containing entries for value and unit, using the built-in or configured dimensionRegEx regular expression.

If the String contains no unit but a number, the defaultUnit is used as unit.

If neither dimensionRegEx nor number match, the function returns null.

`Dimension.getUnits()`

Returns an Array containing all currently configured Dimensions (without aliases).

Supported Units

The list of built-in units is deliberately kept short. New units can be added quickly by providing conversion functions or factors (at minimum to and from the global base unit config.anchorUnit) using Dimension.addConversion()

Metric Units

Unit / Aliases	Description	mm
`km`	Kilometer	10^6
`m`	Meter	10^3
`cm`	Centimeter	10
`mm`	Millimeter	1
`µ` / `µm` / `um`	Micrometer	10^-3

Imperial Units

Unit / Aliases	Description	mm
`in`	Inch	25.4
`thou`	Thousandths of an Inch	0.0254

Typesetting Units

Unit / Aliases	Description	mm
`pc`	(DTP) Pica (1/6in)	≈4.23
`pt`	(DTP) Point (1/12pc)	≈0.353
`twip`	Twip (1/20pt)	≈0.0176

Screen Units

Unit / Aliases	Description	mm
`px`	Physical Screen Pixel	Varying, depending on `config.pixelDensity` (≈0.265mm @ 96dpi)

Angular Units

Unit / Aliases	Description	mm
`deg` / `°`	Angular Degree	Varying, depending on `config.viewingDistance` (≈10.5mm @ 600mm)
`arcmin`	Arc Minute	Varying, depending on `config.viewingDistance` (≈0.175mm @ 600mm)
`arcsec`	Arc Second	Varying, depending on `config.viewingDistance` (≈0.003mm @ 600mm)

Test coverage report

File	% Stmts	% Branch	% Funcs	% Lines
another-dimension.js	100	100	100	100

Credits

another-dimension was created by Florian Ledermann as part of the stimsrv project.

License: MIT License.

"I'll take your brains to another dimension ... pay close attention!" — In memoriam Keith Flint / The Prodigy

another-dimension

A lightweight library for converting units of length

another-dimension in a Nutshell

Installation & Import

Node.js

Browser

API Documentation

Creating Dimensions

Dimension(spec[, options])

Retrieving and converting Dimensions

dimensionInstance.toDimension(targetUnit)

dimensionInstance.toNumber(targetUnit)

dimensionInstance.toString([targetUnit], [digits])

dimensionInstance.toFixed([digits[, targetUnit]])

dimensionInstance.toJSON()

dimensionInstance.valueOf()

Using Dimensions as primitives

Global Configuration

Dimension.configure(options)

Dimension.addConversion(fromUnit, toUnit, factorOrFunction)

Example:

Dimension.addAlias(unit, alias)

Example:

Global Helpers

Dimension.getConversionFunction(fromUnit, toUnit[, options])

Dimension.unAlias(unit)

Dimension.parseDimensionString(dimensionString)

Dimension.getUnits()

Supported Units

Metric Units

Imperial Units

Typesetting Units

Screen Units

Angular Units

Test coverage report

Credits

Versions

Current Tags

Version History

Package Sidebar

Install

Repository

Homepage

DownloadsWeekly Downloads

Version

License

Unpacked Size

Total Files

Last publish

Collaborators

`another-dimension` in a Nutshell

`Dimension(spec[, options])`

`dimensionInstance.toDimension(targetUnit)`

`dimensionInstance.toNumber(targetUnit)`

`dimensionInstance.toString([targetUnit], [digits])`

`dimensionInstance.toFixed([digits[, targetUnit]])`

`dimensionInstance.toJSON()`

`dimensionInstance.valueOf()`

`Dimension.configure(options)`

`Dimension.addConversion(fromUnit, toUnit, factorOrFunction)`

`Dimension.addAlias(unit, alias)`

`Dimension.getConversionFunction(fromUnit, toUnit[, options])`

`Dimension.unAlias(unit)`

`Dimension.parseDimensionString(dimensionString)`

`Dimension.getUnits()`

Weekly Downloads