企业官网建设流程全解析

• GIS
• CLI
• 数据可视化

-buffer是 Mapshaper 中围绕点、线、面要素创建缓冲多边形的核心命令。本指南基于 docs/guides/buffering.md 与仓库源码（src/commands/mapshaper-buffer.mjs 及src/buffer/下的实现模块），系统讲解缓冲距离在经纬度与投影坐标系下的差异、fill-gaps缺口填充、topological拓扑缓冲的底层原理，以及tolerance、vertices、quad-segs、cap-style、max-widening、merge-islands、geodesic等全部选项的用法。读完本文，你将能够根据数据坐标系正确选择缓冲模式，并用一条命令完成海岸线缺口填充、国界内政边界保持等常见制图任务。

命令概览：从最简单的缓冲开始

-buffer可以对 point（点）、polyline（折线）和 polygon（面）三种几何类型创建缓冲多边形，基本调用形式是：

mapshaper rivers.shp -buffer 2km -o river_buffers.shp

这条命令读取rivers.shp，围绕每条河流要素向外扩展 2 公里生成缓冲区多边形，并写入river_buffers.shp。下图中粉色为源线要素，黑色为生成的缓冲多边形：

缓冲区距离通过<radius>参数（或等价的radius=选项）指定，可以是常量，也可以是 JavaScript 表达式。当数据位于经纬度（longitude/latitude）坐标系时，Mapshaper 默认创建测地线（geodesic）缓冲，500m、2km这类距离表示的是地球表面的真实地面距离；当数据处于投影坐标系时，缓冲默认在其平面坐标系内按投影坐标计算，如果希望改用地面距离，需要显式追加geodesic选项。两种模式的详细差别与实现路径见下一节。

缓冲距离与坐标系：测地线缓冲 vs 平面缓冲

经纬度数据的测地线缓冲

对于经纬度输入，-buffer的距离单位直接换算为球面上的地面距离。docs/reference.md中的-buffer参考 说明：

• 半径值可以携带单位后缀，例如500m、2km、1mi、1000ft；
• 当数据集具有已知 CRS 且半径未带单位时，默认按米解释；
• 当数据集没有 CRS 信息时，无单位半径按源坐标单位解释。

从源码看，半径解析由 mapshaper-buffer-common.mjs 的getBufferDistanceFunction()完成：先尝试用parseConstantBufferDistance()解析常量距离，失败则把半径编译为逐要素求值的 JavaScript 表达式（compileFeatureExpression），因此支持类似-buffer 'POPDENS * 100m'这样按属性动态变化的缓冲距离。

投影数据：默认平面缓冲与 geodesic 模式

投影数据默认在其平面坐标系中缓冲，此时距离直接用投影坐标单位度量——参考文档提醒，如果所用投影在数据范围内不保距，结果可能出现形变。要给投影数据使用地面距离，需追加geodesic：

mapshaper projected.shp -buffer 1km geodesic -o out.shp

其实现位于 src/commands/mapshaper-buffer.mjs 的buildGeodesicProjectedBufferDataset()，调用链可以概括为三步：

1. 克隆源图层并反投影到 WGS84 经纬度——克隆避免改动原数据集，且要求源投影存在可逆变换（源码中isInvertibleCRS守卫，否则报错The geodesic option requires a source projection with an inverse）；
2. 在经纬度克隆上走普通测地线缓冲管线（buildBufferDataset会自动选择球面偏移构造）；
3. 把缓冲结果正投影回源 CRS，并借助projectDataset的投影前裁剪/钳位处理超出投影有效范围的几何。

从代码结构看，buildBufferDataset()（mapshaper-buffer.mjs）按几何类型分派到三个模块：点缓冲走 mapshaper-point-buffer.mjs、线缓冲走 mapshaper-polyline-buffer.mjs、面缓冲走 mapshaper-polygon-buffer.mjs。

fill-gaps：填充河流、海湾与封闭空洞而不增长外边界

fill-gaps选项用于填充封闭空洞和窄口入口（narrow-mouthed inlets），但不增长外边界。典型场景是：在一层面状数据（如海岸线多边形）中填充河流、海湾、水道等缺口，同时把开阔的海岸线原样保留。

