ComfyUI Extension: ComfyUI-TextureAlchemy

Authored by amtarr

Created 6 days ago

Updated 4 days ago

0 stars

Complete workflow suite for ComfyUI that transforms images into PBR material sets ready for game engines and 3D software.

Custom Nodes (0)

README

TextureAlchemy

Transform Images into complete material sets ready for game engines, 3D software, and rendering pipelines.*

Complete workflow suite for ComfyUI. Extract, process, and enhance physically-based rendering textures with AI-powered alchemy.

🎯 What It Does

Creates complete PBR material sets from images using AI (Marigold/Lotus) with professional post-processing tools:

Material Maps:

Albedo - Base color/diffuse
Normal - Surface normals (OpenGL/DirectX compatible)
Roughness - Surface roughness
Metallic - Metalness/reflectivity
AO - Ambient occlusion
Height - Displacement/parallax
Curvature - Edge detection for wear/weathering

Professional Tools:

Seamless tiling, texture scaling, triplanar projection
Channel packing (save VRAM), normal/height conversion
Material mixing, wear generation, detail blending
HSV color adjustment, gradient mapping
Interactive color ramp with visual UI

📦 Installation

Copy ComfyUI_PBR_MaterialProcessor folder to ComfyUI/custom_nodes/
Restart ComfyUI
Find all nodes in Texture Alchemist category in ComfyUI's node library

No additional requirements needed - uses ComfyUI's built-in libraries (PyTorch, PIL, NumPy).

📚 Node Categories

All nodes are in the "Texture Alchemist" category in ComfyUI!

To find nodes: Right-click in ComfyUI → Add Node → Texture Alchemist → Choose subcategory

⚗️ Texture Alchemist/Core (2 nodes)

Extract and adjust PBR materials from AI outputs

⚗️ Texture Alchemist/Pipeline (6 nodes)

Bundle maps, adjust in batch, mix materials, save sets

⚗️ Texture Alchemist/Normal (4 nodes)

Process, combine, convert normal maps

⚗️ Texture Alchemist/Color (4 nodes)

Recolor, adjust HSV, color ramps

⚗️ Texture Alchemist/Effects (4 nodes)

Wear generation, curvature, detail blending

⚗️ Texture Alchemist/Texture (8 nodes)

Tiling, scaling, projection, optimization

⚗️ Texture Alchemist/Channel (8 nodes)

Pack/unpack RGB channels, grayscale conversion

⚗️ Texture Alchemist/Maps (3 nodes)

Height processing, AO generation

⚗️ Texture Alchemist/Materials (User nodes)

Your custom PBR extractors

🔌 The Nodes (Detailed Reference)

Core Processing

1. PBR Extractor (Marigold)

Extracts PBR maps from Marigold AI outputs into a PBR_PIPE. Needs the Marigold model loader from ComfyUI-Marigold

Inputs:

marigold_appearance - Marigold output (appearance model)
marigold_lighting - Marigold output (lighting model)
albedo_source - "appearance" or "lighting"
gamma_albedo - Gamma for albedo (0.45)
gamma_metal_rough - Gamma for metallic and roughness (2.2)
gamma_lighting_ao - Gamma for lighting and AO (0.45)

Outputs:

pbr_pipe - Complete PBR pipeline with albedo, roughness, metallic, lighting

Tips:

Default gamma_metal_rough=2.2 provides strong contrast; adjust 1.8-2.6 if needed
Default albedo_source="lighting" provides cleaner albedo; try "appearance" for alternative look
gamma_albedo affects albedo regardless of source (appearance or lighting)

2. PBR Adjuster

Simple brightness/contrast/invert adjustments for individual maps.

Inputs:

Individual maps (albedo, ao, roughness, metallic)
Per-map: brightness (0-3x), contrast (0-3x), invert (bool)

Outputs:

Adjusted versions of input maps

Use Cases:

Quick map adjustments before combining
Fine-tune individual channels

3. AO Approximator

Generate ambient occlusion from height + normal maps.

Inputs:

height - Height/displacement map (required)
normal - Normal map (optional, improves quality)
radius - Sample radius in pixels (8-16 typical)
strength - AO intensity (1.0)
samples - Quality vs speed (16-32)
contrast - Contrast boost (1.0)

Outputs:

ao - Generated ambient occlusion map

Tips:

More samples = better quality but slower
Larger radius = broader, softer AO
Use both height + normal for best results

Pipeline System

4. PBR Combiner

Bundle individual maps into a single PBR_PIPE connection.

Inputs (all optional):

pbr_pipe - Existing pipe to merge with
albedo, normal, ao, height, roughness, metallic, transparency, emission ⭐

Outputs:

pbr_pipe - All maps in one bundle

Use Cases:

Create pipe from individual maps
Add normal/height to extractor output
Override specific maps in existing pipe
Add emission maps for glowing/emissive materials (lights, lava, screens, etc.)

