MoonBit-native lightweight image processing and basic computer vision algorithms.

moonbit

image-processing

computer-vision

moon add PingGuoMiaoMiao/MoonVision@0.2.5

Download zip

Author

PingGuoMiaoMiao

Version

0.2.5

License

MIT

Repository

github.com/PingGuoMiaoMiao/MoonVision

Last updated

14 hours ago

Downloads

README

#MoonVision

MoonVision is a MoonBit-native lightweight image processing and basic computer vision library.

#中文安装与验收

请在 Windows PowerShell 里从零按下面步骤验证。MoonVision 已在 moon 0.1.20260803 (c19f78e 2026-08-03) 下验证通过。

安装或更新 MoonBit 工具链：

powershell -NoProfile -ExecutionPolicy Bypass -Command "irm https://cli.moonbitlang.com/install/powershell.ps1 | iex"
moon version

新建一个独立项目并安装 MoonVision：

cd $env:USERPROFILE\Desktop
moon new MoonVisionExternalCheck --user LocalCheck --name MoonVisionExternalCheck
cd MoonVisionExternalCheck
moon add PingGuoMiaoMiao/MoonVision@0.2.5

在 cmd/main/moon.pkg 中导入 MoonVision 包：

import {
  "PingGuoMiaoMiao/MoonVision/image",
  "PingGuoMiaoMiao/MoonVision/ops",
  "PingGuoMiaoMiao/MoonVision/filter",
  "PingGuoMiaoMiao/MoonVision/edge",
  "PingGuoMiaoMiao/MoonVision/components",
  "PingGuoMiaoMiao/MoonVision/export",
}

pkgtype(kind: "executable")

将 cmd/main/main.mbt 替换为最小图像处理链：

fn main {
  let gray = try! @image.gray_from_array(
    4,
    4,
    [
      b'\x00', b'\x00', b'\xff', b'\xff',
      b'\x00', b'\x40', b'\xc0', b'\xff',
      b'\x00', b'\x40', b'\xc0', b'\xff',
      b'\x00', b'\x00', b'\xff', b'\xff',
    ],
  )
  let binary = try! @ops.threshold(gray, 100)
  let blurred = try! @filter.gaussian_blur(gray, radius=1)
  let canny = try! @edge.canny_edges(blurred, 32, 96)
  let components = try! @components.connected_components(binary, min_area=1)
  let png = @export.encode_gray_png(canny)
  println(
    "external-ok width=\{gray.width()}, height=\{gray.height()}, components=\{components.length()}, png_bytes=\{png.length()}"
  )
}

在独立项目中检查并运行：

moon check
moon build
moon run cmd/main

期望输出：

external-ok width=4, height=4, components=1, png_bytes=80

完整的独立验证仓库： https://github.com/PingGuoMiaoMiao/MoonVisionExternalCheck

验证 MoonVision 仓库本身：

cd $env:USERPROFILE\Desktop\MoonVision
moon check -d
moon check --warn-list +73
moon build
moon test
moon fmt --check
moon info
moon run src/demo/object_counting
moon run src/demo/edge_detection
moon run src/demo/document_enhancement

moon test 应输出 Total tests: 86, passed: 86, failed: 0. 三个示例会把结果写入 examples/output/。

#Install And Verify

Follow these steps from a clean Windows PowerShell terminal.

Install or update MoonBit:

powershell -NoProfile -ExecutionPolicy Bypass -Command "irm https://cli.moonbitlang.com/install/powershell.ps1 | iex"
moon version

This repository has been verified with:

moon 0.1.20260803 (c19f78e 2026-08-03)

Use MoonVision from a new MoonBit project:

cd $env:USERPROFILE\Desktop
moon new MoonVisionExternalCheck --user LocalCheck --name MoonVisionExternalCheck
cd MoonVisionExternalCheck
moon add PingGuoMiaoMiao/MoonVision@0.2.5

Import MoonVision packages in cmd/main/moon.pkg:

import {
  "PingGuoMiaoMiao/MoonVision/image",
  "PingGuoMiaoMiao/MoonVision/ops",
  "PingGuoMiaoMiao/MoonVision/filter",
  "PingGuoMiaoMiao/MoonVision/edge",
  "PingGuoMiaoMiao/MoonVision/components",
  "PingGuoMiaoMiao/MoonVision/export",
}

pkgtype(kind: "executable")

Replace cmd/main/main.mbt with this minimal image-processing chain:

fn main {
  let gray = try! @image.gray_from_array(
    4,
    4,
    [
      b'\x00', b'\x00', b'\xff', b'\xff',
      b'\x00', b'\x40', b'\xc0', b'\xff',
      b'\x00', b'\x40', b'\xc0', b'\xff',
      b'\x00', b'\x00', b'\xff', b'\xff',
    ],
  )
  let binary = try! @ops.threshold(gray, 100)
  let blurred = try! @filter.gaussian_blur(gray, radius=1)
  let canny = try! @edge.canny_edges(blurred, 32, 96)
  let components = try! @components.connected_components(binary, min_area=1)
  let png = @export.encode_gray_png(canny)
  println(
    "external-ok width=\{gray.width()}, height=\{gray.height()}, components=\{components.length()}, png_bytes=\{png.length()}"
  )
}

Check and run the external project:

moon check
moon build
moon run cmd/main

Expected run output:

external-ok width=4, height=4, components=1, png_bytes=80

A complete external verification repository is available at https://github.com/PingGuoMiaoMiao/MoonVisionExternalCheck.

Verify this repository itself:

cd $env:USERPROFILE\Desktop\MoonVision
moon check -d
moon check --warn-list +73
moon build
moon test
moon fmt --check
moon info
moon run src/demo/object_counting
moon run src/demo/edge_detection
moon run src/demo/document_enhancement

moon test should report Total tests: 86, passed: 86, failed: 0. The three demo commands write their output files under examples/output/.

The current v2.0 line includes the core lightweight image-processing library:

flat image containers: GrayImage, RgbImage
PNG decode to RgbImage through a vendored adapter layer
basic pixel operations: grayscale, threshold, Otsu threshold, adaptive threshold, invert, brightness, contrast
convolution and neighborhood filters: box blur, gaussian blur, sharpen, median blur
gray-image geometric transforms: nearest-neighbor resize, bilinear resize, horizontal flip, vertical flip, 90-degree rotation
edge detection: Sobel X/Y, gradient magnitude, binary edge extraction, Canny, lightweight Hough line detection
binary morphology: erosion, dilation, open binary, close binary, gradient, top hat, black hat
connected components, contour hierarchy, contour statistics, shape analysis, distance transform, and bounding boxes
histogram analysis: grayscale histogram, cumulative histogram, normalized histogram, histogram equalization
template matching: grayscale sum-of-absolute-differences best match
visual export: PNG bytes, SVG overlays, HTML reports

The v1.5 bacteria-review workflow extends the demo layer with:

a lightweight bacteria probe under src/demo/bacteria_probe
a large-lesion clustering route derived from dark binary candidates
a labeled-review script that rebuilds one native executable and reuses it across a batch
label-level, size-bucket, and review-mode summaries for the current annotated bacteria set

#Module Layout

src/
  image/           GrayImage, RgbImage, pixel access, gray transforms
  ops/             grayscale, threshold, otsu, adaptive threshold, brightness, contrast
  histogram/       grayscale histograms and histogram equalization
  filter/          convolution, box blur, gaussian blur, sharpen, median blur
  edge/            sobel, gradient magnitude, canny, hough lines
  morphology/      binary morphology operators and derived morphology
  components/      connected components, contours, distance transform, and bounding boxes
  match/           grayscale template matching
  export/          PNG encoding, SVG overlays, HTML reports
  demo_support/    demo-only file writing helpers
  demo/            runnable demo packages

#Basic Usage

let rgb = try! @image.rgb(4, 4)
let gray = try! @ops.grayscale(rgb)
let binary = try! @ops.otsu_threshold(gray)
let adaptive = try! @ops.adaptive_threshold_mean(gray, 5, 7)
let denoised = try! @filter.median_blur(gray, radius=1)
let blurred = try! @filter.gaussian_blur(gray, radius=1)
let resized = try! @image.resize_nearest(gray, 8, 8)
let smooth_resized = try! @image.resize_bilinear(gray, 8, 8)
let rotated = try! @image.rotate90_cw(gray)
let equalized = try! @histogram.equalize_histogram(gray)
let edges = try! @edge.gradient_magnitude(blurred)
let canny = try! @edge.canny_edges(blurred, 48, 96)
let lines = try! @edge.hough_lines(canny, vote_threshold=4, max_lines=8)
let blobs = try! @components.connected_components(binary, min_area=4)
let distances = try! @components.distance_transform_manhattan(binary)
let contours = try! @components.find_contours(binary)
let first_kind = @components.contour_kind(contours[0])
let first_parent = @components.contour_parent_index(contours[0])
let simplified = @components.approx_contour(contours[0], 1.0)
let hull = @components.convex_hull(contours[0])
let rect = @components.min_area_rect(contours[0])
let circularity = @components.contour_circularity(contours[0])
let solidity = @components.contour_solidity(contours[0])
let best_match = try! @match.match_template_sad(gray, gray)
ignore(adaptive)
ignore(denoised)
ignore(resized)
ignore(smooth_resized)
ignore(rotated)
ignore(equalized)
ignore(edges)
ignore(canny)
ignore(lines)
ignore(blobs)
ignore(distances)
ignore(contours)
ignore(first_kind)
ignore(first_parent)
ignore(simplified)
ignore(hull)
ignore(rect)
ignore(circularity)
ignore(solidity)
ignore(best_match)

