geometry3d

v0.5.0 - GSAP SVG Animation Backend

geometry3d is a small MoonBit 3D geometry foundation built on Luna-Flow/linear-algebra. It is intentionally not a full 3D engine: the goal is to show how the Luna-Flow math base can quickly support reliable geometry, view, frontend, and backend packages.

Luna-Flow/linear-algebra
  -> geometry3d core
  -> geometry3d view
  -> geometry3d frontend
  -> backend/tui
  -> backend/canvas
  -> backend/gsap
  -> demo

Packages

• Luna-Flow/geometry3d/core: meshes, quad faces, vector helpers, face normals, backface visibility, and 4x4 TRS transforms.
• Luna-Flow/geometry3d/view: camera, scientific sensor/lens model, viewport, perspective and orthographic projection, plus perspective-correct depth interpolation.
• Luna-Flow/geometry3d/frontend: Scene, RenderView, and backend-neutral DrawList, directional-light shadow mapping, LumaBuffer, exposure settings, and demo-grade optical flow.
• Luna-Flow/geometry3d/backend/tui: character frame buffer, Z-buffer, shade ramp, background patterns, terminal y-axis correction, and perspective-correct triangle rasterization.
• Luna-Flow/geometry3d/backend/canvas: browser Canvas 2D rendering backed by the frontend software Z-buffer, quantized RGB shading, and merged scanline runs.
• Luna-Flow/geometry3d/backend/gsap: JS-only SVG polygon rendering with painter-order depth sorting and a GSAP timeline playback controller.
• Luna-Flow/geometry3d/demo: ANSI terminal showcase for cube, torus, and Hitchcock scenes.

The core and frontend packages do not know about terminal characters, ANSI output, backgrounds, or terminal aspect ratio correction.

Documentation

This repository follows the same documentation shape used by Luna-Flow/linear-algebra: localized docs under doc/, a documentation standard, and subsystem pages for API, tutorial, and design notes.

• English: doc/en_US
• 简体中文: doc/zh_CN
• 日本語: doc/ja_JP

Subsystem entry points:

• Core: API, Tutorial, Design
• View: API, Tutorial, Design
• Frontend: API, Tutorial, Design
• Backend TUI: API, Tutorial, Design
• Backend Canvas: API, Tutorial, Design
• Backend GSAP: API, Tutorial, Design
• Demo: API, Tutorial, Design

Background Patterns

Backgrounds are pure functions:

fn dotted_background(x : Int, y : Int, width : Int, height : Int) -> Char

FrameBuffer::new receives a pattern function and uses it to initialize every cell. The demo defaults to dotted_background, and blank_background is also provided for tests or alternate renderers.

Run

just torus

The default just entry points auto-detect terminal dimensions with stty and tput, then pass LINES and COLUMNS to the demo runner. just torus renders a rotating torus with dotted background, Z-buffering, backface culling, directional lighting and shadows, and terminal y-scale correction.

To render a multi-object Hitchcock/dolly zoom scene:

just hitchcock

The default and Hitchcock demos now derive perspective scale from ScientificCamera sensor/lens parameters.

You can still invoke the raw demo entry directly when needed:

moon run src/demo --target native -- --torus
moon run src/demo --target native -- --hitchcock

To build and serve the browser Canvas demos:

just canvas-serve

Then open http://localhost:8080. The Canvas backend is JS-only and uses moonbit-community/rabbita/dom, the maintained successor to the DOM package used by MoonBit's official browser examples. Use the page selector to switch between the rotating torus and the scientific-camera Dolly zoom scene.

To build and serve the GSAP-driven SVG demo:

just gsap-serve

Open http://localhost:8081. The demo loads GSAP 3.13.0 from jsDelivr and provides play, pause, reverse, restart, seek, speed, loop, and scene controls. The backend emits reusable SVG polygons ordered from far to near. Intersecting triangles use painter-order approximation instead of a per-pixel Z-buffer.

To record a playable TUI sequence and play it back:

just record

The .tui3d sequence is a simple text format containing width, height, fps, and rendered character frames. Timeline sampling lives in the frontend package; file IO and playback live only in the demo runner.

Any .tui3d sequence can be converted to H.264 MP4 or ProRes MOV with the generic video export tool. See tools/README.md for recording, conversion, aspect-ratio, dependency, and Dolly demo examples.

To export a static TUI image and show it later:

just export-image
just show-image

The .tuiimg format is the single-frame counterpart to .tui3d: width, height, and one rendered character frame.

Test

moon test
bash ./run_test.sh

The tests cover mesh construction, TRS transforms, camera/view/projection, backend-neutral draw lists, scientific camera scale/FOV, shutter sample counts, luma buffers, optical-flow accumulation, terminal y-scale, background patterns, timeline sampling, TUI sequence/image encode/decode, frame buffer initialization, Z-buffer behavior, and foreground rendering without relying on full character-art snapshots. Canvas tests cover color quantization, scanline merging, zero-luma foregrounds, and depth ordering. GSAP SVG tests cover config normalization, polygon serialization, color quantization, and stable painter ordering. Torus tests also enforce outward face winding so backface culling cannot regress to displaying the inner wall.

run_test.sh mirrors the publish workflow and runs the test suite across wasm-gc, js, native, and wasm targets.

Publish

Publishing is handled by .github/workflows/publish.yml, matching the linear-algebra manual workflow:

1. Install MoonBit.
2. Read moon.mod version.
3. Run moon update.
4. Run moon check --target all.
5. Run bash ./run_test.sh.
6. Publish with moon publish using the LUNA_MOONCAKE repository secret.