isValid2DBoundingBox

[M-Scott-Lassiter]

Description

Bounding boxes are an optional GeoJSON property that describe a box of longitude boundaries that run along meridians and latitude boundaries that are parallel to the equator. A 2D Bounding Box only describes longitude and latitude boundaries, whereas a 3D BBox describes an additional min and max altitude/depth value.

A GeoJSON object MAY have a member named "bbox" to include information on the coordinate range for its Geometries, Features, or FeatureCollections. The value of the bbox member MUST be an array of length 2*n where n is the number of dimensions represented in the contained geometries, with all axes of the most southwesterly point followed by all axes of the more northeasterly point. The axes order of a bbox follows the axes order of geometries.

The "bbox" values define shapes with edges that follow lines of constant longitude, latitude, and elevation.
~ https://datatracker.ietf.org/doc/html/rfc7946#section-5

Format

The values of a "bbox" array are [west, south, east, north], not [minx, miny, maxx, maxy].
~https://datatracker.ietf.org/doc/html/rfc7946#appendix-B.1

The Antimeridian

In the case of objects spanning the antimeridian, a bounding box becomes required.

Consider a set of point Features within the Fiji archipelago, straddling the antimeridian between 16 degrees S and 20 degrees S. The southwest corner of the box containing these Features is at 20 degrees S and 177 degrees E, and the northwest corner is at 16 degrees S and 178 degrees W. The antimeridian-spanning GeoJSON bounding box for this FeatureCollection is

"bbox": [177.0, -20.0, -178.0, -16.0]

and covers 5 degrees of longitude. The complementary bounding box for the same latitude band, not crossing the antimeridian, is

"bbox": [-178.0, -20.0, 177.0, -16.0]

and covers 355 degrees of longitude.

The latitude of the northeast corner is always greater than the latitude of the southwest corner, but bounding boxes that cross the antimeridian have a northeast corner longitude that is less than the longitude of the southwest corner.
~https://datatracker.ietf.org/doc/html/rfc7946#section-5.2

The Poles

An area that encompasses either the north or south pole will also require a bounding box that meets special use cases.

A bounding box that contains the North Pole extends from a southwest corner of "minlat" degrees N, 180 degrees W to a northeast corner of 90 degrees N, 180 degrees E. Viewed on a globe, this bounding box approximates a spherical cap bounded by the "minlat" circle of latitude.

"bbox": [-180.0, minlat, 180.0, 90.0]

A bounding box that contains the South Pole extends from a southwest corner of 90 degrees S, 180 degrees W to a northeast corner of "maxlat" degrees S, 180 degrees E.

"bbox": [-180.0, -90.0, 180.0, maxlat]

A bounding box that just touches the North Pole and forms a slice of an approximate spherical cap when viewed on a globe extends from a southwest corner of "minlat" degrees N and "westlon" degrees E to a northeast corner of 90 degrees N and "eastlon" degrees E.

"bbox": [westlon, minlat, eastlon, 90.0]

Similarly, a bounding box that just touches the South Pole and forms a slice of an approximate spherical cap when viewed on a globe has the following representation in GeoJSON.

"bbox": [westlon, -90.0, eastlon, maxlat]

Implementers MUST NOT use latitude values greater than 90 or less than -90 to imply an extent that is not a spherical cap.
~https://datatracker.ietf.org/doc/html/rfc7946#section-5.3

Boundaries

Any values outside of the WGS-84 standards should fail.

WGS84 Bounds: -180.0000, -90.0000, 180.0000, 90.0000
Projected Bounds: -180.0000, -90.0000, 180.0000, 90.0000
~ https://spatialreference.org/ref/epsg/wgs-84/
Also, see https://datatracker.ietf.org/doc/html/rfc7946#section-4

Although not explicitly stated, it can be inferred that the north value must be larger than the south value.

Valid GeoJSON Examples

Example of a 2D bbox member on a Feature:

{
    "type": "Feature",
    "bbox": [-10.0, -10.0, 10.0, 10.0],
    "geometry": {
        "type": "Polygon",
        "coordinates": [
            [
                [-10.0, -10.0],
                [10.0, -10.0],
                [10.0, 10.0],
                [-10.0, -10.0]
            ]
        ]
    }
}

Example of a 2D bbox member on a FeatureCollection:

{
    "type": "FeatureCollection",
    "bbox": [100.0, 0.0, 105.0, 1.0],
         "features": [
             ...
         ]
}

Example of a 2D bbox on a feature with a FeatureCollection that also has a bounding box:

