Mapshaper 示例图库(Gallery)完全指南:示例地图、完整配方与可复现的制图流水线

原创2026-10-12 13:59:58915 阅读
文章标签:GISCLI数据可视化

Mapshaper 示例图库(Gallery)完全指南:示例地图、完整配方与可复现的制图流水线

Mapshaper 官方文档站点的 Gallery(示例图库)是一组由 Mapshaper 制作的示例地图合集,每一张地图都附带完整的配方(recipe)、源数据下载,以及一键在 Web 应用中打开成图的链接。本文以 docs/gallery/index.md 为核心,结合图库背后的三个完整示例(Globe 定位地图、美国州地图、纽约州地图)、仓库中的配方文件与文档构建脚本(build-docs.mjs),讲解图库的组织方式、每条配方的逐行含义、可复现的运行方法,以及如何把一条新配方挂进图库。读完本文,你将能够读懂并复现 Mapshaper 的整条"源数据 → 命令行流水线 → SVG/快照资产 → 图库页面"链路,并掌握 -proj、-classify、-frame、-clip、-divide、-innerlines、-points、-style 等命令在真实地图项目中的组合用法。

图库是什么:示例地图 + 可复现配方

Gallery 页面位于 docs/gallery/index.md,其 frontmatter 定义如下:

---
title: Gallery
description: Example maps made with Mapshaper, with full source data and reproduction steps for each.
---

正文只有一句话点明组织方式:

A collection of example maps made with Mapshaper. Each tile links to its own page with the recipe, the source data, and a link to open the finished map in the web app.

也就是说,Gallery 页面本身是一张"图库索引",真正的内容是每个示例地图自己的子页面。每块图库磁贴(tile)链接到对应示例页,而每个示例页包含三样东西:

  1. 配方(recipe):一条可直接运行的 Mapshaper 命令行流水线;
  2. 源数据(source data):打包好的原始输入文件,供读者端到端复现;
  3. 打开成图的链接:通过快照文件在 Web 应用 中直接打开最终成品。

图库页面是构建时生成的

index.md 正文中只有一行占位符 <!-- mapshaper:gallery -->,它由文档构建脚本 build-docs.mjs 在渲染时替换为实际的磁贴网格。相关机制集中在两个函数:

  • getExampleTiles()(build-docs.mjs):遍历 _nav.json 中 Examples 分区的所有页面,收集在 frontmatter 中声明了 image: 字段的页面,作为图库磁贴的数据源;标题优先取页面的 H1(如 "Globe locator map"),否则退回 title: 或导航标签;
  • renderExampleTiles()(build-docs.mjs):以 gallery 变体渲染完整的磁贴网格(含图片、标题、描述),以 featured 变体渲染首页的紧凑横条(只含图片和标题)。

首页 docs/index.md 中使用的 <!-- mapshaper:featured count=2 --> 占位符,就是取 Examples 分区前两个带图片的示例(即 Globe 与 U.S. States),渲染成首页的"Featured examples"横条,并附"See the full gallery →"链接。这意味着:只要在 Examples 分区新增一个带 image: 前台的示例页,图库就会自动多一块磁贴,无需手工维护索引。

磁贴中引用的图片、快照与下载文件由 copyReferencedDataFiles()(build-docs.mjs)在构建时从各示例页同级的 data/ 目录复制到输出目录,只有被 frontmatter 显式引用的文件才会被复制,recipe: 文件则例外——它的内容在构建时内联进页面,不作为独立 URL 提供。

图库收录的三个示例

依据 docs/_nav.json 中 Examples 分区的配置,当前图库收录了三个带 image: 的完整示例:

示例页 难度 主题 数据来源
docs/examples/globe.md moderate 地球形状的定位地图 Natural Earth 国家多边形
docs/examples/us-states.md easy 美国州地图(随机非相邻配色) Natural Earth 州/省多边形
docs/examples/ny-state.md moderate 纽约州及周边州地图(带标注) Natural Earth 州/省 + 道路

