# mapbox-map-image-export

> Export a Mapbox GL map to a hi-res image for printing

Latest version **2.4.1** (published 2019-01-02) · MIT license · 0 weekly downloads

## Install

```sh
npm install mapbox-map-image-export
pnpm add mapbox-map-image-export
yarn add mapbox-map-image-export
bun add mapbox-map-image-export
```

Provides the command `export-map`.

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 2.4.1 |
| Published | 2019-01-02 |
| First published | 2016-07-15 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 19 |
| Unpacked size | 410.3 KB |
| Known vulnerabilities | 0 (+61 in 2 direct dependencies) |
| Install scripts | no |
| GitHub stars | 87 |
| Author | Gregor MacLennan |
| Maintainers | digidem-admin, gmaclennan, karissa, noffle, substack |
| Keywords | mapbox, mapbox-gl, print, image, export, map |

## Links

- npm: https://www.npmjs.com/package/mapbox-map-image-export
- Repository: https://github.com/digidem/mapbox-map-image-export
- Homepage: https://github.com/digidem/mapbox-map-image-export#readme
- Issues: https://github.com/digidem/mapbox-map-image-export/issues
- npm.io page: https://npm.io/package/mapbox-map-image-export

## Dependencies (19)

- [once](https://npm.io/package/once.md) ^1.4.0
- [pump](https://npm.io/package/pump.md) ^3.0.0
- [from2](https://npm.io/package/from2.md) ^2.3.0
- [gl-fbo](https://npm.io/package/gl-fbo.md) ^2.0.5
- [pumpify](https://npm.io/package/pumpify.md) ^1.5.1
- [electron](https://npm.io/package/electron.md) ^3.0.7
- [minimist](https://npm.io/package/minimist.md) ^1.2.0
- [through2](https://npm.io/package/through2.md) ^2.0.1
- [mapbox-gl](https://npm.io/package/mapbox-gl.md) ^0.49.0
- [decimal.js](https://npm.io/package/decimal.js.md) ^10.0.1
- [png-stream](https://npm.io/package/png-stream.md) ^1.0.4
- [multistream](https://npm.io/package/multistream.md) ^2.1.1
- [through2-spy](https://npm.io/package/through2-spy.md) ^2.0.0
- [yargs-parser](https://npm.io/package/yargs-parser.md) ^11.0.0
- [js-quantities](https://npm.io/package/js-quantities.md) ^1.7.2
- [gl-pixel-stream](https://npm.io/package/gl-pixel-stream.md) ^1.2.0
- [single-line-log](https://npm.io/package/single-line-log.md) ^1.1.2
- [@turf/bbox-polygon](https://npm.io/package/@turf/bbox-polygon.md) ^6.0.1
- [mosaic-image-stream](https://npm.io/package/mosaic-image-stream.md) ^1.0.1

## Alternatives

- [exif-parser](https://npm.io/package/exif-parser.md) — 3.8M weekly downloads
- [vite-plugin-compression](https://npm.io/package/vite-plugin-compression.md) — 569.5K weekly downloads
- [pica](https://npm.io/package/pica.md) — 442.4K weekly downloads
- [@reportportal/client-javascript](https://npm.io/package/@reportportal/client-javascript.md) — 408.8K weekly downloads
- [@tldraw/state](https://npm.io/package/@tldraw/state.md) — 316.0K weekly downloads

## Recent versions

- 2.4.1 (latest) — 2019-01-02
- 2.4.1-beta.2 (next) — 2018-11-03
- 2.4.0 — 2018-04-08
- 2.3.0 — 2018-04-08
- 2.2.1 — 2017-07-22
- 2.2.0 — 2017-07-07
- 2.1.0 — 2017-02-16
- 2.0.1 — 2017-01-28
- 2.0.0 — 2017-01-28
- 1.0.0 — 2016-07-15

## README

# mapbox-map-image-export

A command-line tool to export a [Mapbox vector map][1], such as one created with [Mapbox Studio][2], to a high-resolution image for printing etc.

Mapbox has a [Maps static API][3] for exporting images, but it is limited to `1280px`, and exports as jpeg, with visible compression artifacts. `mapbox-map-image-export` renders the map in a headless browser and exports by default to uncompressed png. You can adjust the dpi setting for high-quality printing. `192dpi` (the default) is good enough for most print applications, but if you want better quality try `288dpi`. Icons will be 192dpi (retina) due to the way sprites are handled by `mapbox-gl-js`.

The Mapbox [wmts service][4] is another option for creating maps for printing in QGIS or ArcMap, but it does not currently support retina maps, so is limited to printing at around 72dpi, and is also only jpeg right now.

[1]: https://www.mapbox.com/maps/
[2]: https://www.mapbox.com/mapbox-studio/
[3]: https://www.mapbox.com/api-documentation/#static
[4]: https://www.mapbox.com/help/mapbox-arcgis-qgis/

```sh
export MAPBOX_TOKEN=YOUR_MAPBOX_API_PUBLIC_TOKEN

export-map mapbox://styles/mapbox/streets-v9 -w=11in -h=8.5in \
  -b=-7.1354,57.9095,-6.1357,58.516 -t=$MAPBOX_TOKEN -o=lewis.png
```

![lewis](lewis.png)

## Install

This tool uses Electron to render the map using [mapbox-gl-js][3], so it is fairly heavy (~100mb). Install with latest [npm](https://www.npmjs.com/).

[5]: https://www.mapbox.com/mapbox-gl-js/api/

```sh
npm install mapbox-map-image-export -g
```

## Usage

```txt
Usage:
  export-map mapboxStyleUrl

Options:
  --bounds, -b      comma-separated bounding box [required] 'minLon,minLat                        maxLon,maxLat' eg. '-7.1354,57.9095,-6.1357,58.516'
  --token, -t       Mapbox API token [required]:
                    https://www.mapbox.com/studio/account/tokens/
  --output, -o      image output path, optional, defaults to std.out
  --dpi, -d         dpi of output image, default 192dpi (equivalent to how the                    map renders on a retina screen)
  --format, -f      output format, "jpg", "webp" or "png" (default)
  --quality, -q     encoding quality for jpg and webp, default 0.9
  --width, -w       output width for printing e.g. 11in or 297mm
  --height, -h      output height for printing
  --help            show this help
  --version, -v     show version
  --debug           renders bounding box and (print) tile boundaries and opens                    the developer tools console
```

Exports a map for a given mapbox style url for the specified bounding box.

If no `--output` is given, the PNG is written to stdout.

## What does 'dpi' mean?

Mapbox Studio and Mapbox GL maps are designed for the screen, as such 'dpi' (dots per inch), a print term, does not have any real meaning. However, the standard screen resolution is equivalent to between 72 and 96dpi (e.g. 96 screen pixels will measure approximately 1 inch on a standard screen). Mapbox GL maps are designed by zoom level, and this tool assumes you want maps to look on paper roughly the same as they look on screen at the same size. `mapbox-map-image-export` assumes a standard resolution mapbox map is 96dpi, and a retina (@2x) map is 192dpi. You can set 288dpi if you like, and this will render as if to an ultra-retina screen with a devicePixelRatio=3. Keep dpi to a multiple of `96` if you want icons to look good.

## Acknowledgements

This is inspired by [extract-streetview](https://github.com/Jam3/extract-streetview) by [mattdesl](https://github.com/mattdesl). It uses [Electron](https://electron.atom.io/) to render the map in a headless version of Chrome.

## License

MIT

---
_Source: https://npm.io/package/mapbox-map-image-export · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._
