# 移植说明

## 来源

原项目：topojson/topojson-client，v3.1.0。
来源：https://github.com/topojson/topojson-client/tree/71e5bd6428fd8b7a40fa980d2ef7862140851f03
许可证：ISC，Copyright 2012–2019 Michael Bostock。测试基准源码位于 tools/upstream/src，保持上游内容；该目录只供 Node 对照测试使用，MoonBit 运行时不加载它。

## 对应关系

| 上游源码 | MoonTopo |
| --- | --- |
| transform / reverse | transform.mbt 的 point、arc |
| feature | feature.mbt |
| bbox | bbox.mbt |
| untransform / quantize | untransform.mbt、quantize.mbt |
| neighbors / bisect | neighbors.mbt，排序去重代替有序插入 |
| stitch | stitch.mbt，端点索引与片段拼接 |
| mesh | mesh.mbt |
| merge | merge.mbt |

保留了负索引按 -i-1 寻址、先累计 delta 再反转、共享弧去重、按绝对平面面积选择外环等规则。重复引用同一弧可能让上游 neighbors 包含自身索引；MoonTopo 保留了这个行为。

## MoonBit 接口调整

Topology 封装经过校验的 Json。公开 object 返回分离副本，量化、裁剪等方法返回新的 Topology，不修改调用方输入。动态几何转换为标准库 Json，以便保留 id、properties、bbox 等元数据。

JavaScript 的任意 mesh 回调收敛成 All / Interior / Exterior 三种常见过滤模式。对象使用名称选择。stitch 使用排序后的端点键输出片段，片段排列可能与 JS 的对象插入序不同。闭环表示的起点也允许不同；差分工具只在 mesh / merge 上规范化这些顺序，其余坐标严格比较。

额外提供 dequantize、prune、statistics、quantization_report 和 JSON 请求入口。prune 重编号弧并重新计算 bbox；dequantize 保留引用关系。quantization_report 在删除量化碰撞点之前逐样本测量 XY，存储点数则统计删除之后的数据。

## 输入限制

文本上限为 16,777,216 个 UTF-16 单元；JSON 嵌套最多 32 层，几何集合最多 16 层。最多 100,000 条弧、1,000,000 个存储点、100,000 次弧引用，引用展开预算为 2,000,000 个坐标。每条弧至少两个点，每个点 2–8 维，各输入数值有限且绝对值不超过 1e12。XY 参与拓扑，后续维度随点保留。

邻接计算限制单弧引用组最多 1,000 项，组长度平方累计不超过 2,000,000。超过边界抛出 TopoError。空拓扑 bbox 返回 None；量化空拓扑抛错。网格大小为 2–1,000,000,000；已量化输入须先 dequantize。

这些是内存与计算预算，不承担完整 GIS 几何有效性校验。自交面、错误环方向、未共享的重复坐标边界应在数据生产环节处理。端点拼接只按 XY 匹配；上游 JS 在非量化输入中可能把额外维度计入键，这类数据建议先统一维度。

## 测试方法

固定对照覆盖七类几何、反向弧、delta、元数据、孔洞与不连通区域；生成对照覆盖 1–8 列、1–4 行矩形行政区。所有上游调用对输入深拷贝，避免 merge 的临时标记串扰用例。浮点容差 1e-9，键顺序不影响 Json 对象相等性。测试失败会非零退出。

矩形数据适合验证共享边消除和邻接索引，但不能替代真实地图规模压测。量化误差按坐标单位给出，未做地理坐标到米的换算。