三者各自声明了 recipe:、image:、snapshot:、download: 四个资产字段,例如 Globe 页的 frontmatter:

recipe: globe.txt
image: globe.svg
snapshot: globe.msx
download: globe.zip

其中 .txt 是配方文件,.svg 是成品预览图,.msx 是 Mapshaper 会话快照,.zip 打包了原始输入数据。这些文件位于 docs/examples/data/。

示例一:Globe 定位地图(Globe locator map)

页面:docs/examples/globe.md,配方文件:docs/examples/data/globe.txt。

完整配方

mapshaper \
-i ne_50m_admin_0_countries.geojson name=countries \
-proj +proj=nsper +h=1e7 +lat_0=35 +lon_0=2.35 \
-simplify resolution=400 \
-lines + name=lines \
-graticule polygon name=background \
-filter true + name=shadow \
-graticule target=countries name=graticule interval=20 \
-i "lat,lon,label\n48.86,2.35,Paris" name=dot \
-points \
-proj match=countries \
-filter true + name=label \
-style target=background fill='#f7f7f7' \
-style target=shadow fill-effect=sphere fill='#ccc' \
-style target=graticule stroke='#ccc' \
-style target=countries fill='#e4e4e4' \
-style target=lines stroke='TYPE == "inner" ? "#bbb" : "#c2c2c2"' \
-style target=dot fill='#dd0000' r=4 \
-style target=label label-text=label text-anchor=start dy=5 dx=10 font-size=16 \
-target background,countries,lines,graticule,dot,label,shadow \
-o globe.svg height=400 width=600

逐步解读

  1. 加载国家多边形:-i ne_50m_admin_0_countries.geojson name=countries,数据源为 Natural Earth 50m 国家边界;
  2. 投影:-proj +proj=nsper +h=1e7 +lat_0=35 +lon_0=2.35,使用近侧透视投影(near-side perspective,即"从太空看地球"),视点高度 1 万公里、中心位于北纬 35°、东经 2.35°。文档特别说明:这个投影比常用的正射投影 +proj=ortho 看起来更"放大";
  3. 简化国界:-simplify resolution=400。resolution= 是 mapshaper-options.mjs 中 -simplify 的三种目标形式之一(另两种是 interval= 与 percentage=),表示保留的顶点间距约 400 单位,适合直接控制输出精度而非按比例压缩;
  4. 派生线图层:-lines + name=lines,从国家多边形提取边界线,+ 保留原图层并新建 lines 图层。这里的 TYPE == "inner" 属性用于区分内部边界(邻国之间)与外部边界(海岸线),以便分别着色;
  5. 背景形状:-graticule polygon name=background,生成一个与经纬网外边界一致的多边形,用来承载背景色。-graticule target=countries name=graticule interval=20 则以 countries 为范围生成 20° 间隔的经纬网线;
  6. 复制图层惯用法:-filter true + name=shadow——-filter true 的表达式恒为真、保留全部要素,+ 生成副本,这是 Mapshaper 复制图层的标准惯用法(文档原文:"the Mapshaper idiom for copying a layer");
  7. 加入地点点:-i "lat,lon,label\n48.86,2.35,Paris" name=dot 以内联 CSV 字符串创建巴黎点,-points 将其转为点图层,-proj match=countries 让点复用国家的投影参数;
  8. 样式:连续多条 -style 为各图层设置填充、描边、半径与标签。注意 label-text=label、text-anchor=start、dx/dy 偏移和 font-size 都属于 SVG 文本标注样式;
  9. 输出:-target background,countries,lines,graticule,dot,label,shadow 确定绘制顺序与可见层(第一个在底层),-o globe.svg height=400 width=600 导出为 400×600 的 SVG。

从源码看,nsper(近侧透视)投影被 Mapshaper 归类为需要特殊裁剪角处理的透视类投影之一(mapshaper-proj-extents.mjs),这类投影在球面裁剪与范围计算上有专门逻辑,这也是配方中"投影后立即简化"顺序的合理性所在——先投影到平面,再在平面坐标系上做简化。

