snap-bbox

> Snap a Bounding Box to a Grid

| before | after |
| ------ | ----- |
| the bounding box partially cuts off some of the pixel grid cells | the bounding box expands to the pixel grid cell boundaries |
| !before | !before |

why

I often try to pull pixel values from GeoTIFFs to display on a web map.
However, the pixels are often displayed in a different projection (like web mercator)
than the projection of the data (often 4326).
Because our pixels are in a structured array and you can't request only part of an array item (try running [1, 2, 3][0.5]), we have to snap our bounding box to the grid structure of our data.

install

``bash
npm install snap-bbox
`

basic usage

`js
const snap = require("snap-bbox");

const result = snap({
// a bounding box as [xmin, ymin, xmax, ymax]
// in the same spatial reference system as the grid
// example below is equivalent to the bounds of a web mercator tile at x=2154, y=3243 and z=13
bbox: [ -85.341796875, 35.02999636902566, -85.2978515625, 35.06597313798418 ],

// the origin of the grid, which is often the top left corner
// example below is the north pole, [180th meridian, top of the world]
origin: [-180, 90],

// the size of each grid cell in [width, height]
// width or height can be negative, which in the case below indicates that
// the y value in the spatial reference system (e.g. latitude) decreases
// as the y-value in cell grid space increases
// This is equivalent to the ModelPixelScaleTag in GeoTIFF Metadata
// http://geotiff.maptools.org/spec/geotiff2.6.html
scale: [0.083333333333333, -0.083333333333333],

// an optional array of two numbers, which represents
// x-padding (horizontal) and y-padding (vertical)
// the padding is applied to both sides of the bbox along an axis.
// in the example below with x-padding of 3 and y-padding of 0,
// the width of the result will increase by 6 grid cells, being padded
// on both the left and right by 3 grid cells.
padding: [3, 0],

// another bbox that limits how much "bbox" can be expanded via snapping and padding
// in the example below, we contain the result to the northern hemisphere
container: [ -180, 0, 180, 90 ]
});
`
result will be something like:
`js
{
bbox_in_coordinate_system: [
// xmin (longitude in this case)
-85.66666666666706,

// ymin (latitude in this case)
35.00000000000022,

// xmax (longitude in this case)
-85.00000000000038,

// ymax (latitude in this case)
35.083333333333556
],

bbox_in_grid_cells: [
// xmin, the number of grid cells from the left edge of the grid
1132,

// ymin, the number of grid cells from the top edge of the grid
660,

// xmax, the number of grid cells from the left edge of the grid
1140,

// ymax, the number of grid cells from the top edge of the grid
659
]
}
`

advanced precise mode


If you require the highest level of precision, you can use snap-bbox in "precise" mode.
Precise mode avoids floating point arithmetic issues. When using precise mode,
all numbers must be passed in as numerical strings and all output numbers will be
represented as strings. snap-bbox uses preciso
for precise numerical computations.
`js
// you can also directly require the precise snapping function
// with require("snap-bbox/lib/snap-precise-bbox.js")
// but this filepath is subject to change between versions
const snap = require("snap-bbox");

const result = snap({
bbox: [ "-85.341796875", "35.02999636902566", "-85.2978515625", "35.06597313798418" ],
origin: ["-180", "90"],
scale: ["0.083333333333333", "-0.083333333333333"],
padding: ["3", "0"],
container: ["-180", "0", "180", "90"],
precise: true
});
`
result will use precise numerical strings:
`js
{
bbox_in_coordinate_system: [
"-85.666666666667044",
"35.00000000000022",
"-85.00000000000038",
"35.083333333333553"
],
bbox_in_grid_cells: [
"1132",
"660",
"1140",
"659"
]
}
`

limiting to edge of finite grid


If the grid has a fixed height and width, you can limit the result to the boundary of the grid
`js
snap({
...options,
size: [width, height],
overflow: false // prevent overflow over the boundaries of the grid
});
``