#Millow

Millow — M (for MoonBit) + illow (a nod to Python's Pillow).

#Demo

moon run cmd/main

cd examples
moon run .

#Features

• Core image type — Image with construction, pixel access, cloning, channel split/merge, and sub-images.
• Color — grayscale (flat & weighted), invert, tint, BGR, alpha flatten, HSV/YCbCr conversions, LUT application, and over compositing.
• Geometry — crop, flips, 90/180/270 rotation, arbitrary rotation, translation, affine transform, shear, resize (nearest / bilinear / bicubic), rescale, fit/cover, thumbnails, and padding.
• Enhancement — brightness, contrast, gamma, normalize, auto-contrast, standardize, sharpen, and unsharp mask.
• Threshold & histogram — fixed threshold, Otsu, Sauvola, histogram (gray & color), equalization, CLAHE, and histogram matching.
• Filters & edges — convolution, box/Gaussian blur, median/min/max, bilateral filter, Sobel, Scharr, Prewitt, Laplacian, and Canny.
• Morphology — erode, dilate, open, close, gradient, top-hat, black-hat, skeletonize, and hit-or-miss.
• Feature detection — LBP, HOG, Harris corner, and Shi-Tomasi corner.
• Measurement — connected components, find contours, moments, Hu moments, region properties, and pixel counting.
• Data augmentation — random crop, flip, rotate, brightness/contrast/gamma adjustment, Gaussian/salt-pepper noise, color jitter, composable pipelines with weighted random choice.
• Metrics — MSE, PSNR, SSIM.
• Drawing — pixels, lines, rectangles, circles, ellipses, polygons, and flood fill.
• I/O — PPM/PGM serialization plus a pluggable Encoder/Decoder registry.

#Project layout

millow/
├── src/              # implementation package (megemini/millow/src)
├── millow.mbt        # root facade: re-exports the public API (megemini/millow)
├── test/             # blackbox test package exercising the public API
├── test_alignment/   # alignment tests against Python (skimage/Pillow) reference
├── cmd/main/         # lightweight synthetic-image demo (millow-only)
└── examples/         # standalone full demo (PNG/JPEG I/O via mizchi/image)

#Installation

moon add megemini/millow

import {
  "megemini/millow" @millow,
}

#Quick start

///|
test "build, transform and inspect an image" {
  // A 64×64 canvas with a filled rectangle drawn on it.
  let base = Image::from_pixel(64, 64, 30, 60, 90, 255)
  let canvas = draw_rect(base, 8, 8, 40, 40, 220, 40, 40, 255, true, 1)

  // Grayscale → blur → edges.
  let gray = to_grayscale(canvas)
  let blurred = gaussian_blur(gray, 1.5)
  let edges = sobel(blurred)
  assert_eq(edges.shape(), (64, 64))

  // Otsu adaptive threshold.
  let (_, binary) = threshold_otsu(blurred)
  assert_eq(binary.shape(), (64, 64))

  // Downscale and serialize to PPM.
  let thumb = resize(canvas, 16, 16, Nearest)
  let ppm = to_ppm(thumb)
  assert_eq(ppm[0], 'P'.to_int().to_byte())
}

In the examples above the API is called unqualified because they run inside the millow package itself. From another module, prefix each name with the import alias, e.g. @millow.to_grayscale(img).

#Augmentation pipeline

///|
test "augment_pipeline example" {
  let img = Image::from_pixel(64, 64, 30, 60, 90, 255)
  let out = augment_pipeline(img, [
    FlipHorizontal,
    Rotate(15.0),
    Brightness(1.2),
    Contrast(1.3),
    NoiseGaussian(8.0),
  ])
  assert_true(out.h > 0 && out.w > 0)
}

///|
test "augment_random_choice example" {
  let img = Image::from_pixel(64, 64, 30, 60, 90, 255)
  let out = augment_random_choice(img, [
    (0.4, FlipVertical),
    (0.4, Gamma(0.8)),
    (0.2, ColorJitter(0.2, 0.2, 0.0, 0.0)),
  ])
  assert_eq(out.shape(), img.shape())
}

#API notes

#Coordinate system

• Dimension order: (h, w) — height first, width second. Image::new(h, w), resize(img, dst_h, dst_w, interp), crop(img, y, x, h, w), Image::shape() -> (h, w).

• Coordinate order: (y, x) — row first, column second. y is the vertical axis (increases downward), x is the horizontal axis (increases rightward). The origin (0, 0) is the top-left corner.

• Drawing centers: draw_circle(img, cy, cx, radius, ...), draw_ellipse(img, cy, cx, ry, rx, ...).

• Translation: translate(img, dy, dx, interp).

• Contours: find_contours returns (y, x) tuples.

#Brightness adjustment

• factor = 1.0 returns the original image
• factor = 0.0 returns a black image
• Values greater than 1.0 brighten the image
• Values less than 1.0 darken the image

#Contrast adjustment

• factor = 1.0 returns the original image
• factor = 0.0 returns a solid gray image equal to the image's mean
• Values greater than 1.0 increase contrast
• Values less than 1.0 decrease contrast

#Alpha compositing

#Border handling

• Replicate — extends the nearest edge pixel outward
• Reflect — mirrors pixels across the edge
• Wrap — tiles the image periodically
• Constant(r, g, b, a) — fills border regions with a constant color

#Bilateral filter

• d is the diameter of the pixel neighborhood (use 0 to auto-compute based on sigma_space)
• sigma_color controls how similar colors must be to influence each other (larger = more smoothing)
• sigma_space controls how close pixels must be spatially to influence each other (larger = wider neighborhood)

#Affine transform

x' = a*x + b*y + c
y' = d*x + e*y + f

#Random noise

#Backends

#Testing

moon test                 # run every test
moon test --target native # pick a backend
moon run cmd/main         # run the synthetic demo (no external deps)
cd examples && moon run . # run the full demo with JPEG I/O

#Alignment tests

1. test_alignment/generate_fixtures.py computes expected output bytes for small test images and writes them as Array[Int] literals in fixtures_test.mbt.
2. The MoonBit tests construct Images from those fixtures, run each millow operation, and compare byte-for-byte (exact for integer ops, ±1 tolerance for floating-point rounding).

source $HOME/venv310/bin/activate
python test_alignment/generate_fixtures.py
moon test

#Roadmap

#License