find_contours returns ordered boundary walks for binary foreground regions, along with area, perimeter, bounding-box, outer/hole kind, and optional parent-contour metadata. In v1.3, contours are returned per traced boundary instead of per connected foreground region. In v1.4, the same contour objects feed shape-analysis helpers for approximation, convex hulls, rotated rectangles, and lightweight descriptors.

Export a grayscale image as PNG bytes:

let png = @export.encode_gray_png(binary)
ignore(png)

Build an SVG overlay for detected components:

let overlay = @export.svg_bounding_boxes(
  binary.width(),
  binary.height(),
  blobs,
)
ignore(overlay)

Decode a PNG file into RgbImage bytes first:

let input = try! @image.rgb_from_png_bytes(png_bytes)
ignore(input)

#Demos

Demo input assets live in examples/assets/.

All demo outputs are written to examples/output/.

Object counting:

moon run src/demo/object_counting

Outputs:

examples/output/object_counting_input.png
examples/output/object_counting_binary_v1_0.png
examples/output/object_counting_binary.png
examples/output/object_counting_contours.png
examples/output/object_counting_overlay.svg
examples/output/object_counting_report.html

Edge detection:

moon run src/demo/edge_detection

Outputs:

examples/output/edge_detection_input.png
examples/output/edge_detection_edges.png
examples/output/edge_detection_canny.png
examples/output/edge_detection_report.html

Document enhancement:

moon run src/demo/document_enhancement

Outputs:

examples/output/document_enhancement_input.png
examples/output/document_enhancement_output_v1_0.png
examples/output/document_enhancement_equalized_v2_0.png
examples/output/document_enhancement_output.png
examples/output/document_enhancement_resized_v2_0.png
examples/output/document_enhancement_report.html

Bacteria labeled review:

powershell -NoProfile -ExecutionPolicy Bypass -File tools/run_labeled_bacteria_review.ps1 -ForceRerun

For quick validation during parameter tuning, restrict the run to specific sample folders:

powershell -NoProfile -ExecutionPolicy Bypass -File tools/run_labeled_bacteria_review.ps1 -SampleFolders 346

Exclude duplicated rename folders when checking the original reviewed images:

powershell -NoProfile -ExecutionPolicy Bypass -File tools/run_labeled_bacteria_review.ps1 -SampleFolders 346 -ExcludeRenameCopies

Or cap the number of reviewed images:

powershell -NoProfile -ExecutionPolicy Bypass -File tools/run_labeled_bacteria_review.ps1 -MaxImages 3

Outputs:

examples/output/bacteria_labeled_review/index.html
examples/output/bacteria_labeled_review/summary_readable.csv
examples/output/bacteria_labeled_review/review_focus.csv
examples/output/bacteria_labeled_review/param_summary.csv
examples/output/bacteria_labeled_review/review_category_summary.csv
examples/output/bacteria_labeled_review/mode_summary.csv
examples/output/bacteria_labeled_review/label_summary.csv
examples/output/bacteria_labeled_review/size_summary.csv

The v1.5 review report includes the default F1-oriented result, a recall-oriented parameter set, and a precision-oriented parameter set for each image. The review dashboard also writes direct tuning views: review_focus.csv groups each image into clean-match, under-detected, over-detected, or mixed miss/noise buckets; param_summary.csv ranks probe presets across the selected image set; review_category_summary.csv summarizes where the current detector still needs tuning.

#Version Stages

v1.0 Focused on the first complete visual-analysis chain: image containers, thresholding, filtering, Sobel edges, binary morphology, connected components, and export.
v1.1 Focused on robustness improvements: Otsu thresholding, adaptive thresholding, median blur, and gray-image transforms.
v1.2 Focuses on edge and contour analysis: Canny edges, contour extraction, contour statistics, and upgraded edge/counting demos.
v1.3 Refines contour semantics into outer/hole-aware hierarchy output, with deterministic parent-child relationships for nested structures.
v1.4 Extends the contour layer into lightweight shape analysis with contour approximation, convex hull extraction, minimum-area rotated rectangles, and descriptor helpers.
v1.5 Focuses on the labeled bacteria-review path: high-recall probe routes, native executable reuse during batch review, quick sample filtering, and multi-mode reporting by F1, recall, and precision.
v2.0 Expands the lightweight imgproc layer with histograms, histogram equalization, extended morphology, distance transform, Hough line detection, grayscale template matching, and bilinear resize.