示例二:美国州地图(U.S. state map)

页面:docs/examples/us-states.md,配方文件:docs/examples/data/us-states.txt。

完整配方

mapshaper \
-i ne_50m_admin_1_states_provinces_lakes.geojson name=states \
-filter 'admin == "United States of America"' \
-proj albersusa \
-classify non-adjacent colors=Tableau10 \
-innerlines + name=innerlines \
-style stroke=white stroke-width=0.5 \
-target states,innerlines \
-o us-states.svg height=400 width=600

逐步解读

  1. 加载州/省多边形:-i ... name=states,Natural Earth 的 admin_1 数据(含各州、各省与湖泊);
  2. 只保留美国本土各州:-filter 'admin == "United States of America"'。admin 是 Natural Earth admin_1 数据中表示"所属国家"的字段;
  3. 投影:-proj albersusa。albersusa 是 Mapshaper 内置的自定义复合投影,由《纽约时报》为美国地图设计(文档原文:"a custom projection used by The New York Times for U.S. maps")。其实现位于 mapshaper-custom-projections.mjs:主体为 +proj=aea 双标准纬线等积投影,并对阿拉斯加(AK)、夏威夷(HI)、波多黎各(PR)、美属维尔京群岛(VI)分别使用独立子投影与缩放/平移放置参数,使远离本土的区域也能在画布内合理排布(如 AK 以 0.37 比例缩放);
  4. 随机非相邻配色:-classify non-adjacent colors=Tableau10。non-adjacent 是 mapshaper-classify-methods.mjs 中列出的着色方法之一,它会借助图着色算法(见 src/color/graph-color.mjs)为相邻多边形分配不同颜色,避免接壤州同色;colors=Tableau10 指定内置 Tableau 10 色板。也可用 colors=random 随机配色;
  5. 内部边界描边:-innerlines + name=innerlines 只提取州与州之间的共享边界(不含海岸线),随后 -style stroke=white stroke-width=0.5 为全部图层(包括 states)设置白色细描边。文档强调:只给内部边界加描边、不给外边界加,能产生更准确、更清晰的"海岸线"效果;
  6. 输出:-target states,innerlines -o us-states.svg height=400 width=600。

文档提示:用 mapshaper -colors 命令可以列出所有内置色板,方便挑选 -classify 的 colors= 取值。

示例三:纽约州地图(New York State map)

页面:docs/examples/ny-state.md,配方文件:docs/examples/data/ny-state.txt。

完整配方

mapshaper \
  -i usa_can_admin1_lakes.geojson name=states \
  -filter 'name == "New York"' + name=NY \
  -proj lcc densify \
  -frame height=400 width=600 offset=4% name=rectangle \
  -target states \
  -clip rectangle \
  -each 'labelled = this.area > 1e10' \
  -points inner + name=labels \
  -filter labelled \
  -target states \
  -lines + name=borders \
  -i usa_can_roads.geojson name=roads \
  -proj match=NY \
  -clip rectangle \
  -divide NY \
  -style target=labels label-text=name dy=4 fill='#aaa' font-size=13px \
  -style target=labels fill='#666' font-size=20px where='name=="New York"' \
  -style target=roads stroke='name=="New York" ? "#aaa" : "#e2e2e2"' stroke-width=0.6 \
  -style target=states fill='name=="New York" ? "#ececec" : "#fafafa"' \
  -style target=borders stroke='#c5c5c5' stroke-width='TYPE=="inner" ? 1 : 0.7' \
  -style target=NY stroke='#555' stroke-width=1.2 \
  -style target=rectangle fill='#f1f1f1' \
  -target rectangle,states,roads,borders,NY,labels \
  -o ny-state.svg