5. PBR Pipeline Adjuster

Advanced batch adjustments with AO integration.

Inputs:

pbr_pipe - PBR pipeline
ao_strength_albedo (1.0) - Darken albedo with AO
ao_strength_roughness (0.0) - Add AO to roughness (weathering)
roughness_strength (1.0) - Brightness multiplier
metallic_strength (1.0) - Brightness multiplier
normal_strength (1.0) - Flatten (0.0) or exaggerate (2.0)
invert_normal_green - OpenGL ↔ DirectX
invert_transparency - Flip alpha
albedo_dimmer (0.0-1.0) - Darken (1.0 = black)
albedo_saturation (1.0) - Color intensity

Outputs:

pbr_pipe - Adjusted pipeline

Tips:

ao_strength_albedo=1.0-1.2 for realistic darkening
ao_strength_roughness=0.2-0.5 for weathered look
albedo_saturation=1.2-1.5 for vibrant colors

6. PBR Splitter

Extract individual maps from PBR_PIPE.

Outputs:

All map types as separate outputs: albedo, normal, ao, height, roughness, metallic, transparency, emission ⭐

7. PBR Saver 💾

Save complete material sets with auto-naming and enumeration.

Inputs:

pbr_pipe - Pipeline to save
base_name - File prefix (e.g., "bricks")
output_path - Folder in ComfyUI/output (default: "pbr_materials")
file_format - png, jpg, exr, tiff
enumeration_mode - "enumerate" or "overwrite"
starting_number - Starting index (1)

Outputs:

images - Batch of all saved maps (for preview)

Example Output:

ComfyUI/output/pbr_materials/
  bricks_albedo_001.png
  bricks_normal_001.png
  bricks_ao_001.png
  bricks_roughness_001.png
  bricks_metallic_001.png

Tips:

Auto-detects portable vs standard ComfyUI install
Connect output to Preview Image to see all maps
Use EXR for 32-bit precision

8. PBR Pipe Preview

Passthrough node that outputs all maps as a batch for preview.

Inputs:

pbr_pipe - Pipeline to preview

Outputs:

pbr_pipe - Unchanged passthrough
preview_batch - All maps in one batch

Use Cases:

Debug pipeline at any stage
Preview without saving
Quick visual check

9. PBR Material Mixer

Blend two complete PBR materials together.

Inputs:

base_pipe - Base material
overlay_pipe - Overlay material
blend_mode - mix, multiply, overlay, add, screen
blend_strength (0.0-1.0) - Blend amount
mask (optional) - Blend mask

Outputs:

pbr_pipe - Mixed material

Use Cases:

Layer materials (brick + moss)
Create material variations
Mask-based blending

Normal & Height Processing

10. Normal Processor (Lotus)

Process Lotus normal maps with channel control.

Inputs:

normal - Lotus output
invert_red, invert_green, invert_blue - Per-channel inversion
strength (0.0-2.0) - Normal intensity

Outputs:

normal - Processed normal map

Tips:

invert_green=True for OpenGL format
Adjust strength to flatten or exaggerate bumps

11. Normal Map Combiner

Combine two normal maps using proper math.

Inputs:

base_normal - Primary normal
detail_normal - Detail to add
blend_mode - reoriented (best), whiteout, linear
detail_strength (0.0-2.0) - Detail intensity

Outputs:

combined_normal - Blended normal

Use Cases:

Add micro-detail to base normals
Layer multiple detail passes
Combine procedural + photo normals

12. Normal to Depth Converter

Convert normal maps to height/depth maps.

Inputs:

normal - Normal map
method - integration (accurate), blue_channel (fast), hybrid (balanced)
strength (1.0) - Depth intensity
iterations (50) - Integration accuracy
blur_radius (1.0) - Smoothing

Outputs:

depth - Generated depth/height map

Tips:

Use "hybrid" for best speed/quality balance
More iterations = more accurate but slower

13. Height to Normal Converter ⭐ NEW

Generate normal maps from height/depth maps.

Inputs:

height - Height/displacement map
strength (1.0) - Normal map intensity
method - sobel (balanced), scharr (detailed), prewitt (smooth)

Outputs:

normal - Generated normal map

Use Cases:

Create normals from Lotus depth output
Generate normals from procedural height
Convert displacement to normal

14. Normal Format Converter (DX↔GL) ⭐ NEW

Convert between DirectX and OpenGL normal map formats.

Inputs:

normal - Normal map
conversion - DirectX_to_OpenGL, OpenGL_to_DirectX, auto_detect

Outputs:

normal - Converted normal map

Tips:

Flips green (Y) channel
Use when normals look inverted
Most game engines use OpenGL

15. Normal Format Validator (OGL vs DX) ⭐ NEW

Automatically detects and validates normal map format (OpenGL vs DirectX).

Inputs:

normal_map - Normal map to analyze

Outputs:

