toBeMultiPolygonGeometry

[M-Scott-Lassiter]

Description

This is a building block matcher. Geometries are the basis of all objects, and we need a way to reliably test that they have been formatted appropriately.

This matcher focuses only on "MultiPolygon". All coordinates must be valid coordinates per the WGS-84 standard. Any non-conforming values should fail. However, the "coordinates" property MAY have an empty array ([ ]) as a valid value. It MAY NOT have an array of empty arrays as a value ([ [ [ ], [ ] ] ]).

A Geometry object represents points, curves, and surfaces in coordinate space. Every Geometry object is a GeoJSON object no matter where it occurs in a GeoJSON text.

• The value of a Geometry object's "type" member MUST be one of the seven geometry types (per Section 1.4: "Point", "MultiPoint", "LineString", "MultiLineString", "Polygon", "MultiPolygon", and "GeometryCollection").
• A GeoJSON Geometry object of any type other than "GeometryCollection" has a member with the name "coordinates". The value of the "coordinates" member is an array. The structure of the elements in this array is determined by the type of geometry. GeoJSON processors MAY interpret Geometry objects with empty "coordinates" arrays as null objects.

~ https://datatracker.ietf.org/doc/html/rfc7946#section-3.1

For type "MultiPolygon", the "coordinates" member is an array of Polygon coordinate arrays.

~ https://datatracker.ietf.org/doc/html/rfc7946#section-3.1.7

The geometry object should have a "type" and a "coordinates" property. It is prohibited from having a "geometry", "properties", or "features" property.

Implementations MUST NOT change the semantics of GeoJSON members and types.

The GeoJSON "coordinates" and "geometries" members define Geometry objects. FeatureCollection and Feature objects, respectively, MUST NOT contain a "coordinates" or "geometries" member.

The GeoJSON "geometry" and "properties" members define a Feature object. FeatureCollection and Geometry objects, respectively, MUST NOT contain a "geometry" or "properties" member.

The GeoJSON "features" member defines a FeatureCollection object. Feature and Geometry objects, respectively, MUST NOT contain a "features" member.
https://datatracker.ietf.org/doc/html/rfc7946#section-7.1

Although illogical, it is NOT PROHIBITED from having a "geometries" property, although if present it would be considered a foreign member.