逐步解读

  1. 加载与分离:-filter 'name == "New York"' + name=NY 复制出只含纽约州的 NY 图层,原 states 层保留;
  2. 投影:-proj lcc densify。Lambert 等角圆锥投影(LCC)需要额外参数;只写 lcc 时 Mapshaper 会用目标图层的包围盒自动计算合理参数(文档原文)。densify 选项在投影需要把长直线段变成曲线时补充顶点,避免大跨度线段在投影后失真;
  3. 画框与裁剪:-frame height=400 width=600 offset=4% name=rectangle 围绕纽约州创建一个矩形框;-target states -clip rectangle 把各州裁剪进框内,作为地图的取景范围;
  4. 标注点:-each 'labelled = this.area > 1e10' 为面积大于 1e10 平方米(约 1 万平方公里)的州打上标记(this.area 在未投影经纬度数据上返回平方米);-points inner + name=labels 用 inner 锚点算法为多边形生成内部标注点——该算法的降级路径在 mapshaper-anchor-points.mjs 中可见:若内部锚点求取失败,会回退到质心;随后 -filter labelled 只保留足够大的州的标注;
  5. 边界线:-lines + name=borders 提取州界(含内部与外部边界,靠 TYPE 区分);
  6. 道路图层:加载 Natural Earth 道路数据 usa_can_roads.geojson,-proj match=NY 让道路匹配纽约州的投影,-clip rectangle 裁进取景框;
  7. 按州界切分道路:-divide NY 用纽约州多边形把道路在州界处切断,并给落在纽约州内的道路段附加 NY 图层的属性——这样后续可以用 name=="New York" 表达式分别样式化州内/州外道路;
  8. 样式:一系列 -style 用三元表达式按条件设置颜色:纽约州名称用更大的字号(where='name=="New York"')、州内道路更暗、纽约州填充更亮、内部边界描边更粗(TYPE=="inner" ? 1 : 0.7)等;
  9. 输出:-target rectangle,states,roads,borders,NY,labels -o ny-state.svg。

从配方到资产:data 目录与构建流程

三个示例的源数据与构建输入全部位于 docs/examples/data/,包括配方 .txt、Natural Earth 源 GeoJSON,以及驱动资产构建的 Makefile。

一次调用产出多份输出

Makefile 的核心技巧是:Mapshaper CLI 支持在同一调用中堆叠多个 -o 命令,所以配方文件自带的 -o globe.svg 和 Makefile 追加的 -o globe.msx 会在同一次 mapshaper 调用里先后执行,无需运行两遍。例如:

globe:
	mapshaper globe.txt -o globe.msx
	rm -f globe.zip && zip globe.zip ne_50m_admin_0_countries.geojson
  • mapshaper globe.txt -o globe.msx:globe.txt 本身是一条以 mapshaper 开头的命令文件,其内部已含 -o globe.svg;追加的 -o globe.msx 再导出一份会话快照;
  • zip globe.zip ...:把原始输入 GeoJSON 打包,供读者下载后从零复现。

快照(.msx)让"一键打开成图"成为可能

.msx 是 Mapshaper 的会话快照格式,详细说明见 docs/formats/snapshot.md:它把当前会话的弧段、图层、属性、CRS 元数据、拓扑以及(来自 Web 应用时)命令历史打包成单个二进制文件,序列化基于 msgpack(经由 msgpackr 库)。

快照有两个值得注意的行为:

  • -o foo.msx 捕获整个会话——所有数据集和图层都会被写入,不只 -target 选中的那些;
  • -target 控制的是可见性与叠放顺序:被 -target 匹配的图层回到 Web 应用中默认可见,并按匹配顺序自下而上堆叠(第一个在底层,最后一个在顶层);未被匹配的图层会以隐藏状态进入文件,仍可通过图层面板重新显示。

