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.
Files changed (86) hide show
  1. package/README.md +5 -3
  2. package/mapshaper.js +1342 -275
  3. package/package.json +5 -2
  4. package/www/assets/jetbrains-mono-regular.woff2 +0 -0
  5. package/www/assets/static-page.css +179 -0
  6. package/www/docs/_assets/cmd-search.js +213 -0
  7. package/www/docs/_assets/docs.css +712 -0
  8. package/www/docs/_assets/docs.js +75 -0
  9. package/www/docs/_assets/highlight.css +10 -0
  10. package/www/docs/essentials/command-line.html +127 -0
  11. package/www/docs/essentials/command-line.html.md +112 -0
  12. package/www/docs/essentials/web-app.html +138 -0
  13. package/www/docs/essentials/web-app.html.md +106 -0
  14. package/www/docs/examples/basics.html +276 -0
  15. package/www/docs/examples/basics.html.md +371 -0
  16. package/www/docs/examples/data/Makefile +31 -0
  17. package/www/docs/examples/data/globe.msx +0 -0
  18. package/www/docs/examples/data/globe.svg +616 -0
  19. package/www/docs/examples/data/globe.txt +21 -0
  20. package/www/docs/examples/data/globe.zip +0 -0
  21. package/www/docs/examples/data/ne_50m_admin_0_countries.geojson +1 -0
  22. package/www/docs/examples/data/ne_50m_admin_1_states_provinces_lakes.geojson +1 -0
  23. package/www/docs/examples/data/us-states.msx +0 -0
  24. package/www/docs/examples/data/us-states.svg +56 -0
  25. package/www/docs/examples/data/us-states.txt +6 -0
  26. package/www/docs/examples/data/us-states.zip +0 -0
  27. package/www/docs/examples/globe.html +108 -0
  28. package/www/docs/examples/globe.html.md +64 -0
  29. package/www/docs/examples/us-states.html +88 -0
  30. package/www/docs/examples/us-states.html.md +44 -0
  31. package/www/docs/formats/csv.html +127 -0
  32. package/www/docs/formats/csv.html.md +97 -0
  33. package/www/docs/formats/dbf.html +87 -0
  34. package/www/docs/formats/dbf.html.md +39 -0
  35. package/www/docs/formats/flatgeobuf.html +86 -0
  36. package/www/docs/formats/flatgeobuf.html.md +42 -0
  37. package/www/docs/formats/geojson.html +107 -0
  38. package/www/docs/formats/geojson.html.md +65 -0
  39. package/www/docs/formats/geopackage.html +87 -0
  40. package/www/docs/formats/geopackage.html.md +42 -0
  41. package/www/docs/formats/json.html +83 -0
  42. package/www/docs/formats/json.html.md +35 -0
  43. package/www/docs/formats/kml.html +82 -0
  44. package/www/docs/formats/kml.html.md +39 -0
  45. package/www/docs/formats/overview.html +192 -0
  46. package/www/docs/formats/overview.html.md +35 -0
  47. package/www/docs/formats/shapefile.html +123 -0
  48. package/www/docs/formats/shapefile.html.md +84 -0
  49. package/www/docs/formats/snapshot.html +87 -0
  50. package/www/docs/formats/snapshot.html.md +39 -0
  51. package/www/docs/formats/svg.html +99 -0
  52. package/www/docs/formats/svg.html.md +51 -0
  53. package/www/docs/formats/topojson.html +102 -0
  54. package/www/docs/formats/topojson.html.md +54 -0
  55. package/www/docs/gallery/index.html +80 -0
  56. package/www/docs/gallery/index.html.md +29 -0
  57. package/www/docs/guides/combining-layers.html +105 -0
  58. package/www/docs/guides/combining-layers.html.md +81 -0
  59. package/www/docs/guides/expressions.html +600 -0
  60. package/www/docs/guides/expressions.html.md +376 -0
  61. package/www/docs/guides/programmatic.html +117 -0
  62. package/www/docs/guides/programmatic.html.md +91 -0
  63. package/www/docs/guides/projections.html +158 -0
  64. package/www/docs/guides/projections.html.md +118 -0
  65. package/www/docs/guides/simplification.html +110 -0
  66. package/www/docs/guides/simplification.html.md +94 -0
  67. package/www/docs/guides/topology.html +90 -0
  68. package/www/docs/guides/topology.html.md +63 -0
  69. package/www/docs/images/simplification-detail.png +0 -0
  70. package/www/docs/images/simplification-dp.png +0 -0
  71. package/www/docs/images/simplification-mod2.png +0 -0
  72. package/www/docs/index.html +101 -0
  73. package/www/docs/index.html.md +59 -0
  74. package/www/docs/reference.html +1302 -0
  75. package/www/docs/reference.html.md +1817 -0
  76. package/www/docs/whats-new.html +76 -0
  77. package/www/docs/whats-new.html.md +53 -0
  78. package/www/index.html +30 -3
  79. package/www/llms-full.txt +4040 -0
  80. package/www/llms.txt +55 -0
  81. package/www/mapshaper-gui.js +7 -1
  82. package/www/mapshaper.js +1342 -275
  83. package/www/page.css +1 -1
  84. package/www/privacy.html +1 -112
  85. package/www/sponsor.html +4 -164
  86. package/www/terms.html +1 -112
