Initial MoonModel implementation

2026-08-11 14:41:33 -07:00
commit 518fe64b13
36 changed files with 2587 additions and 0 deletions
@@ -0,0 +1,40 @@
+# MoonModel
+
+MoonModel creates hollow, terrain-accurate lunar globes as generic, material-aware 3MF files. It supports a one-piece display Moon, an eight-section large Moon, arbitrary named filament colors, nozzle-aware tonal dithering, optional coordinate lines, magnetic-box configuration, and a separate orbital-triskelion stand.
+
+## Setup and use
+
+```sh
+bundle install
+bundle exec ruby bin/moon_model
+```
+
+The executable begins with `require "bundler/setup"`, so all application imports use the locked Bundler environment. To reproduce a run:
+
+```sh
+bundle exec ruby bin/moon_model --config config/example.yml --output build/example
+```
+
+The wizard first asks for a model name, then asks about the printer/tooling envelope, intended use, palette, grid, size or scale, vertical exaggeration, and assembly hardware. Named models are written to `build/<name>/`. Selecting an existing generated name offers to revise it, using its saved configuration as the defaults for a fresh wizard run. It displays maximum one-piece/eight-section sizes in millimeters and inches and a terrain-relief cheat sheet before generation.
+
+## Output
+
+One-piece runs create `moon.3mf`. Segmented runs create eight print files, an assembled preview, and an assembly-key file. The optional one-piece, support-free orbital stand is emitted as `orbital_triskelion_stand.3mf` without a material assignment; its footprint scales with the Moon and is capped to the usable printer bed. Its saddles use conservative terrain-radius bounds so the Moon can be rotated freely while retaining a configurable 10 mm default clearance above the central hub. Every run includes its reusable YAML configuration, a slicer/spool manifest, and assembly instructions. Revisions are generated in a temporary directory and atomically replace the prior generated directory only after successful validation; unrelated directories are never overwritten. `--output DIR` continues to override the named default location.
+
+Colors are closed surface inlay volumes over a continuous structural shell. Palette entry order defines filament slots 1 through N. The 3MF records portable material names/display colors and Bambu Studio part names/slot assignments; confirm the numbered slots against physical AMS or external-spool filaments. The structural shell and first-color surface remain separate bodies assigned to the same filament 1, so an N-color Moon may show N+1 bodies. The file has no fixed palette limit, though the printer and filament system will impose practical limits.
+
+## Modeling notes
+
+- The first palette entry is the structural material.
+- Reflectance is mapped across the palette by perceptual luminance and deterministic spatial dithering.
+- Grid lines override reflectance. They are contrasting inlays for multicolor output and debossed for one-color output.
+- A requested final-envelope diameter is rescaled after exaggeration so it fits. Datum/scale mode preserves the lunar datum diameter and reports the larger resulting envelope.
+- One-piece spherical prints require slicer-generated adhesion/support. Section files are moved above the build plane but may still need slicer-specific support decisions.
+
+See [data/SOURCES.md](data/SOURCES.md) for data provenance and [ROADMAP.md](ROADMAP.md) for milestones and acceptance gates.
+
+Developer visual QA renders front, back, left, right, top, bottom, and isometric views:
+
+```sh
+blender --background --python script/render_previews.py -- build/example/moon.3mf build/example/previews
+```