Other foreign members ARE allowed (see https://datatracker.ietf.org/doc/html/rfc7946#section-6.1). None of these foreign members should get checked for validity of any type; they may contain anything that is valid JSON.

See GeoJSON Spec: What does it mean to extend GeoJSON without using a foreign member? for further clarification.

Bounding boxes, if present, must validate (see isValidBoundingBox).

A GeoJSON object represents a Geometry, Feature, or collection of Features.

~ https://datatracker.ietf.org/doc/html/rfc7946#section-3

A GeoJSON object MAY have a member named "bbox" to include information on the coordinate range for its Geometries, Features, or FeatureCollections.

~ https://datatracker.ietf.org/doc/html/rfc7946#section-5

Valid GeoJSON MultiPolygon Examples

Two polygons, one without a hole and one with:

{
    "type": "MultiPolygon",
    "coordinates": [
        [
            [
                [102.0, 2.0],
                [103.0, 2.0],
                [103.0, 3.0],
                [102.0, 3.0],
                [102.0, 2.0]
            ]
        ],
        [
            [
                [100.0, 0.0],
                [101.0, 0.0],
                [101.0, 1.0],
                [100.0, 1.0],
                [100.0, 0.0]
            ],
            [
                [100.2, 0.2],
                [100.2, 0.8],
                [100.8, 0.8],
                [100.8, 0.2],
                [100.2, 0.2]
            ]
        ]
    ]
}

A single polygon:

{
    "type": "MultiPolygon",
    "coordinates": [
        [
            [
                [102.0, 2.0],
                [103.0, 2.0],
                [103.0, 3.0],
                [102.0, 3.0],
                [102.0, 2.0]
            ]
        ]
    ]
}

Antimeridian Cutting:

{
    "type": "MultiPolygon",
    "coordinates": [
        [
            [
                [180.0, 40.0], [180.0, 50.0], [170.0, 50.0],
                [170.0, 40.0], [180.0, 40.0]
            ]
        ],
        [
            [
                [-170.0, 40.0], [-170.0, 50.0], [-180.0, 50.0],
                [-180.0, 40.0], [-170.0, 40.0]
            ]
        ]
    ]
}

An empty coordinates

{
    "type": "MultiPolygon",
    "coordinates": [ ]
}

In each case, the matcher should only get passed the object in its entirety, not the individual components, and not as part of another collection object.

Example Matcher Usage

const multiPolygon = {
    "type": "MultiPolygon",
    "coordinates": [
        [
            [
                [102.0, 2.0],
                [103.0, 2.0],
                [103.0, 3.0],
                [102.0, 3.0],
                [102.0, 2.0]
            ]
        ],
        ...
    ]
}
const multiLineString = {
    type: "MultiLineString",
    coordinates: [
        [
            [100.0, 0.0],
            [101.0, 0.0],
            [101.0, 1.0],
            [100.0, 1.0],
            [100.0, 0.0]
        ]
    ]
}

expect(multiPolygon).toBeMultiPolygonGeometry()

expect(multiLineString).not.toBeMultiPolygonGeometry()
expect(multiPolygon.coordinates).not.toBeMultiPolygonGeometry()

Passing Tests

This matcher should use core functions to test coordinate validity. Either two or three digit coordinates are allowed.

Values in Range

• Counterclockwise wound
  • 2D points, 3D points, Mixed 2D and 3D
  • Both without and with holes
• Clockwise wound
  • 2D points, 3D points, Mixed 2D and 3D
  • Both without and with holes
• Cutting the antimeridian
• Spanning the antimeridian
  • Note: this is an assumption inferred from proximity. No way to tell without a bounding box on a polygon feature
• Redundant
  • Exterior ring all the same point
  • Interior rings all the same point
  • Interior rings outside exterior rings
• Stressed: A 30 element multi polygon, each element containing 30 coordinates

const testMultiPolygon = {
    type: "MultiPolygon",
    coordinates: [
        [<input>]
    ]
}

• Empty Coordinate

const testMultiPolygon = {
    type: "MultiPolygon",
    coordinates: [ ]
}

Foreign Properties Allowed

• ID (String and number input: 'Test 1', 1

const testMultiPolygon = {
    type: "MultiPolygon",
    id: <input>,
    coordinates: ...
}

• Non alphanumeric ID
  ID Normally needs to be a letter or number, but because it is a foreign member on a geometry object, the GeoJSON standard takes no consideration about it.

const testMultiPolygon1 = {
    type: "MultiPolygon",
    id: null,
    coordinates: [
        [
            [[0, 0], [0, 1], [1, 1], [1, 0], [0, 0]]
        ]
    ]
}

• Geometries

const testMultiPolygon2 = {
    type: "MultiPolygon",
    geometries: testMultiPolygon1,
    coordinates: [
        [
            [[0, 0], [0, 1], [1, 1], [1, 0], [0, 0]]
        ]
    ]
}

• Multiple

const testMultiPolygon3 = {
    type: "MultiPolygon",
    someRandomProp: true,
    geometries: testMultiPolygon2,
    coordinates: [
        [
            [[0, 0], [0, 1], [1, 1], [1, 0], [0, 0]]
        ]
    ]
}

May Have Optional Bounding Box

• Logical
  • 2D: [-10.0, -10.0, 10.0, 10.0]
  • 3D: [-10.0, -10.0, 0, 10.0, 10.0, 200]

const testMultiPolygon = {
    type: 'MultiPolygon',
    coordinates: [
        [
            [[0, 0], [0, 1], [1, 1], [1, 0], [0, 0]]
        ]
    ],
    bbox: <input>
}

• Illogical

const testMultiPolygon = {
    type: 'MultiPolygon',
    coordinates: [
        [
            [[0, 0], [0, 1], [1, 1], [1, 0], [0, 0]]
        ]
    ],
    bbox: [-30.0, -30.0, -20.0, -20.0]
}

• Redundant

const testMultiPolygon = {
    type: 'MultiPolygon',
    coordinates: [
        [
            [[0, 0], [0, 0], [0, 0], [0, 0], [0, 0]]
        ]
    ],
    bbox: [0, 0, 0, 0]
}

Failing Tests

Geometry Input Not an Object

Any of the following inputs to the matcher should fail:

• undefined
• null
• Booleans: true, false
• Numbers: 200, -200, Infinity, -Infinity, NaN
• Arrays:
  • [[0, 0], [0, 1], [1, 1], [1, 0], [0, 0]]
  • [1, 1]
  • [ ]
• Strings: '', 'Random Geometry', '[0, 0]', '[[[[0, 0], [0, 1], [1, 1], [1, 0], [0, 0]]]]'
• Stringified JSON:

  JSON.stringify({
    type: "MultiPolygon",
    coordinates: [
        [
            [[0, 0], [0, 1], [1, 1], [1, 0], [0, 0]]
        ]
    ]
  })

Invalid Coordinates

• Each of the values from "Geometry Input Not an Object":

const testMultiPolygon= {
    type: "MultiPolygon",
    coordinates: [
        [
            [[0, 0], [0, 1], [1, 1], <input>, [0, 0]]
        ]
    ]
}

Coordinates Out of Range

This only tests a handful of invalid coordinates to verify behavior. Detailed coordinate validation occurs in isValidCoordinate

Input:

• [[181, 0], [0, 1], [1, 1], [1, 0], [181, 0]]
• [[0, 0], [0, 91], [1, 1], [1, 0], [0, 0]]
• [[0, 0], [0, 1], [-181, 1], [1, 0], [0, 0]]
• [[0, -181], [0, 1], [1, 1], [1, 0], [0, -181]]
• [[0, 0, 0, 0]]

const testMultiPolygon= {
    type: "MultiPolygon",
    coordinates: [
        [<input>]
    ]
}

Not Enough Coordinates

• The each polygon linestring array in coordinates must have four or more positions.

Input:

• [[[0, 0]]]
• [[[0, 0], [1, 1]]]
• [[[0, 0], [1, 1]], [[1, 0]]]

const testMultiPolygon= {
    type: "MultiPolygon",
    coordinates: [<input>]
}

Final Coordinate does not Match First Coordinate

Input:

• [[0, 0], [0, 1], [1, 1], [1, 0]]
• [[0, 0], [0, 1], [1, 1], [1, 0], [0, 0]], [[0, 0], [0, 1], [1, 1], [1, 0]]
• [[0, 0], [0, 1], [1, 1], [1, 0], [[0, 0], [0, 1], [1, 1], [1, 0], [0, 0]]

const testMultiPolygon= {
    type: "MultiPolygon",
    coordinates: [
        [<input>]
    ]
}

Type Value Incorrect

Input:

• Each of the values from "Geometry Input Not an Object", plus
• 'Point', 'MultiPoint', 'LineString', 'MultiLineString', 'Polygon', and 'GeometryCollection', or
• 'MULTIPOLYGON', 'multipolygon'

Input:

• [[[0, 0]]]
• [[[0, 0], [1, 1]]]
• [[[0, 0], [1, 1]], [[1, 0]]]

const testMultiPolygon= {
    type: "MultiPolygon",
    coordinates: <input>
}

Contains Prohibited Properties

Geometry

const testMultiPolygon = {
    type: "MultiPolygon",
    coordinates: [
        [
            [[0, 0], [0, 1], [1, 1], [1, 0], [0, 0]]
        ]
    ],
    geometry: {
        type: "Point",
        coordinates: [102.0, 0.5]
    }
}

Properties

const testMultiPolygon = {
    type: "MultiPolygon",
    coordinates: [
        [
            [[0, 0], [0, 1], [1, 1], [1, 0], [0, 0]]
        ]
    ],
    properties: {
        prop1: true
    }
}

Features

const testMultiPolygon = {
    type: "MultiPolygon",
    coordinates: [
        [
            [[0, 0], [0, 1], [1, 1], [1, 0], [0, 0]]
        ]
    ],
    features: [{
        type: "Feature",
        geometry: {
            type: "Point",
            coordinates: [102.0, 0.5]
            },
        properties: {
           prop0: "value0"
        }
    }]
}

Missing Required Properties

• No Type

const testMultiPolygon = {
    coordinates: [
        [
            [[0, 0], [0, 1], [1, 1], [1, 0], [0, 0]]
        ]
    ]
}

• No Coordinates

const testMultiPolygon = {
    type: "MultiPolygon"
}

Coordinates is an Array of Null Arrays

• Test for 1x, 2x, 3x
• No Type

const testMultiPolygon = {
    type: "MultiPolygon",
    coordinates: [[[[<arrays>]]]]
}

Invalid Bounding Box

• null
• undefined
• []
• Missing Element: [-10.0, -10.0, 10.0]
• Out of Range Element: [-10.0, -10.0, 190.0, 10.0]
• South Greater than North: [-10.0, 10.0, 10.0, -10]
• Bad altitude: [-10.0, -10.0, 0, 10, 10.0, '200']

const testMultiPolygon = {
    type: 'MultiPolygon',
    coordinates: [
        [
            [[0, 0], [0, 1], [1, 1], [1, 0], [0, 0]]
        ]
    ],
    bbox: <input>
}

[M-Scott-Lassiter]

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

The release is available on:

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

Your semantic-release bot 📦🚀

[M-Scott-Lassiter]

Reopening to add coverage to validate optional bounding boxes.

[M-Scott-Lassiter]

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

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 📦🚀