visualization - 4-panel visual analysis
- Panel 1: Original normal map
- Panel 2: Green channel isolated
- Panel 3: Threshold map (white=up, black=down)
- Panel 4: Format indicator (green=OGL, red=DX)
detected_format - String result with confidence

Detection Method:

Analyzes green channel distribution
OpenGL: More pixels > 0.5 (Y points UP)
DirectX: More pixels < 0.5 (Y points DOWN)
Confidence based on bias strength

Console Output:

📊 GREEN CHANNEL ANALYSIS:
  Pixels > 0.5: 73.2% (up-facing)
  Pixels < 0.5: 26.8% (down-facing)
  Bias: +0.464

🎯 DETECTION RESULT:
  Format: OpenGL
  Confidence: High

Confidence Levels:

High (>20% bias) - Very clear format
Medium (10-20%) - Likely correct
Low (5-10%) - Uncertain
Ambiguous (<5%) - Flat map or balanced normals

Use Cases:

Verify normals from unknown sources
Debug "why does my normal map look wrong?"
QA for asset pipelines
Educational tool

Tips:

Check visualization if result is ambiguous
Flat normal maps may return AMBIGUOUS
Use with "Normal Format Converter" for fixing

Color & Effects

16. Color Ramp 🎨✨

Map grayscale to colors with visual gradient preview (like Blender!).

Features:

🌈 Real-time gradient preview in node
🎯 Interactive color stop markers (click to add, double-click to remove)
🎨 Click color swatches to open color picker
↔️ Drag markers to reposition
📋 8 built-in presets

Inputs:

image - Input (converts to grayscale)
preset - grayscale, heat, rainbow, gold_metal, rust, copper, blue_metal, custom
interpolation - linear, ease_in, ease_out, constant
color_stops - JSON data (managed by visual widget)

Outputs:

image - Recolored output

Presets:

heat - Black → Red → Orange → Yellow (data visualization)
rainbow - Full spectrum
gold_metal - Dark bronze → Gold → Bright
rust, copper, blue_metal - Metallic variations

Use Cases:

Stylized albedo from AO/height
Heat map visualizations
Quick color variations
Artistic effects

17. Simple Recolor

Quick two-color gradient.

Inputs:

dark_color, light_color - RGB values
blend_mode - linear or smooth

17. HSV Adjuster ⭐ NEW

Adjust hue, saturation, and value (better than RGB adjustments).

Inputs:

image - Input image
hue_shift (-0.5 to 0.5) - Rotate color wheel
saturation (0.0-3.0) - Color intensity (0=grayscale, >1=vivid)
value (0.0-3.0) - Brightness

Outputs:

image - Adjusted image

Use Cases:

Color grade albedo
Create material variations
Adjust saturation without affecting brightness
Preserve material properties better than RGB

18. Curvature Map Generator ⭐ NEW

Detect edges and crevices for wear/weathering masks.

Inputs:

input_map - Normal or height map
input_type - normal or height
strength (1.0) - Detection sensitivity
blur_radius (1.0) - Smoothing

Outputs:

curvature - Edge detection mask

Use Cases:

Create wear masks (edges = more wear)
Procedural damage
Detail masking
AO enhancement

19. Detail Map Blender ⭐ NEW

Add micro-detail without washing out base maps.

Inputs:

base - Base map
detail - Detail map
map_type - normal (RNM blend), roughness (multiply), generic (overlay)
strength (1.0) - Detail intensity
mask (optional) - Blend mask

Outputs:

blended - Combined map

Tips:

Use map_type=normal for proper normal blending
Use map_type=roughness for surface detail
Mask controls where detail appears

20. Wear & Edge Damage Generator ⭐ NEW

Procedural wear and weathering effects.

Inputs:

albedo - Base albedo
wear_strength (0.5) - Overall wear
edge_wear (0.7) - Damage on edges (needs curvature)
dirt_strength (0.3) - Dirt in crevices (needs AO)
curvature (optional) - For edge detection
ao (optional) - For cavity dirt

Outputs:

worn_albedo - Weathered albedo
wear_mask - Mask showing wear areas

Use Cases:

Realistic weathering
Procedural damage
Aged materials
Dirt accumulation

21. Gradient Map (Mask) ⭐ NEW

Create selection masks from value ranges.

Inputs:

image - Input map
input_range_min, input_range_max - Value range to select
invert - Flip mask
smoothness (0.0-0.5) - Edge softness

Outputs:

mask - Selection mask

Use Cases:

Select height ranges
Isolate value ranges
Create soft selections
Layer masking

Texture Utilities

22. Texture Offset ⭐ NEW

Offset, rotate, and wrap textures with seamless tiling support and edge mask.

Inputs:

image - Input texture
offset_x (-1.0 to 1.0) - Horizontal shift (fraction of width)
offset_y (-1.0 to 1.0) - Vertical shift (fraction of height)
rotation (-360° to 360°) - Rotation angle
wrap_mode - repeat (tile), clamp (extend), mirror (reflect)
edge_mask_width (0.1) - Edge mask width for affected areas

