Bounding Box Utility Functions

0.20.2 · active · verified Sun Apr 19

bbox-fns is a lightweight JavaScript library offering a collection of modular utility functions for common geospatial bounding box operations. Bounding boxes are consistently represented as a four-element array: `[xmin, ymin, xmax, ymax]`. Currently at version 0.20.2, the library maintains a relatively frequent release cadence, often introducing new functions or minor fixes, with updates typically occurring every few weeks or months. Its key differentiator lies in its 'super light-weight' design and modular structure, where most functions reside in their own file. This approach facilitates granular imports, allowing developers to include only the specific utilities needed, thereby contributing to smaller bundle sizes. It focuses exclusively on core bounding box manipulations rather than broader GIS features.

Common errors

```
TypeError: require is not a function
```
cause Attempting to use CommonJS `require()` in an environment or module context configured for ES Modules (ESM). The `bbox-fns` library is primarily distributed as ESM.

fix Refactor your import statements to use ESM syntax, such as `import functionName from 'bbox-fns/function-name.js';`. Ensure your project's `package.json` correctly sets `"type": "module"` if you intend to use ESM throughout, or use `.mjs` file extensions for ESM files.
```
Error: Points must not contain NaN values (thrown by bboxArray before v0.20.0)
```
cause Input array of points to functions like `bboxArray` contained `NaN` (Not-a-Number) values, and the function was called without a `nan_strategy` option. Before `v0.20.0`, this would always throw an error.

fix Upgrade to `bbox-fns v0.20.0` or higher and provide the `nan_strategy` option: `bboxArray(points, { nan_strategy: 'skip' })` to filter out `NaN` values, or `bboxArray(points, { nan_strategy: 'error' })` to explicitly control the error behavior. Alternatively, pre-filter your input points to remove `NaN` values.

Warnings

breaking Prior to `v0.20.0`, functions like `bboxArray` would throw an error if any input points contained `NaN` values. The introduction of the `nan_strategy` option in `v0.20.0` (and `v0.20.2` fixing a related bug) changes this behavior, allowing developers to explicitly 'skip' or 'error' on `NaN`s. Existing code that relied on implicit error-throwing for `NaN` inputs might now behave differently if `nan_strategy: 'skip'` is applied.
Fix: For `bboxArray` and `reproject` functions, explicitly specify `{ nan_strategy: 'skip' }` in the options to ignore `NaN` values or implement pre-filtering of points to remove `NaN`s if strict error handling is desired.
gotcha This library is distributed as ES Modules (ESM) and its examples consistently use `import` statements with explicit `.js` file extensions. Attempting to use CommonJS `require()` syntax will result in errors in Node.js environments that treat the package as ESM.
Fix: Always use `import` statements with the full path including the `.js` extension (e.g., `import functionName from 'bbox-fns/function-name.js';`). If running in Node.js, ensure your project is configured for ESM (e.g., `"type": "module"` in `package.json` or using `.mjs` files).

Install

npm install bbox-fns npm
yarn add bbox-fns yarn
pnpm add bbox-fns pnpm

Imports

bboxArea
wrong:
```
const bboxArea = require('bbox-fns/bbox-area');
```
correct:
```
import bboxArea from 'bbox-fns/bbox-area.js';
```
The library primarily uses ES Modules with explicit file paths. Attempting to use CommonJS `require` or named imports from the root package for individual functions will lead to errors.
bboxArray
wrong:
```
import { bboxArray } from 'bbox-fns'; // Incorrect named import for file-based modules
```
correct:
```
import bboxArray from 'bbox-fns/bbox-array.js';
```
Each utility is a default export from its specific file. Destructuring from the main package import is not supported.
booleanContains
wrong:
```
const { booleanContains } = require('bbox-fns');
```
correct:
```
import booleanContains from 'bbox-fns/boolean-contains.js';
```
Ensure you include the `.js` extension in import paths when using ESM in environments like Node.js where it's not always implicitly handled.

Quickstart

Demonstrates calculating a bounding box from an array of points, handling NaN values, then calculating its area, and finally checking for intersection with another bounding box.

import bboxArray from 'bbox-fns/bbox-array.js';
import bboxArea from 'bbox-fns/bbox-area.js';
import booleanIntersects from 'bbox-fns/boolean-intersects.js';

// Define a set of points for a polygon ring
const points = [
  [-180, 86.06126914660831],
  [-180, 85.66739606126914],
  [NaN, 84.87964989059081], // Point with NaN value
  [-179, 84.48577680525165]
];

// Calculate the bounding box, skipping NaN values
const calculatedBbox = bboxArray(points, { nan_strategy: 'skip' });
console.log('Calculated Bounding Box (skipping NaN):', calculatedBbox);

// Calculate the area of the bounding box
const area = bboxArea(calculatedBbox);
console.log('Area of the bounding box:', area);

// Define another bounding box
const referenceBbox = [-10, -20, 10, 20];

// Check if the calculated bbox intersects with the reference bbox
const intersects = booleanIntersects(calculatedBbox, referenceBbox);
console.log('Does the calculated bbox intersect with reference bbox?', intersects);

view raw JSON →