ComfyUI-TextureAlchemy

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

1. Copy ComfyUI_PBR_MaterialProcessor folder to ComfyUI/custom_nodes/
2. Restart ComfyUI
3. 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:

1. Extracts average color from texture
2. Applies High Pass filter to isolate details
3. Inverts high pass and blends using selected method
4. 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

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

Material Enhancement

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

Color & Appearance

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

Workflow Optimization

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

Advanced Techniques

17. Layer materials: PBR Material Mixer with masks
18. Procedural damage: Gradient Map → Color Ramp → Wear Generator
19. Detail layers: Base → Detail Map Blender (x3) → fine detail
20. 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:

• ComfyUI_Marigold- kijai
• ComfyUI_Lotus -kijai