Working with geometries

The turf.js library is recommended for working with GeoJSON. The sections below describe using this library together with MapGL JS API.

Bounding box (bbox)

The turf.bbox method calculates a rectangular area that contains given objects or a group of objects.

const line = turf.lineString([
    [34, 40],
    [36, 41],
    [41, 37],
    [48, 42],
    [42, 35],
]);
const bbox = turf.bbox(line); // [minX, minY, maxX, maxY]

Method documentation: @turf/bbox

Usage examples

• Position the map so that all objects are fit into the screen using the map.fitBounds method.

  map.fitBounds({ southWest: bbox.slice(0, 2), northEast: bbox.slice(2, 4) });

• Request additional data. For example, request nearest construction objects when you have municipal area polygons.

Bounding box is the most common and fast way to define boundaries of objects location. The downside is that the boundaries are defined roughly. If you need higher precision, use a convex hull.

Convex hull

The turf.convex method takes an object or a group of objects and creates a convex hull based on them.

const line = turf.lineString([
    [34, 40],
    [36, 41],
    [41, 37],
    [48, 42],
    [42, 35],
]);
const convexHull = turf.convex(line);

Method documentation: @turf/convex

Usage example

Convex hull is a more precise (compared to the bounding box) method of defining object boundaries. The downside is high computational complexity of this method.

Buffer around an object

The turf.buffer method enables enlarging or reducing an object proportionally.

const line = turf.lineString([
    [34, 40],
    [36, 41],
    [41, 37],
    [48, 42],
    [42, 35],
]);
const buffer = turf.buffer(line, 40);

Method documentation: @turf/buffer

Usage examples

• Display various types of security zones, isolation areas, and others.

• Display places equally distant from an object on the map.

  However, this works good only for small distances (up to 50-100 m). Calculation of larger distances is affected by the method of turf.buffer calculations. Distances are calculated purely geometrically while in reality the shortest geometric way usually contains obstacles: houses, rivers, fences, which must be bypassed. In this case, you should use isochrones as a more precise and specialized tool.

Getting a center (centroid)

The turf.center, turf.centroid, and turf.centerOfMass methods enable getting a particular center of an object or a group of objects.

const polygon = turf.polygon([
    [
        [34, 40],
        [36, 41],
        [41, 37],
        [48, 42],
        [42, 35],
        [34, 40],
    ],
]);
const center = turf.center(polygon);
const centroid = turf.centroid(polygon);
const centerOfMass = turf.centerOfMass(polygon);

Method documentation:

• @turf/center,
• @turf/centroid,
• @turf/centerOfMass.

Usage examples

You can get a center in three ways:

• center gets the center of a bounding box of an object or a group.
• centroid calculates a barycenter of an object or a group.
• centerOfMass gets the center of mass of a figure.

On convex and symmetric polygons, these methods show almost no difference. In case of non-convex or other irregular polygons, centerOfMass works best.

Using these methods is convenient for placing object captions.

Nearest point

The turf.nearestPoint method gets the nearest point from the set of points.

const line = turf.lineString([
    [34, 40],
    [36, 41],
    [41, 37],
    [48, 42],
    [42, 35],
]);
const target = turf.point([38, 38]);

const points = turf.explode(line);
const nearest = turf.nearestPoint(target, points);

Method documentation: @turf/nearestPoint

The method feature is working only with a set of points. To transform an object into a set of points, use the @turf/explode method.

Usage example

Find the nearest object to the given one.

Nearest point on a line

The turf.nearestPointOnLine method gets the nearest point to the given one on a line or a group of lines.

const line = turf.lineString([
    [34, 40],
    [36, 41],
    [41, 37],
    [48, 42],
    [42, 35],
]);
const target = turf.point([38, 38], { name: 'Target' });

const nearestOnLine = turf.nearestPointOnLine(line, target);

Method documentation: @turf/nearestPointOnLine

Usage example

Find the nearest point on a route or a road. Like the turf.buffer method, it works in the simplest cases only when considering obstacles is not required. In other cases, use the Routing API.

Union

The turf.union method combines multiple figures into one.

const points = [
    [10, 10],
    [12, 10],
];
const circleA = turf.buffer(turf.point([10, 10]), 300);
const circleB = turf.buffer(turf.point([12, 10]), 300);
const united = turf.union(circleA, circleB);

Method documentation: @turf/union

Usage examples

• Display an area formed by multiple objects as one object on the map.
• Assemble overly fragmented objects, which often happens during geodata handling.

Intersection

The turf.intersect method find a figure formed by an intersection of given figures.

const points = [
    [10, 10],
    [12, 10],
];
const circleA = turf.buffer(turf.point([10, 10]), 300);
const circleB = turf.buffer(turf.point([12, 10]), 300);
const intersected = turf.intersect(circleA, circleB);

Method documentation: @turf/intersect

Usage example

Display an area formed by an intersection of other areas on the map. For example, a free parking lot within a given radius from an object.

Mask

The turf.mask method enables turning a polygon "inside out": turning its surrounding area into a polygon.

const poly = turf.polygon([
    [
        [0, 0],
        [0, 2],
        [2, 2],
        [2, 0],
        [0, 0],
    ],
]);
turf.mask(poly);

Method documentation: @turf/mask

Usage example

Draw attention to one or multiple areas on the map and obscure the remaining space.

Simplification

The turf.simplify method simplifies a geometry using the Ramer–Douglas–Peucker algorithm.

const gpsTrack = turf.lineString([
    [0, 0],
    [0, 0.1],
    [0.5, 0.5],
    [1, 0.5],
]);
const simplifiedTrack = turf.simplify(gpsTrack, { tolerance: 0.2 });
// { ... geometry: { ..., coordinates: [[0, 0], [0.5, 0.5], [1, 0.5]] } }

The simplification degree is defined by the tolerance parameter, which specifies the maximum error that the algorithm can make during simplification. The tolerance value has the same dimension as the source data: if geocoordinates are specified in degrees, tolerance must be in degrees too.

Method documentation: @turf/simplify

Usage examples

• Get less complicated geometries, which are rendered faster.
• Filter data when it is known that their precision must not exceed specific value.
• Display precise data on a large scale: simplified geometries have more aesthetic outlook and smoother lines without visual noise.