package/www/docs/formats/kml.html.md ADDED
@@ -0,0 +1,39 @@
1
+ ---
2
+ title: KML and KMZ
3
+ description: How Mapshaper reads and writes KML and KMZ files for use with Google Earth and similar tools.
4
+ ---
5
+
6
+ # KML and KMZ
7
+
8
+ KML is Google's XML-based format for geographic data, originally created for Google Earth and now an OGC standard. KMZ is a zipped KML. KML emphasises display (icons, styles, balloons) over attributes, so it's most useful for handing files to viewers like Google Earth, mobile mapping apps and Google My Maps — as a data interchange format it has weaker attribute typing and schema support than [GeoJSON](/docs/formats/geojson.html.md) or [Shapefile](/docs/formats/shapefile.html.md).
9
+
10
+ **File extensions:** `.kml`, `.kmz` · **Read:** ✓ · **Write:** ✓ · **Multi-layer:** ✓
11
+
12
+ ### CLI examples
13
+
14
+ ```bash
15
+ mapshaper places.kml -info
16
+ mapshaper places.kmz -o format=geojson places.geojson
17
+ mapshaper provinces.shp -proj wgs84 -o provinces.kml
18
+ ```
19
+
20
+ ### Format-specific input options
21
+
22
+ There are no KML-specific `-i` options. Encoding is always UTF-8 per the KML spec.
23
+
24
+ ### Format-specific output options
25
+
26
+ There are no KML-specific `-o` options.
27
+
28
+ ### Practical notes
29
+
30
+ - KML stores all attribute values as strings, so numeric attributes are imported as strings.
31
+ - KML requires WGS84 coordinates, but Mapshaper does **not** reproject on export — coordinates are written through as-is. If your dataset is in any other CRS, run `-proj wgs84` first, otherwise the output will not be conformant KML and viewers will misplace the geometry.
32
+
33
+
34
+ ## External resources
35
+
36
+ - [OGC KML standard](https://www.ogc.org/standards/kml/) — the formal OGC specification.
37
+ - [Google KML Reference](https://developers.google.com/kml/documentation/kmlreference) — the practical element-by-element reference; more readable than the OGC spec.
38
+ - [Google KML Tutorial](https://developers.google.com/kml/documentation/kml_tut) — covers how Google Earth interprets the format.
39
+ - KML reading and writing in Mapshaper is delegated to two third-party libraries: [`@tmcw/togeojson`](https://github.com/placemark/togeojson) for parsing KML into GeoJSON on import, and [`@placemarkio/tokml`](https://github.com/placemark/tokml) for serialising GeoJSON back to KML on export.
package/www/docs/formats/overview.html ADDED
@@ -0,0 +1,192 @@
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>File formats &middot; mapshaper docs</title>
7
+ <meta name="description" content="A quick comparison of every file format Mapshaper can read and write, with links to per-format details.">
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&#39;s new</a></li><li><a href="/docs/reference.html">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" class="is-active">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
+ <div class="docs-breadcrumbs"><a href="/docs/">Docs</a> &rsaquo; Formats &rsaquo; Overview</div>
35
+ <h1 id="file-formats">File formats</h1>
36
+ <p>This section explains how each supported file format is handled, what format-specific options are available, and what to watch out for.</p>
37
+ <h2 id="comparison">Comparison</h2>
38
+ <div class="formats-table-wrap"><table>
39
+ <thead>
40
+ <tr>
41
+ <th>Format</th>
42
+ <th>Extension</th>
43
+ <th align="center">Read</th>
44
+ <th align="center">Write</th>
45
+ <th>Geometry</th>
46
+ <th>Attributes</th>
47
+ <th align="center">Topology</th>
48
+ <th align="center">Multi-layer</th>
49
+ </tr>
50
+ </thead>
51
+ <tbody><tr>
52
+ <td><a href="/docs/formats/shapefile.html">Shapefile</a></td>
53
+ <td><code>.shp</code></td>
54
+ <td align="center">&check;</td>
55
+ <td align="center">&check;</td>
56
+ <td>vector</td>
57
+ <td>DBF (10-char names)</td>
58
+ <td align="center">&mdash;</td>
59
+ <td align="center">&mdash;</td>
60
+ </tr>
61
+ <tr>
62
+ <td><a href="/docs/formats/geojson.html">GeoJSON</a></td>
63
+ <td><code>.json</code> <code>.geojson</code></td>
64
+ <td align="center">&check;</td>
65
+ <td align="center">&check;</td>
66
+ <td>vector</td>
67
+ <td>yes</td>
68
+ <td align="center">&mdash;</td>
69
+ <td align="center">&mdash;</td>
70
+ </tr>
71
+ <tr>
72
+ <td><a href="/docs/formats/topojson.html">TopoJSON</a></td>
73
+ <td><code>.json</code> <code>.topojson</code></td>
74
+ <td align="center">&check;</td>
75
+ <td align="center">&check;</td>
76
+ <td>vector</td>
77
+ <td>yes</td>
78
+ <td align="center"><strong>&check;</strong></td>
79
+ <td align="center">&check;</td>
80
+ </tr>
81
+ <tr>
82
+ <td><a href="/docs/formats/geopackage.html">GeoPackage</a></td>
83
+ <td><code>.gpkg</code></td>
84
+ <td align="center">&check;</td>
85
+ <td align="center">&check;</td>
86
+ <td>vector</td>
87
+ <td>yes</td>
88
+ <td align="center">&mdash;</td>
89
+ <td align="center">&check;</td>
90
+ </tr>
91
+ <tr>
92
+ <td><a href="/docs/formats/flatgeobuf.html">FlatGeobuf</a></td>
93
+ <td><code>.fgb</code></td>
94
+ <td align="center">&check;</td>
95
+ <td align="center">&check;</td>
96
+ <td>vector</td>
97
+ <td>yes</td>
98
+ <td align="center">&mdash;</td>
99
+ <td align="center">&mdash;</td>
100
+ </tr>
101
+ <tr>
102
+ <td><a href="/docs/formats/kml.html">KML / KMZ</a></td>
103
+ <td><code>.kml</code> <code>.kmz</code></td>
104
+ <td align="center">&check;</td>
105
+ <td align="center">&check;</td>
106
+ <td>vector</td>
107
+ <td>limited</td>
108
+ <td align="center">&mdash;</td>
109
+ <td align="center">&check;</td>
110
+ </tr>
111
+ <tr>
112
+ <td><a href="/docs/formats/csv.html">CSV / TSV</a></td>
113
+ <td><code>.csv</code> <code>.tsv</code></td>
114
+ <td align="center">&check;</td>
115
+ <td align="center">&check;</td>
116
+ <td>points (X/Y)</td>
117
+ <td>yes</td>
118
+ <td align="center">&mdash;</td>
119
+ <td align="center">&mdash;</td>
120
+ </tr>
121
+ <tr>
122
+ <td><a href="/docs/formats/dbf.html">DBF</a></td>
123
+ <td><code>.dbf</code></td>
124
+ <td align="center">&check;</td>
125
+ <td align="center">&check;</td>
126
+ <td>none</td>
127
+ <td>yes</td>
128
+ <td align="center">&mdash;</td>
129
+ <td align="center">&mdash;</td>
130
+ </tr>
131
+ <tr>
132
+ <td><a href="/docs/formats/json.html">JSON records</a></td>
133
+ <td><code>.json</code></td>
134
+ <td align="center">&check;</td>
135
+ <td align="center">&check;</td>
136
+ <td>none</td>
137
+ <td>yes</td>
138
+ <td align="center">&mdash;</td>
139
+ <td align="center">&mdash;</td>
140
+ </tr>
141
+ <tr>
142
+ <td><a href="/docs/formats/svg.html">SVG</a></td>
143
+ <td><code>.svg</code></td>
144
+ <td align="center">&check;</td>
145
+ <td align="center">&check;</td>
146
+ <td>vector</td>
147
+ <td>as <code>data-*</code></td>
148
+ <td align="center">&mdash;</td>
149
+ <td align="center">&check;</td>
150
+ </tr>
151
+ <tr>
152
+ <td><a href="/docs/formats/snapshot.html">Mapshaper snapshot</a></td>
153
+ <td><code>.msx</code></td>
154
+ <td align="center">&check;</td>
155
+ <td align="center">&check;</td>
156
+ <td>vector</td>
157
+ <td>yes</td>
158
+ <td align="center"><strong>&check;</strong></td>
159
+ <td align="center">&check;</td>
160
+ </tr>
161
+ </tbody></table>
162
+ </div><p>A few things worth knowing across all formats:</p>
163
+ <ul>
164
+ <li><strong>Auto-detection by extension.</strong> You usually don&#39;t need to tell Mapshaper what format a file is &mdash; it picks the right reader from the file extension. Use <code>format=</code> on <code>-i</code> or <code>-o</code> to override.</li>
165
+ <li><strong>TopoJSON is the only interchange format that preserves topology</strong> in the file itself. Topology-aware operations like <a href="/docs/reference.html#-dissolve"><code>-dissolve</code></a>, <a href="/docs/reference.html#-clean"><code>-clean</code></a> and <a href="/docs/reference.html#-simplify"><code>-simplify</code></a> work correctly regardless of the input format, but only TopoJSON keeps shared boundaries between adjacent polygons from being duplicated on disk. (Mapshaper&#39;s own <a href="/docs/formats/snapshot.html"><code>.msx</code></a> snapshots also preserve topology, but they&#39;re not readable by other tools.)</li>
166
+ <li><strong>Most formats are single-layer per file.</strong> Multi-layer GeoJSON, Shapefile and FlatGeobuf datasets are conventionally split across multiple files (in the same directory on the CLI; selected together or zipped in the <a href="/docs/essentials/web-app.html">web app</a>); TopoJSON, GeoPackage and KML can hold many layers in one file.</li>
167
+ <li><strong>Encoding.</strong> The <code>encoding=</code> option on <code>-i</code> and <code>-o</code> applies to Shapefile, DBF and CSV/TSV i/o (UTF-8 is the default) &mdash; the other formats are UTF-8-only.</li>
168
+ </ul>
169
+
170
+ <div class="edit-link">
171
+ <a href="https://github.com/mbloch/mapshaper/edit/master/docs/formats/overview.md">Edit this page on GitHub</a>
172
+ </div>
173
+ </article>
174
+ </main>
175
+
176
+ <aside class="docs-toc">
177
+ <div class="docs-toc-title">On this page</div><ul><li class="lvl-2"><a href="#comparison">Comparison</a></li></ul>
178
+ </aside>
179
+
180
+ </div>
181
+
182
+ <script src="/docs/_assets/docs.js" defer></script>
183
+
184
+ <footer class="docs-footer">
185
+ <div class="docs-footer-inner">
186
+ <span>mapshaper is free software, licensed under <a href="https://www.mozilla.org/MPL/2.0/">MPL 2.0</a>.</span>
187
+ <span><a href="/privacy.html">Privacy</a> &middot; <a href="/terms.html">Terms</a> &middot; <a href="/sponsor.html">Support mapshaper</a></span>
188
+ </div>
189
+ </footer>
190
+
191
+ </body>
192
+ </html>
package/www/docs/formats/overview.html.md ADDED
@@ -0,0 +1,35 @@
1
+ ---
2
+ title: File formats
3
+ description: A quick comparison of every file format Mapshaper can read and write, with links to per-format details.
4
+ ---
5
+
6
+ # File formats
7
+
8
+ This section explains how each supported file format is handled, what format-specific options are available, and what to watch out for.
9
+
10
+ ## Comparison
11
+
12
+ <div class="formats-table-wrap">
13
+
14
+ | Format | Extension | Read | Write | Geometry | Attributes | Topology | Multi-layer |
15
+ |---|---|:---:|:---:|---|---|:---:|:---:|
16
+ | [Shapefile](/docs/formats/shapefile.html.md) | `.shp` | &check; | &check; | vector | DBF (10-char names) | &mdash; | &mdash; |
17
+ | [GeoJSON](/docs/formats/geojson.html.md) | `.json` `.geojson` | &check; | &check; | vector | yes | &mdash; | &mdash; |
18
+ | [TopoJSON](/docs/formats/topojson.html.md) | `.json` `.topojson` | &check; | &check; | vector | yes | **&check;** | &check; |
19
+ | [GeoPackage](/docs/formats/geopackage.html.md) | `.gpkg` | &check; | &check; | vector | yes | &mdash; | &check; |
20
+ | [FlatGeobuf](/docs/formats/flatgeobuf.html.md) | `.fgb` | &check; | &check; | vector | yes | &mdash; | &mdash; |
21
+ | [KML / KMZ](/docs/formats/kml.html.md) | `.kml` `.kmz` | &check; | &check; | vector | limited | &mdash; | &check; |
22
+ | [CSV / TSV](/docs/formats/csv.html.md) | `.csv` `.tsv` | &check; | &check; | points (X/Y) | yes | &mdash; | &mdash; |
23
+ | [DBF](/docs/formats/dbf.html.md) | `.dbf` | &check; | &check; | none | yes | &mdash; | &mdash; |
24
+ | [JSON records](/docs/formats/json.html.md) | `.json` | &check; | &check; | none | yes | &mdash; | &mdash; |
25
+ | [SVG](/docs/formats/svg.html.md) | `.svg` | &check; | &check; | vector | as `data-*` | &mdash; | &check; |
26
+ | [Mapshaper snapshot](/docs/formats/snapshot.html.md) | `.msx` | &check; | &check; | vector | yes | **&check;** | &check; |
27
+
28
+ </div>
29
+
30
+ A few things worth knowing across all formats:
31
+
32
+ - **Auto-detection by extension.** You usually don't need to tell Mapshaper what format a file is &mdash; it picks the right reader from the file extension. Use `format=` on `-i` or `-o` to override.
33
+ - **TopoJSON is the only interchange format that preserves topology** in the file itself. Topology-aware operations like [`-dissolve`](/docs/reference.html.md#-dissolve), [`-clean`](/docs/reference.html.md#-clean) and [`-simplify`](/docs/reference.html.md#-simplify) work correctly regardless of the input format, but only TopoJSON keeps shared boundaries between adjacent polygons from being duplicated on disk. (Mapshaper's own [`.msx`](/docs/formats/snapshot.html.md) snapshots also preserve topology, but they're not readable by other tools.)
34
+ - **Most formats are single-layer per file.** Multi-layer GeoJSON, Shapefile and FlatGeobuf datasets are conventionally split across multiple files (in the same directory on the CLI; selected together or zipped in the [web app](/docs/essentials/web-app.html.md)); TopoJSON, GeoPackage and KML can hold many layers in one file.
35
+ - **Encoding.** The `encoding=` option on `-i` and `-o` applies to Shapefile, DBF and CSV/TSV i/o (UTF-8 is the default) &mdash; the other formats are UTF-8-only.
package/www/docs/formats/shapefile.html ADDED
@@ -0,0 +1,123 @@
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>Shapefile &middot; mapshaper docs</title>
7
+ <meta name="description" content="How Mapshaper reads and writes ESRI Shapefiles, including encoding and field-name notes.">
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&#39;s new</a></li><li><a href="/docs/reference.html">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" class="is-active">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
+ <div class="docs-breadcrumbs"><a href="/docs/">Docs</a> &rsaquo; Formats &rsaquo; Shapefile</div>
35
+ <h1 id="shapefile">Shapefile</h1>
36
+ <p>Shapefile is ESRI&#39;s long-standing vector format and remains widely used as an exchange format in desktop GIS workflows. Rather than a single file, a Shapefile is a collection of files — at minimum .shp, .shx, and .dbf, plus commonly .prj (coordinate reference system) and .cpg (character encoding). It has well-known limitations, including a 2 GB size cap per component file, attribute field names limited to 10 characters, attribute values limited to 254 characters, no support for mixed geometry types, and unreliable character encoding declaration. Newer formats like <a href="/docs/formats/geopackage.html">GeoPackage</a> and <a href="/docs/formats/flatgeobuf.html">FlatGeobuf</a> solve most of the limitations.</p>
37
+ <p><strong>File extensions:</strong> <code>.shp</code> (geometry), <code>.dbf</code> (attributes), <code>.shx</code> (index), <code>.prj</code> (projection), <code>.cpg</code> (encoding hint)
38
+ &middot; <strong>Read:</strong> &check; &middot; <strong>Write:</strong> &check; &middot; <strong>Multi-layer:</strong> no</p>
39
+ <h3 id="cli-examples">CLI examples</h3>
40
+ <pre><code class="hljs language-bash">mapshaper provinces.shp -info
41
+ mapshaper provinces.shp -simplify 20% -o provinces.geojson
42
+ mapshaper input.geojson -o provinces.shp
43
+ </code></pre>
44
+ <h3 id="format-specific-input-options">Format-specific input options</h3>
45
+ <ul>
46
+ <li><code>encoding=</code> &mdash; encoding used by the <code>.dbf</code> text fields. If omitted, Mapshaper auto-detects, falling back to the value declared in a <code>.cpg</code> file when present. Common values: <code>latin1</code>, <code>utf8</code>, <code>gb18030</code>. Run <code>mapshaper -encodings</code> for the full list.</li>
47
+ </ul>
48
+ <h3 id="format-specific-output-options">Format-specific output options</h3>
49
+ <ul>
50
+ <li><code>encoding=</code> &mdash; text encoding for the <code>.dbf</code>. Defaults to UTF-8 (with a matching <code>.cpg</code> sidecar).</li>
51
+ <li><code>field-order=ascending</code> &mdash; sort attribute fields alphabetically (case-insensitive).</li>
52
+ </ul>
53
+ <h3 id="practical-notes">Practical notes</h3>
54
+ <ul>
55
+ <li>A Shapefile dataset is a bundle of files sharing a base name. The Mapshaper CLI inputs the <code>.shp</code> and picks up any sibling <code>.dbf</code>, <code>.shx</code>, <code>.prj</code> and <code>.cpg</code> files automatically. In the <a href="/docs/essentials/web-app.html">web app</a> you select or drag-drop them together &mdash; see <a href="#in-the-web-app">In the web app</a> below.</li>
56
+ <li>Field names longer than 10 characters are silently truncated on write, which can produce duplicates. Mapshaper disambiguates by appending digits, or you can rename fields beforehand with <a href="/docs/reference.html#-rename-fields"><code>-rename-fields</code></a>.</li>
57
+ <li>Field values longer than 254 characters are truncated on write.</li>
58
+ <li>Mapshaper does not fully support M (measured) and Z (3D) Shapefiles &mdash; M and Z values are dropped on import.</li>
59
+ <li>When exporting, the Mapshaper CLI produces separate companion files (<code>.shp</code>, <code>.shx</code>, <code>.dbf</code>, <code>.prj</code>). In the web app, the component files get bundled in a <code>.zip</code> file.</li>
60
+ <li>If the <code>.prj</code> file is missing, Mapshaper reads the geometry without coordinate-reference information. Coordinates in the lat-long range are assumed to be WGS-84. You can use the <code>-proj</code> command to assign a CRS (e.g. <code>-proj init=...</code>).</li>
61
+ <li>A standalone <code>.dbf</code> can be imported on its own as a tabular layer &mdash; see the <a href="/docs/formats/dbf.html">DBF page</a>.</li>
62
+ </ul>
63
+ <h3 id="in-the-web-app">In the web app</h3>
64
+ <p>Browsers can&#39;t read files from the filesystem the CLI can, so you have to supply all the parts of a Shapefile together. Two options are:</p>
65
+ <ol>
66
+ <li><strong>Select all the components together.</strong> Click <strong>Add files</strong> and shift- or cmd-click the <code>.shp</code>, <code>.dbf</code>, <code>.prj</code> (and <code>.shx</code>/<code>.cpg</code> if present) in one go, or drag the whole selection onto the import area.</li>
67
+ <li><strong>Drop a <code>.zip</code> containing the bundle.</strong> Shapefiles are very commonly distributed this way.</li>
68
+ </ol>
69
+ <p>If the import warns about an unknown text encoding, re-import with the <strong>with advanced options</strong> checkbox ticked and pass <code>encoding=</code> (e.g. <code>encoding=win1252</code>, <code>encoding=gb18030</code>). The same <code>encoding=</code> values that work on the CLI work here.</p>
70
+ <h3 id="reading-a-shapefile-with-missing-sidecars">Reading a Shapefile with missing sidecars</h3>
71
+ <p>Mapshaper will read a <code>.shp</code> whose <code>.dbf</code> and/or <code>.shx</code> companion files are missing &mdash; useful when you&#39;re handed an incomplete bundle, or when you only care about geometry:</p>
72
+ <ul>
73
+ <li><strong>Missing <code>.dbf</code></strong>: the geometry is imported with no attribute table.</li>
74
+ <li><strong>Missing <code>.shx</code></strong>: Mapshaper recovers feature offsets by reading the <code>.shp</code> directly. This works for normal Shapefiles with densely-packed records; it only fails on the rare Shapefiles that contain out-of-order records, where the <code>.shx</code> is needed to locate each feature.</li>
75
+ </ul>
76
+ <h3 id="dbf-text-encoding"><code>.dbf</code> text encoding</h3>
77
+ <p>The .dbf format is a legacy binary format dating to dBASE III in the early 1980s, predating Unicode. Character encoding is not declared within the file itself, which can cause encoding errors when working with Shapefiles containing non-ASCII characters. In practice, most Shapefiles now come with a <code>.cpg</code> file or use UTF-8, which is almost always auto-detected correctly.</p>
78
+ <p>Mapshaper handles encoding in the following order:</p>
79
+ <ol>
80
+ <li>If <code>encoding=</code> is set on <code>-i</code>, that wins.</li>
81
+ <li>If a <code>.cpg</code> sidecar file is present, Mapshaper uses the encoding it names.</li>
82
+ <li>Otherwise Mapshaper tries to auto-detect the encoding from the <code>.dbf</code> contents.</li>
83
+ </ol>
84
+ <p>Auto-detection covers most public datasets, but it can guess wrong on sparsely-populated columns or unusual codepages. If you see mojibake (<code>é</code> instead of <code>é</code>, <code>?</code> characters where accented letters should be), set <code>encoding=</code> explicitly:</p>
85
+ <pre><code class="hljs language-bash">mapshaper -i provinces.shp encoding=utf8 -info
86
+ mapshaper -i historical.shp encoding=win1252 -o cleaned.geojson
87
+ mapshaper -i china.shp encoding=gb18030 -o cleaned.geojson
88
+ </code></pre>
89
+ <p>When writing, Mapshaper emits UTF-8 plus a <code>.cpg</code> sidecar by default so other tools can decode correctly. Override with <code>encoding=</code> on <code>-o</code> if a downstream consumer requires a specific codepage.</p>
90
+ <h2 id="external-resources">External resources</h2>
91
+ <ul>
92
+ <li><a href="https://desktop.arcgis.com/en/arcmap/latest/manage-data/shapefiles/shapefile-file-extensions.htm">Shapefile file extensions (ArcMap docs)</a> &mdash; ESRI&#39;s own practical reference describing what each <code>.shp</code>/<code>.shx</code>/<code>.dbf</code>/<code>.prj</code>/<code>.cpg</code>/<code>.sbn</code> etc. file actually contains. Useful when you encounter unfamiliar sidecar files.</li>
93
+ <li><a href="https://switchfromshapefile.org/">Switch from Shapefile</a> &mdash; a long-running campaign cataloguing the format&#39;s well-known limitations and pointing to alternatives.</li>
94
+ <li><a href="https://www.esri.com/content/dam/esrisites/sitecore-archive/Files/Pdfs/library/whitepapers/pdfs/shapefile.pdf">ESRI Shapefile Technical Description (PDF)</a> &mdash; the original 1998 white paper that defines the format. Dry but authoritative.</li>
95
+ </ul>
96
+ <h2 id="see-also">See also</h2>
97
+ <ul>
98
+ <li><a href="/docs/formats/dbf.html">DBF format</a></li>
99
+ </ul>
100
+
101
+ <div class="edit-link">
102
+ <a href="https://github.com/mbloch/mapshaper/edit/master/docs/formats/shapefile.md">Edit this page on GitHub</a>
103
+ </div>
104
+ </article>
105
+ </main>
106
+
107
+ <aside class="docs-toc">
108
+ <div class="docs-toc-title">On this page</div><ul><li class="lvl-3"><a href="#cli-examples">CLI examples</a></li><li class="lvl-3"><a href="#format-specific-input-options">Format-specific input options</a></li><li class="lvl-3"><a href="#format-specific-output-options">Format-specific output options</a></li><li class="lvl-3"><a href="#practical-notes">Practical notes</a></li><li class="lvl-3"><a href="#in-the-web-app">In the web app</a></li><li class="lvl-3"><a href="#reading-a-shapefile-with-missing-sidecars">Reading a Shapefile with missing sidecars</a></li><li class="lvl-3"><a href="#dbf-text-encoding">.dbf text encoding</a></li><li class="lvl-2"><a href="#external-resources">External resources</a></li><li class="lvl-2"><a href="#see-also">See also</a></li></ul>
109
+ </aside>
110
+
111
+ </div>
112
+
113
+ <script src="/docs/_assets/docs.js" defer></script>
114
+
115
+ <footer class="docs-footer">
116
+ <div class="docs-footer-inner">
117
+ <span>mapshaper is free software, licensed under <a href="https://www.mozilla.org/MPL/2.0/">MPL 2.0</a>.</span>
118
+ <span><a href="/privacy.html">Privacy</a> &middot; <a href="/terms.html">Terms</a> &middot; <a href="/sponsor.html">Support mapshaper</a></span>
119
+ </div>
120
+ </footer>
121
+
122
+ </body>
123
+ </html>
package/www/docs/formats/shapefile.html.md ADDED
@@ -0,0 +1,84 @@
1
+ ---
2
+ title: Shapefile
3
+ description: How Mapshaper reads and writes ESRI Shapefiles, including encoding and field-name notes.
4
+ ---
5
+
6
+ # Shapefile
7
+
8
+ Shapefile is ESRI's long-standing vector format and remains widely used as an exchange format in desktop GIS workflows. Rather than a single file, a Shapefile is a collection of files — at minimum .shp, .shx, and .dbf, plus commonly .prj (coordinate reference system) and .cpg (character encoding). It has well-known limitations, including a 2 GB size cap per component file, attribute field names limited to 10 characters, attribute values limited to 254 characters, no support for mixed geometry types, and unreliable character encoding declaration. Newer formats like [GeoPackage](/docs/formats/geopackage.html.md) and [FlatGeobuf](/docs/formats/flatgeobuf.html.md) solve most of the limitations.
9
+
10
+ **File extensions:** `.shp` (geometry), `.dbf` (attributes), `.shx` (index), `.prj` (projection), `.cpg` (encoding hint)
11
+ &middot; **Read:** &check; &middot; **Write:** &check; &middot; **Multi-layer:** no
12
+
13
+ ### CLI examples
14
+
15
+ ```bash
16
+ mapshaper provinces.shp -info
17
+ mapshaper provinces.shp -simplify 20% -o provinces.geojson
18
+ mapshaper input.geojson -o provinces.shp
19
+ ```
20
+
21
+ ### Format-specific input options
22
+
23
+ - `encoding=` &mdash; encoding used by the `.dbf` text fields. If omitted, Mapshaper auto-detects, falling back to the value declared in a `.cpg` file when present. Common values: `latin1`, `utf8`, `gb18030`. Run `mapshaper -encodings` for the full list.
24
+
25
+ ### Format-specific output options
26
+
27
+ - `encoding=` &mdash; text encoding for the `.dbf`. Defaults to UTF-8 (with a matching `.cpg` sidecar).
28
+ - `field-order=ascending` &mdash; sort attribute fields alphabetically (case-insensitive).
29
+
30
+ ### Practical notes
31
+
32
+ - A Shapefile dataset is a bundle of files sharing a base name. The Mapshaper CLI inputs the `.shp` and picks up any sibling `.dbf`, `.shx`, `.prj` and `.cpg` files automatically. In the [web app](/docs/essentials/web-app.html.md) you select or drag-drop them together &mdash; see [In the web app](#in-the-web-app) below.
33
+ - Field names longer than 10 characters are silently truncated on write, which can produce duplicates. Mapshaper disambiguates by appending digits, or you can rename fields beforehand with [`-rename-fields`](/docs/reference.html.md#-rename-fields).
34
+ - Field values longer than 254 characters are truncated on write.
35
+ - Mapshaper does not fully support M (measured) and Z (3D) Shapefiles &mdash; M and Z values are dropped on import.
36
+ - When exporting, the Mapshaper CLI produces separate companion files (`.shp`, `.shx`, `.dbf`, `.prj`). In the web app, the component files get bundled in a `.zip` file.
37
+ - If the `.prj` file is missing, Mapshaper reads the geometry without coordinate-reference information. Coordinates in the lat-long range are assumed to be WGS-84. You can use the `-proj` command to assign a CRS (e.g. `-proj init=...`).
38
+ - A standalone `.dbf` can be imported on its own as a tabular layer &mdash; see the [DBF page](/docs/formats/dbf.html.md).
39
+
40
+ ### In the web app
41
+
42
+ Browsers can't read files from the filesystem the CLI can, so you have to supply all the parts of a Shapefile together. Two options are:
43
+
44
+ 1. **Select all the components together.** Click **Add files** and shift- or cmd-click the `.shp`, `.dbf`, `.prj` (and `.shx`/`.cpg` if present) in one go, or drag the whole selection onto the import area.
45
+ 2. **Drop a `.zip` containing the bundle.** Shapefiles are very commonly distributed this way.
46
+
47
+ If the import warns about an unknown text encoding, re-import with the **with advanced options** checkbox ticked and pass `encoding=` (e.g. `encoding=win1252`, `encoding=gb18030`). The same `encoding=` values that work on the CLI work here.
48
+
49
+ ### Reading a Shapefile with missing sidecars
50
+
51
+ Mapshaper will read a `.shp` whose `.dbf` and/or `.shx` companion files are missing &mdash; useful when you're handed an incomplete bundle, or when you only care about geometry:
52
+
53
+ - **Missing `.dbf`**: the geometry is imported with no attribute table.
54
+ - **Missing `.shx`**: Mapshaper recovers feature offsets by reading the `.shp` directly. This works for normal Shapefiles with densely-packed records; it only fails on the rare Shapefiles that contain out-of-order records, where the `.shx` is needed to locate each feature.
55
+
56
+ ### `.dbf` text encoding
57
+
58
+ The .dbf format is a legacy binary format dating to dBASE III in the early 1980s, predating Unicode. Character encoding is not declared within the file itself, which can cause encoding errors when working with Shapefiles containing non-ASCII characters. In practice, most Shapefiles now come with a `.cpg` file or use UTF-8, which is almost always auto-detected correctly.
59
+
60
+ Mapshaper handles encoding in the following order:
61
+
62
+ 1. If `encoding=` is set on `-i`, that wins.
63
+ 2. If a `.cpg` sidecar file is present, Mapshaper uses the encoding it names.
64
+ 3. Otherwise Mapshaper tries to auto-detect the encoding from the `.dbf` contents.
65
+
66
+ Auto-detection covers most public datasets, but it can guess wrong on sparsely-populated columns or unusual codepages. If you see mojibake (`é` instead of `é`, `?` characters where accented letters should be), set `encoding=` explicitly:
67
+
68
+ ```bash
69
+ mapshaper -i provinces.shp encoding=utf8 -info
70
+ mapshaper -i historical.shp encoding=win1252 -o cleaned.geojson
71
+ mapshaper -i china.shp encoding=gb18030 -o cleaned.geojson
72
+ ```
73
+
74
+ When writing, Mapshaper emits UTF-8 plus a `.cpg` sidecar by default so other tools can decode correctly. Override with `encoding=` on `-o` if a downstream consumer requires a specific codepage.
75
+
76
+ ## External resources
77
+
78
+ - [Shapefile file extensions (ArcMap docs)](https://desktop.arcgis.com/en/arcmap/latest/manage-data/shapefiles/shapefile-file-extensions.htm) &mdash; ESRI's own practical reference describing what each `.shp`/`.shx`/`.dbf`/`.prj`/`.cpg`/`.sbn` etc. file actually contains. Useful when you encounter unfamiliar sidecar files.
79
+ - [Switch from Shapefile](https://switchfromshapefile.org/) &mdash; a long-running campaign cataloguing the format's well-known limitations and pointing to alternatives.
80
+ - [ESRI Shapefile Technical Description (PDF)](https://www.esri.com/content/dam/esrisites/sitecore-archive/Files/Pdfs/library/whitepapers/pdfs/shapefile.pdf) &mdash; the original 1998 white paper that defines the format. Dry but authoritative.
81
+
82
+ ## See also
83
+
84
+ - [DBF format](/docs/formats/dbf.html.md)
package/www/docs/formats/snapshot.html ADDED
@@ -0,0 +1,87 @@
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>Mapshaper snapshot (.msx) &middot; mapshaper docs</title>
7
+ <meta name="description" content="A single-file binary snapshot of a Mapshaper session, used to save work in progress and share reproducible projects.">
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&#39;s new</a></li><li><a href="/docs/reference.html">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" class="is-active">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
+ <div class="docs-breadcrumbs"><a href="/docs/">Docs</a> &rsaquo; Formats &rsaquo; Mapshaper snapshot</div>
35
+ <h1 id="mapshaper-snapshot-msx">Mapshaper snapshot (.msx)</h1>
36
+ <p>A Mapshaper snapshot captures the current state of a session &mdash; arcs, layers, attributes, CRS metadata, topology and (when written from the web app) the command history that produced it &mdash; as a single binary file. Snapshots are Mapshaper-specific and not intended for interchange with other GIS tools; for that, use <a href="/docs/formats/shapefile.html">Shapefile</a>, <a href="/docs/formats/geopackage.html">GeoPackage</a>, <a href="/docs/formats/flatgeobuf.html">FlatGeobuf</a> or <a href="/docs/formats/geojson.html">GeoJSON</a>.</p>
37
+ <p><strong>File extension:</strong> <code>.msx</code> &middot; <strong>Read:</strong> &check; &middot; <strong>Write:</strong> &check; &middot; <strong>Multi-layer:</strong> &check;</p>
38
+ <h3 id="when-to-use-a-snapshot">When to use a snapshot</h3>
39
+ <ul>
40
+ <li><strong>Saving work-in-progress</strong> for later editing, with topology, layer order and (in the web app) command history intact.</li>
41
+ <li><strong>Bundling a collection of datasets</strong> into a single compact file that is quicker to re-open than re-running an import pipeline.</li>
42
+ <li><strong>In the browser, as a quick &quot;save point&quot;</strong> before doing something experimental that might fail or give the wrong result &mdash; restore the snapshot to roll back.</li>
43
+ </ul>
44
+ <h3 id="from-the-cli">From the CLI</h3>
45
+ <p><code>-o foo.msx</code> captures the <strong>entire session</strong> &mdash; every dataset and every layer Mapshaper has loaded, not just the ones currently selected by <code>-target</code>. This makes a <code>.msx</code> file a faithful &quot;save point&quot; of the working state, regardless of which layers happen to be active.</p>
46
+ <p><code>-target</code> controls <em>visibility and stacking order</em>, not which layers are written:</p>
47
+ <ul>
48
+ <li>Layers matched by the active <code>-target</code> (or the <code>target=</code> option on <code>-o</code> itself) come back <strong>visible</strong> in the web app, with no further setup.</li>
49
+ <li>They are stacked in the order matched by <code>-target</code> &mdash; first targeted on the bottom, last on top &mdash; so the GUI&#39;s layer stack matches the draw order you&#39;d get from an SVG export of the same target list.</li>
50
+ <li>Layers that weren&#39;t targeted come along <strong>hidden</strong>, parked at the bottom of the layer panel. They&#39;re still in the file (so you can pin them visible later), but they don&#39;t get in the way of the intended view.</li>
51
+ <li>If you want to drop layers from the snapshot rather than just hide them, run an explicit step like <code>-filter-layers</code> or <code>-target b -drop</code> before <code>-o foo.msx</code>.</li>
52
+ </ul>
53
+ <h3 id="in-the-web-app">In the web app</h3>
54
+ <p>The ribbon icon in the layer panel opens the <strong>snapshot menu</strong>. From there you can:</p>
55
+ <ul>
56
+ <li><strong>Create a snapshot</strong> &mdash; saves to in-browser storage. These are session-scoped and <strong>deleted when the tab closes or the page is reloaded.</strong> For anything you want to keep, <strong>Save snapshot to file</strong> writes a <code>.msx</code> file you can re-open later.</li>
57
+ <li><strong>Export</strong> a stored snapshot to a <code>.msx</code> file on disk. Persisted <code>.msx</code> files survive browser restarts and can be re-imported by drag-drop, the <strong>Add files</strong> button, or the <code>?files=</code> URL parameter.</li>
58
+ <li><strong>Restore</strong> a stored snapshot into the current session.</li>
59
+ </ul>
60
+ <h2 id="external-resources">External resources</h2>
61
+ <ul>
62
+ <li><a href="https://msgpack.org/">msgpack.org</a> &mdash; the binary serialization format used inside <code>.msx</code> (via the <a href="https://github.com/kriszyp/msgpackr">msgpackr</a> library).</li>
63
+ </ul>
64
+
65
+ <div class="edit-link">
66
+ <a href="https://github.com/mbloch/mapshaper/edit/master/docs/formats/snapshot.md">Edit this page on GitHub</a>
67
+ </div>
68
+ </article>
69
+ </main>
70
+
71
+ <aside class="docs-toc">
72
+ <div class="docs-toc-title">On this page</div><ul><li class="lvl-3"><a href="#when-to-use-a-snapshot">When to use a snapshot</a></li><li class="lvl-3"><a href="#from-the-cli">From the CLI</a></li><li class="lvl-3"><a href="#in-the-web-app">In the web app</a></li><li class="lvl-2"><a href="#external-resources">External resources</a></li></ul>
73
+ </aside>
74
+
75
+ </div>
76
+
77
+ <script src="/docs/_assets/docs.js" defer></script>
78
+
79
+ <footer class="docs-footer">
80
+ <div class="docs-footer-inner">
81
+ <span>mapshaper is free software, licensed under <a href="https://www.mozilla.org/MPL/2.0/">MPL 2.0</a>.</span>
82
+ <span><a href="/privacy.html">Privacy</a> &middot; <a href="/terms.html">Terms</a> &middot; <a href="/sponsor.html">Support mapshaper</a></span>
83
+ </div>
84
+ </footer>
85
+
86
+ </body>
87
+ </html>