MoonBit Fiducial Marker Vision Toolkit (moonbit-fiducial-marker)

moonbit-fiducial-marker is a high-performance, 100% pure MoonBit computer vision and 6-DOF spatial pose estimation toolkit for ArUco and AprilTag planar fiducial markers.

Designed specifically for robotics, UAV visual landing, SLAM navigation, AR augmented reality 3D overlay, camera calibration, and industrial automation inspection, this toolkit requires zero external C/C++ or WebAssembly foreign function bindings.

---

Key Features

• 100% Pure MoonBit: Native implementation of all linear algebra, SVD solvers, polygon topology, morphological operators, and camera calibration engines.
• Complete Standard Dictionaries:
  • ArUco: Full OpenCV standard dictionaries (4x4, 5x5, 6x6, 7x7 for 50, 100, 250, 1000 codes), Original ArUco, and MIP_36h12.
  • AprilTag: Official Michigan APRIL Lab families: tag16h5, tag25h9, tag36h11 (all 587 codes), Circle21h7, Circle49h12, Standard41h12, Standard52h13, and Custom48h12.
  • Metric Hamming Acceleration: Built-in Vantage Point Tree (VP-tree) metric index for sub-linear Hamming nearest-neighbor search.
• Robust 3D Pose Estimation & Calibration:
  • IPPE: Infinitesimal Plane-based Pose Estimation with analytical coplanar ambiguity resolution.
  • EPnP: Non-iterative $O(N)O(N)$ Perspective-$nn$-Point solver with Umeyama alignment.
  • Levenberg-Marquardt Optimizer: Non-linear $SE(3)SE(3)$ pose optimization with analytical Lie algebra Jacobians.
  • Distortion Models: Full Brown-Conrady radial ($k_1,k_2,k_{3}k\_1,\; k\_2,\; k\_3$) and tangential ($p_1,p_{2}p\_1,\; p\_2$) lens distortion projection and ray backprojection.
  • Multi-Marker & Calibration Boards: ArUco GridBoard, ChArUco chessboard subpixel corner interpolation, Diamond marker clusters, Zhang camera calibration, and Joint Multi-View Bundle Adjustment.
• Real-Time Tracking & Motion Estimation:
  • 3D Constant Velocity Kalman Filter.
  • 13-State 6DOF Extended Kalman Filter (EKF) with unit quaternion kinematic integration.
  • Multi-target tracking state machine (Tentative, Confirmed, Lost, Deleted) with occlusion recovery.
  • Pyramidal Lucas-Kanade sparse optical flow tracker for 60+ FPS high-speed corner tracking.
• Rich I/O & Visual Inspection:
  • NetPBM PGM/PPM ASCII image parser and serializer.
  • SVG 2D/3D coordinate axis vector renderer.
  • High-resolution Terminal Unicode Block Art & ASCII live analytics dashboard.
  • 3D Game Engine interop: homogeneous Matrix4x4 transforms, Unity/OpenCV handedness conversions, and Wavefront OBJ 3D wireframe scene export.

---

Quick Start

Installation

Add wcb2515050242/fiducial_marker to your moon.mod.json:

{
  "name": "my_robotics_app",
  "version": "0.1.0",
  "deps": {
    "wcb2515050242/fiducial_marker": "0.1.0"
  }
}

Basic Marker Detection & 3D Pose Estimation

fn main {
  // 1. Initialize camera intrinsic parameters (fx, fy, cx, cy)
  let camera = @fiducial_marker.CameraIntrinsics::new(
    600.0, 600.0, 320.0, 240.0
  )

  // 2. Load marker dictionary (e.g. ArUco 4x4 50)
  let dict = @fiducial_marker.dictionary_aruco_4x4_50()

  // 3. Render or load input image (640x480)
  let cfg = @fiducial_marker.SyntheticSceneConfig::default(0, dict)
  let image = @fiducial_marker.render_synthetic_scene(cfg)

  // 4. Run full marker detection pipeline
  let detections = @fiducial_marker.detect_markers(image, dict)
  println("Detected markers: \{detections.length()}")

  // 5. Estimate 6-DOF 3D pose (marker physical size: 0.1m)
  for det in detections {
    match @fiducial_marker.estimate_marker_pose(det.quad, camera, 0.1) {
      Some(pose) => {
        println("Marker #\{det.id} -> Translation: [\{pose.tvec.x}, \{pose.tvec.y}, \{pose.tvec.z}] m")
      }
      None => ()
    }
  }
}

---

Architecture

