mapshaper 0.7.0 → 0.7.2

package/www/docs/guides/topology.html.md

@@ -0,0 +1,63 @@
+---
+title: Topology and cleaning
+description: How Mapshaper detects shared boundaries between features, and how to fix the common topology errors that creep into Shapefile and GeoJSON datasets.
+---
+
+# Topology and cleaning
+
+Shapefile and GeoJSON are non-topological formats — they don't record the spatial relationships between adjacent polygons or intersecting polylines. Each polygon is just a list of coordinates; whether two polygons share an edge has to be detected.
+
+Mapshaper detects topology on import by identifying coordinates that are exactly shared between features. This is what makes operations like simplification, dissolving and clipping work correctly: when two polygons share an edge, the shared path (or "arc") is stored once and edited once.
+
+But coordinates that "should be" identical often aren't. Source datasets routinely contain misalignments (tiny gaps or overlaps between adjacent polygons) that defeat exact-match topology detection. The result is that what looks like a clean boundary turns into duplicated, slightly-offset arcs — and simplification, dissolving and clipping all start to misbehave.
+
+## Snapping
+
+The simplest fix is to ask Mapshaper to snap nearby vertices together at import time.
+
+In the **command line**, pass the `snap` flag to `-i`:
+
+```bash
+mapshaper countries.shp snap -dissolve CONTINENT -o continents.shp
+```
+
+In the **web app**, tick "snap vertices" in the import dialog (open the import options with the **with advanced options** checkbox).
+
+By default, snapping uses an automatic threshold of about 0.0025× the average segment length, which is designed to catch misalignments caused by floating-point rounding. To set an explicit snapping distance, use `snap-interval=`:
+
+```bash
+mapshaper countries.shp snap-interval=0.0001 -o cleaned.shp
+```
+
+## Cleaning
+
+Snapping handles slightly offset pairs of vertices, but doesn't help much when adjacent polygons have small overlapping regions or gaps along their shared boundaries. The [`-clean`](/docs/reference.html.md#-clean) command repairs these by recomputing the polygon mosaic and snapping geometry that's nearly identical:
+
+```bash
+mapshaper countries.shp -clean -o cleaned.shp
+```
+
+`-clean` accepts a `gap-fill-area=` option to control how aggressively gaps are filled, and a `sliver-control=` setting for handling sliver polygons. [`-dissolve`](/docs/reference.html.md#-dissolve) runs an equivalent repair by default, so explicitly running `-clean` is mainly useful when you want clean output without dissolving anything.
+
+In the web app, `-clean` runs from the **Console** the same way as on the CLI — the leading `-` is optional, e.g. just `clean gap-fill-area=100`.
+
+## Dissolving with topology repair
+
+[`-dissolve`](/docs/reference.html.md#-dissolve) repairs topology automatically. To skip the repair pass (faster, but only safe when you trust the input topology), pass `no-repair` — Mapshaper will then warn if it detects segment intersections in the input.
+
+```bash
+mapshaper counties.shp -dissolve STATE_FIPS -o states.shp
+```
+
+## Detecting line intersections
+
+The web app can highlight self-intersections in your data: open the **Display** panel and tick "detect line intersections". Intersections often indicate either a topology error in the source data or self-intersections introduced by simplification — the **Repair** button at the top-left of the map attempts to fix the latter.
+
+On the command line, [`-clean`](/docs/reference.html.md#-clean) and [`-dissolve`](/docs/reference.html.md#-dissolve) both detect and fix intersections.
+
+## Notes on common sources of topology errors
+
+A few patterns to watch out for:
+
+- **`.shp` files exported from older GIS tools.** Some pipelines round coordinates inconsistently between adjacent features, producing systematic misalignments. Importing with `snap` is usually enough.
+- **Older versions of ArcGIS's dissolve tool** have been observed to produce topology errors when dissolving a Shapefile that hasn't first been added to a Geodatabase. If you're starting from such output, run it through `mapshaper input.shp -clean -o cleaned.shp` to repair before further processing.

package/www/docs/index.html

@@ -0,0 +1,101 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Mapshaper documentation &middot; mapshaper docs</title>
+<meta name="description" content="Documentation for mapshaper, the command-line tool and web app for editing Shapefile, GeoJSON, TopoJSON, GeoPackage, FlatGeobuf, KML and CSV data.">
+<link rel="icon" type="image/png" href="/images/icon.png">
+<link rel="stylesheet" href="/docs/_assets/highlight.css">
+<link rel="stylesheet" href="/docs/_assets/docs.css">
+</head>
+<body class="is-home">
+
+<header class="page-header">
+  <a href="/" class="mapshaper-logo">map<span class="logo-highlight">shaper</span></a>
+  <span class="header-section-label">Docs</span>
+  <nav class="header-nav">
+    <a href="/">Web app</a>
+    <a href="https://github.com/mbloch/mapshaper">GitHub</a>
+    <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>
+  </nav>
+</header>
+
+<div class="docs-layout">
+
+  <aside class="docs-sidebar">
+    <div class="sidebar-inner">
+      <nav class="docs-nav"><ul class="top-links"><li><a href="/docs/" class="is-active">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">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>
+    </div>
+  </aside>
+
+  <main class="docs-main">
+    <article class="docs-article">
+      
+      <h1 id="mapshaper-documentation">Mapshaper documentation</h1>
+<p class="lead">Mapshaper is a tool for editing Shapefile, GeoJSON, TopoJSON, GeoPackage, FlatGeobuf, KML and CSV data &mdash; available as a command-line program and as a web app at <a href="/">mapshaper.org</a>.</p><div class="section-cards">
+  <a class="section-card" href="/docs/essentials/command-line.html">
+    <p class="card-title">Getting started</p>
+    <p class="card-desc">Introductions to the CLI and the web app.</p>
+  </a>
+  <a class="section-card" href="/docs/guides/simplification.html">
+    <p class="card-title">Guides</p>
+    <p class="card-desc">Task-oriented walk-throughs: simplification, topology, joining layers, scripting from Node.</p>
+  </a>
+  <a class="section-card" href="/docs/formats/overview.html">
+    <p class="card-title">File formats</p>
+    <p class="card-desc">Read/write details for Shapefile, GeoJSON, TopoJSON, GeoPackage, FlatGeobuf, KML, CSV and more.</p>
+  </a>
+  <a class="section-card" href="/docs/examples/basics.html">
+    <p class="card-title">Examples</p>
+    <p class="card-desc">Short recipes for common GIS tasks, plus a Gallery of full map examples with source data.</p>
+  </a>
+</div><h2 id="featured-examples">Featured examples</h2>
+<div class="featured-maps">
+  <a class="gallery-tile" href="/docs/examples/globe.html">
+    <div class="gallery-tile-image">
+      <img src="/docs/examples/data/globe.svg" alt="Globe locator map">
+    </div>
+    <div class="gallery-tile-caption">
+      <div class="gallery-tile-title">Globe locator map</div>
+    </div>
+  </a>
+  <a class="gallery-tile" href="/docs/examples/us-states.html">
+    <div class="gallery-tile-image">
+      <img src="/docs/examples/data/us-states.svg" alt="U.S. state map">
+    </div>
+    <div class="gallery-tile-caption">
+      <div class="gallery-tile-title">U.S. state map</div>
+    </div>
+  </a>
+</div><p class="featured-maps-link"><a href="/docs/gallery/">See the full gallery &rarr;</a></p><h2 id="whats-new">What&#39;s new</h2>
+<p>A curated log of recently added features is at <a href="/docs/whats-new.html">What&#39;s new</a>. The full <a href="https://github.com/mbloch/mapshaper/blob/master/CHANGELOG.md">changelog</a> is on GitHub.</p>
+<h2 id="help-and-feedback">Help and feedback</h2>
+<ul>
+<li>Found a bug or want to request a feature? <a href="https://tally.so/r/44Njok">Share feedback</a> or <a href="https://github.com/mbloch/mapshaper/issues">open an issue on GitHub</a>.</li>
+<li>Mapshaper is free software. If it&#39;s useful to you, please consider <a href="/sponsor.html">supporting its development</a>.</li>
+</ul>
+
+      <div class="edit-link">
+        <a href="https://github.com/mbloch/mapshaper/edit/master/docs/index.md">Edit this page on GitHub</a>
+      </div>
+    </article>
+  </main>
+
+  <aside class="docs-toc">
+    <div class="docs-toc-title">On this page</div><ul><li class="lvl-2"><a href="#featured-examples">Featured examples</a></li><li class="lvl-2"><a href="#whats-new">What&#39;s new</a></li><li class="lvl-2"><a href="#help-and-feedback">Help and feedback</a></li></ul>
+  </aside>
+
+</div>
+
+<script src="/docs/_assets/docs.js" defer></script>
+
+<footer class="docs-footer">
+  <div class="docs-footer-inner">
+    <span>mapshaper is free software, licensed under <a href="https://www.mozilla.org/MPL/2.0/">MPL 2.0</a>.</span>
+    <span><a href="/privacy.html">Privacy</a> &middot; <a href="/terms.html">Terms</a> &middot; <a href="/sponsor.html">Support mapshaper</a></span>
+  </div>
+</footer>
+
+</body>
+</html>

package/www/docs/index.html.md

@@ -0,0 +1,59 @@
+---
+title: Mapshaper documentation
+description: Documentation for mapshaper, the command-line tool and web app for editing Shapefile, GeoJSON, TopoJSON, GeoPackage, FlatGeobuf, KML and CSV data.
+---
+
+# Mapshaper documentation
+
+<p class="lead">Mapshaper is a tool for editing Shapefile, GeoJSON, TopoJSON, GeoPackage, FlatGeobuf, KML and CSV data &mdash; available as a command-line program and as a web app at <a href="/">mapshaper.org</a>.</p>
+
+<div class="section-cards">
+  <a class="section-card" href="/docs/essentials/command-line.html">
+    <p class="card-title">Getting started</p>
+    <p class="card-desc">Introductions to the CLI and the web app.</p>
+  </a>
+  <a class="section-card" href="/docs/guides/simplification.html">
+    <p class="card-title">Guides</p>
+    <p class="card-desc">Task-oriented walk-throughs: simplification, topology, joining layers, scripting from Node.</p>
+  </a>
+  <a class="section-card" href="/docs/formats/overview.html">
+    <p class="card-title">File formats</p>
+    <p class="card-desc">Read/write details for Shapefile, GeoJSON, TopoJSON, GeoPackage, FlatGeobuf, KML, CSV and more.</p>
+  </a>
+  <a class="section-card" href="/docs/examples/basics.html">
+    <p class="card-title">Examples</p>
+    <p class="card-desc">Short recipes for common GIS tasks, plus a Gallery of full map examples with source data.</p>
+  </a>
+</div>
+
+## Featured examples
+
+<div class="featured-maps">
+  <a class="gallery-tile" href="/docs/examples/globe.html">
+    <div class="gallery-tile-image">
+      <img src="/docs/examples/data/globe.svg" alt="Globe locator map">
+    </div>
+    <div class="gallery-tile-caption">
+      <div class="gallery-tile-title">Globe locator map</div>
+    </div>
+  </a>
+  <a class="gallery-tile" href="/docs/examples/us-states.html">
+    <div class="gallery-tile-image">
+      <img src="/docs/examples/data/us-states.svg" alt="U.S. state map">
+    </div>
+    <div class="gallery-tile-caption">
+      <div class="gallery-tile-title">U.S. state map</div>
+    </div>
+  </a>
+</div>
+
+<p class="featured-maps-link"><a href="/docs/gallery/">See the full gallery &rarr;</a></p>
+
+## What's new
+
+A curated log of recently added features is at [What's new](/docs/whats-new.html.md). The full [changelog](https://github.com/mbloch/mapshaper/blob/master/CHANGELOG.md) is on GitHub.
+
+## Help and feedback
+
+- Found a bug or want to request a feature? [Share feedback](https://tally.so/r/44Njok) or [open an issue on GitHub](https://github.com/mbloch/mapshaper/issues).
+- Mapshaper is free software. If it's useful to you, please consider [supporting its development](/sponsor.html).