mapshaper states.shp -buffer 5km fill-gaps -o output.shp

下面的示例图展示了对一条长的河流入海口和海岸线上若干小缺口的填充效果，主外边界被完整保留：

max-widening：控制缺口被填充的最大宽度

max-widening=配合fill-gaps使用，用于限制缺口宽度上限——超过该宽度的间隙保持开放。默认值为5，即：以 1km 缓冲距离执行fill-gaps时，宽度小于 5km 的内部间隙会被填充，更宽的间隙保持开放。参考文档给出的完整表述是"填充宽度不超过缓冲距离该倍数的内部间隙"。

对应源码中，GAP_MAX_WIDENING_DEFAULT = 5定义于 mapshaper-polygon-buffer.mjs，getGapMaxWideningFactor()（同文件 L298-L305）要求该值必须>= 1，否则报错。文档注释解释了默认值刻意"远大于 1"的原因：避免在宽度围绕嘴部尺寸波动的河道上留下一串小洞（例如哥伦比亚河）。

merge-islands：是否把小岛桥接到邻近大陆

默认情况下，fill-gaps会让小型孤立岛屿保持分离，不会把它跨过窄水道桥接到邻近大陆；追加merge-islands后，这类小岛也会被桥接。判定标准是：只有面积小于"以嘴部半径为半径的圆盘"（mouth-radius disk）的陆地才被视为岛屿；两个大型陆地之间的间隙（如两州之间的河流）无论是否使用merge-islands都会被填充。

源码级原理：一次形态学闭运算（morphological closing）

fill-gaps的实现在 mapshaper-polygon-buffer.mjs 的makeGapFillPolygonBuffer()中，注释将其描述为"拓扑感知的形态学闭运算"，包含两个阈值：

• 嘴部半径 r = mouthSize/2：控制哪些缺口会被海岸封住——只有开口比嘴部尺寸窄的缺口才会被封闭；
• 填充半径 R = k·mouthSize/2（k 为 max-widening 倍数）：决定填充深入封闭入口多远，以及多宽的内部间隙必须保持开放。

实现步骤为：先用拓扑缓冲以 R 增长每个要素并按最近源分割争议空间（T_R），再用嘴部半径 r 对陆地做"膨胀—并集—腐蚀"得到嘴部门控掩膜（mask），掩膜内部比 k·mouthSize 窄的孔洞被填充，最后把T_R裁剪到填充后的掩膜上，从而既填充了窄缺口、又完整保留各要素原始面积。值得注意的是，fill-gaps天然是拓扑性的（内部强制启用 topological 管线），因此不必同时显式写topological。

topological：只缓冲未共享的边界

对于面图层，topological选项只缓冲未共享的多边形边界，例如海岸线和空洞；相邻多边形之间的共享边界不被缓冲，且重叠的缓冲区域会按**邻近度（proximity）**在要素之间分割——争议空间中的每个点归属于最近的源多边形。

mapshaper countries.shp -buffer 25km topological -o coast_buffers.shp

下图中缓冲区沿海岸线生成，而国家之间的内部边界保持原样：

参考文档还强调：拓扑缓冲的缓冲区不覆盖任何原始多边形区域。实现上，拓扑管线复用 Delaunay/Voronoi 中轴构造来划分要素间的争议地带，相关代码位于 mapshaper-buffer-voronoi.mjs（buildInterFeatureMedialLines、buildInterFeatureDelaunay）以及 mapshaper-polygon-buffer.mjs 中makePolygonBuffer()的 topological 分支。命令入口处对选项有严格的类型校验：topological与fill-gaps都要求输入为 polygon 图层，否则直接报错（见 mapshaper-buffer.mjs）。

点缓冲与线缓冲的细分选项

点要素：vertices 控制圆的平滑度

点要素缓冲生成圆形多边形，vertices=指定近似圆所用的顶点数，默认72。参考文档给出的完整说明是"用于近似每个点缓冲圆的顶点数，默认 72"；源码 mapshaper-point-buffer.mjs 中正是var vertices = opts.vertices || 72;。对于经纬度输入，圆由测地线段构造（getGeodeticSegmentFunction），从而保持地面距离。

线要素：quad-segs、cap-style 与 offset-left/right