{
    "type": "FeatureCollection",
    "bbox": [-100.0, -10, 10, 49.5],
         "features": [
             {
                 "type": "Feature",
                 "bbox": [-10.0, -10.0, 10.0, 10.0],
                 "geometry": {
                     ...
                 }
             },
             ...
         ]
}

Example of a 2D bbox that crosses the antimeridian:

{
    "type": "FeatureCollection",
    "bbox": [177.0, -20.0, -178.0, -16.0],
         "features": [
             ...
         ]
}

Example Matcher Usage

expect([-10.0, -10.0, 10.0, 10.0]).isValid2DBoundingBox()
expect([100.0, 0.0, 105.0, 1.0]).isValid2DBoundingBox()
expect([177.0, -20.0, -178.0, -16.0]).isValid2DBoundingBox() // Crosses antimeridian and spans 5 degrees

expect([-10.0, -10.0, 10.0, 100.0]).not.isValid2DBoundingBox() // North out of bounds
expect([100.0, 0.0, -100.0, 105.0, 1.0, 0.0]).not.isValid2DCoordinate() // 3D bounding box
expect({ bbox: [-10.0, -10.0, 10.0, 10.0] }).not.isValid2DCoordinate() // Object instead of bbox array

Passing Tests

Values in Range

• Each quadrant
  • NW: [-20, 10, -10, 20]
  • NE: [10, 10, 20, 20]
  • SW: [-20, -20, -10, -10]
  • SE: [10, -20, 20, -10]
• Spanning all quadrants
  • Prime meridian: [-10, -20, 20, 10]
  • Antimeridian: [170, -20, -170, 20]

Values at Edge Cases

• Longitude Boundaries:
  • West: [-180, 10, 20, 20]
  • North: [10, 10, 180, 20]
• Poles with Cap
  • North: [-180.0, 80, 180.0, 90.0]
  • South: [-180.0, -90, 180.0, -80.0]
• Poles not Including Cap
  • North: [10, 80, 20, 90.0]
  • South: [-45, -90, -80, -80.0]
• Spanning all longitudes
  • All longitudes: [-180, 10, 180, 20]
  • All latitudes: [-10, -90, 10, 90]
  • Whole Earth: [-180, -90, 180, 90]
• Northern Boundary Equals Southern:
  • [-10, -20, 10, -20]
  • [-10, 20, 10, 20]
• Eastern Boundary Equals Western
  • [-10, -20, -10, 20]
  • [10, -20, 10, 20]
• All zeros
  • [0, 0, 0, 0]

Failing Tests

Bbox input not an array

• undefined
• null
• Booleans: true, false
• Numbers: 200, -200, Infinity, -Infinity, NaN
• Objects: { bbox: [10, 10, 20, 20] }
• Strings: '', 'Random Coordinate', '[10, 10, 20, 20]'

Incorrect number of array elements

• [ ], [20], [20, 10], [20, 30, 0], [20, 30, 0, 0, 10], [20, 30, 0, 20, 30, 0], [20, 30, 0, 20, 30, 0, 20, 30, 0]

Coordinates out of range

• Latitude: [-10, -90.0000001, 10, 0], [-10, 0, 10, 90.0000001], [-10, -90000, 10, 0], [-10, 0, 10, 90000]
• Longitude: [-180.0000001, -10, -160, 10], [160, -10, 180.0000001, 10], [-1800000, -10, -160, 10], [160, -10, 1800000, 10]
• Combination:
  • [-181, -10, 181, 10]
  • [-10, -91, 10, 91]
  • [-181, -91, 10, 10]
  • [-10, -10, 181, 91]
  • [-181, -91, 181, 91]

Illogical BBox

• Northern Boundary Less Than Southern: [-10, 20, 10, -20]

BBox has non-numeric values

• Each of the values in "Bbox input not an array" paired with valid inputs:
  • [<value>, -10, 10, 10]
  • [-10, <value>, 10, 10]
  • [-10, -10, <value>, 10]
  • [-10, -10, 10, <value>]
  • [<value>, <value>, <value>, <value>]

BBox values are arrays of numbers

[[-20], [10], [-10], [20]]

[M-Scott-Lassiter]

🎉 This issue has been resolved in version 1.0.0-beta.4 🎉

The release is available on:

• npm package (@beta dist-tag)
• GitHub release

Your semantic-release bot 📦🚀

[M-Scott-Lassiter]

🎉 This issue has been resolved in version 1.0.0 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