File formats

This section explains how each supported file format is handled, what format-specific options are available, and what to watch out for.

Comparison

A few things worth knowing across all formats:

• Auto-detection by extension. You usually don't need to tell Mapshaper what format a file is — the input and output format are both inferred from the file extension. Use format= on -i or -o to override.
• TopoJSON is the only interchange format that preserves topology in the file itself. Topology-aware operations like -dissolve, -clean and -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 snapshots also preserve topology, but they're not readable by other tools.)
• Encoding. The encoding= option on -i and -o applies to Shapefile, DBF and CSV/TSV i/o (UTF-8 is the default) — the other formats are UTF-8-only.
• Raster and vector layers export separately. GeoTIFF is the only output format that takes a raster layer's pixels, and it takes nothing else, so -o needs a target= when a session holds both kinds of layer. SVG and .msx snapshots are the two formats that accept a mix. A GeoTIFF written by Mapshaper keeps the pixel values as they are, in the type they were read in, so an elevation model comes out as elevations rather than as an image; the pixels are Deflate-compressed unless you ask for compression=none. The layer's projection is written into the file, either as an EPSG code or spelled out parameter by parameter. A handful of projections — Mapshaper's interrupted and composite ones among them — have no GeoTIFF representation at all; for those, Mapshaper writes the projection to a small .aux.xml file next to the .tif, so keep the two together, since that's where GIS software — and Mapshaper itself, when the .tif is loaded again — will look for it. Reading a raster, Mapshaper fills in what the file leaves out in the same way it does for vector data: a projection given without a datum is assumed to be on WGS 84, and a file with no projection metadata at all is assumed to be in WGS 84 lat-long if its coordinates fall in the decimal-degree range. A raster whose coordinates are outside that range and that says nothing about its CRS still loads and displays, but can't be projected or shown over a basemap until you say what it's in, with -proj init=<crs> crs=<crs>.