Moonbit docs

// 3MF 解析。
//
// 3MF（3D Manufacturing Format）是现代切片软件实际使用的格式——PrusaSlicer、
// Bambu Studio、Cura 导出的都是它，定位上就是 STL 的正式替代品。
//
// 它和 STL 有两处根本不同：
//
//   1. **它是个 ZIP 包**（OPC 容器），模型数据装在里面一个 XML 部件里，
//      通常叫 3D/3dmodel.model。
//   2. **顶点是共享的**。三角形存的是顶点表下标，和 OBJ 一样，
//      而不是像 STL 那样每个三角形把自己的三个顶点重写一遍。
//
// 第二点对「能不能打印」这个问题特别重要：**拓扑关系是现成的**。
// STL 里「哪些三角形共用同一个顶点」得靠容差焊接去猜（差 1e-9 的算不算同一个点？），
// 3MF 直接写清楚了。所以同一个模型，3MF 的水密性判断比 STL 更可靠。
//
// 代价是格式复杂得多：要解 ZIP、要解 XML，对象还能互相引用拼成装配体。

///|
/// 一个 3MF 对象。
///
/// 两种形态二选一：要么自带网格（顶点表 + 三角形索引），要么是一组组件
/// （引用别的对象，各带一个变换矩阵）。用两个数组共存来表示，
/// 比套一层枚举少绕几下——解析时本来就是一个一个往里塞。
priv struct MfObject {
  /// 共享顶点表
  vertices : Array[Vec3]
  /// 三角形，存的是顶点表下标
  triangles : Array[(Int, Int, Int)]
  /// 组件：引用的对象 id + 变换矩阵
  components : Array[(Int, FixedArray[Double]?)]
}

///|
/// 3MF 是个 ZIP 包。只看魔数，真正的校验在 `parse_3mf` 里做——
/// 「打开才知道」的检查不该塞进一个只看开头的判断函数。
pub fn is_3mf(data : Bytes) -> Bool {
  data.length() >= 4 &&
  data[0] == b'P' &&
  data[1] == b'K' &&
  // 空 ZIP 的开头是 PK\x05\x06，这里要的是有内容的那种
  data[2] == b'\x03' &&
  data[3] == b'\x04'
}

///|
/// 解析 3MF：解 ZIP → 找模型部件 → 解 XML → 按 build 里列的对象拼出网格。
pub fn parse_3mf(data : Bytes) -> Result[Mesh, String] {
  // 解 ZIP。fzip 自带 zip bomb 防护（解压比超过 1000 倍直接拒绝）
  // 和不安全路径拒绝（绝对路径、`..` 一律不收）——解析用户传上来的文件，
  // 这两道防线是必须的，自己写很容易漏。
  let entries = @fzip.unzip_sync(data.to_fixedarray()) catch {
    @fzip.FzipError(message~, ..) =>
      return Err("这不是一个合法的 3MF：ZIP 解不开——\{message}")
  }
  let xml = match find_model_part(entries) {
    Ok(text) => text
    Err(msg) => return Err(msg)
  }
  parse_model_xml(xml)
}

///|
/// 从压缩包里找出模型部件。
///
/// 正规做法是读 `_rels/.rels`，里面记着哪个部件是模型。绝大多数文件确实就叫
/// `3D/3dmodel.model`。两条路都走：先按规范查关系表，查不到再退化成
/// 「找唯一一个 .model 文件」——有些导出器写的关系表不规范，但文件名是对的。
fn find_model_part(
  entries : Array[(String, FixedArray[Byte])],
) -> Result[String, String] {
  let target = match find_entry(entries, "_rels/.rels") {
    Some(raw) => rels_model_target(@utf8.decode_lossy(Bytes::from_array(raw)))
    None => None
  }
  match target {
    Some(path) =>
      match find_entry(entries, path) {
        Some(raw) => Ok(@utf8.decode_lossy(Bytes::from_array(raw)))
        None =>
          Err(
            "3MF 的关系表指向「\{path}」，但包里没有这个部件",
          )
      }
    None => {
      // 退路：找 .model 文件
      let models : Array[String] = []
      for entry in entries {
        let (name, _) = entry
        if name.to_lower().has_suffix(".model") {
          models.push(name)
        }
      }
      if models.length() == 0 {
        Err(
          "这个 ZIP 里没有 3D 模型部件（找不到 .model 文件），不是 3MF 文件",
        )
      } else if models.length() > 1 {
        Err(
          "这个 3MF 里有 \{models.length()} 个 .model 部件，关系表也没说是哪个，认不出来",
        )
      } else {
        match find_entry(entries, models[0]) {
          Some(raw) => Ok(@utf8.decode_lossy(Bytes::from_array(raw)))
          None => Err("读不到模型部件「\{models[0]}」")
        }
      }
    }
  }
}

///|
/// 从 `_rels/.rels` 里找出模型部件路径。
///
/// 关系表长这样：
///
/// ```xml
/// 
/// ```
///
/// 认的是 Type 后缀而不是 Id——Id 是随便起的。
fn rels_model_target(xml : String) -> String? {
  let reader = @xml.Reader::from_string(xml)
  let mut found : String? = None
  while found is None {
    let event = reader.read_event() catch {
      // 关系表坏了不该让整个解析失败，退回去按文件名找就行
      _ => break
    }
    let element = match event.kind {
      @xml.EventKind::Start(e) | @xml.EventKind::Empty(e) => e
      // **必须在这里停下来。**
      //
      // 读到文件末尾之后，`read_event` 会一直返回 `Eof` 而不会抛错。
      // 少了这个分支，一个「关系表是合法 XML、但里面没有 3dmodel 关系」的包
      // 就会在这里无限空转——CPU 跑满，命令行和网页都卡死，而且永远等不到报错。
      // 现实中把 .docx 改名成 .3mf 就是这个样子。
      @xml.EventKind::Eof => break
      _ => continue
    }
    if local_name(element.name) != "Relationship" {
      continue
    }
    let kind = match element.get("Type") {
      Some(t) => t
      None => continue
    }
    if !kind.has_suffix("/3dmodel") {
      continue
    }
    // 关系对上了但没有 Target——文件不规范，不算数，继续往后找
    match element.get("Target") {
      Some(t) => found = Some(normalize_part_path(t))
      None => ()
    }
  }
  found
}

///|
/// OPC 里的路径可能写成 `/3D/3dmodel.model` 这种带前导斜杠的，
/// 而压缩包里存的是 `3D/3dmodel.model`。统一去掉前导斜杠。
fn normalize_part_path(path : String) -> String {
  if path.has_prefix("/") {
    path[1:].to_owned()
  } else {
    path
  }
}

///|
/// 按名字找一个部件。
///
/// 大小写不敏感——OPC 的部件名在规范里不区分大小写，
/// 实际文件里 `3D/3dmodel.model` 和 `3d/3DModel.model` 都出现过。
fn find_entry(
  entries : Array[(String, FixedArray[Byte])],
  name : String,
) -> FixedArray[Byte]? {
  let want = normalize_entry_name(name)
  for entry in entries {
    let (entry_name, bytes) = entry
    if normalize_entry_name(entry_name) == want {
      return Some(bytes)
    }
  }
  None
}

///|
/// 把压缩包里的条目名规范化，好用来比对。
///
/// 两件事：
///
/// 1. **转小写**——OPC 的部件名不区分大小写。
/// 2. **反斜杠换成正斜杠**——ZIP 规范要求条目名用正斜杠，但 Windows 上一些
///    打包工具（比如 PowerShell 的 `Compress-Archive`）会写成反斜杠。
///    不归一化的话，一个结构完好的包会因为 `3D\3dmodel.model` 匹配不上
///    `3D/3dmodel.model` 而被判成「没有模型部件」——报错完全指错了方向。
fn normalize_entry_name(name : String) -> String {
  let lower = name.to_lower()
  if lower.contains("\\") {
    lower.replace_all(old="\\", new="/")
  } else {
    lower
  }
}

