A Rust CLI that generates PBR (Physically Based Rendering) maps from diffuse/albedo textures using GPU compute shaders via wgpu. No GUI, no Unity — one command, six (or seven) maps.

Inspired by the original 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.

Materialize takes a single diffuse/albedo texture and produces up to seven PBR maps:

Key properties:

• Fast — GPU compute shaders via wgpu; no CPU-bound image loops
• Cross-platform — Linux, macOS, Windows (Vulkan, Metal, DirectX 12)
• No CUDA required — wgpu works with any modern GPU
• Auto-detect — -p auto analyses the texture and picks the best preset
• Batch-friendly — directories and globs, --skip-existing resume
• Scriptable — CLI-only; stable exit codes

From the repository root:

./install.sh materialize

This compiles the crate and installs the binary to ~/.local/bin/. Ensure ~/.local/bin is on your PATH.

Requires Rust 1.87+ and a GPU with up-to-date drivers.

cd Materialize
cargo build --release
cargo install --path .

The materialize binary is placed in Cargo's ~/.cargo/bin/.

git clone https://github.com/maikramer/Materialize-CLI.git
cd Materialize-CLI
./install.sh          # install
./install.sh reinstall
./install.sh uninstall

Generate PBR maps from a diffuse/albedo image. INPUT may be a single file, a directory, or a glob pattern.

materialize texture.png
materialize texture.png -o ./out/ -v
materialize skin.png --preset skin -o ./materials/
materialize ./textures/ -o ./pbr/ --jobs 4 --progress
materialize texture.png -p auto -v

--height-contrast, --height-blur, --normal-strength, --metallic-scale, --metallic-local-variance, --smoothness-base, --smoothness-boost, --smoothness-roughness, --edge-contrast, --ao-depth-scale.

Analyse a texture without generating maps. Prints the detected preset, confidence score, and the full feature vector.

materialize info texture.png

Install the Materialize CLI Cursor AI skill into the current project's .cursor/skills/materialize-cli/ directory.

materialize skill install

19 material presets plus auto. Use -p / --preset to select one.

materialize brick_diffuse.png -p stone -o ./out/
materialize character_skin.png --preset skin -v
materialize metal_panel.jpg -p metal -f exr -o ./hdr/
materialize mystery.png -p auto -v

-p auto runs a fast CPU pre-pass over the texture and computes:

• Luminance mean/std
• Saturation mean/std
• Hue histogram (12 bins)
• Sobel edge density
• 5×5 local contrast variance
• Tile MSE (full top/bottom + left/right border rows/cols)
• Alpha coverage

A decision tree maps these features to a preset (metal, skin, wood, stone, foliage, floor, default) plus a confidence score. When the tile MSE is below 0.005, the pipeline switches all neighbourhood-sampling shaders to wrap (Euclidean modulo) at borders so the generated maps stay tileable.

Use materialize info <image> to preview the analysis without generating any maps.

MATERIALIZE_GPU_BACKEND=vulkan materialize texture.png
MATERIALIZE_LOG=debug materialize texture.png -v

From an input file texture.png, Materialize generates up to seven files in the output directory (extension follows --format):

Materialize runs after Texture2D or Paint3D to generate PBR maps from diffuse textures. It is integrated into the GameDev monorepo pipeline at several points:

• GameAssets batch — via materialize: true in the texture2d block of game.yaml
• Paint3D — vertex-pbr command uses Materialize for map generation
• Standalone — can process any diffuse image from any source

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.

# Typical pipeline: generate texture, then PBR maps
texture2d generate "brick wall" -o ./textures/
materialize textures/brick_wall.png -p auto -o ./materials/brick/

# Process a directory (sequentially; --jobs controls CPU-side parallelism)
materialize ./textures/ -o ./pbr/ --jobs 4 --progress

# Resume after interruption
materialize ./textures/ -o ./pbr/ --skip-existing

# Glob pattern
materialize "./textures/bricks/*.png" -o ./pbr/

# Script-friendly: quiet mode, check exit code
materialize texture.png -o ./out/ --quiet
if [ $? -eq 0 ]; then echo "PBR maps generated"; fi

cd Materialize

# Build
cargo build

# Run tests
cargo test

# Format (auto-fix)
cargo fmt

# Lint
cargo clippy -- -D warnings

Requires Rust 1.87+ (edition 2024). Dev dependencies: tempfile for integration tests.

MIT License — see LICENSE.

This project is based on 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.

• docs/README.md — Overview, installation details, and doc index
• docs/cli-api.md — Full CLI reference, environment variables, shell completion
• docs/architecture.md — System structure
• docs/features.md — Capabilities
• docs/algorithms.md — Processing algorithms
• docs/shaders.md — WGSL compute shaders
• docs/roadmap.md — Future plans
• CHANGELOG.md — Release history (2.0 breaking changes)

• Bugs & features — Open an issue
• Questions — GitHub Discussions
• Contributing — See CONTRIBUTING.md