mapshaper 0.7.2 → 0.7.3

package/www/llms-full.txt

@@ -1,4053 +0,0 @@
-# Mapshaper
-
-> Mapshaper is a command-line tool and in-browser editor for geographic vector data. It reads and writes Shapefile, GeoJSON, TopoJSON, GeoPackage, FlatGeobuf, KML/KMZ, CSV/TSV, DBF, JSON records and SVG, and can simplify, clip, dissolve, join, project and otherwise transform layers. The CLI and web app share the same command language, so commands written interactively in the browser console run unchanged in scripts.
-
-These docs cover the same material in two forms:
-
-- **Markdown mirrors** of every page (this file links to them) for use by language models and other tools.
-- **HTML pages** at the same paths without the trailing `.md`, with navigation, search and syntax highlighting, intended for humans.
-
-When in doubt about a command's behavior, the [command reference](https://mapshaper.org/docs/reference.html.md) is the source of truth. The Node.js source code lives at <https://github.com/mbloch/mapshaper>.
-
----
-
-<!-- https://mapshaper.org/docs/ -->
-
-# Mapshaper documentation
-
-<p class="lead">Mapshaper is a tool for editing Shapefile, GeoJSON, TopoJSON, GeoPackage, FlatGeobuf, KML and CSV data &mdash; available as a command-line program and as a web app at <a href="/">mapshaper.org</a>.</p>
-
-<div class="section-cards">
-  <a class="section-card" href="/docs/essentials/command-line.html">
-    <p class="card-title">Getting started</p>
-    <p class="card-desc">Introductions to the CLI and the web app.</p>
-  </a>
-  <a class="section-card" href="/docs/guides/simplification.html">
-    <p class="card-title">Guides</p>
-    <p class="card-desc">Task-oriented walk-throughs: simplification, topology, joining layers, scripting from Node.</p>
-  </a>
-  <a class="section-card" href="/docs/formats/overview.html">
-    <p class="card-title">File formats</p>
-    <p class="card-desc">Read/write details for Shapefile, GeoJSON, TopoJSON, GeoPackage, FlatGeobuf, KML, CSV and more.</p>
-  </a>
-  <a class="section-card" href="/docs/examples/basics.html">
-    <p class="card-title">Examples</p>
-    <p class="card-desc">Short recipes for common GIS tasks, plus a Gallery of full map examples with source data.</p>
-  </a>
-</div>
-
-## Featured examples
-
-<!-- mapshaper:featured count=2 -->
-
-<p class="featured-maps-link"><a href="/docs/gallery/">See the full gallery &rarr;</a></p>
-
-## What's new
-
-A curated log of recently added features is at [What's new](/docs/whats-new.html.md). The full [changelog](https://github.com/mbloch/mapshaper/blob/master/CHANGELOG.md) is on GitHub.
-
-## Help and feedback
-
-- Found a bug or want to request a feature? [Share feedback](https://tally.so/r/44Njok) or [open an issue on GitHub](https://github.com/mbloch/mapshaper/issues).
-- Mapshaper is free software. If it's useful to you, please consider [supporting its development](/sponsor.html).
-
----
-
-<!-- https://mapshaper.org/docs/whats-new.html -->
-
-# What's new
-
-This is a curated list of recently added features. For the full list of changes, including bug fixes and internal work, see the [changelog](https://github.com/mbloch/mapshaper/blob/master/CHANGELOG.md) on GitHub.
-
-## April 2026
-
-<div class="whats-new-entry">
-
-**Undo/redo buttons.** The web UI now has an undo/redo toolbar. Undo and redo were already supported in the geometry and attribute editing modes; the toolbar makes them more discoverable for users who didn't know the keyboard shortcuts (**⌘Z** / **⌘⇧Z**) existed.
-
-</div>
-
-<div class="whats-new-entry">
-
-**Command files.** A sequence of Mapshaper commands can be written to a `.txt` file with `#` comments and no shell quoting, and run with `-run <file>` (or just `mapshaper commands.txt`). Command files can also be written in a shell-compatible way, if you want to be able to paste the commands into the terminal or add them to a shell script. In a future release, these files will also be runnable in the browser.
-
-```bash
-mapshaper build.txt
-```
-
-→ See [Command files](/docs/reference.html.md#command-files) in the reference.
-</div>
-
-<div class="whats-new-entry">
-
-**Variable interpolation in commands.** Command files and command lines support `{{VAR}}` placeholders, resolved at run time against environment variables (`{{env.HOME}}`), values set with the new `-vars` and `-defaults` commands, and variables defined dynamically by `-calc`, `-define` and `-each` expressions.
-
-```bash
-mapshaper -vars YEAR=2030 PCT=5 -run build.txt
-```
-
-→ See [Variable interpolation](/docs/reference.html.md#variable-interpolation), [`-vars`](/docs/reference.html.md#-vars) and [`-defaults`](/docs/reference.html.md#-defaults).
-</div>
-
-<div class="whats-new-entry">
-
-**Farewell to dissolve2.** The `-dissolve` command now uses Mapshaper's most robust dissolve function, which can handle overlaps, gaps and other topology errors. The legacy faster algorithm is still available as `-dissolve no-repair`. (The old `-dissolve2` is just an alias for `-dissolve`.)
-
-→ See [`-dissolve`](/docs/reference.html.md#-dissolve).
-</div>
-
-<div class="whats-new-entry">
-
-**FlatGeobuf and GeoPackage support.** Mapshaper reads and writes FlatGeobuf (`.fgb`) and GeoPackage (`.gpkg`) files.
-
-→ See [FlatGeobuf](/docs/formats/flatgeobuf.html.md), [GeoPackage](/docs/formats/geopackage.html.md) and [`-i layers=`](/docs/reference.html.md#-i-input).
-</div>
-
-<div class="whats-new-entry">
-
-**SVG import.** SVG files exported by Mapshaper can be re-imported &mdash; useful for making stylistic edits.
-
-→ See [SVG](/docs/formats/svg.html.md).
-</div>
-
----
-
-<!-- https://mapshaper.org/docs/reference.html -->
-
-# Command reference
-
-## Command line syntax
-
-Mapshaper takes a list of commands and runs them in sequence, from left to right. A command consists of the name of a command prefixed by a hyphen, followed by options for the command. The initial import command `-i` can be omitted.
-
-#### Example
-
-```bash
-# Read a Shapefile, simplify using Douglas-Peucker, output as GeoJSON.
-mapshaper provinces.shp -simplify dp 20% -o precision=0.00001 output.geojson
-```
-
-### Command options can take three forms:
-
-  - Values, like `provinces.shp` and `output.geojson` in the above example
-
-  - Flags, like `dp`
-
-  - Name/value pairs, like `precision=0.00001`
-
-### Common options
-
-The following options are documented here, because they are used by many commands.
-
-`name=` Rename the layer (or layers) modified by a command.
-
-`target=` Specify the layer or layers targeted by a command. Takes the name of a layer, the number of a layer (first layer is 1), or a comma-separated list of layer names or numbers. Names may contain the `*` wildcard.
-
-`+` Use the output of a command to create a new layer or layers instead of replacing the target layer(s). Use together with the `name=` option to assign a name to the new layer(s).
-
-#### Example
-```bash
-# Make a derived layer containing a subset of features
-# while retaining the original layer
-mapshaper states.geojson -filter 'ST == "AK"' + name=alaska -o output/ target=*
-```
-
-## Command files
-
-As an alternative to typing commands on the command line, you can put them in a plain-text command file and run them with the mapshaper CLI.
-
-Command files offer a few conveniences over a shell script or Makefile:
-
-- Hash-delimited (`#`) comments, both on their own line and at the end of a line.
-- No need to escape `*` or other shell metacharacters; commands aren't passed through the shell.
-- Trailing-backslash line continuations are accepted but not required &mdash; lines that don't begin with `-` are joined onto the previous command.
-- Variable interpolation using `{{VAR}}` placeholders. See [variables](#variables) below.
-
-(Support for running command files in the mapshaper web UI is planned for a future release.)
-
-### File format
-
-A mapshaper command file is a `.txt` file whose first non-blank, non-comment line starts with `mapshaper`.
-
-```
-mapshaper
--i provinces.shp
-# Use Douglas Peucker simplification
--simplify dp 20%
--o precision=0.00001 output.geojson
-```
-
-If you write the command file using shell-compatible syntax &mdash; trailing `\` for line continuations and no `#` comments &mdash; it can also be pasted directly onto a bash command line, where the leading `mapshaper` word invokes the CLI. To make the above example shell compatible, you could write:
-
-```
-mapshaper \
--i provinces.shp \
--simplify dp 20% \
--o precision=0.00001 output.geojson
-```
-
-### Running a command file
-
-The command for running a command file is [`-run`](#-run):
-
-```bash
-mapshaper -run build.txt
-```
-
-`mapshaper commands.txt` is a shortcut for `mapshaper -run commands.txt`.
-
-## Variable interpolation
-
-Command files and command lines may contain `{{VAR}}` placeholders, which are substituted just before each command runs. Two forms are recognized:
-
-- `{{VAR}}` &mdash; substituted with the value of `VAR`.
-- `{{env.NAME}}` &mdash; substituted with the value of the `NAME` environment variable.
-
-This syntax allows you to interpolate all or part of a command option. For example, `-simplify {{SIMPLIFY_METHOD}} resolution={{SIMPLIFY_RESOLUTION}}`.
-
-Variables can be set in several ways:
-- The [`-vars`](#-vars) command sets one or more variables, always overwriting any previous value.
-- The [`-defaults`](#-defaults) command set only those values that do not already exist.
-- Assignments in `-calc` and `-define` expressions create new variables.
-- Assigning a property to the `global` object in an `-each` expression creates a new variable.
-
-`-vars` and `-defaults` write to a templating-scope store; the other commands write to an expression-scope store (`global`). `{{X}}` substitution checks the templating scope first and falls back to the expression scope, so values from any of the four mechanisms above are reachable. Bare names in JS expressions only see the expression scope &mdash; a name set by `-vars` is *not* readable by bare name from inside `-each`, `-filter`, etc. See [JavaScript expressions](/docs/guides/expressions.html.md#sharing-state-across-commands) for the full story.
-
-#### Example
-
-`build.txt`:
-```
-mapshaper
--defaults YEAR=2024 PCT=10                    # overridable defaults
--i sources/counties_{{YEAR}}.shp
--simplify {{PCT}}%
--o out/counties_{{YEAR}}_simplified.shp
-```
-
-Run with the command file's defaults:
-```bash
-mapshaper build.txt
-```
-
-Or override default values from the command line:
-```bash
-mapshaper -vars YEAR=2030 PCT=5 -run build.txt
-```
-
-## Index of commands
-
-**File I/O**
-
-[-i (input)](#-i-input)
-[-o (output)](#-o-output)
-
-**Editing**
-
-[-affine](#-affine)
-[-classify](#-classify)
-[-clean](#-clean)
-[-clip](#-clip)
-[-colorizer](#-colorizer)
-[-dashlines](#-dashlines)
-[-dissolve](#-dissolve)
-[-dissolve2](#-dissolve2)
-[-divide](#-divide)
-[-dots](#-dots)
-[-drop](#-drop)
-[-each](#-each)
-[-erase](#-erase)
-[-explode](#-explode)
-[-filter](#-filter)
-[-filter-fields](#-filter-fields)
-[-filter-islands](#-filter-islands)
-[-filter-slivers](#-filter-slivers)
-[-frame](#-frame)
-[-graticule](#-graticule)
-[-grid](#-grid)
-[-include](#-include)
-[-inlay](#-inlay)
-[-innerlines](#-innerlines)
-[-join](#-join)
-[-lines](#-lines)
-[-merge-layers](#-merge-layers)
-[-mosaic](#-mosaic)
-[-point-grid](#-point-grid)
-[-points](#-points)
-[-polygons](#-polygons)
-[-proj](#-proj)
-[-rectangle](#-rectangle)
-[-rectangles](#-rectangles)
-[-rename-fields](#-rename-fields)
-[-rename-layers](#-rename-layers)
-[-require](#-require)
-[-run](#-run)
-[-scalebar](#-scalebar)
-[-shape](#-shape)
-[-simplify](#-simplify)
-[-snap](#-snap)
-[-sort](#-sort)
-[-split](#-split)
-[-split-on-grid](#-split-on-grid)
-[-subdivide](#-subdivide)
-[-style](#-style)
-[-symbols](#-symbols)
-[-union](#-union)
-[-uniq](#-uniq)
-
-**Control Flow**
-
-[-if](#-if)
-[-elif](#-elif)
-[-else](#-else)
-[-endif](#-endif)
-[-stop](#-stop)
-[-target](#-target)
-
-**Information**
-
-[-calc](#-calc)
-[-colors](#-colors)
-[-comment](#-comment)
-[-defaults](#-defaults)
-[-encodings](#-encodings)
-[-help](#-help)
-[-info](#-info)
-[-inspect](#-inspect)
-[-print](#-print)
-[-projections](#-projections)
-[-quiet](#-quiet)
-[-vars](#-vars)
-[-verbose](#-verbose)
-[-version](#-version)
-
-
-## I/O Commands
-
-### -i (input)
-
-Input one or more files in a supported vector data format. Supported file types include: Shapefile, GeoJSON, TopoJSON, GeoPackage, FlatGeobuf, KML, JSON data records, DBF, CSV/TSV.
-
-The `-i` command is assumed if `mapshaper` is followed by the path of an input data file.
-
-Mapshaper does not fully support M and Z type Shapefiles. The M and Z data is lost when these files are imported.
-
-When multiple input files are given, they can either be processed together (as a group of layers with shared topology) or separately (as a sequence of independent runs). Use `combine-files` to process them together, or `batch-mode` to process them separately.
-
-For backward compatibility, multiple input files are currently processed in batch mode by default; this default will change in a future release. Mapshaper prints a deprecation notice when batch mode is triggered implicitly. Existing scripts that rely on batch processing should add the `batch-mode` flag.
-
-**Options**
-
-`<files>` or `files=`  File(s) to input (space-separated list). Use `-` to import from `/dev/stdin`.
-
-In place of a file name, you can also pass data inline:
-
-  - **JSON.** A string starting with `{` or `[` is treated as a literal JSON object or array.
-  - **CSV.** A comma-delimited string is treated as inline CSV when it contains a newline (a real one or the literal escape sequence `\n`) and both the first and second lines contain at least one comma.
-
-```bash
-mapshaper -i 'lat,lon,label\n48.86,2.35,Paris\n51.51,-0.13,London' -o cities.json
-```
-
-`combine-files` Import multiple files to separate layers with shared topology. Useful for generating a single TopoJSON file containing multiple geometry objects.
-
-`batch-mode` Apply subsequent commands separately to each input file, as if running mapshaper multiple times with the same set of commands. Used together with `-o` to transform a directory of files. Required (in a future release) to use this batch-processing behavior.
-
-`merge-files` (Deprecated) Merge features from multiple input files into as few layers as possible. Preferred method: import files to separate layers using `-i combine-files`, then use the `-merge-layers` command to merge layers. 
-
-`snap`     Snap together vertices within a small distance threshold. This option is intended to fix minor coordinate misalignments in adjacent polygons. The snapping distance is 0.0025 of the average segment length.
-
-`snap-interval=`    Specify snapping distance in source units.
-
-`precision=`     (Deprecated) Round all coordinates to a specified precision, e.g. `0.001`. It is recommended to set coordinate precision on export, using `-o precision=`.
-
-`no-topology`  Skip topology identification to speed up processing of large files. For use with commands like `-filter` that don't require topology.
-
-`encoding=`	Specify encoding used for reading .dbf files and delimited text files. If the `encoding` option is missing, mapshaper will try to detect the encoding of .dbf files. Dbf encoding can also be set using a .cpg file.
-
-`id-field=` (Topo/GeoJSON) Import values of "id" property to this data field.
-
-`string-fields=` (CSV) List of fields to import as strings (e.g. FIPS,ZIPCODE). Using `string-fields=*` imports all fields as strings.
-
-`field-types=` Type hints for importing delimited text. Takes a comma-separated list of field names with type hints appended; e.g. `FIPS:str,zipcode:str`. Recognized type hints include `:str` or `:string`, `:num` or `:number`. Without a type hint, fields containing text data that looks like numeric data, like ZIP Codes, will be converted to numbers.
-
-`csv-skip-lines=` Number of lines to skip at the beginning of a CSV file. Useful when a CSV has been exported from a spreadsheet and there are rows of notes above the data section of the worksheet.
-
-`csv-lines=` Number of data records to import from a CSV file (default is all).
-
-`csv-field-names=` Comma-sep. list of names to assign each field. Can be used in conjunction with `csv-skip-lines=1` to replace names from an existing set of field headers.
-
-`csv-fields=` Comma-sep. list of fields to import from a CSV-formatted input file. Fields are filtered as the file is read, which reduces the memory needed to import very large CSV files.
-
-`decimal-comma`  Import numbers formatted with decimal commas, not decimal points. Accepted formats: `1.000,01`  `1 000,01` (both imported as as 1000.01).
-
-`csv-dedup-fields` Assign unique names to CSV fields with duplicate names.
-
-`csv-filter=` A JavaScript expression for importing a subset of the records in a CSV file. Records are filtered as the file is read, which reduces the memory needed to import very large CSV files.
-
-`json-path=` [JSON] Path to an array of data records or a GeoJSON object. For example, `json-path=data/counties` expects a JSON object with the following structure `{"data": {"counties": []}}`.
-
-`layers=` [GeoPackage] Comma-separated list of layer names to import from a GeoPackage file. If omitted, all layers are imported.
-
-`name=`  Rename the imported layer (or layers).
-
-**Example** 
-
-```bash
-# Input a Shapefile with text data in the latin1 encoding
-# and see what kind of data it contains
-mapshaper countries_wgs84.shp encoding=latin1 -info
-```
-
-### -o (output)
-
-Save content of the target layer(s) to a file or files.
-
-**Options**
-
-`<file>|<directory>|-`  Name of output file or directory. Use `-` to export text-based formats to `/dev/stdout`.
-
-`format=shapefile|geojson|topojson|flatgeobuf|geopackage|json|dbf|csv|tsv|svg` Specify output format. If the `format=` option is missing, Mapshaper tries to infer the format from the output filename. If no filename is given, Mapshaper exports to the same format as the input format. The `json` format is an array of objects containing data properties for each feature.
-
-`target=` Specify layer(s) to export (comma-separated list). The default target is the output layer(s) of the previous command. Use `target=*` to select all layers.
-
-`force`  Allow output files to overwrite input files (without this option, overwriting input files is not allowed).
-
-`gzip`  Apply gzip compression to output files.
-
-`zip`  Save output files in a single .zip archive.
-
-`cut-table`  Detach attribute data from shapes and save as a JSON file.
-
-`drop-table`  Remove attribute data from output.
-
-`precision=`  Round all coordinates to a specified precision, e.g. `precision=0.001`. Useful for reducing the size of GeoJSON files.
-
-`fix-geometry` Remove segment intersections caused by rounding (via the `precision=` option) or TopoJSON quantization, by reverting intersecting areas to the original coordinates. In the case of quantized TopoJSON output, this option produces delta-encoded arcs that contain some decimal numbers. Be sure to test your software for compatibility. Note that this option is only applied if the original paths are free of intersections. Also, some kinds of invalid geometry, like spikes, do not get fixed.
-
-`bbox-index`  Export a JSON file containing bounding boxes of each output layer.
-
-`encoding=` (Shapefile/CSV) Encoding of input text (by default, Shapefile encoding is auto-detected and CSV files are assumed to be UTF-8).
-
-`field-order=` (Shapefile/CSV) `field-order=ascending` sorts data fields in alphabetical order of field names (A-Z, case-insensitive).
-
-`id-field=`  (Topo/GeoJSON/SVG) Specify one or more data fields to use as the "id" property of GeoJSON, TopoJSON or SVG features (comma-separated list). When exporting multiple layers, you can pass a list of field names. The first listed name that is present in a layer's attribute table will be used as the id field for that layer.
-
-`bbox`  (Topo/GeoJSON) Add bbox property to the top-level object.
-
-`extension=`  (Topo/GeoJSON) set file extension (default is ".json").
-
-`prettify`  (Topo/GeoJSON) Format output for readability.
-
-`singles`  (TopoJSON) Save each output layer as a separate file. Each output file and the TopoJSON object that it contains are named after the corresponding data layer. 
-
-`quantization=`     (TopoJSON) Specify quantization as the maximum number of differentiable points along either dimension. Equivalent to the quantization parameter used by the [topoquantize](https://github.com/topojson/topojson-client#topoquantize) command line program. By default, mapshaper applies quantization equivalent to 0.02 of the average segment length.
-
-`no-quantization`  (TopoJSON) Arc coordinates are encoded at full precision and without delta-encoding.
-
-`presimplify` (TopoJSON) Add a threshold value to each arc vertex in the z position (i.e. [x, y, z]). Useful for dynamically simplifying paths using vertex filtering. Given W as the width of the map viewport in pixels, S as the ratio of content width to viewport width, and pz as the presimplify value of a point, the following expression tests if the point should be excluded from the output path: `pz > 0 && pz < 10000 / (W * S)`.
-
-`topojson-precision=`	(TopoJSON) Set quantization as a fraction of the average segment length.
-
-`ndjson`  (GeoJSON/JSON) Output newline-delimited records.
-
-`gj2008`  (GeoJSON) Generate output that is consistent with the pre-RFC 7946 GeoJSON spec (dating to 2008). Polygon rings are CW and holes are CCW, which is the opposite of the default RFC 7946-compatible output. Mapshaper's default GeoJSON output is now compatible with the current specification (RFC 7946).
-
-`combine-layers`  (GeoJSON) Combine multiple output layers into a single GeoJSON file.
-
-`geojson-type=`   (GeoJSON) Overrides the default output type. Possible values: "FeatureCollection", "GeometryCollection", "Feature" (for a single feature).
-
-`no-null-props`   (GeoJSON) use `"properties": {}` instead of `"properties": null` when outputting a Feature with no attribute data.
-
-`hoist=`  (GeoJSON) Move one or more properties to the root level of each Feature. Hoisting a field named "id" creates an id for each Feature. This option can also be used to create non-standard Feature attributes (as used by the tippecanoe program).
-
-`width=`    (SVG/TopoJSON) Set the width of the output dataset in pixels. When used with TopoJSON output, this option switches the output coordinates from geographic units to pixels and flips the Y axis. SVG output is always in pixels (default SVG width is 800).
-
-`height=`    (SVG/TopoJSON) Similar to the `width` option. If both `height` and `width` are set, content is centered inside the `[0, 0, width, height]` bounding box.
-
-`max-height=` (SVG/TopoJSON) Limit output height (units: pixels).
-
-`margin=`   (SVG/TopoJSON) Set the margin between coordinate data and the edge of the viewport (default is 1). To assign different margins to each side, pass a list of values in the order `<left,bottom,right,top>` (similar to the `bbox=` option found in other commands).
-
-`pixels=`  (SVG/TopoJSON) Output area in pixels (alternative to width=).
-
-`id-prefix=` Prefix for namespacing layer and feature ids.
-
-`svg-data=` (SVG) Export a comma-seperated list of data fields as SVG data-* attributes. Attribute names should match the following regex pattern: `/^[a-z_][a-z0-9_-]*$/`. Non-conforming fields are skipped.
-
-`svg-scale=`   (SVG) Scale SVG output using geographical units per pixel (an alternative to the `width=` option).
-
-`svg-bbox=<xmin,ymin,xmax,ymax>` (SVG)  Bounding box of SVG map in projected map units. By default, the extent of SVG output fits the content; this option lets you provide a custom extent. This could be useful when aligning the SVG output with other content layers, such as images or videos.
-
-`fit-extent=<layer id>` (SVG) Use a layer (typically a layer containing a single rectangle) to set the extent of the map. Paths that overflow this extent are retained in the SVG output.
-
-`point-symbol=square`  (SVG) Use squares instead of circles to symbolize point data.
-
-`delimiter=`  (CSV) Set the field delimiter for CSV/delimited text output; e.g. `delimiter=|`.
-
-`decimal-comma`  (CSV) Export numbers with decimal commas instead of decimal points (common in Europe and elsewhere).
-
-`show-all`  [Snapshot] All layers of the exported snapshot will be displayed when opened in the web UI.
-
-**Example**
-```bash
-# Convert all the Shapefiles in one directory into GeoJSON
-# files in a different directory.
-mapshaper -i shapefiles/*.shp batch-mode -o geojson/ format=geojson
-```
-
-## Editing Commands
-
-
-### -affine
-
-Transform coordinates by shifting, scaling and rotating. Not recommended for unprojected datasets.
-
-`shift=`  X,Y shift in source units (e.g. 5000,-5000)
-
-`scale=`  Scale (default is 1)
-
-`rotate=`  Angle of rotation in degrees (default is 0)
-
-`anchor=`  Center of rotation/scaling (default is center of the bounding box of the selected content)
-
-`where=`  Use a JS expression to select a subset of features.
-
-Common options: `target=`
-
-### -classify
-
-Assign colors or data values to each feature using one of several classification methods. Methods for sequential data include `quantile`, `equal-interval`, `hybrid` and `nice` or categorical classification to a data field.
-
-`<field>` or `field=` Name of the data field to classify.
-
-`save-as=`     	Name of a (new or existing) field to receive the output of classification. The default output field for colors is `fill` or `stroke` (depending on geometry type) and `class` for non-color output.
-
-`values=`       List of values to assign to data classes. If the number of values differs from the number of classes given by the (optional) `classes` or `breaks` option, then interpolated values will be calculated. Mapshaper uses d3 for interpolation.
-
-`colors=` Takes a list of CSS colors, the name of a predefined color scheme, or `random`. Run the [-colors](#-colors) command to list all of the built-in color schemes. Similar to the `values=` option, if the number of listed colors is different from the number of requested classes, interpolated colors are calculated.
-
-`non-adjacent`  Assign colors to a polygon layer in a randomish pattern, trying not to assign the same color to adjacent polygons. Mapshaper's algorithm balances performance and quality. Usually it can find a solution with four or five colors. If mapshaper is unable to avoid giving the same color to neighboring polygons, it will print a warning. You can resolve the problem by increasing the number of colors.
-
-`stops=` A pair of comma-separated numbers (0-100) for limiting the output range of a color ramp.
-
-
-`null-value=`   Value (or color) to use for invalid or missing data.
-
-`classes=`      Number of data classes. This number can also be inferred from the `breaks=` or `values=` options.
-
-`breaks=`       Specify user-defined sequential class breaks (an alternative to automatic classification using `quantile`, `equal-interval`, etc.).
-
-`outer-breaks=`  A pair of comma-separated numbers setting min and max breakpoints to use when computing class breaks. This setting overrides the default behavior, which is to use the min and max values of the data field being classified. This setting can be used to prevent extreme data values (outliers) from affecting equal-interval classification. Also useful for setting outside breakpoints for continuous color ramps (when using the `continuous` option).
-
-`method=`       Classification method. One of: `quantile`, `equal-interval`, `nice`, `hybrid` (sequential data), `categorical`, `non-adjacent` and `indexed`. This parameter is not required if the classification method can be inferred from other options. For example, the `index-field=` parameter implies indexed classification, the `categories=` parameter implies categorical classification.
-
-`quantile`      Use quantile classification. Shortcut for `method=quantile`.
-
-`equal-interval` Use equal interval classification. Shortcut for `method=equal-interval`.
-
-`nice`          Same as `method=nice`. This scheme finds equally spaced, round breakpoints that roughly divide the dataset into equal parts (similar to quantile classification).
-
-`invert`        Reverse the order of colors/values.
-
-`continuous`    Output continuously interpolated values (experimental). Uses linear interpolation between class breaks, which may give poor results with some distributions of data. This option is for creating unclassed/continuous-color maps.
-
-`index-field=`  Use class ids that have been precalculated and assigned to this field. Values should be integers from `0 ... n-1` (where n is the number of classes). `-1` is the null value.
-
-`precision=`    Round data values before classification (e.g. `precision=0.1`).
-
-`categories=`   List of values in the source data field. Using this option triggers categorical classification.
-
-`other=`  Default value for categorical classification. This value is used when the value of the source data field is not present in the list of values given by `categories=`. Defaults to `null-value=` or null.
-
-**Options for generating SVG keys**
-
-`key-style=`         One of: simple, gradient, dataviz
-
-`key-name= `         Name of output SVG file
-
-`key-width=`         Width of key in pixels
-
-`key-font-size=`     Font size of tic labels in pixels
-
-`key-tile-height=`   Height of color tiles in pixels
-
-`key-tic-length=`    Length of tic mark in pixels
-
-`key-label-suffix=`  String to append to each label
-
-`key-last-suffix=`   String to append to the last label
-
-
-**Examples**
-
-```bash
-# Apply a sequential color ramp to a polygon dataset using quantiles.
-mapshaper covid_cases.geojson \
-  -classify save-as=fill quantile color-scheme=Oranges classes=6 \
-  -o out.geojson
-```
-
-### -clean
-
-This command attempts to repair various kinds of abnormal geometry that might cause problems when running other mapshaper commands or when using other software.
-
-Features with null geometries are deleted, unless the `allow-empty` flag is used.
-
-Polygon features are cleaned by removing overlaps and filling small gaps between adjacent polygons. Only gaps that are completely enclosed can be filled. Areas that are contained by more than one polygon (overlaps) are assigned to the polygon with the largest area. Similarly, gaps are assigned to the largest-area polygon. This rule may give undesired results and will likely change in the future.
-
-Line features are cleaned by removing self-intersections within the same path. Self-intersecting paths are split at the point of intersection and converted into multiple paths within the same feature. When two separate paths intersect in-between segment endpoints, new vertices are inserted at the point of intersection.
-
-Point features are cleaned by removing duplicate coordinates within the same feature.
-
-`gap-fill-area=`  (polygons) Gaps smaller than this area will be filled; larger gaps will be retained as holes in the polygon mosaic. Example values: 2km2 500m2 0. Defaults to a  dynamic value calculated from the geometry of the dataset.
-
-`sliver-control=` (polygons) Preferentially remove slivers (polygons with a high perimeter-area ratio). Accepts values from 0-1, default is 1. Implementation: multiplies the area of gap areas by the "Polsby Popper" compactness metric before applying area threshold.
-
-`overlap-rule=` (polygons) Assign overlapping polygon areas to one of the overlapping features based on this rule. Possible options are: min-id, max-id, min-area, max-area (default is max-area).
-
-`allow-overlaps` Allow features to overlap each other. The default behavior is to remove overlaps.
-
-`snap-interval=` Snap vertices within a given threshold before performing other kinds of geometry repair. Defaults to a very small threshold. Uses source units.
-
-`rewind` Fix errors in the winding order of polygon rings.
-
-`allow-empty`  Allow null geometries, which are removed by default.
-
-Common options: `target=`
-
-
-### -clip
-
-Remove features or portions of features that fall outside a clipping area.
-
-`<source>` or `source=` Clip to a set of polygon features. Takes the filename or layer id of the clip polygons.
-
-`bbox=<xmin,ymin,xmax,ymax>` Delete features or portions of features that fall outside a bounding box.
-
-`bbox2=` Faster bounding box clipping than `bbox=` (experimental).
-
-`remove-slivers` Remove tiny sliver polygons created by clipping.
-
-Common options: [`name=` `+` `target=`](#common-options)
-
-```bash
-# Example: Clip a polygon layer using another polygon layer.
-mapshaper usa_counties.shp -clip land-area.shp -o clipped.shp
-```
-
-### -colorizer
-
-Define a function for converting data values to colors that can be used in subsequent calls to the `-style` command.
-
-`name=`  Name of the colorizer function.
-
-`colors=`  List of CSS colors.
-
-`random`  Randomly assign colors. Uses `colors=` list if given.
-
-`breaks=`  Ascending-order list of breaks (thresholds) for creating a sequential color scheme.
-
-`categories=`  List of data values (keys) for creating a categorical color scheme.
-
-`other=`  Default color for categorical scheme (defaults to `nodata` color).
-
-`nodata=` Color to use for invalid or missing data (default is white).
-
-`precision=` Rounding precision to apply to numerical data before converting to a color (e.g. 0.1).
-
-```bash
-# Example: define a function for a sequential color scheme
-# and assign colors based on data values
-mapshaper data.json \
-  -colorizer name=getColor \
-    colors='#f0f9e8,#bae4bc,#7bccc4,#2b8cbe' breaks=25,50,75 \
-  -each 'color = getColor(PCT)' \
-  -o output.json
-
-# Example: define a function for a categorical color scheme
-# and use it to assign fill colors
-mapshaper data.json \
-  -colorizer name=calcFill colors='red,blue,green' \
-    categories='Republican,Democrat,Other' \
-  -style fill='calcFill(PARTY)' \
-  -o output.svg
-```
-
-### -dashlines
-
-Split lines into sections, with or without a gap.
-
-`dash-length=`  Length of split-apart lines (e.g. 200km)
-`gap-length=`   Length of gaps between dashes (default is 0)
-`scaled`        Scale dashes and gaps to prevent partial dashes
-`planar`        Use planar geometry
-`where=`        Use a JS expression to select a subset of features.
-
-### -dissolve
-
-Aggregate groups of features using a data field, or aggregate all features if no field is given. For polygon layers, `-dissolve` merges adjacent polygons by erasing shared boundaries. For point layers, `-dissolve` replaces a group of points with their centroid. For polyline layers, `-dissolve` tries to merge contiguous polylines into as few polylines as possible.
-
-For polygon layers, `-dissolve` repairs topology before dissolving, so it produces correct results on inputs that contain overlaps, gaps or other topology errors. The `no-repair` option skips this step for a faster (but less robust) dissolve.
-
-`<fields>` or `fields=` (optional) Name of a data field or fields to dissolve on. Accepts a comma-separated list of field names.
-
-`group-points`   [points] Group the points from each dissolved group of features into a multi-point feature instead of converting multiple points into a single-point centroid feature.
-
-`weight=`  [points] Name of a field or a JS expression for generating weighted centroids. For example, the following command estimates the "center of mass" of the U.S. population: ` mapshaper census_tracts.shp -points -dissolve weight=POPULATION -o out.shp`
-
-`planar`   [points] Treat decimal degree coordinates as planar cartesian coordinates when calculating dissolve centroids. (By default, mapshaper calculates the centroids of lat-long point data in 3D space.)
-
-`gap-fill-area=`  [polygons] Gaps smaller than this area will be filled; larger gaps will be retained as holes in the polygon mosaic. Example values: 2km2 500m2 0. Defaults to a dynamic value calculated from the geometry of the dataset.
-
-`sliver-control=` [polygons] Preferentially remove slivers (polygons with a high perimeter-area ratio). Accepts values from 0-1, default is 1. Implementation: multiplies the area of gap areas by the "Polsby Popper" compactness metric before applying area threshold.
-
-`allow-overlaps` [polygons] Allow dissolved groups of features to overlap each other. The default behavior is to remove overlaps.
-
-`no-repair` [polygons] Skip topology repair before dissolving. Use when the input is known to be clean and you want a faster dissolve. Mapshaper checks for segment intersections and prints a warning if the assumption appears to be wrong, but it still performs the dissolve. Incompatible with `gap-fill-area=`, `sliver-control=` and `allow-overlaps`.
-
-`calc=` Use built-in JavaScript functions to create data fields in the dissolved layer. See example below; see [-calc](#-calc) for a list of supported functions.
-
-`sum-fields=` Fields to sum when dissolving (comma-sep. list).
-          
-`copy-fields=`  Fields to copy when dissolving (comma-sep. list). Copies values from the first feature in each group of dissolved features.
-
-`multipart`  Group features from the target layer into multipart features, without otherwise modifying geometry.
-
-`where=`   Use a JS expression to select a subset of features to dissolve.
-
-Common options: `name=` `+` `target=`
-
-```bash
-# Example: Aggregate county polygons to states
-mapshaper counties.shp -dissolve STATE -o states.shp
-
-# Example: Use the calc= option to count the number of dissolved features
-# and perform other calculations
-mapshaper counties.shp \
-  -dissolve STATE calc='n = count(),
-                        total_pop = sum(POP),
-                        max_pop = max(POP),
-                        min_pop = min(POP)'
-```
-
-
-### -dissolve2
-
-Deprecated alias for [`-dissolve`](#-dissolve). The topology-repairing behavior of `-dissolve2` has been promoted to be the default behavior of `-dissolve`. Existing scripts that use `-dissolve2` will continue to work but print a deprecation notice.
-
-### -divide
-
-Divide a polyline layer by a polygon layer. Line features that cross polygon boundaries are divided into separate features. Data fields from the polygon layer are copied to the line layer, as in the `-join` command.
-
-`<file|layer>` or `source=` File or layer containing polygon features.
-
-`fields=`  A comma-separated list of fields to copy from the polygon layer (see `-join` command).
-
-`calc=` Use JS assignments and built-in functions to convert values from the polygon layer to (new) fields the target table (see `-join` command).
-
-Other options: `target=`
-
-### -dots
-
-Fill polygons with random points, for making dot density maps. This command should be applied to projected layers.
-
-`<fields>` or `fields=`  List of one or more data fields containing data for the number of dots to place in each polygon.
-
-`colors=`	List of dot colors (one color for each field  in the `fields=` parameter). Dots of different colors are placed in random sequence, so dots of one color do not consistently cover up dots of other colors in the densest areas.
-
-`values=` List of values to assign to dots (alternative to `colors=`).
-
-`save-as=`  Name of a (new or existing) field to receive the assigned colors or values. (By default, colors are assigned to the `fill` field.)
-
-`r=`	Dot radius in pixels.
-
-`evenness=`	A value from 0-1. 0 corresponds to purely random placement, 1 maintains (fairly) even spacing between the dots within each polygon. The default is 1.
-
-`per-dot=` A number for scaling data values. For example, use `per-dot=100` to make a map that displays one dot per 100 people (or whatever entity is being visualized).
-
-`copy-fields=` List of fields to copy from the original polygon layer to each dot feature.
-
-`multipart` Combine groups of same-color dots into multi-part features.
-
-Other options: `name=` `+` `target=`
-
-
-### -drop
-
-Delete the target layer(s) or elements within the target layer(s).
-
-`fields=`  Delete a (comma-separated) list of attribute data fields. To delete all fields, use `fields=*`.
-
-`geometry`  Delete all geometry.
-
-`holes`  Delete any holes from a polygon layer.
-
-`target=`  Layer(s) to target.
-
-
-### -each
-
-Apply a JavaScript expression to each feature in a layer. Data properties are available as local variables; the feature's geometry-derived properties are available on the `this` object (e.g. `this.area`, `this.centroidX`, `this.bbox`).
-
-**Tip:** Enclose JS expressions in single quotes when using the bash shell (Mac and Linux) to avoid shell expansion of `!` and other special characters. Using the Windows command interpreter, enclose JS expressions in double quotes.
-
-`<expression>` or `expression=`  JavaScript expression to apply to each feature.
-
-`where=`  Secondary boolean JS expression for targetting a subset of features.
-
-`target=`  Layer to target.
-
-The same expression syntax and execution context are used by all commands that support expressions. See [JavaScript expressions](/docs/guides/expressions.html.md) for the full reference. The [Basics](/docs/examples/basics.html.md) page has practical recipes that put expressions to work.
-
-**Examples**
-
-```bash
-# Create two fields
-mapshaper counties.shp \
-  -each 'STATE_FIPS=COUNTY_FIPS.substr(0, 2), AREA=this.area' \
-  -o out.shp
-
-# Delete two fields
-mapshaper states.shp -each 'delete STATE_NAME, delete GEOID' -o out.shp
-
-# Rename a field
-mapshaper states.shp -each 'STATE_NAME=NAME, delete NAME' -o out.shp
-
-# Print the value of a field to the console
-mapshaper states.shp -each 'console.log(NAME)'
-
-# Assign a new data record to each feature
-mapshaper states.shp -each 'this.properties = {FID: this.id}' -o out.shp
-```
-
-
-### -erase
-
-Remove features or portions of features that fall inside an area.
-
-`<source>` or `source=` File or layer containing erase polygons. Takes the filename or layer id of the erase polygons.
-
-`bbox=<xmin,ymin,xmax,ymax>` Delete features or portions of features that fall inside a bounding box. Similar to `-clip bbox=`.
-
-`bbox2=` Faster bounding box erasing than `bbox=` (experimental).
-
-`remove-slivers` Remove tiny sliver polygons created by erasing.
-
-Common options: [`name=` `+` `target=`](#common-options)
-
-```bash
-# Example: Erase a polygon layer using another polygon layer.
-mapshaper usa_counties.shp -erase lakes.shp -o out.shp
-```
-
-
-### -explode
-
-Divide each multi-part feature into several single-part features.
-
-Common options: `target=`
-
-
-### -filter
-
-Apply a boolean JavaScript expression to each feature, removing features that evaluate to false.
-
-`<expression>` or `expression=`  JS expression evaluating to `true` or `false`. Uses the same execution context as [`-each`](#-each).
-
-`bbox=` Retains features that intersect the given bounding box (xmin,ymin,xmax,ymax).
-
-`invert`  Invert the filter -- retain only those features that would have been deleted.
-
-`remove-empty` Delete features with null geometry. May be used by itself or in combination with an `<expression>`.
-
-Common options: [`name=` `+` `target=` ](#common-options)
-
-```bash
-# Example: Select counties from New England states
-mapshaper usa_counties.shp \
-  -filter '"ME,VT,NH,MA,CT,RI".indexOf(STATE) > -1' \
-  -o ne_counties.shp
-```
-
-
-### -filter-fields
-
-Delete fields in an attribute table, by listing the fields to retain. If no files are given, then all attributes are removed.
-
-`<fields>` or `fields=`   Comma-separated list of data fields to retain.
-
-`invert`  Invert the filter -- delete the listed fields instead of retaining them.
-
-Common options: `target=`
-
-```bash
-# Example: Retain two fields
-mapshaper states.shp -filter-fields FID,NAME -o out.shp
-```
-
-### -filter-islands
-
-Remove small detached polygon rings (islands).
-
-`min-area=` Remove small-area islands using an area threshold (e.g. 10km2).
-
-`min-vertices=` Remove low-vertex-count islands.
-
-`remove-empty` Delete features with null geometry.
-
-[`target=`](#common-options)
-
-
-### -filter-slivers
-
-Remove small polygon rings.
-
-`min-area=` Area threshold for removal (e.g. 10km2).
-
-`sliver-control=` (polygons) Preferentially remove slivers (polygons with a high perimeter-area ratio). Accepts values from 0-1, default is 1. Implementation: multiplies the area of polygon rings by the "Polsby Popper" compactness metric before applying area threshold.
-
-`remove-empty` Delete features with null geometry.
-
-[`target=`](#common-options)
-
-### -frame
-
-Create a rectangular frame layer at a given display width. Frame size is used for scaling symbols and for setting the display size of SVG output. The geographical extent of the frame is based on the `bbox=` option or the bounding box of the target layer or layers, if `bbox=` is omitted.
-
-`width=`  Width of frame (e.g. 5in, 10cm, 600px; default is 800px)
-
-`height=`  Height of frame (in addition to or instead of width= option)
-
-`aspect-ratio=`  Aspect ratio of frame (optional)
-
-`bbox=` Bounding coordinates of frame contents in projected map coordinates (xmin,ymin,xmax,ymax). If omitted, the bounding box of the target layer(s) is used.
-
-`offset=` Padding around the frame's `bbox` in display units or pct of width/height, e.g. 5cm 20px 5%
-
-`offsets=`  Comma-sep. list of offsets for each side of the map frame, in l,b,r,t order
-
-Other options: `name=` `target=`
-
-### -graticule
-
-Create a graticule layer appropriate for a world map centered on longitude 0.
-
-`polygon` Create an polygon enclosing the entire area of the graticule. Useful for creating background or outline shapes for clipped projections, like Robinson or Stereographic.
-
-`interval=` Specify the spacing of graticule lines (in degrees). Common options are: 5, 10, 15, 30, 45. Default is 10.
-
-### -grid
-
-Create a continuous grid of square or hexagonal polygons.
-
-The `-grid` command should have a projected layer as its target. The cells of the grid will completely enclose the bounding box of the target layer.
-
-This command is intended for visualizing data in a grid. Typically, you would use the `-join` command to join data from a polygon or point layer to a grid layer. Use `-join interpolate=<fields>` to interpolate data values (typically count data) from the polygon layer to the grid layer based on area. Use `-join calc='<field> = sum(<field>)'` or `-join calc='<field> = count()'` to aggregate point data values.
-
-`type=`  Supported values: `square` `hex` `hex2`. The `hex` and `hex2` types have different rotations.
-
-`interval=` The length of one side of a grid cell. Example values: `500m` `2km`.
-
-Other options: `name=` `+` `target=`
-
-
-### -include
-
-`<file>` or `file=` Path to the external .js file to load. The file should contain a single JS object. The properties of this object are converted to variables in the JS expression used by the `-each` command.
-
-### -inlay
-
-Inscribe a polygon layer within another polygon layer.
-
-`<source>` or `source=`  File or layer containing polygons to inlay
-
-Other options: `target=`
-
-### -innerlines
-
-Create a polyline layer consisting of shared boundaries with no attribute data.
-
-`where=`   Filter lines using a JS expression (see the `-lines where=` option).
-
-Other options: `name=` `+` `target=`
-
-```bash
-# Example: Extract the boundary between two states.
-mapshaper states.shp -filter 'STATE=="OR" || STATE=="WA"' -innerlines -o out.shp
-```
-
-
-### -join
-
-Join attribute data from a source layer or file to a target layer. If the `keys=` option is used, Mapshaper will join records by matching the values of key fields. If the `keys=` option is missing, Mapshaper will perform a polygon-to-polygon, point-to-polygon, polygon-to-point or point-to-point spatial join.
-
-`<file|layer>` or `source=` File or layer containing data records to join.
-
-`keys=`  Names of two fields to use as join keys, separated by a comma. The key field from the destination table is followed by the key field from the source table. If the `keys=` option is missing, mapshaper performs a spatial join.
-
-`calc=` Use JS assignments and built-in functions to convert values from the source table to (new) fields the target table. See the [`-calc` command reference](#-calc) for a list of supported functions. Useful for handling many-to-one joins. See example below.
-
-`where=`  Use a boolean JS expression to filter records from the source table. The expression has the same syntax as the expression used by the `-filter` command. The functions `isMax(<field>)` `isMin(<field>)` and `isMode(<field>)` can be used in many-to-one joins to select among source records.
-
-`fields=`  A comma-separated list of fields to copy from the external table. If the `fields` option and `calc` options are both absent, all fields are copied except the key field (if joining on keys) unless the. Use `fields=*` to copy all fields, including any key field. Use `fields=` (empty list) to copy no fields.
-
-`prefix=` Add a prefix to the names of fields joined from the external attribute table.
-
-`interpolate=`  (polygon-to-polygon joins only) A list of fields to interpolate/reaggregate based on area of overlap. Interpolates fields containing count data, such as population counts or vote counts. Treats data as being uniformly distributed within polygon areas. Also interpolates string fields containing categorical data. The value associated with the largest area of overlap between source and target polygons gets copied to the target feature.
-
-`point-method` (polygon-to-polygon joins only) Use an alternate method for joining two polygon layers. The default polygon-polygon join method detects areas of overlap between two polygon layers by compositing the two layers internally. This method is simpler -- it generates a temporary point layer from the source layer with the greater number of features (using the same inner-point method as the `-points inner` command), and then performs a point-to-polygon or polygon-to-point join. This method does not support the `interpolate=` option.
-
-`largest-overlap` (polygon-to-polygon joins only) selects a single polygon to join when multiple source polygons overlap a target polygon, based on largest area of overlap.
-
-`min-overlap-pct=` (polygon-to-polygon joins only) Only source features with at least this percentage overlap of the target feature (by area) get joined.
-
-`min-overlap-area=` (polygon-to-polygon joins only) Only source features with at least this much areal overlap of the target feature get joined.
-
-`max-distance=` (point-to-point joins only) Join source layer points within this distance of a target layer point.
-
-`duplication`  Create duplicate features in the target layer on many-to-one joins.
-
-`sum-fields=` (deprecated) A comma-separated list of fields to sum when several source records match the same target record. This option is equivalent to using the `sum()` function inside a `calc=` expression like this: `calc='FIELD = sum(FIELD)'`.
-
-`string-fields=` A comma-separated list of fields in source CSV file to import as strings (e.g. FIPS,ZIPCODE).
-
-`field-types=` A comma-separated list of type hints (when joining a CSV file or other delimited text file). See `-i field-types=` above.
-
-`force`  Allow values in the target data table to be overwritten by values in the source table when both tables contain identically named fields.
-
-`unjoined`  Copy unjoined records from the source table to a layer named "unjoined".
-
-`unmatched`  Copy unmatched records from the destination table to a layer named "unmatched".
-
-Other options: `encoding=` `target=`
-
-**Examples**
-
-Join a point layer to a polygon layer (spatial join), using the `calc=` option to handle many-to-one matches.
-
-```bash
-mapshaper states.shp \
-  -join points.shp calc='median_score = median(SCORE),
-                         mean_score = average(SCORE),
-                         join_count = count()' \
-  -o out.shp
-```
-
-Copy data from a csv file to the attribute table of a Shapefile by matching values from the *STATE_FIPS* field of the Shapefile and the *FIPS* field of the csv file. (The string-fields=FIPS argument prevents FIPS codes in the CSV file from being converted to numbers.)
-
-```bash
-mapshaper states.shp \
-  -join demographics.txt keys=STATE_FIPS,FIPS string-fields=FIPS \
-  -o out.shp
-```
-
-### -lines
-
-Converts points and polygons to lines. Polygons are converted to topological boundaries. Without the `<fields>` argument, external (unshared) polygon boundaries are attributed as `TYPE: "outer", RANK: 0` and internal (shared) boundaries are `TYPE: "inner", RANK: 1`. 
-
-`<fields>` or `fields=` (Optional) comma-separated list of attribute fields for creating a hierarchy of polygon boundaries. A single field name adds an intermediate level of hierarchy with attributes: `TYPE: <field name>, RANK: 1`, and the lowest-level internal boundaries are given attributes `TYPE: "outer", RANK: 2`. A comma-separated list of fields adds additional levels of hierarchy.
-
-`where=`  Use a JS expression for filtering polygon boundaries using properties of adjacent polygons. The expression context has objects named A and B, which represent features on eather side of a path. B is null if a path only belongs to a single feature.
-
-`each=`   Apply a JS expression to each line (using A and B, like the `where=` option).
-
-`groupby=`  Convert a point layer into multiple lines, using a field value for grouping.
-
-Common options: `name=` `+` `target=`
-
-```bash
-# Example: Classify national, state and county boundaries.
-mapshaper counties.shp -lines STATE_FIPS -o boundaries.shp
-```
-
-```bash
-# Example: add the names of neighboring countries to each section of border
-mapshaper countries.geojson \
-  -lines each='COUNTRIES = A.NAME + (B ? "," + B.NAME : "")' \
-  -o borders.geojson
-```
-
-
-### -merge-layers
-
-Merge features from several layers into a single layer. Layers can only be merged if they have compatible geometry types. Target layers should also have compatible data fields, unless the `force` option is used.
-
-`force`  Allow merging layers with inconsistent fields. When a layer is missing a particular field, the field will be added, with the values set to `undefined`. Using this option, you are still prevented from merging fields with different data types (e.g. a field containing numbers in one layer and strings in another). You are also still prevented from merging layers containing different geometry types.
-
-`flatten` (polygon layers) Remove polygon overlaps by assigning overlapping areas to the last overlapping polygon (the topmost feature if features are rendered in sequence).
-
-Common options: `name=` `target=`
-
-```bash
-# Example: Combine features from several Shapefiles into a single Shapefile.
-# -i combine-files is used because files are processed separately by default.
-mapshaper -i OR.shp WA.shp CA.shp AK.shp combine-files \
-	-merge-layers \
-	-o pacific_states.shp
-```
-
-### -mosaic
-
-Flatten a polygon layer by converting overlapping areas to separate polygons.
-
-`calc=` Use a JavaScript expression to handle many-to-one aggregation (similar to the `calc=` option of the`-join` and `-dissolve` functions). See [-calc](#-calc) for a list of supported functions.
-
-Common options: `name=` `+` `target=`
-
-
-### -point-grid
-
-Create a rectangular grid of points.
-
-`<cols,rows>`  Size of the grid, e.g. `-point-grid 100,100`.
-
-`interval=`    Distance between adjacent points, in source units (alternative to setting the number of cols and rows).
-
-`bbox=`        Fit the grid to a bounding box (xmin,ymin,xmax,ymax). Defaults to the bounding box of the other data layers, or of the world if no other layers are present.
-
-`name=`        Set the name of the point grid layer
-
-### -points
-
-Create a point layer, either from polygon or polyline geometry or from values in the attribute table. By default, polygon features are replaced by a single point located at the centroid of the polygon ring, or the largest ring of a multipart polygon. By default, polyline features are replaced by a single point located at the polyline vertex that is closest to the center of the feature's bounding box (this can be used to join polylines to polygons using a point-to-polygon spatial join).
-
-`x=` Name of field containing x coordinate values. Common X-coordinate names are auto-detected (e.g. longitude, LON).
-
-`y=` Name of field containing y coordinate values. Common Y-coordinate names are auto-detected (e.g. latitude, LAT).
-
-`centroid` Create points at the centroid of the largest ring of each polygon feature. Point placement is currrently not affected by holes.
-
-`inner` Create points in the interior of the largest ring of each polygon feature. Inner points are located away from polygon boundaries.
-
-`vertices` Convert polygon and polyline features into point features containing the unique vertices in each shape.
-
-`vertices2` Convert all the vertices in polygon and polyline features into points, including duplicate coordinates (e.g. the duplicate endpoint coordinates of polygon rings).
-
-`endpoints` Capture the unique endpoints of polygon and polyline arcs.
-
-`midpoints`  Find the midpoint of each path in a polyline layer.
-
-`interpolated` Interpolate points along polylines. Requires the `interval=` option to be set. Original vertices are replaced by interpolated vertices.
-
-`interval=` Distance between interpolated points (in meters if coordinates are unprojected, or projected units).
-
-Common options: `name=` `+` `target=`
-
-```bash
-# Example: Create points in the interior of each polygon 
-mapshaper counties.shp -points inner -o points.shp
-
-# Example: Create points in the interior of each polygon (alternate method)
-mapshaper counties.shp \
-  -each 'cx=this.innerX, cy=this.innerY' \
-  -points x=cx y=cy \
-  -o points.shp
-```
-
-### -polygons
-
-Convert a polyline layer to a polygon layer by linking together intersecting polylines to form rings.
-
-`gap-tolerance=`  Close gaps ("undershoots") between polylines up to the distance specified by this option.
-
-`from-rings`  Convert a layer of closed polyline rings into polygons. Nested rings in multipart features are converted into holes.
-
-Common options: `target=`
-
-### -proj
-
-Project a dataset using a PROJ string, EPSG code or alias. This command affects all layers in the dataset(s) containing the targeted layer or layers. Information on PROJ string syntax can be found on the [PROJ website](https://proj.org/usage/index.html).
-
-`<crs>` or `crs=`  Target CRS, given as a Proj.4 definition or an alias. Use the [`-projections`](#-projections) command to list available projections and aliases.  In projections which require additional parameters, such as a zone in UTM, you can pass a Proj4 string enclosed in quotes.  For example, `crs='+proj=utm +zone=27'`.
-
-`densify` Interpolate vertices along long line segments as needed to approximate curved lines.
-
-`match=` Match the projection of the given layer or .prj file.
-
-`init=` Define the pre-projected coordinate system, if unknown. This option is not needed if the source coordinate system is defined by a .prj file, or if the source CRS is WGS84. As with `crs`, you can pass a Proj4 string enclosed in quotes if the selected projection requires extra parameters, for example `init='+proj=utm +zone=33'`.
-
-`target=` Layer(s) to target. All layers belonging to the same dataset as a targeted layer will be reprojected. To reproject all datasets, use `target=*`.
-
-**Examples**
-```bash
-# Convert a GeoJSON file to New York Long Island state plane CRS,
-# using a Proj.4 string
-mapshaper nyc.json \
-  -proj +proj=lcc \
-        +lat_1=41.03333333333333 +lat_2=40.66666666666666 \
-        +lat_0=40.16666666666666 +lon_0=-74 \
-        +x_0=300000 +y_0=0 \
-        +ellps=GRS80 +datum=NAD83 +units=m \
-  -o out.json
-
-# Apply the same projection using an EPSG code
-mapshaper nyc.json -proj EPSG:2831 -o out.json
-
-# Convert a projected Shapefile to WGS84 coordinates
-mapshaper area.shp -proj wgs84 -o out.shp
-
-# Use the Winkel Tripel projection with a custom central meridian
-mapshaper countries.shp -proj +proj=wintri +lon_0=10 -o out.shp
-
-# Shortcut notation for the above projection
-mapshaper countries.shp -proj wintri +lon_0=10 -o out.shp
-
-# Convert an unprojected U.S. Shapefile into a composite projection with Alaska
-# and Hawaii repositioned and rescaled to fit in the lower left corner.
-# Show Puerto Rico and the U.S. Virgin Islands
-# Override the default central meridian and scale of the Alaska inset
-mapshaper us_states.shp \
-  -proj albersusa +PR +VI +AK.lon_0=-141 +AK.scale=0.4 \
-  -o out.shp
-```
-
-### -rectangle
-
-Create a new layer containing a rectangular polygon.
-
-`bbox=<xmin,ymin,xmax,ymax>`  Give the coordinates of the rectangle.
-
-`source=` Create a bounding box around a given layer.
-
-`aspect-ratio=`  Aspect ratio as a number or range (e.g. 2 0.8,1.6 ,2).
-
-`offset=` Padding as a distance or percentage of width/height (single value or list).
-
-`name=` Assign a name to the newly created layer.
-
-### -rectangles
-
-Create a new layer containing a rectangular polygon for each feature in the layer.
-
-`aspect-ratio=`  Aspect ratio as a number or range (e.g. 2 0.8,1.6 ,2).
-
-`bbox=` Use an expression to generate rectangle bounds for each feature. The expression should evaluate to a GeoJSON-style bbox array.
-
-`offset=` Padding as a distance or percentage of width/height (single value or list).
-
-`name=` Assign a name to the newly created layer.
-
-### -rename-fields
-
-Rename data fields. To rename a field from A to B, use the assignment operator: B=A.
-
-`<fields>` or `fields=`  List of fields to rename as a comma-separated list. 
-
-Common options: `target=`
-
-```bash
-# Example: rename STATE_FIPS to FIPS and STATE_NAME to NAME
-mapshaper states.shp -rename-fields FIPS=STATE_FIPS,NAME=STATE_NAME -o out.shp
-```
-
-
-### -rename-layers
-
-Assign new names to layers. If fewer names are given than there are layers, the last name in the list is repeated with numbers appended (e.g. layer1, layer2).
-
-`<names>` or `names=`  One or more layer names (comma-separated).
-
-`target=`  Rename a subset of all layers.
-
-```bash
-# Example: Create a TopoJSON file with sensible object names.
-mapshaper ne_50m_rivers_lake_centerlines.shp ne_50m_land.shp combine-files \
-  -rename-layers water,land -o target=* layers.topojson 
-```
-
-### -require
-
-Require a Node module or ES module for use in commands like `-each` and `-run`. Modules are added to the expression context. When the `alias=` option is given, modules are accessed via their aliases. Modules that are imported by name (e.g. `-require d3`) are accessed via their name, or by their alias if the `alias=` option is used. Module files without an alias name have their exported functions and data added directly to the expression context.
-
-`<module>` or `module=`  Name of an installed module or path to a module file.
-
-`alias=` Import the module as a custom-named variable.
-
-```bash
-# Example: use the underscore module (which has been installed locally)
-$ mapshaper data.json \
-	-require underscore alias=_ \
-	-each 'id = _.uniqueId()' \
-	-o data2.json
-```
-
-```bash
-# Example: import a module file containing a user-defined function 
-$ mapshaper data.json \
-  -require scripts/includes.mjs \
-  -each 'displayname = getDisplayName(d)' \
-  -o data2.json
-```
-
-### -run
-
-Run mapshaper commands from a [command file](#command-files) or generated on-the-fly from a JS expression.
-
-`<file|expression>`  Either:
-- A path to a mapshaper [command file](#command-files).
-- A JS expression or template containing embedded expressions, for generating one or more mapshaper commands.
-
-* Embedded expressions are enclosed in curly braces (see below).
-* Expressions can access `target` and `io` objects.
-* Expressions can also access functions and data loaded with the `-require` command.
-* Functions can be async.
-
-Expression context:
-
-If command has a single target layer:
-`target` object provides data and information about the command's target layer
-- `target.layer_name`  Name of layer
-- `target.geojson`  (getter/setter) Returns a GeoJSON FeatureCollection for the layer (getter) or replaces the layer with the contents of a GeoJSON object (setter).
-- `target.geometry_type` One of: polygon, polyline, point, `undefined`
-- `target.feature_count` Number of features in the layer
-- `target.null_shape_count` Number of features with null geometry
-- `target.null_data_count` Number of features with no attribute data
-- `target.bbox` GeoJSON-style bounding box
-- `target.proj4` PROJ-formatted string giving the CRS (coordinate reference system) of the layer
-
-`targets` object gives access to all layers targetted by the run command.
-- by numerical index, like an array (`targets[0]` refers to the first target layer)
-- by layer name (`targets.states` refers to a layer named "states")
-
-`io` object has a method for passing data to the `-i` command.
-- `io.ifile(<filename>, <data>)` Create a temp file to use as input in a `-run` command (see example 2 below)
-
-**Example 1:** Apply a custom projection based on the layer extent.
-
-```bash
-$ mapshaper -i country.shp \
-    -require projection.js \
-    -run '-proj {tmerc(target.bbox)}' \
-    -o
-```
-
-```javascript
-// contents of projection.js file
-module.exports.tmerc = function(bbox) {
-  var lon0 = (bbox[0] + bbox[2]) / 2,
-      lat0 = (bbox[1] + bbox[3]) / 2;
-  return `+proj=tmerc lat_0=${lat0} lon_0=${lon0}`;
-};
-```
-
-**Example 2:** Convert points to a Voronoi diagram using a template expression
-together with an external script.
-
-```bash
-$ mapshaper points.geojson \
-  -require script.js \
-  -run '-i {io.ifile("voronoi.json", voronoi(target.geojson, target.bbox))}' \
-  -o
-```
-
-```javascript
-// contents of script.js file
-module.exports.voronoi = async function(points, bbox) {
-  const d3 = await import('d3-delaunay'); // installed locally
-  const coords = points.features.map(feat => feat.geometry.coordinates);
-  const voronoi = d3.Delaunay.from(coords).voronoi(bbox);
-  const features = Array.from(voronoi.cellPolygons()).map(function(ring, i) {
-    return {
-      type: 'Feature',
-      properties: points.features[i].properties,
-      geometry: {
-        type: 'Polygon',
-        coordinates: [ring]
-      }
-    };
-  });
-  return {type: 'FeatureCollection', features: features};
-};
-```
-
-### -scalebar
-
-Add a scale bar to an SVG map. The command creates a data-only layer containing the scale bar's data properties. A scale bar is included in the SVG output file if the scale bar layer is included as an output layer.
-
-The length of the scale bar reflects the scale in the center of the map's rectangular frame.
-
-`<label>` or `label=` Optional label giving the size and units of the scalebar, e.g. `"25 k.m."`. If only units are given, a length will be assigned. If the `label` property is missing, scale bar properties will be auto-generated. If two lengths are given (e.g. `1000 km,500 miles`), a dual-unit bar will be generated, if the scale bar style supports it.
-
-`style=` Scalebar style, `a` or `b`. Style `b` has tic marks.
-
-`bar-width=` Line width of bar.
-
-`tic-length=` (style b) length of tic marks.
-
-`label-position=` Position of labels relative to the bar (`top` or `bottom`).
-
-`position=` Position of the scalebar on the map (default is `top-left`).
-
-`margin=` Offset in pixels from edge of map.
-
-
-### -shape
-
-Create a new layer containing a single polyline or polygon shape.
-
-`coordinates=<x,y,...>`  Specify vertex coordinates as a comma-separated list.
-
-`offsets=<dx,dy,...>`   Specify vertex coordinates as a list of offsets from the previous vertex. The first vertex in the list is offset from the last coordinate in the `coordinates=` list.
-
-`closed`  Close an open path to form a polygon shape.
-
-`name=` Assign a name to the newly created layer.
-
-
-### -simplify
-
-Mapshaper supports Douglas-Peucker simplification and two kinds of Visvalingam simplification.
-
-Douglas-Peucker (a.k.a. Ramer-Douglas-Peucker) produces simplified lines that remain within a specified distance of the original line. It is effective for thinning dense vertices but tends to form spikes at high simplification.
-
-Visvalingam simplification iteratively removes the least important point from a polyline. The importance of points is measured using a metric based on the geometry of the triangle formed by each non-endpoint vertex and the two neighboring vertices. The `visvalingam` option uses the "effective area" metric &mdash; points forming smaller-area triangles are removed first.
-
-Mapshaper's default simplification method uses Visvalingam simplification but weights the effective area of each point so that smaller-angle vertices are preferentially removed, resulting in a smoother appearance.
-
-When working with multiple polygon and polyline layers, the `-simplify` command is applied to all of the layers.
-
-**Options**
-
-`<percentage>` or `percentage=`  Percentage of removable points to retain. Accepts values in the range `0%-100%` or `0-1`.
-
-`dp` `rdp`	Use Douglas-Peucker simplification.
-
-`visvalingam`   Use Visvalingam simplification with the "effective area" metric.
-
-`weighted`   Use weighted Visvalingam simplification (this is the default). Points located at the vertex of more acute angles are preferentially removed, for a smoother appearance.
-
-`weighting=`  Coefficient for weighting Visvalingam simplification (default is 0.7). Higher values produce smoother output. `weighting=0` is equivalent to unweighted Visvalingam simplification.
-
-`resolution=`  Use an output resolution (e.g. `5000` or `1000x800`) to control the amount of simplification.
-
-`interval=`	 Specify simplification amount in units of distance (e.g. `100m`). If the distance unit is omitted (e.g. `interval=100`), uses meters when simplifying unprojected datasets in 3D space (see `planar` option below), otherwise uses the same units as the source data.
-
-`variable`  Apply a variable amount of simplification to the paths in a polygon or polygon layer. This flag changes the `interval=`, `percentage=` and `resolution=` options to accept JavaScript expressions instead of literal values. See [JavaScript expressions](/docs/guides/expressions.html.md) for the available context.
-
-`planar`  By default, mapshaper simplifies decimal degree coordinates in 3D space (using geocentric x,y,z coordinates). The `planar` option treats lng,lat coordinates as x,y coordinates on a Cartesian plane.
-
-`keep-shapes`   Prevent polygon features from disappearing at high simplification. For multipart features, mapshaper preserves the part with the largest original bounding box.
-
-`no-repair`	By default, mapshaper rolls back simplification along pairs of intersecting line segments by re-introducing removed points until either the intersection disappears or there are no more points to add. This option disables intersection repair.
-
-`stats`  Display summary statistics relating to the geometry of simplified paths.
-
-**Examples**
-```bash
-# Simplify counties.shp using the default algorithm,
-# retaining 10% of removable vertices.
-mapshaper counties.shp -simplify 10% -o simplified.shp
-
-# Use Douglas-Peucker simplification with a 100 meter threshold.
-mapshaper states.shp -simplify dp interval=100 -o simplified/
-```
-
-### -snap
-
-Snap together nearby vertices
-
-`interval` Snap tolerance (default is small).
-
-`endpoints` Only snap endpoints of polyline features.
-
-`precision=`  Round all coordinates to a given decimal precision (e.g. 0.000001).
-
-`fix-geometry` Remove segment intersections caused by rounding or snapping by reverting intersecting areas to original coordinates. This option is only applied if the original paths are free of intersections.
-
-[`target=`](#common-options)
-
-### -sort
-
-Sort features in a data layer using a JavaScript expression.
-
-`<expression>` or `expression=`  Apply a JavaScript expression to each feature, using the resulting values for sorting the features. Uses the same execution environment as [`-each`](#-each).
-
-`ascending` Sort in ascending order (this is the default).
-
-`descending` Sort in descending order.
-
-[`target=`](#common-options)
-
-
-### -split
-
-Distributes features in the target layer to multiple output layers. If the `expression=` option is present, features with the same value are grouped together. The value of the expression is used to name the split-apart fields. If no argument is supplied, split-apart layers are numbered.
-
-`<expression>` or `expression=`  JS expression or name of the attribute field to split on.
-
-Common options: `+` `target=`
-
-**Examples**
-```bash
-# Split features from a named layer into new GeoJSON files using a data field.
-# Output names use the original layer name + data values,
-# e.g. states-AK.json, states-AL.json, etc.
-mapshaper states.shp -split STATE -o format=geojson
-
-# Split features from an unnamed layer into new GeoJSON files
-# using a data field.
-# Output names contain data values,
-# e.g. AK.json, AL.json, etc.
-mapshaper states.shp name='' -split STATE -o format=geojson
-
-# Split source features into individual GeoJSON files (no data field supplied).
-# Output names use source layer name + ascending number,
-# e.g. states-1, states-2, etc.
-mapshaper states.shp -split -o format=geojson
-```
-
-### -split-on-grid
-
-Split features into separate layers using a grid of cols,rows cells. Useful for dividing a large dataset into smaller files that can be loaded dynamically into an interactive map. Use `-o bbox-index` to export a file containing the name and bounding box of the shapes in each file. Empty cells are removed from the output.
-
-`<cols,rows>`  Size of the grid, e.g. `-split-on-grid 12,10`
-
-Common options: `target=` 
-
-### -subdivide
-
-Recursively divide a layer using a boolean JS expression. The expression is first evaluated against all features in the layer. If true, the features are spatially partitioned either vertically or horizontally, according to whether the aggregate bounding box is relatively tall or wide. See example below.
-
-Subdivide expressions can call several functions that operate on a group of features. The `sum()` function takes a feature-level expression as an argument and returns the summed result after applying the expression to each feature in the group. Similar functions include `min()` `max()` `average()` and `median()`.
-
-`<expression>` or `expression=` Boolean JavaScript expression
-
-Common options:  `target=`
-
-**Example**
-```bash
-# Aggregate census tracts into groups of less than 1,000,000 population
-# and less than 100 sq km in area.
-mapshaper tracts.shp
-  -subdivide "sum('POPULATION') >= 1000000 && sum('this.area') > 1e8" \
-  -dissolve sum-fields=POPULATION \
-  -merge-layers \
-  -o tract_groups.shp
-```
-
-### -style
-
-Add common SVG attributes for SVG export and display in the web UI. Attribute values take either a literal value or a JS expression. See [JavaScript expressions](/docs/guides/expressions.html.md) for the available context. This command was named `-svg-style` in earlier versions of mapshaper.
-
-`where=`           Boolean JS expression for targetting a subset of features.
-
-`clear` Remove all style properties from a layer.
-
-`class=`           One or more CSS classes, separated by spaces (e.g. `class="light semi-transparent"`)
-
-`css=`             Inline CSS to use as the `style=` attribute of each SVG symbol.
-
-`fill=`            Fill color (e.g. `#eee` `pink` `rgba(0, 0, 0, 0.2)`)
-
-`fill-pattern=`    Definition string for a pattern. There are four pattern types: hatches, dots, squares and dashes. The syntax for each pattern is:
-
-- hatches [rotation] width1 color1 [width2 color2 ...]
-- dots [rotation] size color1 [color2 ...] spacing background-color
-- squares [rotation] size color1 [color2 ...] spacing background-color
-- dashes [rotation] dash-length space-length line-width color line-spacing background-color
-
-Example: `hatches 45deg 2px red 2px grey`
-
-`fill-effect=sphere`  Add a gradient effect to the bounding circle of a globe projection (e.g. `ortho` `npers`) to create a 3d effect.
-
-`stroke=`          Stroke color
-
-`stroke-width=`    Stroke width
-
-`stroke-dasharray=` Dashes
-
-`opacity=`         Symbol opacity (e.g. `opacity=0.5`)
-
-`r=`               Circle radius. Setting this exports points as SVG `<circle>` symbols, unless the `-o point-symbol=square` option is used.
-
-`label-text=`      Label text (set this to export points as labels). To create multiline labels, insert line delimiters into the label text. There are three possible line delimiters: the newline character, `\n` (backslash + "n"), and `<br>`. (When importing JSON data, `\n` in a JSON string is parsed as a newline and `\\n` is parsed as backslash + "n"). Note that Mapshaper doesn't accept multiline strings as input on the command line.
-  
-`text-anchor=`     Horizontal justification of label text. Possible values are: start, end or middle (the default).
-
-`dx=`              X offset of labels (default is 0)
-
-`dy=`              Y offset of labels (default is baseline-aligned)
-  
-`font-size=`       Size of label text (default is 12)
-  
-`font-family=`     CSS font-family of labels (default is sans-serif)
-
-`font-weight=`     CSS font-weight property of labels (e.g. bold, 700)
-
-`font-style=`      CSS font-style property of labels (e.g. italic)
-
-`font-stretch=`      CSS font-stretch property of labels (e.g. condensed)
-
-`letter-spacing=`  CSS letter-spacing property of labels
- 
-`line-height=`     Line spacing of multi-line labels (default is 1.1em). Lines are separated by newline characters or `<br>` tags in the label text.
-
-Common options: `target=`
-
-**Example**
-
-```bash
-# Apply a 2px grey stroke and no fill to a polygon layer
-mapshaper polygons.geojson \
--style fill=none stroke='#aaa' stroke-width=2 \
--o out.svg
-```
-
-### -symbols
-
-Symbolize points as regular polygons, circles, stars, arrows and other shapes.
-
-`type=`            Basic types: star, polygon, circle, arrow, ring. Aliases: triangle, square, pentagon, etc.
-
-`fill=`            Symbol fill color
-
-`stroke=`          Symbol line color (linear symbols only)
-
-`stroke-width=`    Symbol line width (linear symbols only)
-
-`opacity=`         Symbol opacity
-
-`geographic`       Make geographic shapes (polygons or polylines) instead of SVG objects
-
-`pixel-scale=`     Set symbol scale in meters-per-pixel (for polygons option)
-
-`rotated`          Symbol is rotated to an alternate orientation
-
-`rotation=`        Rotation of symbol in degrees
-
-`scale=`           Scale symbols by a multiplier
-
-`radius=`          Distance from center to farthest point on the symbol
-
-`sides=`           (polygon) number of sides of a polygon symbol
-
-`points=`          (star) number of points
-
-`point-ratio=`     (star) ratio of minor to major radius of star
-
-`radii=`           (ring) comma-sep. list of concentric radii, ascending order
-
-`length=`          (arrow) length of arrow in pixels
-
-`direction=`       (arrow) angle off of vertical (-90 = left-pointing)
-
-`head-angle=`      (arrow) angle of tip of arrow (default is 40 degrees)
-
-`head-width=`      (arrow) width of arrow head from side to side
-
-`head-length=`     (arrow) length of head (alternative to head-angle). Use `head-length=0` to make headless arrows (i.e. simple lines)
-
-`stem-width=`      (arrow) width of stem at its widest point
-
-`stem-length=`     (arrow) alternative to length
-
-`stem-taper=`      (arrow) factor for tapering the width of the stem (0-1)
-
-`stem-curve=`      (arrow) curvature in degrees (default is 0)
-
-`min-stem-ratio=`  (arrow) minimum ratio of stem to total length. This option scales down the entire symbol instead of making the stem shorter than the given ratio.
-
-`anchor=`          (arrow) takes one of: start, middle, end (default is start)
-
-Common options: `name=` `+` `target=`
-
-### -union
-
-Create a composite layer (a polygon mosaic without overlaps) from two or more target polygon layers.
-
-Data values are copied from source features to output features. (Areal interpolation may
-be added in the future. The `-join` command currently supports areal interpolation between polygon layers using the `-join interpolate=<fields>` option.) Same-named fields in source layers are renamed in the output layer. For example, two source-layer fields named "id" will be renamed to "id_1" and "id_2".
-
-`fields=`  Fields to retain (default is all fields).
-
-Common options: `name=` `+` `target=`
-
-### -uniq
-
-Delete features with the same id as a previous feature
-
-`<expression>` or `expression=`  JS expression to obtain the id of a feature. Uses the same expression syntax as [`-each`](#-each).
-
-`max-count=` Allow multiple features with the same id (default is 1).
-
-`invert` Retain only features that would ordinarily be deleted by `-uniq`.
-
-`verbose`  Print information about each removed feature.
-
-`target=`
-
-```bash
-# Example: Retain only the largest parts of each multipart polygon
-mapshaper polygons.shp \
-	-each 'fid = this.id' \
-	-explode \
-	-sort 'this.area' descending \
-	-uniq 'fid' \
-	-o out.shp
-```
-
-## Control Flow Commands
-
-### -if
-
-The `if` command runs the following commands if a condition is met.
-
-`<expression>` or `expression=`  Use a JavaScript expression to test a condition.
-
-`empty`         Test if layer is empty.
-
-`not-empty`     Test if layer contains data.
-
-`layer=`        Name or id of layer to test (default is current target layer).
-
-**Properties of `this`**
-
-- `this.name`   Layer name, or <undefined> if layer is unnamed.
-- `this.size`   Number of features in the layer.
-- `this.empty`  True if layer contains 0 features.
-- `this.data`   Array of attribute data records, one object per feature.
-- `this.type`   Geometry type, one of: polygon, polyline, point, <undefined>.
-- `this.bbox`   An array [xmin, ymin, xmax, ymax] with additional properties: cx, cy, height, width, left, bottom, top, right.
-
-**Functions of `this`**
-
-- `this.field_exists(<name>)`  Tests if a data field exists in the target layer.
-- `this.field_type(<name>)`    Returns the data type of a field, or `null` if a field is empty or missing. Types include: `"string" "number" "boolean" "date" "object"`. If a field includes multiple data types (which may occur in GeoJSON), the type of the first non-empty data value is returned.
-- `this.field_includes(<value>)`  Tests if a given value occurs at least once in a data field.
-- `this.file_exists(<filename>)`  Tests if a file exists.
-
-**Example**
-
-```bash
-mapshaper -i shapes.json -if '!this.empty' -dissolve -o out/dissolved.json
-```
-
-### -elif
-
-One or more `-elif` (short for "else if") commands may be added to test for alternate conditions, following an `-if` statement. The `-elif` command accepts the same options as the `-if` command.
-
-### -else
-
-Run the following commands if all preceding -if/-elif conditions are false.
-
-### -endif
-
-Mark the end of an -if/-elif/-else sequence.
-
-### -stop
-
-Stop processing (skip remaining commands). Useful when writing scripts, in combination with -if/-elif/-else.
-
-**Example**
-
-```bash
-# Don't try to process a missing file
-mapshaper -if '!file_exists("boundaries.geojson")' -stop -endif \
-  -i boundaries.geojson -proj robin -o output/boundaries.shp
-```
-
-### -target
-
-Set the target layer or layers for the following command.
-
-`<target>` or `target=`  Name or id of a layer (first layer is 1).
-
-`type=`  Type of layer(s) to match (polygon, polyline or point). This is useful when importing GeoJSON files containing several types of geometry.
-
-`name=`   Rename the target layer.
-
-
-## Informational Commands
-
-
-### -calc
-
-Perform calculations on a collection of records and display the results, using a JavaScript expression. The expression can use one or more of the following built-in functions. Most functions take the name of a data field or a JS expression as the first argument.
-
-The `calc` functions are also available in the context of `calc=` expressions, which can be used as options to `-join`, `-dissolve` and several other commands. See example below. For the full expression context (per-feature properties available inside `<expr>`, the `where=` filter syntax, etc.), see [JavaScript expressions](/docs/guides/expressions.html.md).
-
-| function | description |
-| --- | --- |
-| `count ()` | returns number of records in the collection |
-| `sum (<expr>)` | |
-| `mean (<expr>)` | |
-| `average (<expr>)` | same as mean() |
-| `median (<expr>)` | |
-| `mode (<expr>)` | returns most frequently occuring value in the collection (or the first such value in case of a tie). |
-| `min (<expr>)` | |
-| `max (<expr>)` | |
-| `quartile1 (<expr>)` | first quartile |
-| `quartile2 (<expr>)` | same as median() |
-| `quartile3 (<expr>)` | third quartile |
-| `iqr (<expr>)` | interquartile range |
-| `quantile (<expr>, <pct>)` | arbitrary percentile (`<pct>` is 0-1) |
-| `collect (<expr>)` | returns array containing all values |
-| `collectIds ()` | returns array of feature indexes (features are indexed 0 to n-1)
-| `first (<expr>)` | returns first value in the collection |
-| `last (<expr>)` | returns last value in the collection |
-| `every (<expr>)` | returns true if expression is true for all elements in the collection |
-| `some (<expr>)` | returns true if expression is true for one or more elements in the collection |
-
-Argument expressions take the same form as `-each` expressions. If no records are processed, `count()` and `sum()` return `0`, and the other functions return `null`.
-
-**Assignments**
-
-The `-calc` expression can take the form of one or more assignments. This creates global variables that can be accessed by subsequent expressions using the `global` namespace. For example:
-
-```
-mapshaper data.csv \
-  -calc 'N = count()' \
-  -if 'global.N < 5' \
-  -print 'LOW SAMPLE SIZE, STOPPING' \
-  -stop \
-  -endif
-```
-
-**Options**
-
-`<expression>` or `expression=` JS expression containing calls to one or more `-calc` functions.
-
-`where=`  Perform calculations on a subset of records, using a boolean JS expression as a filter (similar to [`-filter`](#-filter) command).
-`+` Save output to a layer.
-`name=` Name the output layer (default name is "calc").
-`target=`
-
-**Examples**
-
-```bash
-# Calculate the sum of a data field
-mapshaper ny-census-blocks.shp -calc 'sum(POPULATION)'
-
-# Count census blocks in NY with zero population
-mapshaper ny-census-blocks.shp -calc 'count()' where='POPULATION == 0'
-
-# Using calc functions in conjunction with the `-dissolve` command
-mapshaper counties.csv \
-  -dissolve STATE_NAME calc='NUM_COUNTIES = count()' \
-  -o states.csv
-```
-
-### -colors
-Print list of built-in color schemes. Color schemes can be used with the `color-scheme=` option of the [-classify](#-classify) command. (These color schemes come from the [d3-scale-chromatic](https://github.com/d3/d3-scale-chromatic) library.)
-
-### -comment
-The following text up to the next command is treated as a comment. Useful for adding explanatory comments to a long sequence of commands.
-
-### -encodings
-Print list of supported text encodings (for .dbf import).
-
-### -help
-
-Print usage tips and a list of commands.
-
-`<command>` Show options for a single command, e.g. `mapshaper -h join`.
-
-### -info
-
-Print information about a dataset. Useful for seeing the fields in a layer's attribute data table. Also useful for summarizing the result of a series of commands, or for debugging unexpected output.
-
-```bash
-# Example: Get information about an unknown GeoJSON or TopoJSON dataset
-mapshaper mystery_file.json -info
-```
-
-`save-to=` Save information to a .json file.
-`+` Save output to a layer.
-`name=` Name the output layer (default name is "info").
-
-### -inspect
-
-Print information about the data attributes of a feature.
-
-`<expression>` or `expression=` JS expression for selecting a feature (see [JavaScript expressions](/docs/guides/expressions.html.md) for the syntax and context).
-
-Common options: `target=`
-
-```bash
-# Example: View attribute data for a state
-mapshaper states.geojson -inspect 'NAME == "Delaware"'
-```
-
-### -print
-
-Prints a message to the console or terminal (using stdout). This command is useful in combination with the `-if/-elif/-else` commands.
-
-```bash
-# Example
-mapshaper cities.json \
--if 'this.empty' \
--print FILE IS EMPTY
-```
-
-### -projections
-
-Print list of supported proj4 projection ids and projection aliases.
-
-### -quiet
-
-Inhibit console messages.
-
-### -vars
-
-Define variables for [`{{VAR}}` interpolation](#variables). Each argument is either an inline assignment (`KEY=value`) or a path to a JSON file containing a flat object whose keys are variable names and whose values are strings, numbers or booleans.
-
-`-vars` can be used on the command line, inside a command file, or anywhere else a command is accepted. Each invocation writes to the templating-scope variable store, overwriting any previously defined value. Use [`-defaults`](#-defaults) instead if you want set-if-unset behavior.
-
-Values set by `-vars` are visible to `{{X}}` substitution but **not** by bare name in JS expressions (`-each`, `-filter`, `-define`, etc.). If you want a value usable from both, set it once with [`-define`](#-define) &mdash; `{{X}}` substitution falls back to the expression scope when a name isn't in the templating scope.
-
-**Options**
-
-`<values>` Space-separated list of `KEY=value` assignments and/or paths to JSON files containing variable definitions.
-
-**Example**
-
-```bash
-# Set YEAR=2024 before running the command file
-mapshaper -vars YEAR=2024 -run build.txt
-
-# Load values from a JSON file, then override one of them
-mapshaper -vars values.json YEAR=2030 -run build.txt
-```
-
-### -defaults
-
-Like [`-vars`](#-vars), but writes only those keys that are not already defined. Used inside a command file to declare overridable defaults: a CLI `-vars` (or any earlier write) preempts the command file's `-defaults` for the same key.
-
-**Options**
-
-`<values>` Space-separated list of `KEY=value` assignments and/or paths to JSON files containing variable definitions.
-
-**Example**
-
-```bash
-# build.txt declares YEAR=2024 as a default; this CLI invocation overrides it
-mapshaper -vars YEAR=2030 -run build.txt
-```
-
-### -verbose
-
-Print verbose messages, including the time taken by each processing step.
-
-### -version
-
-Print mapshaper version.
-
----
-
-<!-- https://mapshaper.org/docs/gallery/ -->
-
-# Gallery
-
-A collection of example maps made with Mapshaper. Each tile links to a full write-up with the recipe, the source data, and a one-click link to open the finished snapshot in the [web app](/).
-
-<!-- mapshaper:gallery -->
-
----
-
-<!-- https://mapshaper.org/docs/essentials/command-line.html -->
-
-# The command-line tool
-
-Mapshaper ships as a command-line tool and a [web app](/docs/essentials/web-app.html.md). This page is a tour of the CLI and the most common things you'll use it for.
-
-## Install
-
-Mapshaper requires [Node.js](https://nodejs.org). With Node installed:
-
-```bash
-npm install -g mapshaper
-```
-
-That gives you three executables:
-
-- `mapshaper` &mdash; the main CLI.
-- `mapshaper-xl` &mdash; same as `mapshaper`, but launched with a larger Node heap (8 GB by default) for processing very large files. Override the limit with `mapshaper-xl 16gb [commands]`.
-- `mapshaper-gui` &mdash; runs the [web UI](/docs/essentials/web-app.html.md) locally on `http://localhost:5555`.
-
-You can also run mapshaper without installing it via [Bun](https://bun.sh/) (`bunx mapshaper [commands]`) or with `npx mapshaper [commands]`.
-
-Check the install with:
-
-```bash
-mapshaper -v
-```
-
-## Anatomy of a Mapshaper command
-
-A Mapshaper invocation is a sequence of commands run left-to-right. Each command starts with a hyphen-prefixed name and is followed by zero or more options. The initial `-i` (input) command is implied if the first argument is a file path.
-
-```bash
-mapshaper provinces.shp -simplify dp 20% -o precision=0.00001 output.geojson
-```
-
-This reads a Shapefile, simplifies it using the Douglas-Peucker algorithm to 20% of its vertices, and writes a GeoJSON file with rounded coordinates.
-
-Options come in three forms:
-
-- **Values** like `provinces.shp` and `output.geojson`.
-- **Flags** like `dp`.
-- **Name/value pairs** like `precision=0.00001`.
-
-For the full reference, see the [command reference](/docs/reference.html.md).
-
-## Some examples
-
-### Get help
-
-```bash
-mapshaper -h                 # list all commands
-mapshaper -h simplify        # detailed options for one command
-```
-
-### Chain commands
-
-```bash
-# From census blocks: dissolve populated Census blocks to tract level.
-mapshaper tabblock2010_36_pophu.shp \
-  -filter 'POP10 > 0' \
-  -each 'TRACT=BLOCKID10.substr(0,11)' \
-  -dissolve TRACT sum-fields=POP10 \
-  -o tracts.shp
-```
-
-```bash
-# Generate state and national boundaries from one county-level Shapefile.
-# Output: states.shp, usa.shp and other Shapefile component files
-mapshaper counties.shp \
-  -dissolve STATE_FIPS name=states \
-  -dissolve + name=usa \
-  -o target='*'
-```
-
-For a broader set of recipes — filtering, joining, dissolving, reprojection, styling and more — see [Basics](/docs/examples/basics.html.md).
-
-## Working with layers
-
-Most commands operate on **layers** of data features. A layer is a collection of features with the same geometry type and a consistent attribute schema. Mapshaper supports polygon, polyline and point layers; a single feature may contain one shape, multiple shapes, or no shapes at all.
-
-The simplest case is a single layer in, a single layer out:
-
-```bash
-mapshaper counties.shp -filter 'this.isNull === false' -o counties_notnull.shp
-```
-
-When a command runs on a multi-layer dataset, it acts on the **target** layer(s). Most commands accept a `target=` option, and the [`-target`](/docs/reference.html.md#-target) command sets the target for everything that follows.
-
-The `+` option keeps the original layer and creates a new one from the command's output. Combined with `name=`, it's the idiomatic way to derive a new layer:
-
-```bash
-# Output: out/provinces.json and out/lines.json
-mapshaper provinces.shp \
-  -simplify 20% \
-  -innerlines + name=lines \
-  -target provinces,lines \
-  -o format=geojson out/
-```
-
-This produces `out/provinces.json` and `out/lines.json`.
-
-When importing a TopoJSON file, each named object becomes a layer:
-
-```bash
-mapshaper usa.topojson \
-  -filter 'STATE == "HI"' target=states \
-  -o out/hawaii.geojson
-```
-
----
-
-<!-- https://mapshaper.org/docs/essentials/web-app.html -->
-
-# The web app
-
-The Mapshaper web app at [mapshaper.org](/) is designed for interactive editing and visual exploration. Its built-in console exposes the complete command set, so almost anything the CLI can do is available directly in the browser.
-
-All processing happens in your browser. Your data stays on your machine, even when you use the public website.
-
-## Loading data
-
-Drag-drop, paste, or use the **Add files** button to import data.
-
-A few less-obvious behaviors:
-
-- **Drop a `.zip` containing a Shapefile bundle** &mdash; Mapshaper unzips it on the fly and pulls out the sidecars. (Same goes for `.gz` for single-file formats and `.kmz` for KML.)
-- **Paste a URL** anywhere on the page to import the file at that address.
-- **Query-string preload** &mdash; `https://mapshaper.org/?files=URL1,URL2` imports a comma-separated list of URLs. All files need to be served from a host that allows cross-origin requests. Append `&q` to skip the import dialog and open the files immediately.
-- **With advanced options** is a freeform text field. Anything you'd pass after `-i` on the CLI works here, including `encoding=`, `string-fields=`, `csv-fields=`, `csv-filter=`, `combine-files`, `name=` and so on.
-- **Multiple files do not auto-combine.** Selecting several files at once imports them as independent layers. To get a shared topology (so common boundaries simplify identically), tick **with advanced options** and add `combine-files`.
-
-### Tips for importing Shapefiles
-
-- Drag-drop or select the `.shp`, `.dbf` and `.prj` files together. Without `.dbf` you'll have geometry but no attributes; without `.prj`, projection-dependent commands won't know what to do.
-- If you see a warning about an unknown text encoding, re-import using the **with advanced options** checkbox and set `encoding=` (for example, `encoding=big5` for Big-5).
-
-## The console
-
-The Console (top-right of the header, or **space bar** to toggle) is the most powerful part of the UI. Anything the [CLI](/docs/reference.html.md) can do, you can do here.
-
-### Keyboard
-
-- **Space** &mdash; open or close the console (only when you're not typing in another text field).
-- **Esc** &mdash; close the console, or close any open panel.
-- **Up / Down** &mdash; cycle through previous commands. The history persists across page reloads.
-- **Backslash `\` at end of line** &mdash; continue a long command on the next line. The Enter key adds the wrap; another **Enter** runs the full command.
-
-### Syntax
-
-- The leading `-` is optional in the console: `clip places` works the same as `-clip places`.
-- Commands run on the **currently-selected layer** by default. Switch layers in the layer panel before issuing a command, or pass `target=` to be explicit (`target=*` runs against every layer).
-
-### Magic words at the prompt
-
-These are recognized directly by the console, not by Mapshaper:
-
-- `history` &mdash; print the current session as a single command-line string. Handy for reproducing an interactive workflow as a script.
-- `layers` &mdash; print the list of loaded layers.
-- `clear` &mdash; clear the console buffer.
-- `close` / `exit` / `quit` &mdash; close the console.
-
-### Discovering commands
-
-- `help` lists every available command.
-- `help <command>` shows the full options for one command, e.g. `help dissolve`.
-- The [command reference](/docs/reference.html.md) is the same content with a search box.
-
-## The map
-
-### Right-click menu
-
-The right-click menu adapts to what's under the cursor:
-
-- **Copy lon, lat** &mdash; copy the WGS84 coordinates of the click point to the clipboard.
-- **Copy x, y** &mdash; copy the projected coordinates of the click point.
-- **Copy as GeoJSON** &mdash; copy the selected feature(s) to the clipboard as GeoJSON. Useful for snipping out one polygon for use elsewhere.
-- **Delete vertex** / **delete point** / **delete feature** &mdash; available in the corresponding edit modes.
-
-### Layer navigation
-
-- **Left / Right arrows** (when not typing) &mdash; cycle through the loaded layers.
-
-## Display options
-
-The **Display** button at the top right opens the display options panel.
-
-- **Detect line intersections** &mdash; highlights self-intersections in red as you simplify or edit. The quickest way to spot simplification damage. The setting is remembered between sessions.
-
-## Snapshots and session history
-
-The ribbon icon in the layer panel opens the snapshot menu. Snapshots save the current state of a session so you can return to it. They also record the **session history** that produced the snapshot, so when you re-open one the full history is available too.
-
-- **Create a snapshot** &mdash; saves to in-browser storage. These are session-scoped and **deleted when the tab closes or the page is reloaded.** For anything you want to keep, **Save snapshot to file** writes a `.msx` file you can re-open later.
-- **View session history** &mdash; a shortcut for typing `history` in the console: prints the full sequence of commands that produced the current state.
-
-See the [Mapshaper snapshot format page](/docs/formats/snapshot.html.md) for more on what a `.msx` file contains and how to use it from the CLI.
-
-## Running the web UI locally
-
-`mapshaper-gui` (installed alongside `mapshaper` when you `npm install -g mapshaper`) starts a local Node web server and opens the web UI at `http://localhost:5555`. Use `--port` to pick a different port.
-
-You can pre-load files by listing them on the command line, which skips the import dialog:
-
-```bash
-mapshaper-gui states.shp rivers.shp
-```
-
-## Browser support
-
-When importing very large files (hundreds of megabytes), the web app may run out of memory and crash. Firefox used to be better than Chrome at handling large files, but Chrome seems to have improved recently. If the web app crashes, try the [`mapshaper-xl` command-line tool](/docs/essentials/command-line.html.md), which can allocate a large amount of memory.
-
-## Privacy
-
-The Mapshaper web app runs entirely in your browser. No file content is uploaded to any server. The only network traffic is for static assets (the app itself), basemap tiles when you've enabled a basemap, and analytics for `mapshaper.org` page loads. See the [privacy policy](/privacy.html) for details.
-
----
-
-<!-- https://mapshaper.org/docs/guides/simplification.html -->
-
-# Simplification
-
-Simplification reduces the number of vertices in polylines and polygon boundaries while preserving as much of their shape as possible. It is Mapshaper's original feature, and the workhorse for reducing large, detailed datasets to a size practical for web maps.
-
-## Choosing a method
-
-Mapshaper offers three simplification methods, selectable as flags to `-simplify`:
-
-- **`dp`** &mdash; Douglas-Peucker (also known as Ramer–Douglas–Peucker). Guarantees that simplified lines stay within a fixed distance of the original. Good for stripping excess vertices to reduce file size, but tends to grow visible spikes at high simplification.
-- **`visvalingam`** &mdash; The Visvalingam algorithm. Iteratively removes the point that forms the smallest triangle with its two neighbors.
-- **`weighted_visvalingam`** (Mapshaper's default) &mdash; Visvalingam's effective-area algorithm with a custom weighting that underweights points at sharp angles, so they are removed earlier than in standard Visvalingam. The result is visibly smoother lines and fewer jagged spikes at high simplification.
-
-Weighted Visvalingam is the default because it has proven to be versatile and effective at reducing detail in highly detailed source data. This method can be effective at generalizing very detailed source files, but be careful that it doesn't remove long, thin geographic features that you want to keep.You can control the amount of weighting used by Weighted Visvalingam with the `weighting=` option (default is 0.7).
-
-If you are only interested in minimizing file size, Douglas-Peucker is generally the better choice.
-
-
-
-**Figures**
-
-Natural Earth 10m coastlines, simplified with modified Visvalingam at 5% point retention.
-![image](/docs/images/simplification-mod2.png)
-
-Same file using Douglas-Peucker, also 5% simplification.
-![image](/docs/images/simplification-dp.png)
-
-Zoomed-in view of Norwegian coastline at 5% simplification; left: weighted Visvalingam, right: Douglas-Peucker.
-![image](/docs/images/simplification-detail.png)
-
-## Simplification amount
-
-On the command line, there are three ways to specify the amount of simplification to apply: `percentage`, `interval`, and `resolution`.
-
-Percentage is the default (you don't need to type `percentage=`). It gives the percentage of removable vertices to retain, so lower numbers = more simplification.
-
-```bash
-mapshaper provinces.geojson -simplify 20% \
-  -o provinces_simplified.geojson
-```
-
-The `interval` option takes a distance threshold. With Douglas-Peucker simplification (see below), this is the maximum deviation of the simplified line from the original. With Visvalingam-based methods, `interval=` describes the approximate size of the smallest details in the simplified output.
-
-```bash
-mapshaper provinces.geojson -simplify interval=500m \
-  -o provinces_simplified.geojson
-```
-
-The `resolution=` option lets you specify the intended display size of your map in SVG units (equivalent to CSS pixels). A larger value retains more detail, since Mapshaper estimates the display size using the full extent of your data. Be careful with this option if your final map will show a smaller geographic area, as the paths may be over-simplified.
-
-```bash
-mapshaper provinces.geojson -simplify resolution=800 \
-  -o provinces_simplified.geojson
-```
-
-See the [`-simplify` reference](/docs/reference.html.md#-simplify) for the full set of options.
-
-
-## Avoiding shape removal
-
-At high simplification, small polygons can disappear entirely. Pass `keep-shapes` to `-simplify` (or tick **prevent shape removal** in the web UI's Simplify panel) to retain at least one ring per multipart feature, regardless of how aggressive the simplification is.
-
-```bash
-mapshaper provinces.shp -simplify 5% keep-shapes -o provinces.geojson
-```
-
-## Spherical vs planar geometry
-
-By default, Mapshaper simplifies lat/long coordinates on the surface of a sphere, using 3D geometry. This applies a consistent amount of simplification across the whole globe, including near the poles. If your data is in a projected coordinate system, simplification uses 2D planar geometry.
-
-## Avoiding self-intersections
-
-Heavy simplification can pull adjacent polygon edges across each other, producing self-intersections. The `-simplify` command detects and tries to remove intersections automatically by rolling back simplification where the intersections occur. In the web UI, you can enable "detect line intersections" on the Display panel to show intersections as red dots. In this mode, you will see a button for repairing intersections caused by simplification.
-
-The [`-clean`](/docs/reference.html.md#-clean) command will also remove intersections:
-
-```bash
-mapshaper provinces.shp -simplify 5% -clean -o provinces.geojson
-```
-
-## Simplifying multiple layers consistently
-
-When you import multiple layers using `-i combine-files`, Mapshaper builds a shared topology. This means that boundaries shared between layers — for example, aligned state and county polygon borders — are simplified identically across both.
-Without this, the layers would diverge during simplification, creating visible gaps and overlaps where they should align.
-
-```bash
-mapshaper -i states.shp counties.shp combine-files \
-  -simplify 10% \
-  -o out/
-```
-
-The web app does **not** combine files automatically when you import multiple layers. To get the shared-topology behavior in the web app, tick **with advanced options** in the import dialog and add `combine-files` to the options field.
-
----
-
-<!-- https://mapshaper.org/docs/guides/expressions.html -->
-
-# JavaScript expressions
-
-Many Mapshaper commands take a **JS expression** as an argument or option. Expressions let you read and write per-feature attributes, derive new fields, filter records, sort, generate templated commands, and inspect layer-level metadata. The same expression syntax and execution context are reused across commands, so once you've learned the shape of a `-each` expression you can use it almost everywhere.
-
-```bash
-mapshaper counties.shp \
-  -each 'STATE_FIPS = COUNTY_FIPS.substr(0, 2),
-         AREA_KM2 = this.area / 1e6' \
-  -o out.shp
-```
-
-Expressions are plain JavaScript. They can use any built-in language feature (arithmetic, string methods, conditionals, regex, etc.). Some commands also expect the expression to return a particular kind of value &mdash; `-filter` and `-inspect` expect `true` or `false`, `-sort` expects a sort key, `-split` expects a group identifier, and so on.
-
-## Where expressions appear
-
-| Command | Expression role | Type |
-| --- | --- | --- |
-| [`-each`](/docs/reference.html.md#-each) | Run side-effects per feature, including assignments to data fields | feature |
-| [`-filter`](/docs/reference.html.md#-filter) | Boolean test, kept if `true` | feature, returns boolean |
-| [`-sort`](/docs/reference.html.md#-sort) | Returns the sort key for each feature | feature |
-| [`-inspect`](/docs/reference.html.md#-inspect) | Boolean test, prints matching feature(s) | feature, returns boolean |
-| [`-split`](/docs/reference.html.md#-split) | Returns the value used to group features into output layers | feature |
-| [`-subdivide`](/docs/reference.html.md#-subdivide) | Boolean test driving recursive partitioning, can call group functions like `sum()` | feature, returns boolean |
-| [`-calc` and `calc=` options](/docs/reference.html.md#-calc) | Aggregations across a group of features (`sum`, `count`, `median`, etc.) | calc |
-| `where=` (on `-filter`, `-each`, `-affine`, `-dashlines`, `-dissolve`, `-innerlines`, `-join`, `-style`, `-symbols`, `-calc`) | Sub-filter applied before the main operation | feature, returns boolean |
-| `weight=` on `-dissolve`/`-points` | Weighting expression for centroid calculation | feature |
-| Attribute options on [`-style`](/docs/reference.html.md#-style) and [`-symbols`](/docs/reference.html.md#-symbols) | Most values (`fill=`, `stroke=`, `stroke-width=`, `opacity=`, `r=`, `label-text=`, `dx=`, `dy=`, `font-size=`, etc.) accept either a literal or a JS expression evaluated per feature | feature |
-| [`-lines where=` and `each=`](/docs/reference.html.md#-lines) | Operates on **pairs** of features either side of a path, exposed as `A` and `B` | pair |
-| [`-if` / `-elif`](/docs/reference.html.md#-if) | Boolean test on layer-level metadata | layer |
-| [`-define`](/docs/reference.html.md#-define) | Stores variables and helper functions in a global namespace shared by later expressions | layer |
-| [`-run`](/docs/reference.html.md#-run) | Generates command strings, with embedded `{...}` template substitutions | template |
-
-<!-- | `bbox=` on `-rectangles` | Returns a `[xmin, ymin, xmax, ymax]` per feature | feature | -->
-These five flavors &mdash; **feature**, **calc**, **pair**, **layer** and **template** &mdash; share most of their context but differ in which variables are available and which functions are in scope.
-
-## The execution context
-
-Inside any feature-level expression you have access to:
-
-- **Field names as bare variables.** Reading a field name returns its value. Assigning to a field name updates the current feature's record (and creates the field on first use). If a field name is not a valid JavaScript identifier (e.g. it contains spaces or starts with a digit), use `d["field name"]` to reference it.
-- **`this`**, the feature proxy. Provides geometry-derived properties (`this.area`, `this.bbox`, etc.) and read/write access to the feature's `properties`, `geojson` and `coordinates`.
-- **`d`**, a reference to the data record (the same object as `this.properties`).
-- **`global`**, an object that persists across commands. Variables created by `-define`, by assignment in a `-calc` expression, or by writing to `global.foo = ...` inside `-each` end up here. Values set by [`-vars`](/docs/reference.html.md#-vars) and [`-defaults`](/docs/reference.html.md#-defaults) live in a separate *templating* scope (read by `{{X}}` substitution) and are **not** visible by bare name in expressions; use `-define` if you want a value reachable from both `{{X}}` and JS expressions.
-- **`console.log()`** for printing values to stderr while debugging.
-- **Built-in helpers** (see [Helper functions](#helper-functions) below).
-- **User helpers** loaded by [`-define`](/docs/reference.html.md#-define), [`-include`](/docs/reference.html.md#-include) or [`-require`](/docs/reference.html.md#-require).
-
-If a name is referenced but not present in any of the above, JavaScript treats it as `undefined`, *not* an error. This is convenient when chaining expressions across heterogeneous datasets but can mask typos &mdash; double-check field names with `mapshaper -info` if a `-filter` returns a suspiciously empty result.
-
-### Field assignment
-
-Assigning to a bare name creates or updates a data field on the current feature:
-
-```bash
-mapshaper counties.shp -each 'POP_DENSITY = POPULATION / (this.area / 1e6)' -o
-```
-
-Bare assignments like `POP_DENSITY = ...` will create the data table if the layer doesn't already have one. Assignments routed through `this.properties.X = ...` or `d.X = ...` only update an existing data table &mdash; prefer a bare assignment if you're not sure the layer has one yet.
-
-To delete a field, use the JS `delete` operator:
-
-```bash
-mapshaper states.shp -each 'delete STATE_NAME, delete GEOID' -o
-```
-
-To replace the entire record, assign to `this.properties`:
-
-```bash
-mapshaper states.shp -each 'this.properties = {FID: this.id, NAME: NAME}' -o
-```
-
-### Multiple statements
-
-Use commas to evaluate multiple sub-expressions. The value of the whole expression is the value of the last sub-expression (relevant for `-filter`, `-sort`, `-split`):
-
-```bash
-mapshaper data.csv -each 'A = parseInt(A), B = A * 2, C = A + B'
-```
-
-Inside command files, you can also break a long expression across lines with `\`:
-
-```
--each '
-  STATE_FIPS = COUNTY_FIPS.substr(0, 2),  \
-  AREA_KM2   = this.area / 1e6,           \
-  CENTROID_X = this.centroidX,            \
-  CENTROID_Y = this.centroidY
-'
-```
-
-## Feature properties (`this`)
-
-`this` is a proxy for the current feature. It gives you geometry-derived properties and a few editing affordances. The properties below are read-only unless the description says otherwise.
-
-### All layer types
-
-| Name | Description |
-| --- | --- |
-| `this.id` | 0-based numerical id of the feature |
-| `this.layer_name` | Name of the layer (or empty string) |
-| `this.properties` | Data record. Read/write &mdash; assign a new object to replace all attributes. |
-| `this.layer` | Layer proxy &mdash; see [Layer-level properties](#layer-level-properties-thislayer) |
-| `this.geojson` | GeoJSON Feature (geometry + properties). Read/write &mdash; assign a new Feature to replace this one. |
-| `this.geometry` | Just the GeoJSON geometry. Read/write. |
-
-### Polygon, polyline and point layers (with geometry)
-
-| Name | Description |
-| --- | --- |
-| `this.partCount` | 1 for single-part features, >1 for multi-part, 0 for null |
-| `this.isNull` | `true` if `partCount === 0` |
-| `this.bbox` | `[xmin, ymin, xmax, ymax]` |
-| `this.width`, `this.height` | Bounding-box width and height |
-| `this.bboxContainsPoint(x, y)` | `true` if the bbox covers the point |
-| `this.bboxIntersectsRectangle(a, b, c, d)` | `true` if the bbox overlaps the rectangle |
-| `this.bboxContainsRectangle(a, b, c, d)` | `true` if the bbox fully contains the rectangle |
-| `this.bboxContainedByRectangle(a, b, c, d)` | `true` if the bbox is fully inside the rectangle |
-
-### Polygon-only
-
-| Name | Description |
-| --- | --- |
-| `this.area` | Area in source units (square meters for unprojected lat/long, computed on a sphere) |
-| `this.planarArea` | Treats lat/long as planar &mdash; useful inside expressions that already account for projection |
-| `this.originalArea` | Area before any `-simplify` was applied |
-| `this.perimeter` | Perimeter length (meters for unprojected lat/long) |
-| `this.compactness` | Polsby-Popper compactness ratio (0&ndash;1) |
-| `this.innerPct` | Fraction of the perimeter that is shared with neighboring polygons |
-| `this.centroidX`, `this.centroidY` | Centroid coordinates (computed from the largest ring; ignores holes) |
-| `this.innerX`, `this.innerY` | An interior point useful for placing a label or symbol |
-
-### Polyline-only
-
-| Name | Description |
-| --- | --- |
-| `this.length` | Total length (meters for unprojected lat/long) |
-
-### Point-only
-
-| Name | Description |
-| --- | --- |
-| `this.coordinates` | The full nested coordinate array, or `null`. Read/write &mdash; assign `null` to drop the geometry. |
-| `this.x`, `this.y` | Coordinates of the first point of the (possibly multi-) feature. Read/write. |
-
-> **Why it matters for unprojected data:** `this.area` and `this.length` use *spherical* (not planar or ellipsoidal) geometry on lat/long datasets. Results are in square meters / meters and accurate to within ~0.5% for most use cases. If you need ellipsoidal accuracy, project first with `-proj`.
-
-## Layer-level properties (`this.layer`)
-
-`this.layer` exposes information about the layer the feature belongs to. Useful in expressions that need to know about other features:
-
-| Name | Description |
-| --- | --- |
-| `this.layer.name` | Layer name |
-| `this.layer.type` | `'polygon'`, `'polyline'`, `'point'` or `null` |
-| `this.layer.size` | Feature count |
-| `this.layer.empty` | `true` if `size === 0` |
-| `this.layer.bbox` | `[xmin, ymin, xmax, ymax]`, with extra `cx`, `cy`, `width`, `height`, `left`, `right`, `top`, `bottom` properties |
-| `this.layer.data` | The full array of data records (use sparingly inside per-feature loops) |
-| `this.layer.field_exists(name)` | Returns `true` if a field exists |
-| `this.layer.field_type(name)` | Returns `'string'`, `'number'`, `'object'` etc., or `null` |
-| `this.layer.field_includes(name, value)` | Returns `true` if any record's `name` field equals `value` |
-
-## Helper functions
-
-These are always in scope inside feature expressions:
-
-- `round(num [, decimals])` &mdash; Round to N decimal places (default 0). Faster and easier than `Math.round`.
-- `sprintf(fmt, ...)` &mdash; printf-style formatter (uses [printj](https://github.com/SheetJS/printj) syntax).
-- `format_dms(coord [, fmt])` &mdash; Format a number as a degrees/minutes/seconds string. Common formats: `'DD° MM′ SS.SSSSS″ [NS]'`, `'DdMmSs [EW]'`, `'[+-]DDDMM.MMMMM'`, `'[-]DD.DDDDD°'`.
-- `parse_dms(string [, fmt])` &mdash; Parse a DMS string back to a number.
-- `blend(c1, c2, ...)` &mdash; Mix CSS color strings together (returns a hex string).
-- `console.log(...)` &mdash; Write to stderr.
-
-JavaScript's built-in `Math`, `JSON`, `Number`, `String`, `Array`, `Date`, `Object` etc. are all available. Node-specific globals like `process`, `require` and `setTimeout` are not.
-
-## Calc expressions
-
-`-calc` and any command's `calc=` option use the same context as `-each` plus a set of *aggregate* functions that operate over the entire group of features (or the entire layer for `-calc`). Each aggregate function takes a per-feature expression and reduces it to a single value across the group.
-
-| Function | Description |
-| --- | --- |
-| `count()` | Number of records in the collection |
-| `sum(<expr>)` | Sum of the per-feature expression |
-| `mean(<expr>)`, `average(<expr>)` | Arithmetic mean |
-| `median(<expr>)` | Median value |
-| `mode(<expr>)` | Most common value (first one wins ties) |
-| `min(<expr>)`, `max(<expr>)` | Extremes |
-| `quartile1(<expr>)`, `quartile2(<expr>)`, `quartile3(<expr>)` | Quartiles |
-| `iqr(<expr>)` | Interquartile range |
-| `quantile(<expr>, <pct>)` | Arbitrary percentile (0&ndash;1) |
-| `collect(<expr>)` | Array of all values (preserves order) |
-| `collectIds()` | Array of feature ids |
-| `first(<expr>)`, `last(<expr>)` | First / last value seen |
-| `every(<expr>)`, `some(<expr>)` | Boolean reductions |
-
-Argument expressions use the same syntax as `-each`, so per-feature properties and helpers are available:
-
-```bash
-mapshaper counties.shp \
-  -calc 'TOTAL_POP = sum(POP),
-         MEAN_AREA_KM2 = sum(this.area / 1e6) / count(),
-         TOP_DENSITY = max(POP / this.area)'
-```
-
-Calc expressions can also use assignments to expose values to subsequent commands via the `global` namespace (see [Sharing state across commands](#sharing-state-across-commands) below).
-
-## Pair expressions (`A` and `B`)
-
-The `-lines where=` and `each=` options operate on path segments shared between two adjacent features. Inside these expressions:
-
-- `A` is the feature on one side of the path
-- `B` is the feature on the other side, or `null` for outer boundaries
-
-Both `A` and `B` give you the full set of feature properties (`A.properties`, `A.area`, `A.id`, etc.).
-
-```bash
-# Keep only inner boundaries between two different states
-mapshaper counties.shp \
-  -lines where='B && A.STATE != B.STATE' \
-  -o state-borders.shp
-```
-
-## Layer-level expressions (`-if`, `-define`)
-
-The `-if` family and `-define` evaluate against the *current command's target layer(s)*, not per feature. The context exposes:
-
-- `target` &mdash; the proxy for the single target layer (only set when there's exactly one target)
-- `targets` &mdash; an array-like of layer proxies, also indexable by name (`targets.states`)
-- `layer_name`, `data`, `type`, `size`, `empty`, `bbox`
-- `field_exists(name)`, `field_type(name)`, `field_includes(name, value)`
-- `layer_exists(name [, geometry_type])`
-- `file_exists(path)`
-- `global` &mdash; the shared variable namespace
-
-```bash
-mapshaper data.csv \
-  -calc 'N = count()' \
-  -if 'global.N < 5' -print 'LOW SAMPLE SIZE, STOPPING' -stop -endif
-```
-
-Each entry in `targets` exposes useful summary stats from `-info`: `layer_name`, `feature_count`, `null_shape_count`, `null_data_count`, `bbox`, `proj4`. Reading `targets[0].geojson` returns the layer as a GeoJSON FeatureCollection; assigning to it replaces the layer with the FeatureCollection you provide.
-
-## Template expressions (`-run`)
-
-`-run` accepts either a path to a [command file](/docs/reference.html.md#command-files) or a string containing one or more curly-brace template expressions. Each `{...}` is evaluated as a JS expression and substituted into the resulting command string before Mapshaper parses it.
-
-```bash
-# Project to a transverse Mercator centred on the layer
-mapshaper -i country.shp -require projection.js \
-  -run '-proj {tmerc(target.bbox)}' -o
-```
-
-Inside the curly braces you have:
-
-- `target` and `targets` (same as `-if`)
-- `io.ifile(filename, data)` &mdash; spill data to a temp file and yield its path, useful for piping computed JSON back into `-i`
-- Anything loaded by `-require` or `-define`
-
-Bare function calls outside curly braces are also evaluated directly, so `-run 'tmerc(target.bbox)'` works the same as `-run '{tmerc(target.bbox)}'` when the function name was loaded via `-require`.
-
-## Loading helpers
-
-Three commands extend the expression context with your own variables and helpers:
-
-- [`-define`](/docs/reference.html.md#-define) takes an inline JS expression and stores any assignments on the global namespace. Good for one-liners.
-- [`-include`](/docs/reference.html.md#-include) loads a `.js` file containing a single object literal; each property of that object becomes a variable in subsequent expressions.
-- [`-require`](/docs/reference.html.md#-require) loads an installed npm module or a local module file. With `alias=foo` the module is bound to that name; without an alias, the module's exported names are added directly to the context.
-
-```bash
-mapshaper data.json \
-  -require ./helpers.mjs \
-  -each 'displayname = formatName(d)' \
-  -o data.json
-```
-
-```bash
-mapshaper -define 'KM_PER_MILE = 1.609344' \
-  routes.geojson \
-  -each 'KM = MILES * global.KM_PER_MILE' \
-  -o
-```
-
-## Sharing state across commands
-
-Mapshaper has two scopes for values that persist between commands. They share a name lookup for `{{X}}` substitution but are otherwise independent.
-
-- **Expression scope (`global`)** &mdash; written by `-define`, `-include`, `-require`, `-colorizer`, and `-calc` assignments (e.g. `N = count()`) or any `global.foo = ...` inside `-each`. Values can be any JavaScript value (numbers, strings, functions, objects). Read by JS expressions as bare names, and as `global.X` everywhere. `{{X}}` substitution falls back to this scope, so `-define base = "out"` &rarr; `-o {{base}}.geojson` and `-calc 'N = count()'` &rarr; `-if '{{N}} > 100'` work as you'd expect.
-- **Templating scope** &mdash; written by [`-vars`](/docs/reference.html.md#-vars) and [`-defaults`](/docs/reference.html.md#-defaults). Values must be primitives (string / number / boolean / null) and are validated at write time. Read by `{{X}}` substitution; `{{X}}` checks the templating scope first, then falls back to the expression scope. **Not** visible by bare name in JS expressions &mdash; that's deliberate, so a string set by `-vars N=5` can't silently coerce into arithmetic.
-
-If you want one value usable in both contexts, set it once with `-define`. If you only need it in command strings, use `-vars` (or `-defaults` for command-file overridable defaults).
-
-```bash
-mapshaper counties.shp \
-  -calc 'BIG = count("POP > 1000000")' \
-  -if 'global.BIG > 0' \
-    -filter 'POP > 1000000' \
-    -o big-counties.shp \
-  -endif
-```
-
-## Common pitfalls
-
-- **Quoting.** In bash/zsh, wrap expressions in single quotes so the shell doesn't expand `!`, `$` or backticks. In Windows `cmd.exe`, use double quotes and escape inner quotes with backslashes. In PowerShell, prefer single quotes, or escape `$` with a backtick.
-- **Type coercion from CSVs.** Numeric-looking strings in CSVs are parsed as numbers by default; identifier-like strings (FIPS, ZIP) need `string-fields=` on `-i` to preserve leading zeros. See [CSV practical notes](/docs/formats/csv.html.md#practical-notes).
-- **Field name collisions.** A field called `area`, `length`, `id` etc. shadows the built-in property of the same name. Mapshaper prints a warning. Either rename the field with `-rename-fields`, or read the property via `this.area` rather than the bare name.
-- **Lat/long area surprises.** `this.area` on an unprojected polygon returns *square meters on a sphere*, not square degrees. To get square kilometres, divide by `1e6`. To get planar square degrees (e.g. for sanity checks), use `this.planarArea`.
-- **Centroids ignore holes.** `this.centroidX/Y` is the centroid of the largest ring. For a labelling point that's guaranteed inside the polygon, use `innerX`/`innerY`.
-- **`-each` doesn't return values.** Its expression is evaluated for side-effects only. Use `-filter`, `-sort` or `-calc` if you want the return value to drive behavior.
-- **Reserved names.** `this`, `d`, `_`, `global`, `console`, `target`, `targets` and the helper function names listed above are not safe to use as field names.
-- **Auto-vivification of fields.** Assigning to a name that isn't a known field creates a new field on every record. If you only want to set a field on *some* records, wrap it in a conditional and assign explicit `null` for the others, otherwise downstream readers may see `undefined` instead of a real null.
-
-## Examples
-
-```bash
-# Add two derived fields
-mapshaper counties.shp \
-  -each 'STATE_FIPS = COUNTY_FIPS.substr(0, 2),
-         AREA_KM2 = round(this.area / 1e6, 2)' \
-  -o out.shp
-
-# Drop features outside a date window
-mapshaper events.csv \
-  -filter 'new Date(DATE) >= new Date("2020-01-01")' \
-  -o recent.csv
-
-# Sort polygons largest-first
-mapshaper countries.geojson \
-  -sort '-this.area' \
-  -o sorted.geojson
-
-# Look up one feature
-mapshaper states.geojson -inspect 'NAME == "Delaware"'
-
-# Aggregate stats during a dissolve
-mapshaper counties.shp \
-  -dissolve STATE calc='N = count(),
-                        POP = sum(POP),
-                        MEDIAN_INC = median(MEDIAN_INC)' \
-  -o states.shp
-
-# Conditional pipeline based on a calc result
-mapshaper data.csv \
-  -calc 'N = count()' \
-  -if 'global.N == 0' -stop -endif \
-  -o data.csv
-
-# Filter shared boundaries
-mapshaper counties.shp \
-  -lines where='B && A.STATE != B.STATE' \
-  -o state-borders.shp
-
-# Per-feature styling: circle radius from POP, fill from an expression
-mapshaper cities.geojson \
-  -style r='Math.sqrt(POP) / 40' \
-         fill='POP > 1e6 ? "#c33" : "#39c"' \
-         opacity=0.7 \
-  -o cities.svg
-
-# Project to a layer-specific CRS
-mapshaper -i country.shp -require ./projection.js \
-  -run '-proj {tmerc(target.bbox)}' -o
-```
-
-## See also
-
-- [`-each`](/docs/reference.html.md#-each) &mdash; the canonical feature-expression command
-- [`-filter`](/docs/reference.html.md#-filter)
-- [`-calc`](/docs/reference.html.md#-calc)
-- [`-define`](/docs/reference.html.md#-define), [`-include`](/docs/reference.html.md#-include), [`-require`](/docs/reference.html.md#-require)
-- [`-run`](/docs/reference.html.md#-run)
-- [Basics](/docs/examples/basics.html.md) &mdash; recipes that put expressions to work
-
----
-
-<!-- https://mapshaper.org/docs/guides/projections.html -->
-
-# Projections
-
-Mapshaper's [`-proj`](/docs/reference.html.md#-proj) command reprojects a dataset from one coordinate reference system (CRS) to another, using a JavaScript port of the [PROJ](https://proj.org/) coordinate transformation library.
-
-**Examples**
-
-```bash
-# Project a Shapefile to UTM zone 11N using a PROJ string
-mapshaper nevada.shp -proj +proj=utm +zone=11 -o
-
-# Convert a projected Shapefile to WGS84 — the following are equivalent:
-mapshaper nyc.shp -proj EPSG:4326 -o
-mapshaper nyc.shp -proj wgs84 -o
-mapshaper nyc.shp -proj +proj=longlat +datum=WGS84 -o
-
-# Composite projection for U.S. maps with Alaska, Hawaii, and Puerto Rico insets
-mapshaper us-states.shp -proj albersusa +PR -o
-```
-
-## Forms of CRS notation
-
-`-proj` accepts a CRS in any of three forms.
-
-**PROJ strings** are sequences of `+key=value` parameters. They are the lowest-level form and expose the full set of options for each projection. Parameters that have sensible defaults (datum, units, false easting/northing) can usually be omitted.
-
-```bash
-mapshaper data.shp -proj +proj=lcc +lat_1=33 +lat_2=45 +lat_0=39 +lon_0=-96 -o
-```
-
-**EPSG codes** are numeric identifiers from the [EPSG registry](https://epsg.io/). Thousands of national and regional coordinate systems have EPSG codes, making them a compact and unambiguous way to specify a CRS.
-
-```bash
-mapshaper data.shp -proj EPSG:3857 -o   # Web Mercator
-mapshaper data.shp -proj EPSG:32611 -o  # UTM zone 11N (WGS84)
-```
-
-**Aliases** are short names for common projections. Run `mapshaper -projections` to print the full list. The built-in aliases are:
-
-| Alias | Equivalent PROJ string |
-|---|---|
-| `wgs84` | `+proj=longlat +datum=WGS84` |
-| `webmercator` | `+proj=merc +a=6378137 +b=6378137` |
-| `robinson` | `+proj=robin +datum=WGS84` |
-| `albersusa` | [Composite U.S. projection](#albersusa) (see below) |
-
-You can also use a bare PROJ projection name (without `+proj=`) as shorthand when no extra parameters are required:
-
-```bash
-mapshaper world.shp -proj robin -o
-```
-
-## Auto-fitted parameters
-
-For some conic and cylindrical projections, you can supply just the projection name and Mapshaper will calculate suitable parameters from the extent of the data. This is useful when you want a locally appropriate projection without looking up specific values.
-
-For **Lambert Conformal Conic** (`lcc`) and **Albers Equal Area Conic** (`aea`), Mapshaper calculates the central meridian (`lon_0`) and two standard parallels (`lat_1`, `lat_2`) using the one-sixth rule applied to the data's bounding box.
-
-For **Transverse Mercator** (`tmerc`, `etmerc`), it calculates the central meridian and latitude of origin (`lon_0`, `lat_0`) from the center of the bounding box.
-
-```bash
-# Mapshaper fills in lon_0, lat_1, lat_2 based on the data extent
-mapshaper region.geojson -proj lcc -o region_lcc.geojson
-
-# Equivalent — Mapshaper fills in lon_0 and lat_0
-mapshaper region.geojson -proj tmerc -o region_tmerc.geojson
-```
-
-When Mapshaper auto-fits parameters, it prints the expanded PROJ string so you can see exactly what was applied — for example: `Converted "lcc" to "+proj=lcc +lon_0=-95.5 +lat_1=30.17 +lat_2=44.83"`. You can copy that string and use it explicitly if you need reproducible output.
-
-## albersusa
-
-`albersusa` is a Mapshaper-specific composite projection for maps of the United States. It is not part of the PROJ library. It applies Albers Equal Area Conic to the contiguous 48 states, then tiles Alaska (scaled down) and Hawaii as insets in the lower-left corner of the map.
-
-```bash
-mapshaper us-states.shp -proj albersusa -o
-```
-
-Two optional flags add insets for outlying territories:
-
-- `+PR` — Puerto Rico
-- `+VI` — U.S. Virgin Islands (placed alongside Puerto Rico)
-
-```bash
-mapshaper us-states.shp -proj albersusa +PR +VI -o
-```
-
-The position, scale, rotation, and other properties of each inset can be overridden with named parameters if the defaults do not suit your map. See the [`-proj` reference](/docs/reference.html.md#-proj) for the full option syntax.
-
-## Finding CRS definitions
-
-Several websites provide PROJ strings and EPSG codes for coordinate systems worldwide:
-
-- **[EPSG.io](https://epsg.io/)** — search by place name, CRS name, or EPSG code. Each entry shows the PROJ string and WKT definition and lets you preview the projection on a map.
-- **[SpatialReference.org](https://spatialreference.org/)** — similar database built directly from the PROJ library. Good for browsing the full set of supported systems.
-- **[PROJ documentation](https://proj.org/operations/projections/)** — reference for every projection in PROJ, including all supported parameters. Mapshaper's JavaScript port supports most but not all of them; run `mapshaper -projections` to see the exact list.
-
-## Coordinate system quirks and limitations
-
-- GeoJSON and TopoJSON files are assumed to use WGS84 when their bounding boxes fall within the normal range for decimal degree coordinates.
-- Mapshaper does not support coordinate transformations that require grid-shift files (for example, NAD27 → WGS84). If a transformation silently fails, this is the likely cause.
-- Projections that can only represent part of the globe — including orthographic (`ortho`), near-side perspective (`nsper`, `geos`), gnomonic (`gnom`), stereographic (`stere`), and Lambert Azimuthal Equal-Area (`laea`) — automatically clip input data to the projection's valid extent before projecting. This prevents distorted or invalid geometry from coordinates outside the visible area.
-- For projections that introduce significant curvature along straight lines, add the `densify` option to interpolate extra vertices along long segments:
-
-  ```bash
-  mapshaper data.shp -proj +proj=ortho +lat_0=45 +lon_0=-100 densify -o
-  ```
-
-- When `-proj` targets a layer, all topologically related layers (those sharing the same geometry) are also reprojected. To reproject all layers, use `target=*`.
-- The `init=` option is available for files whose source CRS is unknown and cannot be inferred from a `.prj` file. Shapefiles normally carry a `.prj` sidecar; GeoJSON and TopoJSON are assumed to be WGS84 when their coordinates fall within the standard lat/long range.
-
-## The -proj command
-
-See the [`-proj` reference](/docs/reference.html.md#-proj) for the full list of options.
-
----
-
-<!-- https://mapshaper.org/docs/guides/topology.html -->
-
-# Topology and cleaning
-
-Shapefile and GeoJSON are non-topological formats &mdash; they don't record the spatial relationships between adjacent polygons or intersecting polylines. Each polygon is just a list of coordinates; whether two polygons share an edge has to be detected.
-
-Mapshaper detects topology on import by identifying coordinates that are exactly shared between features. This is what makes operations like simplification, dissolving and clipping work correctly: when two polygons share an edge, the shared path (or "arc") is stored once and edited once.
-
-But coordinates that "should be" identical often aren't. Source datasets routinely contain misalignments (tiny gaps or overlaps between adjacent polygons) that defeat exact-match topology detection. The result is that what looks like a clean boundary turns into duplicated, slightly-offset arcs &mdash; and simplification, dissolving and clipping all start to misbehave.
-
-## Snapping
-
-The simplest fix is to ask Mapshaper to snap nearby vertices together at import time.
-
-In the **command line**, pass the `snap` flag to `-i`:
-
-```bash
-mapshaper countries.shp snap -dissolve CONTINENT -o continents.shp
-```
-
-In the **web app**, tick "snap vertices" in the import dialog (open the import options with the **with advanced options** checkbox).
-
-By default, snapping uses an automatic threshold of about 0.0025× the average segment length, which is designed to catch misalignments caused by floating-point rounding. To set an explicit snapping distance, use `snap-interval=`:
-
-```bash
-mapshaper countries.shp snap-interval=0.0001 -o cleaned.shp
-```
-
-## Cleaning
-
-Snapping handles slightly offset pairs of vertices, but doesn't help much when adjacent polygons have small overlapping regions or gaps along their shared boundaries. The [`-clean`](/docs/reference.html.md#-clean) command repairs these by recomputing the polygon mosaic and snapping geometry that's nearly identical:
-
-```bash
-mapshaper countries.shp -clean -o cleaned.shp
-```
-
-`-clean` accepts a `gap-fill-area=` option to control how aggressively gaps are filled, and a `sliver-control=` setting for handling sliver polygons. [`-dissolve`](/docs/reference.html.md#-dissolve) runs an equivalent repair by default, so explicitly running `-clean` is mainly useful when you want clean output without dissolving anything.
-
-In the web app, `-clean` runs from the **Console** the same way as on the CLI &mdash; the leading `-` is optional, e.g. just `clean gap-fill-area=100`.
-
-## Dissolving with topology repair
-
-[`-dissolve`](/docs/reference.html.md#-dissolve) repairs topology automatically. To skip the repair pass (faster, but only safe when you trust the input topology), pass `no-repair` &mdash; Mapshaper will then warn if it detects segment intersections in the input.
-
-```bash
-mapshaper counties.shp -dissolve STATE_FIPS -o states.shp
-```
-
-## Detecting line intersections
-
-The web app can highlight self-intersections in your data: open the **Display** panel and tick "detect line intersections". Intersections often indicate either a topology error in the source data or self-intersections introduced by simplification &mdash; the **Repair** button at the top-left of the map attempts to fix the latter.
-
-On the command line, [`-clean`](/docs/reference.html.md#-clean) and [`-dissolve`](/docs/reference.html.md#-dissolve) both detect and fix intersections.
-
-## Notes on common sources of topology errors
-
-A few patterns to watch out for:
-
-- **`.shp` files exported from older GIS tools.** Some pipelines round coordinates inconsistently between adjacent features, producing systematic misalignments. Importing with `snap` is usually enough.
-- **Older versions of ArcGIS's dissolve tool** have been observed to produce topology errors when dissolving a Shapefile that hasn't first been added to a Geodatabase. If you're starting from such output, run it through `mapshaper input.shp -clean -o cleaned.shp` to repair before further processing.
-
----
-
-<!-- https://mapshaper.org/docs/guides/combining-layers.html -->
-
-# Tutorial: combining two layers in the web UI
-
-> Originally contributed by Amanda Hickman to the project wiki.
-
-This walkthrough shows how to combine and prune two boundary layers to produce a single GeoJSON file you can use as a custom basemap (for example, in [Datawrapper](https://www.datawrapper.de/)).
-
-The example builds a basemap of the San Francisco Bay Area, with both county boundaries and the cities ("places") inside them.
-
-The walkthrough uses the web app at [mapshaper.org](/), driving the workflow from the **Console**. The same commands work on the CLI &mdash; chain them together with leading `-` prefixes (so `clip bayarea_county` becomes `-clip bayarea_county`) and connect them with backslash line continuations.
-
-## The starting data
-
-We'll use two source files:
-
-- A county boundary file from the California Open Data Portal &mdash; or, in this case, a [version clipped to the shoreline](https://geodata.lib.berkeley.edu/catalog/ark28722-s7hs4j) from UC Berkeley's Geo Data Commons. The shoreline-clipped version reads more naturally on a map than the legal-boundary version, which extends into the bay.
-- A statewide [places boundary file](https://geodata.lib.berkeley.edu/catalog/ark28722-s7bp4z) for city boundaries.
-
-The legal county boundaries from the Census TIGER files extend straight across the water &mdash; San Francisco even reaches out to include the Farallon Islands:
-
-![Bay Area counties from the Census TIGER file, with boundaries cutting across the bay and extending offshore](/docs/images/tiger-counties.png)
-
-The Berkeley library's version is clipped to the shoreline, so the bay shows as empty space between the counties:
-
-![The same Bay Area counties, with each polygon clipped to the coastline so the bay is visible between them](/docs/images/cal-counties.png)
-
-Download both as `.zip` files.
-
-## Open them in Mapshaper
-
-Drag the two `.zip` files onto [mapshaper.org](/), or run the web app locally with `mapshaper-gui`. You'll end up with two layers loaded into the session.
-
-## Set the projection
-
-Datawrapper expects WGS84 coordinates. Open the **Console** (top-right of the header) and run, with each layer selected:
-
-```
-proj wgs84
-```
-
-You'll need to run this once per layer &mdash; switch which layer is selected in the layer panel between runs.
-
-→ See the [`-proj` reference](/docs/reference.html.md#-proj).
-
-## Clip the places layer to the Bay Area
-
-The places layer covers the whole state. We only want places inside the Bay Area counties. With the places layer selected:
-
-```
-clip bayarea_county
-```
-
-→ See the [`-clip` reference](/docs/reference.html.md#-clip).
-
-Alternatively, if the places layer has a `COUNTY` attribute, a filter expression works too:
-
-```
-filter '["Marin", "Contra Costa", "Alameda",
-         "San Francisco", "Santa Clara", "San Mateo"].includes(COUNTY)'
-```
-
-→ See the [`-filter` reference](/docs/reference.html.md#-filter).
-
-## Merge the layers
-
-The two layers can now be combined into a single layer with [`-merge-layers`](/docs/reference.html.md#-merge-layers):
-
-```
-merge-layers target=bayarea_county,california_place_clipped force
-```
-
-The `force` flag is needed because the two layers have different attribute schemas; without it, Mapshaper refuses to merge layers whose fields don't match.
-
-## Export
-
-Open the **Export** panel (top-right of the header), pick **GeoJSON** as the format, and save the merged layer. You can now upload that file to Datawrapper (or any other tool that accepts GeoJSON) as a custom basemap.
-
-## What you've learned
-
-- How to load multiple data files into one Mapshaper session.
-- How to apply a projection inside the web UI's console.
-- How to clip one layer by another.
-- How to merge two layers into a single layer for export.
-
-For more on layers and how Mapshaper organizes multi-layer datasets, see [The command-line tool](/docs/essentials/command-line.html.md#working-with-layers).
-
----
-
-<!-- https://mapshaper.org/docs/guides/programmatic.html -->
-
-# Using Mapshaper from Node.js
-
-This page is for developers who want to use Mapshaper's geoprocessing functions inside their own programs &mdash; either by shelling out to the CLI from a build tool, or by calling Mapshaper's API from Node.js code directly.
-
-## Calling the CLI from a build tool
-
-The simplest way to script Mapshaper is to invoke the `mapshaper` (or `mapshaper-xl`) command from `make` or a shell script.
-
-Example `Makefile` target:
-
-```make
-europe.topojson: shp/world_countries.shp
-	mapshaper $< \
-	  -filter "CONTINENT == 'Europe'" \
-	  -simplify interval=100m keep-shapes \
-	  -o $@
-```
-
-An alternative to embedding a long series of Mapshaper commands on the command line is to put them in a `.txt` file and pass the file to `mapshaper`. See [command files](/docs/reference.html.md#command-files) and [variable interpolation](/docs/reference.html.md#variable-interpolation) in the reference.
-
-## The Node.js API
-
-Mapshaper exposes three top-level functions for running editing commands programmatically. All three accept the same command-line string format as the `mapshaper` CLI.
-
-### `runCommands(commands[, input][, callback])`
-
-Runs a command line against files on disk (or in-memory). The `-o` command(s) write their output to disk.
-
-- `commands` &mdash; a command-line string.
-- `input` (optional) &mdash; an object whose keys are filenames and whose values are file contents. Files referenced by `-i` are looked up here first, then on the filesystem.
-- `callback` (optional) &mdash; a Node-style `function(err)`. Without a callback, `runCommands` returns a Promise.
-
-```javascript
-import mapshaper from 'mapshaper';
-
-await mapshaper.runCommands('-i shapefiles/*.shp -o geojson/ format=geojson');
-```
-
-### `applyCommands(commands[, input][, callback])`
-
-Same signature as `runCommands`, but instead of writing files to disk, the contents produced by `-o` are returned to the caller as a `{ filename: Buffer }` object. Useful for processing data without touching the filesystem.
-
-```javascript
-import mapshaper from 'mapshaper';
-
-const input = { 'input.csv': 'lat,lng,value\n40.3,-72.3,1000' };
-const cmd   = '-i input.csv -points x=lng y=lat -o output.geojson';
-
-const output = await mapshaper.applyCommands(cmd, input);
-// output['output.geojson'] is a Buffer containing GeoJSON
-```
-
-### `runCommandsXL(commands[, options][, callback])`
-
-Like `runCommands`, but the work runs in a child Node process configured with a larger maximum heap (8 GB by default). Equivalent to running `mapshaper-xl` from the command line. Override the heap size with the `xl` option:
-
-```javascript
-await mapshaper.runCommandsXL(commands, { xl: '16gb' });
-```
-
-This function reads input only from the filesystem &mdash; there's no `input` argument as on `runCommands`/`applyCommands`.
-
-## Working with Shapefiles in `applyCommands`
-
-Shapefiles are really a set of component files. To import one through `applyCommands`, pass the contents of all the parts you care about:
-
-- `.shp` &mdash; geometry (Buffer or ArrayBuffer)
-- `.dbf` &mdash; attribute table (Buffer or ArrayBuffer)
-- `.prj` &mdash; coordinate system (string)
-
-Without `.dbf` you'll get geometry but no attributes; without `.prj`, projection-dependent commands won't have a coordinate system to work from.
-
-```javascript
-const input = {
-  'world.shp': shpBuffer,
-  'world.dbf': dbfBuffer,
-  'world.prj': prjString
-};
-const output = await mapshaper.applyCommands(
-  '-i world.shp -simplify 10% -o world.geojson', input
-);
-```
-
-## Versioning
-
-The Node API is stable across minor Mapshaper releases, but new options and commands appear regularly. The full set of accepted command-line options is the same as the CLI's, so the [command reference](/docs/reference.html.md) is the authoritative list of what you can put into the `commands` string.
-
----
-
-<!-- https://mapshaper.org/docs/formats/overview.html -->
-
-# File formats
-
-This section explains how each supported file format is handled, what format-specific options are available, and what to watch out for.
-
-## Comparison
-
-<div class="formats-table-wrap">
-
-| Format | Extension | Read | Write | Geometry | Attributes | Topology | Multi-layer |
-|---|---|:---:|:---:|---|---|:---:|:---:|
-| [Shapefile](/docs/formats/shapefile.html.md) | `.shp` | &check; | &check; | vector | DBF (10-char names) | &mdash; | &mdash; |
-| [GeoJSON](/docs/formats/geojson.html.md) | `.json` `.geojson` | &check; | &check; | vector | yes | &mdash; | &mdash; |
-| [TopoJSON](/docs/formats/topojson.html.md) | `.json` `.topojson` | &check; | &check; | vector | yes | **&check;** | &check; |
-| [GeoPackage](/docs/formats/geopackage.html.md) | `.gpkg` | &check; | &check; | vector | yes | &mdash; | &check; |
-| [FlatGeobuf](/docs/formats/flatgeobuf.html.md) | `.fgb` | &check; | &check; | vector | yes | &mdash; | &mdash; |
-| [KML / KMZ](/docs/formats/kml.html.md) | `.kml` `.kmz` | &check; | &check; | vector | limited | &mdash; | &check; |
-| [CSV / TSV](/docs/formats/csv.html.md) | `.csv` `.tsv` | &check; | &check; | points (X/Y) | yes | &mdash; | &mdash; |
-| [DBF](/docs/formats/dbf.html.md) | `.dbf` | &check; | &check; | none | yes | &mdash; | &mdash; |
-| [JSON records](/docs/formats/json.html.md) | `.json` | &check; | &check; | none | yes | &mdash; | &mdash; |
-| [SVG](/docs/formats/svg.html.md) | `.svg` | &check; | &check; | vector | as `data-*` | &mdash; | &check; |
-| [Mapshaper snapshot](/docs/formats/snapshot.html.md) | `.msx` | &check; | &check; | vector | yes | **&check;** | &check; |
-
-</div>
-
-A few things worth knowing across all formats:
-
-- **Auto-detection by extension.** You usually don't need to tell Mapshaper what format a file is &mdash; it picks the right reader from the file extension. Use `format=` on `-i` or `-o` to override.
-- **TopoJSON is the only interchange format that preserves topology** in the file itself. Topology-aware operations like [`-dissolve`](/docs/reference.html.md#-dissolve), [`-clean`](/docs/reference.html.md#-clean) and [`-simplify`](/docs/reference.html.md#-simplify) work correctly regardless of the input format, but only TopoJSON keeps shared boundaries between adjacent polygons from being duplicated on disk. (Mapshaper's own [`.msx`](/docs/formats/snapshot.html.md) snapshots also preserve topology, but they're not readable by other tools.)
-- **Encoding.** The `encoding=` option on `-i` and `-o` applies to Shapefile, DBF and CSV/TSV i/o (UTF-8 is the default) &mdash; the other formats are UTF-8-only.
-
----
-
-<!-- https://mapshaper.org/docs/formats/shapefile.html -->
-
-# Shapefile
-
-Shapefile is ESRI's long-standing vector format and remains widely used as an exchange format in desktop GIS workflows. Rather than a single file, a Shapefile is a collection of files — at minimum .shp, .shx, and .dbf, plus commonly .prj (coordinate reference system) and .cpg (character encoding). It has well-known limitations, including a 2 GB size cap per component file, attribute field names limited to 10 characters, attribute values limited to 254 characters, no support for mixed geometry types, and unreliable character encoding declaration. Newer formats like [GeoPackage](/docs/formats/geopackage.html.md) and [FlatGeobuf](/docs/formats/flatgeobuf.html.md) solve most of the limitations.
-
-**File extensions:** `.shp` (geometry), `.dbf` (attributes), `.shx` (index), `.prj` (projection), `.cpg` (encoding hint)
-&middot; **Read:** &check; &middot; **Write:** &check; &middot; **Multi-layer:** no
-
-### CLI examples
-
-```bash
-mapshaper provinces.shp -info
-mapshaper provinces.shp -simplify 20% -o provinces.geojson
-mapshaper input.geojson -o provinces.shp
-```
-
-### Format-specific input options
-
-- `encoding=` &mdash; encoding used by the `.dbf` text fields. If omitted, Mapshaper auto-detects, falling back to the value declared in a `.cpg` file when present. Common values: `latin1`, `utf8`, `gb18030`. Run `mapshaper -encodings` for the full list.
-
-### Format-specific output options
-
-- `encoding=` &mdash; text encoding for the `.dbf`. Defaults to UTF-8 (with a matching `.cpg` sidecar).
-- `field-order=ascending` &mdash; sort attribute fields alphabetically (case-insensitive).
-
-### Practical notes
-
-- A Shapefile dataset is a bundle of files sharing a base name. The Mapshaper CLI inputs the `.shp` and picks up any sibling `.dbf`, `.shx`, `.prj` and `.cpg` files automatically. In the [web app](/docs/essentials/web-app.html.md) you select or drag-drop them together &mdash; see [In the web app](#in-the-web-app) below.
-- Field names longer than 10 characters are silently truncated on write, which can produce duplicates. Mapshaper disambiguates by appending digits, or you can rename fields beforehand with [`-rename-fields`](/docs/reference.html.md#-rename-fields).
-- Field values longer than 254 characters are truncated on write.
-- Mapshaper does not fully support M (measured) and Z (3D) Shapefiles &mdash; M and Z values are dropped on import.
-- When exporting, the Mapshaper CLI produces separate companion files (`.shp`, `.shx`, `.dbf`, `.prj`). In the web app, the component files get bundled in a `.zip` file.
-- If the `.prj` file is missing, Mapshaper reads the geometry without coordinate-reference information. Coordinates in the lat-long range are assumed to be WGS-84. You can use the `-proj` command to assign a CRS (e.g. `-proj init=...`).
-- A standalone `.dbf` can be imported on its own as a tabular layer &mdash; see the [DBF page](/docs/formats/dbf.html.md).
-
-### In the web app
-
-Browsers can't read files from the filesystem the CLI can, so you have to supply all the parts of a Shapefile together. Two options are:
-
-1. **Select all the components together.** Click **Add files** and shift- or cmd-click the `.shp`, `.dbf`, `.prj` (and `.shx`/`.cpg` if present) in one go, or drag the whole selection onto the import area.
-2. **Drop a `.zip` containing the bundle.** Shapefiles are very commonly distributed this way.
-
-If the import warns about an unknown text encoding, re-import with the **with advanced options** checkbox ticked and pass `encoding=` (e.g. `encoding=win1252`, `encoding=gb18030`). The same `encoding=` values that work on the CLI work here.
-
-### Reading a Shapefile with missing sidecars
-
-Mapshaper will read a `.shp` whose `.dbf` and/or `.shx` companion files are missing &mdash; useful when you're handed an incomplete bundle, or when you only care about geometry:
-
-- **Missing `.dbf`**: the geometry is imported with no attribute table.
-- **Missing `.shx`**: Mapshaper recovers feature offsets by reading the `.shp` directly. This works for normal Shapefiles with densely-packed records; it only fails on the rare Shapefiles that contain out-of-order records, where the `.shx` is needed to locate each feature.
-
-### `.dbf` text encoding
-
-The .dbf format is a legacy binary format dating to dBASE III in the early 1980s, predating Unicode. Character encoding is not declared within the file itself, which can cause encoding errors when working with Shapefiles containing non-ASCII characters. In practice, most Shapefiles now come with a `.cpg` file or use UTF-8, which is almost always auto-detected correctly.
-
-Mapshaper handles encoding in the following order:
-
-1. If `encoding=` is set on `-i`, that wins.
-2. If a `.cpg` sidecar file is present, Mapshaper uses the encoding it names.
-3. Otherwise Mapshaper tries to auto-detect the encoding from the `.dbf` contents.
-
-Auto-detection covers most public datasets, but it can guess wrong on sparsely-populated columns or unusual codepages. If you see mojibake (`é` instead of `é`, `?` characters where accented letters should be), set `encoding=` explicitly:
-
-```bash
-mapshaper -i provinces.shp encoding=utf8 -info
-mapshaper -i historical.shp encoding=win1252 -o cleaned.geojson
-mapshaper -i china.shp encoding=gb18030 -o cleaned.geojson
-```
-
-When writing, Mapshaper emits UTF-8 plus a `.cpg` sidecar by default so other tools can decode correctly. Override with `encoding=` on `-o` if a downstream consumer requires a specific codepage.
-
-## External resources
-
-- [Shapefile file extensions (ArcMap docs)](https://desktop.arcgis.com/en/arcmap/latest/manage-data/shapefiles/shapefile-file-extensions.htm) &mdash; ESRI's own practical reference describing what each `.shp`/`.shx`/`.dbf`/`.prj`/`.cpg`/`.sbn` etc. file actually contains. Useful when you encounter unfamiliar sidecar files.
-- [Switch from Shapefile](https://switchfromshapefile.org/) &mdash; a long-running campaign cataloguing the format's well-known limitations and pointing to alternatives.
-- [ESRI Shapefile Technical Description (PDF)](https://www.esri.com/content/dam/esrisites/sitecore-archive/Files/Pdfs/library/whitepapers/pdfs/shapefile.pdf) &mdash; the original 1998 white paper that defines the format. Dry but authoritative.
-
-## See also
-
-- [DBF format](/docs/formats/dbf.html.md)
-
----
-
-<!-- https://mapshaper.org/docs/formats/geojson.html -->
-
-# GeoJSON
-
-GeoJSON is a simple, human-readable format for geospatial vector data. It is used by many web mapping APIs, although formats like TopoJSON, FlatGeobuf, GeoParquet, and vector tiles have replaced it for specific use cases such as large-file efficiency, cloud-optimized access, and tiled rendering.
-
-**File extensions:** `.json`, `.geojson` &middot; **Read:** &check; &middot; **Write:** &check; &middot; **Multi-layer:** one layer per file (combinable)
-
-### CLI examples
-
-```bash
-mapshaper input.shp -o provinces.geojson
-mapshaper input.shp -o precision=0.001 prettify provinces.geojson
-```
-
-### Format-specific input options
-
-- `id-field=` &mdash; import the value of each Feature's top-level `id` property into a data field of the given name.
-- `json-path=` &mdash; for files where the GeoJSON object is nested inside a larger JSON document, e.g. `json-path=data/regions`.
-
-### Format-specific output options
-
-- `precision=` &mdash; round coordinates to a fixed precision. This is a simple way to reduce file size.
-- `prettify` &mdash; pretty-print the JSON with line breaks and indentation.
-- `id-field=` &mdash; promote one or more attribute fields to the GeoJSON `id` property (comma-separated; first matching field per layer is used).
-- `bbox` &mdash; add a `bbox` array to the top-level FeatureCollection.
-- `extension=` &mdash; override the default `.json` extension (e.g. `extension=geojson`).
-- `combine-layers` &mdash; merge multiple layers into a single GeoJSON output file (geometries are kept separate as Features, attribute schemas are unioned).
-- `geojson-type=` &mdash; output a `Feature`, `FeatureCollection` or bare `GeometryCollection` instead of the default FeatureCollection.
-- `no-null-props` &mdash; emit `"properties": {}` instead of `"properties": null` for Features without attributes.
-- `hoist=` &mdash; promote one or more properties out of the `properties` object onto the Feature itself. Useful for non-standard consumers like [tippecanoe](https://github.com/felt/tippecanoe).
-- `gj2008` &mdash; emit pre-RFC-7946 GeoJSON (clockwise outer rings). This option produces files that can be rendered with `d3`.
-- `ndjson` &mdash; write one Feature per line as newline-delimited JSON (works with the [`json` records](/docs/formats/json.html.md) family of options as well).
-- `id-prefix=` &mdash; prefix layer/feature ids when exporting multiple layers.
-
-### Practical notes
-
-- The GeoJSON spec states that GeoJSON uses WGS-84 coordinates (the lat-long coordinate system used by GPS), but Mapshaper will also export GeoJSON files with projected coordinates.
-- Coordinates are emitted at full precision &mdash; consider `precision=` to reduce file size. `precision=0.0001` equates to ~11 m at the equator, ~8 m in New York City, and ~6 m in Reykjavík, Iceland.
-- Polygon ring winding follows RFC 7946 (CCW outer, CW holes); the `gj2008` option outputs the CW outer rings expected by `d3`.
-- Output is minified by default; pass `prettify` for human-readable JSON.
-- If you are loading the data into a web map and you want the smallest possible file size, consider [TopoJSON](/docs/formats/topojson.html.md) as an alternative to GeoJSON. For datasets with shared boundaries, file sizes are often a fraction of the equivalent GeoJSON size.
-- `precision=` rounding can introduce sliver overlaps at boundaries. Pair it with `fix-geometry` if downstream tools are strict.
-
-### Reading very large GeoJSON files
-
-Mapshaper's custom GeoJSON parser is not limited by the ~500 MB ceiling affecting tools that use `JSON.parse()`.
-
-In the [web app](/docs/essentials/web-app.html.md), the theoretical upper bound is around 2 GB per file in most browsers, though in practice the browser may run out of memory and crash well before that. If a GeoJSON is too big to open in the browser, use the CLI instead.
-
-`mapshaper-xl` can handle multi-gigabyte files. It allocates 8 GB of memory by default, but you can assign more.
-
-```bash
-mapshaper-xl huge.geojson -info
-mapshaper-xl 32gb huge.geojson -simplify 5% -o huge.topojson
-```
-
-## External resources
-
-- [RFC 7946: The GeoJSON Format](https://datatracker.ietf.org/doc/html/rfc7946) &mdash; the IETF specification Mapshaper writes by default.
-- [More than you ever wanted to know about GeoJSON](https://macwright.com/2015/03/23/geojson-second-bite.html) &mdash; Tom MacWright's detailed practical introduction.
-- [geojson.org](https://geojson.org/) &mdash; spec home with links to tooling and validators.
-
----
-
-<!-- https://mapshaper.org/docs/formats/topojson.html -->
-
-# TopoJSON
-
-TopoJSON is a JSON-based format that encodes geographic topology: shared boundaries between adjacent features are stored once instead of duplicated. For datasets with shared boundaries (administrative divisions, watersheds, anything with adjacency) the resulting file is often 2&ndash;5&times; smaller than the equivalent GeoJSON. A single TopoJSON file can hold multiple layers, making it a natural choice for shipping a complete map (e.g. countries + states + cities) in one HTTP request.
-
-**File extensions:** `.json`, `.topojson` &middot; **Read:** &check; &middot; **Write:** &check; &middot; **Multi-layer:** &check;
-
-### CLI examples
-
-```bash
-mapshaper world.topojson -info
-mapshaper world.topojson -o format=geojson world.geojson
-mapshaper provinces.shp -o provinces.topojson
-mapshaper provinces.shp -o quantization=10000 provinces.topojson
-mapshaper countries.shp states.shp -o singles output/
-```
-
-### Format-specific input options
-
-- `id-field=` &mdash; import the `id` property of each Feature into a data field of the given name.
-- `json-path=` &mdash; for files where the TopoJSON object is nested inside a larger document.
-
-### Format-specific output options
-
-- `quantization=` &mdash; number of distinct integer values that x and y coordinates are quantized to, *per axis*. For example, `quantization=10000` produces a 10000&times;10000 integer grid regardless of the bounding box's aspect ratio (x and y use independent scales). Lower values produce smaller files at the cost of precision. Equivalent to the [`topoquantize`](https://github.com/topojson/topojson-server/blob/master/README.md#topoquantize) CLI's parameter.
-- `topojson-precision=` &mdash; alternative way to set quantization, expressed as a fraction of the average segment length.
-- `no-quantization` &mdash; emit full-precision arc coordinates.
-- `singles` &mdash; write each layer as a separate file, named after the layer.
-- `prettify` &mdash; pretty-print the JSON.
-- `id-field=` &mdash; promote an attribute field to the `id` property of each output object.
-- `bbox` &mdash; add a top-level `bbox` array.
-- `extension=` &mdash; override the default `.json` extension (e.g. `extension=topojson`).
-- `width=` / `height=` / `pixels=` / `margin=` &mdash; switch the output coordinate system from geographic units to pixels, flipping the Y axis. Useful when generating a TopoJSON intended for direct use as SVG path data.
-
-### Practical notes
-
-- Quantization is on by default with a value calibrated to the geometry (about 0.02 of the average segment length), which keeps files compact while staying visually lossless. Use the `quantization=` option to override the default.
-- Use `no-quantization` to save coordinates losslessly.
-- TopoJSON does not store coordinate system metadata. If your data is in a projected coordinate system, you'll need to manage the projection separately.
-- Output is minified by default; pass `prettify` for human-readable JSON.
-- Aggressive quantization can introduce visible misalignments and sliver overlaps. If this happens, raise the `quantization=` value.
-
-## External resources
-
-- [TopoJSON specification](https://github.com/topojson/topojson-specification) &mdash; the format spec on GitHub.
-- [How To Infer Topology](https://bost.ocks.org/mike/topology/) &mdash; Mike Bostock's original explainer of the algorithm and data model behind TopoJSON. Required reading if you want to understand what makes the format compact.
-
-## See also
-
-- [Quantized TopoJSON](/docs/examples/basics.html.md#quantized-topojson)
-
----
-
-<!-- https://mapshaper.org/docs/formats/geopackage.html -->
-
-# GeoPackage
-
-GeoPackage is the OGC's modern, open replacement for Shapefile &mdash; a single SQLite database file that holds one or many vector layers along with their CRS metadata. It solves most of Shapefile's problems (long field names, UTF-8 encoding, no companion files, multiple layers per file, no 2 GB cap) and is well-supported across QGIS, ArcGIS and `ogr2ogr`.
-
-**File extension:** `.gpkg` &middot; **Read:** &check; &middot; **Write:** &check; &middot; **Multi-layer:** &check;
-
-### CLI examples
-
-```bash
-mapshaper basemap.gpkg -info
-mapshaper basemap.gpkg -o format=geojson regions.geojson
-mapshaper -i basemap.gpkg layers=provinces,cities -info
-mapshaper provinces.shp -o provinces.gpkg
-mapshaper a.shp b.shp -o combined.gpkg
-```
-
-### Format-specific input options
-
-- `layers=` &mdash; comma-separated list of layer names to import. Useful for picking a subset out of a large multi-layer GeoPackage. Omit to import everything.
-
-### Format-specific output options
-
-There are no GeoPackage-specific `-o` options. The format honors the general flags (`precision=`, `gzip`, `zip`, etc.) where they apply.
-
-### Practical notes
-
-- By default, every vector layer in the file is imported as a separate Mapshaper layer. To pick a subset, use the `layers=` option on the CLI; in the web app, tick the **with advanced options** checkbox in the import dialog to bring up a per-layer selection list.
-- When multiple layers are exported to a single `.gpkg`, each becomes a separate layer table inside the database, named after the source layer.
-- Raster tile layers (the OGC GeoPackage spec also covers tiles) are ignored &mdash; Mapshaper is vector-only.
-
-
-## External resources
-
-- [geopackage.org](https://www.geopackage.org/) &mdash; project home with spec, FAQs and tool support.
-- [QGIS user manual: supported data formats](https://docs.qgis.org/latest/en/docs/user_manual/managing_data_source/supported_data.html) &mdash; the practical reference on how QGIS treats GeoPackage, including multi-layer use and project storage.
-- [Learn spatial SQL and master GeoPackage with QGIS](https://www.gispo.fi/en/blog/learn-spatial-sql-and-master-geopackage-with-qgis-3/) &mdash; tutorial from Gispo showing how to query GeoPackage layers with SQL directly from QGIS.
-- GeoPackage reading and writing in Mapshaper is delegated to NGA's [`@ngageoint/geopackage`](https://github.com/ngageoint/geopackage-js) library, which handles the underlying SQLite database, the OGC table schemas and the WKB-to-GeoJSON geometry conversions.
-
----
-
-<!-- https://mapshaper.org/docs/formats/flatgeobuf.html -->
-
-# FlatGeobuf
-
-FlatGeobuf is a modern binary vector format designed for fast streaming reads. A single self-contained file with UTF-8 text encoding, it avoids the companion-file clutter of Shapefile. Its optional embedded spatial index enables efficient bounding-box queries without reading the whole file, making it well-suited to large datasets served over HTTP. It also works well as a general-purpose GIS exchange format.
-
-**File extension:** `.fgb` &middot; **Read:** &check; &middot; **Write:** &check; &middot; **Multi-layer:** no (one layer per file)
-
-### CLI examples
-
-```bash
-mapshaper buildings.fgb -info
-mapshaper buildings.fgb -simplify 5% -o buildings.geojson
-mapshaper provinces.shp -o provinces.fgb
-```
-
-### Format-specific input options
-
-There are no FlatGeobuf-specific `-i` options.
-
-### Format-specific output options
-
-There are no FlatGeobuf-specific `-o` options. The format honors the general flags (`precision=`, `gzip`, `zip`, etc.) where they apply.
-
-### Practical notes
-
-- Mapshaper reads CRS metadata from the file header when it's encoded as an EPSG code. WKT2-only definitions can't be parsed and produce an "Unable to import WKT2 CRS from FlatGeobuf" warning &mdash; the layer comes in without a CRS.
-- On output, Mapshaper embeds an EPSG code in the FlatGeobuf header whenever it can derive one from the source: a round-tripped FlatGeobuf or GeoPackage CRS, an `epsg:NNNN` string passed to `-proj`, an `AUTHORITY["EPSG", N]` clause in a Shapefile `.prj`, or any encoding of WGS-84 or Web Mercator (which covers most GeoJSON, CSV-with-lat/lon and `-proj wgs84`/`-proj webmercator` outputs).
-- Mapshaper cannot yet convert an arbitrary proj4 definition (such as a custom Albers projection set with `-proj +proj=aea ...`) to an EPSG code. In that case the file is written with no CRS in the header and a warning is printed: *"Wrote `foo.fgb` without a CRS in the FlatGeobuf header..."*. Re-run the file through `ogr2ogr` if you need the CRS embedded for downstream tools.
-- Mapshaper does not write the optional packed R-tree spatial index, and it doesn't use the index for selective reads of indexed input either &mdash; the whole file is read into memory. If you need an indexed `.fgb` for HTTP range-request reads, build it with `ogr2ogr` or the [`flatgeobuf` CLI](https://github.com/flatgeobuf/flatgeobuf).
-
-## External resources
-
-- [flatgeobuf.org](https://flatgeobuf.org/) &mdash; project home with spec links and language bindings.
-- [Kicking the Tires: FlatGeobuf](https://worace.works/2022/02/23/kicking-the-tires-flatgeobuf/) &mdash; an independent practical writeup with benchmarks against Shapefile, GeoJSON and GeoPackage.
-- [Bryce Mecum: Flatgeobuf](https://brycemecum.com/2022/04/04/flatgeobuf/) &mdash; a hands-on exploration of streaming reads in the browser, including a worth-knowing gotcha about the spatial index sitting at the front of the file.
-- [Cloud-Native Geospatial Formats Guide: FlatGeobuf](https://guide.cloudnativegeo.org/flatgeobuf/) &mdash; how the format fits into modern cloud-storage workflows.
-- FlatGeobuf reading and writing in Mapshaper is built on the official [`flatgeobuf`](https://github.com/flatgeobuf/flatgeobuf) JavaScript library, which provides the FlatBuffers schema, header parsing and feature serialisation primitives.
-
----
-
-<!-- https://mapshaper.org/docs/formats/kml.html -->
-
-# KML and KMZ
-
-KML is Google's XML-based format for geographic data, originally created for Google Earth and now an OGC standard. KMZ is a zipped KML. KML emphasises display (icons, styles, balloons) over attributes, so it's most useful for handing files to viewers like Google Earth, mobile mapping apps and Google My Maps &mdash; as a data interchange format it has weaker attribute typing and schema support than [GeoJSON](/docs/formats/geojson.html.md) or [Shapefile](/docs/formats/shapefile.html.md).
-
-**File extensions:** `.kml`, `.kmz` &middot; **Read:** &check; &middot; **Write:** &check; &middot; **Multi-layer:** &check;
-
-### CLI examples
-
-```bash
-mapshaper places.kml -info
-mapshaper places.kmz -o format=geojson places.geojson
-mapshaper provinces.shp -proj wgs84 -o provinces.kml
-```
-
-### Format-specific input options
-
-There are no KML-specific `-i` options. Encoding is always UTF-8 per the KML spec.
-
-### Format-specific output options
-
-There are no KML-specific `-o` options.
-
-### Practical notes
-
-- KML stores all attribute values as strings, so numeric attributes are imported as strings.
-- KML requires WGS84 coordinates, but Mapshaper does **not** reproject on export &mdash; coordinates are written through as-is. If your dataset is in any other CRS, run `-proj wgs84` first, otherwise the output will not be conformant KML and viewers will misplace the geometry.
-
-
-## External resources
-
-- [OGC KML standard](https://www.ogc.org/standards/kml/) &mdash; the formal OGC specification.
-- [Google KML Reference](https://developers.google.com/kml/documentation/kmlreference) &mdash; the practical element-by-element reference; more readable than the OGC spec.
-- [Google KML Tutorial](https://developers.google.com/kml/documentation/kml_tut) &mdash; covers how Google Earth interprets the format.
-- KML reading and writing in Mapshaper is delegated to two third-party libraries: [`@tmcw/togeojson`](https://github.com/placemark/togeojson) for parsing KML into GeoJSON on import, and [`@placemarkio/tokml`](https://github.com/placemark/tokml) for serialising GeoJSON back to KML on export.
-
----
-
-<!-- https://mapshaper.org/docs/formats/csv.html -->
-
-# CSV and TSV
-
-Plain-text tabular data. Mapshaper treats CSV/TSV as pure attribute data by default, or as a point layer when longitude and latitude columns are present. Combined with [`-join`](/docs/reference.html.md#-join), CSV is the lowest-friction way to attach external attributes (population, election results, anything keyed on a stable id) to a geometry layer.
-
-**File extensions:** `.csv`, `.tsv` &middot; **Read:** &check; &middot; **Write:** &check; &middot; **Multi-layer:** no
-
-### CLI examples
-
-```bash
-mapshaper data.csv -info
-mapshaper data.csv -points x=lon y=lat -o points.geojson
-mapshaper big.csv csv-fields=id,name,pop -info
-mapshaper provinces.shp -drop-table -o stats.csv
-mapshaper data.csv -o delimiter=";" out.csv
-```
-
-### Format-specific input options
-
-- `encoding=` &mdash; text encoding. Default is UTF-8.
-- `string-fields=` &mdash; comma-separated list of fields to import as strings even if their values look numeric. Use `string-fields=*` to import every field as a string. Essential for ZIP codes, FIPS codes and anything else where leading zeros matter.
-- `field-types=` &mdash; per-field type hints, e.g. `FIPS:str,population:num`. More flexible alternative to `string-fields=`.
-- `csv-skip-lines=` &mdash; skip N lines at the top of the file. Useful for spreadsheet exports with notes above the data.
-- `csv-lines=` &mdash; import only the first N data rows.
-- `csv-field-names=` &mdash; assign explicit field names. Combine with `csv-skip-lines=1` to override existing headers.
-- `csv-fields=` &mdash; import only the named columns. Filtering happens during the read, so this option dramatically reduces peak memory for wide CSVs.
-- `csv-filter=` &mdash; a JavaScript expression evaluated per row. Rows that return false are dropped before they ever reach the layer.
-- `csv-dedup-fields` &mdash; rename duplicate column headers (otherwise Mapshaper errors out).
-- `decimal-comma` &mdash; parse numbers using `1.000,01` European convention instead of `1,000.01`.
-
-### Format-specific output options
-
-- `encoding=` &mdash; text encoding for the output. Default is UTF-8.
-- `delimiter=` &mdash; override the field delimiter, e.g. `delimiter="|"`.
-- `decimal-comma` &mdash; emit numbers using the European decimal-comma convention.
-- `field-order=ascending` &mdash; sort columns alphabetically.
-
-### Practical notes
-
-- The delimiter is auto-detected from the extension (`.csv` &rarr; comma, `.tsv` &rarr; tab). Use `-i format=csv` to force CSV parsing for a differently-named file (e.g. `.txt`).
-- When exporting non-point geometry to CSV, Mapshaper writes only the attribute table. Use [`-points`](/docs/reference.html.md#-points) first if you want to export point coordinates as `lon`/`lat` columns.
-- BOM-prefixed files (typically from Excel) are handled transparently on read.
-- Output has no quoting unless a value contains the delimiter, a quote or a newline.
-
-### Importing identifier-like fields (ZIP, FIPS, phone numbers&hellip;)
-
-This is the single biggest CSV footgun. Mapshaper guesses each column's type from its values, so a column of US ZIP codes like `02134`, `90210`, `10001` looks numeric and gets imported as numbers &mdash; silently stripping leading zeros and breaking any subsequent join. The same applies to FIPS codes, phone numbers, account numbers and any other identifier that happens to contain only digits.
-
-Always declare these columns as strings on import:
-
-```bash
-mapshaper -i counties.csv string-fields=GEOID,STATEFP,COUNTYFP -info
-mapshaper -i zips.csv string-fields=zipcode -join points key=zipcode,zipcode
-```
-
-If you don't trust the schema at all, `string-fields=*` imports every column as a string. You can also be precise with `field-types=`:
-
-```bash
-mapshaper -i data.csv field-types=GEOID:str,population:num,year:str -info
-```
-
-A symptom of getting this wrong is a join silently dropping all rows because `02134` (string) doesn't match `2134` (number).
-
-### Prefiltering large CSVs
-
-For multi-gigabyte CSVs &mdash; election precinct records, OSM extract attribute tables, parcel data &mdash; it usually isn't viable to load the whole file into memory and then filter. Mapshaper has two options that filter **during** the read, before the data lands in a layer:
-
-- `csv-fields=` &mdash; keep only the named columns. Wide CSVs (hundreds of columns, only a few of interest) shrink dramatically.
-- `csv-filter=` &mdash; a JavaScript expression evaluated per row. Rows that return false are skipped.
-
-Example (note that numerical fields have not been converted from strings at this point):
-
-```bash
-mapshaper -i big.csv \
-  csv-fields=GEOID,name,population,state \
-  csv-filter='state == "TX" && population > "10000"' \
-  -o cities-tx.csv
-```
-
-### In the web app
-
-The same import options work in the [web app](/docs/essentials/web-app.html.md). Tick **with advanced options** in the import dialog and pass any of `string-fields=`, `field-types=`, `encoding=`, `csv-fields=`, `csv-filter=` etc. as you would on the CLI:
-
-```
-string-fields=GEOID,STATEFP encoding=utf8
-```
-
-For very large CSVs, `csv-fields=` and `csv-filter=` are the most useful options for keeping memory under control. If a file is too big for the browser to load, the [`mapshaper-xl` CLI](/docs/essentials/command-line.html.md) is the fallback.
-
-## External resources
-
-- [RFC 4180: Common Format and MIME Type for CSV](https://datatracker.ietf.org/doc/html/rfc4180) &mdash; the closest thing to a CSV specification, though many real-world files diverge from it.
-- [Frictionless CSV Dialect spec](https://specs.frictionlessdata.io/csv-dialect/) &mdash; a practical schema for declaring how a particular CSV file is formatted (delimiter, quoting, line terminator).
-
----
-
-<!-- https://mapshaper.org/docs/formats/dbf.html -->
-
-# DBF
-
-DBF is the dBase database format. It's best known as the attribute-table half of a Shapefile, but Mapshaper can also import a `.dbf` on its own as a tabular layer with no geometry. [CSV](/docs/formats/csv.html.md) is generally preferred as an exchange format for tabular data.
-
-**File extension:** `.dbf` &middot; **Read:** &check; &middot; **Write:** &check; &middot; **Geometry:** none
-
-### CLI examples
-
-```bash
-mapshaper provinces.dbf -info
-mapshaper provinces.dbf -filter '"BC,AB,SK".indexOf(prov) > -1' -o subset.csv
-mapshaper data.csv -o data.dbf
-```
-
-### Format-specific input options
-
-- `encoding=` &mdash; text encoding. If omitted, Mapshaper auto-detects, falling back to a `.cpg` sidecar file if present. Run `mapshaper -encodings` for the list of supported encodings.
-
-### Format-specific output options
-
-- `encoding=` &mdash; output text encoding. Default UTF-8 (with a matching `.cpg` sidecar).
-- `field-order=ascending` &mdash; sort columns alphabetically.
-
-### Practical notes
-
-- DBF holds tabular data only &mdash; no geometry.
-- DBF files do not declare their text encoding internally. Mapshaper auto-detects against UTF-8, Windows-1252 and a few other common encodings. See the [Shapefile encoding notes](/docs/formats/shapefile.html.md#dbf-text-encoding) for the full picture.
-- Field names are limited to 10 ASCII characters. Longer names are truncated on write; duplicate truncated names are disambiguated with numeric suffixes.
-- Field values are limited to 254 characters; longer strings will have been truncated when the file was written.
-
-## External resources
-
-- [Wikipedia: .dbf](https://en.wikipedia.org/wiki/.dbf) &mdash; useful overview of the format's history and dialects.
-- [Xbase File Format Description](https://www.clicketyclick.dk/databases/xbase/format/) &mdash; Erik Bachmann's reference for the dBase / xBase family. The standard external citation for byte-level DBF details.
-
----
-
-<!-- https://mapshaper.org/docs/formats/json.html -->
-
-# JSON records
-
-A JSON-records file is a plain JSON array of objects, one per record, with no geometry.
-
-**File extension:** `.json` &middot; **Read:** &check; &middot; **Write:** &check; &middot; **Geometry:** none
-
-A JSON-records file looks like this:
-
-```json
-[
-  { "id": 1, "name": "Alice", "city": "Toronto" },
-  { "id": 2, "name": "Bob",   "city": "Vancouver" }
-]
-```
-
-### Format-specific input options
-
-- `json-path=` &mdash; for files where the array is nested inside a larger object, e.g. `json-path=data/records` for `{"data": {"records": [...]}}`.
-
-### Format-specific output options
-
-- `ndjson` &mdash; emit newline-delimited JSON instead of an array. One record per line. Often easier to process with line-oriented tools.
-
-### Practical notes
-
-- When exporting non-tabular layers as JSON records, the geometry is dropped &mdash; you get just the attribute table as JSON.
-
-## External resources
-
-- [JSON Lines (jsonlines.org)](https://jsonlines.org/) &mdash; the spec for the newline-delimited JSON variant emitted by Mapshaper's `ndjson` option.
-
----
-
-<!-- https://mapshaper.org/docs/formats/svg.html -->
-
-# SVG
-
-SVG is the W3C standard for vector graphics on the web. Mapshaper writes SVG and can also import its own SVG output files. Use SVG when you want to drop a non-interactive map straight into a web page or edit your map in Illustrator &mdash; it's a display format, not a data interchange format.
-
-**File extension:** `.svg` &middot; **Read:** &check; &middot; **Write:** &check; &middot; **Multi-layer:** &check;
-
-### CLI examples
-
-```bash
-mapshaper provinces.shp -o provinces.svg
-mapshaper provinces.shp -o width=1200 svg-data=name,pop provinces.svg
-mapshaper a.shp b.shp -o combined.svg
-```
-
-### Format-specific output options
-
-- `width=` &mdash; output width in pixels (default 800). Geometry is fitted to this width.
-- `height=` &mdash; output height in pixels. If both `width` and `height` are set, content is centred inside a `[0, 0, width, height]` viewport.
-- `max-height=` &mdash; cap the output height in pixels.
-- `pixels=` &mdash; total output area in pixels (alternative to `width=`).
-- `margin=` &mdash; padding between content and viewport edge (default 1 px). Pass `<left,bottom,right,top>` for asymmetric margins.
-- `svg-scale=` &mdash; scale in source units per pixel. Alternative to `width=` when you want a fixed scale rather than a fixed canvas size.
-- `svg-bbox=` &mdash; explicit `xmin,ymin,xmax,ymax` for the SVG viewport. Useful for aligning multiple SVG layers exported separately.
-- `fit-extent=` &mdash; use a layer (typically a single rectangle) to define the viewport.
-- `svg-data=` &mdash; comma-separated list of attribute fields to emit as `data-*` attributes on each `<path>`. Field names must match `[a-z_][a-z0-9_-]*`.
-- `id-field=` &mdash; promote one or more attribute fields to the SVG `id` attribute.
-- `id-prefix=` &mdash; prefix all generated layer/feature ids.
-- `point-symbol=square` &mdash; render points as squares instead of circles.
-
-### Practical notes
-
-- Each layer becomes a `<g>` group, with the layer name as the group id. Features become `<path>` (polygons/lines) or `<circle>` (points).
-- No data attributes are emitted unless you pass `svg-data=`.
-- The output is unstyled by default. Use [`-style`](/docs/reference.html.md#-style) to assign inline style attributes.
-- Very large or detailed layers can produce SVGs that are slow to render in browsers. Consider using [`-simplify`](/docs/reference.html.md#-simplify) before exporting.
-
-## External resources
-
-- [W3C SVG 2 specification](https://www.w3.org/TR/SVG2/) &mdash; the formal spec.
-- [MDN SVG tutorial](https://developer.mozilla.org/en-US/docs/Web/SVG/Tutorial) &mdash; the friendliest practical introduction, with browser support notes.
-
-## See also
-
-- [Add SVG styling for export](/docs/examples/basics.html.md#add-svg-styling-for-export)
-- [Quantile-classify into a color ramp](/docs/examples/basics.html.md#quantile-classify-into-a-color-ramp)
-- [Simplify a polygon layer for the web](/docs/examples/basics.html.md#simplify-a-polygon-layer-for-the-web)
-
----
-
-<!-- https://mapshaper.org/docs/formats/snapshot.html -->
-
-# Mapshaper snapshot (.msx)
-
-A Mapshaper snapshot captures the current state of a session &mdash; arcs, layers, attributes, CRS metadata, topology and (when written from the web app) the command history that produced it &mdash; as a single binary file. Snapshots are Mapshaper-specific and not intended for interchange with other GIS tools; for that, use [Shapefile](/docs/formats/shapefile.html.md), [GeoPackage](/docs/formats/geopackage.html.md), [FlatGeobuf](/docs/formats/flatgeobuf.html.md) or [GeoJSON](/docs/formats/geojson.html.md).
-
-**File extension:** `.msx` &middot; **Read:** &check; &middot; **Write:** &check; &middot; **Multi-layer:** &check;
-
-### When to use a snapshot
-
-- **Saving work-in-progress** for later editing, with topology, layer order and (in the web app) command history intact.
-- **Bundling a collection of datasets** into a single compact file that is quicker to re-open than re-running an import pipeline.
-- **In the browser, as a quick "save point"** before doing something experimental that might fail or give the wrong result &mdash; restore the snapshot to roll back.
-
-### From the CLI
-
-`-o foo.msx` captures the **entire session** &mdash; every dataset and every layer Mapshaper has loaded, not just the ones currently selected by `-target`. This makes a `.msx` file a faithful "save point" of the working state, regardless of which layers happen to be active.
-
-`-target` controls *visibility and stacking order*, not which layers are written:
-
-- Layers matched by the active `-target` (or the `target=` option on `-o` itself) come back **visible** in the web app, with no further setup.
-- They are stacked in the order matched by `-target` &mdash; first targeted on the bottom, last on top &mdash; so the GUI's layer stack matches the draw order you'd get from an SVG export of the same target list.
-- Layers that weren't targeted come along **hidden**, parked at the bottom of the layer panel. They're still in the file (so you can pin them visible later), but they don't get in the way of the intended view.
-- If you want to drop layers from the snapshot rather than just hide them, run an explicit step like `-filter-layers` or `-target b -drop` before `-o foo.msx`.
-
-### In the web app
-
-The ribbon icon in the layer panel opens the **snapshot menu**. From there you can:
-
-- **Create a snapshot** &mdash; saves to in-browser storage. These are session-scoped and **deleted when the tab closes or the page is reloaded.** For anything you want to keep, **Save snapshot to file** writes a `.msx` file you can re-open later.
-- **Export** a stored snapshot to a `.msx` file on disk. Persisted `.msx` files survive browser restarts and can be re-imported by drag-drop, the **Add files** button, or the `?files=` URL parameter.
-- **Restore** a stored snapshot into the current session.
-
-## External resources
-
-- [msgpack.org](https://msgpack.org/) &mdash; the binary serialization format used inside `.msx` (via the [msgpackr](https://github.com/kriszyp/msgpackr) library).
-
----
-
-<!-- https://mapshaper.org/docs/examples/basics.html -->
-
-# Basics
-
-Short Mapshaper examples for common tasks. The filenames and field names are illustrative &mdash; substitute your own. Most recipes also work in the [web app's](/docs/essentials/web-app.html.md) console: drop the leading `mapshaper` and the input filename; the GUI should already your data loaded.
-
-> Looking for the syntax of a particular command or option? See the [command reference](/docs/reference.html.md). For the JS expression context used by `-each`, `-filter`, `calc=` and other commands, see [JavaScript expressions](/docs/guides/expressions.html.md).
-
-## Inspecting and exploring
-
-### Print a summary of a dataset
-
-```bash
-mapshaper input.shp -info
-```
-
-`-info` prints the geometry type, feature count, CRS (if known), bounding box, and the name and type of every attribute field. It's the fastest way to remind yourself what a file actually contains. Add `save-to=info.json` to capture it as JSON.
-
-
-### Count features grouped by a field
-
-```bash
-mapshaper counties.shp \
-  -drop geometry \
-  -dissolve STATE calc='N = count(), POP = sum(POP)' \
-  -o state_data.csv
-```
-
-A dissolve with a `calc=` clause is an idiomatic way to aggregate data values.
-
-## Filtering and selecting
-
-### Keep features matching a condition
-
-```bash
-mapshaper countries.geojson -filter 'CONTINENT == "Asia" && POP > 1e7' \
-  -o output.geojson
-```
-
-`-filter` keeps features for which the expression returns `true`.
-
-### Keep features inside a bounding box
-
-```bash
-mapshaper world.shp -clip bbox=-10,35,30,60 -o europe.shp
-```
-
-The four bbox numbers are `xmin,ymin,xmax,ymax` in the layer's own coordinates.
-
-### Keep the top N features by some attribute
-
-```bash
-mapshaper cities.geojson \
-  -sort POP descending \
-  -filter 'this.id < 50' \
-  -o top50.geojson
-```
-
-`-sort POP descending` orders by population from largest to smallest. Features have numerical ids starting with `0`, so `this.id < 50` keeps the first 50.
-
-### Drop features with empty geometry
-
-```bash
-mapshaper messy.geojson -filter remove-empty -o clean.geojson
-```
-
-The `remove-empty` flag drops features with missing or empty geometry.
-
-## Editing attributes
-
-### Add derived fields
-
-```bash
-mapshaper counties.shp \
-  -each 'STATE_FIPS = COUNTY_FIPS.substr(0, 2),
-         AREA_KM2 = round(this.area / 1e6, 1)' \
-  -o out.shp
-```
-
-`-each` runs a JS expression on each feature; assigning to a bare name creates or updates a field. `round(x, 1)` is Mapshaper's rounding helper (one decimal here). On unprojected lat/long data, `this.area` returns square meters, dividing by 1e6 converts to square kilometers.
-
-### Rename and filter fields
-
-```bash
-mapshaper data.csv \
-  -rename-fields POPULATION=POP,MEDIAN_INCOME=MEDIAN_INC \
-  -filter-fields STATE,COUNTY,POPULATION,MEDIAN_INCOME \
-  -o cleaned.csv
-```
-
-`-rename-fields` takes `NEW=OLD` pairs. `-filter-fields` keeps only the listed fields, in the listed order &mdash; convenient for shaping CSV output.
-
-### Preserve leading zeros from a CSV
-
-```bash
-mapshaper -i counties.csv string-fields=FIPS,STATEFIPS \
-  -o counties.shp
-```
-
-By default Mapshaper parses any numeric-looking CSV column as a number, which silently drops leading zeros from FIPS, ZIP and similar identifier columns. `string-fields=` forces the named columns to stay as strings.
-
-## Joining data
-
-### Join a CSV to a Shapefile by key
-
-```bash
-mapshaper states.shp \
-  -join demographics.csv keys=STATE_FIPS,FIPS string-fields=FIPS \
-  -o states_with_data.shp
-```
-
-`keys=A,B` means "match the target's `A` field to the source's `B` field". `string-fields=FIPS` (passed through to the CSV import) keeps the FIPS code as a string so `"06"` matches `"06"` rather than being parsed to `6`. To pull just a few columns from the source, add `fields=FIELD_A,FIELD_B`.
-
-### Spatial join: tag points with the polygon they fall in
-
-```bash
-mapshaper crimes.geojson \
-  -join precinct_polygons.shp \
-  -o crimes_with_precinct.geojson
-```
-
-When `keys=` is omitted, `-join` falls back to a spatial join based on the geometry types involved. Here, every point inherits the attributes of the polygon containing it. Use `fields=PRECINCT_ID,DIVISION` to keep just specific columns.
-
-### Many-to-one join with an aggregation
-
-```bash
-mapshaper precincts.shp \
-  -join crimes.geojson calc='N = count(), AVG_SEVERITY = mean(SEVERITY)' \
-  -o precincts_with_stats.shp
-```
-
-A polygon-to-many-points join can use `calc=` to summarize the matched source records into one or more new fields per target feature. The functions in `calc=` are the same set documented under [`-calc`](/docs/reference.html.md#-calc).
-
-## Simplifying
-
-### Simplify a polygon layer for the web
-
-```bash
-mapshaper provinces.shp \
-  -simplify 5% keep-shapes \
-  -clean \
-  -o format=topojson provinces.topojson
-```
-
-`-simplify 5%` keeps 5% of the original vertices using the default weighted Visvalingam algorithm. `keep-shapes` prevents simplification from wiping out very small polygons. `-clean` mops up any topology errors introduced by aggressive simplification. TopoJSON output is usually 2&ndash;5x smaller than the equivalent GeoJSON.
-
-### Simplify multiple files with shared topology
-
-```bash
-mapshaper -i states.shp counties.shp combine-files \
-  -simplify 10% \
-  -o out/
-```
-
-`combine-files` merges the inputs into one dataset before Mapshaper builds its arc topology, so vertices shared between layers stay shared after simplification &mdash; no gaps or overlaps along state/county boundaries. Each input still gets written back out as a separate file in `out/`. In the web app, add `combine-files` in the **Advanced options** field at import time to get the same behavior.
-
-### Repair topology errors
-
-```bash
-mapshaper messy.shp -clean -o cleaned.shp
-```
-
-`-clean` snaps near-duplicate vertices, removes tiny gaps and overlaps between polygons, and fixes self-intersecting lines. It's a safe first step before any spatial operation. You can tune `gap-fill-area=`, `sliver-control=` or `snap-interval=` if necessary.
-
-## Aggregating
-
-### Dissolve to a parent geography
-
-```bash
-mapshaper counties.shp -dissolve STATE -o states.shp
-```
-
-`-dissolve` merges adjacent polygons that share a value in the named field.
-
-### Dissolve while computing per-group stats
-
-```bash
-mapshaper counties.shp \
-  -dissolve STATE calc='N = count(),
-                        POP = sum(POP),
-                        MEDIAN_INC = median(MEDIAN_INC)' \
-  -o states_with_stats.shp
-```
-
-`calc=` works inside `-dissolve` as well as `-join`. The named functions (`count`, `sum`, `mean`, `median`, `mode`, `min`, `max`, `quartile1/2/3`, `iqr`, `quantile`, `collect`, `every`, `some`, `first`, `last`) all see the same per-feature context as `-each`.
-
-### Convert points to population-weighted centroids
-
-```bash
-mapshaper cities.shp \
-  -dissolve STATE_FIPS weight=POPULATION \
-  -o state_centers.shp
-```
-
-Dissolve groups of points that share a `STATE_FIPS` value into a single weighted centroid per group. The `weight=` option accepts a field name or a JS expression. Omitting a grouping field dissolves all points into one centroid.
-
-## Spatial operations
-
-### Erase one layer from another
-
-```bash
-mapshaper land.shp -erase lakes.shp -o land_no_lakes.shp
-```
-
-`-erase` removes the parts of the target layer that fall inside the source layer's polygons. Useful for masking out water, parks, or any "do-not-count" region. The inverse is `-clip`, which keeps the inside instead.
-
-### Compute interior boundaries
-
-```bash
-mapshaper counties.shp -innerlines -o county_borders.shp
-```
-
-`-innerlines` returns the shared boundaries between polygons as a polyline layer, which is usually used for adding a stroke to interior boundaries on a styled map. Use [`-lines`](/docs/reference.html.md#-lines) instead if you want to retain both outer and inner boundaries.
-
-### Generate a hex grid covering a layer
-
-```bash
-mapshaper region.shp \
-  -grid type=hex interval=10km name=hex \
-  -o hex.shp
-```
-
-`-grid` builds a regular grid (`square`, `hex`, `hex2`) covering the target's bounding box. Pair it with a spatial join to style the grid cells using interpolated count data (`-join interpolate=POPULATION`).
-
-## Reprojection
-
-### Project to a named CRS
-
-```bash
-mapshaper world.geojson -proj robinson -o world_robinson.geojson
-```
-
-`-proj` accepts EPSG codes (`EPSG:3857`), PROJ strings (`+proj=tmerc +lon_0=...`), or short aliases (`wgs84`, `webmercator`, `robinson`, `albersusa`). See the [Projections guide](/docs/guides/projections.html.md) for details.
-
-### Match the projection of another file
-
-```bash
-mapshaper points.shp -proj match=basemap.shp -o points_aligned.shp
-```
-
-`match=` reads the CRS of another file and projects the target to match it &mdash; handy when assembling multiple datasets that need to share a coordinate system.
-
-## Classification and styling
-
-### Quantile-classify into a color ramp
-
-```bash
-mapshaper covid_cases.geojson \
-  -classify save-as=fill quantile classes=6 color-scheme=Oranges \
-  -o themed.geojson
-```
-
-`-classify` writes a class index or a derived value (here, a fill color) into the named field. The default is sequential quantile classification, but you can switch to `equal-interval`, `nice`, `categorical` or `non-adjacent`. Run `mapshaper -colors` to list the built-in color schemes.
-
-### Add SVG styling for export
-
-```bash
-mapshaper boundaries.shp \
-  -style stroke="#444" stroke-width=0.5 fill=none \
-  -style where='RANK == 0' stroke="#000" stroke-width=1.5 \
-  -o map.svg
-```
-
-`-style` writes SVG presentation attributes onto each feature; the `where=` form lets you set them conditionally. The result is a valid SVG you can drop into a print or web layout.
-
-## Output and conversion
-
-### Convert Shapefile &harr; GeoJSON
-
-```bash
-mapshaper input.shp -o input.geojson
-mapshaper input.geojson -o input.shp
-```
-
-The output format is inferred from the file extension. Use `format=` to force it (e.g. `-o format=topojson out.json`). When writing a Shapefile, Mapshaper produces `.shp`, `.shx`, `.dbf`, and `.prj`. If no output filename is given, the output file takes the name of the targeted layer.
-
-### Quantized TopoJSON
-
-```bash
-mapshaper boundaries.shp -o boundaries.topojson
-```
-
-TopoJSON output is quantized by default — Mapshaper picks a quantization level based on the data's coordinate range. Quantization rounds coordinates to a grid, which dramatically shrinks file size. The default can be overridden with `quantization=` (e.g. `quantization=1e5`). Combined with `-simplify` and TopoJSON's shared-arc encoding, quantized output is routinely 2&ndash;5&times; smaller than equivalent GeoJSON.
-
-### Output as ndjson
-
-```bash
-mapshaper big.geojson -o ndjson big.ndjson
-```
-
-Newline-delimited JSON is friendlier to line-oriented tools like jq, BigQuery, and DuckDB. One Feature per line, no enclosing FeatureCollection.
-
-### Split a layer into multiple files
-
-```bash
-mapshaper counties.shp \
-  -split STATE \
-  -o out/ extension=geojson
-```
-
-`-split FIELD` partitions features into separate layers by the value of `FIELD`; `-o` to a directory then writes one file per layer, named after the field value.
-
-## Workflow patterns
-
-### Run a chain of commands from a file
-
-```
-# build.txt
-mapshaper
--i counties.shp
--rename-fields POP=POPULATION
--dissolve STATE calc='POP = sum(POP)'
--simplify 5%
--o out/states.topojson
-```
-
-```bash
-mapshaper -run build.txt
-# or simply:
-mapshaper build.txt
-```
-
-Long pipelines can be kept in a [command file](/docs/reference.html.md#command-files).
-
-### Parameterize a command file
-
-```bash
-mapshaper -vars YEAR=2024 PCT=10 -run build.txt
-```
-
-```
-# build.txt
-mapshaper
--defaults YEAR=2020 PCT=5
--i sources/counties_{{YEAR}}.shp
--simplify {{PCT}}%
--o out/counties_{{YEAR}}.shp
-```
-
-`{{VAR}}` placeholders are substituted at parse time. `-defaults` sets values that the caller can override with `-vars` (or with `{{env.NAME}}` for environment variables).
-
-### Stop a pipeline early on bad input
-
-```bash
-mapshaper input.csv \
-  -calc 'N = count()' \
-  -if 'global.N == 0' \
-    -print 'No records, exiting' \
-    -stop \
-  -endif \
-  -o out.csv
-```
-
-`-calc` expressions can publish values to the `global` object via simple assignment. `-if`/`-stop` then guard the rest of the pipeline. Useful in scripts where bad upstream data should fail loudly rather than silently produce empty output.
-
-### Increase the heap for very large files
-
-```bash
-mapshaper-xl 16gb counties_5m.shp -simplify 10% -o counties_5m.topojson
-```
-
-`mapshaper-xl` is a wrapper that launches Node with extra heap space (default 8 GB; pass a size to override). Use it whenever you see "JavaScript heap out of memory" errors.
-
-## See also
-
-- [Command reference](/docs/reference.html.md) &mdash; every command and option
-- [JavaScript expressions](/docs/guides/expressions.html.md) &mdash; the syntax and context used by `-each`, `-filter`, `calc=`, etc.
-
----
-
-<!-- https://mapshaper.org/docs/examples/globe.html -->
-
-# Globe locator map
-
-Difficulty: moderate
-
-<!-- mapshaper:image -->
-
-### Steps
-
-1. Load country polygons (source: Natural Earth)
-2. Project countries using the Earth from space projection
-3. Simplify country borders
-4. Derive a line layer from the country polygons
-5. Add a circle so we can show a background color
-6. Add graticule lines
-7. Add a dot and a label
-8. Style all the layers
-9. Export as SVG
-
-### Code
-
-<!-- mapshaper:code -->
-
-### Notes
-
-* The PROJ string `+proj=nsper +h=1e7 +lat_0=35 +lon_0=2.35` uses the near-side perspective projection (sometimes called "Earth from space") from a height of 10,000 km above the Earth. This gives a more zoomed-in appearance than the orthographic projection (`+proj=ortho`), which is also commonly used for globe maps.
-* `-graticule polygon` creates a polygon that matches the boundary of the graticule, to give the map a background shape.
-* `-filter true +` is the Mapshaper idiom for copying a layer (the filter expression is `true`, which means every feature is retained).
-
-### Assets
-
-<!-- mapshaper:assets -->
-
----
-
-<!-- https://mapshaper.org/docs/examples/us-states.html -->
-
-# U.S. state map
-
-Difficulty: easy
-
-<!-- mapshaper:image -->
-
-### Steps
-
-1. Load state/province polygons (source: Natural Earth)
-2. Keep only U.S. states
-3. Project to the "Albers USA" projection
-4. Assign random, non-adjacent colors
-5. Export as SVG
-
-### Code
-
-<!-- mapshaper:code -->
-
-### Notes
-
-* To see the list of built-in color schemes to use with `-classify`, run `mapshaper -colors`. You can also use `colors=random`.
-* The Albers USA projection (`-proj albersusa`) is a custom projection used by The New York Times for U.S. maps.
-
-### Assets
-
-<!-- mapshaper:assets -->
-
----