Outputs:

image - Offset/rotated texture
edge_mask - White mask showing transformed/affected edges

Wrap Modes:

repeat - True circular/seamless wrapping (perfect for tileable textures)
clamp - Extends edge pixels (useful for bordered images)
mirror - Reflects at edges (creates symmetrical patterns)

Technical Note:

repeat mode uses torch.roll() for offset (perfect circular wrapping)
repeat mode with rotation tiles 3x3, rotates, then crops center (maintains seamless edges!)
Other modes use PyTorch's grid_sample() with border/reflection padding

Use Cases:

Adjust texture alignment for UV mapping
Test tiling at different offsets
Rotate textures without re-rendering
Fix texture orientation issues

Tips:

Use repeat mode for seamless textures (maintains tiling even with rotation!)
offset_x/y = 0.5 shifts by half (useful for seam testing)
Combine with Seamless Tiling for perfect results

23. Texture Tiler ⭐ NEW

Create grid of repeated textures (2x2, 3x3, etc.) with two modes.

Inputs:

image - Input texture
tile_x (1-8) - Horizontal tile count
tile_y (1-8) - Vertical tile count
scale_to_input (False) - Scale output back to input size

Outputs:

image - Tiled grid texture

Two Modes:

Mode 1: Scale to Input OFF (default)

Output size = Input × (tile_x, tile_y)
Example: 512×512 input, 3×3 tiles → 1536×1536 output
Use for: Creating large texture sheets, high-res previews

Mode 2: Scale to Input ON

Output size = Input size (each tile is smaller)
Example: 512×512 input, 3×3 tiles → 512×512 output (tiles are 170×170)
Use for: Previewing tiling density, testing scale variations

Use Cases:

Preview how textures tile at different scales
Create larger texture sheets (scale OFF)
Test seamless tiling quality
Visualize density/frequency (scale ON)

Tips:

Scale OFF: Best for checking seams at full quality
Scale ON: Best for seeing overall tiling pattern/density
Use after Seamless Tiling Maker to preview results
2x2 is ideal for checking seams
Larger grids (4x4+) useful with scale ON to see pattern repetition

Example Workflows:

MODE 1 (Large Preview):
Load Texture (512×512)
   ↓
Seamless Tiling Maker
   ↓
Texture Tiler (3x3, scale_to_input: OFF)
   ↓
Preview (1536×1536 - see all tiles at full size!)

MODE 2 (Density Preview):
Load Texture (512×512)
   ↓
Seamless Tiling Maker
   ↓
Texture Tiler (4x4, scale_to_input: ON)
   ↓
Preview (512×512 - see how dense the pattern looks!)

24. Texture Equalizer ⭐ NEW

Remove uneven lighting and shadows from textures using High Pass technique.

Inputs:

image - Texture with uneven lighting/shadows
radius (100) - High pass radius for detail preservation (50-150 typical)
strength (1.0) - Effect intensity (0.0=off, 1.0=full, 2.0=exaggerated)
preserve_color (True) - Keep original hue/saturation, only fix brightness
method (overlay) - Blend method: overlay, soft_light, or linear_light

Outputs:

image - Equalized texture with normalized lighting
average_color - Extracted average color (for debugging/visualization)

How It Works: Based on the professional Photoshop technique:

Extracts average color from texture
Applies High Pass filter to isolate details
Inverts high pass and blends using selected method
Optionally preserves original color hue

Parameters Explained:

Radius (50-150):

50 - Gentle correction, preserves gradients
100 - Standard correction ⭐ (recommended)
150 - Aggressive flattening, removes all gradients

Strength (0.0-2.0):

0.0 - No effect (original)
0.5 - Subtle correction
1.0 - Full correction ⭐
2.0 - Exaggerated/stylized

Preserve Color:

ON - Keeps original hue/saturation, fixes only brightness (recommended for albedo)
OFF - Full equalization including color shifts (useful for height maps)

Method (Blend Mode):

overlay - Photoshop standard method ⭐ (recommended)
- Balanced correction, works well for most textures
- Matches the classic Photoshop equalization tutorial
soft_light - Gentle, subtle correction
- Less aggressive than overlay
- Good for textures with mild lighting issues
linear_light - Strong, aggressive correction
- Maximum correction power
- Use for heavily shadowed textures

Use Cases:

Remove shadows from photos taken in uneven lighting
Clean up scanned textures
Prepare textures for seamless tiling (remove lighting variations)
Normalize albedo maps before PBR extraction
Fix height maps with lighting baked in
Remove vignetting from camera photos

Perfect For:

Photos with directional lighting
Textures with cast shadows
Camera vignetting (darker edges)
Uneven illumination from lighting setup
Baked lighting in scans

Before/After Examples:

BEFORE: Photo with shadow on left side, bright on right
AFTER: Evenly lit, shadow removed, details preserved!