• quad-segs=：连接处与端帽中每个四分之一圆所用的线段数，默认8（mapshaper-polyline-buffer.mjs 中opts.quad_segs >= 2 ? opts.quad_segs : 8）；
• cap-style=flat|round：线缓冲的端帽样式，默认round（同文件 L89 的roundCaps: (opts.cap_style || 'round') == 'round'）。扁平端帽让线缓冲区呈"跑道"形，圆端帽则向外鼓出；
• 参考文档还提到"线缓冲默认端帽为 round、可为 flat"，若只需线的单侧偏移，命令层支持offset-left=/offset-right=选项：它们把单侧缓冲的外边缘作为线图层输出（而非缓冲多边形），且仅适用于 polyline 图层；两个选项不能同时使用（见 mapshaper-buffer.mjs）。

tolerance：速度与精度的权衡

tolerance=设置线/面缓冲可接受的半径误差，取值可以是距离（如20m）或缓冲半径的百分比（如1%），默认1%。较小的容差让缓冲生成更快，而tolerance=0可完全禁用该优化。解析逻辑在 mapshaper-buffer-common.mjs 的parseBufferTolerance()：百分号形式按比例折算，距离形式按常量距离折算。容差同时驱动缓冲前的 Douglas-Peucker 预简化（getBufferSimplifyFunction，默认简化区间等于误差预算BUFFER_SIMPLIFY_FACTOR = 1），并作为子容差伪影清理的阈值（cullSubTolerancePolygonArtifacts，mapshaper-polygon-buffer.mjs）——小于tol × tol的碎片化正面积伪影会被丢弃，而最小合法缓冲部件（点状要素的膨胀，约 π·d²）比阈值大四个数量级，因此真实几何不会被误删。

完整选项速查表

以下汇总自 docs/reference.md 的-buffer条目：

参考文档给出的三个可直接运行的示例：

# 对线图层做 2km 缓冲 mapshaper roads.shp -buffer 2km -o roads_buffer.geojson # 对面图层创建拓扑海岸线风格缓冲 mapshaper counties.shp -buffer 100m topological -o counties_buffer.geojson # 填充宽度不超过 500m 的入口与封闭空洞，不增长海岸线 mapshaper land.shp -buffer 500m fill-gaps -o land_filled.geojson

另外，负距离缓冲（-buffer -1km）仅对面图层受支持：正距离扩大多边形并缩小空洞，负距离缩小多边形并扩大空洞。

注意事项与已知限制

原指南在 Notes and limitations 一节明确列出了三项限制，实现代码也印证了这些边界行为：

1. 反子午线（antimeridian）：跨越反子午线的测地线缓冲会被自动拆分并包裹，但该支持仍属实验性。相关处理在 mapshaper-polyline-buffer.mjs 的splitAntimeridianBufferDataset与 mapshaper-antimeridian-cuts.mjs 中。
2. 地球模型：测地线缓冲尺寸基于球面而非椭球地球模型计算，可能不足以满足高精度 GIS 分析需求。
3. 极点处理：到达极点的面缓冲使用实验性的极点处理（源码中polygonBufferNeedsPolarMode/makePolarPolygonBuffer，见 mapshaper-polygon-buffer.mjs），并会在控制台输出Using experimental polar buffer mode...提示；测地线线缓冲则不能延伸到极点。另外，若面要素的某条边跨越完整经度范围（如 -180 → 180）且中间无顶点，缓冲时会塌缩为细条，源码会发出警告并建议先加密（densify）该边。

如何进一步验证与深入

-buffer的行为有完整的测试覆盖，可在仓库 test/ 目录中查看：普通缓冲测试见 test/buffer-test.mjs 与 test/buffer-bugfix-test.mjs，缺口填充专项见 test/buffer-fill-gaps-coastline-test.mjs，线缓冲见 test/polyline-buffer-test.mjs 与 test/polyline-buffer-v4-test.mjs，环移除与楔形暴露算法见 test/buffer-loop-removal-test.mjs 与 test/wedge-exposure-test.mjs。若要深入实现，推荐从命令入口 mapshaper-buffer.mjs 开始，沿makePolygonBuffer/makePolylineBuffer/makePointBuffer三个构造器追踪调用链。

• GIS
• CLI
• 数据可视化