Node Trilateration

1.0.0 · active · verified Sun Apr 19

node-trilateration is a JavaScript module designed to solve the 2D trilateration problem, enabling the calculation of a device's position based on its distances to three known beacon locations. Operating at version 1.0.0, this package provides a straightforward implementation of the geometric principles, where three circles (representing beacons with their distances as radii) are used to determine a unique intersection point. The library's core function takes an array of three beacon objects, each with `x`, `y` coordinates and a `distance`, and returns the calculated `x`, `y` position of the device. It focuses on this specific mathematical task without extensive abstractions, making it a concise solution for applications requiring basic 2D positioning from distance measurements. There is no stated release cadence, suggesting a stable, single-purpose utility.

Common errors

```
TypeError: Cannot read properties of undefined (reading 'x')
```
cause The `beacons` array passed to `trilateration.calculate` was empty, contained non-object elements, or was not an array.

fix Ensure the input to `trilateration.calculate` is an array of exactly three objects, each having `x`, `y`, and `distance` numeric properties.
```
TypeError: trilateration.calculate is not a function
```
cause The module was imported incorrectly, or `calculate` was attempted to be called as a named export when it is a method on the default export.

fix Use `const trilateration = require('node-trilateration');` then `trilateration.calculate(beacons);` for CommonJS. For ESM, try `import trilateration from 'node-trilateration';` (though compatibility might vary) and then `trilateration.calculate(beacons);`.
```
ReferenceError: beacons is not defined
```
cause The `beacons` array was not declared or initialized before being passed to the `calculate` function.

fix Declare and initialize the `beacons` array with the three required beacon objects before calling `trilateration.calculate`.

Warnings

gotcha The `node-trilateration` package is designed exclusively for 2D trilateration. It does not support 3D positioning calculations and will not work correctly for scenarios requiring Z-axis coordinates.
Fix: Ensure your problem space is strictly two-dimensional or use a different library designed for 3D trilateration/multilateration.
gotcha The `calculate` function strictly requires an array containing exactly three beacon objects. Providing fewer or more than three beacons will lead to incorrect results or runtime errors, as the underlying mathematical model relies on three distinct reference points.
Fix: Always pass an array with precisely three beacon objects, each containing valid `x`, `y`, and `distance` numeric properties.
gotcha The library assumes valid geometric input. Edge cases such as colinear beacons, distances that make a solution impossible (e.g., circles not intersecting), or highly ambiguous geometries might result in inaccurate or unexpected position calculations without explicit error handling or warnings from the library.
Fix: Implement robust input validation for beacon positions and distances in your application code. Consider preprocessing beacon data or adding custom checks for geometric validity if precise error handling is critical.
gotcha Input validation within the library for non-numeric or malformed `x`, `y`, or `distance` properties on beacon objects is minimal. Providing invalid data types could lead to `TypeError` exceptions during arithmetic operations.
Fix: Ensure that all `x`, `y`, and `distance` values within your beacon objects are valid numbers before passing them to the `calculate` function.

Install

npm install node-trilateration npm
yarn add node-trilateration yarn
pnpm add node-trilateration pnpm

Imports

trilateration
wrong:
```
import trilateration from 'node-trilateration';
```
correct:
```
const trilateration = require('node-trilateration');
```
This package is primarily a CommonJS module. While bundlers might allow ES Module syntax, the native Node.js experience is via `require`.
calculate
wrong:
```
import { calculate } from 'node-trilateration';
```
correct:
```
const { calculate } = require('node-trilateration');
```
The `calculate` function is the primary API, directly exposed by the module's default export.
trilateration.calculate
wrong:
```
const pos = calculate(beacons);
```
correct:
```
const trilateration = require('node-trilateration');
const pos = trilateration.calculate(beacons);
```
The `calculate` function is a method on the `trilateration` object (the module's export), not a direct named export.

Quickstart

This example demonstrates how to install `node-trilateration`, define three beacon locations with their respective distances, and use the `calculate` function to determine and log the device's estimated (x, y) coordinates. It showcases the core functionality for 2D positioning.

const trilateration = require('node-trilateration');

// Define three beacons with their coordinates and distances to the device.
// These distances represent the radii of circles centered at each beacon.
const beacons = [
	{x: 2, y: 4, distance: 5.7},
	{x: 5.5, y: 13, distance: 6.8},
	{x: 11.5, y: 2, distance: 6.4}
];

// Perform the trilateration calculation to find the device's position.
const pos = trilateration.calculate(beacons);

// Log the calculated (x, y) coordinates of the device.
console.log(`Calculated device position: X: ${pos.x}; Y: ${pos.y}`);
// Expected output: Calculated device position: X: 7; Y: 6.5 (approximately)

view raw JSON →