BEFORE: Scanned texture with dark edges (vignetting)
AFTER: Uniform brightness edge-to-edge

BEFORE: Height map with baked shadows
AFTER: Clean height data, no lighting artifacts

Pro Tips:

Start with radius: 100, strength: 1.0, preserve_color: ON
For subtle effects, reduce strength to 0.5-0.7
For aggressive flattening, increase radius to 150+
Always enable preserve_color for albedo/diffuse maps
Disable preserve_color for grayscale maps (height, roughness, etc.)
Apply BEFORE making texture seamless for best results

Troubleshooting:

Output too dark/black:
- Try method="overlay" instead of linear_light ⭐
- Check console output for value ranges
- View average_color output to verify extraction
- Try lower radius (30-70)
- Try lower strength (0.5-0.7)
Output washed out:
- Increase radius or strength
- Try method="linear_light" for stronger correction
Colors look wrong: Enable preserve_color
Not enough effect:
- Increase radius to 150-200
- Try method="linear_light"
- Increase strength to 1.5-2.0

Workflow:

Load Photo (uneven lighting)
   ↓
Texture Equalizer
├─ radius: 100
├─ strength: 1.0
└─ preserve_color: ON
   ↓
Seamless Tiling Maker
   ↓
PBR Extractor
   ↓
Perfect material with no shadow artifacts!

Reference: Based on Tolas' Photoshop technique

26. Seamless Tiling Maker

Make textures tile seamlessly with edge mask for inpainting.

Inputs:

image - Input texture
method - mirror (fast), blend_edges (best), offset (simple)
blend_width (0.1) - Edge blend width and mask feathering

Outputs:

image - Seamless texture
edge_mask - White mask showing edge/seam regions (for inpainting)

Methods:

mirror - Flip and average (fast, good for organic)
blend_edges - Smooth edge transitions (best quality)
offset - Shift by half (creates center cross seam)

Edge Mask:

White (1.0) at edges/seams where inpainting would help
Black (0.0) in center where texture is unchanged
Gradient based on blend_width parameter
Perfect for: Inpainting cleanup, selective processing, edge detection

Use Cases:

Game textures (seamless + inpaint mask)
Repeating materials
Inpainting cleanup (use mask to target seams)
Tile-able patterns

27. Square Maker ⭐ NEW

Convert any image to a perfect square by cropping or scaling.

Inputs:

image - Input texture (any dimensions)
method - crop (maintain aspect) or scale (stretch)
square_size - shortest_edge, longest_edge, or custom
custom_size (1024) - Custom square size (64-8192, multiples of 64)
crop_position - 9 positions for crop alignment
scaling_method - bicubic, bilinear, lanczos, nearest

Outputs:

image - Perfect square image

Methods:

Crop (Recommended):

Maintains aspect ratio
Removes excess from edges
No distortion

Choose from 9 crop positions:

Top Left    | Top Center    | Top Right
Middle Left | Center        | Middle Right
Bottom Left | Bottom Center | Bottom Right

Scale:

Stretches to square
No content loss
May distort image
Useful when all content must be preserved

Square Size Modes:

shortest_edge ⭐ Recommended for crop:

Square size = shortest dimension
Example: 1920×1080 → 1080×1080 (crops width)
No quality loss, only crops excess

longest_edge:

Square size = longest dimension
Example: 1920×1080 → 1920×1920 (upscales height if crop, or uses 1920 if custom)
May upscale one dimension

custom:

Specify exact square size
Scales to match, then crops if needed
Perfect for specific requirements (512, 1024, 2048, etc.)

Use Cases:

AI models requiring square inputs (Stable Diffusion, etc.)
Game engines with square texture requirements
Instagram/social media (square format)
Cube maps and skyboxes
Preparing textures for tiling

Examples:

Example 1: Landscape to Square (Crop Center)
Input: 1920×1080 (landscape photo)
Settings:
  - method: crop
  - square_size: shortest_edge
  - crop_position: center
Output: 1080×1080 (center portion, no distortion)

Example 2: Portrait to Square (Crop Top Center)
Input: 1080×1920 (portrait photo, face at top)
Settings:
  - method: crop
  - square_size: shortest_edge
  - crop_position: top_center
Output: 1080×1080 (top portion with face)

Example 3: Exact Size for AI Model
Input: 3000×2000 (any size)
Settings:
  - method: crop
  - square_size: custom
  - custom_size: 1024
  - crop_position: center
Output: 1024×1024 (perfect for SD)

Example 4: Stretch to Square
Input: 1920×1080
Settings:
  - method: scale
  - square_size: longest_edge
Output: 1920×1920 (stretched, all content preserved)

Pro Tips:

Use crop + shortest_edge for no quality loss
Use center position for most images
Use top_center for portraits (keeps faces)
Use bottom_center for landscapes (keeps ground)
Combine with Smart Texture Resizer for GPU-optimized squares
Use custom size for specific AI model requirements

