MoonBit Vector Trace Planner (moonbit-vector-trace-plan)

moonbit-vector-trace-plan is a high-performance, pure MoonBit bitmap-to-vector path tracing and planning library. It processes pixel-based grid images, clusters colors into layers, traces boundary contours, simplifies curves, and produces structured vector path intermediate representations (IR) ready for SVG serialization or target machine path planning.

This project is built for the MoonBit Hackathon 2026 to demonstrate robust algorithm design, standard-compliant package structure, and complete test coverage using MoonBit v0.10.3.

Project Structure

The project is split into several modular packages:

• lib/core: Defines the foundational data models and serialization helpers.
  • Point: Represents a 2D coordinate (x, y).
  • Image: Represents the input bitmap grid with width, height, and color pixels.
  • PathSegment: Vector path segment enum supporting MoveTo, LineTo, QuadTo (quadratic Bezier), CubicTo (cubic Bezier), and ClosePath.
  • Path: Encapsulates a series of segments.
  • ColorLayer: Holds a list of vector paths mapped to a specific ARGB color value.
  • VectorManifest: The final container holding canvas size and all color layers.
  • SVG & JSON Serialization: Converts paths into standard SVG path instructions (d="...") or XML files.
• lib/trace: Implements image contour detection.
  • image_extract_mask: Extracts binary masks for specific color layers.
  • image_unique_colors: Detects all unique colors in an image.
  • trace_contour: Moore-Neighbor boundary tracing algorithm implementation for pixel-perfect loop extraction.
  • plan_trace: The primary orchestration function linking mask extraction, contour tracing, path simplification, and vector path generation.
• lib/simplify: Implements curve simplification.
  • rdp: The Ramer-Douglas-Peucker (RDP) algorithm implementation for polygon vertex reduction using a configurable distance threshold epsilon.
• cmd/main: Command-line demonstration showing the tracer in action with a mock multi-color bitmap grid, printing the resulting SVG path XML.

Key Algorithms

1. Moore-Neighbor Tracing

The library extracts contours using the Moore-Neighbor tracing algorithm guided by Jacob’s stopping criterion. This allows the tracer to track exact boundaries of arbitrary shapes inside a binary grid. It supports complex region configurations, including thin borders and isolated single-pixel segments.

2. Ramer-Douglas-Peucker (RDP) Simplification

Contours traced directly from pixels are jagged and blocky. The RDP algorithm recursively reduces the number of points by calculating the perpendicular distance of vertices from line segments. It simplifies curves when the deviation is below a threshold epsilon, turning pixelated steps into smooth vector lines.

Getting Started

Prerequisites

Ensure you have the latest MoonBit toolchain installed (v0.10.3 or higher is recommended). Verify your toolchain version with:

moon version --all

Installation

Clone the repository to your local machine:

git clone https://github.com/zgfzgf899/moonbit-vector-trace-plan.git
cd moonbit-vector-trace-plan

Type Checking & Formatting

To verify the code is type-safe and formatted correctly:

moon check --deny-warn
moon fmt

Running Tests

To run all tests inside the core, trace, and simplify packages:

moon test

Running the Demo

To compile and run the CLI demonstration:

moon run cmd/main

The demo will print the structured color layers found in a mock 10x10 grid along with the generated SVG output:

<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 10 10" width="10" height="10">
  <path d="M 2.5 2.5 L 5.5 2.5 L 5.5 5.5 L 2.5 5.5 L 2.5 3.5 Z" fill="#ff0000" stroke="#ff0000" stroke-width="0.5" />
  <path d="M 6.5 6.5 L 8.5 6.5 L 8.5 8.5 L 6.5 8.5 L 6.5 7.5 Z" fill="#00ff00" stroke="#00ff00" stroke-width="0.5" />
</svg>

License

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