mapshaper 0.6.121 → 0.7.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +5 -3
- package/mapshaper.js +1342 -275
- package/package.json +5 -2
- package/www/assets/jetbrains-mono-regular.woff2 +0 -0
- package/www/assets/static-page.css +179 -0
- package/www/docs/_assets/cmd-search.js +213 -0
- package/www/docs/_assets/docs.css +712 -0
- package/www/docs/_assets/docs.js +75 -0
- package/www/docs/_assets/highlight.css +10 -0
- package/www/docs/essentials/command-line.html +127 -0
- package/www/docs/essentials/command-line.html.md +112 -0
- package/www/docs/essentials/web-app.html +138 -0
- package/www/docs/essentials/web-app.html.md +106 -0
- package/www/docs/examples/basics.html +276 -0
- package/www/docs/examples/basics.html.md +371 -0
- package/www/docs/examples/data/Makefile +31 -0
- package/www/docs/examples/data/globe.msx +0 -0
- package/www/docs/examples/data/globe.svg +616 -0
- package/www/docs/examples/data/globe.txt +21 -0
- package/www/docs/examples/data/globe.zip +0 -0
- package/www/docs/examples/data/ne_50m_admin_0_countries.geojson +1 -0
- package/www/docs/examples/data/ne_50m_admin_1_states_provinces_lakes.geojson +1 -0
- package/www/docs/examples/data/us-states.msx +0 -0
- package/www/docs/examples/data/us-states.svg +56 -0
- package/www/docs/examples/data/us-states.txt +6 -0
- package/www/docs/examples/data/us-states.zip +0 -0
- package/www/docs/examples/globe.html +108 -0
- package/www/docs/examples/globe.html.md +64 -0
- package/www/docs/examples/us-states.html +88 -0
- package/www/docs/examples/us-states.html.md +44 -0
- package/www/docs/formats/csv.html +127 -0
- package/www/docs/formats/csv.html.md +97 -0
- package/www/docs/formats/dbf.html +87 -0
- package/www/docs/formats/dbf.html.md +39 -0
- package/www/docs/formats/flatgeobuf.html +86 -0
- package/www/docs/formats/flatgeobuf.html.md +42 -0
- package/www/docs/formats/geojson.html +107 -0
- package/www/docs/formats/geojson.html.md +65 -0
- package/www/docs/formats/geopackage.html +87 -0
- package/www/docs/formats/geopackage.html.md +42 -0
- package/www/docs/formats/json.html +83 -0
- package/www/docs/formats/json.html.md +35 -0
- package/www/docs/formats/kml.html +82 -0
- package/www/docs/formats/kml.html.md +39 -0
- package/www/docs/formats/overview.html +192 -0
- package/www/docs/formats/overview.html.md +35 -0
- package/www/docs/formats/shapefile.html +123 -0
- package/www/docs/formats/shapefile.html.md +84 -0
- package/www/docs/formats/snapshot.html +87 -0
- package/www/docs/formats/snapshot.html.md +39 -0
- package/www/docs/formats/svg.html +99 -0
- package/www/docs/formats/svg.html.md +51 -0
- package/www/docs/formats/topojson.html +102 -0
- package/www/docs/formats/topojson.html.md +54 -0
- package/www/docs/gallery/index.html +80 -0
- package/www/docs/gallery/index.html.md +29 -0
- package/www/docs/guides/combining-layers.html +105 -0
- package/www/docs/guides/combining-layers.html.md +81 -0
- package/www/docs/guides/expressions.html +600 -0
- package/www/docs/guides/expressions.html.md +376 -0
- package/www/docs/guides/programmatic.html +117 -0
- package/www/docs/guides/programmatic.html.md +91 -0
- package/www/docs/guides/projections.html +158 -0
- package/www/docs/guides/projections.html.md +118 -0
- package/www/docs/guides/simplification.html +110 -0
- package/www/docs/guides/simplification.html.md +94 -0
- package/www/docs/guides/topology.html +90 -0
- package/www/docs/guides/topology.html.md +63 -0
- package/www/docs/images/simplification-detail.png +0 -0
- package/www/docs/images/simplification-dp.png +0 -0
- package/www/docs/images/simplification-mod2.png +0 -0
- package/www/docs/index.html +101 -0
- package/www/docs/index.html.md +59 -0
- package/www/docs/reference.html +1302 -0
- package/www/docs/reference.html.md +1817 -0
- package/www/docs/whats-new.html +76 -0
- package/www/docs/whats-new.html.md +53 -0
- package/www/index.html +30 -3
- package/www/llms-full.txt +4040 -0
- package/www/llms.txt +55 -0
- package/www/mapshaper-gui.js +7 -1
- package/www/mapshaper.js +1342 -275
- package/www/page.css +1 -1
- package/www/privacy.html +1 -112
- package/www/sponsor.html +4 -164
- package/www/terms.html +1 -112
|
@@ -0,0 +1,1302 @@
|
|
|
1
|
+
<!DOCTYPE html>
|
|
2
|
+
<html lang="en">
|
|
3
|
+
<head>
|
|
4
|
+
<meta charset="UTF-8">
|
|
5
|
+
<meta name="viewport" content="width=device-width, initial-scale=1">
|
|
6
|
+
<title>Command reference · mapshaper docs</title>
|
|
7
|
+
<meta name="description" content="">
|
|
8
|
+
<link rel="icon" type="image/png" href="/images/icon.png">
|
|
9
|
+
<link rel="stylesheet" href="/docs/_assets/highlight.css">
|
|
10
|
+
<link rel="stylesheet" href="/docs/_assets/docs.css">
|
|
11
|
+
</head>
|
|
12
|
+
<body class="">
|
|
13
|
+
|
|
14
|
+
<header class="page-header">
|
|
15
|
+
<a href="/" class="mapshaper-logo">map<span class="logo-highlight">shaper</span></a>
|
|
16
|
+
<span class="header-section-label">Docs</span>
|
|
17
|
+
<nav class="header-nav">
|
|
18
|
+
<a href="/">Web app</a>
|
|
19
|
+
<a href="https://github.com/mbloch/mapshaper">GitHub</a>
|
|
20
|
+
<a href="/sponsor.html" class="sponsor-link"><svg viewBox="0 0 24 24" aria-hidden="true"><path d="M12 21.35l-1.45-1.32C5.4 15.36 2 12.28 2 8.5 2 5.42 4.42 3 7.5 3c1.74 0 3.41.81 4.5 2.09C13.09 3.81 14.76 3 16.5 3 19.58 3 22 5.42 22 8.5c0 3.78-3.4 6.86-8.55 11.54L12 21.35z"/></svg> Become a sponsor</a>
|
|
21
|
+
</nav>
|
|
22
|
+
</header>
|
|
23
|
+
|
|
24
|
+
<div class="docs-layout">
|
|
25
|
+
|
|
26
|
+
<aside class="docs-sidebar">
|
|
27
|
+
<div class="sidebar-inner">
|
|
28
|
+
<nav class="docs-nav"><ul class="top-links"><li><a href="/docs/">Home</a></li><li><a href="/docs/whats-new.html">What's new</a></li><li><a href="/docs/reference.html" class="is-active">Command reference</a></li><li><a href="/docs/gallery/">Gallery</a></li></ul><h2>Getting started</h2><ul><li><a href="/docs/essentials/command-line.html">The command-line tool</a></li><li><a href="/docs/essentials/web-app.html">The web app</a></li></ul><h2>Guides</h2><ul><li><a href="/docs/guides/simplification.html">Simplification</a></li><li><a href="/docs/guides/expressions.html">JavaScript expressions</a></li><li><a href="/docs/guides/projections.html">Projections</a></li><li><a href="/docs/guides/topology.html">Topology and cleaning</a></li><li><a href="/docs/guides/combining-layers.html">Combining two layers</a></li><li><a href="/docs/guides/programmatic.html">Using Mapshaper from Node.js</a></li></ul><h2>Formats</h2><ul><li><a href="/docs/formats/overview.html">Overview</a></li><li><a href="/docs/formats/shapefile.html">Shapefile</a></li><li><a href="/docs/formats/geojson.html">GeoJSON</a></li><li><a href="/docs/formats/topojson.html">TopoJSON</a></li><li><a href="/docs/formats/geopackage.html">GeoPackage</a></li><li><a href="/docs/formats/flatgeobuf.html">FlatGeobuf</a></li><li><a href="/docs/formats/kml.html">KML / KMZ</a></li><li><a href="/docs/formats/csv.html">CSV / TSV</a></li><li><a href="/docs/formats/dbf.html">DBF</a></li><li><a href="/docs/formats/json.html">JSON records</a></li><li><a href="/docs/formats/svg.html">SVG</a></li><li><a href="/docs/formats/snapshot.html">Mapshaper snapshot</a></li></ul><h2>Examples</h2><ul><li><a href="/docs/examples/basics.html">Basics</a></li><li><a href="/docs/examples/globe.html">Globe</a></li><li><a href="/docs/examples/us-states.html">U.S. state map</a></li></ul></nav>
|
|
29
|
+
</div>
|
|
30
|
+
</aside>
|
|
31
|
+
|
|
32
|
+
<main class="docs-main">
|
|
33
|
+
<article class="docs-article">
|
|
34
|
+
|
|
35
|
+
<h1 id="command-reference">Command reference</h1>
|
|
36
|
+
<div class="cmd-search-wrap"><input type="search" class="cmd-search-input" placeholder="Jump to a command" autocomplete="off" spellcheck="false" role="combobox" aria-autocomplete="list" aria-expanded="false" aria-controls="cmd-search-results" aria-label="Jump to a command"><div class="cmd-search-results" id="cmd-search-results" role="listbox" hidden><div class="cmd-search-status" aria-live="polite"></div><ul class="cmd-search-list"></ul></div></div><h2 id="command-line-syntax">Command line syntax</h2>
|
|
37
|
+
<p>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 <code>-i</code> can be omitted.</p>
|
|
38
|
+
<h4 id="example">Example</h4>
|
|
39
|
+
<pre><code class="hljs language-bash"><span class="hljs-comment"># Read a Shapefile, simplify using Douglas-Peucker, output as GeoJSON.</span>
|
|
40
|
+
mapshaper provinces.shp -simplify dp 20% -o precision=0.00001 output.geojson
|
|
41
|
+
</code></pre>
|
|
42
|
+
<h3 id="command-options-can-take-three-forms">Command options can take three forms:</h3>
|
|
43
|
+
<ul>
|
|
44
|
+
<li><p>Values, like <code>provinces.shp</code> and <code>output.geojson</code> in the above example</p>
|
|
45
|
+
</li>
|
|
46
|
+
<li><p>Flags, like <code>dp</code></p>
|
|
47
|
+
</li>
|
|
48
|
+
<li><p>Name/value pairs, like <code>precision=0.00001</code></p>
|
|
49
|
+
</li>
|
|
50
|
+
</ul>
|
|
51
|
+
<h3 id="common-options">Common options</h3>
|
|
52
|
+
<p>The following options are documented here, because they are used by many commands.</p>
|
|
53
|
+
<p><code>name=</code> Rename the layer (or layers) modified by a command.</p>
|
|
54
|
+
<p><code>target=</code> 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 <code>*</code> wildcard.</p>
|
|
55
|
+
<p><code>+</code> Use the output of a command to create a new layer or layers instead of replacing the target layer(s). Use together with the <code>name=</code> option to assign a name to the new layer(s).</p>
|
|
56
|
+
<h4 id="example-2">Example</h4>
|
|
57
|
+
<pre><code class="hljs language-bash"><span class="hljs-comment"># Make a derived layer containing a subset of features</span>
|
|
58
|
+
<span class="hljs-comment"># while retaining the original layer</span>
|
|
59
|
+
mapshaper states.geojson -filter <span class="hljs-string">'ST == "AK"'</span> + name=alaska -o output/ target=*
|
|
60
|
+
</code></pre>
|
|
61
|
+
<h2 id="command-files">Command files</h2>
|
|
62
|
+
<p>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.</p>
|
|
63
|
+
<p>Command files offer a few conveniences over a shell script or Makefile:</p>
|
|
64
|
+
<ul>
|
|
65
|
+
<li>Hash-delimited (<code>#</code>) comments, both on their own line and at the end of a line.</li>
|
|
66
|
+
<li>No need to escape <code>*</code> or other shell metacharacters; commands aren't passed through the shell.</li>
|
|
67
|
+
<li>Trailing-backslash line continuations are accepted but not required — lines that don't begin with <code>-</code> are joined onto the previous command.</li>
|
|
68
|
+
<li>Variable interpolation using <code>{{VAR}}</code> placeholders. See <a href="#variables">variables</a> below.</li>
|
|
69
|
+
</ul>
|
|
70
|
+
<p>(Support for running command files in the mapshaper web UI is planned for a future release.)</p>
|
|
71
|
+
<h3 id="file-format">File format</h3>
|
|
72
|
+
<p>A mapshaper command file is a <code>.txt</code> file whose first non-blank, non-comment line starts with <code>mapshaper</code>.</p>
|
|
73
|
+
<pre><code>mapshaper
|
|
74
|
+
-i provinces.shp
|
|
75
|
+
# Use Douglas Peucker simplification
|
|
76
|
+
-simplify dp 20%
|
|
77
|
+
-o precision=0.00001 output.geojson
|
|
78
|
+
</code></pre>
|
|
79
|
+
<p>If you write the command file using shell-compatible syntax — trailing <code>\</code> for line continuations and no <code>#</code> comments — it can also be pasted directly onto a bash command line, where the leading <code>mapshaper</code> word invokes the CLI. To make the above example shell compatible, you could write:</p>
|
|
80
|
+
<pre><code>mapshaper \
|
|
81
|
+
-i provinces.shp \
|
|
82
|
+
-simplify dp 20% \
|
|
83
|
+
-o precision=0.00001 output.geojson
|
|
84
|
+
</code></pre>
|
|
85
|
+
<h3 id="running-a-command-file">Running a command file</h3>
|
|
86
|
+
<p>The command for running a command file is <a href="#-run"><code>-run</code></a>:</p>
|
|
87
|
+
<pre><code class="hljs language-bash">mapshaper -run build.txt
|
|
88
|
+
</code></pre>
|
|
89
|
+
<p><code>mapshaper commands.txt</code> is a shortcut for <code>mapshaper -run commands.txt</code>.</p>
|
|
90
|
+
<h2 id="variable-interpolation">Variable interpolation</h2>
|
|
91
|
+
<p>Command files and command lines may contain <code>{{VAR}}</code> placeholders, which are substituted just before each command runs. Two forms are recognized:</p>
|
|
92
|
+
<ul>
|
|
93
|
+
<li><code>{{VAR}}</code> — substituted with the value of <code>VAR</code>.</li>
|
|
94
|
+
<li><code>{{env.NAME}}</code> — substituted with the value of the <code>NAME</code> environment variable.</li>
|
|
95
|
+
</ul>
|
|
96
|
+
<p>This syntax allows you to interpolate all or part of a command option. For example, <code>-simplify {{SIMPLIFY_METHOD}} resolution={{SIMPLIFY_RESOLUTION}}</code>.</p>
|
|
97
|
+
<p>Variables can be set in several ways:</p>
|
|
98
|
+
<ul>
|
|
99
|
+
<li>The <a href="#-vars"><code>-vars</code></a> command sets one or more variables, always overwriting any previous value.</li>
|
|
100
|
+
<li>The <a href="#-defaults"><code>-defaults</code></a> command set only those values that do not already exist.</li>
|
|
101
|
+
<li>Assignments in <code>-calc</code> and <code>-define</code> expressions create new variables.</li>
|
|
102
|
+
<li>Assigning a property to the <code>global</code> object in an <code>-each</code> expression creates a new variable.</li>
|
|
103
|
+
</ul>
|
|
104
|
+
<p><code>-vars</code> and <code>-defaults</code> write to a templating-scope store; the other commands write to an expression-scope store (<code>global</code>). <code>{{X}}</code> 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 <code>-vars</code> is <em>not</em> readable by bare name from inside <code>-each</code>, <code>-filter</code>, etc. See <a href="/docs/guides/expressions.html#sharing-state-across-commands">JavaScript expressions</a> for the full story.</p>
|
|
105
|
+
<h4 id="example-3">Example</h4>
|
|
106
|
+
<p><code>build.txt</code>:</p>
|
|
107
|
+
<pre><code>mapshaper
|
|
108
|
+
-defaults YEAR=2024 PCT=10 # overridable defaults
|
|
109
|
+
-i sources/counties_{{YEAR}}.shp
|
|
110
|
+
-simplify {{PCT}}%
|
|
111
|
+
-o out/counties_{{YEAR}}_simplified.shp
|
|
112
|
+
</code></pre>
|
|
113
|
+
<p>Run with the command file's defaults:</p>
|
|
114
|
+
<pre><code class="hljs language-bash">mapshaper build.txt
|
|
115
|
+
</code></pre>
|
|
116
|
+
<p>Or override default values from the command line:</p>
|
|
117
|
+
<pre><code class="hljs language-bash">mapshaper -vars YEAR=2030 PCT=5 -run build.txt
|
|
118
|
+
</code></pre>
|
|
119
|
+
<h2 id="index-of-commands">Index of commands</h2>
|
|
120
|
+
<p><strong>File I/O</strong></p>
|
|
121
|
+
<p><a href="#-i-input">-i (input)</a>
|
|
122
|
+
<a href="#-o-output">-o (output)</a></p>
|
|
123
|
+
<p><strong>Editing</strong></p>
|
|
124
|
+
<p><a href="#-affine">-affine</a>
|
|
125
|
+
<a href="#-classify">-classify</a>
|
|
126
|
+
<a href="#-clean">-clean</a>
|
|
127
|
+
<a href="#-clip">-clip</a>
|
|
128
|
+
<a href="#-colorizer">-colorizer</a>
|
|
129
|
+
<a href="#-dashlines">-dashlines</a>
|
|
130
|
+
<a href="#-dissolve">-dissolve</a>
|
|
131
|
+
<a href="#-dissolve2">-dissolve2</a>
|
|
132
|
+
<a href="#-divide">-divide</a>
|
|
133
|
+
<a href="#-dots">-dots</a>
|
|
134
|
+
<a href="#-drop">-drop</a>
|
|
135
|
+
<a href="#-each">-each</a>
|
|
136
|
+
<a href="#-erase">-erase</a>
|
|
137
|
+
<a href="#-explode">-explode</a>
|
|
138
|
+
<a href="#-filter">-filter</a>
|
|
139
|
+
<a href="#-filter-fields">-filter-fields</a>
|
|
140
|
+
<a href="#-filter-islands">-filter-islands</a>
|
|
141
|
+
<a href="#-filter-slivers">-filter-slivers</a>
|
|
142
|
+
<a href="#-frame">-frame</a>
|
|
143
|
+
<a href="#-graticule">-graticule</a>
|
|
144
|
+
<a href="#-grid">-grid</a>
|
|
145
|
+
<a href="#-include">-include</a>
|
|
146
|
+
<a href="#-inlay">-inlay</a>
|
|
147
|
+
<a href="#-innerlines">-innerlines</a>
|
|
148
|
+
<a href="#-join">-join</a>
|
|
149
|
+
<a href="#-lines">-lines</a>
|
|
150
|
+
<a href="#-merge-layers">-merge-layers</a>
|
|
151
|
+
<a href="#-mosaic">-mosaic</a>
|
|
152
|
+
<a href="#-point-grid">-point-grid</a>
|
|
153
|
+
<a href="#-points">-points</a>
|
|
154
|
+
<a href="#-polygons">-polygons</a>
|
|
155
|
+
<a href="#-proj">-proj</a>
|
|
156
|
+
<a href="#-rectangle">-rectangle</a>
|
|
157
|
+
<a href="#-rectangles">-rectangles</a>
|
|
158
|
+
<a href="#-rename-fields">-rename-fields</a>
|
|
159
|
+
<a href="#-rename-layers">-rename-layers</a>
|
|
160
|
+
<a href="#-require">-require</a>
|
|
161
|
+
<a href="#-run">-run</a>
|
|
162
|
+
<a href="#-scalebar">-scalebar</a>
|
|
163
|
+
<a href="#-shape">-shape</a>
|
|
164
|
+
<a href="#-simplify">-simplify</a>
|
|
165
|
+
<a href="#-snap">-snap</a>
|
|
166
|
+
<a href="#-sort">-sort</a>
|
|
167
|
+
<a href="#-split">-split</a>
|
|
168
|
+
<a href="#-split-on-grid">-split-on-grid</a>
|
|
169
|
+
<a href="#-subdivide">-subdivide</a>
|
|
170
|
+
<a href="#-style">-style</a>
|
|
171
|
+
<a href="#-symbols">-symbols</a>
|
|
172
|
+
<a href="#-union">-union</a>
|
|
173
|
+
<a href="#-uniq">-uniq</a></p>
|
|
174
|
+
<p><strong>Control Flow</strong></p>
|
|
175
|
+
<p><a href="#-if">-if</a>
|
|
176
|
+
<a href="#-elif">-elif</a>
|
|
177
|
+
<a href="#-else">-else</a>
|
|
178
|
+
<a href="#-endif">-endif</a>
|
|
179
|
+
<a href="#-stop">-stop</a>
|
|
180
|
+
<a href="#-target">-target</a></p>
|
|
181
|
+
<p><strong>Information</strong></p>
|
|
182
|
+
<p><a href="#-calc">-calc</a>
|
|
183
|
+
<a href="#-colors">-colors</a>
|
|
184
|
+
<a href="#-comment">-comment</a>
|
|
185
|
+
<a href="#-defaults">-defaults</a>
|
|
186
|
+
<a href="#-encodings">-encodings</a>
|
|
187
|
+
<a href="#-help">-help</a>
|
|
188
|
+
<a href="#-info">-info</a>
|
|
189
|
+
<a href="#-inspect">-inspect</a>
|
|
190
|
+
<a href="#-print">-print</a>
|
|
191
|
+
<a href="#-projections">-projections</a>
|
|
192
|
+
<a href="#-quiet">-quiet</a>
|
|
193
|
+
<a href="#-vars">-vars</a>
|
|
194
|
+
<a href="#-verbose">-verbose</a>
|
|
195
|
+
<a href="#-version">-version</a></p>
|
|
196
|
+
<h2 id="i-o-commands" class="cmd-category">I/O Commands</h2>
|
|
197
|
+
<section class="cmd-section" data-id="-i-input" data-name="-i (input)" data-options="mapshaper combine-files batch-mode files merge-files snap snap-interval precision no-topology encoding id-field string-fields field-types csv-skip-lines csv-lines csv-field-names csv-fields decimal-comma csv-dedup-fields csv-filter json-path layers name"><h3 id="-i-input">-i (input)</h3>
|
|
198
|
+
<p>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.</p>
|
|
199
|
+
<p>The <code>-i</code> command is assumed if <code>mapshaper</code> is followed by the path of an input data file.</p>
|
|
200
|
+
<p>Mapshaper does not fully support M and Z type Shapefiles. The M and Z data is lost when these files are imported.</p>
|
|
201
|
+
<p>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 <code>combine-files</code> to process them together, or <code>batch-mode</code> to process them separately.</p>
|
|
202
|
+
<p>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 <code>batch-mode</code> flag.</p>
|
|
203
|
+
<p><strong>Options</strong></p>
|
|
204
|
+
<p><code><files></code> or <code>files=</code> File(s) to input (space-separated list). Use <code>-</code> to import from <code>/dev/stdin</code>.</p>
|
|
205
|
+
<p>In place of a file name, you can also pass data inline:</p>
|
|
206
|
+
<ul>
|
|
207
|
+
<li><strong>JSON.</strong> A string starting with <code>{</code> or <code>[</code> is treated as a literal JSON object or array.</li>
|
|
208
|
+
<li><strong>CSV.</strong> A comma-delimited string is treated as inline CSV when it contains a newline (a real one or the literal escape sequence <code>\n</code>) and both the first and second lines contain at least one comma.</li>
|
|
209
|
+
</ul>
|
|
210
|
+
<pre><code class="hljs language-bash">mapshaper -i <span class="hljs-string">'lat,lon,label\n48.86,2.35,Paris\n51.51,-0.13,London'</span> -o cities.json
|
|
211
|
+
</code></pre>
|
|
212
|
+
<p><code>combine-files</code> Import multiple files to separate layers with shared topology. Useful for generating a single TopoJSON file containing multiple geometry objects.</p>
|
|
213
|
+
<p><code>batch-mode</code> Apply subsequent commands separately to each input file, as if running mapshaper multiple times with the same set of commands. Used together with <code>-o</code> to transform a directory of files. Required (in a future release) to use this batch-processing behavior.</p>
|
|
214
|
+
<p><code>merge-files</code> (Deprecated) Merge features from multiple input files into as few layers as possible. Preferred method: import files to separate layers using <code>-i combine-files</code>, then use the <code>-merge-layers</code> command to merge layers. </p>
|
|
215
|
+
<p><code>snap</code> 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.</p>
|
|
216
|
+
<p><code>snap-interval=</code> Specify snapping distance in source units.</p>
|
|
217
|
+
<p><code>precision=</code> (Deprecated) Round all coordinates to a specified precision, e.g. <code>0.001</code>. It is recommended to set coordinate precision on export, using <code>-o precision=</code>.</p>
|
|
218
|
+
<p><code>no-topology</code> Skip topology identification to speed up processing of large files. For use with commands like <code>-filter</code> that don't require topology.</p>
|
|
219
|
+
<p><code>encoding=</code> Specify encoding used for reading .dbf files and delimited text files. If the <code>encoding</code> option is missing, mapshaper will try to detect the encoding of .dbf files. Dbf encoding can also be set using a .cpg file.</p>
|
|
220
|
+
<p><code>id-field=</code> (Topo/GeoJSON) Import values of "id" property to this data field.</p>
|
|
221
|
+
<p><code>string-fields=</code> (CSV) List of fields to import as strings (e.g. FIPS,ZIPCODE). Using <code>string-fields=*</code> imports all fields as strings.</p>
|
|
222
|
+
<p><code>field-types=</code> Type hints for importing delimited text. Takes a comma-separated list of field names with type hints appended; e.g. <code>FIPS:str,zipcode:str</code>. Recognized type hints include <code>:str</code> or <code>:string</code>, <code>:num</code> or <code>:number</code>. Without a type hint, fields containing text data that looks like numeric data, like ZIP Codes, will be converted to numbers.</p>
|
|
223
|
+
<p><code>csv-skip-lines=</code> 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.</p>
|
|
224
|
+
<p><code>csv-lines=</code> Number of data records to import from a CSV file (default is all).</p>
|
|
225
|
+
<p><code>csv-field-names=</code> Comma-sep. list of names to assign each field. Can be used in conjunction with <code>csv-skip-lines=1</code> to replace names from an existing set of field headers.</p>
|
|
226
|
+
<p><code>csv-fields=</code> 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.</p>
|
|
227
|
+
<p><code>decimal-comma</code> Import numbers formatted with decimal commas, not decimal points. Accepted formats: <code>1.000,01</code> <code>1 000,01</code> (both imported as as 1000.01).</p>
|
|
228
|
+
<p><code>csv-dedup-fields</code> Assign unique names to CSV fields with duplicate names.</p>
|
|
229
|
+
<p><code>csv-filter=</code> 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.</p>
|
|
230
|
+
<p><code>json-path=</code> [JSON] Path to an array of data records or a GeoJSON object. For example, <code>json-path=data/counties</code> expects a JSON object with the following structure <code>{"data": {"counties": []}}</code>.</p>
|
|
231
|
+
<p><code>layers=</code> [GeoPackage] Comma-separated list of layer names to import from a GeoPackage file. If omitted, all layers are imported.</p>
|
|
232
|
+
<p><code>name=</code> Rename the imported layer (or layers).</p>
|
|
233
|
+
<p><strong>Example</strong> </p>
|
|
234
|
+
<pre><code class="hljs language-bash"><span class="hljs-comment"># Input a Shapefile with text data in the latin1 encoding</span>
|
|
235
|
+
<span class="hljs-comment"># and see what kind of data it contains</span>
|
|
236
|
+
mapshaper countries_wgs84.shp encoding=latin1 -info
|
|
237
|
+
</code></pre>
|
|
238
|
+
</section>
|
|
239
|
+
<section class="cmd-section" data-id="-o-output" data-name="-o (output)" data-options="format json target force gzip zip cut-table drop-table precision fix-geometry bbox-index encoding field-order id-field bbox extension prettify singles quantization no-quantization presimplify topojson-precision ndjson gj2008 combine-layers geojson-type no-null-props hoist width height max-height margin pixels id-prefix svg-data svg-scale delimiter decimal-comma show-all"><h3 id="-o-output">-o (output)</h3>
|
|
240
|
+
<p>Save content of the target layer(s) to a file or files.</p>
|
|
241
|
+
<p><strong>Options</strong></p>
|
|
242
|
+
<p><code><file>|<directory>|-</code> Name of output file or directory. Use <code>-</code> to export text-based formats to <code>/dev/stdout</code>.</p>
|
|
243
|
+
<p><code>format=shapefile|geojson|topojson|flatgeobuf|geopackage|json|dbf|csv|tsv|svg</code> Specify output format. If the <code>format=</code> 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 <code>json</code> format is an array of objects containing data properties for each feature.</p>
|
|
244
|
+
<p><code>target=</code> Specify layer(s) to export (comma-separated list). The default target is the output layer(s) of the previous command. Use <code>target=*</code> to select all layers.</p>
|
|
245
|
+
<p><code>force</code> Allow output files to overwrite input files (without this option, overwriting input files is not allowed).</p>
|
|
246
|
+
<p><code>gzip</code> Apply gzip compression to output files.</p>
|
|
247
|
+
<p><code>zip</code> Save output files in a single .zip archive.</p>
|
|
248
|
+
<p><code>cut-table</code> Detach attribute data from shapes and save as a JSON file.</p>
|
|
249
|
+
<p><code>drop-table</code> Remove attribute data from output.</p>
|
|
250
|
+
<p><code>precision=</code> Round all coordinates to a specified precision, e.g. <code>precision=0.001</code>. Useful for reducing the size of GeoJSON files.</p>
|
|
251
|
+
<p><code>fix-geometry</code> Remove segment intersections caused by rounding (via the <code>precision=</code> 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.</p>
|
|
252
|
+
<p><code>bbox-index</code> Export a JSON file containing bounding boxes of each output layer.</p>
|
|
253
|
+
<p><code>encoding=</code> (Shapefile/CSV) Encoding of input text (by default, Shapefile encoding is auto-detected and CSV files are assumed to be UTF-8).</p>
|
|
254
|
+
<p><code>field-order=</code> (Shapefile/CSV) <code>field-order=ascending</code> sorts data fields in alphabetical order of field names (A-Z, case-insensitive).</p>
|
|
255
|
+
<p><code>id-field=</code> (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.</p>
|
|
256
|
+
<p><code>bbox</code> (Topo/GeoJSON) Add bbox property to the top-level object.</p>
|
|
257
|
+
<p><code>extension=</code> (Topo/GeoJSON) set file extension (default is ".json").</p>
|
|
258
|
+
<p><code>prettify</code> (Topo/GeoJSON) Format output for readability.</p>
|
|
259
|
+
<p><code>singles</code> (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. </p>
|
|
260
|
+
<p><code>quantization=</code> (TopoJSON) Specify quantization as the maximum number of differentiable points along either dimension. Equivalent to the quantization parameter used by the <a href="https://github.com/topojson/topojson-client#topoquantize">topoquantize</a> command line program. By default, mapshaper applies quantization equivalent to 0.02 of the average segment length.</p>
|
|
261
|
+
<p><code>no-quantization</code> (TopoJSON) Arc coordinates are encoded at full precision and without delta-encoding.</p>
|
|
262
|
+
<p><code>presimplify</code> (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: <code>pz > 0 && pz < 10000 / (W * S)</code>.</p>
|
|
263
|
+
<p><code>topojson-precision=</code> (TopoJSON) Set quantization as a fraction of the average segment length.</p>
|
|
264
|
+
<p><code>ndjson</code> (GeoJSON/JSON) Output newline-delimited records.</p>
|
|
265
|
+
<p><code>gj2008</code> (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).</p>
|
|
266
|
+
<p><code>combine-layers</code> (GeoJSON) Combine multiple output layers into a single GeoJSON file.</p>
|
|
267
|
+
<p><code>geojson-type=</code> (GeoJSON) Overrides the default output type. Possible values: "FeatureCollection", "GeometryCollection", "Feature" (for a single feature).</p>
|
|
268
|
+
<p><code>no-null-props</code> (GeoJSON) use <code>"properties": {}</code> instead of <code>"properties": null</code> when outputting a Feature with no attribute data.</p>
|
|
269
|
+
<p><code>hoist=</code> (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).</p>
|
|
270
|
+
<p><code>width=</code> (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).</p>
|
|
271
|
+
<p><code>height=</code> (SVG/TopoJSON) Similar to the <code>width</code> option. If both <code>height</code> and <code>width</code> are set, content is centered inside the <code>[0, 0, width, height]</code> bounding box.</p>
|
|
272
|
+
<p><code>max-height=</code> (SVG/TopoJSON) Limit output height (units: pixels).</p>
|
|
273
|
+
<p><code>margin=</code> (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 <code><left,bottom,right,top></code> (similar to the <code>bbox=</code> option found in other commands).</p>
|
|
274
|
+
<p><code>pixels=</code> (SVG/TopoJSON) Output area in pixels (alternative to width=).</p>
|
|
275
|
+
<p><code>id-prefix=</code> Prefix for namespacing layer and feature ids.</p>
|
|
276
|
+
<p><code>svg-data=</code> (SVG) Export a comma-seperated list of data fields as SVG data-* attributes. Attribute names should match the following regex pattern: <code>/^[a-z_][a-z0-9_-]*$/</code>. Non-conforming fields are skipped.</p>
|
|
277
|
+
<p><code>svg-scale=</code> (SVG) Scale SVG output using geographical units per pixel (an alternative to the <code>width=</code> option).</p>
|
|
278
|
+
<p><code>svg-bbox=<xmin,ymin,xmax,ymax></code> (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.</p>
|
|
279
|
+
<p><code>fit-extent=<layer id></code> (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.</p>
|
|
280
|
+
<p><code>point-symbol=square</code> (SVG) Use squares instead of circles to symbolize point data.</p>
|
|
281
|
+
<p><code>delimiter=</code> (CSV) Set the field delimiter for CSV/delimited text output; e.g. <code>delimiter=|</code>.</p>
|
|
282
|
+
<p><code>decimal-comma</code> (CSV) Export numbers with decimal commas instead of decimal points (common in Europe and elsewhere).</p>
|
|
283
|
+
<p><code>show-all</code> [Snapshot] All layers of the exported snapshot will be displayed when opened in the web UI.</p>
|
|
284
|
+
<p><strong>Example</strong></p>
|
|
285
|
+
<pre><code class="hljs language-bash"><span class="hljs-comment"># Convert all the Shapefiles in one directory into GeoJSON</span>
|
|
286
|
+
<span class="hljs-comment"># files in a different directory.</span>
|
|
287
|
+
mapshaper -i shapefiles/*.shp batch-mode -o geojson/ format=geojson
|
|
288
|
+
</code></pre>
|
|
289
|
+
</section>
|
|
290
|
+
<h2 id="editing-commands" class="cmd-category">Editing Commands</h2>
|
|
291
|
+
<section class="cmd-section" data-id="-affine" data-name="-affine" data-options="shift scale rotate anchor where target"><h3 id="-affine">-affine</h3>
|
|
292
|
+
<p>Transform coordinates by shifting, scaling and rotating. Not recommended for unprojected datasets.</p>
|
|
293
|
+
<p><code>shift=</code> X,Y shift in source units (e.g. 5000,-5000)</p>
|
|
294
|
+
<p><code>scale=</code> Scale (default is 1)</p>
|
|
295
|
+
<p><code>rotate=</code> Angle of rotation in degrees (default is 0)</p>
|
|
296
|
+
<p><code>anchor=</code> Center of rotation/scaling (default is center of the bounding box of the selected content)</p>
|
|
297
|
+
<p><code>where=</code> Use a JS expression to select a subset of features.</p>
|
|
298
|
+
<p>Common options: <code>target=</code></p>
|
|
299
|
+
</section>
|
|
300
|
+
<section class="cmd-section" data-id="-classify" data-name="-classify" data-options="quantile equal-interval hybrid nice field save-as fill stroke class values classes breaks colors random non-adjacent stops null-value outer-breaks continuous method categorical indexed index-field categories invert precision other key-style key-width key-font-size key-tile-height key-tic-length key-label-suffix key-last-suffix"><h3 id="-classify">-classify</h3>
|
|
301
|
+
<p>Assign colors or data values to each feature using one of several classification methods. Methods for sequential data include <code>quantile</code>, <code>equal-interval</code>, <code>hybrid</code> and <code>nice</code> or categorical classification to a data field.</p>
|
|
302
|
+
<p><code><field></code> or <code>field=</code> Name of the data field to classify.</p>
|
|
303
|
+
<p><code>save-as=</code> Name of a (new or existing) field to receive the output of classification. The default output field for colors is <code>fill</code> or <code>stroke</code> (depending on geometry type) and <code>class</code> for non-color output.</p>
|
|
304
|
+
<p><code>values=</code> List of values to assign to data classes. If the number of values differs from the number of classes given by the (optional) <code>classes</code> or <code>breaks</code> option, then interpolated values will be calculated. Mapshaper uses d3 for interpolation.</p>
|
|
305
|
+
<p><code>colors=</code> Takes a list of CSS colors, the name of a predefined color scheme, or <code>random</code>. Run the <a href="#-colors">-colors</a> command to list all of the built-in color schemes. Similar to the <code>values=</code> option, if the number of listed colors is different from the number of requested classes, interpolated colors are calculated.</p>
|
|
306
|
+
<p><code>non-adjacent</code> 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.</p>
|
|
307
|
+
<p><code>stops=</code> A pair of comma-separated numbers (0-100) for limiting the output range of a color ramp.</p>
|
|
308
|
+
<p><code>null-value=</code> Value (or color) to use for invalid or missing data.</p>
|
|
309
|
+
<p><code>classes=</code> Number of data classes. This number can also be inferred from the <code>breaks=</code> or <code>values=</code> options.</p>
|
|
310
|
+
<p><code>breaks=</code> Specify user-defined sequential class breaks (an alternative to automatic classification using <code>quantile</code>, <code>equal-interval</code>, etc.).</p>
|
|
311
|
+
<p><code>outer-breaks=</code> 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 <code>continuous</code> option).</p>
|
|
312
|
+
<p><code>method=</code> Classification method. One of: <code>quantile</code>, <code>equal-interval</code>, <code>nice</code>, <code>hybrid</code> (sequential data), <code>categorical</code>, <code>non-adjacent</code> and <code>indexed</code>. This parameter is not required if the classification method can be inferred from other options. For example, the <code>index-field=</code> parameter implies indexed classification, the <code>categories=</code> parameter implies categorical classification.</p>
|
|
313
|
+
<p><code>quantile</code> Use quantile classification. Shortcut for <code>method=quantile</code>.</p>
|
|
314
|
+
<p><code>equal-interval</code> Use equal interval classification. Shortcut for <code>method=equal-interval</code>.</p>
|
|
315
|
+
<p><code>nice</code> Same as <code>method=nice</code>. This scheme finds equally spaced, round breakpoints that roughly divide the dataset into equal parts (similar to quantile classification).</p>
|
|
316
|
+
<p><code>invert</code> Reverse the order of colors/values.</p>
|
|
317
|
+
<p><code>continuous</code> 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.</p>
|
|
318
|
+
<p><code>index-field=</code> Use class ids that have been precalculated and assigned to this field. Values should be integers from <code>0 ... n-1</code> (where n is the number of classes). <code>-1</code> is the null value.</p>
|
|
319
|
+
<p><code>precision=</code> Round data values before classification (e.g. <code>precision=0.1</code>).</p>
|
|
320
|
+
<p><code>categories=</code> List of values in the source data field. Using this option triggers categorical classification.</p>
|
|
321
|
+
<p><code>other=</code> 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 <code>categories=</code>. Defaults to <code>null-value=</code> or null.</p>
|
|
322
|
+
<p><strong>Options for generating SVG keys</strong></p>
|
|
323
|
+
<p><code>key-style=</code> One of: simple, gradient, dataviz</p>
|
|
324
|
+
<p><code>key-name= </code> Name of output SVG file</p>
|
|
325
|
+
<p><code>key-width=</code> Width of key in pixels</p>
|
|
326
|
+
<p><code>key-font-size=</code> Font size of tic labels in pixels</p>
|
|
327
|
+
<p><code>key-tile-height=</code> Height of color tiles in pixels</p>
|
|
328
|
+
<p><code>key-tic-length=</code> Length of tic mark in pixels</p>
|
|
329
|
+
<p><code>key-label-suffix=</code> String to append to each label</p>
|
|
330
|
+
<p><code>key-last-suffix=</code> String to append to the last label</p>
|
|
331
|
+
<p><strong>Examples</strong></p>
|
|
332
|
+
<pre><code class="hljs language-bash"><span class="hljs-comment"># Apply a sequential color ramp to a polygon dataset using quantiles.</span>
|
|
333
|
+
mapshaper covid_cases.geojson \
|
|
334
|
+
-classify save-as=fill quantile color-scheme=Oranges classes=6 \
|
|
335
|
+
-o out.geojson
|
|
336
|
+
</code></pre>
|
|
337
|
+
</section>
|
|
338
|
+
<section class="cmd-section" data-id="-clean" data-name="-clean" data-options="allow-empty gap-fill-area sliver-control overlap-rule allow-overlaps snap-interval rewind target"><h3 id="-clean">-clean</h3>
|
|
339
|
+
<p>This command attempts to repair various kinds of abnormal geometry that might cause problems when running other mapshaper commands or when using other software.</p>
|
|
340
|
+
<p>Features with null geometries are deleted, unless the <code>allow-empty</code> flag is used.</p>
|
|
341
|
+
<p>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.</p>
|
|
342
|
+
<p>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.</p>
|
|
343
|
+
<p>Point features are cleaned by removing duplicate coordinates within the same feature.</p>
|
|
344
|
+
<p><code>gap-fill-area=</code> (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.</p>
|
|
345
|
+
<p><code>sliver-control=</code> (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.</p>
|
|
346
|
+
<p><code>overlap-rule=</code> (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).</p>
|
|
347
|
+
<p><code>allow-overlaps</code> Allow features to overlap each other. The default behavior is to remove overlaps.</p>
|
|
348
|
+
<p><code>snap-interval=</code> Snap vertices within a given threshold before performing other kinds of geometry repair. Defaults to a very small threshold. Uses source units.</p>
|
|
349
|
+
<p><code>rewind</code> Fix errors in the winding order of polygon rings.</p>
|
|
350
|
+
<p><code>allow-empty</code> Allow null geometries, which are removed by default.</p>
|
|
351
|
+
<p>Common options: <code>target=</code></p>
|
|
352
|
+
</section>
|
|
353
|
+
<section class="cmd-section" data-id="-clip" data-name="-clip" data-options="source bbox2 bbox remove-slivers name target"><h3 id="-clip">-clip</h3>
|
|
354
|
+
<p>Remove features or portions of features that fall outside a clipping area.</p>
|
|
355
|
+
<p><code><source></code> or <code>source=</code> Clip to a set of polygon features. Takes the filename or layer id of the clip polygons.</p>
|
|
356
|
+
<p><code>bbox=<xmin,ymin,xmax,ymax></code> Delete features or portions of features that fall outside a bounding box.</p>
|
|
357
|
+
<p><code>bbox2=</code> Faster bounding box clipping than <code>bbox=</code> (experimental).</p>
|
|
358
|
+
<p><code>remove-slivers</code> Remove tiny sliver polygons created by clipping.</p>
|
|
359
|
+
<p>Common options: <a href="#common-options"><code>name=</code> <code>+</code> <code>target=</code></a></p>
|
|
360
|
+
<pre><code class="hljs language-bash"><span class="hljs-comment"># Example: Clip a polygon layer using another polygon layer.</span>
|
|
361
|
+
mapshaper usa_counties.shp -clip land-area.shp -o clipped.shp
|
|
362
|
+
</code></pre>
|
|
363
|
+
</section>
|
|
364
|
+
<section class="cmd-section" data-id="-colorizer" data-name="-colorizer" data-options="name colors random breaks categories other nodata precision"><h3 id="-colorizer">-colorizer</h3>
|
|
365
|
+
<p>Define a function for converting data values to colors that can be used in subsequent calls to the <code>-style</code> command.</p>
|
|
366
|
+
<p><code>name=</code> Name of the colorizer function.</p>
|
|
367
|
+
<p><code>colors=</code> List of CSS colors.</p>
|
|
368
|
+
<p><code>random</code> Randomly assign colors. Uses <code>colors=</code> list if given.</p>
|
|
369
|
+
<p><code>breaks=</code> Ascending-order list of breaks (thresholds) for creating a sequential color scheme.</p>
|
|
370
|
+
<p><code>categories=</code> List of data values (keys) for creating a categorical color scheme.</p>
|
|
371
|
+
<p><code>other=</code> Default color for categorical scheme (defaults to <code>nodata</code> color).</p>
|
|
372
|
+
<p><code>nodata=</code> Color to use for invalid or missing data (default is white).</p>
|
|
373
|
+
<p><code>precision=</code> Rounding precision to apply to numerical data before converting to a color (e.g. 0.1).</p>
|
|
374
|
+
<pre><code class="hljs language-bash"><span class="hljs-comment"># Example: define a function for a sequential color scheme</span>
|
|
375
|
+
<span class="hljs-comment"># and assign colors based on data values</span>
|
|
376
|
+
mapshaper data.json \
|
|
377
|
+
-colorizer name=getColor \
|
|
378
|
+
colors=<span class="hljs-string">'#f0f9e8,#bae4bc,#7bccc4,#2b8cbe'</span> breaks=25,50,75 \
|
|
379
|
+
-each <span class="hljs-string">'color = getColor(PCT)'</span> \
|
|
380
|
+
-o output.json
|
|
381
|
+
|
|
382
|
+
<span class="hljs-comment"># Example: define a function for a categorical color scheme</span>
|
|
383
|
+
<span class="hljs-comment"># and use it to assign fill colors</span>
|
|
384
|
+
mapshaper data.json \
|
|
385
|
+
-colorizer name=calcFill colors=<span class="hljs-string">'red,blue,green'</span> \
|
|
386
|
+
categories=<span class="hljs-string">'Republican,Democrat,Other'</span> \
|
|
387
|
+
-style fill=<span class="hljs-string">'calcFill(PARTY)'</span> \
|
|
388
|
+
-o output.svg
|
|
389
|
+
</code></pre>
|
|
390
|
+
</section>
|
|
391
|
+
<section class="cmd-section" data-id="-dashlines" data-name="-dashlines" data-options="dash-length gap-length scaled planar where"><h3 id="-dashlines">-dashlines</h3>
|
|
392
|
+
<p>Split lines into sections, with or without a gap.</p>
|
|
393
|
+
<p><code>dash-length=</code> Length of split-apart lines (e.g. 200km)
|
|
394
|
+
<code>gap-length=</code> Length of gaps between dashes (default is 0)
|
|
395
|
+
<code>scaled</code> Scale dashes and gaps to prevent partial dashes
|
|
396
|
+
<code>planar</code> Use planar geometry
|
|
397
|
+
<code>where=</code> Use a JS expression to select a subset of features.</p>
|
|
398
|
+
</section>
|
|
399
|
+
<section class="cmd-section" data-id="-dissolve" data-name="-dissolve" data-options="no-repair fields group-points weight planar gap-fill-area sliver-control allow-overlaps calc sum-fields copy-fields multipart where name target"><h3 id="-dissolve">-dissolve</h3>
|
|
400
|
+
<p>Aggregate groups of features using a data field, or aggregate all features if no field is given. For polygon layers, <code>-dissolve</code> merges adjacent polygons by erasing shared boundaries. For point layers, <code>-dissolve</code> replaces a group of points with their centroid. For polyline layers, <code>-dissolve</code> tries to merge contiguous polylines into as few polylines as possible.</p>
|
|
401
|
+
<p>For polygon layers, <code>-dissolve</code> repairs topology before dissolving, so it produces correct results on inputs that contain overlaps, gaps or other topology errors. The <code>no-repair</code> option skips this step for a faster (but less robust) dissolve.</p>
|
|
402
|
+
<p><code><fields></code> or <code>fields=</code> (optional) Name of a data field or fields to dissolve on. Accepts a comma-separated list of field names.</p>
|
|
403
|
+
<p><code>group-points</code> [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.</p>
|
|
404
|
+
<p><code>weight=</code> [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: <code> mapshaper census_tracts.shp -points -dissolve weight=POPULATION -o out.shp</code></p>
|
|
405
|
+
<p><code>planar</code> [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.)</p>
|
|
406
|
+
<p><code>gap-fill-area=</code> [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.</p>
|
|
407
|
+
<p><code>sliver-control=</code> [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.</p>
|
|
408
|
+
<p><code>allow-overlaps</code> [polygons] Allow dissolved groups of features to overlap each other. The default behavior is to remove overlaps.</p>
|
|
409
|
+
<p><code>no-repair</code> [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 <code>gap-fill-area=</code>, <code>sliver-control=</code> and <code>allow-overlaps</code>.</p>
|
|
410
|
+
<p><code>calc=</code> Use built-in JavaScript functions to create data fields in the dissolved layer. See example below; see <a href="#-calc">-calc</a> for a list of supported functions.</p>
|
|
411
|
+
<p><code>sum-fields=</code> Fields to sum when dissolving (comma-sep. list).</p>
|
|
412
|
+
<p><code>copy-fields=</code> Fields to copy when dissolving (comma-sep. list). Copies values from the first feature in each group of dissolved features.</p>
|
|
413
|
+
<p><code>multipart</code> Group features from the target layer into multipart features, without otherwise modifying geometry.</p>
|
|
414
|
+
<p><code>where=</code> Use a JS expression to select a subset of features to dissolve.</p>
|
|
415
|
+
<p>Common options: <code>name=</code> <code>+</code> <code>target=</code></p>
|
|
416
|
+
<pre><code class="hljs language-bash"><span class="hljs-comment"># Example: Aggregate county polygons to states</span>
|
|
417
|
+
mapshaper counties.shp -dissolve STATE -o states.shp
|
|
418
|
+
|
|
419
|
+
<span class="hljs-comment"># Example: Use the calc= option to count the number of dissolved features</span>
|
|
420
|
+
<span class="hljs-comment"># and perform other calculations</span>
|
|
421
|
+
mapshaper counties.shp \
|
|
422
|
+
-dissolve STATE calc=<span class="hljs-string">'n = count(),
|
|
423
|
+
total_pop = sum(POP),
|
|
424
|
+
max_pop = max(POP),
|
|
425
|
+
min_pop = min(POP)'</span>
|
|
426
|
+
</code></pre>
|
|
427
|
+
</section>
|
|
428
|
+
<section class="cmd-section" data-id="-dissolve2" data-name="-dissolve2" data-options=""><h3 id="-dissolve2">-dissolve2</h3>
|
|
429
|
+
<p>Deprecated alias for <a href="#-dissolve"><code>-dissolve</code></a>. The topology-repairing behavior of <code>-dissolve2</code> has been promoted to be the default behavior of <code>-dissolve</code>. Existing scripts that use <code>-dissolve2</code> will continue to work but print a deprecation notice.</p>
|
|
430
|
+
</section>
|
|
431
|
+
<section class="cmd-section" data-id="-divide" data-name="-divide" data-options="source fields calc target"><h3 id="-divide">-divide</h3>
|
|
432
|
+
<p>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 <code>-join</code> command.</p>
|
|
433
|
+
<p><code><file|layer></code> or <code>source=</code> File or layer containing polygon features.</p>
|
|
434
|
+
<p><code>fields=</code> A comma-separated list of fields to copy from the polygon layer (see <code>-join</code> command).</p>
|
|
435
|
+
<p><code>calc=</code> Use JS assignments and built-in functions to convert values from the polygon layer to (new) fields the target table (see <code>-join</code> command).</p>
|
|
436
|
+
<p>Other options: <code>target=</code></p>
|
|
437
|
+
</section>
|
|
438
|
+
<section class="cmd-section" data-id="-dots" data-name="-dots" data-options="fields colors values save-as fill evenness per-dot copy-fields multipart name target"><h3 id="-dots">-dots</h3>
|
|
439
|
+
<p>Fill polygons with random points, for making dot density maps. This command should be applied to projected layers.</p>
|
|
440
|
+
<p><code><fields></code> or <code>fields=</code> List of one or more data fields containing data for the number of dots to place in each polygon.</p>
|
|
441
|
+
<p><code>colors=</code> List of dot colors (one color for each field in the <code>fields=</code> 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.</p>
|
|
442
|
+
<p><code>values=</code> List of values to assign to dots (alternative to <code>colors=</code>).</p>
|
|
443
|
+
<p><code>save-as=</code> Name of a (new or existing) field to receive the assigned colors or values. (By default, colors are assigned to the <code>fill</code> field.)</p>
|
|
444
|
+
<p><code>r=</code> Dot radius in pixels.</p>
|
|
445
|
+
<p><code>evenness=</code> 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.</p>
|
|
446
|
+
<p><code>per-dot=</code> A number for scaling data values. For example, use <code>per-dot=100</code> to make a map that displays one dot per 100 people (or whatever entity is being visualized).</p>
|
|
447
|
+
<p><code>copy-fields=</code> List of fields to copy from the original polygon layer to each dot feature.</p>
|
|
448
|
+
<p><code>multipart</code> Combine groups of same-color dots into multi-part features.</p>
|
|
449
|
+
<p>Other options: <code>name=</code> <code>+</code> <code>target=</code></p>
|
|
450
|
+
</section>
|
|
451
|
+
<section class="cmd-section" data-id="-drop" data-name="-drop" data-options="fields geometry holes target"><h3 id="-drop">-drop</h3>
|
|
452
|
+
<p>Delete the target layer(s) or elements within the target layer(s).</p>
|
|
453
|
+
<p><code>fields=</code> Delete a (comma-separated) list of attribute data fields. To delete all fields, use <code>fields=*</code>.</p>
|
|
454
|
+
<p><code>geometry</code> Delete all geometry.</p>
|
|
455
|
+
<p><code>holes</code> Delete any holes from a polygon layer.</p>
|
|
456
|
+
<p><code>target=</code> Layer(s) to target.</p>
|
|
457
|
+
</section>
|
|
458
|
+
<section class="cmd-section" data-id="-each" data-name="-each" data-options="this expression where target calc weight radius bbox"><h3 id="-each">-each</h3>
|
|
459
|
+
<p>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 <code>this</code> object (e.g. <code>this.area</code>, <code>this.centroidX</code>, <code>this.bbox</code>).</p>
|
|
460
|
+
<p><strong>Tip:</strong> Enclose JS expressions in single quotes when using the bash shell (Mac and Linux) to avoid shell expansion of <code>!</code> and other special characters. Using the Windows command interpreter, enclose JS expressions in double quotes.</p>
|
|
461
|
+
<p><code><expression></code> or <code>expression=</code> JavaScript expression to apply to each feature.</p>
|
|
462
|
+
<p><code>where=</code> Secondary boolean JS expression for targetting a subset of features.</p>
|
|
463
|
+
<p><code>target=</code> Layer to target.</p>
|
|
464
|
+
<p>The same expression syntax and execution context are used by <code>-each</code>, <code>-filter</code>, <code>-sort</code>, <code>-inspect</code>, <code>-split</code>, <code>-subdivide</code>, <code>-calc</code> (and <code>calc=</code> options on <code>-dissolve</code>, <code>-join</code>, etc.), <code>-style</code>, <code>-symbols</code>, and any <code>where=</code>, <code>weight=</code>, <code>radius=</code> or <code>bbox=</code> option. See <a href="/docs/guides/expressions.html">JavaScript expressions</a> for the full reference: the available <code>this.*</code> properties for each geometry type, helper functions like <code>round()</code>, <code>sprintf()</code> and <code>format_dms()</code>, the <code>-calc</code> aggregation functions, the <code>A</code>/<code>B</code> pair context used by <code>-lines</code>, and common pitfalls. The <a href="/docs/examples/basics.html">Basics</a> page has practical recipes that put expressions to work.</p>
|
|
465
|
+
<p><strong>Examples</strong></p>
|
|
466
|
+
<pre><code class="hljs language-bash"><span class="hljs-comment"># Create two fields</span>
|
|
467
|
+
mapshaper counties.shp \
|
|
468
|
+
-each <span class="hljs-string">'STATE_FIPS=COUNTY_FIPS.substr(0, 2), AREA=this.area'</span> \
|
|
469
|
+
-o out.shp
|
|
470
|
+
|
|
471
|
+
<span class="hljs-comment"># Delete two fields</span>
|
|
472
|
+
mapshaper states.shp -each <span class="hljs-string">'delete STATE_NAME, delete GEOID'</span> -o out.shp
|
|
473
|
+
|
|
474
|
+
<span class="hljs-comment"># Rename a field</span>
|
|
475
|
+
mapshaper states.shp -each <span class="hljs-string">'STATE_NAME=NAME, delete NAME'</span> -o out.shp
|
|
476
|
+
|
|
477
|
+
<span class="hljs-comment"># Print the value of a field to the console</span>
|
|
478
|
+
mapshaper states.shp -each <span class="hljs-string">'console.log(NAME)'</span>
|
|
479
|
+
|
|
480
|
+
<span class="hljs-comment"># Assign a new data record to each feature</span>
|
|
481
|
+
mapshaper states.shp -each <span class="hljs-string">'this.properties = {FID: this.id}'</span> -o out.shp
|
|
482
|
+
</code></pre>
|
|
483
|
+
</section>
|
|
484
|
+
<section class="cmd-section" data-id="-erase" data-name="-erase" data-options="source bbox2 bbox remove-slivers name target"><h3 id="-erase">-erase</h3>
|
|
485
|
+
<p>Remove features or portions of features that fall inside an area.</p>
|
|
486
|
+
<p><code><source></code> or <code>source=</code> File or layer containing erase polygons. Takes the filename or layer id of the erase polygons.</p>
|
|
487
|
+
<p><code>bbox=<xmin,ymin,xmax,ymax></code> Delete features or portions of features that fall inside a bounding box. Similar to <code>-clip bbox=</code>.</p>
|
|
488
|
+
<p><code>bbox2=</code> Faster bounding box erasing than <code>bbox=</code> (experimental).</p>
|
|
489
|
+
<p><code>remove-slivers</code> Remove tiny sliver polygons created by erasing.</p>
|
|
490
|
+
<p>Common options: <a href="#common-options"><code>name=</code> <code>+</code> <code>target=</code></a></p>
|
|
491
|
+
<pre><code class="hljs language-bash"><span class="hljs-comment"># Example: Erase a polygon layer using another polygon layer.</span>
|
|
492
|
+
mapshaper usa_counties.shp -erase lakes.shp -o out.shp
|
|
493
|
+
</code></pre>
|
|
494
|
+
</section>
|
|
495
|
+
<section class="cmd-section" data-id="-explode" data-name="-explode" data-options="target"><h3 id="-explode">-explode</h3>
|
|
496
|
+
<p>Divide each multi-part feature into several single-part features.</p>
|
|
497
|
+
<p>Common options: <code>target=</code></p>
|
|
498
|
+
</section>
|
|
499
|
+
<section class="cmd-section" data-id="-filter" data-name="-filter" data-options="expression true false bbox invert remove-empty name target"><h3 id="-filter">-filter</h3>
|
|
500
|
+
<p>Apply a boolean JavaScript expression to each feature, removing features that evaluate to false.</p>
|
|
501
|
+
<p><code><expression></code> or <code>expression=</code> JS expression evaluating to <code>true</code> or <code>false</code>. Uses the same execution context as <a href="#-each"><code>-each</code></a>.</p>
|
|
502
|
+
<p><code>bbox=</code> Retains features that intersect the given bounding box (xmin,ymin,xmax,ymax).</p>
|
|
503
|
+
<p><code>invert</code> Invert the filter -- retain only those features that would have been deleted.</p>
|
|
504
|
+
<p><code>remove-empty</code> Delete features with null geometry. May be used by itself or in combination with an <code><expression></code>.</p>
|
|
505
|
+
<p>Common options: <a href="#common-options"><code>name=</code> <code>+</code> <code>target=</code> </a></p>
|
|
506
|
+
<pre><code class="hljs language-bash"><span class="hljs-comment"># Example: Select counties from New England states</span>
|
|
507
|
+
mapshaper usa_counties.shp \
|
|
508
|
+
-filter <span class="hljs-string">'"ME,VT,NH,MA,CT,RI".indexOf(STATE) > -1'</span> \
|
|
509
|
+
-o ne_counties.shp
|
|
510
|
+
</code></pre>
|
|
511
|
+
</section>
|
|
512
|
+
<section class="cmd-section" data-id="-filter-fields" data-name="-filter-fields" data-options="fields invert target"><h3 id="-filter-fields">-filter-fields</h3>
|
|
513
|
+
<p>Delete fields in an attribute table, by listing the fields to retain. If no files are given, then all attributes are removed.</p>
|
|
514
|
+
<p><code><fields></code> or <code>fields=</code> Comma-separated list of data fields to retain.</p>
|
|
515
|
+
<p><code>invert</code> Invert the filter -- delete the listed fields instead of retaining them.</p>
|
|
516
|
+
<p>Common options: <code>target=</code></p>
|
|
517
|
+
<pre><code class="hljs language-bash"><span class="hljs-comment"># Example: Retain two fields</span>
|
|
518
|
+
mapshaper states.shp -filter-fields FID,NAME -o out.shp
|
|
519
|
+
</code></pre>
|
|
520
|
+
</section>
|
|
521
|
+
<section class="cmd-section" data-id="-filter-islands" data-name="-filter-islands" data-options="min-area min-vertices remove-empty target"><h3 id="-filter-islands">-filter-islands</h3>
|
|
522
|
+
<p>Remove small detached polygon rings (islands).</p>
|
|
523
|
+
<p><code>min-area=</code> Remove small-area islands using an area threshold (e.g. 10km2).</p>
|
|
524
|
+
<p><code>min-vertices=</code> Remove low-vertex-count islands.</p>
|
|
525
|
+
<p><code>remove-empty</code> Delete features with null geometry.</p>
|
|
526
|
+
<p><a href="#common-options"><code>target=</code></a></p>
|
|
527
|
+
</section>
|
|
528
|
+
<section class="cmd-section" data-id="-filter-slivers" data-name="-filter-slivers" data-options="min-area sliver-control remove-empty target"><h3 id="-filter-slivers">-filter-slivers</h3>
|
|
529
|
+
<p>Remove small polygon rings.</p>
|
|
530
|
+
<p><code>min-area=</code> Area threshold for removal (e.g. 10km2).</p>
|
|
531
|
+
<p><code>sliver-control=</code> (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.</p>
|
|
532
|
+
<p><code>remove-empty</code> Delete features with null geometry.</p>
|
|
533
|
+
<p><a href="#common-options"><code>target=</code></a></p>
|
|
534
|
+
</section>
|
|
535
|
+
<section class="cmd-section" data-id="-frame" data-name="-frame" data-options="bbox width height aspect-ratio offset offsets name target"><h3 id="-frame">-frame</h3>
|
|
536
|
+
<p>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 <code>bbox=</code> option or the bounding box of the target layer or layers, if <code>bbox=</code> is omitted.</p>
|
|
537
|
+
<p><code>width=</code> Width of frame (e.g. 5in, 10cm, 600px; default is 800px)</p>
|
|
538
|
+
<p><code>height=</code> Height of frame (in addition to or instead of width= option)</p>
|
|
539
|
+
<p><code>aspect-ratio=</code> Aspect ratio of frame (optional)</p>
|
|
540
|
+
<p><code>bbox=</code> 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.</p>
|
|
541
|
+
<p><code>offset=</code> Padding around the frame's <code>bbox</code> in display units or pct of width/height, e.g. 5cm 20px 5%</p>
|
|
542
|
+
<p><code>offsets=</code> Comma-sep. list of offsets for each side of the map frame, in l,b,r,t order</p>
|
|
543
|
+
<p>Other options: <code>name=</code> <code>target=</code></p>
|
|
544
|
+
</section>
|
|
545
|
+
<section class="cmd-section" data-id="-graticule" data-name="-graticule" data-options="polygon interval"><h3 id="-graticule">-graticule</h3>
|
|
546
|
+
<p>Create a graticule layer appropriate for a world map centered on longitude 0.</p>
|
|
547
|
+
<p><code>polygon</code> Create an polygon enclosing the entire area of the graticule. Useful for creating background or outline shapes for clipped projections, like Robinson or Stereographic.</p>
|
|
548
|
+
<p><code>interval=</code> Specify the spacing of graticule lines (in degrees). Common options are: 5, 10, 15, 30, 45. Default is 10.</p>
|
|
549
|
+
</section>
|
|
550
|
+
<section class="cmd-section" data-id="-grid" data-name="-grid" data-options="type square hex hex2 interval name target"><h3 id="-grid">-grid</h3>
|
|
551
|
+
<p>Create a continuous grid of square or hexagonal polygons.</p>
|
|
552
|
+
<p>The <code>-grid</code> command should have a projected layer as its target. The cells of the grid will completely enclose the bounding box of the target layer.</p>
|
|
553
|
+
<p>This command is intended for visualizing data in a grid. Typically, you would use the <code>-join</code> command to join data from a polygon or point layer to a grid layer. Use <code>-join interpolate=<fields></code> to interpolate data values (typically count data) from the polygon layer to the grid layer based on area. Use <code>-join calc='<field> = sum(<field>)'</code> or <code>-join calc='<field> = count()'</code> to aggregate point data values.</p>
|
|
554
|
+
<p><code>type=</code> Supported values: <code>square</code> <code>hex</code> <code>hex2</code>. The <code>hex</code> and <code>hex2</code> types have different rotations.</p>
|
|
555
|
+
<p><code>interval=</code> The length of one side of a grid cell. Example values: <code>500m</code> <code>2km</code>.</p>
|
|
556
|
+
<p>Other options: <code>name=</code> <code>+</code> <code>target=</code></p>
|
|
557
|
+
</section>
|
|
558
|
+
<section class="cmd-section" data-id="-include" data-name="-include" data-options="file"><h3 id="-include">-include</h3>
|
|
559
|
+
<p><code><file></code> or <code>file=</code> 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 <code>-each</code> command.</p>
|
|
560
|
+
</section>
|
|
561
|
+
<section class="cmd-section" data-id="-inlay" data-name="-inlay" data-options="source target"><h3 id="-inlay">-inlay</h3>
|
|
562
|
+
<p>Inscribe a polygon layer within another polygon layer.</p>
|
|
563
|
+
<p><code><source></code> or <code>source=</code> File or layer containing polygons to inlay</p>
|
|
564
|
+
<p>Other options: <code>target=</code></p>
|
|
565
|
+
</section>
|
|
566
|
+
<section class="cmd-section" data-id="-innerlines" data-name="-innerlines" data-options="where name target"><h3 id="-innerlines">-innerlines</h3>
|
|
567
|
+
<p>Create a polyline layer consisting of shared boundaries with no attribute data.</p>
|
|
568
|
+
<p><code>where=</code> Filter lines using a JS expression (see the <code>-lines where=</code> option).</p>
|
|
569
|
+
<p>Other options: <code>name=</code> <code>+</code> <code>target=</code></p>
|
|
570
|
+
<pre><code class="hljs language-bash"><span class="hljs-comment"># Example: Extract the boundary between two states.</span>
|
|
571
|
+
mapshaper states.shp -filter <span class="hljs-string">'STATE=="OR" || STATE=="WA"'</span> -innerlines -o out.shp
|
|
572
|
+
</code></pre>
|
|
573
|
+
</section>
|
|
574
|
+
<section class="cmd-section" data-id="-join" data-name="-join" data-options="keys source calc where fields prefix interpolate point-method largest-overlap min-overlap-pct min-overlap-area max-distance duplication sum-fields string-fields field-types force unjoined unmatched encoding target"><h3 id="-join">-join</h3>
|
|
575
|
+
<p>Join attribute data from a source layer or file to a target layer. If the <code>keys=</code> option is used, Mapshaper will join records by matching the values of key fields. If the <code>keys=</code> option is missing, Mapshaper will perform a polygon-to-polygon, point-to-polygon, polygon-to-point or point-to-point spatial join.</p>
|
|
576
|
+
<p><code><file|layer></code> or <code>source=</code> File or layer containing data records to join.</p>
|
|
577
|
+
<p><code>keys=</code> 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 <code>keys=</code> option is missing, mapshaper performs a spatial join.</p>
|
|
578
|
+
<p><code>calc=</code> Use JS assignments and built-in functions to convert values from the source table to (new) fields the target table. See the <a href="#-calc"><code>-calc</code> command reference</a> for a list of supported functions. Useful for handling many-to-one joins. See example below.</p>
|
|
579
|
+
<p><code>where=</code> Use a boolean JS expression to filter records from the source table. The expression has the same syntax as the expression used by the <code>-filter</code> command. The functions <code>isMax(<field>)</code> <code>isMin(<field>)</code> and <code>isMode(<field>)</code> can be used in many-to-one joins to select among source records.</p>
|
|
580
|
+
<p><code>fields=</code> A comma-separated list of fields to copy from the external table. If the <code>fields</code> option and <code>calc</code> options are both absent, all fields are copied except the key field (if joining on keys) unless the. Use <code>fields=*</code> to copy all fields, including any key field. Use <code>fields=</code> (empty list) to copy no fields.</p>
|
|
581
|
+
<p><code>prefix=</code> Add a prefix to the names of fields joined from the external attribute table.</p>
|
|
582
|
+
<p><code>interpolate=</code> (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.</p>
|
|
583
|
+
<p><code>point-method</code> (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 <code>-points inner</code> command), and then performs a point-to-polygon or polygon-to-point join. This method does not support the <code>interpolate=</code> option.</p>
|
|
584
|
+
<p><code>largest-overlap</code> (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.</p>
|
|
585
|
+
<p><code>min-overlap-pct=</code> (polygon-to-polygon joins only) Only source features with at least this percentage overlap of the target feature (by area) get joined.</p>
|
|
586
|
+
<p><code>min-overlap-area=</code> (polygon-to-polygon joins only) Only source features with at least this much areal overlap of the target feature get joined.</p>
|
|
587
|
+
<p><code>max-distance=</code> (point-to-point joins only) Join source layer points within this distance of a target layer point.</p>
|
|
588
|
+
<p><code>duplication</code> Create duplicate features in the target layer on many-to-one joins.</p>
|
|
589
|
+
<p><code>sum-fields=</code> (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 <code>sum()</code> function inside a <code>calc=</code> expression like this: <code>calc='FIELD = sum(FIELD)'</code>.</p>
|
|
590
|
+
<p><code>string-fields=</code> A comma-separated list of fields in source CSV file to import as strings (e.g. FIPS,ZIPCODE).</p>
|
|
591
|
+
<p><code>field-types=</code> A comma-separated list of type hints (when joining a CSV file or other delimited text file). See <code>-i field-types=</code> above.</p>
|
|
592
|
+
<p><code>force</code> Allow values in the target data table to be overwritten by values in the source table when both tables contain identically named fields.</p>
|
|
593
|
+
<p><code>unjoined</code> Copy unjoined records from the source table to a layer named "unjoined".</p>
|
|
594
|
+
<p><code>unmatched</code> Copy unmatched records from the destination table to a layer named "unmatched".</p>
|
|
595
|
+
<p>Other options: <code>encoding=</code> <code>target=</code></p>
|
|
596
|
+
<p><strong>Examples</strong></p>
|
|
597
|
+
<p>Join a point layer to a polygon layer (spatial join), using the <code>calc=</code> option to handle many-to-one matches.</p>
|
|
598
|
+
<pre><code class="hljs language-bash">mapshaper states.shp \
|
|
599
|
+
-<span class="hljs-built_in">join</span> points.shp calc=<span class="hljs-string">'median_score = median(SCORE),
|
|
600
|
+
mean_score = average(SCORE),
|
|
601
|
+
join_count = count()'</span> \
|
|
602
|
+
-o out.shp
|
|
603
|
+
</code></pre>
|
|
604
|
+
<p>Copy data from a csv file to the attribute table of a Shapefile by matching values from the <em>STATE_FIPS</em> field of the Shapefile and the <em>FIPS</em> field of the csv file. (The string-fields=FIPS argument prevents FIPS codes in the CSV file from being converted to numbers.)</p>
|
|
605
|
+
<pre><code class="hljs language-bash">mapshaper states.shp \
|
|
606
|
+
-<span class="hljs-built_in">join</span> demographics.txt keys=STATE_FIPS,FIPS string-fields=FIPS \
|
|
607
|
+
-o out.shp
|
|
608
|
+
</code></pre>
|
|
609
|
+
</section>
|
|
610
|
+
<section class="cmd-section" data-id="-lines" data-name="-lines" data-options="fields where each groupby name target"><h3 id="-lines">-lines</h3>
|
|
611
|
+
<p>Converts points and polygons to lines. Polygons are converted to topological boundaries. Without the <code><fields></code> argument, external (unshared) polygon boundaries are attributed as <code>TYPE: "outer", RANK: 0</code> and internal (shared) boundaries are <code>TYPE: "inner", RANK: 1</code>. </p>
|
|
612
|
+
<p><code><fields></code> or <code>fields=</code> (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: <code>TYPE: <field name>, RANK: 1</code>, and the lowest-level internal boundaries are given attributes <code>TYPE: "outer", RANK: 2</code>. A comma-separated list of fields adds additional levels of hierarchy.</p>
|
|
613
|
+
<p><code>where=</code> 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.</p>
|
|
614
|
+
<p><code>each=</code> Apply a JS expression to each line (using A and B, like the <code>where=</code> option).</p>
|
|
615
|
+
<p><code>groupby=</code> Convert a point layer into multiple lines, using a field value for grouping.</p>
|
|
616
|
+
<p>Common options: <code>name=</code> <code>+</code> <code>target=</code></p>
|
|
617
|
+
<pre><code class="hljs language-bash"><span class="hljs-comment"># Example: Classify national, state and county boundaries.</span>
|
|
618
|
+
mapshaper counties.shp -lines STATE_FIPS -o boundaries.shp
|
|
619
|
+
</code></pre>
|
|
620
|
+
<pre><code class="hljs language-bash"><span class="hljs-comment"># Example: add the names of neighboring countries to each section of border</span>
|
|
621
|
+
mapshaper countries.geojson \
|
|
622
|
+
-lines each=<span class="hljs-string">'COUNTRIES = A.NAME + (B ? "," + B.NAME : "")'</span> \
|
|
623
|
+
-o borders.geojson
|
|
624
|
+
</code></pre>
|
|
625
|
+
</section>
|
|
626
|
+
<section class="cmd-section" data-id="-merge-layers" data-name="-merge-layers" data-options="force undefined flatten name target"><h3 id="-merge-layers">-merge-layers</h3>
|
|
627
|
+
<p>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 <code>force</code> option is used.</p>
|
|
628
|
+
<p><code>force</code> Allow merging layers with inconsistent fields. When a layer is missing a particular field, the field will be added, with the values set to <code>undefined</code>. 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.</p>
|
|
629
|
+
<p><code>flatten</code> (polygon layers) Remove polygon overlaps by assigning overlapping areas to the last overlapping polygon (the topmost feature if features are rendered in sequence).</p>
|
|
630
|
+
<p>Common options: <code>name=</code> <code>target=</code></p>
|
|
631
|
+
<pre><code class="hljs language-bash"><span class="hljs-comment"># Example: Combine features from several Shapefiles into a single Shapefile.</span>
|
|
632
|
+
<span class="hljs-comment"># -i combine-files is used because files are processed separately by default.</span>
|
|
633
|
+
mapshaper -i OR.shp WA.shp CA.shp AK.shp combine-files \
|
|
634
|
+
-merge-layers \
|
|
635
|
+
-o pacific_states.shp
|
|
636
|
+
</code></pre>
|
|
637
|
+
</section>
|
|
638
|
+
<section class="cmd-section" data-id="-mosaic" data-name="-mosaic" data-options="calc name target"><h3 id="-mosaic">-mosaic</h3>
|
|
639
|
+
<p>Flatten a polygon layer by converting overlapping areas to separate polygons.</p>
|
|
640
|
+
<p><code>calc=</code> Use a JavaScript expression to handle many-to-one aggregation (similar to the <code>calc=</code> option of the<code>-join</code> and <code>-dissolve</code> functions). See <a href="#-calc">-calc</a> for a list of supported functions.</p>
|
|
641
|
+
<p>Common options: <code>name=</code> <code>+</code> <code>target=</code></p>
|
|
642
|
+
</section>
|
|
643
|
+
<section class="cmd-section" data-id="-point-grid" data-name="-point-grid" data-options="interval bbox name"><h3 id="-point-grid">-point-grid</h3>
|
|
644
|
+
<p>Create a rectangular grid of points.</p>
|
|
645
|
+
<p><code><cols,rows></code> Size of the grid, e.g. <code>-point-grid 100,100</code>.</p>
|
|
646
|
+
<p><code>interval=</code> Distance between adjacent points, in source units (alternative to setting the number of cols and rows).</p>
|
|
647
|
+
<p><code>bbox=</code> 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.</p>
|
|
648
|
+
<p><code>name=</code> Set the name of the point grid layer</p>
|
|
649
|
+
</section>
|
|
650
|
+
<section class="cmd-section" data-id="-points" data-name="-points" data-options="centroid inner vertices vertices2 endpoints midpoints interpolated interval name target"><h3 id="-points">-points</h3>
|
|
651
|
+
<p>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).</p>
|
|
652
|
+
<p><code>x=</code> Name of field containing x coordinate values. Common X-coordinate names are auto-detected (e.g. longitude, LON).</p>
|
|
653
|
+
<p><code>y=</code> Name of field containing y coordinate values. Common Y-coordinate names are auto-detected (e.g. latitude, LAT).</p>
|
|
654
|
+
<p><code>centroid</code> Create points at the centroid of the largest ring of each polygon feature. Point placement is currrently not affected by holes.</p>
|
|
655
|
+
<p><code>inner</code> Create points in the interior of the largest ring of each polygon feature. Inner points are located away from polygon boundaries.</p>
|
|
656
|
+
<p><code>vertices</code> Convert polygon and polyline features into point features containing the unique vertices in each shape.</p>
|
|
657
|
+
<p><code>vertices2</code> Convert all the vertices in polygon and polyline features into points, including duplicate coordinates (e.g. the duplicate endpoint coordinates of polygon rings).</p>
|
|
658
|
+
<p><code>endpoints</code> Capture the unique endpoints of polygon and polyline arcs.</p>
|
|
659
|
+
<p><code>midpoints</code> Find the midpoint of each path in a polyline layer.</p>
|
|
660
|
+
<p><code>interpolated</code> Interpolate points along polylines. Requires the <code>interval=</code> option to be set. Original vertices are replaced by interpolated vertices.</p>
|
|
661
|
+
<p><code>interval=</code> Distance between interpolated points (in meters if coordinates are unprojected, or projected units).</p>
|
|
662
|
+
<p>Common options: <code>name=</code> <code>+</code> <code>target=</code></p>
|
|
663
|
+
<pre><code class="hljs language-bash"><span class="hljs-comment"># Example: Create points in the interior of each polygon </span>
|
|
664
|
+
mapshaper counties.shp -points inner -o points.shp
|
|
665
|
+
|
|
666
|
+
<span class="hljs-comment"># Example: Create points in the interior of each polygon (alternate method)</span>
|
|
667
|
+
mapshaper counties.shp \
|
|
668
|
+
-each <span class="hljs-string">'cx=this.innerX, cy=this.innerY'</span> \
|
|
669
|
+
-points x=cx y=cy \
|
|
670
|
+
-o points.shp
|
|
671
|
+
</code></pre>
|
|
672
|
+
</section>
|
|
673
|
+
<section class="cmd-section" data-id="-polygons" data-name="-polygons" data-options="gap-tolerance from-rings target"><h3 id="-polygons">-polygons</h3>
|
|
674
|
+
<p>Convert a polyline layer to a polygon layer by linking together intersecting polylines to form rings.</p>
|
|
675
|
+
<p><code>gap-tolerance=</code> Close gaps ("undershoots") between polylines up to the distance specified by this option.</p>
|
|
676
|
+
<p><code>from-rings</code> Convert a layer of closed polyline rings into polygons. Nested rings in multipart features are converted into holes.</p>
|
|
677
|
+
<p>Common options: <code>target=</code></p>
|
|
678
|
+
</section>
|
|
679
|
+
<section class="cmd-section" data-id="-proj" data-name="-proj" data-options="crs densify match init target"><h3 id="-proj">-proj</h3>
|
|
680
|
+
<p>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 <a href="https://proj.org/usage/index.html">PROJ website</a>.</p>
|
|
681
|
+
<p><code><crs></code> or <code>crs=</code> Target CRS, given as a Proj.4 definition or an alias. Use the <a href="#-projections"><code>-projections</code></a> 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, <code>crs='+proj=utm +zone=27'</code>.</p>
|
|
682
|
+
<p><code>densify</code> Interpolate vertices along long line segments as needed to approximate curved lines.</p>
|
|
683
|
+
<p><code>match=</code> Match the projection of the given layer or .prj file.</p>
|
|
684
|
+
<p><code>init=</code> 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 <code>crs</code>, you can pass a Proj4 string enclosed in quotes if the selected projection requires extra parameters, for example <code>init='+proj=utm +zone=33'</code>.</p>
|
|
685
|
+
<p><code>target=</code> Layer(s) to target. All layers belonging to the same dataset as a targeted layer will be reprojected. To reproject all datasets, use <code>target=*</code>.</p>
|
|
686
|
+
<p><strong>Examples</strong></p>
|
|
687
|
+
<pre><code class="hljs language-bash"><span class="hljs-comment"># Convert a GeoJSON file to New York Long Island state plane CRS,</span>
|
|
688
|
+
<span class="hljs-comment"># using a Proj.4 string</span>
|
|
689
|
+
mapshaper nyc.json \
|
|
690
|
+
-proj +proj=lcc \
|
|
691
|
+
+lat_1=41.03333333333333 +lat_2=40.66666666666666 \
|
|
692
|
+
+lat_0=40.16666666666666 +lon_0=-74 \
|
|
693
|
+
+x_0=300000 +y_0=0 \
|
|
694
|
+
+ellps=GRS80 +datum=NAD83 +units=m \
|
|
695
|
+
-o out.json
|
|
696
|
+
|
|
697
|
+
<span class="hljs-comment"># Apply the same projection using an EPSG code</span>
|
|
698
|
+
mapshaper nyc.json -proj EPSG:2831 -o out.json
|
|
699
|
+
|
|
700
|
+
<span class="hljs-comment"># Convert a projected Shapefile to WGS84 coordinates</span>
|
|
701
|
+
mapshaper area.shp -proj wgs84 -o out.shp
|
|
702
|
+
|
|
703
|
+
<span class="hljs-comment"># Use the Winkel Tripel projection with a custom central meridian</span>
|
|
704
|
+
mapshaper countries.shp -proj +proj=wintri +lon_0=10 -o out.shp
|
|
705
|
+
|
|
706
|
+
<span class="hljs-comment"># Shortcut notation for the above projection</span>
|
|
707
|
+
mapshaper countries.shp -proj wintri +lon_0=10 -o out.shp
|
|
708
|
+
|
|
709
|
+
<span class="hljs-comment"># Convert an unprojected U.S. Shapefile into a composite projection with Alaska</span>
|
|
710
|
+
<span class="hljs-comment"># and Hawaii repositioned and rescaled to fit in the lower left corner.</span>
|
|
711
|
+
<span class="hljs-comment"># Show Puerto Rico and the U.S. Virgin Islands</span>
|
|
712
|
+
<span class="hljs-comment"># Override the default central meridian and scale of the Alaska inset</span>
|
|
713
|
+
mapshaper us_states.shp \
|
|
714
|
+
-proj albersusa +PR +VI +AK.lon_0=-141 +AK.scale=0.4 \
|
|
715
|
+
-o out.shp
|
|
716
|
+
</code></pre>
|
|
717
|
+
</section>
|
|
718
|
+
<section class="cmd-section" data-id="-rectangle" data-name="-rectangle" data-options="source aspect-ratio offset name"><h3 id="-rectangle">-rectangle</h3>
|
|
719
|
+
<p>Create a new layer containing a rectangular polygon.</p>
|
|
720
|
+
<p><code>bbox=<xmin,ymin,xmax,ymax></code> Give the coordinates of the rectangle.</p>
|
|
721
|
+
<p><code>source=</code> Create a bounding box around a given layer.</p>
|
|
722
|
+
<p><code>aspect-ratio=</code> Aspect ratio as a number or range (e.g. 2 0.8,1.6 ,2).</p>
|
|
723
|
+
<p><code>offset=</code> Padding as a distance or percentage of width/height (single value or list).</p>
|
|
724
|
+
<p><code>name=</code> Assign a name to the newly created layer.</p>
|
|
725
|
+
</section>
|
|
726
|
+
<section class="cmd-section" data-id="-rectangles" data-name="-rectangles" data-options="aspect-ratio bbox offset name"><h3 id="-rectangles">-rectangles</h3>
|
|
727
|
+
<p>Create a new layer containing a rectangular polygon for each feature in the layer.</p>
|
|
728
|
+
<p><code>aspect-ratio=</code> Aspect ratio as a number or range (e.g. 2 0.8,1.6 ,2).</p>
|
|
729
|
+
<p><code>bbox=</code> Use an expression to generate rectangle bounds for each feature. The expression should evaluate to a GeoJSON-style bbox array.</p>
|
|
730
|
+
<p><code>offset=</code> Padding as a distance or percentage of width/height (single value or list).</p>
|
|
731
|
+
<p><code>name=</code> Assign a name to the newly created layer.</p>
|
|
732
|
+
</section>
|
|
733
|
+
<section class="cmd-section" data-id="-rename-fields" data-name="-rename-fields" data-options="fields target"><h3 id="-rename-fields">-rename-fields</h3>
|
|
734
|
+
<p>Rename data fields. To rename a field from A to B, use the assignment operator: B=A.</p>
|
|
735
|
+
<p><code><fields></code> or <code>fields=</code> List of fields to rename as a comma-separated list. </p>
|
|
736
|
+
<p>Common options: <code>target=</code></p>
|
|
737
|
+
<pre><code class="hljs language-bash"><span class="hljs-comment"># Example: rename STATE_FIPS to FIPS and STATE_NAME to NAME</span>
|
|
738
|
+
mapshaper states.shp -rename-fields FIPS=STATE_FIPS,NAME=STATE_NAME -o out.shp
|
|
739
|
+
</code></pre>
|
|
740
|
+
</section>
|
|
741
|
+
<section class="cmd-section" data-id="-rename-layers" data-name="-rename-layers" data-options="names target"><h3 id="-rename-layers">-rename-layers</h3>
|
|
742
|
+
<p>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).</p>
|
|
743
|
+
<p><code><names></code> or <code>names=</code> One or more layer names (comma-separated).</p>
|
|
744
|
+
<p><code>target=</code> Rename a subset of all layers.</p>
|
|
745
|
+
<pre><code class="hljs language-bash"><span class="hljs-comment"># Example: Create a TopoJSON file with sensible object names.</span>
|
|
746
|
+
mapshaper ne_50m_rivers_lake_centerlines.shp ne_50m_land.shp combine-files \
|
|
747
|
+
-rename-layers water,land -o target=* layers.topojson
|
|
748
|
+
</code></pre>
|
|
749
|
+
</section>
|
|
750
|
+
<section class="cmd-section" data-id="-require" data-name="-require" data-options="alias module"><h3 id="-require">-require</h3>
|
|
751
|
+
<p>Require a Node module or ES module for use in commands like <code>-each</code> and <code>-run</code>. Modules are added to the expression context. When the <code>alias=</code> option is given, modules are accessed via their aliases. Modules that are imported by name (e.g. <code>-require d3</code>) are accessed via their name, or by their alias if the <code>alias=</code> option is used. Module files without an alias name have their exported functions and data added directly to the expression context.</p>
|
|
752
|
+
<p><code><module></code> or <code>module=</code> Name of an installed module or path to a module file.</p>
|
|
753
|
+
<p><code>alias=</code> Import the module as a custom-named variable.</p>
|
|
754
|
+
<pre><code class="hljs language-bash"><span class="hljs-comment"># Example: use the underscore module (which has been installed locally)</span>
|
|
755
|
+
$ mapshaper data.json \
|
|
756
|
+
-require underscore <span class="hljs-built_in">alias</span>=_ \
|
|
757
|
+
-each <span class="hljs-string">'id = _.uniqueId()'</span> \
|
|
758
|
+
-o data2.json
|
|
759
|
+
</code></pre>
|
|
760
|
+
<pre><code class="hljs language-bash"><span class="hljs-comment"># Example: import a module file containing a user-defined function </span>
|
|
761
|
+
$ mapshaper data.json \
|
|
762
|
+
-require scripts/includes.mjs \
|
|
763
|
+
-each <span class="hljs-string">'displayname = getDisplayName(d)'</span> \
|
|
764
|
+
-o data2.json
|
|
765
|
+
</code></pre>
|
|
766
|
+
</section>
|
|
767
|
+
<section class="cmd-section" data-id="-run" data-name="-run" data-options="target io undefined targets"><h3 id="-run">-run</h3>
|
|
768
|
+
<p>Run mapshaper commands from a <a href="#command-files">command file</a> or generated on-the-fly from a JS expression.</p>
|
|
769
|
+
<p><code><file|expression></code> Either:</p>
|
|
770
|
+
<ul>
|
|
771
|
+
<li>A path to a mapshaper <a href="#command-files">command file</a>.</li>
|
|
772
|
+
<li>A JS expression or template containing embedded expressions, for generating one or more mapshaper commands.</li>
|
|
773
|
+
</ul>
|
|
774
|
+
<ul>
|
|
775
|
+
<li>Embedded expressions are enclosed in curly braces (see below).</li>
|
|
776
|
+
<li>Expressions can access <code>target</code> and <code>io</code> objects.</li>
|
|
777
|
+
<li>Expressions can also access functions and data loaded with the <code>-require</code> command.</li>
|
|
778
|
+
<li>Functions can be async.</li>
|
|
779
|
+
</ul>
|
|
780
|
+
<p>Expression context:</p>
|
|
781
|
+
<p>If command has a single target layer:
|
|
782
|
+
<code>target</code> object provides data and information about the command's target layer</p>
|
|
783
|
+
<ul>
|
|
784
|
+
<li><code>target.layer_name</code> Name of layer</li>
|
|
785
|
+
<li><code>target.geojson</code> (getter/setter) Returns a GeoJSON FeatureCollection for the layer (getter) or replaces the layer with the contents of a GeoJSON object (setter).</li>
|
|
786
|
+
<li><code>target.geometry_type</code> One of: polygon, polyline, point, <code>undefined</code></li>
|
|
787
|
+
<li><code>target.feature_count</code> Number of features in the layer</li>
|
|
788
|
+
<li><code>target.null_shape_count</code> Number of features with null geometry</li>
|
|
789
|
+
<li><code>target.null_data_count</code> Number of features with no attribute data</li>
|
|
790
|
+
<li><code>target.bbox</code> GeoJSON-style bounding box</li>
|
|
791
|
+
<li><code>target.proj4</code> PROJ-formatted string giving the CRS (coordinate reference system) of the layer</li>
|
|
792
|
+
</ul>
|
|
793
|
+
<p><code>targets</code> object gives access to all layers targetted by the run command.</p>
|
|
794
|
+
<ul>
|
|
795
|
+
<li>by numerical index, like an array (<code>targets[0]</code> refers to the first target layer)</li>
|
|
796
|
+
<li>by layer name (<code>targets.states</code> refers to a layer named "states")</li>
|
|
797
|
+
</ul>
|
|
798
|
+
<p><code>io</code> object has a method for passing data to the <code>-i</code> command.</p>
|
|
799
|
+
<ul>
|
|
800
|
+
<li><code>io.ifile(<filename>, <data>)</code> Create a temp file to use as input in a <code>-run</code> command (see example 2 below)</li>
|
|
801
|
+
</ul>
|
|
802
|
+
<p><strong>Example 1:</strong> Apply a custom projection based on the layer extent.</p>
|
|
803
|
+
<pre><code class="hljs language-bash">$ mapshaper -i country.shp \
|
|
804
|
+
-require projection.js \
|
|
805
|
+
-run <span class="hljs-string">'-proj {tmerc(target.bbox)}'</span> \
|
|
806
|
+
-o
|
|
807
|
+
</code></pre>
|
|
808
|
+
<pre><code class="hljs language-javascript"><span class="hljs-comment">// contents of projection.js file</span>
|
|
809
|
+
<span class="hljs-variable language_">module</span>.<span class="hljs-property">exports</span>.<span class="hljs-property">tmerc</span> = <span class="hljs-keyword">function</span>(<span class="hljs-params">bbox</span>) {
|
|
810
|
+
<span class="hljs-keyword">var</span> lon0 = (bbox[<span class="hljs-number">0</span>] + bbox[<span class="hljs-number">2</span>]) / <span class="hljs-number">2</span>,
|
|
811
|
+
lat0 = (bbox[<span class="hljs-number">1</span>] + bbox[<span class="hljs-number">3</span>]) / <span class="hljs-number">2</span>;
|
|
812
|
+
<span class="hljs-keyword">return</span> <span class="hljs-string">`+proj=tmerc lat_0=<span class="hljs-subst">${lat0}</span> lon_0=<span class="hljs-subst">${lon0}</span>`</span>;
|
|
813
|
+
};
|
|
814
|
+
</code></pre>
|
|
815
|
+
<p><strong>Example 2:</strong> Convert points to a Voronoi diagram using a template expression
|
|
816
|
+
together with an external script.</p>
|
|
817
|
+
<pre><code class="hljs language-bash">$ mapshaper points.geojson \
|
|
818
|
+
-require script.js \
|
|
819
|
+
-run <span class="hljs-string">'-i {io.ifile("voronoi.json", voronoi(target.geojson, target.bbox))}'</span> \
|
|
820
|
+
-o
|
|
821
|
+
</code></pre>
|
|
822
|
+
<pre><code class="hljs language-javascript"><span class="hljs-comment">// contents of script.js file</span>
|
|
823
|
+
<span class="hljs-variable language_">module</span>.<span class="hljs-property">exports</span>.<span class="hljs-property">voronoi</span> = <span class="hljs-keyword">async</span> <span class="hljs-keyword">function</span>(<span class="hljs-params">points, bbox</span>) {
|
|
824
|
+
<span class="hljs-keyword">const</span> d3 = <span class="hljs-keyword">await</span> <span class="hljs-keyword">import</span>(<span class="hljs-string">'d3-delaunay'</span>); <span class="hljs-comment">// installed locally</span>
|
|
825
|
+
<span class="hljs-keyword">const</span> coords = points.<span class="hljs-property">features</span>.<span class="hljs-title function_">map</span>(<span class="hljs-function"><span class="hljs-params">feat</span> =></span> feat.<span class="hljs-property">geometry</span>.<span class="hljs-property">coordinates</span>);
|
|
826
|
+
<span class="hljs-keyword">const</span> voronoi = d3.<span class="hljs-property">Delaunay</span>.<span class="hljs-title function_">from</span>(coords).<span class="hljs-title function_">voronoi</span>(bbox);
|
|
827
|
+
<span class="hljs-keyword">const</span> features = <span class="hljs-title class_">Array</span>.<span class="hljs-title function_">from</span>(voronoi.<span class="hljs-title function_">cellPolygons</span>()).<span class="hljs-title function_">map</span>(<span class="hljs-keyword">function</span>(<span class="hljs-params">ring, i</span>) {
|
|
828
|
+
<span class="hljs-keyword">return</span> {
|
|
829
|
+
<span class="hljs-attr">type</span>: <span class="hljs-string">'Feature'</span>,
|
|
830
|
+
<span class="hljs-attr">properties</span>: points.<span class="hljs-property">features</span>[i].<span class="hljs-property">properties</span>,
|
|
831
|
+
<span class="hljs-attr">geometry</span>: {
|
|
832
|
+
<span class="hljs-attr">type</span>: <span class="hljs-string">'Polygon'</span>,
|
|
833
|
+
<span class="hljs-attr">coordinates</span>: [ring]
|
|
834
|
+
}
|
|
835
|
+
};
|
|
836
|
+
});
|
|
837
|
+
<span class="hljs-keyword">return</span> {<span class="hljs-attr">type</span>: <span class="hljs-string">'FeatureCollection'</span>, <span class="hljs-attr">features</span>: features};
|
|
838
|
+
};
|
|
839
|
+
</code></pre>
|
|
840
|
+
</section>
|
|
841
|
+
<section class="cmd-section" data-id="-scalebar" data-name="-scalebar" data-options="label style bar-width tic-length label-position top bottom position top-left margin"><h3 id="-scalebar">-scalebar</h3>
|
|
842
|
+
<p>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.</p>
|
|
843
|
+
<p>The length of the scale bar reflects the scale in the center of the map's rectangular frame.</p>
|
|
844
|
+
<p><code><label></code> or <code>label=</code> Optional label giving the size and units of the scalebar, e.g. <code>"25 k.m."</code>. If only units are given, a length will be assigned. If the <code>label</code> property is missing, scale bar properties will be auto-generated. If two lengths are given (e.g. <code>1000 km,500 miles</code>), a dual-unit bar will be generated, if the scale bar style supports it.</p>
|
|
845
|
+
<p><code>style=</code> Scalebar style, <code>a</code> or <code>b</code>. Style <code>b</code> has tic marks.</p>
|
|
846
|
+
<p><code>bar-width=</code> Line width of bar.</p>
|
|
847
|
+
<p><code>tic-length=</code> (style b) length of tic marks.</p>
|
|
848
|
+
<p><code>label-position=</code> Position of labels relative to the bar (<code>top</code> or <code>bottom</code>).</p>
|
|
849
|
+
<p><code>position=</code> Position of the scalebar on the map (default is <code>top-left</code>).</p>
|
|
850
|
+
<p><code>margin=</code> Offset in pixels from edge of map.</p>
|
|
851
|
+
</section>
|
|
852
|
+
<section class="cmd-section" data-id="-shape" data-name="-shape" data-options="coordinates closed name"><h3 id="-shape">-shape</h3>
|
|
853
|
+
<p>Create a new layer containing a single polyline or polygon shape.</p>
|
|
854
|
+
<p><code>coordinates=<x,y,...></code> Specify vertex coordinates as a comma-separated list.</p>
|
|
855
|
+
<p><code>offsets=<dx,dy,...></code> 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 <code>coordinates=</code> list.</p>
|
|
856
|
+
<p><code>closed</code> Close an open path to form a polygon shape.</p>
|
|
857
|
+
<p><code>name=</code> Assign a name to the newly created layer.</p>
|
|
858
|
+
</section>
|
|
859
|
+
<section class="cmd-section" data-id="-simplify" data-name="-simplify" data-options="visvalingam percentage dp rdp weighted weighting resolution interval planar variable keep-shapes no-repair stats"><h3 id="-simplify">-simplify</h3>
|
|
860
|
+
<p>Mapshaper supports Douglas-Peucker simplification and two kinds of Visvalingam simplification.</p>
|
|
861
|
+
<p>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.</p>
|
|
862
|
+
<p>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 <code>visvalingam</code> option uses the "effective area" metric — points forming smaller-area triangles are removed first.</p>
|
|
863
|
+
<p>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.</p>
|
|
864
|
+
<p>When working with multiple polygon and polyline layers, the <code>-simplify</code> command is applied to all of the layers.</p>
|
|
865
|
+
<p><strong>Options</strong></p>
|
|
866
|
+
<p><code><percentage></code> or <code>percentage=</code> Percentage of removable points to retain. Accepts values in the range <code>0%-100%</code> or <code>0-1</code>.</p>
|
|
867
|
+
<p><code>dp</code> <code>rdp</code> Use Douglas-Peucker simplification.</p>
|
|
868
|
+
<p><code>visvalingam</code> Use Visvalingam simplification with the "effective area" metric.</p>
|
|
869
|
+
<p><code>weighted</code> Use weighted Visvalingam simplification (this is the default). Points located at the vertex of more acute angles are preferentially removed, for a smoother appearance.</p>
|
|
870
|
+
<p><code>weighting=</code> Coefficient for weighting Visvalingam simplification (default is 0.7). Higher values produce smoother output. <code>weighting=0</code> is equivalent to unweighted Visvalingam simplification.</p>
|
|
871
|
+
<p><code>resolution=</code> Use an output resolution (e.g. <code>5000</code> or <code>1000x800</code>) to control the amount of simplification.</p>
|
|
872
|
+
<p><code>interval=</code> Specify simplification amount in units of distance (e.g. <code>100m</code>). If the distance unit is omitted (e.g. <code>interval=100</code>), uses meters when simplifying unprojected datasets in 3D space (see <code>planar</code> option below), otherwise uses the same units as the source data.</p>
|
|
873
|
+
<p><code>variable</code> Apply a variable amount of simplification to the paths in a polygon or polygon layer. This flag changes the <code>interval=</code>, <code>percentage=</code> and <code>resolution=</code> options to accept JavaScript expressions instead of literal values. See <a href="/docs/guides/expressions.html">JavaScript expressions</a> for the available context.</p>
|
|
874
|
+
<p><code>planar</code> By default, mapshaper simplifies decimal degree coordinates in 3D space (using geocentric x,y,z coordinates). The <code>planar</code> option treats lng,lat coordinates as x,y coordinates on a Cartesian plane.</p>
|
|
875
|
+
<p><code>keep-shapes</code> Prevent polygon features from disappearing at high simplification. For multipart features, mapshaper preserves the part with the largest original bounding box.</p>
|
|
876
|
+
<p><code>no-repair</code> 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.</p>
|
|
877
|
+
<p><code>stats</code> Display summary statistics relating to the geometry of simplified paths.</p>
|
|
878
|
+
<p><strong>Examples</strong></p>
|
|
879
|
+
<pre><code class="hljs language-bash"><span class="hljs-comment"># Simplify counties.shp using the default algorithm,</span>
|
|
880
|
+
<span class="hljs-comment"># retaining 10% of removable vertices.</span>
|
|
881
|
+
mapshaper counties.shp -simplify 10% -o simplified.shp
|
|
882
|
+
|
|
883
|
+
<span class="hljs-comment"># Use Douglas-Peucker simplification with a 100 meter threshold.</span>
|
|
884
|
+
mapshaper states.shp -simplify dp interval=100 -o simplified/
|
|
885
|
+
</code></pre>
|
|
886
|
+
</section>
|
|
887
|
+
<section class="cmd-section" data-id="-snap" data-name="-snap" data-options="interval endpoints precision fix-geometry target"><h3 id="-snap">-snap</h3>
|
|
888
|
+
<p>Snap together nearby vertices</p>
|
|
889
|
+
<p><code>interval</code> Snap tolerance (default is small).</p>
|
|
890
|
+
<p><code>endpoints</code> Only snap endpoints of polyline features.</p>
|
|
891
|
+
<p><code>precision=</code> Round all coordinates to a given decimal precision (e.g. 0.000001).</p>
|
|
892
|
+
<p><code>fix-geometry</code> 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.</p>
|
|
893
|
+
<p><a href="#common-options"><code>target=</code></a></p>
|
|
894
|
+
</section>
|
|
895
|
+
<section class="cmd-section" data-id="-sort" data-name="-sort" data-options="expression ascending descending target"><h3 id="-sort">-sort</h3>
|
|
896
|
+
<p>Sort features in a data layer using a JavaScript expression.</p>
|
|
897
|
+
<p><code><expression></code> or <code>expression=</code> Apply a JavaScript expression to each feature, using the resulting values for sorting the features. Uses the same execution environment as <a href="#-each"><code>-each</code></a>.</p>
|
|
898
|
+
<p><code>ascending</code> Sort in ascending order (this is the default).</p>
|
|
899
|
+
<p><code>descending</code> Sort in descending order.</p>
|
|
900
|
+
<p><a href="#common-options"><code>target=</code></a></p>
|
|
901
|
+
</section>
|
|
902
|
+
<section class="cmd-section" data-id="-split" data-name="-split" data-options="expression target"><h3 id="-split">-split</h3>
|
|
903
|
+
<p>Distributes features in the target layer to multiple output layers. If the <code>expression=</code> 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.</p>
|
|
904
|
+
<p><code><expression></code> or <code>expression=</code> JS expression or name of the attribute field to split on.</p>
|
|
905
|
+
<p>Common options: <code>+</code> <code>target=</code></p>
|
|
906
|
+
<p><strong>Examples</strong></p>
|
|
907
|
+
<pre><code class="hljs language-bash"><span class="hljs-comment"># Split features from a named layer into new GeoJSON files using a data field.</span>
|
|
908
|
+
<span class="hljs-comment"># Output names use the original layer name + data values,</span>
|
|
909
|
+
<span class="hljs-comment"># e.g. states-AK.json, states-AL.json, etc.</span>
|
|
910
|
+
mapshaper states.shp -<span class="hljs-built_in">split</span> STATE -o format=geojson
|
|
911
|
+
|
|
912
|
+
<span class="hljs-comment"># Split features from an unnamed layer into new GeoJSON files</span>
|
|
913
|
+
<span class="hljs-comment"># using a data field.</span>
|
|
914
|
+
<span class="hljs-comment"># Output names contain data values,</span>
|
|
915
|
+
<span class="hljs-comment"># e.g. AK.json, AL.json, etc.</span>
|
|
916
|
+
mapshaper states.shp name=<span class="hljs-string">''</span> -<span class="hljs-built_in">split</span> STATE -o format=geojson
|
|
917
|
+
|
|
918
|
+
<span class="hljs-comment"># Split source features into individual GeoJSON files (no data field supplied).</span>
|
|
919
|
+
<span class="hljs-comment"># Output names use source layer name + ascending number,</span>
|
|
920
|
+
<span class="hljs-comment"># e.g. states-1, states-2, etc.</span>
|
|
921
|
+
mapshaper states.shp -<span class="hljs-built_in">split</span> -o format=geojson
|
|
922
|
+
</code></pre>
|
|
923
|
+
</section>
|
|
924
|
+
<section class="cmd-section" data-id="-split-on-grid" data-name="-split-on-grid" data-options="target"><h3 id="-split-on-grid">-split-on-grid</h3>
|
|
925
|
+
<p>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 <code>-o bbox-index</code> to export a file containing the name and bounding box of the shapes in each file. Empty cells are removed from the output.</p>
|
|
926
|
+
<p><code><cols,rows></code> Size of the grid, e.g. <code>-split-on-grid 12,10</code></p>
|
|
927
|
+
<p>Common options: <code>target=</code> </p>
|
|
928
|
+
</section>
|
|
929
|
+
<section class="cmd-section" data-id="-subdivide" data-name="-subdivide" data-options="expression target"><h3 id="-subdivide">-subdivide</h3>
|
|
930
|
+
<p>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.</p>
|
|
931
|
+
<p>Subdivide expressions can call several functions that operate on a group of features. The <code>sum()</code> 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 <code>min()</code> <code>max()</code> <code>average()</code> and <code>median()</code>.</p>
|
|
932
|
+
<p><code><expression></code> or <code>expression=</code> Boolean JavaScript expression</p>
|
|
933
|
+
<p>Common options: <code>target=</code></p>
|
|
934
|
+
<p><strong>Example</strong></p>
|
|
935
|
+
<pre><code class="hljs language-bash"><span class="hljs-comment"># Aggregate census tracts into groups of less than 1,000,000 population</span>
|
|
936
|
+
<span class="hljs-comment"># and less than 100 sq km in area.</span>
|
|
937
|
+
mapshaper tracts.shp
|
|
938
|
+
-subdivide <span class="hljs-string">"sum('POPULATION') >= 1000000 && sum('this.area') > 1e8"</span> \
|
|
939
|
+
-dissolve sum-fields=POPULATION \
|
|
940
|
+
-merge-layers \
|
|
941
|
+
-o tract_groups.shp
|
|
942
|
+
</code></pre>
|
|
943
|
+
</section>
|
|
944
|
+
<section class="cmd-section" data-id="-style" data-name="-style" data-options="where clear class css style fill pink fill-pattern ortho npers stroke stroke-width stroke-dasharray opacity label-text text-anchor dx dy font-size font-family font-weight font-style font-stretch letter-spacing line-height target"><h3 id="-style">-style</h3>
|
|
945
|
+
<p>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 <a href="/docs/guides/expressions.html">JavaScript expressions</a> for the available context. This command was named <code>-svg-style</code> in earlier versions of mapshaper.</p>
|
|
946
|
+
<p><code>where=</code> Boolean JS expression for targetting a subset of features.</p>
|
|
947
|
+
<p><code>clear</code> Remove all style properties from a layer.</p>
|
|
948
|
+
<p><code>class=</code> One or more CSS classes, separated by spaces (e.g. <code>class="light semi-transparent"</code>)</p>
|
|
949
|
+
<p><code>css=</code> Inline CSS to use as the <code>style=</code> attribute of each SVG symbol.</p>
|
|
950
|
+
<p><code>fill=</code> Fill color (e.g. <code>#eee</code> <code>pink</code> <code>rgba(0, 0, 0, 0.2)</code>)</p>
|
|
951
|
+
<p><code>fill-pattern=</code> Definition string for a pattern. There are four pattern types: hatches, dots, squares and dashes. The syntax for each pattern is:</p>
|
|
952
|
+
<ul>
|
|
953
|
+
<li>hatches [rotation] width1 color1 [width2 color2 ...]</li>
|
|
954
|
+
<li>dots [rotation] size color1 [color2 ...] spacing background-color</li>
|
|
955
|
+
<li>squares [rotation] size color1 [color2 ...] spacing background-color</li>
|
|
956
|
+
<li>dashes [rotation] dash-length space-length line-width color line-spacing background-color</li>
|
|
957
|
+
</ul>
|
|
958
|
+
<p>Example: <code>hatches 45deg 2px red 2px grey</code></p>
|
|
959
|
+
<p><code>fill-effect=sphere</code> Add a gradient effect to the bounding circle of a globe projection (e.g. <code>ortho</code> <code>npers</code>) to create a 3d effect.</p>
|
|
960
|
+
<p><code>stroke=</code> Stroke color</p>
|
|
961
|
+
<p><code>stroke-width=</code> Stroke width</p>
|
|
962
|
+
<p><code>stroke-dasharray=</code> Dashes</p>
|
|
963
|
+
<p><code>opacity=</code> Symbol opacity (e.g. <code>opacity=0.5</code>)</p>
|
|
964
|
+
<p><code>r=</code> Circle radius. Setting this exports points as SVG <code><circle></code> symbols, unless the <code>-o point-symbol=square</code> option is used.</p>
|
|
965
|
+
<p><code>label-text=</code> 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, <code>\n</code> (backslash + "n"), and <code><br></code>. (When importing JSON data, <code>\n</code> in a JSON string is parsed as a newline and <code>\\n</code> is parsed as backslash + "n"). Note that Mapshaper doesn't accept multiline strings as input on the command line.</p>
|
|
966
|
+
<p><code>text-anchor=</code> Horizontal justification of label text. Possible values are: start, end or middle (the default).</p>
|
|
967
|
+
<p><code>dx=</code> X offset of labels (default is 0)</p>
|
|
968
|
+
<p><code>dy=</code> Y offset of labels (default is baseline-aligned)</p>
|
|
969
|
+
<p><code>font-size=</code> Size of label text (default is 12)</p>
|
|
970
|
+
<p><code>font-family=</code> CSS font-family of labels (default is sans-serif)</p>
|
|
971
|
+
<p><code>font-weight=</code> CSS font-weight property of labels (e.g. bold, 700)</p>
|
|
972
|
+
<p><code>font-style=</code> CSS font-style property of labels (e.g. italic)</p>
|
|
973
|
+
<p><code>font-stretch=</code> CSS font-stretch property of labels (e.g. condensed)</p>
|
|
974
|
+
<p><code>letter-spacing=</code> CSS letter-spacing property of labels</p>
|
|
975
|
+
<p><code>line-height=</code> Line spacing of multi-line labels (default is 1.1em). Lines are separated by newline characters or <code><br></code> tags in the label text.</p>
|
|
976
|
+
<p>Common options: <code>target=</code></p>
|
|
977
|
+
<p><strong>Example</strong></p>
|
|
978
|
+
<pre><code class="hljs language-bash"><span class="hljs-comment"># Apply a 2px grey stroke and no fill to a polygon layer</span>
|
|
979
|
+
mapshaper polygons.geojson \
|
|
980
|
+
-style fill=none stroke=<span class="hljs-string">'#aaa'</span> stroke-width=2 \
|
|
981
|
+
-o out.svg
|
|
982
|
+
</code></pre>
|
|
983
|
+
</section>
|
|
984
|
+
<section class="cmd-section" data-id="-symbols" data-name="-symbols" data-options="type fill stroke stroke-width opacity geographic pixel-scale rotated rotation scale radius sides points point-ratio radii length direction head-angle head-width head-length stem-width stem-length stem-taper stem-curve min-stem-ratio anchor name target"><h3 id="-symbols">-symbols</h3>
|
|
985
|
+
<p>Symbolize points as regular polygons, circles, stars, arrows and other shapes.</p>
|
|
986
|
+
<p><code>type=</code> Basic types: star, polygon, circle, arrow, ring. Aliases: triangle, square, pentagon, etc.</p>
|
|
987
|
+
<p><code>fill=</code> Symbol fill color</p>
|
|
988
|
+
<p><code>stroke=</code> Symbol line color (linear symbols only)</p>
|
|
989
|
+
<p><code>stroke-width=</code> Symbol line width (linear symbols only)</p>
|
|
990
|
+
<p><code>opacity=</code> Symbol opacity</p>
|
|
991
|
+
<p><code>geographic</code> Make geographic shapes (polygons or polylines) instead of SVG objects</p>
|
|
992
|
+
<p><code>pixel-scale=</code> Set symbol scale in meters-per-pixel (for polygons option)</p>
|
|
993
|
+
<p><code>rotated</code> Symbol is rotated to an alternate orientation</p>
|
|
994
|
+
<p><code>rotation=</code> Rotation of symbol in degrees</p>
|
|
995
|
+
<p><code>scale=</code> Scale symbols by a multiplier</p>
|
|
996
|
+
<p><code>radius=</code> Distance from center to farthest point on the symbol</p>
|
|
997
|
+
<p><code>sides=</code> (polygon) number of sides of a polygon symbol</p>
|
|
998
|
+
<p><code>points=</code> (star) number of points</p>
|
|
999
|
+
<p><code>point-ratio=</code> (star) ratio of minor to major radius of star</p>
|
|
1000
|
+
<p><code>radii=</code> (ring) comma-sep. list of concentric radii, ascending order</p>
|
|
1001
|
+
<p><code>length=</code> (arrow) length of arrow in pixels</p>
|
|
1002
|
+
<p><code>direction=</code> (arrow) angle off of vertical (-90 = left-pointing)</p>
|
|
1003
|
+
<p><code>head-angle=</code> (arrow) angle of tip of arrow (default is 40 degrees)</p>
|
|
1004
|
+
<p><code>head-width=</code> (arrow) width of arrow head from side to side</p>
|
|
1005
|
+
<p><code>head-length=</code> (arrow) length of head (alternative to head-angle). Use <code>head-length=0</code> to make headless arrows (i.e. simple lines)</p>
|
|
1006
|
+
<p><code>stem-width=</code> (arrow) width of stem at its widest point</p>
|
|
1007
|
+
<p><code>stem-length=</code> (arrow) alternative to length</p>
|
|
1008
|
+
<p><code>stem-taper=</code> (arrow) factor for tapering the width of the stem (0-1)</p>
|
|
1009
|
+
<p><code>stem-curve=</code> (arrow) curvature in degrees (default is 0)</p>
|
|
1010
|
+
<p><code>min-stem-ratio=</code> (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.</p>
|
|
1011
|
+
<p><code>anchor=</code> (arrow) takes one of: start, middle, end (default is start)</p>
|
|
1012
|
+
<p>Common options: <code>name=</code> <code>+</code> <code>target=</code></p>
|
|
1013
|
+
</section>
|
|
1014
|
+
<section class="cmd-section" data-id="-union" data-name="-union" data-options="fields name target"><h3 id="-union">-union</h3>
|
|
1015
|
+
<p>Create a composite layer (a polygon mosaic without overlaps) from two or more target polygon layers.</p>
|
|
1016
|
+
<p>Data values are copied from source features to output features. (Areal interpolation may
|
|
1017
|
+
be added in the future. The <code>-join</code> command currently supports areal interpolation between polygon layers using the <code>-join interpolate=<fields></code> 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".</p>
|
|
1018
|
+
<p><code>fields=</code> Fields to retain (default is all fields).</p>
|
|
1019
|
+
<p>Common options: <code>name=</code> <code>+</code> <code>target=</code></p>
|
|
1020
|
+
</section>
|
|
1021
|
+
<section class="cmd-section" data-id="-uniq" data-name="-uniq" data-options="expression max-count invert verbose target"><h3 id="-uniq">-uniq</h3>
|
|
1022
|
+
<p>Delete features with the same id as a previous feature</p>
|
|
1023
|
+
<p><code><expression></code> or <code>expression=</code> JS expression to obtain the id of a feature. Uses the same expression syntax as <a href="#-each"><code>-each</code></a>.</p>
|
|
1024
|
+
<p><code>max-count=</code> Allow multiple features with the same id (default is 1).</p>
|
|
1025
|
+
<p><code>invert</code> Retain only features that would ordinarily be deleted by <code>-uniq</code>.</p>
|
|
1026
|
+
<p><code>verbose</code> Print information about each removed feature.</p>
|
|
1027
|
+
<p><code>target=</code></p>
|
|
1028
|
+
<pre><code class="hljs language-bash"><span class="hljs-comment"># Example: Retain only the largest parts of each multipart polygon</span>
|
|
1029
|
+
mapshaper polygons.shp \
|
|
1030
|
+
-each <span class="hljs-string">'fid = this.id'</span> \
|
|
1031
|
+
-explode \
|
|
1032
|
+
-<span class="hljs-built_in">sort</span> <span class="hljs-string">'this.area'</span> descending \
|
|
1033
|
+
-<span class="hljs-built_in">uniq</span> <span class="hljs-string">'fid'</span> \
|
|
1034
|
+
-o out.shp
|
|
1035
|
+
</code></pre>
|
|
1036
|
+
</section>
|
|
1037
|
+
<h2 id="control-flow-commands" class="cmd-category">Control Flow Commands</h2>
|
|
1038
|
+
<section class="cmd-section" data-id="-if" data-name="-if" data-options="if expression empty not-empty layer this null"><h3 id="-if">-if</h3>
|
|
1039
|
+
<p>The <code>if</code> command runs the following commands if a condition is met.</p>
|
|
1040
|
+
<p><code><expression></code> or <code>expression=</code> Use a JavaScript expression to test a condition.</p>
|
|
1041
|
+
<p><code>empty</code> Test if layer is empty.</p>
|
|
1042
|
+
<p><code>not-empty</code> Test if layer contains data.</p>
|
|
1043
|
+
<p><code>layer=</code> Name or id of layer to test (default is current target layer).</p>
|
|
1044
|
+
<p><strong>Properties of <code>this</code></strong></p>
|
|
1045
|
+
<ul>
|
|
1046
|
+
<li><code>this.name</code> Layer name, or <undefined> if layer is unnamed.</li>
|
|
1047
|
+
<li><code>this.size</code> Number of features in the layer.</li>
|
|
1048
|
+
<li><code>this.empty</code> True if layer contains 0 features.</li>
|
|
1049
|
+
<li><code>this.data</code> Array of attribute data records, one object per feature.</li>
|
|
1050
|
+
<li><code>this.type</code> Geometry type, one of: polygon, polyline, point, <undefined>.</li>
|
|
1051
|
+
<li><code>this.bbox</code> An array [xmin, ymin, xmax, ymax] with additional properties: cx, cy, height, width, left, bottom, top, right.</li>
|
|
1052
|
+
</ul>
|
|
1053
|
+
<p><strong>Functions of <code>this</code></strong></p>
|
|
1054
|
+
<ul>
|
|
1055
|
+
<li><code>this.field_exists(<name>)</code> Tests if a data field exists in the target layer.</li>
|
|
1056
|
+
<li><code>this.field_type(<name>)</code> Returns the data type of a field, or <code>null</code> if a field is empty or missing. Types include: <code>"string" "number" "boolean" "date" "object"</code>. If a field includes multiple data types (which may occur in GeoJSON), the type of the first non-empty data value is returned.</li>
|
|
1057
|
+
<li><code>this.field_includes(<value>)</code> Tests if a given value occurs at least once in a data field.</li>
|
|
1058
|
+
<li><code>this.file_exists(<filename>)</code> Tests if a file exists.</li>
|
|
1059
|
+
</ul>
|
|
1060
|
+
<p><strong>Example</strong></p>
|
|
1061
|
+
<pre><code class="hljs language-bash">mapshaper -i shapes.json -<span class="hljs-keyword">if</span> <span class="hljs-string">'!this.empty'</span> -dissolve -o out/dissolved.json
|
|
1062
|
+
</code></pre>
|
|
1063
|
+
</section>
|
|
1064
|
+
<section class="cmd-section" data-id="-elif" data-name="-elif" data-options=""><h3 id="-elif">-elif</h3>
|
|
1065
|
+
<p>One or more <code>-elif</code> (short for "else if") commands may be added to test for alternate conditions, following an <code>-if</code> statement. The <code>-elif</code> command accepts the same options as the <code>-if</code> command.</p>
|
|
1066
|
+
</section>
|
|
1067
|
+
<section class="cmd-section" data-id="-else" data-name="-else" data-options=""><h3 id="-else">-else</h3>
|
|
1068
|
+
<p>Run the following commands if all preceding -if/-elif conditions are false.</p>
|
|
1069
|
+
</section>
|
|
1070
|
+
<section class="cmd-section" data-id="-endif" data-name="-endif" data-options=""><h3 id="-endif">-endif</h3>
|
|
1071
|
+
<p>Mark the end of an -if/-elif/-else sequence.</p>
|
|
1072
|
+
</section>
|
|
1073
|
+
<section class="cmd-section" data-id="-stop" data-name="-stop" data-options=""><h3 id="-stop">-stop</h3>
|
|
1074
|
+
<p>Stop processing (skip remaining commands). Useful when writing scripts, in combination with -if/-elif/-else.</p>
|
|
1075
|
+
<p><strong>Example</strong></p>
|
|
1076
|
+
<pre><code class="hljs language-bash"><span class="hljs-comment"># Don't try to process a missing file</span>
|
|
1077
|
+
mapshaper -<span class="hljs-keyword">if</span> <span class="hljs-string">'!file_exists("boundaries.geojson")'</span> -stop -endif \
|
|
1078
|
+
-i boundaries.geojson -proj robin -o output/boundaries.shp
|
|
1079
|
+
</code></pre>
|
|
1080
|
+
</section>
|
|
1081
|
+
<section class="cmd-section" data-id="-target" data-name="-target" data-options="target type name"><h3 id="-target">-target</h3>
|
|
1082
|
+
<p>Set the target layer or layers for the following command.</p>
|
|
1083
|
+
<p><code><target></code> or <code>target=</code> Name or id of a layer (first layer is 1).</p>
|
|
1084
|
+
<p><code>type=</code> Type of layer(s) to match (polygon, polyline or point). This is useful when importing GeoJSON files containing several types of geometry.</p>
|
|
1085
|
+
<p><code>name=</code> Rename the target layer.</p>
|
|
1086
|
+
</section>
|
|
1087
|
+
<h2 id="informational-commands" class="cmd-category">Informational Commands</h2>
|
|
1088
|
+
<section class="cmd-section" data-id="-calc" data-name="-calc" data-options="calc where null global expression name target"><h3 id="-calc">-calc</h3>
|
|
1089
|
+
<p>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.</p>
|
|
1090
|
+
<p>The <code>calc</code> functions are also available in the context of <code>calc=</code> expressions, which can be used as options to <code>-join</code>, <code>-dissolve</code> and several other commands. See example below. For the full expression context (per-feature properties available inside <code><expr></code>, the <code>where=</code> filter syntax, etc.), see <a href="/docs/guides/expressions.html">JavaScript expressions</a>.</p>
|
|
1091
|
+
<table>
|
|
1092
|
+
<thead>
|
|
1093
|
+
<tr>
|
|
1094
|
+
<th>function</th>
|
|
1095
|
+
<th>description</th>
|
|
1096
|
+
</tr>
|
|
1097
|
+
</thead>
|
|
1098
|
+
<tbody><tr>
|
|
1099
|
+
<td><code>count ()</code></td>
|
|
1100
|
+
<td>returns number of records in the collection</td>
|
|
1101
|
+
</tr>
|
|
1102
|
+
<tr>
|
|
1103
|
+
<td><code>sum (<expr>)</code></td>
|
|
1104
|
+
<td></td>
|
|
1105
|
+
</tr>
|
|
1106
|
+
<tr>
|
|
1107
|
+
<td><code>mean (<expr>)</code></td>
|
|
1108
|
+
<td></td>
|
|
1109
|
+
</tr>
|
|
1110
|
+
<tr>
|
|
1111
|
+
<td><code>average (<expr>)</code></td>
|
|
1112
|
+
<td>same as mean()</td>
|
|
1113
|
+
</tr>
|
|
1114
|
+
<tr>
|
|
1115
|
+
<td><code>median (<expr>)</code></td>
|
|
1116
|
+
<td></td>
|
|
1117
|
+
</tr>
|
|
1118
|
+
<tr>
|
|
1119
|
+
<td><code>mode (<expr>)</code></td>
|
|
1120
|
+
<td>returns most frequently occuring value in the collection (or the first such value in case of a tie).</td>
|
|
1121
|
+
</tr>
|
|
1122
|
+
<tr>
|
|
1123
|
+
<td><code>min (<expr>)</code></td>
|
|
1124
|
+
<td></td>
|
|
1125
|
+
</tr>
|
|
1126
|
+
<tr>
|
|
1127
|
+
<td><code>max (<expr>)</code></td>
|
|
1128
|
+
<td></td>
|
|
1129
|
+
</tr>
|
|
1130
|
+
<tr>
|
|
1131
|
+
<td><code>quartile1 (<expr>)</code></td>
|
|
1132
|
+
<td>first quartile</td>
|
|
1133
|
+
</tr>
|
|
1134
|
+
<tr>
|
|
1135
|
+
<td><code>quartile2 (<expr>)</code></td>
|
|
1136
|
+
<td>same as median()</td>
|
|
1137
|
+
</tr>
|
|
1138
|
+
<tr>
|
|
1139
|
+
<td><code>quartile3 (<expr>)</code></td>
|
|
1140
|
+
<td>third quartile</td>
|
|
1141
|
+
</tr>
|
|
1142
|
+
<tr>
|
|
1143
|
+
<td><code>iqr (<expr>)</code></td>
|
|
1144
|
+
<td>interquartile range</td>
|
|
1145
|
+
</tr>
|
|
1146
|
+
<tr>
|
|
1147
|
+
<td><code>quantile (<expr>, <pct>)</code></td>
|
|
1148
|
+
<td>arbitrary percentile (<code><pct></code> is 0-1)</td>
|
|
1149
|
+
</tr>
|
|
1150
|
+
<tr>
|
|
1151
|
+
<td><code>collect (<expr>)</code></td>
|
|
1152
|
+
<td>returns array containing all values</td>
|
|
1153
|
+
</tr>
|
|
1154
|
+
<tr>
|
|
1155
|
+
<td><code>collectIds ()</code></td>
|
|
1156
|
+
<td>returns array of feature indexes (features are indexed 0 to n-1)</td>
|
|
1157
|
+
</tr>
|
|
1158
|
+
<tr>
|
|
1159
|
+
<td><code>first (<expr>)</code></td>
|
|
1160
|
+
<td>returns first value in the collection</td>
|
|
1161
|
+
</tr>
|
|
1162
|
+
<tr>
|
|
1163
|
+
<td><code>last (<expr>)</code></td>
|
|
1164
|
+
<td>returns last value in the collection</td>
|
|
1165
|
+
</tr>
|
|
1166
|
+
<tr>
|
|
1167
|
+
<td><code>every (<expr>)</code></td>
|
|
1168
|
+
<td>returns true if expression is true for all elements in the collection</td>
|
|
1169
|
+
</tr>
|
|
1170
|
+
<tr>
|
|
1171
|
+
<td><code>some (<expr>)</code></td>
|
|
1172
|
+
<td>returns true if expression is true for one or more elements in the collection</td>
|
|
1173
|
+
</tr>
|
|
1174
|
+
</tbody></table>
|
|
1175
|
+
<p>Argument expressions take the same form as <code>-each</code> expressions. If no records are processed, <code>count()</code> and <code>sum()</code> return <code>0</code>, and the other functions return <code>null</code>.</p>
|
|
1176
|
+
<p><strong>Assignments</strong></p>
|
|
1177
|
+
<p>The <code>-calc</code> expression can take the form of one or more assignments. This creates global variables that can be accessed by subsequent expressions using the <code>global</code> namespace. For example:</p>
|
|
1178
|
+
<pre><code>mapshaper data.csv \
|
|
1179
|
+
-calc 'N = count()' \
|
|
1180
|
+
-if 'global.N < 5' \
|
|
1181
|
+
-print 'LOW SAMPLE SIZE, STOPPING' \
|
|
1182
|
+
-stop \
|
|
1183
|
+
-endif
|
|
1184
|
+
</code></pre>
|
|
1185
|
+
<p><strong>Options</strong></p>
|
|
1186
|
+
<p><code><expression></code> or <code>expression=</code> JS expression containing calls to one or more <code>-calc</code> functions.</p>
|
|
1187
|
+
<p><code>where=</code> Perform calculations on a subset of records, using a boolean JS expression as a filter (similar to <a href="#-filter"><code>-filter</code></a> command).
|
|
1188
|
+
<code>+</code> Save output to a layer.
|
|
1189
|
+
<code>name=</code> Name the output layer (default name is "calc").
|
|
1190
|
+
<code>target=</code></p>
|
|
1191
|
+
<p><strong>Examples</strong></p>
|
|
1192
|
+
<pre><code class="hljs language-bash"><span class="hljs-comment"># Calculate the sum of a data field</span>
|
|
1193
|
+
mapshaper ny-census-blocks.shp -calc <span class="hljs-string">'sum(POPULATION)'</span>
|
|
1194
|
+
|
|
1195
|
+
<span class="hljs-comment"># Count census blocks in NY with zero population</span>
|
|
1196
|
+
mapshaper ny-census-blocks.shp -calc <span class="hljs-string">'count()'</span> <span class="hljs-built_in">where</span>=<span class="hljs-string">'POPULATION == 0'</span>
|
|
1197
|
+
|
|
1198
|
+
<span class="hljs-comment"># Using calc functions in conjunction with the `-dissolve` command</span>
|
|
1199
|
+
mapshaper counties.csv \
|
|
1200
|
+
-dissolve STATE_NAME calc=<span class="hljs-string">'NUM_COUNTIES = count()'</span> \
|
|
1201
|
+
-o states.csv
|
|
1202
|
+
</code></pre>
|
|
1203
|
+
</section>
|
|
1204
|
+
<section class="cmd-section" data-id="-colors" data-name="-colors" data-options="color-scheme"><h3 id="-colors">-colors</h3>
|
|
1205
|
+
<p>Print list of built-in color schemes. Color schemes can be used with the <code>color-scheme=</code> option of the <a href="#-classify">-classify</a> command. (These color schemes come from the <a href="https://github.com/d3/d3-scale-chromatic">d3-scale-chromatic</a> library.)</p>
|
|
1206
|
+
</section>
|
|
1207
|
+
<section class="cmd-section" data-id="-comment" data-name="-comment" data-options=""><h3 id="-comment">-comment</h3>
|
|
1208
|
+
<p>The following text up to the next command is treated as a comment. Useful for adding explanatory comments to a long sequence of commands.</p>
|
|
1209
|
+
</section>
|
|
1210
|
+
<section class="cmd-section" data-id="-encodings" data-name="-encodings" data-options=""><h3 id="-encodings">-encodings</h3>
|
|
1211
|
+
<p>Print list of supported text encodings (for .dbf import).</p>
|
|
1212
|
+
</section>
|
|
1213
|
+
<section class="cmd-section" data-id="-help" data-name="-help" data-options=""><h3 id="-help">-help</h3>
|
|
1214
|
+
<p>Print usage tips and a list of commands.</p>
|
|
1215
|
+
<p><code><command></code> Show options for a single command, e.g. <code>mapshaper -h join</code>.</p>
|
|
1216
|
+
</section>
|
|
1217
|
+
<section class="cmd-section" data-id="-info" data-name="-info" data-options="save-to name"><h3 id="-info">-info</h3>
|
|
1218
|
+
<p>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.</p>
|
|
1219
|
+
<pre><code class="hljs language-bash"><span class="hljs-comment"># Example: Get information about an unknown GeoJSON or TopoJSON dataset</span>
|
|
1220
|
+
mapshaper mystery_file.json -info
|
|
1221
|
+
</code></pre>
|
|
1222
|
+
<p><code>save-to=</code> Save information to a .json file.
|
|
1223
|
+
<code>+</code> Save output to a layer.
|
|
1224
|
+
<code>name=</code> Name the output layer (default name is "info").</p>
|
|
1225
|
+
</section>
|
|
1226
|
+
<section class="cmd-section" data-id="-inspect" data-name="-inspect" data-options="expression target"><h3 id="-inspect">-inspect</h3>
|
|
1227
|
+
<p>Print information about the data attributes of a feature.</p>
|
|
1228
|
+
<p><code><expression></code> or <code>expression=</code> JS expression for selecting a feature (see <a href="/docs/guides/expressions.html">JavaScript expressions</a> for the syntax and context).</p>
|
|
1229
|
+
<p>Common options: <code>target=</code></p>
|
|
1230
|
+
<pre><code class="hljs language-bash"><span class="hljs-comment"># Example: View attribute data for a state</span>
|
|
1231
|
+
mapshaper states.geojson -inspect <span class="hljs-string">'NAME == "Delaware"'</span>
|
|
1232
|
+
</code></pre>
|
|
1233
|
+
</section>
|
|
1234
|
+
<section class="cmd-section" data-id="-print" data-name="-print" data-options=""><h3 id="-print">-print</h3>
|
|
1235
|
+
<p>Prints a message to the console or terminal (using stdout). This command is useful in combination with the <code>-if/-elif/-else</code> commands.</p>
|
|
1236
|
+
<pre><code class="hljs language-bash"><span class="hljs-comment"># Example</span>
|
|
1237
|
+
mapshaper cities.json \
|
|
1238
|
+
-<span class="hljs-keyword">if</span> <span class="hljs-string">'this.empty'</span> \
|
|
1239
|
+
-<span class="hljs-built_in">print</span> FILE IS EMPTY
|
|
1240
|
+
</code></pre>
|
|
1241
|
+
</section>
|
|
1242
|
+
<section class="cmd-section" data-id="-projections" data-name="-projections" data-options=""><h3 id="-projections">-projections</h3>
|
|
1243
|
+
<p>Print list of supported proj4 projection ids and projection aliases.</p>
|
|
1244
|
+
</section>
|
|
1245
|
+
<section class="cmd-section" data-id="-quiet" data-name="-quiet" data-options=""><h3 id="-quiet">-quiet</h3>
|
|
1246
|
+
<p>Inhibit console messages.</p>
|
|
1247
|
+
</section>
|
|
1248
|
+
<section class="cmd-section" data-id="-vars" data-name="-vars" data-options=""><h3 id="-vars">-vars</h3>
|
|
1249
|
+
<p>Define variables for <a href="#variables"><code>{{VAR}}</code> interpolation</a>. Each argument is either an inline assignment (<code>KEY=value</code>) or a path to a JSON file containing a flat object whose keys are variable names and whose values are strings, numbers or booleans.</p>
|
|
1250
|
+
<p><code>-vars</code> 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 <a href="#-defaults"><code>-defaults</code></a> instead if you want set-if-unset behavior.</p>
|
|
1251
|
+
<p>Values set by <code>-vars</code> are visible to <code>{{X}}</code> substitution but <strong>not</strong> by bare name in JS expressions (<code>-each</code>, <code>-filter</code>, <code>-define</code>, etc.). If you want a value usable from both, set it once with <a href="#-define"><code>-define</code></a> — <code>{{X}}</code> substitution falls back to the expression scope when a name isn't in the templating scope.</p>
|
|
1252
|
+
<p><strong>Options</strong></p>
|
|
1253
|
+
<p><code><values></code> Space-separated list of <code>KEY=value</code> assignments and/or paths to JSON files containing variable definitions.</p>
|
|
1254
|
+
<p><strong>Example</strong></p>
|
|
1255
|
+
<pre><code class="hljs language-bash"><span class="hljs-comment"># Set YEAR=2024 before running the command file</span>
|
|
1256
|
+
mapshaper -vars YEAR=2024 -run build.txt
|
|
1257
|
+
|
|
1258
|
+
<span class="hljs-comment"># Load values from a JSON file, then override one of them</span>
|
|
1259
|
+
mapshaper -vars values.json YEAR=2030 -run build.txt
|
|
1260
|
+
</code></pre>
|
|
1261
|
+
</section>
|
|
1262
|
+
<section class="cmd-section" data-id="-defaults" data-name="-defaults" data-options=""><h3 id="-defaults">-defaults</h3>
|
|
1263
|
+
<p>Like <a href="#-vars"><code>-vars</code></a>, but writes only those keys that are not already defined. Used inside a command file to declare overridable defaults: a CLI <code>-vars</code> (or any earlier write) preempts the command file's <code>-defaults</code> for the same key.</p>
|
|
1264
|
+
<p><strong>Options</strong></p>
|
|
1265
|
+
<p><code><values></code> Space-separated list of <code>KEY=value</code> assignments and/or paths to JSON files containing variable definitions.</p>
|
|
1266
|
+
<p><strong>Example</strong></p>
|
|
1267
|
+
<pre><code class="hljs language-bash"><span class="hljs-comment"># build.txt declares YEAR=2024 as a default; this CLI invocation overrides it</span>
|
|
1268
|
+
mapshaper -vars YEAR=2030 -run build.txt
|
|
1269
|
+
</code></pre>
|
|
1270
|
+
</section>
|
|
1271
|
+
<section class="cmd-section" data-id="-verbose" data-name="-verbose" data-options=""><h3 id="-verbose">-verbose</h3>
|
|
1272
|
+
<p>Print verbose messages, including the time taken by each processing step.</p>
|
|
1273
|
+
</section>
|
|
1274
|
+
<section class="cmd-section" data-id="-version" data-name="-version" data-options=""><h3 id="-version">-version</h3>
|
|
1275
|
+
<p>Print mapshaper version.</p>
|
|
1276
|
+
</section>
|
|
1277
|
+
|
|
1278
|
+
<script src="/docs/_assets/cmd-search.js" defer></script>
|
|
1279
|
+
|
|
1280
|
+
<div class="edit-link">
|
|
1281
|
+
<a href="https://github.com/mbloch/mapshaper/edit/master/docs/reference.md">Edit this page on GitHub</a>
|
|
1282
|
+
</div>
|
|
1283
|
+
</article>
|
|
1284
|
+
</main>
|
|
1285
|
+
|
|
1286
|
+
<aside class="docs-toc">
|
|
1287
|
+
<div class="docs-toc-title">On this page</div><ul><li class="lvl-2"><a href="#command-line-syntax">Command line syntax</a></li><li class="lvl-3"><a href="#command-options-can-take-three-forms">Command options can take three forms:</a></li><li class="lvl-3"><a href="#common-options">Common options</a></li><li class="lvl-2"><a href="#command-files">Command files</a></li><li class="lvl-3"><a href="#file-format">File format</a></li><li class="lvl-3"><a href="#running-a-command-file">Running a command file</a></li><li class="lvl-2"><a href="#variable-interpolation">Variable interpolation</a></li><li class="lvl-2"><a href="#index-of-commands">Index of commands</a></li><li class="lvl-2"><a href="#i-o-commands">I/O Commands</a></li><li class="lvl-3"><a href="#-i-input">-i (input)</a></li><li class="lvl-3"><a href="#-o-output">-o (output)</a></li><li class="lvl-2"><a href="#editing-commands">Editing Commands</a></li><li class="lvl-3"><a href="#-affine">-affine</a></li><li class="lvl-3"><a href="#-classify">-classify</a></li><li class="lvl-3"><a href="#-clean">-clean</a></li><li class="lvl-3"><a href="#-clip">-clip</a></li><li class="lvl-3"><a href="#-colorizer">-colorizer</a></li><li class="lvl-3"><a href="#-dashlines">-dashlines</a></li><li class="lvl-3"><a href="#-dissolve">-dissolve</a></li><li class="lvl-3"><a href="#-dissolve2">-dissolve2</a></li><li class="lvl-3"><a href="#-divide">-divide</a></li><li class="lvl-3"><a href="#-dots">-dots</a></li><li class="lvl-3"><a href="#-drop">-drop</a></li><li class="lvl-3"><a href="#-each">-each</a></li><li class="lvl-3"><a href="#-erase">-erase</a></li><li class="lvl-3"><a href="#-explode">-explode</a></li><li class="lvl-3"><a href="#-filter">-filter</a></li><li class="lvl-3"><a href="#-filter-fields">-filter-fields</a></li><li class="lvl-3"><a href="#-filter-islands">-filter-islands</a></li><li class="lvl-3"><a href="#-filter-slivers">-filter-slivers</a></li><li class="lvl-3"><a href="#-frame">-frame</a></li><li class="lvl-3"><a href="#-graticule">-graticule</a></li><li class="lvl-3"><a href="#-grid">-grid</a></li><li class="lvl-3"><a href="#-include">-include</a></li><li class="lvl-3"><a href="#-inlay">-inlay</a></li><li class="lvl-3"><a href="#-innerlines">-innerlines</a></li><li class="lvl-3"><a href="#-join">-join</a></li><li class="lvl-3"><a href="#-lines">-lines</a></li><li class="lvl-3"><a href="#-merge-layers">-merge-layers</a></li><li class="lvl-3"><a href="#-mosaic">-mosaic</a></li><li class="lvl-3"><a href="#-point-grid">-point-grid</a></li><li class="lvl-3"><a href="#-points">-points</a></li><li class="lvl-3"><a href="#-polygons">-polygons</a></li><li class="lvl-3"><a href="#-proj">-proj</a></li><li class="lvl-3"><a href="#-rectangle">-rectangle</a></li><li class="lvl-3"><a href="#-rectangles">-rectangles</a></li><li class="lvl-3"><a href="#-rename-fields">-rename-fields</a></li><li class="lvl-3"><a href="#-rename-layers">-rename-layers</a></li><li class="lvl-3"><a href="#-require">-require</a></li><li class="lvl-3"><a href="#-run">-run</a></li><li class="lvl-3"><a href="#-scalebar">-scalebar</a></li><li class="lvl-3"><a href="#-shape">-shape</a></li><li class="lvl-3"><a href="#-simplify">-simplify</a></li><li class="lvl-3"><a href="#-snap">-snap</a></li><li class="lvl-3"><a href="#-sort">-sort</a></li><li class="lvl-3"><a href="#-split">-split</a></li><li class="lvl-3"><a href="#-split-on-grid">-split-on-grid</a></li><li class="lvl-3"><a href="#-subdivide">-subdivide</a></li><li class="lvl-3"><a href="#-style">-style</a></li><li class="lvl-3"><a href="#-symbols">-symbols</a></li><li class="lvl-3"><a href="#-union">-union</a></li><li class="lvl-3"><a href="#-uniq">-uniq</a></li><li class="lvl-2"><a href="#control-flow-commands">Control Flow Commands</a></li><li class="lvl-3"><a href="#-if">-if</a></li><li class="lvl-3"><a href="#-elif">-elif</a></li><li class="lvl-3"><a href="#-else">-else</a></li><li class="lvl-3"><a href="#-endif">-endif</a></li><li class="lvl-3"><a href="#-stop">-stop</a></li><li class="lvl-3"><a href="#-target">-target</a></li><li class="lvl-2"><a href="#informational-commands">Informational Commands</a></li><li class="lvl-3"><a href="#-calc">-calc</a></li><li class="lvl-3"><a href="#-colors">-colors</a></li><li class="lvl-3"><a href="#-comment">-comment</a></li><li class="lvl-3"><a href="#-encodings">-encodings</a></li><li class="lvl-3"><a href="#-help">-help</a></li><li class="lvl-3"><a href="#-info">-info</a></li><li class="lvl-3"><a href="#-inspect">-inspect</a></li><li class="lvl-3"><a href="#-print">-print</a></li><li class="lvl-3"><a href="#-projections">-projections</a></li><li class="lvl-3"><a href="#-quiet">-quiet</a></li><li class="lvl-3"><a href="#-vars">-vars</a></li><li class="lvl-3"><a href="#-defaults">-defaults</a></li><li class="lvl-3"><a href="#-verbose">-verbose</a></li><li class="lvl-3"><a href="#-version">-version</a></li></ul>
|
|
1288
|
+
</aside>
|
|
1289
|
+
|
|
1290
|
+
</div>
|
|
1291
|
+
|
|
1292
|
+
<script src="/docs/_assets/docs.js" defer></script>
|
|
1293
|
+
|
|
1294
|
+
<footer class="docs-footer">
|
|
1295
|
+
<div class="docs-footer-inner">
|
|
1296
|
+
<span>mapshaper is free software, licensed under <a href="https://www.mozilla.org/MPL/2.0/">MPL 2.0</a>.</span>
|
|
1297
|
+
<span><a href="/privacy.html">Privacy</a> · <a href="/terms.html">Terms</a> · <a href="/sponsor.html">Support mapshaper</a></span>
|
|
1298
|
+
</div>
|
|
1299
|
+
</footer>
|
|
1300
|
+
|
|
1301
|
+
</body>
|
|
1302
|
+
</html>
|