Workflow Example:

Load Image (any size)
   ↓
Square Maker
├─ method: crop
├─ square_size: custom
├─ custom_size: 1024
└─ crop_position: center
   ↓
Smart Texture Resizer (optional)
├─ target_megapixels: 1.0
└─ multiple_of: 64
   ↓
Perfect 1024×1024 texture, GPU-optimized!

28. Smart Texture Resizer ⭐ NEW

Intelligently resize textures to optimal GPU-friendly resolutions.

Inputs:

image - Input texture
target_megapixels (0.25-16.0 MP) - Target size in megapixels
multiple_of - 4, 8, 16, 32, 64, 128, 256 (ensures dimensions are multiples)
resize_mode - fit_within, fit_exact, no_upscale
scaling_method - bicubic, bilinear, lanczos, nearest

Outputs:

image - Optimized texture

Resize Modes:

fit_within - Stay under target MP, never exceed (safe for VRAM limits)
fit_exact - Get as close to target MP as possible
no_upscale - Only downscale, never increase size

Multiple Benefits:

32 - Standard GPU optimization (recommended for most textures)
64 - Extra GPU friendly, some game engines prefer this
16 - Good for smaller textures
8 - AI model compatibility (Stable Diffusion, etc.)
4 - Minimum GPU alignment

Why This Matters:

GPUs process textures most efficiently at multiples of 32
Game engines often require power-of-2 or specific multiples
Reduces VRAM waste and improves performance
AI models (SD, ControlNet) often need multiples of 8/64

Examples:

Input: 1920×1080 (2.07 MP, not GPU optimized)
Target: 2.0 MP, multiple_of: 32
Output: 1536×864 (1.33 MP, both divisible by 32!)

Input: 4096×4096 (16.7 MP, too large)
Target: 4.0 MP, multiple_of: 64
Output: 2048×2048 (4.2 MP, perfect square, divisible by 64!)

Input: 3000×2000 (6.0 MP, odd dimensions)
Target: 4.0 MP, multiple_of: 32, mode: fit_within
Output: 1920×1280 (2.46 MP, GPU optimized)

Use Cases:

Optimize textures for game engines
Prepare images for AI models (SD needs multiples of 8/64)
Reduce VRAM usage while maintaining quality
Ensure GPU-friendly dimensions automatically

29. Texture Scaler

Manual texture resolution scaling.

Inputs:

image - Input texture
scale_factor (0.125-8.0x) - Size multiplier
method - nearest (pixel art), bilinear (fast), bicubic (quality), lanczos (best)

Outputs:

image - Scaled texture

Tips:

Use nearest for pixel art preservation
Use bicubic or lanczos for photographic textures
Scale up to 8x or down to 0.125x
For GPU optimization, use Smart Texture Resizer instead

30. Triplanar Projection ⭐ NEW

Remove UV seams with XYZ projection blending.

Inputs:

image - Input texture
blend_sharpness (1.0) - Transition sharpness
scale (1.0) - Texture tiling

Outputs:

image - Projected texture

Use Cases:

Remove UV seams
Organic surfaces
Procedural textures
Seamless projections

Channel Tools

31. Grayscale to Color ⭐ NEW

Convert grayscale images to RGB by repeating the channel.

Inputs:

grayscale - Single-channel grayscale image

Outputs:

color - RGB image (grayscale repeated across R, G, B)

Use Cases:

Convert height/AO maps to RGB for display
Prepare grayscale for nodes requiring RGB input
Visualization purposes

32. Color to Grayscale ⭐ NEW

Convert RGB images to grayscale using various methods.

Inputs:

color - RGB image
method - luminance (perceptual), average, lightness, red_only, green_only, blue_only

Outputs:

grayscale - Grayscale image (as RGB for display)

Methods:

luminance - Perceptual (Rec. 709: 0.2126R + 0.7152G + 0.0722B) - Best for photos
average - Simple average (R+G+B)/3 - Fast
lightness - (max+min)/2 - Preserves brightness range
red/green/blue_only - Extract single channel

Use Cases:

Convert albedo to grayscale for masks
Create height maps from photos
Channel extraction

33. Channel Packer (RGB)

Pack 3 grayscale maps into RGB channels (saves VRAM).

Inputs:

red_channel - Grayscale map for R
green_channel (optional) - For G
blue_channel (optional) - For B
preset - custom, orm_unity, orm_unreal, rma

Outputs:

packed - RGB packed image

Common Packing:

ORM (Unity): AO(R) + Roughness(G) + Metallic(B)
RMA: Roughness(R) + Metallic(G) + AO(B)

Use Cases:

Reduce texture count for games
Save VRAM
Standard game engine formats

34. Channel Unpacker (RGB)

Extract RGB channels back to grayscale maps.

Inputs:

packed - RGB packed image
output_channels - all, r_only, g_only, b_only, rg, rb, gb

Outputs:

