Polylabel is a fast algorithm for finding the pole of inaccessibility of a polygon, the most distant internal point from the polygon outline, implemented as a JavaScript library.

Useful for optimal placement of a text label on a polygon.

Polylabel Documentation

Introduction

Polylabel is a utility for finding the optimal placement of a label within a polygon. It uses various techniques such as the pole of inaccessibility to find the most distant point from the polygon's edges, ensuring the label is placed in the most central location.

Class and Function Signatures

TinyQueue

A priority queue implementation.

class TinyQueue {
    TinyQueue(data: Array, compare: Function): TinyQueue
    void push(item: Any): void
    Any pop(): Any
    Any peek(): Any
    void _up(pos: Number): void
    void _down(pos: Number): void
}

Rectangle

A class for representing rectangles and checking for collisions.

class Rectangle {
    static Rectangle fromXYWH(x: Number, y: Number, width: Number, height: Number): Rectangle
    static Rectangle fromAABB(ax: Number, ay: Number, bx: Number, by: Number): Rectangle
    static Rectangle fromLatLon(ll1: Object, ll2: Object): Rectangle
    static Rectangle fromLatLng(ll1: Object, ll2: Object): Rectangle

    Rectangle(x: Number, y: Number, width: Number, height: Number, mode: String = 'xywh'): Rectangle

    Number getArea(): Number
    Object getTopLeft(): Object
    Object getTopRight(): Object
    Object getBottomLeft(): Object
    Object getBottomRight(): Object

    static Boolean isColliding(rect1: Rectangle, rect2: Rectangle): Boolean
    static Rectangle resolveCollision(rect1: Rectangle, rect2: Rectangle): Rectangle
}

computeGeoJSONCentroids

Compute centroids for a GeoJSON feature collection.

Array computeGeoJSONCentroids(featureCollection: Object): Array

polylabel

Find the pole of inaccessibility for a polygon.

Array polylabel(polygon: Array, precision: Number = 1.0, debug: Boolean = false, centroidWeight: Number = 0): Array

polylabel.stretched

Find the pole of inaccessibility for a stretched polygon.

Array polylabel.stretched(rings: Array, ratio: Number): Array

polylabel.getLabelPos

Get the best label position for a GeoJSON geometry.

Array polylabel.getLabelPos(geometry: Object): Array

Example Usage

Here is an example of using the polylabel.getLabelPos function with a custom implementation using stretch ratio and options:

const geojsonFeature = {
    "type": "Feature",
    "geometry": {
        "type": "Polygon",
        "coordinates": [
            [
                [-73.96943, 40.78519],
                [-73.96082, 40.78095],
                [-73.95269, 40.78404],
                [-73.95796, 40.79070],
                [-73.96541, 40.79449],
                [-73.96943, 40.78519]
            ]
        ]
    }
};

const ratio = 1.5;

function customGetLabelPos(geometry, ratio, options = {}) {
    let pos;
    if (geometry.type === 'MultiPolygon') {
        let maxDist = 0;
        for (const polygon of geometry.coordinates) {
            const p = polylabel.stretched(polygon, ratio);
            if (p.distance > maxDist) {
                pos = p;
                maxDist = p.distance;
            }
        }
    } else {
        pos = polylabel.stretched(geometry.coordinates, ratio);
    }
    return pos;
}

const labelPos = customGetLabelPos(geojsonFeature.geometry, ratio);
console.log(labelPos); // Outputs the best label position for the polygon