# MoonBit Generative Patterns

MoonBit Generative Patterns is a dependency-light toolkit for building procedural artwork and geometric design systems. It targets poster, packaging, cultural-product, preview, and SVG-based workflows where deterministic geometry, reusable motifs, and portable export are more useful than a heavyweight rendering framework.

## Project positioning

The library provides a composable geometry and pattern-generation layer. It focuses on deterministic data generation and standard output formats, so the same design recipe can be used from a MoonBit application, a command-line workflow, or a WebAssembly integration.

The core package is `hmyhmyhmyss/generative_patterns` and depends only on `moonbitlang/core/math`.

## Core capabilities

- **Geometry** — affine matrices, inverse/decomposition, vectors, bounds, polygon metrics, clipping, convex hulls, curve sampling, and rectangle fitting.
- **Paths and shapes** — SVG path construction, Bezier curves, circles, stars, flowers, rounded rectangles, capsules, arrows, gears, spirals, and polylines.
- **Layouts and symmetry** — rectangular, hexagonal, triangular, radial, normalized, and jittered grids; adjacency; packing; cyclic, dihedral, and wallpaper groups.
- **Procedural fields** — deterministic random streams, value/fractal noise, turbulence, domain warping, flow fields, scalar fields, contours, and sampling modes.
- **Color and composition** — RGBA/HSL/HSV colors, contrast helpers, palettes, gradients, layers, motifs, transforms, shadows, glow effects, and scene recipes.
- **Production tooling** — L-system turtle rendering, triangle meshes, raster previews, responsive constraints, SVG asset bundles, batch export plans, visual quality metrics, and reproducible benchmark APIs.

## Quick start

Install the package through MoonBit's package workflow, or use the repository directly:

```bash
moon check --target all
moon test --target wasm-gc
moon run cmd/main
```

Build a deterministic SVG scene from the library:

```mbt check
test {
  let recipe = @generative_patterns.SceneRecipe::new(
    2026U,
    800.0,
    800.0,
    12,
    12,
    @generative_patterns.ocean_palette(),
  )
  let svg = recipe.build().render().to_svg_string()
  assert_true(svg.contains("<svg"))
  assert_true(svg.length() > 1000)
}
```

For lower-level construction, combine `Path`, `Grid`, `Matrix2D`, `Color`, `Palette`, `NoiseSampler`, `Motif`, and `SvgDocument` directly. Public APIs are summarized in the generated [`pkg.generated.mbti`](pkg.generated.mbti).

## CLI

The showcase under [`cmd/main`](cmd/main) generates three representative workflows:

- a rectangular-grid poster with dihedral symmetry;
- a p4m wallpaper composition;
- a noise-warped organic pattern.

Run it with:

```bash
moon run cmd/main
```

The CLI prints generated SVG sizes and a deterministic benchmark record for scene rendering, noise sampling, and the export pipeline. Applications that need the SVG string directly should call `SvgDocument::to_svg_string()` or `DesignDocument::to_svg()`; applications that need a reproducible multi-format bundle can use `PatternPipeline::artifacts()`.

## Architecture

The root package is organized around small, composable modules:

```text
root package
├── geometry / matrix / polygon_ops   geometric primitives and transforms
├── path / curve / shape_library      paths, curves, and reusable shapes
├── sampling / path_sampling           arc-length measurement and resampling
├── grid / grid_variants / layout     placement and spatial organization
├── layout_engine / tiling_engine      production layout and seamless tiling
├── noise / noise_advanced / field    procedural scalar and vector fields
├── field_sampling_plus                field statistics, resampling, and reports
├── color / palette / gradients       color models and interpolation
├── color_system                       semantic themes and contrast audits
├── color_analysis                     perceptual color and accessibility audits
├── composition / scene / motif_graph design composition and export models
├── export_pipeline                    multi-format artifact generation
├── svg / svg_advanced / svg_filters  SVG serialization and effects
├── raster_ops / raster_compositor     preview filters and layered raster output
├── mesh_refinement / graph_layout     mesh and motif graph analysis
├── animation_timeline                 deterministic animation sampling
├── responsive_layout_plus              breakpoint-aware layout constraints
├── svg_asset_pipeline                  asset bundles, sprites, and manifests
├── design_quality / scene_validation   production quality gates and diagnostics
└── cmd/main                          runnable showcase
```

Most APIs are pure data transformations with explicit deterministic seeds. This keeps generation reproducible and makes the library suitable for testing, caching, and WebAssembly integration.

## Benchmark

The benchmark API includes `benchmark_scene`, `benchmark_noise`, `benchmark_pipeline`, and `benchmark_production_suite`. Each uses fixed seeds and emits checksums so output changes can be detected across toolchains. The current local measurement, workload definition, and reproduction instructions are recorded in [`BENCHMARKS.md`](BENCHMARKS.md).

Benchmarks are intended for relative comparisons on the same machine and toolchain; the recorded timings are not a cross-machine performance guarantee.

## Testing

Run the main validation commands locally:

```bash
moon fmt --check
moon info
moon check --target all --deny-warn
moon test --target wasm-gc --deny-warn
moon test --target native --deny-warn
```

The test suite covers geometry, path construction, grids, symmetry, noise determinism, color conversion, field sampling, composition, export, boundary cases, and parameterized regression cases.

## CI

GitHub Actions validates the project on Linux, macOS, and Windows. The workflows install the latest stable MoonBit toolchain and run formatting, all-target checking, interface regeneration checks, wasm-gc/native tests, and coverage checks where applicable.

## License

Apache-2.0. See [`LICENSE`](LICENSE).