red, green, blue - Extracted channels (as RGB for display)

Use Cases:

Extract from packed textures
Separate channels for editing
Convert ORM back to individual maps

35. Channel Packer (ORMA) ⭐ NEW

Advanced ORM packing with alpha channel support.

Inputs:

occlusion - AO map (R channel)
roughness - Roughness map (G channel)
metallic - Metallic map (B channel)
alpha (optional) - Transparency/mask (A channel, defaults to 1.0 if not provided)

Outputs:

orma_packed - RGBA packed image

Format:

R - Occlusion (AO)
G - Roughness
B - Metallic
A - Alpha (transparency/mask)

Use Cases:

Game engines with transparency support
Vegetation/foliage materials (alpha for cutout)
Decals with transparency
Advanced material packing with masks

Advantage over ORM:

Supports transparency/opacity maps
Perfect for masked materials
4 maps in 1 texture!

36. Channel Packer (RMA) ⭐ NEW

Pack RMA format (alternative to ORM).

Inputs:

roughness - Roughness map (R channel)
metallic - Metallic map (G channel)
ao - Ambient Occlusion map (B channel)

Outputs:

rma_packed - RGB packed image

Format:

R - Roughness
G - Metallic
B - AO (Ambient Occlusion)

Use Cases:

Some game engines prefer RMA over ORM
Alternative channel layout
Consistency with certain workflows

RMA vs ORM:

RMA: Roughness, Metallic, AO
ORM: AO, Roughness, Metallic
Same maps, different channel order

37. Channel Packer (RMAA) ⭐ NEW

Advanced RMA packing with alpha channel support.

Inputs:

roughness - Roughness map (R channel)
metallic - Metallic map (G channel)
ao - AO map (B channel)
alpha (optional) - Transparency/mask (A channel, defaults to 1.0 if not provided)

Outputs:

rmaa_packed - RGBA packed image

Format:

R - Roughness
G - Metallic
B - AO (Ambient Occlusion)
A - Alpha (transparency/mask)

Use Cases:

RMA format with transparency support
Vegetation/foliage materials (alpha for cutout)
Decals with transparency
Alternative to ORMA with different channel order

RMAA vs ORMA:

RMAA: Roughness, Metallic, AO, Alpha
ORMA: AO, Roughness, Metallic, Alpha
Both support 4 channels, different channel order preference

38. Channel Unpacker (RMA) ⭐ NEW

Unpack RMA format back to individual maps.

Inputs:

rma_packed - RGB packed RMA image

Outputs:

roughness - Extracted roughness (as RGB for display)
metallic - Extracted metallic (as RGB for display)
ao - Extracted AO (as RGB for display)

Use Cases:

Extract from RMA packed textures
Edit individual RMA channels
Convert RMA to separate maps for processing

Additional Processing

39. Height Processor (Lotus)

Process Lotus depth output.

Inputs:

lotus_depth - Lotus output
invert - Flip values
bit_depth - 8, 16, or 32-bit

Outputs:

height - Processed height map

💡 Emission Maps

NEW in v2.1! Full emission map support throughout the PBR pipeline.

What are Emission Maps?

Self-illuminated/glowing parts of materials
Used for lights, screens, lava, neon signs, glowing eyes, etc.
Not affected by scene lighting

Usage:

Load Emission Texture
   ↓
PBR Combiner
├─ albedo: (your albedo)
├─ normal: (your normal)
├─ roughness: (your roughness)
├─ metallic: (your metallic)
└─ emission: (glowing parts) ⭐
   ↓
PBR Pipe → Game Engine

Common Uses:

Screens/Monitors - Emissive UI elements
Lights - Light fixtures, bulbs, LEDs
Lava/Fire - Glowing hot materials
Neon Signs - Bright glowing text
Sci-Fi - Glowing panels, energy effects
Magic Effects - Glowing runes, spells

Workflow Example:

Albedo → Brightness/Contrast → Mask bright areas → Emission map
                                                      ↓
                                            PBR Combiner (emission input)

🎮 Example Workflows

⚡ Quick Start (Fastest)

Load Image
   ↓
   ├─> Marigold (appearance) ─┐
   └─> Marigold (lighting) ────┼─> PBR Extractor ──> PBR Saver ──> Preview Image
                               │      (pbr_pipe)        (images)     (view all)
                               └─ Done in 3 nodes!

🎯 Complete Workflow (Recommended)

