Inspired by the map function in the creative coding framework Processing and its counterpart ofMap in openFrameworks. Especially useful for creative coding applications, e.g. animations.
The value 0.5
in the range [0,1] should return as 50
in the range [0,100]:
const result = remap(0.5, [0,1], [0, 100]); // result === 50
The value 10% should count as as 100% minus 10% (i.e. 90%) if we are counting backwards, i.e.
const result = remap(10, [0, 100], [100, 0]); // notice reversed output range; result === 90
// A pixel in the middle of the screen, normalised in the range [0,1]
const [x, y] = [0.5, 0.5]
// Convert it to a position on display with dimensions 1920x1080
const [px, py] = remapCoords([x,y], [1,1], [1920,1080])
console.log(px, py) // "960, 540"
You'll see the value of x
modulate from -1 to 1 smoothly over time.
The remapping keeps the result in a range between 10 and 1000 (mm? who knows)
const start = Date.now();
setInterval(() => {
const elapsed = Date.now() - start;
const x = Math.sin(elapsed / 1000);
const height = remap(x, [-1, 1], [10, 1000])
console.log(elapsed, x, height);
}, 40)
Basic remapping of a value from one range to another.
remap (value, inputRange, targetRange, clamp, shouldRound)
...where the parameters are:
value
: a numberinputRange
,targetRange
: arrays of exactly 2 elements each, i.e[min,max]
clamp
(optional; defaultfalse
): whether to constrain the result within the given target rangeshouldRound
(optional; defaultfalse
): whether to round to nearest integer, i.e. only whole numbers
Provide the range (inputMin
, inputMax
) that your value
is currently in, and specify a new range (outputMin
, outputMax
) and you'll get back a new value as per the target range.
Remap many values at once.
remapArray (values, inputRange, targetRange, clamp, shouldRound)
... where the parameters are the same as above, except that values
is an array values, not a single value.
Remap coordinates in multiple dimensions.
remapCoords (inputCoords, inputDimensions, targetDimensions, clamp, shouldRound
Given a set of "coordinates" in X dimensions,
inputCoords
is an array representing coordinates in X dimensions, i.e. should have a length of XinputDimensions
is an array representing maximum extents for the input coordinate system, one per dimension. Should therefore also have a length of XtargetDimensions
is an array representing maximum extents for the target coordinate system you want to remap your coordinates to. Should therefore also have a length of X
Keep in mind:
- The minimum extent for each dimension is always assumed to be zero (
0
) - Unlike
remap
andremapArray
, the default forshouldRound
istrue
because this is convenient for normalised-to-pixel translations which is the most common use case
npm install @anselan/maprange
Import the basics:
import { remap } from '@anselan/maprange'
...or import other functions you need:
import { remap, remapArray, remapCoords } from '@anselan/maprange'
If you cannot use import
, try require
:
const { remap } = require('@anselan/maprange`)
Differs from the following similar JS packages:
- map-range and @compactjs/remap do not include optional clamping
- range-map always rounds resulting numbers
None of the above provide the following convenience features:
remapArray
remapCoords
Hopefully, you also find the array-format ranges ([0,1]
, etc.) more readable than the APIs referenced above, too.