///|
/// 去掉命名空间前缀，只留本地名。
///
/// 3MF 的 XML 用默认命名空间，正常情况下标签就是 ``。
/// 但规范允许写前缀形式 ``，
/// 那就得把 `m:` 切掉才能按名字匹配。
fn local_name(name : String) -> String {
  let mut last : StringView = name[:]
  for part in name.split(":") {
    last = part
  }
  last.to_owned()
}

///|
/// 取命名空间前缀。没有冒号就是空串（默认命名空间）。
fn prefix_of(name : String) -> String {
  match name.find(":") {
    Some(i) => name[:i].to_owned()
    None => ""
  }
}

///|
/// 3MF 核心命名空间的识别特征。
///
/// 不写死完整 URI 是因为后面可能跟版本号（规范的命名空间是
/// `http://schemas.microsoft.com/3dmanufacturing/core/2015/02`）。
const CORE_NS_MARK : String = "3dmanufacturing/core"

///|
/// 从根元素的命名空间声明里找出**核心命名空间用的是哪个前缀**。
///
/// 为什么需要这个：只看本地名会把别的命名空间的同名元素也认成核心元素。
/// 最现实的例子是 3MF 的切片扩展——里面有 `` / ``，
/// 那是**二维**顶点，规范只定义了 x 和 y，**没有 z**。不区分命名空间的话
/// 它会被当成核心的三维顶点，报一句「少了坐标属性 z」，
/// 结果是一份完全合法的文件整个解析不了。
///
/// 返回 `None` 表示根元素上没有声明核心命名空间，那就退回老规矩：
/// 不带前缀的元素都算核心的。
fn detect_core_prefix(element : @xml.XmlElement) -> String? {
  for attr in element.attributes {
    if !attr.value.contains(CORE_NS_MARK) {
      continue
    }
    // 默认命名空间写成 xmlns="..."，前缀是空串
    if attr.name == "xmlns" {
      return Some("")
    }
    if attr.name.has_prefix("xmlns:") {
      return Some(attr.name[6:].to_owned())
    }
  }
  None
}

///|
/// 解析 3D/3dmodel.model。
///
/// 关心的标签只有几个：`model`（拿单位）、`object`（攒顶点和三角形）、
/// `component`（装配体引用）、`item`（build 里列出要打印的对象）。
/// 其余（metadata、basematerials、切片信息……）全部跳过——
/// 它们和「能不能打印」没关系。
fn parse_model_xml(xml : String) -> Result[Mesh, String] {
  let reader = @xml.Reader::from_string(xml)
  let objects : Map[Int, MfObject] = Map([])
  // build 里列出的 (对象 id, 变换)
  let build : Array[(Int, FixedArray[Double]?)] = []

  // 单位换算到毫米。STL 没有单位概念，3MF 有，不换算的话
  // 一个以英寸建模的模型体积会差 25.4³ ≈ 16387 倍
  let mut unit_scale = 1.0

  // 核心命名空间用的是哪个前缀。`None` = 还没见到根元素
  let mut core_prefix : String? = None

  // 当前正在攒的对象
  let mut cur_id : Int? = None
  let mut cur_vertices : Array[Vec3] = []
  let mut cur_triangles : Array[(Int, Int, Int)] = []
  let mut cur_components : Array[(Int, FixedArray[Double]?)] = []

  while !reader.is_eof() {
    let event = reader.read_event() catch {
      err =>
        return Err(
          "3MF 的模型 XML 解析失败（第 \{reader.line()} 行）：\{err}",
        )
    }
    let element = match event.kind {
      @xml.EventKind::Start(e) | @xml.EventKind::Empty(e) => e
      @xml.EventKind::End(name) => {
        // 对象在这里收尾。但自闭合的 `