Load Image
   ↓
   ├─> Marigold (appearance) ─┐
   ├─> Marigold (lighting) ────┼─> PBR Extractor ──> pbr_pipe ─┐
   ├─> Lotus (normal) ─────────┤                                │
   └─> Lotus (height) ─────────┘                                ↓
                                                    PBR Combiner (merge)
                                                    ├─ pbr_pipe
                                                    ├─ normal (Lotus)
                                                    └─ height (Lotus)
                                                                ↓
                                                    Height to Normal ──┐
                                                    (generate backup)  │
                                                                ↓      ↓
                                                    PBR Pipeline Adjuster
                                                    ├─ ao_strength_albedo: 1.0
                                                    ├─ roughness_strength: 1.2
                                                    ├─ albedo_saturation: 1.1
                                                    └─ normal_strength: 1.0
                                                                ↓
                                                    PBR Pipe Preview ──> Preview
                                                    (check before save)
                                                                ↓
                                                    PBR Saver
                                                    ├─ base_name: "material_name"
                                                    └─ format: png
                                                                ↓
                                                    Preview Image
                                                    (final review)

🎨 Advanced: Material Mixing

Material A (pbr_pipe) ─┐
                       ├─> PBR Material Mixer ──> mixed_pipe
Material B (pbr_pipe) ─┤     ├─ blend_mode: overlay
Mask (optional) ───────┘     ├─ strength: 0.5
                             └─ mask: (optional)

🛠️ Advanced: Weathering & Wear

PBR Pipe ──> Curvature Generator ──┐
              (from normal/height)  │
                                   ├─> Wear Generator ──> worn_pipe
AO Map ───────────────────────────┘    ├─ edge_wear: 0.7
                                        ├─ dirt_strength: 0.3
                                        └─ wear_strength: 0.5

📦 Advanced: Channel Packing

Roughness ──┐
            ├─> Channel Packer ──> ORM_packed.png
Metallic ───┤    (preset: orm_unity)
AO ─────────┘    R=AO, G=Roughness, B=Metallic

🎨 Advanced: Stylized Materials

Height Map ──> Gradient Map ──> Color Ramp ──> Stylized Albedo
               ├─ min: 0.2     (heat preset)
               └─ max: 0.8

💡 Pro Tips

Extraction & Quality

Washed out maps? Adjust gamma_metal_rough (try 1.2-1.6)
Better AO? Use AO Approximator with height + normal, 24-32 samples
Sharper normals? Use method=scharr in Height to Normal converter
Cross-platform normals? Use Normal Format Converter

Material Enhancement

Realistic wear: Curvature Generator → Wear Generator (edge_wear=0.7)
Weathering: Set ao_strength_roughness=0.3 in Pipeline Adjuster
Add detail: Detail Map Blender with RNM mode for normals
Seamless textures: Seamless Tiling Maker with blend_edges method

Color & Appearance

Color variations: HSV Adjuster (hue_shift for different colors)
Vibrant materials: Increase albedo_saturation (1.2-1.5)
Stylized look: Color Ramp with custom gradients or presets
Heat maps: Color Ramp heat preset on AO or height

Workflow Optimization

Clean workflow: Use Pipeline system (fewer connections)
Debug easily: PBR Pipe Preview at any stage
Batch materials: PBR Saver enumerate mode
Save VRAM: Channel Packer for ORM textures

Advanced Techniques

Layer materials: PBR Material Mixer with masks
Procedural damage: Gradient Map → Color Ramp → Wear Generator
Detail layers: Base → Detail Map Blender (x3) → fine detail
Smart masks: Curvature + Gradient Map for precise selections

🎯 Common Use Cases

Game Development

Optimize textures: Channel Packer (ORM format)
Tile-able materials: Seamless Tiling Maker
LOD textures: Texture Scaler for multiple resolutions
Batch export: PBR Saver with enumerate mode

Architectural Visualization

Weathered materials: Wear Generator + Curvature
Detail enhancement: Detail Map Blender
Material variations: HSV Adjuster + Material Mixer
High precision: Save as EXR (32-bit)

3D Printing

Height maps: Normal to Depth Converter
Clean normals: Normal Format Converter
Seamless patterns: Seamless Tiling Maker + Triplanar Projection

VFX & Film

Material layering: Material Mixer with masks
Procedural aging: Wear Generator + Gradient Maps
Color grading: HSV Adjuster + Color Ramp
High-res export: Texture Scaler + EXR format

🔧 Technical Details

PBR_PIPE Format

Internal dictionary structure:

{
    'albedo': IMAGE tensor,
    'normal': IMAGE tensor,
    'ao': IMAGE tensor,
    'height': IMAGE tensor,
    'roughness': IMAGE tensor,
    'metallic': IMAGE tensor,
    'lighting': IMAGE tensor,
    'transparency': IMAGE tensor
}

Image Formats

PNG: 8-bit, standard
JPG: 8-bit, compressed
EXR: 16/32-bit, lossless
TIFF: 16-bit, compatible

Performance Notes

Color Ramp: Fully GPU-accelerated (100x faster than v1.0)
Channel Packing: Instant, no quality loss
Integration methods: CPU-intensive (Normal to Depth hybrid mode recommended)
Wear Generator: GPU-accelerated, scales with resolution

✅ Requirements

Included with ComfyUI:

PyTorch (GPU acceleration)
PIL (image I/O)
NumPy (array processing)
imageio (format support)

Optional for source inputs: