# Mapshaper

> Mapshaper is a command-line tool and in-browser editor for geographic vector and raster data. It reads and writes Shapefile, GeoJSON, TopoJSON, GeoPackage, FlatGeobuf, GeoParquet, GeoTIFF, 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, GeoParquet, GeoTIFF, 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/reference.html">
    <p class="card-title">Command reference</p>
    <p class="card-desc">Every command and option, with examples.</p>
  </a>
  <a class="section-card" href="/docs/whats-new.html">
    <p class="card-title">What's new</p>
    <p class="card-desc">A curated log of recently added features.</p>
  </a>
  <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">In-depth coverage of key topics.</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 all of Mapshaper's supported data formats.</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 editing tasks, plus a collection of full map recipes.</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>

## Help and feedback

- Found a bug or want to request a feature? [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.

## September 2026

<div class="whats-new-entry">

**Pie and donut symbols.** The `-symbols` command has a new `pie` type. A `values=` list sets the size of each wedge from numbers, field names or expressions, and a `fills=` list sets their colors. Adding `hole=` makes the symbol a donut, either as a radius or, if negative, as a distance inward from the edge.

→ See [`-symbols`](/docs/reference.html.md#-symbols) and the [styles and symbols guide](/docs/guides/styles-and-symbols.html.md).
</div>

## August 2026

<div class="whats-new-entry">

**Repel command.** The `-repel` command removes or reduces overlaps between circle symbols. A `max-shift=` option keeps symbols within a given distance of their true positions. A `polygons=` option constrains symbols to polygon boundaries.

→ See [`-repel`](/docs/reference.html.md#-repel).
</div>

<div class="whats-new-entry">

**Isobands.**  The `-contours` command has a new `closed` flag for creating polygon bands.

</div>

<div class="whats-new-entry">

**Clean command improvements.**

- A new `close-outer-gaps` option closes cracks that open onto the outside of a polygon mosaic.
- The `gap-width=` option is now the preferred way to set the threshold for filling gaps. Gap artifacts tend to be long and thin slivers, so a width parameter is more suitable than the now-deprecated `gap-fill-area=` and `sliver-control=` options.

</div>

<div class="whats-new-entry">

**Snip tool.** The web UI has a snip mode for cutting polyline features apart. Hover over a line to see its vertices, then click a vertex or a point along a segment to divide it in two. The shorter piece becomes a new feature, so on a multipart feature the rest stays connected. Rings take two clicks, since one cut leaves them in one piece.

</div>

## July 2026

<div class="whats-new-entry">

**Saving rasters as GeoTIFF files.** Raster layers can now be exported to a `.tif` GeoTIFF file. Files are compressed by default.

→ See [File formats](/docs/formats/overview.html.md) and [`-o`](/docs/reference.html.md#-o).
</div>

<div class="whats-new-entry">

**Contour lines from rasters.** The `-contours` command traces contour lines from a raster layer &mdash; typically elevation contours from a digital elevation model. Mapshaper picks a sensible spacing between lines from the data itself, or you can set your own with `interval=` or a list of `levels=`. Add `+` to keep the raster layer.

→ See [`-contours`](/docs/reference.html.md#-contours).
</div>

<div class="whats-new-entry">

**Blur command.** The `-blur` command takes a radius either in pixels (`-blur 5px`) or as a real-world distance (`-blur 500m`). Slightly blurring an elevation model before running `-contours` is an effective way to get smoother, more generalized contour lines.

→ See [`-blur`](/docs/reference.html.md#-blur).
</div>

<div class="whats-new-entry">

**Interrupted and polyhedral world projections.** The `-proj` command supports Interrupted Goode Homolosine (`igh`, `igh_o`), Interrupted Mollweide (`imoll`, `imoll_o`), Buckminster Fuller's Dymaxion map (`dymaxion`, `dymaxion2`), two octahedral butterfly maps (`butterfly`, `butterfly2`), the Cahill-Keyes projection (`cahill_keyes`), Hajime Narukawa's 2022 update to the AuthaGraph projection (`narukawa2022`), and two rectangular world maps using tetrahedral geometry (`markley`, `calm`). The `-graticule` command can generate graticules, polygon footprints and neatlines for all of these projections.

→ See [Interrupted and polyhedral world projections](/docs/guides/projections.html.md#interrupted-and-polyhedral-world-projections).
</div>

<div class="whats-new-entry">

**Ruler tool.** The web UI has a ruler mode for measuring distances on the map. It supports great-circle measurements, projected distance readouts, basemap view, and draggable ruler endpoints.

</div>

## June 2026

<div class="whats-new-entry">

**Smooth command.** The `-smooth` command smooths the geometry of polygon and polyline features to a given resolution.

- Sharp corners where straight-line segments meet are preserved by default instead of being rounded.
- By default, a pre-filter is applied to remove intricate sub-scale detail (jetties, narrow inlets, spikes).
- The `gain` option controls the amplitude of output curves.
- The `max-bend-angle` option trades output vertex count against join smoothness.

→ See [`-smooth`](/docs/reference.html.md#-smooth).
</div>

<div class="whats-new-entry">

**Buffer command.** The `-buffer` command makes buffers around points, lines and polygons.

- The command uses geodesic distance on lat-long datasets and on projected datasets with the `geodesic` option.
- Negative `radius` parameters shrink polygons (positive distances expand them).
- The `topological` option prevents buffers from overlapping nearby polygons.
- The `fill-gaps` option fills enclosed holes and narrow-mouthed inlets (like a river up to its mouth) without growing the outer boundary.

→ See [`-buffer`](/docs/reference.html.md#-buffer).
</div>

## May 2026

<div class="whats-new-entry">

**Raster layer support.** Mapshaper can now import GeoTIFF rasters, plus PNG and JPEG images with world-file georeferencing, preview them in the web UI, clip them with the rectangle tool, and export as images embedded in SVG. Mapshaper's default options for raster importing and projecting rasters should work well for typical image layers. When importing rasters containing data, you may need to set additional options, which are documented in the command reference.

→ See [`-i`](/docs/reference.html.md#-i-input).
</div>

<div class="whats-new-entry">

**Point icons with `-style`.** The `-style` command has new `icon=`, `icon-size=` and `icon-color=` options for drawing simple point icons, including circles, squares, rings and stars. Icons can be combined with labels on the same point layer.

→ See [`-style`](/docs/reference.html.md#-style).
</div>

<div class="whats-new-entry">

**Undo/redo for web UI commands.** The web UI can now save temporary restore data while you work, so console commands and other data edits can be undone and redone from a pop-up toolbar. **This feature is very new and may have bugs, please report any problems that you encounter**. Undo is on by default and can be turned off from the new History menu.

</div>

<div class="whats-new-entry">

**More grid options.** The `-grid` command can now create rhombus and triangle grids. There are new `cols=`, `rows=` and `cells=` options for controlling the size of the grid cells, as alternatives to the original `interval=` option. A new `cell-scale=` option lets you scale each cell within the grid (creating gaps or overlaps between adjacent cells).

→ See [`-grid`](/docs/reference.html.md#-grid).
</div>

<div class="whats-new-entry">

**GeoParquet support.** Mapshaper reads and writes GeoParquet (`.parquet`) files. To use ZSTD compression (instead of the default Snappy compression), add `compression=zstd` to the output options.

→ See [GeoParquet](/docs/formats/geoparquet.html.md).
</div>

## April 2026

<div class="whats-new-entry">

**Messages panel.** Warnings and informational messages are now collected in a messages panel. When new messages are available, an icon with a count appears in the header bar; clicking it opens the panel. This keeps important information accessible without interrupting your session with a modal popup.

</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. **Update:** these files can also be imported and run in the browser UI.

```bash
mapshaper build.txt
```

→ See [Command files](/docs/essentials/command-line.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/essentials/command-line.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 now 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. If the first token is not a command, Mapshaper infers one: most file paths are treated as `-i`, while `.txt` command files are treated as `-run`.

#### 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=*
```

## Index of commands

**File I/O**

[-i (input)](#-i-input)
[-o (output)](#-o-output)

**Editing**

[-affine](#-affine)
[-buffer](#-buffer)
[-classify](#-classify)
[-clean](#-clean)
[-clip](#-clip)
[-colorizer](#-colorizer)
[-dashlines](#-dashlines)
[-densify](#-densify)
[-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)
[-repel](#-repel)
[-require](#-require)
[-run](#-run)
[-scalebar](#-scalebar)
[-shape](#-shape)
[-simplify](#-simplify)
[-smooth](#-smooth)
[-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, table, or raster data format. Supported file types include: Shapefile, GeoJSON, TopoJSON, GeoPackage, FlatGeobuf, GeoParquet, KML, JSON data records, DBF, CSV/TSV, GeoTIFF, PNG and JPEG images with world files.

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.

`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.

`scaling=none|minmax|percentile` [Raster] Display scaling method for raster imports. The default is `none` for 8-bit rasters and `percentile` for non-8-bit rasters.

`scale-range=` [Raster] Output intensity range for raster display scaling, as normalized percentages. The default is `0,100`.

`percentile-range=` [Raster] Input percentile range used with `scaling=percentile`. The default is `2,98`.

`raster-type=image|categorical|continuous` [Raster] Semantic raster type. This sets the default resampling method for later raster reprojection, and how uncovered pixels are filled. `image` (the default) uses bilinear resampling and fills with a color. `categorical` uses nearest-neighbor resampling to preserve class/code values, and fills with the source nodata value. `continuous` is for measurement rasters such as elevation models: it uses bilinear resampling like `image` but fills with the source nodata value like `categorical`, so uncovered pixels do not become a color value mixed in with the data.

`rendition=` [GeoTIFF] Import a specific GeoTIFF rendition, using a slug such as `full` or `overview-1`. When a GeoTIFF has internal overviews, Mapshaper lists the available slugs during import. By default, large GeoTIFFs are imported from the best available reduced-resolution overview under Mapshaper's import size limit, or resampled during import if no suitable overview is available. Use `rendition=full` to force full-resolution import.

`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|geoparquet|geotiff|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. The `geotiff` format takes raster layers only; every other format takes vector or table layers only, apart from `svg` and `msx`, which accept both.

`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).

`reverse-winding`  (GeoJSON) Reverse the winding order of GeoJSON polygon rings on export, so outer rings have clockwise order and holes have counter-clockwise order. This option will usually generate d3-compatible GeoJSON files, but it doesn't apply special spherical-geometry rules for very large polygons or ocean polygons.

`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).

`metadata`  (SVG/TopoJSON/GeoJSON) Include metadata in output. In the case of SVG output, CRS and bbox data is embedded in the file, so when the SVG is re-imported the original geographic coordinates can be recovered. For GeoJSON output, this option re-emits non-structural top-level members that were present in the imported GeoJSON file, such as a legacy `crs` object, a top-level `id`, or non-standard members like `metadata`. Preserved members are passed through unchanged, so values that describe the data (e.g. a feature count) may become stale after editing. A preserved `crs` member is dropped if the dataset is reprojected with `-proj`.

`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.

`raster-res=` (SVG) Resolution of embedded raster images, in raster pixels per SVG pixel. The default is `1`; larger values produce higher-resolution embedded images, up to the resolution of the source raster.

`linked-images` (SVG) Output raster images as separate JPEG or PNG files and link to them from SVG `<image>` elements instead of embedding them as data URIs.

`jpeg-quality=` (SVG) JPEG quality for embedded or linked raster images, from `1` to `100`. The default is `85`.

`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).

`compression=`  (GeoParquet) Select Parquet column compression. One of: `snappy` `zstd` `none`. The default is `snappy`. (GeoTIFF) One of: `deflate` `none`. The default is `deflate`.

`level=`  (GeoParquet) Set the ZSTD compression level when using `compression=zstd`. Valid values are integers from 1 to 22.

`rowgroup=`  (GeoParquet) Set the number of rows in each row group. By default Mapshaper sizes row groups by their estimated size in bytes rather than by a fixed row count, aiming for around 16MB of uncompressed data per group, so that a layer of points and a layer of detailed polygons both produce groups of a similar size. Set this only if you know the access pattern you are writing for.

`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=`

### -blur

Apply a Gaussian-like blur to raster layers. The command only works on projected
rasters; unprojected lat-long rasters should be reprojected first with `-proj`.

`<radius>` Blur amount, given either in pixels or as a real-world distance. This
value corresponds to `2 * sigma` of a Gaussian curve. Pixels can be written as
plain numbers or with a `px` suffix (`radius=10`, `radius=10px`); distances carry
units (`radius=500m`, `radius=2km`) and are converted using the size of a pixel
on the ground, so the same command gives a comparable amount of blur on rasters
of differing resolution. The radius can be given without the `radius=` prefix,
for example `-blur 5px` or `-blur 500m`.

Common options: `target=`

### -buffer

Create buffer polygons around point, polyline or polygon features.

The buffer distance is given by the `<radius>` parameter. For layers in
longitude/latitude coordinates, distances such as `2km` or `500m` are measured
over the earth, so a one-kilometer buffer is approximately one kilometer on the ground. For projected layers, distances are measured in the layer's flat,
projected coordinate system, so be aware that results can be distorted if the layer is in a projection that does not preserve distances well across the data area.

For point layers, `-buffer` creates circular polygons. For polyline layers, it
creates rounded or flat-ended line buffers. For polygon layers, positive buffers expand polygons and shrink holes; negative buffers shrink polygons and expand holes. Negative buffers are only supported for polygon layers.

`<radius>` or `radius=` Buffer distance, as a constant or JavaScript expression.
Distance units may be included in the radius value, for example `500m`, `2km`,
`1mi` or `1000ft`. If no units are given, meters are assumed when the dataset
has a known CRS. For datasets without CRS information, unitless radius values
are interpreted in source coordinate units.

`tolerance=` Acceptable radius error for line and polygon buffers. Values may be distances, such as `20m`,
or percentages of the buffer radius, such as `1%`. The default is `1%`. Buffer generation is faster using a small tolerance, but you can disable this optimization by setting `tolerance=0`.

`vertices=` [points] Number of vertices used to approximate each point buffer
circle. The default is 72.

`quad-segs=` [lines, polygons] Number of segments per quarter-circle in joins
and caps. The default is 8.

`cap-style=flat|round` [lines] End cap style for line buffers. The default is
`round`.

`topological` [polygons] Buffer only unshared polygon boundaries, such as coastlines and empty holes. Buffer areas do not cover any
original polygon areas, and overlapping buffer areas are partitioned between features by proximity, so each point in a contested area is assigned to the nearest source polygon.

`fill-gaps` [polygons] Fill enclosed holes and narrow-mouthed inlets — gaps whose
opening is narrower than the buffer distance — without growing the outer
boundary (a river is filled up to its mouth, but the open coastline is left in
place). The filled area is partitioned among the adjacent features by proximity.

`max-widening=` [polygons, with `fill-gaps`] Fill interior gaps up to this
multiple of the buffer distance wide; wider gaps are kept open. The default is 5.
For example, with a 1km buffer distance and the default `max-widening` value, an interior gap is
filled if it is narrower than 5km and left open otherwise.

`merge-islands` [polygons, with `fill-gaps`] Also bridge a small isolated island
to a neighboring landmass when the gap between them is narrower than the buffer
distance. By default such islands are left separate (only a landmass smaller than
a disk of the mouth radius is treated as an island; gaps between larger landmasses,
such as a river between two states, are filled either way).

`geodesic` [projected data] Buffer using geodesic distances instead of projected planar distances.

Common options: `name=` `+` `target=`

```bash
# Buffer a line layer by 2 km
mapshaper roads.shp -buffer 2km -o roads_buffer.geojson

# Create a topological coastline-style buffer around polygons
mapshaper counties.shp -buffer 100m topological -o counties_buffer.geojson

# Fill inlets and enclosed holes up to 500m wide without growing the coastline
mapshaper land.shp -buffer 500m fill-gaps -o land_filled.geojson
```

### -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. Areas that are contained by more than one polygon (overlaps) are assigned to the polygon with the largest area.

A filled gap goes to the feature it shares the longest boundary with, except where it borders three or more features: such a gap is divided between them, each receiving the part of it that lies nearest, so that a crack running past several features does not become a spur on whichever one claimed it. A gap narrower than the detail of the data around it is given whole to one feature instead — that moves a boundary by less than the width of the gap, where dividing it would give several features a hair-thin sliver each.

A boundary that two neighboring features each carry their own copy of, differing only in the last digits of its coordinates, is merged into one shared boundary. Left alone, the hair-thin gap between the two copies would be filled like any other gap, and awarded to one of the features, which would then carry a zero-width spike along a boundary it shares with its neighbors — visible as a stray line as soon as that feature is drawn with an outline.

Only gaps that are completely enclosed by polygons can be filled. Use `close-outer-gaps` to reach a crack that opens onto the outside instead.

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-width=`  (polygons) Fill gaps narrower than this width (e.g. `2m`, `0`). Each gap’s width is estimated from its area and perimeter (roughly, how wide a long thin shape would be if straightened out), so slender cracks are filled while more compact holes of similar area, such as small lakes, are more likely to be kept. Defaults to an automatic value based on the median segment length of the layer. The same width applies to the cracks that `close-outer-gaps` reaches.

`close-outer-gaps`  (polygons) Close cracks that open onto the outside of the mosaic, up to the width set by `gap-width=`. Such a crack is not enclosed by polygons, so there is no gap for the ordinary filling to find. Its mouth is pinched shut where the two sides come within that width of each other, which encloses it, and it is then filled — or divided between its neighbors, where it borders three or more of them — like any other gap. Only the pinched pair of vertices moves, half the width of the mouth each, and interior gaps are filled exactly as they are without this option. It is opt-in because it seals off narrow openings in a coverage, which are not always mistakes.

`gap-fill-area=`  (polygons, deprecated) Use `gap-width=` instead. Gaps smaller than this area will be filled; larger gaps will be retained as holes in the polygon mosaic. Example values: 2km2 500m2 0.

`sliver-control=` (polygons, deprecated) Use `gap-width=` instead. 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
```

### -contours

Convert a raster layer to a polyline layer of contour lines (isolines). Add
`closed` to create polygon bands between the contour lines instead. This is most
often used with a digital elevation model, but it works on any continuous
raster.

Running `-blur` before `-contours` produces smoother lines than contouring the raw data.

Values are read at pixel centers, so ordinary contour lines span from the center
of the first pixel to the center of the last, half a pixel inside the raster's
bounds. Closed bands extend lines that reach this outer lattice to the raster
bounds and use the bounds as a fixed outer frame.

`-contours` finishes by smoothing the lines, using an interval of a quarter of a
pixel. Where smoothing causes lines to cross, the intersecting lines are left unsmoothed. Use `no-smoothing` to
skip the step and keep the raw traced geometry, which you can then smooth
yourself with `-smooth`.

By default the contour layer replaces the raster layer. Use `+` to keep the
raster as well.

`interval=` Spacing between contour levels. Levels are multiples of this value,
so `interval=100` gives levels at 100, 200, 300 and so on. If neither
`interval=` nor `levels=` is given, mapshaper picks a round interval that
divides the raster's value range into roughly fifteen steps.

`levels=` Explicit comma-separated list of contour levels, for example
`levels=0,100,500,1000`. Overrides `interval=`.

`base=` Value to align `interval=` to (the default is 0). For example
`interval=100 base=50` gives levels at 50, 150, 250 and so on.

`band=` Index of the band to read values from (the default is 0). Elevation
models normally have a single band.

`field=` Name of the output field holding each line's contour value. The default
is `value`. This option applies to line output, not `closed` output.

`closed` Create polygon bands instead of contour lines. Each feature has
`lower` and `upper` fields. Interior bands are lower-inclusive and
upper-exclusive; the highest band includes the raster maximum. The lowest and
highest bounds are the minimum and maximum valid raster values, while interior
bounds come from `interval=` or `levels=`.

`no-smoothing` Skip contour smoothing. With `closed`, the contour boundaries are
smoothed by default but the raster and nodata closure boundaries are not.

Common options: `name=`, `no-replace`, `target=`

```bash
# Trace 100-meter contours from an elevation model
mapshaper dem.tif -contours interval=100 -o contours.json

# Blur the data first, then label the output field ELEV
mapshaper dem.tif raster-type=continuous \
  -proj webmercator \
  -blur radius=3 \
  -contours interval=50 field=ELEV \
  -o contours.json

# Keep the raster and draw specific contours over it
mapshaper dem.tif -contours levels=500,1000,1500 + name=contours \
  -o output.svg

# Create smoothed, closed elevation bands
mapshaper dem.tif -contours interval=100 closed -o bands.json

# Trace raw lines, then smooth them by hand
mapshaper dem.tif -contours interval=100 no-smoothing \
  -smooth 40 no-corners no-prefilter \
  -o contours.json
```

### -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.

### -densify

Add vertices along the segments of polyline and polygon features, so that no
segment is longer than a given interval. Densifying before reprojecting allows long straight segments to follow a curved path. Densifying can also improve the quality of geodesic buffers.

New vertices are interpolated along one of three paths. For lat-long datasets the
default is `geodesic`; for projected datasets the only supported mode is `planar`.

`<interval>` or `interval=` Maximum segment length. For `geodesic` and `rhumb`
interpolation this is a ground distance and may include units, for example
`100km`, `500m`, `50mi` or `1000ft` (a value without units is interpreted as
meters). For `planar` interpolation of a lat-long dataset the interval is in
decimal degrees (for example `2` or `0.5deg`); for `planar` interpolation of a
projected dataset it is in the layer's coordinate units.

`geodesic` [lat-long, default] Interpolate along the ellipsoidal shortest path
between two vertices.

`rhumb` [lat-long] Interpolate along a rhumb line (a line of constant compass
bearing).

`planar` [default for projected data] Interpolate along a straight line in the
layer's coordinate space.

### -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-width=`  [polygons] Fill gaps narrower than this width (e.g. `2m`, `0`). Each gap’s width is estimated from its area and perimeter (roughly, how wide a long thin shape would be if straightened out), so slender cracks are filled while more compact holes of similar area, such as small lakes, are more likely to be kept. Defaults to an automatic value based on the median segment length when gap filling is enabled.

`gap-fill-area=`  [polygons, deprecated] Use `gap-width=` instead. Gaps smaller than this area will be filled; larger gaps will be retained as holes in the polygon mosaic. Example values: 2km2 500m2 0.

`sliver-control=` [polygons, deprecated] Use `gap-width=` instead. 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-width=`, `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-detail

Remove intricate, sub-scale detail that `-smooth` cannot generalize cleanly. This is an optional preprocessing step before smoothing: features such as jetties, breakwaters, narrow inlets and fjords are too thin and too convoluted for a low-pass filter to average away, and smoothing them tends to leave kinks or even self-intersections. `-filter-detail` cuts those features out first, so the subsequent `-smooth` sees a cleaner line.

Unlike `-simplify`, it does not thin the whole line — that would starve `-smooth`, which makes a better approximation of the original when it has more vertices to work with. Instead it cuts only where there is genuine convoluted detail and leaves everything else at full resolution. It works in two phases:

1. **Find candidate chords** with a chord-length-gated weighted Visvalingam peel — the same vertex ranking `-simplify`'s default method uses. Vertices are removed least-significant first (smallest angle-weighted triangle area), so a thin feature is peeled from its tip inward and each removal sweeps the smallest possible triangle, finding the shortest chord that would slice the feature off. A vertex is only eligible when the chord that would replace it is no longer than the detail distance, which segments the line into runs that each fit within the detail scale and bounds every candidate chord.

2. **Cut selectively, span by span.** Within each run, find the span whose chord is shortest relative to the original path across it — the most convoluted *tortuosity* — and cut it to its chord when that ratio is above the threshold, then continue. Everything not cut keeps its original vertices, so gentle stretches stay at full detail. Because the decision is per span rather than per run, a small spike is removed whether it sits alone or is embedded in a long gentle stretch; removal depends on how convoluted a feature is, not on how small it is relative to the distance.

Like `-simplify` and `-smooth`, this rewrites shared arc vertices in place and always preserves arc endpoints (topology nodes), so polygon boundaries stay coincident and topology is preserved. It applies to all polygon and polyline layers in a dataset, and any pending simplification is locked in first.

**Options**

`<distance>` or `distance=`  Detail size threshold as a distance (e.g. `1km`), and the longest chord the filter is allowed to create. Convoluted features narrower than this are cut; wider features are left alone. A good starting point is the same distance you pass to `-smooth`. If the unit is omitted, uses meters for unprojected data in spherical mode, otherwise the source units.

`tortuosity=`  How convoluted a span must be before it is cut, measured as original sub-path length divided by chord length (default `2`). Higher values keep more detail (only very convoluted features are removed); values near `1` cut almost every sub-distance span.

`weighting=`  Visvalingam angle-weight coefficient (default `0.7`, matching `-simplify weighted`). Higher values rank sharply-angled (spiky) vertices as less significant; `weighting=0` ranks purely by triangle area.

`planar`  Treat lng,lat coordinates as planar x,y instead of measuring distances and areas on the sphere (the default for unprojected data). Projected data is always measured planar.

Common options: `target=`

**Examples**
```bash
# Strip convoluted coastal detail, then smooth.
mapshaper coast.shp -filter-detail 1km -smooth 1km -o out.shp

# Remove detail finer than 200m before a 1km smooth.
mapshaper coast.shp -filter-detail 200m -smooth 1km -o out.shp

# Keep more detail by only cutting the most convoluted features.
mapshaper coast.shp -filter-detail 1km tortuosity=3 -smooth 1km -o out.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 the target dataset's projection. Bounded and interrupted projections include matching outline paths.

`polygon` Create a polygon enclosing the entire area of the graticule. Useful for creating background or outline shapes for bounded and interrupted projections.

`outline` Create the same boundary as the `polygon` option, as a polyline layer.

`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, hexagonal, rhombus, triangle or cairo 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` `square2` `hex` `hex2` `rhombus` `rhombus2` `triangle` `triangle2` `cairo`. The `square` and `square2` types have different rotations. The `hex` and `hex2` types have different rotations. `rhombus` and `rhombus2` subdivide `hex` and `hex2` cells into rhombi; `triangle` and `triangle2` subdivide them into triangles. `cairo` is the Cairo pentagonal tessellation.

`interval=` The length of one side of a grid cell. Example values: `500m` `2km`.

`cols=` The target number of grid columns. For non-square grids, this option sets a comparable horizontal grid resolution, not an exact column count.

`rows=` The target number of grid rows. For non-square grids, this option sets a comparable vertical grid resolution, not an exact row count.

`cells=` The target number of grid cells. The actual number may be larger because the grid is extended to enclose the target layer.

`cell-scale=` Scale each grid cell from its center. Values must be greater than 0 and less than 2. Values less than 1 create gaps between cells; values greater than 1 create overlaps.

`rotate=` Rotate the grid by a given number of degrees (similar to `-affine rotate=`).

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 both `fields` and `calc` are absent, all source fields are copied (except the source key field when joining with `keys=`). If `calc` is present and `fields` is absent, no fields are copied by default unless assigned by `calc`. Use `fields=*` to copy all source 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 some projections that require additional parameters, Mapshaper can fit parameters automatically from the data extent, for example `crs=utm` selects a UTM zone. You can also 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'`.

`nodata-color=` (raster) Color for output pixels that do not receive source raster content after reprojection. The default is white for image rasters and the source nodata value, when available, for categorical and continuous rasters. Use `transparent` for transparent output.

`background=` (raster) Alias for `nodata-color=`.

`resampling=nearest|bilinear` (raster) Resampling method for raster reprojection. Overrides the default set by `-i raster-type=`. Use `bilinear` for smooth continuous-tone imagery and elevation data, and `nearest` for categorical rasters or exact cell values. Bilinear resampling skips nodata source pixels and renormalizes the remaining weights, so a nodata value is never averaged into a real one.

`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

# Create Dymaxion-projected layers including a graticule and neatline
mapshaper countries.geojson \
-proj dymaxion \
-graticule name=graticule \
-graticule outline name=neatline \
-o target="*" output/

# 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
```

Interrupted Goode Homolosine (`+proj=igh`, `+proj=igh_o`), Interrupted
Mollweide (`+proj=imoll`, `+proj=imoll_o`), rectangular tetrahedral
projections (`+proj=narukawa2022`, `+proj=markley`, `+proj=calm`), Dymaxion
(`+proj=dymaxion`, `+proj=dymaxion2`), and octahedral butterfly projections
(`+proj=butterfly`, `+proj=butterfly2`, `+proj=cahill_keyes`) cannot be used as
source CRSs or represented by generated Shapefile `.prj` files. They can be
used as destinations for vector and raster layers. The `_o` variants are
oceanic layouts and default to `+lon_0=-160`.

`narukawa2022` uses Narukawa's published 2022 mathematical approximation of
the original AuthaGraph modeling process. `markley` and `calm` use L. P. Lee's
conformal tetrahedral face projection in two rectangular aspects. `dymaxion`
uses the Gray-Fuller facet transformation; `dymaxion2` uses gnomonic facets.
`butterfly` and `butterfly2` use the Cahill-Keyes 12-zone facet construction in
a butterfly arrangement inspired by Cahill and Waterman; they differ only in
their default central meridians of 157.5°E and 20°W, respectively.
`cahill_keyes` uses the M-profile and also defaults to 20°W.

### -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 
```

### -repel

Move colliding point symbols apart. The target must be a projected point layer containing symbols from [`-symbols`](#-symbols), from [`-style`](#-style) or from the `radius=` option. All targeted layers are laid out together, so symbols in different layers are moved apart from each other as well.

The command supports symbols with a circular outline: circles, pies, donuts and "ring"-type symbols. Other symbols created with the `-symbols` command, like arrows and polygons, are also supported if a `radius=` option is provided.

The layout happens in pixel space, so the command needs to know the display scale. It takes it from a [`-frame`](#-frame) if the target has one, and otherwise requires a `width=` option. Give the same width to `-repel` and to `-o`, or symbols will be spaced for a differently sized map.

`width=`      Display width of the layer in pixels. Required if the target has no frame.

`max-shift=`  How far a symbol may move, in pixels (default is 20). Accepts a number, a field name or a JS expression, so the limit can vary from symbol to symbol. A symbol with a limit of 0 gets pinned in place. Symbols too crowded to separate within `max-shift=` are left overlapping

`padding=`    Pixels of clearance to leave around each symbol (default is 0). Accepts a field name or an expression. Padding surrounds each symbol, so a pair of symbols ends up with the *sum* of their two paddings between them.

`margin=`     Pixels of clearance to leave between two symbols (default is 0). Accepts a field name or an expression. A margin gives the minimum spacing between two symbols. If two symbols have different margin values, the *greater* of their two margins is used.

`radius=`     Field or expression giving symbol radius in pixels. Use this when the layer has no symbols from `-symbols` or `-style`.

`polygons=`   Layer or file of polygons that symbols must stay inside. Each symbol is confined to the polygon its true position falls in. Symbols outside every polygon are left free to move.

`ticks=`      Number of solver passes (default is 100).

`strength=`   Portion of each overlap resolved per pass, 0-1 (default is 0.4). Higher values clear crowded areas faster but can leave symbols further from their original positions.

Common options: `target=`

```
# Put a dot in each county and keep them inside their respective states
mapshaper counties.geojson \
-proj albersusa \
-dissolve STATE + name=states \
-style fill='#eee' stroke=white \
-target counties \
-points inner + name=dots \
-style r=2 fill=magenta \
-repel width=800 polygons=states \
-o width=800 target=states,dots map.svg
```

### -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](/docs/essentials/command-line.html.md#command-files) or generated on-the-fly from a JS expression.

`<file|expression>`  Either:
- A path to a mapshaper [command file](/docs/essentials/command-line.html.md#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/
```

### -smooth

Smooth the geometry of polygon and polyline features. Unlike `-simplify`, which removes vertices, `-smooth` replaces the original vertices to create fluid, generalized curves. The `<distance>` parameter controls how much smoothing is applied: larger values produce smoother output with less fine detail.

Output vertices are distributed adaptively along the smoothed line: vertices are denser along sharp bends and sparser along straight and gently-curving stretches.

By default, `-smooth` first runs a prefilter to remove intricate details that smoothing cannot generalize cleanly. Use `no-prefilter` to turn this off.

Also by default, corners between straight-line segments are detected and preserved. Use `corner-bias=` to adjust the sensitivity of corner detection or `no-corners` to turn corner preservation off.

**Options**

`<distance>` or `distance=`  Smoothing resolution as a distance (e.g. `2km`): detail finer than this is removed. The value of `distance` is approximately how far the smoothed line can deviate from the original at sharp bends, where displacement is greatest.

`gain=`  Controls a curvature correction that counteracts the tendency of smoothing to flatten bends. The default is `1` (fully corrected, so bends keep their amplitude). `gain=0` disables the correction. Values above `1` over-correct, exaggerating the curvature of bends.

`max-bend-angle=`  Maximum bend (in degrees) between consecutive output segments. The default is `8`. A larger value (e.g. `15`) keeps fewer vertices at the cost of slightly more angular joins; a smaller value keeps more vertices for smoother joins.

`corner-bias=`  Adjusts how readily corners are detected, relative to the baseline (default `0`). Positive values preserve more corners; negative values preserve fewer.

`no-corners`  By default, `-smooth` preserves sharp corners where straight-line segments meet (e.g. artificial borders) instead of rounding them. This option turns corner detection off and smooths the whole line.

`no-prefilter`  By default, `-smooth` runs a detail filter pass before smoothing to remove intricate sub-scale detail — jetties, narrow inlets, spikes — that the low-pass smoother cannot generalize cleanly and that otherwise tends to leave kinks or self-intersections. This option skips that step and smooths the input as-is.

**Examples**
```bash
# Smooth a coastline, removing detail finer than 500 meters.
mapshaper coast.geojson -smooth 1km -o smoothed.geojson

# Smooth county boundaries, rounding the sharp corners of straight-line borders
# instead of preserving them (corner preservation is on by default).
mapshaper counties.shp -smooth 500m no-corners -o smoothed.json
```

### -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.

`icon=`            Point icon shape. Possible values are: circle, square, ring or star. Icons are rendered as SVG symbols and can be combined with labels on the same point layer.

`icon-size=`       Point icon size in pixels. If `icon=` is missing, `icon-size=` creates circle icons.

`icon-color=`      Point icon color. If missing, icons use the `fill=` color, or black if `fill=` is also missing. Ring icons use this color for the stroke.

`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, pies and donuts.

A `pie` symbol is a pie or donut chart, sized by `radius=` and divided up by `values=` and `fills=`. Add `hole=` to make it a donut. Its first wedge starts at the top of the symbol and the rest follow in clockwise order. `rotation=` changes the origin.

`type=`            Basic types: star, polygon, circle, arrow, ring, pie. 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

`hole=`            (pie) Radius of the hole in a donut symbol. The wedges span the space between `hole=` and `radius=`. A negative value is measured inward from the outer radius, so `radius=30 hole=-5` and `radius=30 hole=25` describe the same donut; a negative value is the shorter way to write a band of wedges of a fixed width when `radius=` comes from data. A hole as wide as the symbol is ignored, leaving a plain pie.

`values=`          (pie) Comma-separated list of wedge values. Each item can be a number, a field name or a JS expression. The values are shares of the whole symbol, so their sum is the 100% value. Missing, non-numeric and negative values count as zero, and a symbol whose values are all zero is not drawn.

`fills=`           (pie) Comma-separated list of wedge fill colors, one for each item in `values=`. A wedge whose color is missing, `none`, `transparent` or not a color is left out of the symbol, leaving a gap without shifting the other wedges.

`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 its own page with the recipe, the source data, and a link to open the finished map 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
```

## 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 was added in v0.7.46.)

### 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
```

---

<!-- 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 supports the same editing syntax as the CLI for most workflows once data is loaded.

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 component files of a Shapefile together. `.shp`, `.dbf` and `.prj` are the most essential, others can generally be skipped. 
- 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 (**space bar** to toggle) is the most powerful part of the UI. Most [CLI](/docs/reference.html.md) commands are available here, except file-loading commands like `-i`, `-include` and `-require`, which are disabled in the browser console.

### Keyboard

- **Space** &mdash; open or close the console (only when you're not typing in another text field).
- **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 for a single console command: `clip places` works the same as `-clip places`.
- When entering a sequence of commands, include the leading `-` before each command after the first. The examples in these docs include leading `-` prefixes because that style works in both the web console and the CLI.
- 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, but not by the `mapshaper` CLI program:

- `history` &mdash; print the current session as a single command-line string. Handy for reproducing an interactive workflow as a script.
- `clear` &mdash; clear the console buffer.

### 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

<img class="ui-screenshot" width="234" src="/docs/images/web-app-right-click-menu.png" alt="The right-click menu over a satellite image, showing longitude and latitude, red, green and blue band values, and a color tile beside a hex color">

The right-click menu adapts to what's under the cursor. Clicking a value copies it to the clipboard. Click anywhere else to dismiss the menu.

- **Longitude, latitude** &mdash; the WGS84 coordinates of the click point.
- **X, y** &mdash; the same point in the layer's own coordinates, when the data is projected.
- **Band values** &mdash; on a raster layer, the sample values of the pixel under the cursor, labelled `red, green, blue` (plus `alpha`) for a color image. A pixel with no data is labelled as such. Color images also get a **color** entry, showing a tile of the pixel's color next to its hex value, so it can be copied into a style command.
- **Copy as GeoJSON** &mdash; copies the selected feature(s) 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

<img class="ui-screenshot" width="279" src="/docs/images/web-app-display-options.png" alt="The Display options panel, with checkboxes for detect line intersections and compare with original, and a Basemaps section listing Reference map and Satellite image">

The **Display** button in the header opens the display options panel. Both checkboxes are remembered between sessions.

- **Detect line intersections** &mdash; highlights self-intersections in red as you simplify or edit, with a running count at the top of the map. This can reveal topology problems in your source data and line intersections caused by simplification. In Simplify mode a **repair** link appears next to the count, which tries to fix intersections caused by simplifying.
- **Compare with original** &mdash; draws the shapes as they were before your last edit, as a magenta outline on top of the current ones. It applies to the `-buffer`, `-smooth` and `-simplify` commands and to the Simplify slider, so you can see exactly what an edit changed without toggling layers on and off. The overlay clears when you make an unrelated edit or turn the checkbox off.

### Basemaps

Turning on a basemap draws map tiles behind your data. Click the eye icon next to **Reference map** or **Satellite image** to switch one on; the same two are also available as thumbnail buttons in the top-right corner of the map.

Basemaps are in the Mercator projection, so switching one on displays your data in Mercator too. If your data can't be shown that way &mdash; it has no geographic coordinates, or its projection is unknown &mdash; the panel says so instead of listing the basemaps.

**Add** adds your own basemap, either from a Mapbox style URL (`mapbox://...`, with an optional access key) or from a raster tile URL template, with a checkbox for TMS tiles that count their y-index from the bottom. Basemaps you add are kept in the browser and can be removed from the list later.

Basemap tiles are fetched over the network. Everything else in Mapshaper stays on your machine &mdash; see [Privacy](#privacy) below.

## History, undo and snapshots

<img class="ui-screenshot" width="237" src="/docs/images/web-app-history-menu.png" alt="The History menu, with an enable undo checkbox, a line reading restore data stored on-disk: 0 KB, and links to clear undo history, view command history and create snapshot">

The **History** button in the header covers three things: undo, the command history, and snapshots.

### Undo and redo

Undo is **on by default**. Clearing **enable undo** turns it off, which is worth doing if you're working with data large enough that storing the data needed to reverse each step is a burden. The setting is remembered between sessions, and a change applies from that point on rather than retroactively.

- **Ctrl+Z** (**⌘Z** on a Mac) undoes and **Shift+Ctrl+Z** (**⇧⌘Z**) redoes. The same buttons appear in a small toolbar at the bottom of the map whenever there's anything to undo. Keyboard shortcuts are ignored while you're typing in a text field.
- The first import of a session isn't undoable, and neither is restoring a snapshot. Both are treated as starting points rather than edits.
- Mapshaper keeps the last ten steps, dropping older ones as you work &mdash; though while you're inside an editing mode, every change you've made since entering it can be undone, however many there are. Editing very large datasets can push older steps out sooner, and a step too big to store isn't undoable at all: the command still runs, and a warning appears in the messages panel.
- The data needed to reverse a step is stored in the browser. **Restore data stored on-disk** shows how much space that is currently taking, and **clear undo history** discards it.

### Command history

**View command history** opens the console and prints the sequence of commands that produced the current state, as one command line you can paste into a terminal or save as a [command file](/docs/essentials/command-line.html.md#command-files). It's the same as typing `history` in the console. Undoing a step removes it from this list, so the history always describes what's on screen now.

### Snapshots

Snapshots save the state of a session so you can return to it. They also record the command history behind them, so re-opening a snapshot brings back its history too.

**Create snapshot** saves to in-browser storage. Each snapshot appears in a list under the button, with three links:

- **restore** &mdash; go back to that state. This replaces the loaded layers and clears the undo history.
- **export** &mdash; download the snapshot as an `.msx` file.
- **remove** &mdash; delete it from the browser.

In-browser snapshots are meant to be temporary; Mapshaper tries to clean them up when the tab closes or the page reloads. For anything you want to keep, use **export**, or choose **Snapshot file** as the format in the Export panel.

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, optional AI assistant requests when an installation has enabled them, and analytics for `mapshaper.org` page loads. See the [privacy policy](/privacy.html) for details.

---

<!-- https://mapshaper.org/docs/examples/basics.html -->

# Basics

Short Mapshaper recipes for common tasks. The examples are written for the [web app's](/docs/essentials/web-app.html.md) Console: load your data first, then run the commands shown here. Filenames, layer names and field names are illustrative &mdash; substitute your own.

These examples keep the leading `-` on command names because that style works in both the web console and the CLI, and because command sequences need it after the first command. To run most examples from the command line, add `mapshaper input-file` before the command sequence and `-o output-file` after it.

> 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

```text
-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. In the CLI, add `save-to=info.json` to capture it as JSON.

### Run a command on another layer

```text
-info target=counties
```

Commands run on the currently selected layer by default. Use `target=` to name a different layer, or `target=*` to run a command on every layer.

### Count features grouped by a field

```text
-drop geometry \
  -dissolve STATE calc='N = count(), POP = sum(POP)'
```

A dissolve with a `calc=` clause is an idiomatic way to aggregate data values. Here, `-drop geometry` turns the result into a table, ready to export as CSV.

## Filtering and selecting

### Keep features matching a condition

```text
-filter 'CONTINENT == "Asia" && POP > 1e7'
```

`-filter` keeps features for which the expression returns `true`.

### Keep the original layer while filtering

```text
-filter 'POP > 100000' + name=large_places
```

The `+` flag saves the result as a new layer instead of replacing the active layer. Use `name=` to give the new layer a useful name.

### Keep features inside a bounding box

```text
-clip bbox=-10,35,30,60
```

The four bbox numbers are `xmin,ymin,xmax,ymax` in the layer's own coordinates.

### Keep the top N features by some attribute

```text
-sort POP descending \
  -filter 'this.id < 50'
```

`-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

```text
-filter remove-empty
```

The `remove-empty` flag drops features with missing or empty geometry.

## Editing attributes

### Add derived fields

```text
-each 'STATE_FIPS = COUNTY_FIPS.substr(0, 2),
       AREA_KM2 = round(this.area / 1e6, 1)'
```

`-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

```text
-rename-fields POPULATION=POP,MEDIAN_INCOME=MEDIAN_INC \
  -filter-fields STATE,COUNTY,POPULATION,MEDIAN_INCOME
```

`-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

```text
string-fields=FIPS,STATEFIPS
```

By default Mapshaper parses any numeric-looking CSV column as a number, which silently drops leading zeros from FIPS, ZIP and similar identifier columns. In the web app, enter `string-fields=FIPS,STATEFIPS` in the **Advanced options** field when importing the CSV. In the CLI, pass it with `-i`: `mapshaper -i counties.csv string-fields=FIPS,STATEFIPS`.

## Joining data

### Join a CSV to a Shapefile by key

```text
-join demographics keys=STATE_FIPS,FIPS
```

Load both the target layer and the CSV before running the join. `keys=A,B` means "match the target's `A` field to the source's `B` field". If the source key is a FIPS, ZIP or other code with leading zeros, import the CSV with `string-fields=FIPS` 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

```text
-join precinct_polygons
```

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

```text
-join crimes calc='N = count(), AVG_SEVERITY = mean(SEVERITY)'
```

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

```text
-simplify 5% keep-shapes \
  -clean
```

`-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; choose TopoJSON in the Export dialog or use `-o format=topojson provinces.topojson` in the CLI.

### Simplify multiple files with shared topology

```text
-simplify 10%
```

When importing the files in the web app, add `combine-files` in the **Advanced options** field. This 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.

### Repair topology errors

```text
-clean
```

`-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

```text
-dissolve STATE
```

`-dissolve` merges adjacent polygons that share a value in the named field.

### Dissolve while computing per-group stats

```text
-dissolve STATE calc='N = count(),
                      POP = sum(POP),
                      MEDIAN_INC = median(MEDIAN_INC)'
```

`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

```text
-dissolve STATE_FIPS weight=POPULATION
```

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

```text
-erase lakes
```

`-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

```text
-innerlines
```

`-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

```text
-grid type=hex interval=10km name=hex
```

```text
-grid type=hex cols=40 name=hex
```

`-grid` builds a regular grid (`square`, `square2`, `hex`, `hex2`, `rhombus`, `rhombus2`, `triangle`, `triangle2`, `cairo`) covering the target's bounding box. Use `interval=` to set the cell side length directly, or `cols=`, `rows=` or `cells=` to set an approximate grid resolution. Use `cell-scale=` to shrink or expand cells from their centers. Use `rotate=` to rotate the grid around the target bbox center. Pair it with a spatial join to style the grid cells using interpolated count data (`-join interpolate=POPULATION`).

### Merge compatible layers

```text
-merge-layers target=OR,WA,CA,AK name=pacific_states
```

`-merge-layers` combines layers with compatible geometry types into one layer. Use `force` if the layers have different attribute fields and you want Mapshaper to fill missing values.

## Reprojection

### Project to a named CRS

```text
-proj robinson
```

`-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

```text
-proj match=basemap
```

`match=` reads the CRS of another layer or `.prj` 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

```text
-classify save-as=fill quantile classes=6 color-scheme=Oranges
```

`-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`. In the CLI, run `mapshaper -colors` to list the built-in color schemes.

### Add SVG styling for export

```text
-style stroke="#444" stroke-width=0.5 fill=none \
  -style where='RANK == 0' stroke="#000" stroke-width=1.5
```

`-style` writes SVG presentation attributes onto each feature; the `where=` form lets you set them conditionally. Export as SVG when you're ready to use the styled map in a print or web layout.

## Output and conversion

### Convert Shapefile &harr; GeoJSON

Use the Export button and choose GeoJSON or Shapefile.

In the CLI, the output format is inferred from the file extension:

```bash
mapshaper input.shp -o input.geojson
mapshaper input.geojson -o input.shp
```

Use `format=` to force a format (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

Use the Export button and choose 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. This is mainly a CLI workflow.

### 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. This is mainly a CLI workflow.

## 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/essentials/command-line.html.md#command-files). This is a CLI workflow; support for running command files in the web app is planned for a future release.

### 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. Add a stroke to borders between two states
6. 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.
* Applying a stroke to interior lines using `-innerlines` (and not to exterior lines) creates a more accurate and crisper-looking coastline.

### Assets

<!-- mapshaper:assets -->

---

<!-- https://mapshaper.org/docs/examples/ny-state.html -->

# New York State map

Difficulty: moderate

<!-- mapshaper:image -->

### Steps

1. Load states/provinces (source: Natural Earth)
2. Make a layer containing just N.Y. State
3. Project to Lambert Confirmal Conic
4. Create a rectangular frame around N.Y.
5. Clip the states to the frame
6. Derive label points from the states/provinces
7. Extract lines from the states/provinces
8. Load roads (source: Natural Earth)
9. Project and clip
10. Divide the roads at the N.Y. border (for styling)
11. Style all the layers
12. Export as SVG

### Code

<!-- mapshaper:code -->

### Notes

* `-proj lcc densify`: Lambert Conformal Conic requires additional parameters. When just `lcc` is given, Mapshaper calculates reasonable parameters using the bounding box of the targeted layer(s). The `densify` option adds additional vertices when the projection needs to create curved lines from long straight-line segments.
* `-each 'labelled = this.area > 1e10'`: This command creates a variable named `labelled` which is false if the area of a polygon in the states layer is less than 1e10 square meters (10,000 square kilometers).
* `-divide NY`: this command uses the NY polygon (the N.Y. State border) to divide roads at the polygon boundary and adds the NY layer's attribute data to the roads that fall inside the polygon.

### Assets

<!-- mapshaper:assets -->

---

<!-- 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 method options in the web UI's Simplification menu or flags to `-simplify` on the command line. 

- **`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 introduce visible spikes at high simplification.
- **`Visvalingam / effective area`**. Iteratively removes the point that forms the triangle of smallest area with its two neighbors.
- **`Visvalingam / weighted area`**. A variation on Visvalingam's algorithm 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 Mapshaper's default method because it produces generalizations that look good enough for most web maps, even if they fall short of true cartographic quality. But be aware that none of these methods can approach the quality that a cartographer achieves when generalizing linework by hand. For higher-quality generalization than `-simplify` can provide, try Mapshaper's new `-smooth` command.

If you are primarily interested in removing as many vertices as possible without visible changes to the shape of the lines, you may find that Douglas-Peucker combined with an appropriate `interval=` or `resolution=` parameter gives the best results.

**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. These figures illustrate the different ways each method removes detail. In a finished map, you would apply far less simplification than this — simplification artifacts generally should not be discernible to the naked eye.

![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, 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. Mapshaper estimates the display size using the full extent of your data, so 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 islands.geojson -simplify 5% keep-shapes -o islands-simplified.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. Boundaries shared between the input layers — for example, aligned state and county polygon borders — are simplified identically across all layers, but only if their vertices are perfectly aligned to begin with. Since source layers are rarely aligned this precisely, a more reliable approach is to import the smallest available level of geography — counties, in the example below — and derive higher levels using the `-dissolve` command.

```bash
mapshaper -i states.shp counties.shp combine-files \
  -simplify 10% \
  -o out/
```

or

```bash
mapshaper -i counties.shp \
  -dissolve STATE + name=states \
  -simplify 10% \
  -o target=counties,states 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/smoothing.html -->

# Smoothing

`-smooth` generalizes polygon and polyline geometry by replacing the original vertices with smooth curves. Unlike [`-simplify`](/docs/guides/simplification.html.md), which thins existing vertices, `-smooth` recomputes the line's shape. It also filters out small intricate details and preserves sharp corners, such as surveyed borders.

```bash
mapshaper coastline.shp -smooth 5km -o smoothed.shp
```

The `<distance>` parameter sets the smoothing resolution: detail finer than this scale is removed.

## Usage tip

For best geographical fidelity, apply `-smooth` to unsimplified linework. Smoothing can also be applied to simplified paths, but low-resolution inputs give the smoother less information to work with.

Smoothed low-resolution contour lines:

![image](/docs/images/smooth-lowres-contours.png)


## Prefiltering intricate detail

When line smoothing is applied to small, intricate features — jetties, narrow inlets, docks, spikes — the output can include kinks or self-intersections. To prevent this, `-smooth` first removes detail below the smoothing scale.

Use `no-prefilter` to skip prefiltering and smooth the input as-is.

Fig. 1: with the prefilter, the small basin, dock outline, and other fine detail are dropped before smoothing.

![image](/docs/images/smooth-prefilter-on.png)

Fig. 2: without the prefilter, the same details pull the smoothed line into unwanted bends and loops.

![image](/docs/images/smooth-prefilter-off.png)

## Corner preservation

By default, `-smooth` protects long straight sections from being reshaped by smoothing.

Here, the straight lines are preserved and the riverine section is smoothed:

![image](/docs/images/smooth-corners.png)

Use `corner-bias=` to adjust the sensitivity of corner detection, or `no-corners` to smooth the entire line uniformly.

```bash
# Round off corners instead of preserving them.
mapshaper borders.shp -smooth 5km no-corners -o smoothed.shp
```

## Adaptive vertex density

Output vertices are placed adaptively: more on tight bends, fewer on straight or gently curving runs.

The dots below mark output vertices along a smoothed line.

![image](/docs/images/smooth-vertex-density.png)

The `max-bend-angle=` option (default `8` degrees) controls output density. A larger value uses fewer vertices; a smaller value uses more.

## Technical notes

- The `-smooth` command uses a Gaussian smoothing kernel.
- Curve compensation reduces the shrinkage that smoothing causes around bends. The `gain=` option controls the strength of this correction.
- Lat-long data is smoothed on a sphere: coordinates are converted to 3D geocentric coordinates, distances are measured along great circles, and the result is converted back to longitude and latitude.

See the [`-smooth` reference](/docs/reference.html.md#-smooth) for the full set of options.

---

<!-- https://mapshaper.org/docs/guides/buffering.html -->

# Buffering

`-buffer` creates buffer polygons around point, polyline or polygon features. When the input data is in longitude-latitude coordinates, Mapshaper creates geodesic buffers, so distances such as `500m` or `2km` are measured on the ground. Projected data is buffered in its planar coordinate system by default; add `geodesic` to use ground distances instead.

```bash
mapshaper rivers.shp -buffer 2km -o river_buffers.shp
```

Pink: source line. Black: buffer polygon.

![image](/docs/images/buffer-plain.png)

## Filling gaps

The `fill-gaps` option fills enclosed holes and narrow-mouthed inlets without growing the outer boundary. This is useful for filling rivers, bays, channels and other gaps inside a polygon layer while leaving the open coastline in place.

```bash
mapshaper states.shp -buffer 5km fill-gaps -o output.shp
```

The example below fills a long river inlet and some small gaps along the coastline while preserving the main outer boundary.

![image](/docs/images/buffer-fill-gaps.png)

Use `max-widening=` with `fill-gaps` to limit how wide a gap may be before it is left open.

By default `fill-gaps` leaves small isolated islands separate rather than bridging them to a neighboring landmass across a narrow channel. Add `merge-islands` to bridge them as well.

## Topological buffers

For polygon layers, the `topological` option buffers only unshared polygon boundaries, such as coastlines and holes. Shared boundaries between adjacent polygons are not buffered, and overlapping buffer areas are split between features by proximity.

```bash
mapshaper countries.shp -buffer 25km topological -o coast_buffers.shp
```

In the example below, buffers are created along coastlines, while internal borders are left unchanged.

![image](/docs/images/buffer-topological.png)

## Notes and limitations

- Geodesic buffers that cross the antimeridian are split and wrapped automatically. This support is still experimental.
- Geodesic buffer size is calculated using a spherical, not ellipsoidal, earth model, so it may not be accurate enough for GIS analysis.
- Polygon buffers that reach a pole use experimental polar handling. Geodesic line buffers cannot extend to the poles. 

See the [`-buffer` reference](/docs/reference.html.md#-buffer) for the full set of options.

---

<!-- https://mapshaper.org/docs/guides/styles-and-symbols.html -->

# Styles and symbols

Mapshaper can attach SVG styling properties to features with [`-style`](/docs/reference.html.md#-style), and it can assign colors or other values from data with [`-classify`](/docs/reference.html.md#-classify). The [`-symbols`](/docs/reference.html.md#-symbols) command creates arrows and other symbols. These commands are useful when you want to create a styled map that can be exported as an SVG file.

The examples below are written for the web app's Console. Load your data first, then run the commands. The same command sequences also work on the CLI when you add `mapshaper input-file` before them and `-o output.svg` after them.

## The `-style` command

`-style` writes common SVG presentation attributes to each feature. Line layers can be styled with `stroke=`, `stroke-width=`, `stroke-opacity=`, `stroke-dasharray=` and `opacity=`. Polygon layers add `fill=` and `fill-opacity=` options.

Style values can be literal values, like `stroke="#777"`, or JavaScript expressions, like `r='Math.sqrt(POP) / 100'`. Use `where=` to override the styles of a selected group of features.

```text
-style fill="#eee" stroke="#999" \
-style where='TYPE == "primary"' stroke="#555" stroke-width=1.5
```

### Making circles

To make circles from a point layer, add a `r=` (for radius) property along with fill and stroke styles. For scaled circles, use a JavaScript expression for `r=`. Use `Math.sqrt()` in your expression so the area of the circle is proportional to your data values.

```text
-style r='Math.sqrt(POP) / 250' \
  fill='rgba(227, 74, 51, 0.65)' \
  stroke='rgba(0, 0, 0, 0.15)'
```

### Making point icons

Use `icon=` with `icon-size=` to add circle, square, ring or star icons to a point layer. Icons use `icon-color=` when it is provided. Otherwise they use the layer's `fill=` color, falling back to black.

```text
-style icon=star icon-size=10 fill="#333"
```

## Styling data layers with the `-classify` command

### Classed and unclassed color gradients

`-classify` can assign colors or other values based on a data field. For numeric data, mapshaper can automatically classify a data field using `method=quantile|equal-interval|nice|hybrid`.

This example applies a six-class orange color ramp to a `RATE` field. By default, the colors are assigned to the `fill` field (the `save-as=` option changes this).

```text
-classify RATE method=quantile classes=6 color-scheme=Oranges
```

Quantiles put roughly the same number of features in each class. Equal intervals use evenly spaced numeric ranges.

```text
-classify RATE method=equal-interval classes=5 color-scheme=Blues
```

Mapshaper's `nice` method is similar to `equal-interval` but finds rounded class breaks that look better in a map legend.

The `hybrid` method uses equal-interval breaks in the interior of the class range paired with variable-size outer breaks to handle data outliers.

Use the `breaks=` option when you want to define the class breaks yourself.

```text
-classify RATE breaks=10,25,50,100 \
  colors="#f7fbff,#c6dbef,#6baed6,#2171b5,#08306b"
```

For continuous, unclassed color ramps, add `continuous`.

```text
-classify RATE continuous color-scheme=Viridis
```

### Styling categorical data

Categorical data uses named groups rather than numeric ranges: party, land use, road class, region, status and similar fields. Use `categories=` and `colors=` to map known values to colors.

Run `-colors` in the web console, or `mapshaper -colors` on the CLI, to see the names of Mapshaper's built-in categorical color schemes.

```text
-classify PARTY save-as=fill \
  categories=Democratic,Republican,Independent \
  colors="#2b8cbe,#de2d26,#756bb1" \
  other="#ddd"
```

The `other=` value is used for records whose category is missing from the list. This is useful when a field has miscellaneous or unexpected values to which you want to apply a fallback color instead of the missing-data color.

## Making arrows with the `-symbols` command

Use [`-symbols`](/docs/reference.html.md#-symbols) to turn a point layer into arrows or other symbol shapes. Arrow options accept expressions, so you can drive the length and direction of each arrow from data fields.

For a point layer with `SPEED` and `BEARING` fields, this example scales arrow length from `SPEED` and points each arrow using `BEARING`.

```text
-symbols type=arrow \
  length='Math.max(8, Math.min(60, SPEED * 2))' \
  direction=BEARING \
  fill="rgba(49, 130, 189, 0.65)" \
  stem-width=3 head-width=12 anchor=middle
```

`direction=` is measured in degrees off vertical: `0` points up and `-90` points left. If your data stores compass bearings clockwise from north, those values can usually be used directly as `direction=` values.

For a lighter vector-field style, use stick arrows. This draws arrow strokes instead of filled polygons.

```text
-symbols type=arrow arrow-style=stick \
  length='Math.max(6, Math.min(45, WIND_SPEED * 1.5))' \
  direction=WIND_DIR \
  stroke="#2b8cbe" stroke-width=1.2 \
  head-length=6 anchor=middle
```

## Making pie and donut charts with the `-symbols` command

`type=pie` divides a symbol into wedges. `values=` lists the size of each wedge and `fills=` lists its color. The values are shares of the whole symbol, so their sum is the 100% value — there's no need to convert them to percentages first.

This example makes a pie chart of three vote fields, sized by `radius=`.

```text
-symbols type=pie \
  values=DEM,REP,OTHER \
  fills="#2b8cbe,#de2d26,#bbb" \
  radius='Math.sqrt(TOTAL_VOTES) / 8' \
  stroke="#fff" stroke-width=0.5
```

Wedges start at the top of the symbol and follow in clockwise order. Add `rotation=` to start somewhere else.

Adding `hole=<radius>` makes a donut instead, with the wedges spanning the space between the hole and the outer radius. A negative `hole=` value is measured inward from the outer radius, so `hole=-5` gives a band of wedges 5 pixels wide whatever the symbol's radius.

## Making labels with `-style`

Labels are created from point layers by setting `label-text=`. The label text can be a field name or an expression. Label styling uses familiar CSS-like properties such as `font-size=`, `font-family=` and `font-weight=`. The SVG properties `text-anchor=`, `dx=` and `dy=` place the label relative to its anchor point.

Labels are centered horizontally by default (equivalent to setting `text-anchor=middle`). To center labels vertically, nudge them down a bit by setting a small `dy=` value. This is required because SVG aligns text vertically to the font baseline.

```text
-style label-text=NAME font-size=13 dy=4
```

Use `dx=` together with `text-anchor=start` or `text-anchor=end` to place labels to the left or right of their anchor points. Typically you would combine this with a dot over the anchor point. You can add the dots to the label layer by adding an `r=` property.

```text
-style label-text=NAME dx=6 dy=3 font-size=12 text-anchor=start r=2
```

For labeled point icons, use `icon=` on the same layer. In this example the icon and label both use `fill="#555"`.

```text
-style label-text=NAME dx=8 dy=3 text-anchor=start \
  icon=circle icon-size=6 fill="#555"
```

You can combine `where=` with multiple `-style` commands to emphasize important labels.

```text
-style label-text=NAME font-size=12 fill="#555" dy=3 \
  -style where='POP > 1000000' font-size=15 dy=4 font-weight=bold
```

## Exporting styled maps

Style fields are most useful when exporting SVG:

```bash
mapshaper input.geojson \
  -classify RATE save-as=fill quantile classes=6 color-scheme=Oranges \
  -style stroke="#fff" stroke-width=0.4 \
  -o map.svg
```

In the web app, run the styling commands in the Console, then open **Export** and choose SVG.

## Tips

- Use transparency (`fill=rgba(...)` or `fill-opacity=...`) when dense symbols overlap.
- Prefer `Math.sqrt()` scaling for proportional circles.
- Use `-sort r descending` to place larger circles behind smaller circles.
- Use `where=` for exceptions and emphasis instead of splitting off highlighted shapes onto a separate layer.
- Run `-style clear` if earlier styling is confusing the current result.
- See [`-style`](/docs/reference.html.md#-style), [`-classify`](/docs/reference.html.md#-classify), [`-colors`](/docs/reference.html.md#-colors) and [JavaScript expressions](/docs/guides/expressions.html.md) for the full syntax.

---

<!-- https://mapshaper.org/docs/guides/expressions.html -->

# JavaScript expressions

Many Mapshaper commands take a **JS expression** as an argument or option. Expressions let you filter features, derive new fields, calculate summary statistics, control style attributes and much more. The expression language is standard JavaScript, and the variables available inside expressions — field names, `this`, `d`, helper functions — are consistent across most commands.

```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, 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.

## What is a JavaScript expression?

An **expression** is any fragment of JavaScript code that produces a value. The key distinction is between an expression (which *evaluates to something*) and a statement (which *does something but produces no value*). Mapshaper always expects an expression — a piece of code that can be evaluated and whose result is used by the command.

The simplest expressions are literals:

```js
true          // the boolean value true
42            // the number 42
"hello"       // the string "hello"
```

A field name from the attribute table is also an expression — it evaluates to that field's value for the current feature:

```js
POPULATION    // the value of the POPULATION field
```

Arithmetic, comparisons and string operations are expressions:

```js
POPULATION / AREA        // division of two fields
NAME.toUpperCase()       // calling a string method
Math.abs(CHANGE)         // calling a built-in math function
POPULATION > 1000000     // comparison, evaluates to true or false
```

A **ternary expression** (`condition ? value_if_true : value_if_false`) is a compact conditional that evaluates to one of two values:

```js
TYPE == 'inner' ? 'blue' : 'pink'
```

Multiple expressions separated by commas evaluate left to right; the last value is returned. This is how `-each` handles multiple field assignments in one call:

```js
AREA_KM2 = this.area / 1e6, POP_DENSITY = POPULATION / AREA_KM2
```

**What is not an expression.** Statements and control-flow blocks are not expressions and cannot be used directly as a Mapshaper expression argument:

```js
// ✗ if statement — not an expression
if (POPULATION > 1000000) { LARGE = true }

// ✗ try/catch block — not an expression
try { result = riskyCalc() } catch(e) { result = 0 }

// ✗ for loop — not an expression
for (var i = 0; i < 10; i++) { ... }
```

If you need logic more complex than a ternary, define a helper function in an external file and load it with [`-include`](/docs/reference.html.md#-include):

```bash
mapshaper data.geojson \
  -include helpers.js \
  -each 'SIZE = classify(POPULATION)' \
  -o out.geojson
```

## Quoting expressions

An expression containing spaces or special characters needs to be quoted, otherwise mapshaper will interpret the parts as separate arguments and produce a syntax error. Single quotes are the most common style:

```bash
mapshaper data.geojson -filter 'POPULATION > 1000000' -o out.geojson
```

If the expression itself contains single quotes — for example, a string literal — wrap it in double quotes instead, and vice versa:

```bash
mapshaper data.geojson -filter "TYPE == 'inner'" -o out.geojson
```

Backtick quoting is also available as a third option when both single and double quotes appear in the expression.

Backslash escapes (`\"`, `\'`) can also resolve quoting conflicts, but when running commands in a shell the shell processes them before passing the expression to mapshaper, which can strip the backslashes and produce a JS syntax error. This gets particularly confusing inside shell scripts and Makefiles, where an additional level of escaping may be needed. When possible, switching the outer quote style is simpler than relying on backslash escapes.

## 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 *reduction functions* — functions that convert data from a group of features or an entire layer to a single value. Each reduction function takes a per-feature expression and reduces it 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/essentials/command-line.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 descending \
  -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)
- [`-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; many examples that use expressions

---

<!-- https://mapshaper.org/docs/guides/projections.html -->

# Map 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.

Run `mapshaper -projections` (or just `projections` in the web app console) to print the full list of available projections.

**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 codes** are sequences of `+key=value` parameters used by the [PROJ](https://proj.org/) projection system and supported by Mapshaper. You will often see PROJ codes from other sources with a large number of parameters containing default values, such as `+units=m` and `+x_0=0 +y_0=0` &mdash; these parameters can safely be omitted.

Examples of PROJ codes for some common projections (with default values omitted)
```bash
# Lambert Conformal Conic
+proj=lcc +lat_1=33 +lat_2=45 +lat_0=39 +lon_0=-96
# Albers Equal Area Conic
+proj=aea +lat_1=29.5 +lat_2=45.5 +lat_0=23 +lon_0=-96
# Transverse Mercator
+proj=tmerc +lon_0=-75 +lat_0=0
# Orthographic
+proj=ortho +lat_0=45 +lon_0=-100
# Robinson
+proj=robin
# Mollweide
+proj=moll
# Mercator
+proj=merc
# Web Mercator
+proj=merc +a=6378137 +b=6378137
```

Example of using a PROJ code with the `-proj` command

```bash
mapshaper unprojected.shp \
-proj +proj=lcc +lat_1=33 +lat_2=45 +lat_0=39 +lon_0=-96 \
-o projected.shp
```

**Bare projection name**

You can also use a bare PROJ projection name (without `+proj=`) as shorthand:

```bash
mapshaper world.shp -proj robin -o
```

**EPSG and ESRI codes** are numeric CRS identifiers from the [EPSG registry](https://epsg.io/) and from ESRI. Mapshaper supports many of them.

```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. 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) |



## 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.

For **Universal Transverse Mercator** (`utm`), it calculates the UTM zone from the center longitude of the bounding box and adds `+south` when the center latitude is in the southern hemisphere.

```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

# Equivalent — Mapshaper fills in zone and hemisphere
mapshaper region.geojson -proj utm -o region_utm.geojson
```

When Mapshaper auto-fits parameters, it prints the expanded PROJ string so you can see exactly what was applied. An example message: `Converted "lcc" to "+proj=lcc +lon_0=-95.5 +lat_1=30.17 +lat_2=44.83"`. You can copy this PROJ 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 applies Albers Equal Area Conic to the contiguous 48 states, then places Alaska (scaled down) and Hawaii as insets in the lower-left corner of the map.

![United States in the albersusa composite projection, with Alaska and Hawaii as insets below the southwestern states](/docs/images/albersusa-projection.jpg)

```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.

## Interrupted and polyhedral world projections

### Goode Homolosine and Mollweide projections

- `igh` — Interrupted Goode Homolosine, land emphasis
- `imoll` — Interrupted Mollweide, land emphasis
- `igh_o` — Interrupted Goode Homolosine, ocean emphasis
- `imoll_o` — Interrupted Mollweide, ocean emphasis

![Interrupted Mollweide world projection](/docs/images/interrupted-mollweide.jpg)

The ocean-emphasis projections default to `+lon_0=-160`; an explicit
`+lon_0=` overrides this default.

```bash
# Project world polygons using Goode Homolosine; add a graticule
mapshaper world.geojson \
  -proj +proj=igh \
  -o world-igh.geojson \
  -graticule \
  -o graticule-igh.geojson

# Create an ocean-emphasis Interrupted Mollweide layer with a neatline
mapshaper world.geojson \
  -proj +proj=imoll_o \
  -o world-imoll-o.fgb \
  -graticule outline \
  -o neatline-imoll-o.fgb
```

### Dymaxion projections

Mapshaper includes two versions of Buckminster Fuller's Airocean (Dymaxion)
world map. Both divide the globe into twenty triangles and arrange them on a
flat map according to Fuller's design:

![Dymaxion (Airocean) world projection](/docs/images/dymaxion-projection.jpg)

- `dymaxion` — a version using the Gray-Fuller transform for projecting each polyhedral face, which balances shape and area
  distortion
- `dymaxion2` — a version using the gnomonic projection to project each face

```bash
mapshaper world.geojson \
  -proj +proj=dymaxion densify \
  -o world-dymaxion.geojson \
  -graticule outline \
  -o neatline-dymaxion.geojson
```

### Butterfly and Cahill-Keyes projections

These projections divide the globe into eight octahedral faces. The first two arrange
the triangular faces in a butterfly layout similar to the butterfly maps of Bernard Cahill and Steve Watterman, but use Gene Keyes's facet projection; the third (`cahill_keyes`) uses Gene Keyes's M-shaped arrangement and facet projection.

![Butterfly projection, Pacific and Atlantic aspects](/docs/images/butterfly-projection.jpg)

- `butterfly` — centered on the Pacific, with a default central meridian of
  157.5°E
- `butterfly2` — centered on the Atlantic, with a default central meridian of
  20°W
- `cahill_keyes` — Cahill-Keyes M-shaped profile, with a
  default central meridian of 20°W

```bash
mapshaper world.geojson \
  -proj +proj=butterfly densify \
  -o world-butterfly.geojson \
  -graticule outline \
  -o neatline-butterfly.geojson
```

### Tetrahedral projections

These projections divide the globe into four triangles and arrange them to
form a rectangular world map:

![CALM tetrahedral world projection, with a graticule and neatline](/docs/images/tetrahedral-projection.jpg)

- `narukawa2022` — Hajime Narukawa's published 2022 formulas approximating the original AuthaGraph map
- `calm` — Farhan Adrian's adaptation of L. P. Lee's conformal tetrahedral projection designed to match the AuthaGraph layout.
- `markley` — F. Landis Markley's adaptation of Lee's projection

```bash
mapshaper world.geojson \
  -proj +proj=markley densify \
  -o world-markley.geojson \
  -graticule outline \
  -o neatline-markley.geojson
```

## 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.
- Interrupted and polyhedral projections (`igh`, `imoll`, `igh_o`, `imoll_o`, `narukawa2022`, `markley`, `calm`, `dymaxion`, `dymaxion2`, `butterfly`, `butterfly2`, `cahill_keyes`) can be used as destinations for vector and raster layers, but cannot be used as source CRSs.
- 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.

---

<!-- 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.

## Cleaning

The [`-clean`](/docs/reference.html.md#-clean) command is the general-purpose repair tool for topology errors. It snaps near-duplicate vertices, removes small gaps and overlaps between adjacent polygons, and fixes self-intersecting lines:

```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  (the leading `-` is optional, e.g. just `clean gap-fill-area=100`).

## Snapping

For datasets where adjacent polygons have vertices that should be identical but are slightly offset — typically due to floating-point rounding in the source tool — you can ask Mapshaper to snap those 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. To set an explicit snapping distance, use `snap-interval=`:

```bash
mapshaper countries.shp snap-interval=0.0001 -o cleaned.shp
```

Snapping is only effective when the misalignment is limited to nearly-identical coordinate pairs. Most real-world datasets with topology errors have more complex problems — gaps, overlaps, or self-intersections that snapping alone cannot fix. There is no easy way to know in advance whether snapping is sufficient without inspecting the result, so `-clean` is usually the better starting point.

## 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. Running `-clean` (or importing with `snap` if the misalignments are small and consistent) usually resolves these.
- **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/geojson-for-web-maps.html -->

# Preparing data for D3 and web maps

GeoJSON is the common exchange format for web maps, but different tools make different assumptions about coordinates, polygon winding, and projection. This page covers the fixes for the most common problems when moving data from Mapshaper into D3, Leaflet, MapLibre, Mapbox GL, Observable notebooks, and similar JavaScript workflows.

## Quick recipes

### Export GeoJSON for Leaflet, MapLibre, Mapbox GL, and most web map APIs

Most web map libraries expect GeoJSON coordinates in WGS84 longitude/latitude, even when the map is displayed in Web Mercator. If your source file has coordinates other than WGS84, reproject to WGS84 before exporting:

```bash
mapshaper input.shp -proj wgs84 -o output.geojson
```

If you're unsure what CRS your data file is using, you can look it up using mapshaper's `-info` command. It will give you the CRS in proj4 format, which is used by Mapshaper's `-proj` command.

```bash
mapshaper input.shp -info
```

If your input is a (non-standard) GeoJSON or TopoJSON file with projected coordinates, you'll have to tell Mapshaper what CRS the coordinates are in before reprojecting. If you do not know the CRS, look for documentation on the source dataset's CRS. In the example below, you would replace `EPSG:3857` (Web Mercator) with the correct source CRS.

```bash
mapshaper projected.geojson \
  -proj init=EPSG:3857 \
  -proj wgs84 \
  -o output.geojson
```

### Optimize GeoJSON for web delivery

For browser delivery, you can shrink the size of a file by reducing coordinate precision and removing fields you do not need:

```bash
mapshaper input.shp \
  -filter-fields name,id,population \
  -proj wgs84 \
  -o precision=0.00001 output.geojson
```

`precision=0.00001` is about one metre at the equator. Use a coarser value for smaller files when your map scale allows it.

### Export GeoJSON for D3's `d3.geoPath()`

D3's geographic projections, such as `d3.geoMercator()` and `d3.geoAlbers()`, expect GeoJSON in WGS84 longitude/latitude. For polygon data, also pass `reverse-winding`, which reverses the ring orientation to match D3's spherical polygon convention (see [Winding order and filled polygons](#winding-order-and-filled-polygons) below for details).

```bash
mapshaper input.shp \
  -proj wgs84 \
  -o reverse-winding output.geojson
```

In JavaScript:

```js
const projection = d3.geoMercator().fitSize([width, height], geojson);
const path = d3.geoPath(projection);

svg.selectAll("path")
  .data(geojson.features)
  .join("path")
  .attr("d", path);
```

### Use projected coordinates with D3

If you intentionally export projected coordinates from Mapshaper, do not pass the data to `d3.geoMercator()` or another D3 geographic projection. The coordinates are already projected. Use `d3.geoIdentity()` instead, or export SVG directly from Mapshaper.

```bash
mapshaper input.shp -proj albersusa -o projected.geojson
```

```js
const projection = d3.geoIdentity()
  .reflectY(true)
  .fitSize([width, height], geojson);
const path = d3.geoPath(projection);
```

This treats the coordinates as planar x/y values. It is useful for custom SVG or Canvas rendering, but it is not the format expected by Leaflet, MapLibre, Mapbox GL, or most tile-based web maps.

### Export TopoJSON for D3

TopoJSON is often a better format than GeoJSON for D3 maps of polygon mosaics, such as countries, states, counties, or census areas. It stores shared boundaries once and typically uses quantized, delta-encoded path coordinates, so files are usually much smaller.

```bash
mapshaper counties.shp \
  -proj wgs84 \
  -simplify 10% keep-shapes \
  -o counties.topojson
```

In D3, load the TopoJSON file and convert the object you want to draw back to GeoJSON features with the `topojson-client` library:

```js
const topology = await d3.json("counties.topojson");
const counties = topojson.feature(topology, topology.objects.counties);

const projection = d3.geoAlbersUsa().fitSize([width, height], counties);
const path = d3.geoPath(projection);
```

TopoJSON still has the same coordinate-system question as GeoJSON. To use D3's projection system, export WGS84 longitude/latitude and let D3 project in the browser. For pre-projected planar drawing, use `d3.geoIdentity()` after exporting projected TopoJSON.

If you are combining multiple layers for one D3 map, TopoJSON can keep them in one file:

```bash
mapshaper -i combine-files states.shp counties.shp places.shp \
  -proj wgs84 \
  -o format=topojson map-data.topojson
```


## Understanding the warnings

### "RFC 7946 warning: non-WGS84 GeoJSON output"

RFC 7946, the current GeoJSON specification, defines GeoJSON coordinates as WGS84 longitude/latitude. Mapshaper can still write GeoJSON with projected coordinates, but it prints this warning because some tools will place the data in the wrong location or refuse to read it. For most web maps, reproject to WGS84 before export. The warning is informational when projected GeoJSON is intentional, such as for D3 planar rendering with `d3.geoIdentity()`.

### "My GeoJSON has projected coordinates but no CRS"

GeoJSON no longer has a standard `crs` member. If a projected GeoJSON is saved and re-opened later, Mapshaper cannot infer its CRS unless the coordinate bounds happen to look like longitude/latitude. Set the source CRS explicitly:

```bash
mapshaper projected.geojson -proj init=EPSG:5070 -proj wgs84 -o output.geojson
```

To preserve CRS metadata between editing sessions, use Shapefile, GeoPackage, FlatGeobuf, GeoParquet, or a Mapshaper snapshot (`.msx`) instead of projected GeoJSON.

## Winding order and filled polygons

Polygon winding controls which side of a ring is treated as the polygon interior. For most small land polygons:

- RFC 7946 GeoJSON uses counter-clockwise outer rings and clockwise holes.
- D3's spherical polygon convention uses the opposite orientation (see the [d3-geo winding order notebook](https://observablehq.com/@d3/winding-order) and the [d3-geo overview](https://d3js.org/d3-geo) for details).
- SVG and Canvas planar rendering usually care less, but holes can still render incorrectly when winding is inconsistent.

Mapshaper writes RFC 7946 winding by default. For D3 geographic rendering, try:

```bash
mapshaper input.shp -proj wgs84 -o reverse-winding output.geojson
```

If polygons disappear, holes fill in, or the entire world appears filled except your intended polygon, winding order is a likely cause.

`reverse-winding` is a practical fix for ordinary land polygons. It does not apply D3's special spherical rules for very large polygons, ocean masks, or polygons larger than a hemisphere. For those cases, prefer land polygons over ocean polygons, clip the data to the visible area, or test the output carefully in D3.

## Antimeridian and ocean caveats

The antimeridian is the 180° longitude line on the opposite side of the globe from the prime meridian. Geometries that cross it — such as features covering Fiji, Russia, the Aleutian Islands, or any Pacific-spanning or global dataset — must be split into two parts at the 180° boundary. Tools like Mapshaper and QGIS expect geometries to be divided this way, and will produce rendering artifacts if they aren't. Without splitting, a polygon or line that should neatly cross the antimeridian will instead render as a streak shooting across the entire map, because the renderer interprets the coordinate jump from +180° to −180° as a straight line through planar space rather than a short hop across the date line.

For D3 geographic projections, keep coordinates in WGS84 and let D3 handle spherical projection, clipping and removal of antimeridian cuts:

```bash
mapshaper world.shp -proj wgs84 -o reverse-winding world.geojson
```

For planar rendering or libraries that do not handle dateline wrapping well, split or clean the geometry before export and test the result at the target map extent:

```bash
mapshaper world.shp -clean -proj wgs84 -o world.geojson
```

Ocean polygons and "world minus land" masks are harder than ordinary land polygons because their intended interior may cover most of the globe. Winding and clipping rules differ between spherical and planar renderers. If your goal is a land map, exporting land polygons is usually more robust than exporting an ocean polygon with holes.

## Planar vs spherical rendering

When troubleshooting, first decide which rendering model you are using.

**Spherical rendering** means the JavaScript library receives longitude/latitude and projects it at draw time. This is the normal model for:

- D3 with `d3.geoMercator()`, `d3.geoAlbers()`, `d3.geoNaturalEarth1()`, etc.
- Leaflet, MapLibre, Mapbox GL, and other web map libraries
- GeoJSON meant to be shared with other tools

Use WGS84 GeoJSON:

```bash
mapshaper input.shp -proj wgs84 -o output.geojson
```

**Planar rendering** means coordinates are already x/y values in the drawing coordinate system or in a projected CRS. This is useful for static SVG/Canvas maps, custom D3 layouts, and pre-projected publication maps. Use Mapshaper to project first, then use `d3.geoIdentity()` to render as planar geometry — see [Use projected coordinates with D3](#use-projected-coordinates-with-d3) above for an example.

If a map appears in the wrong place, appears tiny, or is wildly distorted, the most common cause is mixing these models: projected coordinates sent to a spherical web map, or longitude/latitude coordinates treated as planar pixels.

## Preparing data for vector tile pipelines

Mapshaper is useful before a vector tile generator such as [Tippecanoe](https://github.com/felt/tippecanoe), Mapbox Tiling Service, or a similar hosted tile pipeline. Use Mapshaper for the editing steps it is good at: reprojecting to WGS84, cleaning topology, simplifying source geometry, joining attributes, dissolving features, clipping to an area of interest, and dropping fields you do not need in the tiles.

Most vector tile pipelines expect input GeoJSON in WGS84 longitude/latitude. Do not pre-project to Web Mercator unless the tiling tool explicitly asks for it; the tile generator handles the tile-space projection.

```bash
mapshaper raw-boundaries.shp \
  -filter-fields name,id,population \
  -clean \
  -proj wgs84 \
  -o precision=0.00001 fix-geometry boundaries.geojson

tippecanoe -o boundaries.mbtiles -zg --drop-densest-as-needed boundaries.geojson
```

For large datasets, newline-delimited GeoJSON (`ndjson`) is often easier for downstream tools to stream:

```bash
mapshaper raw-points.csv \
  -points x=lon y=lat \
  -filter-fields name,type \
  -proj wgs84 \
  -o ndjson points.ndjson

tippecanoe -o points.mbtiles -zg points.ndjson
```

If your Mapshaper project has several logical tile layers, export separate files and pass them to the tile generator as separate layers. This usually gives clearer tile schemas than combining unrelated feature types into one GeoJSON FeatureCollection.

```bash
mapshaper roads.shp -filter-fields class,name -proj wgs84 -o roads.geojson
mapshaper water.shp -filter-fields kind,name -proj wgs84 -o water.geojson
mapshaper places.shp -filter-fields name,population -proj wgs84 -o places.geojson
```

For Tippecanoe-specific metadata, Mapshaper's `hoist=` output option can promote a property out of the GeoJSON `properties` object onto the top-level Feature. This is useful for fields that Tippecanoe reads outside `properties`, such as feature-level metadata you prepared upstream. Keep this use narrow; most ordinary styling attributes should remain inside `properties`.

```bash
mapshaper input.geojson -o hoist=tippecanoe output.geojson
```

Avoid over-processing before tiling. Tile generators simplify, clip, and drop detail differently at each zoom level. Use Mapshaper to remove obvious waste and fix source-data problems, but test tiles at several zoom levels before applying aggressive simplification or coordinate rounding.

## Checklist

Before filing a bug or debugging renderer code, check:

- Does the target library expect WGS84 longitude/latitude GeoJSON?
- If the input GeoJSON is projected, did you set its CRS with `-proj init=...` before `-proj wgs84`?
- Are you using `d3.geoPath(d3.geoMercator())` for lon/lat data, and `d3.geoPath(d3.geoIdentity())` for projected data?
- For D3 polygon rendering, does `-o reverse-winding` fix missing or inverted fills?
- Would TopoJSON be smaller or easier for your D3 map than GeoJSON?
- If you are preparing vector tiles, are you giving the tile generator WGS84 input rather than pre-projected Web Mercator?
- Does the dataset cross the antimeridian or contain ocean/global mask polygons?
- Did coordinate rounding (`precision=`) introduce intersections that need `fix-geometry`?

## Related docs

- [GeoJSON format notes](/docs/formats/geojson.html.md)
- [TopoJSON format notes](/docs/formats/topojson.html.md)
- [Projections guide](/docs/guides/projections.html.md)
- [Topology and cleaning](/docs/guides/topology.html.md)
- [`-proj` reference](/docs/reference.html.md#-proj)
- [`-o` reference](/docs/reference.html.md#-o)

---

<!-- 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/essentials/command-line.html.md#command-files) and [variable interpolation](/docs/essentials/command-line.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` `.shx` `.dbf` `.prj` `.cpg` | &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; |
| [GeoParquet](/docs/formats/geoparquet.html.md) | `.parquet` `.geoparquet` | &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; |
| GeoTIFF | `.tif` `.tiff` | &check; | &check; | raster | &mdash; | &mdash; | &mdash; |
| PNG / JPEG raster | `.png` `.jpg` `.jpeg` | &check; | &mdash; | raster (with world file) | &mdash; | &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 — the input and output format are both inferred 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.
- **Raster and vector layers export separately.** GeoTIFF is the only output format that takes a raster layer's pixels, and it takes nothing else, so `-o` needs a `target=` when a session holds both kinds of layer. SVG and `.msx` snapshots are the two formats that accept a mix. A GeoTIFF written by Mapshaper keeps the pixel values as they are, in the type they were read in, so an elevation model comes out as elevations rather than as an image; the pixels are Deflate-compressed unless you ask for `compression=none`. The layer's projection is written into the file, either as an EPSG code or spelled out parameter by parameter. A handful of projections &mdash; Mapshaper's interrupted and composite ones among them &mdash; have no GeoTIFF representation at all; for those, Mapshaper writes the projection to a small `.aux.xml` file next to the `.tif`, so keep the two together, since that's where GIS software &mdash; and Mapshaper itself, when the `.tif` is loaded again &mdash; will look for it. Reading a raster, Mapshaper fills in what the file leaves out in the same way it does for vector data: a projection given without a datum is assumed to be on WGS 84, and a file with no projection metadata at all is assumed to be in WGS 84 lat-long if its coordinates fall in the decimal-degree range. A raster whose coordinates are outside that range and that says nothing about its CRS still loads and displays, but can't be projected or shown over a basemap until you say what it's in, with `-proj init=<crs> crs=<crs>`.

---

<!-- 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

When using the CLI, reference only the `.shp` file — Mapshaper automatically reads the companion `.shx`, `.dbf`, `.prj` and `.cpg` files from the same directory if they are present.

```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).
- `reverse-winding` &mdash; reverse the winding order of polygon rings on export.
- `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); use `reverse-winding` to write CW outer rings and CCW holes.
- Output is minified by default; pass `prettify` for human-readable JSON.
- If you are loading the data into a web map, see [Preparing data for D3 and web maps](/docs/guides/geojson-for-web-maps.html.md) for notes on WGS84, projected coordinates, polygon winding and D3 rendering.
- 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 uses a custom GeoJSON parser, so it is not constrained in the same way as tools that must load an entire file into a JavaScript string and call `JSON.parse()`.

In both Node.js and browsers, `JSON.parse()` workflows hit string-size and memory limits much earlier than the raw file-size limit. In practice, browser imports can fail well below 1 GB, and large files may crash the tab. If a GeoJSON is too big for the [web app](/docs/essentials/web-app.html.md), use the CLI (or `mapshaper-xl`) 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/geoparquet.html -->

# GeoParquet

GeoParquet is a compact columnar format that stores vector geometries alongside tabular attributes. It is now a common cloud-native interchange format for vector data: the Overture Maps Foundation publishes its global releases in GeoParquet, and tools such as DuckDB (with spatial), GeoPandas, BigQuery, Athena and Synapse can query GeoParquet datasets directly.

**File extensions:** `.parquet`, `.geoparquet` &middot; **Read:** &check; &middot; **Write:** &check; &middot; **Multi-layer:** no (one layer per file)

### CLI examples

```bash
mapshaper roads.parquet -info
mapshaper roads.parquet -o roads.geojson
mapshaper roads.geojson -o roads.parquet
```

### Format-specific input options

There are no GeoParquet-specific `-i` options.

### Format-specific output options

- `compression=snappy|zstd|none` &mdash; select Parquet column compression. The default is `snappy`. Use `none` to write uncompressed Parquet data. Snappy is designed for fast compression and decompression at moderate compression ratios. ZSTD is slower to compress but typically produces smaller files and is often preferred when file size matters more than write speed (e.g. files published for download or stored in a cloud bucket).
- `level=` &mdash; set the ZSTD compression level when using `compression=zstd`. Valid values are integers from 1 to 22. If omitted, the ZSTD library default is used.

### Practical notes

- Mapshaper imports one geometry column per file (the GeoParquet `primary_column` when present). Additional geometry columns are currently ignored.
- Mapshaper writes a single WKB geometry column named `geometry`.
- There is no fixed maximum GeoParquet file size. Limits are memory-driven:
  - In the regular CLI, the limit is your Node heap. For very large files, use `mapshaper-xl`, which starts with an 8 GB heap by default (and can be increased, e.g. `mapshaper-xl 16gb ...`).
  - In the web app, very large imports (often in the hundreds of MB, depending on browser/device) can run out of memory and crash the tab. For large GeoParquet files, prefer the CLI / `mapshaper-xl`.

## External resources

- [GeoParquet specification](https://geoparquet.org/) &mdash; official format specification and metadata model.
- [Apache Parquet geospatial logical types](https://github.com/apache/parquet-format/blob/apache-parquet-format-2.12.0/Geospatial.md) &mdash; core Parquet geospatial typing details.
- Cloud-Native Geospatial Formats Guide: GeoParquet &mdash; [Overview](https://guide.cloudnativegeo.org/geoparquet/) and [Example](https://guide.cloudnativegeo.org/geoparquet/geoparquet-example.html) pages.
- GeoParquet import in Mapshaper uses the [`hyparquet`](https://github.com/hyparam/hyparquet) JavaScript library.

---

<!-- 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 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 &mdash; [Overview](https://guide.cloudnativegeo.org/flatgeobuf/intro.html) and [Example](https://guide.cloudnativegeo.org/flatgeobuf/flatgeobuf.html) pages.
- 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/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/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/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 **History** button in the header opens the snapshot menu. From there you can:

- **Create snapshot** &mdash; saves to in-browser storage. These are session-scoped and intended to be temporary; Mapshaper tries to clean them up when the tab closes or the page reloads. For anything you want to keep, export it to a file.
- **Export** a stored snapshot to a `.msx` file on disk. Files on disk survive browser restarts and can be re-imported by drag-drop, the **Add files** button, or the `?files=` URL parameter. Choosing **Snapshot file** in the Export panel does the same thing for the current state.
- **Restore** a stored snapshot into the current session.
- **Remove** a stored snapshot from the browser.

See [History, undo and snapshots](/docs/essentials/web-app.html.md#history-undo-and-snapshots) for the rest of the History menu.

## External resources

- [msgpack.org](https://msgpack.org/) &mdash; the binary serialization format used inside `.msx` (via the [msgpackr](https://github.com/kriszyp/msgpackr) library).

---