Skip to content

Commit e7f2a89

Browse files
maikramermaikramer
committed
docs: rewrite package READMEs with pipeline overview, quality presets, multi-GPU docs
Comprehensive README updates across all packages. Root README adds pipeline diagram, one-command dream workflow, VibeGame integration section, and quality presets/multi-GPU overview. Per-package READMEs document CLI usage, quality tiers, GPU options, and updated examples.
1 parent 54db88a commit e7f2a89

17 files changed

Lines changed: 5143 additions & 1264 deletions

File tree

‎Animator3D/README.md‎

Lines changed: 529 additions & 68 deletions
Large diffs are not rendered by default.

‎GameAssets/README.md‎

Lines changed: 883 additions & 168 deletions
Large diffs are not rendered by default.

‎GameDevLab/README.md‎

Lines changed: 501 additions & 83 deletions
Large diffs are not rendered by default.

‎Materialize/README.md‎

Lines changed: 134 additions & 94 deletions
Original file line numberDiff line numberDiff line change
@@ -1,186 +1,226 @@
1-
# Materialize CLI
1+
# Materialize — PBR Map Generation
22

3-
A **Rust CLI** that generates PBR (Physically Based Rendering) maps from diffuse textures using GPU compute shaders via [wgpu](https://wgpu.rs/). No GUI, no Unity — just one command and six maps.
3+
A **Rust CLI** that generates PBR (Physically Based Rendering) maps from diffuse/albedo textures using GPU compute shaders via [wgpu](https://wgpu.rs/). No GUI, no Unity — one command, six maps.
44

5-
Inspired by the original [Materialize](https://github.com/BoundingBoxSoftware/Materialize) (Unity/Windows). **Language:** English (this file) · [Português (`README_PT.md`)](README_PT.md).
6-
7-
**Who is this for?** Game developers, 3D artists, and anyone who needs PBR maps from diffuse textures — in engines like Unity, Unreal, Godot, or in Blender, without running a GUI or the Windows-only original.
8-
9-
**GameDev monorepo:** **Hunyuan3D-Paint 2.1** (`paint3d texture`) already outputs a **PBR GLB**. This CLI is for **PBR maps from a diffuse image** (e.g. **Texture2D** + `texture2d.materialize` in GameAssets). See [`Text3D/docs/PBR_MATERIALIZE.md`](../Text3D/docs/PBR_MATERIALIZE.md).
5+
Inspired by the original [Materialize](https://github.com/BoundingBoxSoftware/Materialize) by Bounding Box Software (Unity/Windows). This is a from-scratch Rust CLI that preserves the same concept — turning a single diffuse image into a complete PBR material set.
106

117
---
128

13-
## Generated maps
9+
## Overview
1410

15-
From a single diffuse/albedo image, the tool outputs six maps:
11+
Materialize takes a single diffuse/albedo texture and produces six PBR maps:
1612

1713
| Map | Description |
1814
|-----|-------------|
19-
| **Height** | Surface elevation for parallax/displacement |
20-
| **Normal** | Surface normals for lighting |
21-
| **Metallic** | Metallic vs dielectric mask |
22-
| **Smoothness** | Roughness/smoothness (base + metallic contribution) |
15+
| **Height** | Surface elevation for parallax / displacement effects |
16+
| **Normal** | Per-pixel surface normals for realistic lighting |
17+
| **Metallic** | Metallic vs. dielectric mask |
18+
| **Smoothness** | Inverse roughness (base + metallic contribution) |
2319
| **Edge** | Edge detection derived from normals |
24-
| **AO** | Ambient occlusion (cavity-style from height) |
25-
26-
---
20+
| **AO** | Ambient occlusion (cavity-style, derived from height) |
2721

28-
## Features
22+
**Key properties:**
2923

30-
- **Minimal** — Command-line only; easy to script and automate
31-
- **Fast** — GPU compute shaders (wgpu); no CPU-bound image loops
24+
- **Fast** — GPU compute shaders via wgpu; no CPU-bound image loops
3225
- **Cross-platform** — Linux, macOS, Windows (Vulkan, Metal, DirectX 12)
33-
- **Flexible** — Output formats: PNG, JPG, TGA, EXR; configurable quality for JPEG
26+
- **No CUDA required** — wgpu works with any modern GPU
27+
- **Scriptable** — CLI-only; easy to batch and integrate into pipelines
3428

3529
---
3630

37-
## Quick start
31+
## Installation
3832

39-
### Install (GameDev monorepo)
33+
### GameDev monorepo (recommended)
4034

41-
If you have the **GameDev** monorepo (this folder lives under `GameDev/Materialize`), use the unified installer from the **repository root**:
35+
From the repository root:
4236

4337
```bash
44-
cd /path/to/GameDev
4538
./install.sh materialize
4639
```
4740

48-
See [docs/INSTALLING.md](../docs/INSTALLING.md). Requires **Rust** (`cargo`) and Python 3 for the installer wrapper.
41+
This compiles the crate and installs the binary to `~/.local/bin/`. Ensure `~/.local/bin` is on your `PATH`.
42+
43+
### Standalone build
44+
45+
Requires **Rust** 1.87+ and a GPU with up-to-date drivers.
46+
47+
```bash
48+
cd Materialize
49+
cargo build --release
50+
cargo install --path .
51+
```
4952

50-
### Install (standalone clone)
53+
The `materialize` binary is placed in Cargo's `~/.cargo/bin/`.
5154

52-
Requires **Python 3** (installer) and **Rust** (cargo) to build. The installer compiles and places the binary in `~/.local/bin/materialize` (ensure it’s on your `PATH`).
55+
### Manual install script
5356

5457
```bash
58+
# Clone and run installer (places binary in ~/.local/bin)
5559
git clone https://github.com/maikramer/Materialize-CLI.git
5660
cd Materialize-CLI
57-
./install.sh
61+
./install.sh # install
62+
./install.sh reinstall
63+
./install.sh uninstall
5864
```
5965

60-
- **Linux/macOS:** `./install.sh` | `./install.sh uninstall` | `./install.sh reinstall`
61-
- **Windows:** `.\install.ps1` or `install.bat`
66+
---
67+
68+
## Commands
69+
70+
### `materialize <INPUT>` (default command)
6271

63-
### Run
72+
Generate PBR maps from a diffuse/albedo image.
6473

6574
```bash
6675
materialize texture.png
67-
# Writes to current directory:
68-
# texture_height.png, texture_normal.png, texture_metallic.png,
69-
# texture_smoothness.png, texture_edge.png, texture_ao.png
70-
7176
materialize texture.png -o ./out/ -v
77+
materialize skin.png --preset skin -o ./materials/
7278
materialize diffuse.png --format png --quiet
7379
```
7480

75-
### Manual build (Cargo)
81+
#### Options
7682

77-
```bash
78-
cargo build --release
79-
cargo install --path .
80-
```
83+
| Flag | Short | Type | Default | Description |
84+
|------|-------|------|---------|-------------|
85+
| `--output` | `-o` | path | `.` | Output directory |
86+
| `--format` | `-f` | str | `png` | Output format: `png`, `jpg`, `jpeg`, `tga`, `exr` |
87+
| `--preset` | `-p` | str | `default` | Material preset (see below) |
88+
| `--quality` | `-q` | int | `95` | JPEG quality 0–100 (ignored for other formats) |
89+
| `--verbose` | `-v` | flag | — | Print progress and timing information |
90+
| `--quiet` | — | flag | — | Suppress generated file list on success |
91+
| `--help` | `-h` | — | — | Show help message |
92+
| `--version` | `-V` | — | — | Show version (`materialize-cli 1.0.0`) |
8193

82-
---
94+
### `materialize skill install`
8395

84-
## Usage
96+
Install the Materialize CLI [Cursor AI skill](.cursor/skills/materialize-cli/) into the current project's `.cursor/skills/materialize-cli/` directory.
8597

86-
### Syntax
87-
88-
```text
89-
materialize [OPTIONS] [INPUT] [COMMAND]
98+
```bash
99+
materialize skill install
90100
```
91101

92-
### Options
102+
---
103+
104+
## PBR Presets
93105

94-
| Option | Short | Default | Description |
95-
|--------|-------|---------|-------------|
96-
| `--output` | `-o` | `./` | Output directory |
97-
| `--format` | `-f` | `png` | Output format: `png`, `jpg`, `jpeg`, `tga`, `exr` |
98-
| `--quality` | `-q` | `95` | JPEG quality (0–100) when using `-f jpg` |
99-
| `--verbose` | `-v` | — | Print progress and timing |
100-
| `--quiet` | — | — | Do not list generated files on success |
101-
| `--help` | `-h` | — | Show help |
102-
| `--version` | `-V` | — | Show version |
106+
Presets tune the generation parameters for specific material types. Use `-p` / `--preset` to select one.
103107

104-
### Subcommands
108+
| Preset | Description | Characteristics |
109+
|--------|-------------|-----------------|
110+
| `default` | General purpose | Balanced settings for any texture |
111+
| `skin` | Human/character skin | No metallic, high smoothness, subtle normals |
112+
| `floor` | Ground surfaces (stone, tile, dirt) | Pronounced height, strong AO, rough surface |
113+
| `metal` | Metallic surfaces | Boosted metallic, sharp edges, polished look |
114+
| `fabric` | Cloth / textile | Matte, no metallic, soft edges |
115+
| `wood` | Wood grain | No metallic, moderate grain detail |
116+
| `stone` | Rock / stone | Very rough, deep AO, strong normals |
105117

106-
- **`materialize skill install`** — Installs the Materialize CLI [Cursor skill](.cursor/skills/materialize-cli/) into the current project’s `.cursor/skills/materialize-cli/`.
118+
```bash
119+
materialize brick_diffuse.png -p stone -o ./out/
120+
materialize character_skin.png --preset skin -v
121+
materialize metal_panel.jpg -p metal -f exr -o ./hdr/
122+
```
107123

108-
### Output naming
124+
---
109125

110-
For input `texture.png`, outputs are:
126+
## Output Files
111127

112-
- `texture_height.png`
113-
- `texture_normal.png`
114-
- `texture_metallic.png`
115-
- `texture_smoothness.png`
116-
- `texture_edge.png`
117-
- `texture_ao.png`
128+
From an input file `texture.png`, Materialize generates six files in the output directory (extension follows `--format`):
118129

119-
(Extension follows `--format`.)
130+
| File | Description |
131+
|------|-------------|
132+
| `texture_height.{ext}` | Height / displacement map |
133+
| `texture_normal.{ext}` | Normal map |
134+
| `texture_metallic.{ext}` | Metallic map |
135+
| `texture_smoothness.{ext}` | Smoothness map |
136+
| `texture_edge.{ext}` | Edge detection map |
137+
| `texture_ao.{ext}` | Ambient occlusion map |
120138

121139
### Exit codes
122140

123141
| Code | Meaning |
124142
|------|---------|
125-
| `0` | Success |
143+
| `0` | Success — files generated |
126144
| `1` | Generic error |
127145
| `2` | Input file not found |
128146
| `3` | Unsupported input format |
129-
| `4` | GPU error (no adapter) |
147+
| `4` | GPU error (no adapter found) |
130148
| `5` | I/O error (permissions, disk full, etc.) |
131149
| `6` | Image too large for GPU |
132150

133151
---
134152

135-
## Examples
153+
## Pipeline Integration
136154

137-
```bash
138-
# Default: current directory, PNG
139-
materialize brick.png
155+
Materialize runs **after** Texture2D or Paint3D to generate PBR maps from diffuse textures. It is integrated into the GameDev monorepo pipeline at several points:
140156

141-
# Custom output directory and verbose
142-
materialize brick.png -o ./materials/brick/ -v
157+
- **GameAssets batch** — via `materialize: true` in the `texture2d` block of `game.yaml`
158+
- **Paint3D** — `vertex-pbr` command uses Materialize for map generation
159+
- **Standalone** — can process any diffuse image from any source
143160

144-
# EXR for HDR / precision
145-
materialize texture.png -f exr -o ./out/
161+
Uses wgpu compute shaders for cross-platform GPU acceleration — no CUDA required. Works on Linux (Vulkan), macOS (Metal), and Windows (DirectX 12) with any modern GPU.
146162

147-
# Batch (parallel with xargs)
148-
ls *.png | xargs -P 4 -I {} materialize {} -o ./output/
163+
```bash
164+
# Typical pipeline: generate texture, then PBR maps
165+
texture2d generate "brick wall" -o ./textures/
166+
materialize textures/brick_wall.png -p stone -o ./materials/brick/
167+
```
168+
169+
### Batch processing
170+
171+
```bash
172+
# Parallel batch with xargs
173+
ls textures/*.png | xargs -P 4 -I {} materialize {} -o ./pbr/
149174

150-
# Script-friendly: quiet, check exit code
175+
# Script-friendly: quiet mode, check exit code
151176
materialize texture.png -o ./out/ --quiet
152-
if [ $? -eq 0 ]; then echo "OK"; fi
177+
if [ $? -eq 0 ]; then echo "PBR maps generated"; fi
153178
```
154179

155180
---
156181

157-
## Getting help
182+
## Development
158183

159-
- **Bugs & features** — [Open an issue](https://github.com/maikramer/Materialize-CLI/issues) (templates for bug reports and feature requests are available).
160-
- **Questions** — [GitHub Discussions](https://github.com/maikramer/Materialize-CLI/discussions).
161-
- **Contributing** — See [CONTRIBUTING.md](CONTRIBUTING.md). We follow a [Code of Conduct](CODE_OF_CONDUCT.md).
184+
```bash
185+
cd Materialize
186+
187+
# Build
188+
cargo build
189+
190+
# Run tests
191+
cargo test
192+
193+
# Format (auto-fix)
194+
cargo fmt
195+
196+
# Lint
197+
cargo clippy -- -D warnings
198+
```
199+
200+
Requires **Rust** 1.87+ (edition 2024). Dev dependencies: `tempfile` for integration tests.
162201

163202
---
164203

165-
## Requirements
204+
## License & Attribution
205+
206+
**MIT License** — see [LICENSE](LICENSE).
166207

167-
- **Rust** 1.75+
168-
- **GPU** with Vulkan (Linux), Metal (macOS), or DirectX 12 (Windows); up-to-date drivers
208+
This project is based on [Materialize](https://github.com/BoundingBoxSoftware/Materialize) by **Bounding Box Software**. The original Materialize is a Unity-based Windows application for generating PBR maps. This is a from-scratch Rust reimplementation that preserves the concept and algorithmic approach.
169209

170210
---
171211

172212
## Documentation
173213

174214
- [docs/README.md](docs/README.md) — Overview, installation details, and doc index
175-
- [docs/cli-api.md](docs/cli-api.md) — Full CLI reference, env vars, shell completion
215+
- [docs/cli-api.md](docs/cli-api.md) — Full CLI reference, environment variables, shell completion
176216
- [docs/architecture.md](docs/architecture.md) — System structure
177217
- [docs/features.md](docs/features.md) — Capabilities
178218
- [docs/algorithms.md](docs/algorithms.md) — Processing algorithms
179-
- [docs/shaders.md](docs/shaders.md) — WGSL shaders
219+
- [docs/shaders.md](docs/shaders.md) — WGSL compute shaders
180220
- [docs/roadmap.md](docs/roadmap.md) — Future plans
181221

182-
---
183-
184-
## License
222+
## Getting Help
185223

186-
[MIT](LICENSE). Based on the original Materialize by Bounding Box Software.
224+
- **Bugs & features** — [Open an issue](https://github.com/maikramer/Materialize-CLI/issues)
225+
- **Questions** — [GitHub Discussions](https://github.com/maikramer/Materialize-CLI/discussions)
226+
- **Contributing** — See [CONTRIBUTING.md](CONTRIBUTING.md)

0 commit comments

Comments
 (0)