urschrei / polylabel_cmd

A command-line utility for generating optimum polygon label coordinates from GeoJSON

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