#v1.0 vs v1.1 vs v1.2 vs v1.3 vs v1.4 vs v1.5 vs v2.0

The bundled demo assets are kept stable so v1.0, v1.1, v1.2, v1.3, and v1.4 remain directly comparable. v1.5 adds a labeled-review workflow for local annotated bacteria images, so its review metrics depend on the dataset selected by the script's InputRoot parameter. v2.0 expands the reusable algorithm layer while preserving the existing demo commands.

Object counting: v1.0 used threshold(120) and detected 5 objects on the bundled asset. v1.1 uses median_blur(radius=1) -> otsu_threshold and also detects 5 objects, while removing the fixed threshold constant from the counting path. v1.2 keeps the v1.1 binary path and adds ordered contour tracing plus a rendered contour mask for the same binary image. v1.3 keeps the v1.1 binary path, reports outer contours and hole contours separately, and labels the rendered contour mask as hierarchy-aware output. v1.4 keeps the v1.3 hierarchy output and adds shape-summary metrics for contour approximation, convex hulls, rotated rectangles, and solidity-style compactness.
Edge detection: v1.1 exported the Sobel gradient magnitude edge map. v1.2 keeps that output and adds a binary Canny edge map for direct comparison.
Document enhancement: v1.0 used a fixed threshold after brightness and contrast adjustment. v1.1 preserves the v1.0 output in document_enhancement_output_v1_0.png and writes the optimized median_blur -> adaptive_threshold_mean result to document_enhancement_output.png. v2.0 adds document_enhancement_equalized_v2_0.png for histogram-equalized contrast preview and document_enhancement_resized_v2_0.png for bilinear-resized output.
Bacteria labeled review: v1.5 keeps all core library APIs unchanged and extends the demo layer with batch review, per-preset scoring, best-alignment overlays, label and size summaries, and mode-level comparison across F1-oriented, recall-oriented, and precision-oriented selections. v2.0 does not change the bacteria-review semantics; it keeps that workflow focused on reporting and validation.

#v1.5 Review Validation

Quick script validation without a full batch run:

powershell -NoProfile -ExecutionPolicy Bypass -File tools/run_labeled_bacteria_review.ps1 -SampleFolders 346

Original-image-only validation:

powershell -NoProfile -ExecutionPolicy Bypass -File tools/run_labeled_bacteria_review.ps1 -SampleFolders 346 -ExcludeRenameCopies

Small smoke run:

powershell -NoProfile -ExecutionPolicy Bypass -File tools/run_labeled_bacteria_review.ps1 -MaxImages 3

Full labeled review:

powershell -NoProfile -ExecutionPolicy Bypass -File tools/run_labeled_bacteria_review.ps1 -ForceRerun

Use mode_summary.csv for the shortest top-level comparison, review_focus.csv for deciding which images need manual inspection, param_summary.csv for preset-level tuning, summary_readable.csv for per-image details, and each sample's preset_scores.csv for parameter-level debugging.

#Final Verification Checklist

Run the core checks:

moon check -d
moon check --warn-list +73
moon build
moon test
moon fmt --check
moon info

Run the bundled visual demos:

moon run src/demo/object_counting
moon run src/demo/edge_detection
moon run src/demo/document_enhancement

Expected bundled demo reports:

examples/output/object_counting_report.html
examples/output/edge_detection_report.html
examples/output/document_enhancement_report.html

Run the bacteria review workflow against local labeled data:

powershell -NoProfile -ExecutionPolicy Bypass -File tools/run_labeled_bacteria_review.ps1 -SampleFolders 346 -ExcludeRenameCopies

Use -ForceRerun only when regenerating the full labeled review from the source images.

#Testing Scope

Current tests cover:

image container invariants
gray-image geometric transforms
histogram analysis and histogram equalization
PNG decode adaptation to RgbImage
grayscale, global thresholding, Otsu thresholding, and adaptive thresholding
filtering, border handling, and median blur behavior
Sobel and Canny edge behavior
Hough line detection behavior
binary morphology behavior and derived morphology operators
connected components, contour hierarchy, and contour statistics
binary distance transform behavior
contour approximation, convex hulls, rotated rectangles, and shape descriptors
grayscale template matching
SVG/HTML export rendering
PNG signature generation

#Notes

The project intentionally focuses on the algorithm layer. It does not provide GUI features, video processing, OpenCV bindings, or machine learning integration.
PNG decode and export are implemented locally from vendored subsets adapted from mizchi/image and mizchi/zlib, because the current upstream registry dependency graph is not compatible with the local MoonBit toolchain used for this repository.
Third-party vendored attribution and Apache-2.0 license notices are documented in THIRD_PARTY_NOTICES.md.

#License

MoonVision is released under the MIT license. See LICENSE for the full text.

Site source Report issue Packages Build queue Skills Statistics