From fdb2d0bba8122ffb512752a5360b8eea39471c68 Mon Sep 17 00:00:00 2001 From: Gabriel Kaszewski Date: Mon, 23 Mar 2026 02:11:01 +0100 Subject: [PATCH] docs: add png image exporter design spec --- .../2026-03-23-png-image-exporter-design.md | 130 ++++++++++++++++++ 1 file changed, 130 insertions(+) create mode 100644 docs/superpowers/specs/2026-03-23-png-image-exporter-design.md diff --git a/docs/superpowers/specs/2026-03-23-png-image-exporter-design.md b/docs/superpowers/specs/2026-03-23-png-image-exporter-design.md new file mode 100644 index 0000000..55f0f61 --- /dev/null +++ b/docs/superpowers/specs/2026-03-23-png-image-exporter-design.md @@ -0,0 +1,130 @@ +# PNG Image Exporter — Design Spec + +**Date:** 2026-03-23 +**Status:** Approved + +## Problem + +Users generating Minecraft text structures need a visual reference showing which blocks to place and where. Current exporters (mcfunction, litematica) produce machine-readable files; there is no human-readable image guide. + +## Solution + +Add a `"png"` format to the exporter registry. The output is a PNG image with a color-coded grid — one cell per block position — plus a legend mapping colors to Minecraft block names. + +## Visual Design + +### Cell style +- Each cell: `cell_size × cell_size` pixels with 1px gaps between cells (gaps act as grid lines) +- Filled cells show a letter code in the center (B = Body, O = Outline, S = Shadow) +- Empty/air positions: dark background color, no letter + +### Colors +| VoxelType | Color | Hex | Letter | +|-----------|-----------|-----------|--------| +| Body | Blue | `#4a90d9` | B | +| Outline | Gray | `#888888` | O | +| Shadow | Tan/gold | `#c0a060` | S | +| Empty | Dark | `#222222` | — | +| Background| Dark | `#222222` | — | + +### Depth handling +All z-layers are stacked vertically in one PNG. Each layer has a "Layer N" header row above its grid. + +### Legend +Below all layers: one row per active VoxelType showing a color swatch, the letter code, and the full Minecraft block name (e.g. `B minecraft:stone`). + +## CLI Interface + +New flag added to `crates/bin`: + +``` +--cell-size Cell size in pixels for PNG export (16 or 32) [default: 16] +``` + +The `--format png` flag selects the image exporter. `--format all` includes PNG at 16px (default). + +## Architecture + +### New file: `crates/exporters/src/image_export.rs` + +```rust +pub struct PngExporter { + palette: BlockPalette, + cell_size: u32, +} + +impl PngExporter { + pub fn new(palette: &BlockPalette, cell_size: u32) -> Self +} + +impl StructureExporter for PngExporter { + fn export(&self, grid: &VoxelGrid) -> anyhow::Result>; + fn file_extension(&self) -> &'static str; // "png" +} +``` + +Private helpers: +- `image_dimensions(grid, cell_size) -> (u32, u32)` — pure dimension calculation +- `draw_cell(img, px, py, cell_size, color)` — fill a rectangle +- `draw_letter(img, px, py, cell_size, ch, color)` — render one char from embedded bitmap font +- `draw_layer_label(img, y, z_index, cell_size)` — "Layer N" header row +- `draw_text_row(img, x, y, text, cell_size)` — render a text string +- `draw_legend(img, y_start, palette, cell_size)` — legend section + +### Text rendering +Letters are rendered using an embedded 5×7 bitmap font (`const FONT_5X7: [[u8; 7]; 128]`). Each font pixel is scaled by `cell_size / 8` (so 2× at 16px, 4× at 32px). No external font files or font-rendering crates required. + +### Registry integration + +`crates/exporters/src/lib.rs` changes: +- Register `("png", |p| Box::new(PngExporter::new(p, 16)))` — enables `--format all` +- Add `pub fn build_png(palette: &BlockPalette, cell_size: u32) -> Box` — used by CLI for user-specified cell size + +The generic `ExporterFactory = fn(&BlockPalette) -> Box` signature is unchanged. No changes to `McFunctionExporter` or `LitematicaExporter`. + +### CLI dispatch (`crates/bin/src/cli.rs`) + +When `"png"` appears in `format_names`, the CLI calls `exporters::build_png(&palette, cli.cell_size)` directly (to honour `--cell-size`) rather than the generic registry path. + +### Image layout (per-pixel coordinates) + +``` +gap = 1 + +layer_block_height = (cell_size + 4) + gap + height * (cell_size + gap) - gap +total_grid_height = depth * layer_block_height + (depth - 1) * gap +img_width = gap + width * (cell_size + gap) +img_height = total_grid_height + gap + legend_height +``` + +Row y=0 in `VoxelGrid` is the bottom row; the image renders row `height-1-y` from the top so text reads naturally top-to-bottom. + +## Dependencies + +Only `crates/exporters/Cargo.toml` gains a new dependency: + +```toml +image = { version = "0.25", default-features = false, features = ["png"] } +``` + +No changes to `crates/lib` or `crates/bin` dependencies. + +## Tests + +All in `crates/exporters/src/image_export.rs`: + +1. `dimensions_single_layer` — formula correct for 1 layer +2. `dimensions_multi_layer` — height increases per additional layer +3. `export_produces_valid_png` — output starts with PNG magic bytes `[137, 80, 78, 71, ...]` +4. `export_empty_grid_no_panic` — all-air grid produces valid output +5. `export_multi_layer_larger_than_single` — 3-layer > 1-layer byte count +6. `letter_for_each_voxel_type` — B/O/S mapping is correct + +## Verification + +```bash +cargo build +cargo test -p exporters +cargo run -- --text "Hi" --font /path/to/font.ttf --format png --cell-size 32 --out test_out +# Verify: test_out.png is a valid image showing the block grid + legend +```