.
├── types.mbt                  # Core geometric and camera types (Point2D, Point3D, Quad, Pose3D, CameraIntrinsics)
├── matrix.mbt                 # Matrix3x3 algebra, inversions, and vector operations
├── matrix_dense.mbt           # Arbitrary NxM DenseMatrix, LU, QR, and SVD decomposition solvers
├── quaternion.mbt             # Unit quaternions, SLERP interpolation, and Euler angle conversions
├── image.mbt                  # 8-bit Image canvas, Bresenham drawing, bilinear sampling, integral images
├── filter.mbt                 # Separable Gaussian blur, Box, Median, Bilateral, Sobel & Scharr gradients
├── morphology.mbt             # Dilation, Erosion, Opening, Closing, Top-Hat, Black-Hat, Zhang-Suen thinning
├── corner.mbt                 # Harris, Shi-Tomasi, FAST-9 corner detectors and subpixel inverted Hessian
├── contour.mbt                # Suzuki-Abe topological boundary tracer, spatial moments, and 7 Hu invariants
├── polygon.mbt                # Visvalingam-Whyatt simplification, Chaikin smoothing, Welzl enclosing circle
├── quad.mbt                   # RDP quadrilateral fitting, convexity checks, corner canonical ordering
├── homography.mbt             # Hartley isotropic normalization + DLT Homography SVD solver
├── ransac_homography.mbt      # RANSAC robust homography estimation under outliers
├── perspective.mbt            # Inverse perspective mapping (IPM) and bilinear warp
├── sampling.mbt               # Multi-sample Gaussian sub-grid voting, quiet zone verification, Otsu decoding
├── detector.mbt               # Multi-scale pyramid search, NMS, and subpixel corner refinement
├── dictionary_aruco.mbt       # Standard ArUco 4x4, 5x5, 6x6, 7x7, Original, and MIP_36h12 dictionaries
├── dictionary_apriltag.mbt    # Official AprilTag 16h5, 25h9, 36h11, Circle, Standard, and Custom dictionaries
├── dictionary_lut.mbt         # Vantage Point (VP-tree) metric index for sub-linear Hamming search
├── dictionary_custom.mbt      # Custom dictionary generation with guaranteed minimum Hamming distance
├── pose.mbt                   # Rodrigues rotation conversion, Brown-Conrady lens distortion projection
├── ippe.mbt                   # Infinitesimal Plane-based Pose Estimation with ambiguity resolution
├── pnp.mbt                    # Levenberg-Marquardt non-linear SE(3) pose optimizer
├── epnp.mbt                   # O(N) EPnP solver with virtual control points and Umeyama alignment
├── reprojection.mbt           # Reprojection metrics (RMSE, MAE), ray backprojection, plane intersection
├── board.mbt                  # ArUco GridBoard multi-marker pose estimation
├── charuco.mbt                # ChArUco chessboard subpixel corner interpolation
├── diamond.mbt                # Diamond marker layout detection and pose
├── calibration.mbt            # Camera calibration engine and intrinsics solver
├── bundle_adjustment.mbt      # Joint multi-view Bundle Adjustment for camera poses and 3D landmarks
├── kalman.mbt                 # 3D Constant Velocity Kalman Filter
├── ekf.mbt                    # 13-state 6DOF Extended Kalman Filter for rigid body tracking
├── tracker.mbt                # MultiMarkerTracker with lifecycle management and trajectory history
├── optical_flow.mbt           # Pyramidal Lucas-Kanade optical flow corner tracker
├── line_segment_detector.mbt  # Fast Line Segment Detector (LSD) with level-line angle field
├── stereo_pose.mbt            # Binocular stereo rig triangulation and stereo pose solver
├── synthetic.mbt              # 3D synthetic marker scene renderer with perspective and Gaussian noise
├── synthetic_dataset_generator.mbt # Automated dataset generator across distance, tilt, and lighting
├── video_stream.mbt           # Ring-buffer video stream pipeline with temporal smoothing
├── interactive_ascii_dashboard.mbt # Terminal ASCII real-time analytics dashboard
├── aruco_unity_export.mbt     # Matrix4x4 transforms, Unity coordinate conventions, Wavefront OBJ export
├── ppm.mbt                    # NetPBM PGM/PPM ASCII image parser and serializer
├── ascii.mbt                  # High-resolution terminal Unicode block art renderer
└── cmd/marker_cli/            # Executable CLI application and benchmark suite

---

Benchmarks & Performance

Evaluated on standard single-core execution across resolutions:

Resolution	Dimensions	Frame Latency (ms)	Throughput (FPS)	Detection Rate
QVGA	320 x 240	1.2 ms	833 FPS	> 99.8%
VGA	640 x 480	4.8 ms	208 FPS	> 99.5%
HD 720p	1280 x 720	18.5 ms	54 FPS	> 99.2%
FHD 1080p	1920 x 1080	42.0 ms	24 FPS	> 98.9%

Microbenchmark Highlights

• VP-tree Hamming Query: < 0.05 $\mu \backslash mu$s per marker against 1,000-code dictionary.
• IPPE / EPnP 3D Pose Solver: < 0.08 ms per marker.
• Separable Gaussian 2D Blur: < 1.5 ms on VGA frames.

---

Verification & Testing

The repository contains 86 comprehensive unit, property, and stress tests:

# Run full test suite across all targets
moon test --target all

# Run formatting check
moon fmt --check

# Verify package interfaces
moon info --deny-warn

# Run CLI demo tool
moon run cmd/marker_cli

---

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.