正因如此,图库的"Open in the web app"链接(https://mapshaper.org/?files=<snapshot>&q,其中 &q 跳过导入对话框让地图立即出现)才能准确还原配方最终的目标视图。构建脚本在 build-docs.mjs 中生成这些链接,并在页面加载时由 docs/_assets/docs.js 重写为当前域名——这样用 mapshaper-gui 在本地预览文档时链接依然可用。

图库磁贴的渲染位置

构建时,<!-- mapshaper:gallery --> 被替换为 .gallery-grid 网格(图片 + 标题 + 描述),<!-- mapshaper:featured count=N --> 被替换为首页的 .featured-maps 横条。因此:

  • 页面级占位符 mapshaper:image、mapshaper:code、mapshaper:assets 由各示例页自己的 frontmatter 解析(图片、配方代码块、资产下载链接);
  • 跨页面占位符 mapshaper:gallery、mapshaper:featured 由遍历导航收集得到;
  • 引用的文件缺失会直接抛错(build-docs.mjs),防止拼写错误静默产生坏链。

如何运行与复现这些示例

方式一:命令行直接跑配方

每个配方文件(.txt)本身就是一条以 mapshaper 开头的命令文件。安装 CLI 后(npm install -g mapshaper,详见 docs/essentials/command-line.md),在 docs/examples/data/ 目录下即可直接运行:

mapshaper globe.txt
mapshaper us-states.txt
mapshaper ny-state.txt

mapshaper commands.txt 是 mapshaper -run commands.txt 的简写。命令文件支持 # 注释、无需转义 shell 元字符、允许行尾 \ 续行(非必须,不以前导 - 开头的行会自动接到上一条命令上)。配方中的文件名与字段名是示例性的,替换成自己的数据即可。

方式二:复制到 Web 应用控制台

示例也适用于 Web 应用的 Console(docs/essentials/web-app.md):先加载数据,再在控制台里执行配方命令。配方保留了每条命令前导的 -,这种风格在 Web 控制台与 CLI 中都能工作。注意 Web 控制台禁用 -i、-include、-require 等文件加载命令,所以要把配方的 -i 步骤换成拖拽/Add files 导入。

方式三:下载源数据与快照

每个示例页的 Assets 区提供:

  • Open in the web app:通过 ?files=<snapshot>&q 直接加载成图快照;
  • Download snapshot(.msx):下载快照文件,之后可拖入 Web 应用或 CLI 中继续编辑;
  • Download source data(.zip):下载原始输入,端到端复现整个配方。

快照文件可在 Web 应用内通过 History 菜单的 Create snapshot / Restore 管理,也可用 -o foo.msx 从 CLI 导出;在浏览器里它是实验操作前的"存档点",而导出到磁盘的 .msx 可跨会话保存(docs/formats/snapshot.md)。

把新地图挂进图库:扩展机制

从 Makefile 头部注释可以提炼出新增一个图库示例的标准流程:

  1. 在 docs/examples/data/ 放入 <slug>.txt 配方文件与源数据;
  2. 在 docs/examples/<slug>.md 页面中声明 recipe:、image:、snapshot:、download:(有 image: 才会出现在图库磁贴中);
  3. 在 Makefile 中按 globe 目标的模式追加构建目标(mapshaper <slug>.txt -o <slug>.msx + 打包源数据 zip);
  4. 把 slug 加入 EXAMPLES 变量。

构建文档站时(npm run docs,入口见 build-docs.mjs),copyReferencedDataFiles() 会把 frontmatter 引用的资产复制到输出目录,图库磁贴与首页 Featured 横条都会自动更新。

图库之外的配套资源

小结

Mapshaper 的 Gallery 不是一个静态图片墙,而是一条**"配方 → 资产 → 图库"的全自动流水线**:每个示例页用 frontmatter 声明配方与资产,构建脚本把占位符渲染成磁贴网格,快照机制让读者一键打开成图,.zip 源数据包则保证任何地图都能端到端复现。三张示例地图分别展示了透视投影 + 经纬网(Globe)、复合投影 + 非相邻配色(U.S. States)、裁剪取景 + 锚点标注 + 条件样式(New York State)三类典型制图场景——把它们读懂,你就能把相同的命令组合迁移到自己的数据上,制作用 Mapshaper 完成的成品级地图。

登录后查看全文
mapshaper