multiPolygon

Creates a MultiPolygon geometry from an array of polygon coordinates or an array of Polygons.

Each polygon must consist of an array of linear rings coordinates. The first ring represents the exterior ring (shell), subsequent rings represent interior rings (holes). Each ring must be a closed line string with first and last positions identical and contain at least 3 positions. Empty polygons without any rings are allowed.

Type Parameters

• P

Parameters

Name	Type	Default	Description
data	Position[][][] | Polygon[]		MultiPolygon coordinates or an array of Polygons
options?	object		Optional geometry options
options.id?	number | string		Optional identifier to be assigned to the geometry instance.
options.properties?	P		Optional data to be assigned to the geometry instance.
options.layout?	'XY' | 'XYZ' | 'XYZM' | 'XYM'	'XYZM'	Coordinate layout for interpreting GeoJSON coordinates. Defines how to interpret the coordinates of input geometries. This does not force the dimension of the resulting geometries - the actual geometry dimension will be determined from the parsed data. Use this to: Trim unwanted Z or M ordinates from the input. Treat the third ordinate as M instead of Z.
options.consume?	boolean	false	Whether to consume the input geometries - consumed geometries become detached, are no longer valid and should not be used. When true the ownership of input geometries is passed to created collection geometry, no extra copies are made, but the input geometries can no longer be used on their own. When false the clones of input geometries are used to create a collection geometry.

Returns

MultiPolygon<P>

A new MultiPolygon geometry

Throws

• InvalidGeoJSONError if any ring is invalid (not closed or with 1 or 2 positions)
• GEOSError when any of the input geometries is not a Polygon

Examples

// from coordinates
const a = multiPolygon([
    [ [ [ 1, 0 ], [ 0, 1 ], [ 1, 1 ], [ 1, 0 ] ] ],
    [ [ [ 1, 1 ], [ 1, 2 ], [ 2, 1 ], [ 1, 1 ] ] ],
]);
const b = multiPolygon([
    [ [ [ 0, 1 ], [ 1, 2 ], [ 1, 1 ], [ 0, 1 ] ] ],
    [ [ [ 1, 0 ], [ 1, 1 ], [ 2, 1 ], [ 1, 0 ] ] ],
], { properties: { name: 'B' } });

// from polygon geometries
const parts = [
    polygon([ [ [ 0, 0 ], [ 0, 1 ], [ 1, 0 ], [ 0, 0 ] ] ]),
    polygon([ [ [ 1, 2 ], [ 2, 2 ], [ 2, 1 ], [ 1, 2 ] ] ]),
];
const c = multiPolygon(parts, { id: 'C' });
const consumableParts = [
    polygon([ [ [ 0, 1 ], [ 0, 2 ], [ 1, 2 ], [ 0, 1 ] ] ]),
    polygon([ [ [ 1, 0 ], [ 2, 1 ], [ 2, 0 ], [ 1, 0 ] ] ]),
];
const d = multiPolygon(consumableParts, { consume: true });
// all `consumableParts` are detached

// from coordinates const a = multiPolygon([ [ [ [ 1, 0 ], [ 0, 1 ], [ 1, 1 ], [ 1, 0 ] ] ], [ [ [ 1, 1 ], [ 1, 2 ], [ 2, 1 ], [ 1, 1 ] ] ], ]); const b = multiPolygon([ [ [ [ 0, 1 ], [ 1, 2 ], [ 1, 1 ], [ 0, 1 ] ] ], [ [ [ 1, 0 ], [ 1, 1 ], [ 2, 1 ], [ 1, 0 ] ] ], ], { properties: { name: 'B' } }); // from polygon geometries const parts = [ polygon([ [ [ 0, 0 ], [ 0, 1 ], [ 1, 0 ], [ 0, 0 ] ] ]), polygon([ [ [ 1, 2 ], [ 2, 2 ], [ 2, 1 ], [ 1, 2 ] ] ]), ]; const c = multiPolygon(parts, { id: 'C' }); const consumableParts = [ polygon([ [ [ 0, 1 ], [ 0, 2 ], [ 1, 2 ], [ 0, 1 ] ] ]), polygon([ [ [ 1, 0 ], [ 2, 1 ], [ 2, 0 ], [ 1, 0 ] ] ]), ]; const d = multiPolygon(consumableParts, { consume: true }); // all `consumableParts` are detached