791 lines
24 KiB
Markdown
791 lines
24 KiB
Markdown
# PNG Image Exporter Implementation Plan
|
||
|
||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
||
|
||
**Goal:** Add `--format png` that generates a color-coded block grid image with B/O/S letter codes in each cell, all z-layers stacked vertically, and a legend mapping colors to block names.
|
||
|
||
**Architecture:** New `PngExporter` in `crates/exporters` implements `StructureExporter`. Renders via `image` crate (`RgbaImage` pixel ops) using an embedded 5×7 bitmap font — no external font files. CLI routes `"png"` through a `build_png(palette, cell_size)` factory to honor `--cell-size`.
|
||
|
||
**Tech Stack:** Rust, `image = "0.25"` (PNG via `RgbaImage`), `clap` (CLI flag)
|
||
|
||
---
|
||
|
||
### Task 1: Scaffold + dependency
|
||
|
||
**Files:**
|
||
- Modify: `crates/exporters/Cargo.toml`
|
||
- Create: `crates/exporters/src/image_export.rs`
|
||
- Modify: `crates/exporters/src/lib.rs`
|
||
- Modify: `crates/lib/src/lib.rs`
|
||
|
||
- [ ] **Step 1: Export `PaletteMappings` from lib**
|
||
|
||
`image_export.rs` needs to inspect `palette.blocks.outline: Option<String>`. Currently `PaletteMappings` is not re-exported. Add to `crates/lib/src/lib.rs`:
|
||
|
||
```rust
|
||
pub use palette::PaletteMappings;
|
||
```
|
||
|
||
- [ ] **Step 2: Add `image` crate**
|
||
|
||
In `crates/exporters/Cargo.toml`, under `[dependencies]`:
|
||
```toml
|
||
image = { version = "0.25", default-features = false, features = ["png"] }
|
||
```
|
||
|
||
- [ ] **Step 3: Create stub module**
|
||
|
||
Create `crates/exporters/src/image_export.rs`:
|
||
```rust
|
||
use lib::{BlockPalette, StructureExporter, VoxelGrid, VoxelType};
|
||
|
||
pub struct PngExporter {
|
||
palette: BlockPalette,
|
||
cell_size: u32,
|
||
}
|
||
|
||
impl PngExporter {
|
||
pub fn new(palette: &BlockPalette, cell_size: u32) -> Self {
|
||
Self { palette: palette.clone(), cell_size }
|
||
}
|
||
}
|
||
|
||
impl StructureExporter for PngExporter {
|
||
fn export(&self, _grid: &VoxelGrid) -> anyhow::Result<Vec<u8>> {
|
||
todo!("png export not yet implemented")
|
||
}
|
||
|
||
fn file_extension(&self) -> &'static str {
|
||
"png"
|
||
}
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 4: Register in `crates/exporters/src/lib.rs`**
|
||
|
||
Add at the top:
|
||
```rust
|
||
mod image_export;
|
||
pub use image_export::PngExporter;
|
||
```
|
||
|
||
Add to `REGISTRY`:
|
||
```rust
|
||
("png", |p| Box::new(PngExporter::new(p, 16))),
|
||
```
|
||
|
||
Add after the `build` function:
|
||
```rust
|
||
pub fn build_png(palette: &BlockPalette, cell_size: u32) -> Box<dyn StructureExporter> {
|
||
Box::new(PngExporter::new(palette, cell_size))
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 5: Verify it compiles**
|
||
|
||
```bash
|
||
cargo check
|
||
```
|
||
Expected: clean (the `todo!()` is fine)
|
||
|
||
- [ ] **Step 6: Commit scaffold**
|
||
|
||
```bash
|
||
git add crates/lib/src/lib.rs crates/exporters/Cargo.toml crates/exporters/src/image_export.rs crates/exporters/src/lib.rs
|
||
git commit -m "feat(exporters): scaffold PngExporter"
|
||
```
|
||
|
||
---
|
||
|
||
### Task 2: Dimension calculation (TDD)
|
||
|
||
**Files:**
|
||
- Modify: `crates/exporters/src/image_export.rs`
|
||
|
||
- [ ] **Step 1: Write failing dimension tests**
|
||
|
||
Add to `image_export.rs`:
|
||
|
||
```rust
|
||
const GAP: u32 = 1;
|
||
|
||
// Returns VoxelTypes that (1) are configured in the palette AND (2) appear in the grid.
|
||
// This matches the spec's definition of "active" for legend entries.
|
||
fn active_voxel_types(palette: &BlockPalette, grid: &VoxelGrid) -> Vec<VoxelType> {
|
||
let mut candidates = vec![VoxelType::Body];
|
||
if palette.blocks.outline.is_some() {
|
||
candidates.push(VoxelType::Outline);
|
||
}
|
||
if palette.blocks.shadow.is_some() {
|
||
candidates.push(VoxelType::Shadow);
|
||
}
|
||
candidates.retain(|&vt| {
|
||
(0..grid.depth).any(|z|
|
||
(0..grid.height).any(|y|
|
||
(0..grid.width).any(|x| grid.get(x, y, z) == Some(vt))
|
||
)
|
||
)
|
||
});
|
||
candidates
|
||
}
|
||
|
||
pub fn image_dimensions(grid: &VoxelGrid, palette: &BlockPalette, cell_size: u32) -> (u32, u32) {
|
||
todo!()
|
||
}
|
||
|
||
#[cfg(test)]
|
||
mod tests {
|
||
use super::*;
|
||
|
||
fn palette_full() -> BlockPalette {
|
||
serde_json::from_str(r#"{
|
||
"name": "test",
|
||
"blocks": {
|
||
"body": "minecraft:stone",
|
||
"outline": "minecraft:cobblestone",
|
||
"shadow": "minecraft:gravel"
|
||
}
|
||
}"#).unwrap()
|
||
}
|
||
|
||
fn palette_body_only() -> BlockPalette {
|
||
serde_json::from_str(r#"{
|
||
"name": "test",
|
||
"blocks": { "body": "minecraft:stone" }
|
||
}"#).unwrap()
|
||
}
|
||
|
||
#[test]
|
||
fn dimensions_single_layer() {
|
||
let grid = VoxelGrid::new(4, 3, 1);
|
||
let palette = palette_full();
|
||
let (w, h) = image_dimensions(&grid, &palette, 16);
|
||
// width: 1 + 4*(16+1) = 69
|
||
assert_eq!(w, 69);
|
||
// label_height = 20, per_layer = 3*17-1 = 50, layer_block = 71
|
||
// total_grid = 71
|
||
// legend = 3*17 + 1 = 52
|
||
// total_h = 71 + 1 + 52 = 124
|
||
assert_eq!(h, 124);
|
||
}
|
||
|
||
#[test]
|
||
fn dimensions_multi_layer() {
|
||
let g1 = VoxelGrid::new(4, 3, 1);
|
||
let g3 = VoxelGrid::new(4, 3, 3);
|
||
let palette = palette_full();
|
||
let (_, h1) = image_dimensions(&g1, &palette, 16);
|
||
let (_, h3) = image_dimensions(&g3, &palette, 16);
|
||
assert!(h3 > h1);
|
||
}
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 2: Run to confirm they fail**
|
||
|
||
```bash
|
||
cargo test -p exporters 2>&1 | head -10
|
||
```
|
||
Expected: `panicked at 'not yet implemented'`
|
||
|
||
- [ ] **Step 3: Implement `image_dimensions`**
|
||
|
||
Replace the `todo!()`:
|
||
```rust
|
||
pub fn image_dimensions(grid: &VoxelGrid, palette: &BlockPalette, cell_size: u32) -> (u32, u32) {
|
||
let label_height = cell_size + 4;
|
||
let per_layer_height = if grid.height == 0 {
|
||
0
|
||
} else {
|
||
grid.height * (cell_size + GAP) - GAP
|
||
};
|
||
let layer_block_height = label_height + GAP + per_layer_height;
|
||
let total_grid_height = grid.depth * layer_block_height
|
||
+ grid.depth.saturating_sub(1) * GAP;
|
||
|
||
let active = active_voxel_types(palette, grid);
|
||
let legend_height = if active.is_empty() {
|
||
0
|
||
} else {
|
||
active.len() as u32 * (cell_size + GAP) + GAP
|
||
};
|
||
|
||
let img_width = if grid.width == 0 {
|
||
1
|
||
} else {
|
||
GAP + grid.width * (cell_size + GAP)
|
||
};
|
||
let img_height = total_grid_height
|
||
+ if legend_height > 0 { GAP + legend_height } else { 0 };
|
||
|
||
(img_width, img_height)
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 4: Run tests**
|
||
|
||
```bash
|
||
cargo test -p exporters dimensions
|
||
```
|
||
Expected: both pass
|
||
|
||
- [ ] **Step 5: Commit**
|
||
|
||
```bash
|
||
git add crates/exporters/src/image_export.rs
|
||
git commit -m "feat(exporters): implement image_dimensions with TDD"
|
||
```
|
||
|
||
---
|
||
|
||
### Task 3: Color constants, font, drawing primitives
|
||
|
||
**Files:**
|
||
- Modify: `crates/exporters/src/image_export.rs`
|
||
|
||
- [ ] **Step 1: Add color constants and helpers**
|
||
|
||
Add near the top of `image_export.rs` (after `use` statements):
|
||
|
||
```rust
|
||
use image::{ImageFormat, Rgba, RgbaImage};
|
||
|
||
const COLOR_BODY: [u8; 4] = [0x4A, 0x90, 0xD9, 0xFF];
|
||
const COLOR_OUTLINE: [u8; 4] = [0x88, 0x88, 0x88, 0xFF];
|
||
const COLOR_SHADOW: [u8; 4] = [0xC0, 0xA0, 0x60, 0xFF];
|
||
const COLOR_BG: [u8; 4] = [0x22, 0x22, 0x22, 0xFF];
|
||
const COLOR_TEXT: [u8; 4] = [0xFF, 0xFF, 0xFF, 0xFF];
|
||
|
||
fn voxel_color(vt: VoxelType) -> [u8; 4] {
|
||
match vt {
|
||
VoxelType::Body => COLOR_BODY,
|
||
VoxelType::Outline => COLOR_OUTLINE,
|
||
VoxelType::Shadow => COLOR_SHADOW,
|
||
}
|
||
}
|
||
|
||
fn voxel_letter(vt: VoxelType) -> char {
|
||
match vt {
|
||
VoxelType::Body => 'B',
|
||
VoxelType::Outline => 'O',
|
||
VoxelType::Shadow => 'S',
|
||
}
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 2: Add `letter_for_each_voxel_type` test and run it**
|
||
|
||
In the test module:
|
||
```rust
|
||
#[test]
|
||
fn letter_for_each_voxel_type() {
|
||
assert_eq!(voxel_letter(VoxelType::Body), 'B');
|
||
assert_eq!(voxel_letter(VoxelType::Outline), 'O');
|
||
assert_eq!(voxel_letter(VoxelType::Shadow), 'S');
|
||
}
|
||
```
|
||
|
||
```bash
|
||
cargo test -p exporters letter_for
|
||
```
|
||
Expected: passes
|
||
|
||
- [ ] **Step 3: Add embedded 5×7 bitmap font**
|
||
|
||
Each `[u8; 7]` entry encodes 7 rows; each `u8` encodes 5 pixels (bit 4 = leftmost col, bit 0 = rightmost). Add to `image_export.rs`:
|
||
|
||
```rust
|
||
/// 5×7 bitmap font indexed by ASCII code. Bit4=left, Bit0=right per row.
|
||
static FONT_5X7: [[u8; 7]; 128] = {
|
||
const __: [u8; 7] = [0; 7];
|
||
[
|
||
// 0-31: control chars (blank)
|
||
__, __, __, __, __, __, __, __, __, __, __, __, __, __, __, __,
|
||
__, __, __, __, __, __, __, __, __, __, __, __, __, __, __, __,
|
||
// 32 ' '
|
||
[0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00],
|
||
// 33 '!'
|
||
[0x04, 0x04, 0x04, 0x04, 0x04, 0x00, 0x04],
|
||
// 34-47: unused (blank)
|
||
__, __, __, __, __, __, __, __, __, __, __, __, __, __,
|
||
// 48 '0'
|
||
[0x0E, 0x11, 0x13, 0x15, 0x19, 0x11, 0x0E],
|
||
// 49 '1'
|
||
[0x04, 0x0C, 0x04, 0x04, 0x04, 0x04, 0x0E],
|
||
// 50 '2'
|
||
[0x0E, 0x11, 0x01, 0x02, 0x04, 0x08, 0x1F],
|
||
// 51 '3'
|
||
[0x0E, 0x11, 0x01, 0x06, 0x01, 0x11, 0x0E],
|
||
// 52 '4'
|
||
[0x02, 0x06, 0x0A, 0x12, 0x1F, 0x02, 0x02],
|
||
// 53 '5'
|
||
[0x1F, 0x10, 0x1E, 0x01, 0x01, 0x11, 0x0E],
|
||
// 54 '6'
|
||
[0x06, 0x08, 0x10, 0x1E, 0x11, 0x11, 0x0E],
|
||
// 55 '7'
|
||
[0x1F, 0x01, 0x02, 0x04, 0x08, 0x08, 0x08],
|
||
// 56 '8'
|
||
[0x0E, 0x11, 0x11, 0x0E, 0x11, 0x11, 0x0E],
|
||
// 57 '9'
|
||
[0x0E, 0x11, 0x11, 0x0F, 0x01, 0x02, 0x0C],
|
||
// 58 ':'
|
||
[0x00, 0x04, 0x04, 0x00, 0x04, 0x04, 0x00],
|
||
// 59-64: blank
|
||
__, __, __, __, __, __,
|
||
// 65 'A'
|
||
[0x04, 0x0A, 0x11, 0x11, 0x1F, 0x11, 0x11],
|
||
// 66 'B'
|
||
[0x1E, 0x11, 0x11, 0x1E, 0x11, 0x11, 0x1E],
|
||
// 67 'C'
|
||
[0x0E, 0x11, 0x10, 0x10, 0x10, 0x11, 0x0E],
|
||
// 68 'D'
|
||
[0x1C, 0x12, 0x11, 0x11, 0x11, 0x12, 0x1C],
|
||
// 69 'E'
|
||
[0x1F, 0x10, 0x10, 0x1E, 0x10, 0x10, 0x1F],
|
||
// 70 'F'
|
||
[0x1F, 0x10, 0x10, 0x1E, 0x10, 0x10, 0x10],
|
||
// 71 'G'
|
||
[0x0E, 0x11, 0x10, 0x17, 0x11, 0x11, 0x0F],
|
||
// 72 'H'
|
||
[0x11, 0x11, 0x11, 0x1F, 0x11, 0x11, 0x11],
|
||
// 73 'I'
|
||
[0x0E, 0x04, 0x04, 0x04, 0x04, 0x04, 0x0E],
|
||
// 74 'J'
|
||
[0x07, 0x02, 0x02, 0x02, 0x02, 0x12, 0x0C],
|
||
// 75 'K'
|
||
[0x11, 0x12, 0x14, 0x18, 0x14, 0x12, 0x11],
|
||
// 76 'L'
|
||
[0x10, 0x10, 0x10, 0x10, 0x10, 0x10, 0x1F],
|
||
// 77 'M'
|
||
[0x11, 0x1B, 0x15, 0x11, 0x11, 0x11, 0x11],
|
||
// 78 'N'
|
||
[0x11, 0x19, 0x15, 0x13, 0x11, 0x11, 0x11],
|
||
// 79 'O'
|
||
[0x0E, 0x11, 0x11, 0x11, 0x11, 0x11, 0x0E],
|
||
// 80 'P'
|
||
[0x1E, 0x11, 0x11, 0x1E, 0x10, 0x10, 0x10],
|
||
// 81 'Q'
|
||
[0x0E, 0x11, 0x11, 0x11, 0x15, 0x12, 0x0D],
|
||
// 82 'R'
|
||
[0x1E, 0x11, 0x11, 0x1E, 0x14, 0x12, 0x11],
|
||
// 83 'S'
|
||
[0x0E, 0x11, 0x10, 0x0E, 0x01, 0x11, 0x0E],
|
||
// 84 'T'
|
||
[0x1F, 0x04, 0x04, 0x04, 0x04, 0x04, 0x04],
|
||
// 85 'U'
|
||
[0x11, 0x11, 0x11, 0x11, 0x11, 0x11, 0x0E],
|
||
// 86 'V'
|
||
[0x11, 0x11, 0x11, 0x11, 0x11, 0x0A, 0x04],
|
||
// 87 'W'
|
||
[0x11, 0x11, 0x11, 0x15, 0x15, 0x1B, 0x11],
|
||
// 88 'X'
|
||
[0x11, 0x11, 0x0A, 0x04, 0x0A, 0x11, 0x11],
|
||
// 89 'Y'
|
||
[0x11, 0x11, 0x0A, 0x04, 0x04, 0x04, 0x04],
|
||
// 90 'Z'
|
||
[0x1F, 0x01, 0x02, 0x04, 0x08, 0x10, 0x1F],
|
||
// 91-94: blank
|
||
__, __, __, __,
|
||
// 95 '_'
|
||
[0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x1F],
|
||
// 96: blank
|
||
__,
|
||
// 97 'a'
|
||
[0x00, 0x00, 0x0E, 0x01, 0x0F, 0x11, 0x0F],
|
||
// 98 'b'
|
||
[0x10, 0x10, 0x1E, 0x11, 0x11, 0x11, 0x1E],
|
||
// 99 'c'
|
||
[0x00, 0x00, 0x0E, 0x10, 0x10, 0x10, 0x0E],
|
||
// 100 'd'
|
||
[0x01, 0x01, 0x0F, 0x11, 0x11, 0x11, 0x0F],
|
||
// 101 'e'
|
||
[0x00, 0x00, 0x0E, 0x11, 0x1F, 0x10, 0x0E],
|
||
// 102 'f'
|
||
[0x06, 0x09, 0x08, 0x1E, 0x08, 0x08, 0x08],
|
||
// 103 'g'
|
||
[0x00, 0x0F, 0x11, 0x11, 0x0F, 0x01, 0x0E],
|
||
// 104 'h'
|
||
[0x10, 0x10, 0x1E, 0x11, 0x11, 0x11, 0x11],
|
||
// 105 'i'
|
||
[0x04, 0x00, 0x0C, 0x04, 0x04, 0x04, 0x0E],
|
||
// 106 'j'
|
||
[0x02, 0x00, 0x06, 0x02, 0x02, 0x12, 0x0C],
|
||
// 107 'k'
|
||
[0x10, 0x10, 0x12, 0x14, 0x18, 0x14, 0x12],
|
||
// 108 'l'
|
||
[0x0C, 0x04, 0x04, 0x04, 0x04, 0x04, 0x0E],
|
||
// 109 'm'
|
||
[0x00, 0x00, 0x1A, 0x15, 0x15, 0x11, 0x11],
|
||
// 110 'n'
|
||
[0x00, 0x00, 0x16, 0x19, 0x11, 0x11, 0x11],
|
||
// 111 'o'
|
||
[0x00, 0x00, 0x0E, 0x11, 0x11, 0x11, 0x0E],
|
||
// 112 'p'
|
||
[0x00, 0x1E, 0x11, 0x11, 0x1E, 0x10, 0x10],
|
||
// 113 'q'
|
||
[0x00, 0x0F, 0x11, 0x11, 0x0F, 0x01, 0x01],
|
||
// 114 'r'
|
||
[0x00, 0x00, 0x16, 0x19, 0x10, 0x10, 0x10],
|
||
// 115 's'
|
||
[0x00, 0x00, 0x0E, 0x10, 0x0E, 0x01, 0x0E],
|
||
// 116 't'
|
||
[0x08, 0x08, 0x1E, 0x08, 0x08, 0x09, 0x06],
|
||
// 117 'u'
|
||
[0x00, 0x00, 0x11, 0x11, 0x11, 0x13, 0x0D],
|
||
// 118 'v'
|
||
[0x00, 0x00, 0x11, 0x11, 0x11, 0x0A, 0x04],
|
||
// 119 'w'
|
||
[0x00, 0x00, 0x11, 0x11, 0x15, 0x15, 0x0A],
|
||
// 120 'x'
|
||
[0x00, 0x00, 0x11, 0x0A, 0x04, 0x0A, 0x11],
|
||
// 121 'y'
|
||
[0x00, 0x11, 0x11, 0x0F, 0x01, 0x11, 0x0E],
|
||
// 122 'z'
|
||
[0x00, 0x00, 0x1F, 0x02, 0x04, 0x08, 0x1F],
|
||
// 123-127: blank
|
||
__, __, __, __, __,
|
||
]
|
||
};
|
||
```
|
||
|
||
- [ ] **Step 4: Add drawing helpers**
|
||
|
||
```rust
|
||
fn draw_rect(img: &mut RgbaImage, x: u32, y: u32, w: u32, h: u32, color: [u8; 4]) {
|
||
let c = Rgba(color);
|
||
for dy in 0..h {
|
||
for dx in 0..w {
|
||
let px = x + dx;
|
||
let py = y + dy;
|
||
if px < img.width() && py < img.height() {
|
||
img.put_pixel(px, py, c);
|
||
}
|
||
}
|
||
}
|
||
}
|
||
|
||
/// Render one char at (x, y). Each font pixel = scale×scale actual pixels.
|
||
fn draw_char(img: &mut RgbaImage, x: u32, y: u32, ch: char, scale: u32, color: [u8; 4]) {
|
||
let code = ch as usize;
|
||
if code >= 128 { return; }
|
||
let glyph = FONT_5X7[code];
|
||
for (row, &bits) in glyph.iter().enumerate() {
|
||
for col in 0..5u32 {
|
||
if bits & (1 << (4 - col)) != 0 {
|
||
draw_rect(img, x + col * scale, y + row as u32 * scale, scale, scale, color);
|
||
}
|
||
}
|
||
}
|
||
}
|
||
|
||
/// Render a string left-to-right. Each char is 6*scale px wide (5px + 1px gap).
|
||
fn draw_text(img: &mut RgbaImage, x: u32, y: u32, text: &str, scale: u32, color: [u8; 4]) {
|
||
let char_w = 6 * scale;
|
||
for (i, ch) in text.chars().enumerate() {
|
||
draw_char(img, x + i as u32 * char_w, y, ch, scale, color);
|
||
}
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 5: Run all tests**
|
||
|
||
```bash
|
||
cargo test -p exporters
|
||
```
|
||
Expected: 3 passing (dimensions ×2, letter_for)
|
||
|
||
- [ ] **Step 6: Commit**
|
||
|
||
```bash
|
||
git add crates/exporters/src/image_export.rs
|
||
git commit -m "feat(exporters): bitmap font, colors, drawing primitives"
|
||
```
|
||
|
||
---
|
||
|
||
### Task 4: Full export implementation (TDD)
|
||
|
||
**Files:**
|
||
- Modify: `crates/exporters/src/image_export.rs`
|
||
|
||
- [ ] **Step 1: Write the 4 export tests**
|
||
|
||
Add to the test module:
|
||
|
||
```rust
|
||
fn make_grid_with_voxels(w: u32, h: u32, d: u32) -> VoxelGrid {
|
||
let mut grid = VoxelGrid::new(w, h, d);
|
||
let _ = grid.set(0, 0, 0, VoxelType::Body);
|
||
let _ = grid.set(1, 0, 0, VoxelType::Outline);
|
||
if d > 1 { let _ = grid.set(0, 0, 1, VoxelType::Body); }
|
||
grid
|
||
}
|
||
|
||
#[test]
|
||
fn export_produces_valid_png() {
|
||
let grid = make_grid_with_voxels(3, 3, 1);
|
||
let bytes = PngExporter::new(&palette_full(), 16).export(&grid).unwrap();
|
||
assert_eq!(&bytes[..8], &[137u8, 80, 78, 71, 13, 10, 26, 10]);
|
||
}
|
||
|
||
#[test]
|
||
fn export_empty_grid_no_panic() {
|
||
let grid = VoxelGrid::new(5, 5, 1); // all None
|
||
let bytes = PngExporter::new(&palette_full(), 16).export(&grid).unwrap();
|
||
assert!(!bytes.is_empty());
|
||
}
|
||
|
||
#[test]
|
||
fn export_multi_layer_larger_than_single() {
|
||
let g1 = make_grid_with_voxels(4, 4, 1);
|
||
let g3 = make_grid_with_voxels(4, 4, 3);
|
||
let b1 = PngExporter::new(&palette_full(), 16).export(&g1).unwrap();
|
||
let b3 = PngExporter::new(&palette_full(), 16).export(&g3).unwrap();
|
||
assert!(b3.len() > b1.len());
|
||
}
|
||
|
||
#[test]
|
||
fn export_palette_with_no_outline() {
|
||
let mut grid = VoxelGrid::new(3, 3, 1);
|
||
let _ = grid.set(0, 0, 0, VoxelType::Outline);
|
||
let bytes = PngExporter::new(&palette_body_only(), 16).export(&grid).unwrap();
|
||
assert!(!bytes.is_empty());
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 2: Run to confirm they fail**
|
||
|
||
```bash
|
||
cargo test -p exporters export 2>&1 | grep -E "FAILED|panicked"
|
||
```
|
||
Expected: all 4 fail with `not yet implemented`
|
||
|
||
- [ ] **Step 3: Implement layer label and legend helpers**
|
||
|
||
Add to `image_export.rs`:
|
||
|
||
```rust
|
||
fn draw_layer_label(img: &mut RgbaImage, y: u32, z: u32, cell_size: u32) {
|
||
let label = format!("Layer {}", z);
|
||
let scale = (cell_size / 8).max(1);
|
||
let label_height = cell_size + 4;
|
||
let text_h = 7 * scale;
|
||
let text_y = y + (label_height.saturating_sub(text_h)) / 2;
|
||
draw_text(img, GAP, text_y, &label, scale, COLOR_TEXT);
|
||
}
|
||
|
||
fn draw_legend(img: &mut RgbaImage, y_start: u32, palette: &BlockPalette, grid: &VoxelGrid, cell_size: u32) {
|
||
let lscale = (cell_size / 8).max(1); // letter scale inside swatch
|
||
for (i, vt) in active_voxel_types(palette, grid).iter().enumerate() {
|
||
let y = y_start + i as u32 * (cell_size + GAP);
|
||
let color = voxel_color(*vt);
|
||
// Color swatch
|
||
draw_rect(img, GAP, y, cell_size, cell_size, color);
|
||
// Letter centered in swatch
|
||
let lw = 5 * lscale;
|
||
let lh = 7 * lscale;
|
||
let lx = GAP + (cell_size.saturating_sub(lw)) / 2;
|
||
let ly = y + (cell_size.saturating_sub(lh)) / 2;
|
||
draw_char(img, lx, ly, voxel_letter(*vt), lscale, COLOR_TEXT);
|
||
// `BlockPalette::resolve(&VoxelType) -> String` is defined in crates/lib/src/palette.rs.
|
||
// It returns the block name string (e.g. "minecraft:stone") or "minecraft:air" for None fields.
|
||
let block_name = palette.resolve(vt);
|
||
let text_x = GAP + cell_size + GAP * 3;
|
||
let text_y = y + (cell_size.saturating_sub(7)) / 2;
|
||
draw_text(img, text_x, text_y, &block_name, 1, COLOR_TEXT);
|
||
}
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 4: Implement `export`**
|
||
|
||
Replace `todo!()` in the `StructureExporter` impl:
|
||
|
||
```rust
|
||
fn export(&self, grid: &VoxelGrid) -> anyhow::Result<Vec<u8>> {
|
||
use std::io::Cursor;
|
||
|
||
let cs = self.cell_size;
|
||
let label_height = cs + 4;
|
||
let per_layer_height = if grid.height == 0 {
|
||
0
|
||
} else {
|
||
grid.height * (cs + GAP) - GAP
|
||
};
|
||
let layer_block_height = label_height + GAP + per_layer_height;
|
||
|
||
let (img_w, img_h) = image_dimensions(grid, &self.palette, cs);
|
||
let mut img = RgbaImage::from_pixel(img_w, img_h, Rgba(COLOR_BG));
|
||
|
||
for z in 0..grid.depth {
|
||
let layer_top_y = z * (layer_block_height + GAP);
|
||
draw_layer_label(&mut img, layer_top_y, z, cs);
|
||
|
||
let grid_top_y = layer_top_y + label_height + GAP;
|
||
for y in 0..grid.height {
|
||
// y=0 in VoxelGrid is the bottom row; flip for image (top-down)
|
||
let vy = grid.height - 1 - y;
|
||
for x in 0..grid.width {
|
||
let px = GAP + x * (cs + GAP);
|
||
let py = grid_top_y + y * (cs + GAP);
|
||
match grid.get(x, vy, z) {
|
||
None => draw_rect(&mut img, px, py, cs, cs, COLOR_BG),
|
||
Some(vt) => {
|
||
draw_rect(&mut img, px, py, cs, cs, voxel_color(vt));
|
||
let lscale = (cs / 8).max(1);
|
||
let lw = 5 * lscale;
|
||
let lh = 7 * lscale;
|
||
let lx = px + (cs.saturating_sub(lw)) / 2;
|
||
let ly = py + (cs.saturating_sub(lh)) / 2;
|
||
draw_char(&mut img, lx, ly, voxel_letter(vt), lscale, COLOR_TEXT);
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
|
||
// Legend below all layers
|
||
let total_grid_height = grid.depth * layer_block_height
|
||
+ grid.depth.saturating_sub(1) * GAP;
|
||
draw_legend(&mut img, total_grid_height + GAP, &self.palette, grid, cs);
|
||
|
||
let mut buf = Cursor::new(Vec::new());
|
||
img.write_to(&mut buf, ImageFormat::Png)
|
||
.map_err(|e| anyhow::anyhow!("PNG encode failed: {}", e))?;
|
||
Ok(buf.into_inner())
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 5: Run all tests**
|
||
|
||
```bash
|
||
cargo test -p exporters
|
||
```
|
||
Expected: all 7 tests pass
|
||
|
||
- [ ] **Step 6: Commit**
|
||
|
||
```bash
|
||
git add crates/exporters/src/image_export.rs
|
||
git commit -m "feat(exporters): implement full PNG grid + legend rendering"
|
||
```
|
||
|
||
---
|
||
|
||
### Task 5: CLI integration
|
||
|
||
**Files:**
|
||
- Modify: `crates/bin/src/cli.rs`
|
||
|
||
- [ ] **Step 1: Add `--cell-size` flag to `Cli` struct**
|
||
|
||
In `crates/bin/src/cli.rs`, add to the `Cli` struct (after `word_spacing`):
|
||
```rust
|
||
/// Cell size in pixels for PNG export (8-64)
|
||
#[arg(long, default_value_t = 16, value_parser = clap::value_parser!(u32).range(8..=64))]
|
||
cell_size: u32,
|
||
```
|
||
|
||
- [ ] **Step 2: Route `"png"` through `build_png`**
|
||
|
||
In `run()`, find the `// Build and validate in one pass` comment and replace the existing `exporters_to_run` collection with:
|
||
|
||
```rust
|
||
// Build and validate in one pass; route "png" through build_png to honour --cell-size
|
||
let exporters_to_run = format_names
|
||
.iter()
|
||
.map(|&name| -> anyhow::Result<Box<dyn lib::StructureExporter>> {
|
||
if name == "png" {
|
||
Ok(exporters::build_png(&palette, cli.cell_size))
|
||
} else {
|
||
exporters::build(name, &palette)
|
||
.ok_or_else(|| anyhow::anyhow!(
|
||
"unknown format '{}'. Available: {}",
|
||
name,
|
||
all_names.join(", ")
|
||
))
|
||
}
|
||
})
|
||
.collect::<anyhow::Result<Vec<_>>>()?;
|
||
```
|
||
|
||
The `for` loop that writes files stays unchanged.
|
||
|
||
Note: you may need to add `use lib::StructureExporter;` at the top of `cli.rs` if the explicit trait bound `Box<dyn lib::StructureExporter>` requires it. Check the import list — if `lib::StructureExporter` is not imported, add it alongside the existing `lib::` imports.
|
||
|
||
- [ ] **Step 3: Build**
|
||
|
||
```bash
|
||
cargo build
|
||
```
|
||
Expected: clean build
|
||
|
||
- [ ] **Step 4: Smoke test — basic PNG generation**
|
||
|
||
```bash
|
||
# Find a TTF font available on your system:
|
||
# fc-list | grep -i ttf | head -5
|
||
# Then substitute the path below:
|
||
cargo run -- --text "Hi" --font /usr/share/fonts/TTF/DejaVuSans.ttf \
|
||
--format png --cell-size 32 --out /tmp/test_hi
|
||
```
|
||
Expected: `/tmp/test_hi.png` created. Open it — should show "Layer 0" header, a grid of colored cells with B/O letters, and a legend below.
|
||
|
||
- [ ] **Step 5: Test `--format all`**
|
||
|
||
```bash
|
||
# Use the same font path from Step 4
|
||
cargo run -- --text "Hi" --font /usr/share/fonts/TTF/DejaVuSans.ttf \
|
||
--format all --cell-size 32 --out /tmp/test_all
|
||
```
|
||
Expected: `/tmp/test_all.mcfunction`, `/tmp/test_all.litematica`, and `/tmp/test_all.png` all created
|
||
|
||
- [ ] **Step 6: Test depth > 1**
|
||
|
||
```bash
|
||
cargo run -- --text "Hi" --font /usr/share/fonts/TTF/DejaVuSans.ttf \
|
||
--format png --depth 3 --cell-size 16 --out /tmp/test_depth
|
||
```
|
||
Expected: PNG with 3 stacked "Layer 0", "Layer 1", "Layer 2" sections
|
||
|
||
- [ ] **Step 7: Commit**
|
||
|
||
```bash
|
||
git add crates/bin/src/cli.rs
|
||
git commit -m "feat(cli): add --cell-size flag, route png through build_png"
|
||
```
|
||
|
||
---
|
||
|
||
### Task 6: Final check
|
||
|
||
- [ ] **Full test suite**
|
||
|
||
```bash
|
||
cargo test
|
||
```
|
||
Expected: all tests pass, no regressions
|
||
|
||
- [ ] **Test shadow (3 legend entries)**
|
||
|
||
```bash
|
||
cargo run -- --text "Hi" --font /usr/share/fonts/TTF/DejaVuSans.ttf \
|
||
--format png --shadow --cell-size 32 --out /tmp/test_shadow
|
||
```
|
||
Expected: PNG with S (tan/gold) cells and all 3 legend rows (B blue, O gray, S tan)
|
||
|
||
- [ ] **Test invalid cell-size is rejected**
|
||
|
||
```bash
|
||
cargo run -- --text "Hi" --font /usr/share/fonts/TTF/DejaVuSans.ttf \
|
||
--format png --cell-size 4 --out /tmp/x 2>&1 | head -3
|
||
```
|
||
Expected: clap error about value out of range
|
||
|
||
- [ ] **Final commit if needed**
|
||
|
||
```bash
|
||
git log --oneline -6
|
||
```
|
||
Confirm all 6 feature commits are present and clean (Tasks 1–6 each produce one commit).
|