{"id":13418433,"url":"https://github.com/mapbox/polylabel","last_synced_at":"2025-05-13T19:16:34.259Z","repository":{"id":45081797,"uuid":"62902729","full_name":"mapbox/polylabel","owner":"mapbox","description":"A fast algorithm for finding the pole of inaccessibility of a polygon (in JavaScript and C++)","archived":false,"fork":false,"pushed_at":"2024-11-18T16:19:52.000Z","size":126,"stargazers_count":1464,"open_issues_count":16,"forks_count":152,"subscribers_count":152,"default_branch":"master","last_synced_at":"2025-04-27T20:05:25.902Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mapbox.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2016-07-08T16:34:29.000Z","updated_at":"2025-04-20T21:46:49.000Z","dependencies_parsed_at":"2024-01-06T00:09:35.154Z","dependency_job_id":"3e7a39ed-8dc4-4aa0-b31b-c227b615f913","html_url":"https://github.com/mapbox/polylabel","commit_stats":null,"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mapbox%2Fpolylabel","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mapbox%2Fpolylabel/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mapbox%2Fpolylabel/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mapbox%2Fpolylabel/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mapbox","download_url":"https://codeload.github.com/mapbox/polylabel/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254010822,"owners_count":21999003,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-07-30T22:01:02.289Z","updated_at":"2025-05-13T19:16:34.190Z","avatar_url":"https://github.com/mapbox.png","language":"C++","readme":"## polylabel [![CI](https://github.com/mapbox/polylabel/actions/workflows/test.yml/badge.svg)](https://github.com/mapbox/polylabel/actions/workflows/test.yml) [![Simply Awesome](https://img.shields.io/badge/simply-awesome-brightgreen.svg)](https://github.com/mourner/projects)\n\nA fast algorithm for finding polygon _pole of inaccessibility_,\nthe most distant internal point from the polygon outline (not to be confused with centroid),\nimplemented as a JavaScript library.\nUseful for optimal placement of a text label on a polygon.\n\nIt's an iterative grid algorithm,\ninspired by [paper by Garcia-Castellanos \u0026 Lombardo, 2007](https://sites.google.com/site/polesofinaccessibility/).\nUnlike the one in the paper, this algorithm:\n\n- guarantees finding **global optimum** within the given precision\n- is many times faster (10-40x)\n\n![](https://cloud.githubusercontent.com/assets/25395/16745865/864a0a30-47c0-11e6-87bc-58acac41a520.png)\n\n### How the algorithm works\n\nThis is an iterative grid-based algorithm, which starts by covering the polygon with big square cells and then iteratively splitting them in the order of the most promising ones, while aggressively pruning uninteresting cells.\n\n1. Generate initial square cells that fully cover the polygon (with cell size equal to either width or height, whichever is lower). Calculate distance from the center of each cell to the outer polygon, using negative value if the point is outside the polygon (detected by ray-casting).\n2. Put the cells into a priority queue sorted by the maximum potential distance from a point inside a cell, defined as a sum of the distance from the center and the cell radius (equal to `cell_size * sqrt(2) / 2`).\n3. Calculate the distance from the centroid of the polygon and pick it as the first \"best so far\".\n4. Pull out cells from the priority queue one by one. If a cell's distance is better than the current best, save it as such.\nThen, if the cell potentially contains a better solution that the current best (`cell_max - best_dist \u003e precision`),\nsplit it into 4 children cells and put them in the queue.\n5. Stop the algorithm when we have exhausted the queue and return the best cell's center as the pole of inaccessibility.\nIt will be guaranteed to be a global optimum within the given precision.\n\n![image](https://cloud.githubusercontent.com/assets/25395/16748630/e6b3336c-47cd-11e6-8059-0eeccf22cf6b.png)\n\n### JavaScript Usage\n\nGiven polygon coordinates in\n[GeoJSON-like format](http://geojson.org/geojson-spec.html#polygon) (an array of arrays of `[x, y]` points)\nand precision (`1.0` by default),\nPolylabel returns the pole of inaccessibility coordinate in `[x, y]` format. The distance to the closest polygon point (in input units) is included as a `distance` property.\n\n```js\nconst p = polylabel([[[0, 0], [1, 0], ...]], 1.0);\nconst distance = p.distance;\n```\n\nBe careful to pick precision appropriate for the input units. E.g. in case of geographic coordinates (longitude and latitude), `0.000001` is appropriate, while the default (`1.0`) would be too imprecise.\n\n### TypeScript\n\n[TypeScript type definitions](https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/polylabel)\nare available via `npm install --save @types/polylabel`.\n\n### C++ Usage\n\nIt is recommended to install polylabel via [mason](https://github.com/mapbox/mason). You will also need to install its dependencies: [geometry.hpp](https://github.com/mapbox/geometry.hpp) and [variant](https://github.com/mapbox/variant).\n\n```C++\n#include \u003cmapbox/polylabel.hpp\u003e\n\nint main() {\n    mapbox::geometry::polygon\u003cdouble\u003e polygon = readPolygon(); // Get polygon data from somewhere.\n    mapbox::geometry::point\u003cdouble\u003e p = mapbox::polylabel(polygon, 1.0);\n    return 0;\n}\n```\n\n#### Ports to other languages\n\n- [andrewharvey/geojson-polygon-labels](https://github.com/andrewharvey/geojson-polygon-labels) (CLI) \n- [Twista/python-polylabel](https://github.com/Twista/python-polylabel) (Python)\n- [Shapely](https://github.com/Toblerity/Shapely/blob/master/shapely/algorithms/polylabel.py) (Python)\n- [polylabelr](https://CRAN.R-project.org/package=polylabelr) (R)\n- [polylabel-rs](https://github.com/urschrei/polylabel-rs) (Rust)\n- [php-polylabel](https://github.com/dliebner/php-polylabel) (PHP)\n- [dart_polylabel](https://github.com/beroso/dart_polylabel) (Dart)\n- [ruby-polylabel](https://github.com/fredplante/ruby-polylabel) (Ruby)\n- [Polylabel.jl](https://github.com/asinghvi17/Polylabel.jl) (Julia)\n- [geobase](https://github.com/navibyte/geospatial/blob/main/dart/geobase/lib/src/geometric/cartesian/areal/polylabel.dart) (Dart)\n","funding_links":[],"categories":["TODO scan for Android support in followings","C++"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmapbox%2Fpolylabel","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmapbox%2Fpolylabel","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmapbox%2Fpolylabel/lists"}