MoonBit Fiducial Marker Detection (moonbit-fiducial-marker)

moonbit-fiducial-marker 是一款基于 MoonBit 语言纯原生实现 的视觉标记检测与三维位姿估计开发库。项目避开已有的 QR 码生成/解码方向，专注于机器人视觉导航、空间定位、增强现实 (AR) 叠加与工业视觉场景。

项目实现了类似于 ArUco 与 AprilTag 规范的二进制标记识别管道，包含图像分割、轮廓提取、四边形拟合、单应性透视矫正、二进制网格采样、汉明码纠错与 3D 位姿估计。

---

🌟 核心特性 (Features)

1. 纯原生无外部依赖 (100% Pure MoonBit): 不依赖外部 C 语言或 WebAssembly 原生库，全套矩阵代数、透视变换与计算机视觉算法采用 MoonBit 语言纯手写实现。
2. 完整的视觉检测管道 (Full Vision Pipeline):
   • 图像二值化: 支持 Otsu 全局阈值分割与基于积分图 (Integral Image) 的 Bradly-Roth 自适应窗口二值化。
   • 轮廓与多边形提取: Suzuki 拓扑轮廓跟踪与 Ramer-Douglas-Peucker (RDP) 多边形逼近。
   • 单应性透视矫正: 基于直接线性变换 (DLT) 解算 3x3 Homography 矩阵，实现开箱即用的透视打平与采样。
   • 字典与纠错引擎: 内置 ArUco 4x4_50 及 AprilTag 16h5 标准字典，支持 4 方向旋转对称解算与汉明距离纠错。
   • 3D 位姿估计: 基于针孔相机模型 (Pinhole Camera) 与 Rodrigues 旋转向量转换解算 $rvecrvec$ 和 $tvectvec$，支持 3D 空间坐标轴投影。
3. 可视化与输出: 自动生成带有标记边框、ID 标签与 3D XYZ 坐标轴的 SVG XML 格式渲染结果。

---

🚀 快速上手 (Quick Start)

1. 安装与导入

在项目的 moon.mod 中添加依赖：

import {
  "wcb2515050242/fiducial_marker",
}

2. 代码示例 (Usage Example)

///|
test {
  // 1. 初始化相机内参 (Pinhole Camera Intrinsics)
  let camera = @fiducial_marker.CameraIntrinsics::new(
    500.0, 500.0, 320.0, 240.0,
  )

  // 2. 加载 Marker 字典 (ArUco 4x4_50)
  let dict = @fiducial_marker.dictionary_aruco_4x4_50()

  // 3. 生成或加载图像 canvas
  match @fiducial_marker.generate_synthetic_marker_image(0, dict, 120, 20) {
    Some(img) => {
      // 4. 执行标记检测与解码
      let detections = @fiducial_marker.detect_markers(img, dict)
      inspect(detections.length() >= 1, content="true")

      // 5. 解算 3D 位姿
      if detections.length() > 0 {
        let det = detections[0]
        let pose = @fiducial_marker.estimate_marker_pose(det.quad, camera, 0.1)
        inspect(pose != None, content="true")
      }
    }
    None => ()
  }
}

---

📁 模块架构 (Architecture)

c:\Users\px830\Desktop\胃肠斌黑客松初审\
├── types.mbt          # Point2D, Point3D, Quad, Matrix3x3, CameraIntrinsics, Pose3D 数据结构
├── matrix.mbt         # 3x3 矩阵代数、行列式、逆矩阵求值、矩阵向量乘法
├── image.mbt          # 8-bit 灰度图抽象、双线性插值采样、Bresenham 画线与 PGM 导出
├── threshold.mbt      # Otsu 全局阈值与积分图自适应窗口二值化
├── contour.mbt        # Suzuki 拓扑轮廓跟踪算法与 Gauss 鞋带公式面积/周长计算
├── quad.mbt           # Ramer-Douglas-Peucker 拟合、凸多边形过滤与角点标准化排序
├── homography.mbt     # DLT 3x3 Homography 矩阵求解器与透视变换采样
├── dictionary.mbt     # ArUco 4x4 及 AprilTag 16h5 字典与 90度旋转汉明纠错
├── decoder.mbt        # 黑色外框校验、网格比特提取与全图 Marker 识别管道
├── pose.mbt           # Rodrigues 旋转变换、相机投影与 3D 位姿求解
├── visualize.mbt      # SVG 可视化 overlay 渲染器与测试用合成 Marker 生成器
└── marker_test.mbt    # 100% 覆盖率的单元测试与集成测试套件

---

🛠️ 构建与测试 (Build & Test)

# 类型检查
moon check

# 运行全套单元测试
moon test

# 代码格式化校验
moon fmt --check

# 生成接口文档
moon info

---

📜 开源许可 (License)

本项目基于 Apache-2.0 License 开源。