#moongpx

MoonBit 的 GPX（GPS Exchange Format）规范实现：解析、校验、序列化、版本迁移。

#状态

#已知限制（当前开发版）

• 不支持带命名空间前缀的元素名：<g:gpx xmlns:g="..."> 会被判为"根元素不是 <gpx>"。 默认命名空间（xmlns="..."，真实文件里的绝大多数写法）不受影响。 彻底解决需要换用底层库的 NamespaceReader，见「依赖行为约定」
• parse_gpx 返回 Err 时，成功解析的部分会被丢弃。 需要"列出全部问题"时用 validate_gpx，它会连同 warning 一起报出
• GPX 1.0 → 1.1 是单向的：反向 1.1 → 1.0 会丢 extensions 与 fix/sat 等精度字段，本库不提供

#为什么需要它

#安装

moon add 2973181701/moongpx

#快速上手

fn main {
  // 纬度：闭区间 [-90, 90]
  match @moongpx.Latitude::from_string("31.2304") {
    Ok(lat) => println(lat.to_gpx_string())   // "31.2304"
    Err(e) => println(e.message())
  }

  // 经度：半开区间 [-180, 180) —— 180 非法
  match @moongpx.Longitude::from_string("180") {
    Ok(_) => println("不应该到这里")
    Err(e) => println(e.message())
    // longitude out of range [-180, 180): 180
  }
}

#API

#解析

parse_gpx(String) -> Result[Gpx, Array[Diagnostic]]

let src = "<gpx version=\"1.0\" creator=\"x\"><wpt lon=\"180\"/></gpx>"
match @moongpx.parse_gpx(src) {
  Ok(gpx) => println(gpx.creator)
  Err(diags) => println(@moongpx.format_diagnostics(diags))
}
// 1:6   error  E1003  version 必须是 "1.1"（schema 固定值），实际是 "1.0"
// 1:29  error  E1009  <wpt> 缺少必填属性 lat

#序列化

to_gpx(Gpx)          -> String   // 带 XML 声明与官方命名空间的完整文档
to_gpx_fragment(Gpx) -> String   // 不带声明与命名空间，便于嵌入别的 XML

let gpx = match @moongpx.parse_gpx(src) {
  Ok(g) => g
  Err(d) => { println(@moongpx.format_diagnostics(d)); return }
}
println(@moongpx.to_gpx(gpx))

<?xml version="1.0" encoding="UTF-8"?>
<gpx xmlns="http://www.topografix.com/GPX/1/1" version="1.1" creator="moongpx">
  <metadata>
    <name>测试轨迹</name>
    <bounds minlat="31" minlon="121" maxlat="31.5" maxlon="121.5"/>
  </metadata>
  <wpt lat="31.2304" lon="121.4737">
    <name>起点</name>
  </wpt>
</gpx>

parse_gpx(to_gpx(g)) == g          // 模型完全相等
to_gpx(parse_gpx(to_gpx(g))) == to_gpx(g)   // 幂等

#校验

validate_gpx(String)        -> Array[Diagnostic]   // 全部诊断，空数组 = 干净
is_valid_gpx(String)        -> Bool                // 连 warning 都没有才算通过
has_schema_errors(String)   -> Bool                // 只看 error
validate_gpx_report(String) -> String              // 直接可打印的报告
diagnostics_of_severity(Array[Diagnostic], Severity) -> Array[Diagnostic]

let src = "<gpx version=\"1.1\" creator=\"x\">" +
  "<wpt lat=\"1\" lon=\"1\"><ele>99999</ele><fix>bogus</fix></wpt>" +
  "<trk><name>空的</name></trk></gpx>"
println(@moongpx.validate_gpx_report(src))
// 共 3 条（1 错误 / 2 警告）：
// 1:69  error    E1016  <fix> 取值非法："bogus"（只允许 none / 2d / 3d / dgps / pps，小写）
// 1:32  warning  W1005  <ele> = 99999 m 超出地球表面合理范围（约 -11000 ~ 9000 m），请确认单位是否为米
// 1:91  warning  W1006  <trk> 没有任何 <trkseg>

let ok_but_suspicious = "<gpx version=\"1.1\" creator=\"x\"><wpt lat=\"1\" lon=\"1\"><ele>99999</ele></wpt></gpx>"

@moongpx.parse_gpx(ok_but_suspicious) is Ok(_)   // true —— 文档合法
@moongpx.has_schema_errors(ok_but_suspicious)    // false
@moongpx.is_valid_gpx(ok_but_suspicious)         // false —— 但有可疑之处
@moongpx.validate_gpx(ok_but_suspicious).length()  // 1

if @moongpx.has_schema_errors(src) {
  // 不合格，把问题列给用户看，不往下走
  println(@moongpx.validate_gpx_report(src))
} else {
  // 合格；warning 只是提醒，照常解析
  match @moongpx.parse_gpx(src) { Ok(g) => use(g), Err(_) => () }
}

