Mapshaper Documentation

Supported Features

• Single-band (grayscale) and multi-band (RGB/RGBA) rasters.
• Stripped and tiled storage.
• Common integer and float sample types.
• BigTIFF support (via geotiff.js).

Limitations

• No Reprojection on Import: Reprojection is handled later via the -proj command or during display preview generation.
• Unsupported Formats: OME-TIFF, CMYK, CIELab, YCbCr, and certain compressions like ZSTD or LERC are currently limited or unsupported.
• Sidecars: .aux.xml (GDAL PAM) files are currently ignored; essential metadata should be contained within the GeoTIFF itself.

Since browsers cannot access the local filesystem like the CLI, you must provide all Shapefile components together using one of two methods:

1. Select all components: Use Add files to select the .shp, .dbf, .prj, and .shx/.cpg files simultaneously (using Shift+Click or Cmd+Click), or drag the entire selection into the import area.
2. Drop a .zip file: Drag and drop a .zip archive containing the complete Shapefile bundle.

Handling encoding errors in the web app: If you see an encoding warning, re-import the files, tick the with advanced options checkbox, and specify the encoding (e.g., encoding=win1252).

When working with GeoJSON in Mapshaper, keep these technical details in mind:

• Precision: Coordinates are emitted at full precision by default. Use precision= to reduce file size. Note that precision=0.0001 equates to roughly 6-11 meters depending on location. High rounding can introduce sliver overlaps; consider pairing precision= with fix-geometry.
• Winding Order: Mapshaper follows RFC 7946 by default (Counter-Clockwise outer rings, Clockwise holes). Use reverse-winding if you need Clockwise outer rings.
• Coordinate Systems: While GeoJSON typically uses WGS-84, Mapshaper can also export GeoJSON with projected coordinates.
• File Size: For datasets with shared boundaries, consider using TopoJSON instead of GeoJSON to significantly reduce file size.

Styling commands are most effective when exporting to SVG. You can run these commands in the web app's Console or via the CLI.

CLI Example:

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

To ensure shared boundaries (like state and county borders) are simplified identically, you must build a shared topology.

Method 1: Combine files directly Use -i combine-files to import multiple layers. This works if vertices are perfectly aligned.

Method 2: Dissolve (Recommended) Because source layers are rarely perfectly aligned, the most reliable approach is to import the smallest geographic level (e.g., counties) and derive higher levels (e.g., states) using the -dissolve command before simplifying.

Web UI Note: To achieve shared topology in the web app, tick with advanced options in the import dialog and add combine-files to the options field.

Modify feature attributes using the following commands:

• Add/Update fields: Use -each to run a JavaScript expression on every feature. Assigning to a new name creates a new field (e.g., -each 'NEW_FIELD = OLD_FIELD * 2').
• Rename fields: Use -rename-fields with NEW=OLD pairs.
• Filter/Reorder fields: Use -filter-fields to keep only specific columns in a specific order.

Note on CSV leading zeros: To prevent Mapshaper from parsing identifier columns (like FIPS or ZIP) as numbers and dropping leading zeros, use string-fields=FIELD_NAME during import.

-each 'STATE_FIPS = COUNTY_FIPS.substr(0, 2), AREA_KM2 = round(this.area / 1e6, 1)'
-rename-fields POPULATION=POP,MEDIAN_INCOME=MEDIAN_INC \
  -filter-fields STATE,COUNTY,POPULATION,MEDIAN_INCOME
# CLI Import example for leading zeros:
mapshaper -i counties.csv string-fields=FIPS,STATEFIPS

When implementing a new command, ensure you complete the following steps:

1. Identify Mutations: List every object the command mutates in place.
2. Capture State: Capture each object before its first mutation and mark it after mutation.
3. Optimize Granularity: Prefer narrow units like record, field, schema, order, metadata, simplification, or info over broad table or layer units.
4. Verify Transactions: Add or update transaction tests for the new granularity.
5. Browser Testing: Add a browser command case for console-visible editing commands. Include payloadTypes or noPayloadTypes assertions if granularity is critical.
6. Run Tests: Execute focused unit tests and npm run test:browser -- browser-tests/undo-console.spec.mjs, then run npm test before committing.

Mapshaper supports importing georeferenced raster files via an asynchronous import path:

• GeoTIFF: Supports .tif and .tiff files. Large files automatically use an overview or resized rendition unless rendition=full is specified.
• PNG/JPEG: Supports .png, .jpg, and .jpeg.
• Georeferencing:
  • For PNG/JPEG, Mapshaper recognizes world-file sidecars (e.g., .pgw, .jgw, .tfw, .wld).
  • For PNG/JPEG, it can read .prj sidecars to populate the dataset's WKT1 projection.
• CRS: Raster CRS metadata is stored at the dataset level in dataset.info (using crs, crs_string, and wkt1). Per-layer placement metadata (pixel-to-map transform) is stored on the raster layer itself.

You can run the Mapshaper web interface on your own machine using the mapshaper-gui command (installed with the global mapshaper package).

# Start the server at http://localhost:5555
mapshaper-gui

# Start the server on a specific port
mapshaper-gui --port 8080

# Start the server and pre-load specific files
mapshaper-gui states.shp rivers.shp