# Mapshaper > Mapshaper is a command-line tool and in-browser editor for geographic vector data. It reads and writes Shapefile, GeoJSON, TopoJSON, GeoPackage, FlatGeobuf, KML/KMZ, CSV/TSV, DBF, JSON records and SVG, and can simplify, clip, dissolve, join, project and otherwise transform layers. The CLI and web app share the same command language, so commands written interactively in the browser console run unchanged in scripts. These docs cover the same material in two forms: - **Markdown mirrors** of every page (this file links to them) for use by language models and other tools. - **HTML pages** at the same paths without the trailing `.md`, with navigation, search and syntax highlighting, intended for humans. When in doubt about a command's behavior, the [command reference](https://mapshaper.org/docs/reference.html.md) is the source of truth. The Node.js source code lives at . --- # Mapshaper documentation

Mapshaper is a tool for editing Shapefile, GeoJSON, TopoJSON, GeoPackage, FlatGeobuf, KML and CSV data — available as a command-line program and as a web app at mapshaper.org.

Getting started

Introductions to the CLI and the web app.

Guides

Task-oriented walk-throughs: simplification, topology, joining layers, scripting from Node.

File formats

Read/write details for Shapefile, GeoJSON, TopoJSON, GeoPackage, FlatGeobuf, KML, CSV and more.

Examples

Short recipes for common GIS tasks, plus a Gallery of full map examples with source data.
## Featured examples

See the full gallery →

