#geo #polylabel #gis

app polylabel_cmd

A command-line utility for finding optimum polygon label positions

27 releases (5 stable)

1.4.0 Feb 3, 2021
1.2.3 Dec 3, 2018
1.2.0 May 27, 2018
1.0.0 Apr 18, 2018
0.0.19 Dec 30, 2017

#7 in #geojson

43 downloads per month

MIT license

21KB
378 lines

Linux / macOS Build Status Windows Build status Crates Link

polylabel_cmd

…is the command-line version of Polylabel. Install it using cargo install polylabel_cmd, or download a binary and put it on your $PATH.
This provides the polylabel command.

Use

Polylabel takes one mandatory argument: a file containing valid GeoJSON containing Polygons and / or MultiPolygons to be labelled. They can be included as a Feature, or a Geometry, or aFeatureCollection or GeometryCollection – you may also mix the two geometries in a FeatureCollection or GeometryCollection.

  • Processing of nested GeometryCollections is supported, but you shouldn't be using those
  • Empty geometries or collections will be left unaltered
  • Non Multi(Polygon) geometries will be left unaltered
  • All properties will be left unaltered

You may also pass:

  • -t or --tolerance, allowing you to fine-tune the tolerance from the default 0.001. Smaller tolerances take longer to calculate
  • -p or --pretty, which will pretty-print the GeoJSON output
  • -s or --stats-only, which will output the number of labelled polygons, but will not output GeoJSON.

Irrespective of input, output is a GeoJSON FeatureCollection. Its contents depend on the input geometry:

  • Polygon: The FeatureCollection contains Point Features
  • MultiPolygon: The FeatureCollection contains MultiPoint Features
  • GeometryCollection: The FeatureCollection contains GeometryCollection Features whose collection members are Points or MultiPoints
  • Other geometries are included in one the above outputs, but are otherwise left unaltered.

Output features retain the order of input features / geometries, and input feature properties are mapped to output features where they exist.

Accuracy

Depending upon the dimensions of your polygon(s), you may require a higher tolerance (i.e. a smaller number) than the default. See here for some guidance on the accuracy provided by each decimal place. The GeoJSON spec recommends a maximum of six decimal places, which provides accuracy around 10cm, which translates to -t 0.000001. This should be sufficient for applications which don't require survey-quality accuracy.

Progress

If you aren't piping the output of the command to a file, polylabel will display progress of the parsing and labelling steps in the terminal, as well as a final count of the labelled polygons.

Validity

While the structure of the input GeoJSON is validated, individual geometries are not validated in the DE-9IM sense. If they self-intersect, have open rings etc., results are not guaranteed to be correct.

Speed

It runs ~10x faster than the NPM package. Polygons are processed in parallel, using Rayon. Note that higher tolerances will result in slower processing.

Binaries

Pre-built binaries are available from releases. Binaries are available for:

  • macOS (x86_64)
  • Linux (x86_64)
  • Windows (x86_64 and i686)

License

MIT

Dependencies

~9MB
~186K SLoC