#GPX 1.0 与版本迁移

parse_gpx_1_0(String) -> Result[Gpx, Array[Diagnostic]]  // 解析 1.0 并升级为 1.1 模型
parse_gpx_any(String) -> Result[Gpx, Array[Diagnostic]]  // 按 version 属性自动分派
detect_gpx_version(String) -> String?                    // 只读 version 属性，不校验

#轨迹统计

haversine_m(Waypoint, Waypoint) -> Double       // 半正矢大圆距离
path_distance_m(Array[Waypoint]) -> Double
track_distance_m(Track) -> Double
climb_m(Array[Waypoint], Double) -> (Double, Double)   // (爬升, 下降)
bounds_of(Array[Waypoint]) -> Bounds?
track_stats(Track) -> TrackStats

1. 跨 trkseg 不相连。trkseg 表示 GPS 信号中断后重新捕获， 段间位移不是真实运动轨迹，计入距离会凭空多出一大截。
2. 爬升必须带阈值。GPS 高程噪声在几米量级，朴素累加相邻点高差 会把来回抖动放大成几百米的假爬升——这是开源实现里最常见的 bug。 climb_m 默认阈值 3 m，传 0.0 可关闭过滤。

let s = @moongpx.track_stats(track)
// s.distance_m / s.ascend_m / s.descend_m / s.min_ele / s.max_ele
// s.bounds / s.start_time / s.end_time / s.duration_s

#数据模型

Waypoint::new(lat, lon).with_ele(Some(10.0)).with_time(Some("2020-01-01T00:00:00Z"))
TrackSegment::new(points)
Track::new(segments)
Bounds::new(min_lat, min_lon, max_lat, max_lon)
Gpx::new(creator)

#诊断

pub(all) enum Severity { Error; Warning }

pub struct Diagnostic {
  severity : Severity
  code : String      // 稳定代码，如 "E1009"
  message : String
  line : Int         // 1-based
  column : Int       // 1-based
}

format_diagnostics(Array[Diagnostic]) -> String
has_errors(Array[Diagnostic]) -> Bool

#坐标类型

Latitude::from_string(String) -> Result[Latitude, GeoError]
Latitude::from_double(Double) -> Result[Latitude, GeoError]
Latitude::to_double(Self)     -> Double
Latitude::to_gpx_string(Self) -> String

#数值工具

parse_decimal(String)   -> Result[Double, GeoError]   // 严格 xsd:decimal
format_decimal(Double)  -> String                     // 保证不含指数记法

#错误

pub(all) enum GeoError {
  NotADecimal(String)
  LatitudeOutOfRange(String)
  LongitudeOutOfRange(String)
  DegreesOutOfRange(String)
  DgpsStationOutOfRange(String)
}

GeoError::message(Self) -> String

#设计取舍

#xsd:decimal 是严格的，不是「能解析成数字就行」

(\+|-)? ( [0-9]+ (\.[0-9]*)? | \.[0-9]+ )

#为什么需要 format_decimal

1.0e-7   → "1e-7"      ← 非法 xsd:decimal
1.0e21   → "1e+21"     ← 非法 xsd:decimal

#Error 与 Warning：一条明确的界线

Error = 把这份文档丢进官方 XSD 校验器，它会判不合格。 Warning = 校验器会放行，但人看一眼就知道有问题。

#复用生态 XML 解析器，不自造

#extensions 的无损保留：一个容易踩的坑

@xml 的 offset 是 UTF-16 码元偏移，不是 Unicode 码点偏移。

#转义：不是「把特殊字符换掉」那么简单

#「空字符串 ≡ 缺失」

#依赖行为约定

#已知边界

• 不做地图渲染、不涉及瓦片或可视化
• 不做坐标系转换（WGS84 → GCJ-02 / BD-09）——那是坐标系规范，不是 GPX 规范
• 不做二进制格式（FIT）、不做 TCX / KML 互转
• 不联网、不读写文件（调用方自己把文本传进来）
• 底层 XML 库是 document-buffered，超大文件（>100 MB）会整体载入内存
• 不支持带命名空间前缀的元素名（<g:gpx>）；默认命名空间正常
• 不做 XML 数字签名校验（GPX 1.1 schema 允许，但实际文件几乎不用）

#规范依据

• GPX 1.1 Schema：https://www.topografix.com/GPX/1/1/gpx.xsd
• GPX 1.0 Schema：https://www.topografix.com/GPX/1/0/gpx.xsd

#开发

moon check          # 类型检查
moon test           # 单元测试
moon fmt            # 格式化
moon run cmd/main   # 可运行示例

#关于 CI

mkdir -p .github/workflows && cp ci/ci.yml .github/workflows/ci.yml

#许可证