## What's new A curated log of recently added features is at [What's new](/docs/whats-new.html.md). The full [changelog](https://github.com/mbloch/mapshaper/blob/master/CHANGELOG.md) is on GitHub. ## Help and feedback - Found a bug or want to request a feature? [Share feedback](https://tally.so/r/44Njok) or [open an issue on GitHub](https://github.com/mbloch/mapshaper/issues). - Mapshaper is free software. If it's useful to you, please consider [supporting its development](/sponsor.html). --- # What's new This is a curated list of recently added features. For the full list of changes, including bug fixes and internal work, see the [changelog](https://github.com/mbloch/mapshaper/blob/master/CHANGELOG.md) on GitHub. ## April 2026
**Undo/redo buttons.** The web UI now has an undo/redo toolbar. Undo and redo were already supported in the geometry and attribute editing modes; the toolbar makes them more discoverable for users who didn't know the keyboard shortcuts (**⌘Z** / **⌘⇧Z**) existed.
**Command files.** A sequence of Mapshaper commands can be written to a `.txt` file with `#` comments and no shell quoting, and run with `-run ` (or just `mapshaper commands.txt`). Command files can also be written in a shell-compatible way, if you want to be able to paste the commands into the terminal or add them to a shell script. In a future release, these files will also be runnable in the browser. ```bash mapshaper build.txt ``` → See [Command files](/docs/reference.html.md#command-files) in the reference.
**Variable interpolation in commands.** Command files and command lines support `{{VAR}}` placeholders, resolved at run time against environment variables (`{{env.HOME}}`), values set with the new `-vars` and `-defaults` commands, and variables defined dynamically by `-calc`, `-define` and `-each` expressions. ```bash mapshaper -vars YEAR=2030 PCT=5 -run build.txt ``` → See [Variable interpolation](/docs/reference.html.md#variable-interpolation), [`-vars`](/docs/reference.html.md#-vars) and [`-defaults`](/docs/reference.html.md#-defaults).
**Farewell to dissolve2.** The `-dissolve` command now uses Mapshaper's most robust dissolve function, which can handle overlaps, gaps and other topology errors. The legacy faster algorithm is still available as `-dissolve no-repair`. (The old `-dissolve2` is just an alias for `-dissolve`.) → See [`-dissolve`](/docs/reference.html.md#-dissolve).
**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).
**SVG import.** SVG files exported by Mapshaper can be re-imported — useful for making stylistic edits. → See [SVG](/docs/formats/svg.html.md).
--- # Command reference ## Command line syntax Mapshaper takes a list of commands and runs them in sequence, from left to right. A command consists of the name of a command prefixed by a hyphen, followed by options for the command. The initial import command `-i` can be omitted. #### Example ```bash # Read a Shapefile, simplify using Douglas-Peucker, output as GeoJSON. mapshaper provinces.shp -simplify dp 20% -o precision=0.00001 output.geojson ``` ### Command options can take three forms: - Values, like `provinces.shp` and `output.geojson` in the above example - Flags, like `dp` - Name/value pairs, like `precision=0.00001` ### Common options The following options are documented here, because they are used by many commands. `name=` Rename the layer (or layers) modified by a command. `target=` Specify the layer or layers targeted by a command. Takes the name of a layer, the number of a layer (first layer is 1), or a comma-separated list of layer names or numbers. Names may contain the `*` wildcard. `+` Use the output of a command to create a new layer or layers instead of replacing the target layer(s). Use together with the `name=` option to assign a name to the new layer(s). #### Example ```bash # Make a derived layer containing a subset of features # while retaining the original layer mapshaper states.geojson -filter 'ST == "AK"' + name=alaska -o output/ target=* ``` ## Command files As an alternative to typing commands on the command line, you can put them in a plain-text command file and run them with the mapshaper CLI. Command files offer a few conveniences over a shell script or Makefile: - Hash-delimited (`#`) comments, both on their own line and at the end of a line. - No need to escape `*` or other shell metacharacters; commands aren't passed through the shell. - Trailing-backslash line continuations are accepted but not required — lines that don't begin with `-` are joined onto the previous command. - Variable interpolation using `{{VAR}}` placeholders. See [variables](#variables) below. (Support for running command files in the mapshaper web UI is planned for a future release.) ### File format A mapshaper command file is a `.txt` file whose first non-blank, non-comment line starts with `mapshaper`. ``` mapshaper -i provinces.shp # Use Douglas Peucker simplification -simplify dp 20% -o precision=0.00001 output.geojson ``` If you write the command file using shell-compatible syntax — trailing `\` for line continuations and no `#` comments — 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}}` — substituted with the value of `VAR`. - `{{env.NAME}}` — 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 — a name set by `-vars` is *not* readable by bare name from inside `-each`, `-filter`, etc. See [JavaScript expressions](/docs/guides/expressions.html.md#sharing-state-across-commands) for the full story. #### Example `build.txt`: ``` mapshaper -defaults YEAR=2024 PCT=10 # overridable defaults -i sources/counties_{{YEAR}}.shp -simplify {{PCT}}% -o out/counties_{{YEAR}}_simplified.shp ``` Run with the command file's defaults: ```bash mapshaper build.txt ``` Or override default values from the command line: ```bash mapshaper -vars YEAR=2030 PCT=5 -run build.txt ``` ## Index of commands **File I/O** [-i (input)](#-i-input) [-o (output)](#-o-output) **Editing** [-affine](#-affine) [-classify](#-classify) [-clean](#-clean) [-clip](#-clip) [-colorizer](#-colorizer) [-dashlines](#-dashlines) [-dissolve](#-dissolve) [-dissolve2](#-dissolve2) [-divide](#-divide) [-dots](#-dots) [-drop](#-drop) [-each](#-each) [-erase](#-erase) [-explode](#-explode) [-filter](#-filter) [-filter-fields](#-filter-fields) [-filter-islands](#-filter-islands) [-filter-slivers](#-filter-slivers) [-frame](#-frame) [-graticule](#-graticule) [-grid](#-grid) [-include](#-include) [-inlay](#-inlay) [-innerlines](#-innerlines) [-join](#-join) [-lines](#-lines) [-merge-layers](#-merge-layers) [-mosaic](#-mosaic) [-point-grid](#-point-grid) [-points](#-points) [-polygons](#-polygons) [-proj](#-proj) [-rectangle](#-rectangle) [-rectangles](#-rectangles) [-rename-fields](#-rename-fields) [-rename-layers](#-rename-layers) [-require](#-require) [-run](#-run) [-scalebar](#-scalebar) [-shape](#-shape) [-simplify](#-simplify) [-snap](#-snap) [-sort](#-sort) [-split](#-split) [-split-on-grid](#-split-on-grid) [-subdivide](#-subdivide) [-style](#-style) [-symbols](#-symbols) [-union](#-union) [-uniq](#-uniq) **Control Flow** [-if](#-if) [-elif](#-elif) [-else](#-else) [-endif](#-endif) [-stop](#-stop) [-target](#-target) **Information** [-calc](#-calc) [-colors](#-colors) [-comment](#-comment) [-defaults](#-defaults) [-encodings](#-encodings) [-help](#-help) [-info](#-info) [-inspect](#-inspect) [-print](#-print) [-projections](#-projections) [-quiet](#-quiet) [-vars](#-vars) [-verbose](#-verbose) [-version](#-version) ## I/O Commands ### -i (input) Input one or more files in a supported vector data format. Supported file types include: Shapefile, GeoJSON, TopoJSON, GeoPackage, FlatGeobuf, KML, JSON data records, DBF, CSV/TSV. The `-i` command is assumed if `mapshaper` is followed by the path of an input data file. Mapshaper does not fully support M and Z type Shapefiles. The M and Z data is lost when these files are imported. When multiple input files are given, they can either be processed together (as a group of layers with shared topology) or separately (as a sequence of independent runs). Use `combine-files` to process them together, or `batch-mode` to process them separately. For backward compatibility, multiple input files are currently processed in batch mode by default; this default will change in a future release. Mapshaper prints a deprecation notice when batch mode is triggered implicitly. Existing scripts that rely on batch processing should add the `batch-mode` flag. **Options** `` or `files=` File(s) to input (space-separated list). Use `-` to import from `/dev/stdin`. In place of a file name, you can also pass data inline: - **JSON.** A string starting with `{` or `[` is treated as a literal JSON object or array. - **CSV.** A comma-delimited string is treated as inline CSV when it contains a newline (a real one or the literal escape sequence `\n`) and both the first and second lines contain at least one comma. ```bash mapshaper -i 'lat,lon,label\n48.86,2.35,Paris\n51.51,-0.13,London' -o cities.json ``` `combine-files` Import multiple files to separate layers with shared topology. Useful for generating a single TopoJSON file containing multiple geometry objects. `batch-mode` Apply subsequent commands separately to each input file, as if running mapshaper multiple times with the same set of commands. Used together with `-o` to transform a directory of files. Required (in a future release) to use this batch-processing behavior. `merge-files` (Deprecated) Merge features from multiple input files into as few layers as possible. Preferred method: import files to separate layers using `-i combine-files`, then use the `-merge-layers` command to merge layers. `snap` Snap together vertices within a small distance threshold. This option is intended to fix minor coordinate misalignments in adjacent polygons. The snapping distance is 0.0025 of the average segment length. `snap-interval=` Specify snapping distance in source units. `precision=` (Deprecated) Round all coordinates to a specified precision, e.g. `0.001`. It is recommended to set coordinate precision on export, using `-o precision=`. `no-topology` Skip topology identification to speed up processing of large files. For use with commands like `-filter` that don't require topology. `encoding=` Specify encoding used for reading .dbf files and delimited text files. If the `encoding` option is missing, mapshaper will try to detect the encoding of .dbf files. Dbf encoding can also be set using a .cpg file. `id-field=` (Topo/GeoJSON) Import values of "id" property to this data field. `string-fields=` (CSV) List of fields to import as strings (e.g. FIPS,ZIPCODE). Using `string-fields=*` imports all fields as strings. `field-types=` Type hints for importing delimited text. Takes a comma-separated list of field names with type hints appended; e.g. `FIPS:str,zipcode:str`. Recognized type hints include `:str` or `:string`, `:num` or `:number`. Without a type hint, fields containing text data that looks like numeric data, like ZIP Codes, will be converted to numbers. `csv-skip-lines=` Number of lines to skip at the beginning of a CSV file. Useful when a CSV has been exported from a spreadsheet and there are rows of notes above the data section of the worksheet. `csv-lines=` Number of data records to import from a CSV file (default is all). `csv-field-names=` Comma-sep. list of names to assign each field. Can be used in conjunction with `csv-skip-lines=1` to replace names from an existing set of field headers. `csv-fields=` Comma-sep. list of fields to import from a CSV-formatted input file. Fields are filtered as the file is read, which reduces the memory needed to import very large CSV files. `decimal-comma` Import numbers formatted with decimal commas, not decimal points. Accepted formats: `1.000,01` `1 000,01` (both imported as as 1000.01). `csv-dedup-fields` Assign unique names to CSV fields with duplicate names. `csv-filter=` A JavaScript expression for importing a subset of the records in a CSV file. Records are filtered as the file is read, which reduces the memory needed to import very large CSV files. `json-path=` [JSON] Path to an array of data records or a GeoJSON object. For example, `json-path=data/counties` expects a JSON object with the following structure `{"data": {"counties": []}}`. `layers=` [GeoPackage] Comma-separated list of layer names to import from a GeoPackage file. If omitted, all layers are imported. `name=` Rename the imported layer (or layers). **Example** ```bash # Input a Shapefile with text data in the latin1 encoding # and see what kind of data it contains mapshaper countries_wgs84.shp encoding=latin1 -info ``` ### -o (output) Save content of the target layer(s) to a file or files. **Options** `||-` Name of output file or directory. Use `-` to export text-based formats to `/dev/stdout`. `format=shapefile|geojson|topojson|flatgeobuf|geopackage|json|dbf|csv|tsv|svg` Specify output format. If the `format=` option is missing, Mapshaper tries to infer the format from the output filename. If no filename is given, Mapshaper exports to the same format as the input format. The `json` format is an array of objects containing data properties for each feature. `target=` Specify layer(s) to export (comma-separated list). The default target is the output layer(s) of the previous command. Use `target=*` to select all layers. `force` Allow output files to overwrite input files (without this option, overwriting input files is not allowed). `gzip` Apply gzip compression to output files. `zip` Save output files in a single .zip archive. `cut-table` Detach attribute data from shapes and save as a JSON file. `drop-table` Remove attribute data from output. `precision=` Round all coordinates to a specified precision, e.g. `precision=0.001`. Useful for reducing the size of GeoJSON files. `fix-geometry` Remove segment intersections caused by rounding (via the `precision=` option) or TopoJSON quantization, by reverting intersecting areas to the original coordinates. In the case of quantized TopoJSON output, this option produces delta-encoded arcs that contain some decimal numbers. Be sure to test your software for compatibility. Note that this option is only applied if the original paths are free of intersections. Also, some kinds of invalid geometry, like spikes, do not get fixed. `bbox-index` Export a JSON file containing bounding boxes of each output layer. `encoding=` (Shapefile/CSV) Encoding of input text (by default, Shapefile encoding is auto-detected and CSV files are assumed to be UTF-8). `field-order=` (Shapefile/CSV) `field-order=ascending` sorts data fields in alphabetical order of field names (A-Z, case-insensitive). `id-field=` (Topo/GeoJSON/SVG) Specify one or more data fields to use as the "id" property of GeoJSON, TopoJSON or SVG features (comma-separated list). When exporting multiple layers, you can pass a list of field names. The first listed name that is present in a layer's attribute table will be used as the id field for that layer. `bbox` (Topo/GeoJSON) Add bbox property to the top-level object. `extension=` (Topo/GeoJSON) set file extension (default is ".json"). `prettify` (Topo/GeoJSON) Format output for readability. `singles` (TopoJSON) Save each output layer as a separate file. Each output file and the TopoJSON object that it contains are named after the corresponding data layer. `quantization=` (TopoJSON) Specify quantization as the maximum number of differentiable points along either dimension. Equivalent to the quantization parameter used by the [topoquantize](https://github.com/topojson/topojson-client#topoquantize) command line program. By default, mapshaper applies quantization equivalent to 0.02 of the average segment length. `no-quantization` (TopoJSON) Arc coordinates are encoded at full precision and without delta-encoding. `presimplify` (TopoJSON) Add a threshold value to each arc vertex in the z position (i.e. [x, y, z]). Useful for dynamically simplifying paths using vertex filtering. Given W as the width of the map viewport in pixels, S as the ratio of content width to viewport width, and pz as the presimplify value of a point, the following expression tests if the point should be excluded from the output path: `pz > 0 && pz < 10000 / (W * S)`. `topojson-precision=` (TopoJSON) Set quantization as a fraction of the average segment length. `ndjson` (GeoJSON/JSON) Output newline-delimited records. `gj2008` (GeoJSON) Generate output that is consistent with the pre-RFC 7946 GeoJSON spec (dating to 2008). Polygon rings are CW and holes are CCW, which is the opposite of the default RFC 7946-compatible output. Mapshaper's default GeoJSON output is now compatible with the current specification (RFC 7946). `combine-layers` (GeoJSON) Combine multiple output layers into a single GeoJSON file. `geojson-type=` (GeoJSON) Overrides the default output type. Possible values: "FeatureCollection", "GeometryCollection", "Feature" (for a single feature). `no-null-props` (GeoJSON) use `"properties": {}` instead of `"properties": null` when outputting a Feature with no attribute data. `hoist=` (GeoJSON) Move one or more properties to the root level of each Feature. Hoisting a field named "id" creates an id for each Feature. This option can also be used to create non-standard Feature attributes (as used by the tippecanoe program). `width=` (SVG/TopoJSON) Set the width of the output dataset in pixels. When used with TopoJSON output, this option switches the output coordinates from geographic units to pixels and flips the Y axis. SVG output is always in pixels (default SVG width is 800). `height=` (SVG/TopoJSON) Similar to the `width` option. If both `height` and `width` are set, content is centered inside the `[0, 0, width, height]` bounding box. `max-height=` (SVG/TopoJSON) Limit output height (units: pixels). `margin=` (SVG/TopoJSON) Set the margin between coordinate data and the edge of the viewport (default is 1). To assign different margins to each side, pass a list of values in the order `` (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=` (SVG) Bounding box of SVG map in projected map units. By default, the extent of SVG output fits the content; this option lets you provide a custom extent. This could be useful when aligning the SVG output with other content layers, such as images or videos. `fit-extent=` (SVG) Use a layer (typically a layer containing a single rectangle) to set the extent of the map. Paths that overflow this extent are retained in the SVG output. `point-symbol=square` (SVG) Use squares instead of circles to symbolize point data. `delimiter=` (CSV) Set the field delimiter for CSV/delimited text output; e.g. `delimiter=|`. `decimal-comma` (CSV) Export numbers with decimal commas instead of decimal points (common in Europe and elsewhere). `show-all` [Snapshot] All layers of the exported snapshot will be displayed when opened in the web UI. **Example** ```bash # Convert all the Shapefiles in one directory into GeoJSON # files in a different directory. mapshaper -i shapefiles/*.shp batch-mode -o geojson/ format=geojson ``` ## Editing Commands ### -affine Transform coordinates by shifting, scaling and rotating. Not recommended for unprojected datasets. `shift=` X,Y shift in source units (e.g. 5000,-5000) `scale=` Scale (default is 1) `rotate=` Angle of rotation in degrees (default is 0) `anchor=` Center of rotation/scaling (default is center of the bounding box of the selected content) `where=` Use a JS expression to select a subset of features. Common options: `target=` ### -classify Assign colors or data values to each feature using one of several classification methods. Methods for sequential data include `quantile`, `equal-interval`, `hybrid` and `nice` or categorical classification to a data field. `` or `field=` Name of the data field to classify. `save-as=` Name of a (new or existing) field to receive the output of classification. The default output field for colors is `fill` or `stroke` (depending on geometry type) and `class` for non-color output. `values=` List of values to assign to data classes. If the number of values differs from the number of classes given by the (optional) `classes` or `breaks` option, then interpolated values will be calculated. Mapshaper uses d3 for interpolation. `colors=` Takes a list of CSS colors, the name of a predefined color scheme, or `random`. Run the [-colors](#-colors) command to list all of the built-in color schemes. Similar to the `values=` option, if the number of listed colors is different from the number of requested classes, interpolated colors are calculated. `non-adjacent` Assign colors to a polygon layer in a randomish pattern, trying not to assign the same color to adjacent polygons. Mapshaper's algorithm balances performance and quality. Usually it can find a solution with four or five colors. If mapshaper is unable to avoid giving the same color to neighboring polygons, it will print a warning. You can resolve the problem by increasing the number of colors. `stops=` A pair of comma-separated numbers (0-100) for limiting the output range of a color ramp. `null-value=` Value (or color) to use for invalid or missing data. `classes=` Number of data classes. This number can also be inferred from the `breaks=` or `values=` options. `breaks=` Specify user-defined sequential class breaks (an alternative to automatic classification using `quantile`, `equal-interval`, etc.). `outer-breaks=` A pair of comma-separated numbers setting min and max breakpoints to use when computing class breaks. This setting overrides the default behavior, which is to use the min and max values of the data field being classified. This setting can be used to prevent extreme data values (outliers) from affecting equal-interval classification. Also useful for setting outside breakpoints for continuous color ramps (when using the `continuous` option). `method=` Classification method. One of: `quantile`, `equal-interval`, `nice`, `hybrid` (sequential data), `categorical`, `non-adjacent` and `indexed`. This parameter is not required if the classification method can be inferred from other options. For example, the `index-field=` parameter implies indexed classification, the `categories=` parameter implies categorical classification. `quantile` Use quantile classification. Shortcut for `method=quantile`. `equal-interval` Use equal interval classification. Shortcut for `method=equal-interval`. `nice` Same as `method=nice`. This scheme finds equally spaced, round breakpoints that roughly divide the dataset into equal parts (similar to quantile classification). `invert` Reverse the order of colors/values. `continuous` Output continuously interpolated values (experimental). Uses linear interpolation between class breaks, which may give poor results with some distributions of data. This option is for creating unclassed/continuous-color maps. `index-field=` Use class ids that have been precalculated and assigned to this field. Values should be integers from `0 ... n-1` (where n is the number of classes). `-1` is the null value. `precision=` Round data values before classification (e.g. `precision=0.1`). `categories=` List of values in the source data field. Using this option triggers categorical classification. `other=` Default value for categorical classification. This value is used when the value of the source data field is not present in the list of values given by `categories=`. Defaults to `null-value=` or null. **Options for generating SVG keys** `key-style=` One of: simple, gradient, dataviz `key-name= ` Name of output SVG file `key-width=` Width of key in pixels `key-font-size=` Font size of tic labels in pixels `key-tile-height=` Height of color tiles in pixels `key-tic-length=` Length of tic mark in pixels `key-label-suffix=` String to append to each label `key-last-suffix=` String to append to the last label **Examples** ```bash # Apply a sequential color ramp to a polygon dataset using quantiles. mapshaper covid_cases.geojson \ -classify save-as=fill quantile color-scheme=Oranges classes=6 \ -o out.geojson ``` ### -clean This command attempts to repair various kinds of abnormal geometry that might cause problems when running other mapshaper commands or when using other software. Features with null geometries are deleted, unless the `allow-empty` flag is used. Polygon features are cleaned by removing overlaps and filling small gaps between adjacent polygons. Only gaps that are completely enclosed can be filled. Areas that are contained by more than one polygon (overlaps) are assigned to the polygon with the largest area. Similarly, gaps are assigned to the largest-area polygon. This rule may give undesired results and will likely change in the future. Line features are cleaned by removing self-intersections within the same path. Self-intersecting paths are split at the point of intersection and converted into multiple paths within the same feature. When two separate paths intersect in-between segment endpoints, new vertices are inserted at the point of intersection. Point features are cleaned by removing duplicate coordinates within the same feature. `gap-fill-area=` (polygons) Gaps smaller than this area will be filled; larger gaps will be retained as holes in the polygon mosaic. Example values: 2km2 500m2 0. Defaults to a dynamic value calculated from the geometry of the dataset. `sliver-control=` (polygons) Preferentially remove slivers (polygons with a high perimeter-area ratio). Accepts values from 0-1, default is 1. Implementation: multiplies the area of gap areas by the "Polsby Popper" compactness metric before applying area threshold. `overlap-rule=` (polygons) Assign overlapping polygon areas to one of the overlapping features based on this rule. Possible options are: min-id, max-id, min-area, max-area (default is max-area). `allow-overlaps` Allow features to overlap each other. The default behavior is to remove overlaps. `snap-interval=` Snap vertices within a given threshold before performing other kinds of geometry repair. Defaults to a very small threshold. Uses source units. `rewind` Fix errors in the winding order of polygon rings. `allow-empty` Allow null geometries, which are removed by default. Common options: `target=` ### -clip Remove features or portions of features that fall outside a clipping area. `` or `source=` Clip to a set of polygon features. Takes the filename or layer id of the clip polygons. `bbox=` Delete features or portions of features that fall outside a bounding box. `bbox2=` Faster bounding box clipping than `bbox=` (experimental). `remove-slivers` Remove tiny sliver polygons created by clipping. Common options: [`name=` `+` `target=`](#common-options) ```bash # Example: Clip a polygon layer using another polygon layer. mapshaper usa_counties.shp -clip land-area.shp -o clipped.shp ``` ### -colorizer Define a function for converting data values to colors that can be used in subsequent calls to the `-style` command. `name=` Name of the colorizer function. `colors=` List of CSS colors. `random` Randomly assign colors. Uses `colors=` list if given. `breaks=` Ascending-order list of breaks (thresholds) for creating a sequential color scheme. `categories=` List of data values (keys) for creating a categorical color scheme. `other=` Default color for categorical scheme (defaults to `nodata` color). `nodata=` Color to use for invalid or missing data (default is white). `precision=` Rounding precision to apply to numerical data before converting to a color (e.g. 0.1). ```bash # Example: define a function for a sequential color scheme # and assign colors based on data values mapshaper data.json \ -colorizer name=getColor \ colors='#f0f9e8,#bae4bc,#7bccc4,#2b8cbe' breaks=25,50,75 \ -each 'color = getColor(PCT)' \ -o output.json # Example: define a function for a categorical color scheme # and use it to assign fill colors mapshaper data.json \ -colorizer name=calcFill colors='red,blue,green' \ categories='Republican,Democrat,Other' \ -style fill='calcFill(PARTY)' \ -o output.svg ``` ### -dashlines Split lines into sections, with or without a gap. `dash-length=` Length of split-apart lines (e.g. 200km) `gap-length=` Length of gaps between dashes (default is 0) `scaled` Scale dashes and gaps to prevent partial dashes `planar` Use planar geometry `where=` Use a JS expression to select a subset of features. ### -dissolve Aggregate groups of features using a data field, or aggregate all features if no field is given. For polygon layers, `-dissolve` merges adjacent polygons by erasing shared boundaries. For point layers, `-dissolve` replaces a group of points with their centroid. For polyline layers, `-dissolve` tries to merge contiguous polylines into as few polylines as possible. For polygon layers, `-dissolve` repairs topology before dissolving, so it produces correct results on inputs that contain overlaps, gaps or other topology errors. The `no-repair` option skips this step for a faster (but less robust) dissolve. `` or `fields=` (optional) Name of a data field or fields to dissolve on. Accepts a comma-separated list of field names. `group-points` [points] Group the points from each dissolved group of features into a multi-point feature instead of converting multiple points into a single-point centroid feature. `weight=` [points] Name of a field or a JS expression for generating weighted centroids. For example, the following command estimates the "center of mass" of the U.S. population: ` mapshaper census_tracts.shp -points -dissolve weight=POPULATION -o out.shp` `planar` [points] Treat decimal degree coordinates as planar cartesian coordinates when calculating dissolve centroids. (By default, mapshaper calculates the centroids of lat-long point data in 3D space.) `gap-fill-area=` [polygons] Gaps smaller than this area will be filled; larger gaps will be retained as holes in the polygon mosaic. Example values: 2km2 500m2 0. Defaults to a dynamic value calculated from the geometry of the dataset. `sliver-control=` [polygons] Preferentially remove slivers (polygons with a high perimeter-area ratio). Accepts values from 0-1, default is 1. Implementation: multiplies the area of gap areas by the "Polsby Popper" compactness metric before applying area threshold. `allow-overlaps` [polygons] Allow dissolved groups of features to overlap each other. The default behavior is to remove overlaps. `no-repair` [polygons] Skip topology repair before dissolving. Use when the input is known to be clean and you want a faster dissolve. Mapshaper checks for segment intersections and prints a warning if the assumption appears to be wrong, but it still performs the dissolve. Incompatible with `gap-fill-area=`, `sliver-control=` and `allow-overlaps`. `calc=` Use built-in JavaScript functions to create data fields in the dissolved layer. See example below; see [-calc](#-calc) for a list of supported functions. `sum-fields=` Fields to sum when dissolving (comma-sep. list). `copy-fields=` Fields to copy when dissolving (comma-sep. list). Copies values from the first feature in each group of dissolved features. `multipart` Group features from the target layer into multipart features, without otherwise modifying geometry. `where=` Use a JS expression to select a subset of features to dissolve. Common options: `name=` `+` `target=` ```bash # Example: Aggregate county polygons to states mapshaper counties.shp -dissolve STATE -o states.shp # Example: Use the calc= option to count the number of dissolved features # and perform other calculations mapshaper counties.shp \ -dissolve STATE calc='n = count(), total_pop = sum(POP), max_pop = max(POP), min_pop = min(POP)' ``` ### -dissolve2 Deprecated alias for [`-dissolve`](#-dissolve). The topology-repairing behavior of `-dissolve2` has been promoted to be the default behavior of `-dissolve`. Existing scripts that use `-dissolve2` will continue to work but print a deprecation notice. ### -divide Divide a polyline layer by a polygon layer. Line features that cross polygon boundaries are divided into separate features. Data fields from the polygon layer are copied to the line layer, as in the `-join` command. `` 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. `` 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. `` 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. `` or `source=` File or layer containing erase polygons. Takes the filename or layer id of the erase polygons. `bbox=` 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. `` 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 ``. Common options: [`name=` `+` `target=` ](#common-options) ```bash # Example: Select counties from New England states mapshaper usa_counties.shp \ -filter '"ME,VT,NH,MA,CT,RI".indexOf(STATE) > -1' \ -o ne_counties.shp ``` ### -filter-fields Delete fields in an attribute table, by listing the fields to retain. If no files are given, then all attributes are removed. `` or `fields=` Comma-separated list of data fields to retain. `invert` Invert the filter -- delete the listed fields instead of retaining them. Common options: `target=` ```bash # Example: Retain two fields mapshaper states.shp -filter-fields FID,NAME -o out.shp ``` ### -filter-islands Remove small detached polygon rings (islands). `min-area=` Remove small-area islands using an area threshold (e.g. 10km2). `min-vertices=` Remove low-vertex-count islands. `remove-empty` Delete features with null geometry. [`target=`](#common-options) ### -filter-slivers Remove small polygon rings. `min-area=` Area threshold for removal (e.g. 10km2). `sliver-control=` (polygons) Preferentially remove slivers (polygons with a high perimeter-area ratio). Accepts values from 0-1, default is 1. Implementation: multiplies the area of polygon rings by the "Polsby Popper" compactness metric before applying area threshold. `remove-empty` Delete features with null geometry. [`target=`](#common-options) ### -frame Create a rectangular frame layer at a given display width. Frame size is used for scaling symbols and for setting the display size of SVG output. The geographical extent of the frame is based on the `bbox=` option or the bounding box of the target layer or layers, if `bbox=` is omitted. `width=` Width of frame (e.g. 5in, 10cm, 600px; default is 800px) `height=` Height of frame (in addition to or instead of width= option) `aspect-ratio=` Aspect ratio of frame (optional) `bbox=` Bounding coordinates of frame contents in projected map coordinates (xmin,ymin,xmax,ymax). If omitted, the bounding box of the target layer(s) is used. `offset=` Padding around the frame's `bbox` in display units or pct of width/height, e.g. 5cm 20px 5% `offsets=` Comma-sep. list of offsets for each side of the map frame, in l,b,r,t order Other options: `name=` `target=` ### -graticule Create a graticule layer appropriate for a world map centered on longitude 0. `polygon` Create an polygon enclosing the entire area of the graticule. Useful for creating background or outline shapes for clipped projections, like Robinson or Stereographic. `interval=` Specify the spacing of graticule lines (in degrees). Common options are: 5, 10, 15, 30, 45. Default is 10. ### -grid Create a continuous grid of square or hexagonal polygons. The `-grid` command should have a projected layer as its target. The cells of the grid will completely enclose the bounding box of the target layer. This command is intended for visualizing data in a grid. Typically, you would use the `-join` command to join data from a polygon or point layer to a grid layer. Use `-join interpolate=` to interpolate data values (typically count data) from the polygon layer to the grid layer based on area. Use `-join calc=' = sum()'` or `-join calc=' = count()'` to aggregate point data values. `type=` Supported values: `square` `hex` `hex2`. The `hex` and `hex2` types have different rotations. `interval=` The length of one side of a grid cell. Example values: `500m` `2km`. Other options: `name=` `+` `target=` ### -include `` 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. `` 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. `` 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()` `isMin()` and `isMode()` can be used in many-to-one joins to select among source records. `fields=` A comma-separated list of fields to copy from the external table. If the `fields` option and `calc` options are both absent, all fields are copied except the key field (if joining on keys) unless the. Use `fields=*` to copy all fields, including any key field. Use `fields=` (empty list) to copy no fields. `prefix=` Add a prefix to the names of fields joined from the external attribute table. `interpolate=` (polygon-to-polygon joins only) A list of fields to interpolate/reaggregate based on area of overlap. Interpolates fields containing count data, such as population counts or vote counts. Treats data as being uniformly distributed within polygon areas. Also interpolates string fields containing categorical data. The value associated with the largest area of overlap between source and target polygons gets copied to the target feature. `point-method` (polygon-to-polygon joins only) Use an alternate method for joining two polygon layers. The default polygon-polygon join method detects areas of overlap between two polygon layers by compositing the two layers internally. This method is simpler -- it generates a temporary point layer from the source layer with the greater number of features (using the same inner-point method as the `-points inner` command), and then performs a point-to-polygon or polygon-to-point join. This method does not support the `interpolate=` option. `largest-overlap` (polygon-to-polygon joins only) selects a single polygon to join when multiple source polygons overlap a target polygon, based on largest area of overlap. `min-overlap-pct=` (polygon-to-polygon joins only) Only source features with at least this percentage overlap of the target feature (by area) get joined. `min-overlap-area=` (polygon-to-polygon joins only) Only source features with at least this much areal overlap of the target feature get joined. `max-distance=` (point-to-point joins only) Join source layer points within this distance of a target layer point. `duplication` Create duplicate features in the target layer on many-to-one joins. `sum-fields=` (deprecated) A comma-separated list of fields to sum when several source records match the same target record. This option is equivalent to using the `sum()` function inside a `calc=` expression like this: `calc='FIELD = sum(FIELD)'`. `string-fields=` A comma-separated list of fields in source CSV file to import as strings (e.g. FIPS,ZIPCODE). `field-types=` A comma-separated list of type hints (when joining a CSV file or other delimited text file). See `-i field-types=` above. `force` Allow values in the target data table to be overwritten by values in the source table when both tables contain identically named fields. `unjoined` Copy unjoined records from the source table to a layer named "unjoined". `unmatched` Copy unmatched records from the destination table to a layer named "unmatched". Other options: `encoding=` `target=` **Examples** Join a point layer to a polygon layer (spatial join), using the `calc=` option to handle many-to-one matches. ```bash mapshaper states.shp \ -join points.shp calc='median_score = median(SCORE), mean_score = average(SCORE), join_count = count()' \ -o out.shp ``` Copy data from a csv file to the attribute table of a Shapefile by matching values from the *STATE_FIPS* field of the Shapefile and the *FIPS* field of the csv file. (The string-fields=FIPS argument prevents FIPS codes in the CSV file from being converted to numbers.) ```bash mapshaper states.shp \ -join demographics.txt keys=STATE_FIPS,FIPS string-fields=FIPS \ -o out.shp ``` ### -lines Converts points and polygons to lines. Polygons are converted to topological boundaries. Without the `` argument, external (unshared) polygon boundaries are attributed as `TYPE: "outer", RANK: 0` and internal (shared) boundaries are `TYPE: "inner", RANK: 1`. `` 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: , 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. `` 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). `` or `crs=` Target CRS, given as a Proj.4 definition or an alias. Use the [`-projections`](#-projections) command to list available projections and aliases. In projections which require additional parameters, such as a zone in UTM, you can pass a Proj4 string enclosed in quotes. For example, `crs='+proj=utm +zone=27'`. `densify` Interpolate vertices along long line segments as needed to approximate curved lines. `match=` Match the projection of the given layer or .prj file. `init=` Define the pre-projected coordinate system, if unknown. This option is not needed if the source coordinate system is defined by a .prj file, or if the source CRS is WGS84. As with `crs`, you can pass a Proj4 string enclosed in quotes if the selected projection requires extra parameters, for example `init='+proj=utm +zone=33'`. `target=` Layer(s) to target. All layers belonging to the same dataset as a targeted layer will be reprojected. To reproject all datasets, use `target=*`. **Examples** ```bash # Convert a GeoJSON file to New York Long Island state plane CRS, # using a Proj.4 string mapshaper nyc.json \ -proj +proj=lcc \ +lat_1=41.03333333333333 +lat_2=40.66666666666666 \ +lat_0=40.16666666666666 +lon_0=-74 \ +x_0=300000 +y_0=0 \ +ellps=GRS80 +datum=NAD83 +units=m \ -o out.json # Apply the same projection using an EPSG code mapshaper nyc.json -proj EPSG:2831 -o out.json # Convert a projected Shapefile to WGS84 coordinates mapshaper area.shp -proj wgs84 -o out.shp # Use the Winkel Tripel projection with a custom central meridian mapshaper countries.shp -proj +proj=wintri +lon_0=10 -o out.shp # Shortcut notation for the above projection mapshaper countries.shp -proj wintri +lon_0=10 -o out.shp # Convert an unprojected U.S. Shapefile into a composite projection with Alaska # and Hawaii repositioned and rescaled to fit in the lower left corner. # Show Puerto Rico and the U.S. Virgin Islands # Override the default central meridian and scale of the Alaska inset mapshaper us_states.shp \ -proj albersusa +PR +VI +AK.lon_0=-141 +AK.scale=0.4 \ -o out.shp ``` ### -rectangle Create a new layer containing a rectangular polygon. `bbox=` 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. `` 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). `` or `names=` One or more layer names (comma-separated). `target=` Rename a subset of all layers. ```bash # Example: Create a TopoJSON file with sensible object names. mapshaper ne_50m_rivers_lake_centerlines.shp ne_50m_land.shp combine-files \ -rename-layers water,land -o target=* layers.topojson ``` ### -require Require a Node module or ES module for use in commands like `-each` and `-run`. Modules are added to the expression context. When the `alias=` option is given, modules are accessed via their aliases. Modules that are imported by name (e.g. `-require d3`) are accessed via their name, or by their alias if the `alias=` option is used. Module files without an alias name have their exported functions and data added directly to the expression context. `` or `module=` Name of an installed module or path to a module file. `alias=` Import the module as a custom-named variable. ```bash # Example: use the underscore module (which has been installed locally) $ mapshaper data.json \ -require underscore alias=_ \ -each 'id = _.uniqueId()' \ -o data2.json ``` ```bash # Example: import a module file containing a user-defined function $ mapshaper data.json \ -require scripts/includes.mjs \ -each 'displayname = getDisplayName(d)' \ -o data2.json ``` ### -run Run mapshaper commands from a [command file](#command-files) or generated on-the-fly from a JS expression. `` Either: - A path to a mapshaper [command file](#command-files). - A JS expression or template containing embedded expressions, for generating one or more mapshaper commands. * Embedded expressions are enclosed in curly braces (see below). * Expressions can access `target` and `io` objects. * Expressions can also access functions and data loaded with the `-require` command. * Functions can be async. Expression context: If command has a single target layer: `target` object provides data and information about the command's target layer - `target.layer_name` Name of layer - `target.geojson` (getter/setter) Returns a GeoJSON FeatureCollection for the layer (getter) or replaces the layer with the contents of a GeoJSON object (setter). - `target.geometry_type` One of: polygon, polyline, point, `undefined` - `target.feature_count` Number of features in the layer - `target.null_shape_count` Number of features with null geometry - `target.null_data_count` Number of features with no attribute data - `target.bbox` GeoJSON-style bounding box - `target.proj4` PROJ-formatted string giving the CRS (coordinate reference system) of the layer `targets` object gives access to all layers targetted by the run command. - by numerical index, like an array (`targets[0]` refers to the first target layer) - by layer name (`targets.states` refers to a layer named "states") `io` object has a method for passing data to the `-i` command. - `io.ifile(, )` 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. `