A powerful ComfyUI custom node package for automating image prompt variations with 20 plug-and-play lighting modifiers and unlimited style transformations.

🔗 GitHub Repository: https://github.com/MushroomFleet/ComfyUI-Variationator

Features

20 Pre-defined Lighting Modifiers (anchor-agnostic, DRY/WET categories)
Style Transformation Engine with 10+ built-in templates
Batch Processing for multiple prompts
Smart Variation with natural language intents
Multiple Export Formats (JSON, CSV, TXT)
CLI Interface for quick automation
Preset Collections for common use cases

Quick Start

Installation for ComfyUI

cd ComfyUI/custom_nodes
git clone https://github.com/MushroomFleet/ComfyUI-Variationator.git
# Restart ComfyUI - nodes will appear under "Prompt Orchestration" category

For detailed installation instructions, see INSTALLATION.md.

For ComfyUI-specific usage guide, see README_COMFYUI.md.

Python API Usage

# The core engine can also be used standalone
python prompt_orchestrator.py  # Run demo

Basic Usage (Python API)

from prompt_orchestrator import PromptOrchestrator

orchestrator = PromptOrchestrator()

# Apply a lighting modifier
base = "Sports car on coastal highway"
golden_hour = orchestrator.apply_lighting_modifier(base, 7)
print(golden_hour)
# → "Sports car on coastal highway, golden hour, warm low-angle side-light, clear sky"

# Apply style transformation
cyberpunk = orchestrator.apply_style_transformation(base, "cyberpunk")
print(cyberpunk)
# → "Transform to cyberpunk aesthetic with neon lights... Base scene: Sports car..."

# Smart variation with natural language
result = orchestrator.smart_variation(base, "make it a wet night scene")
print(result)

Command Line Interface

# Single modifier
python cli.py --prompt "Luxury sedan in urban setting" --modifier 7

# All DRY modifiers
python cli.py --prompt "Modern architecture" --category dry --output results.json

# Style transformation
python cli.py --prompt "Vintage motorcycle" --style noir

# Preset collection
python cli.py --prompt "Product photography" --preset commercial

# Batch process from file
python cli.py --input-file prompts.txt --category all --output batch.csv

# Smart variation
python cli.py --prompt "Car on street" --smart "golden hour with warm lighting"

Lighting Modifiers Reference

DRY Category (1-16): Universal, Clear Conditions

ID	Description
1	sunrise, car-friendly side-light, clear sky
2	early morning, subtle back-light along the road axis, clear sky
3	late morning, high-sun hard light for crisp body lines, clear sky
4	midday, crisp hard sunlight, clear sky
5	early afternoon, gentle side-light, clear sky
6	late afternoon, long shadow geometry, clear sky
7	golden hour, warm low-angle side-light, clear sky
8	sunset, soft rim-lit edges, clear sky
9	twilight, residual glow, clear sky
10	blue hour, deep clear sky
11	night, clear sky with clean highlights
12	moonlit night, clear sky
13	early morning, three-quarter back-light, clear sky
14	late afternoon, subtle back-light along the road axis, clear sky
15	evening, car-friendly side-light, clear sky
16	dawn, clean low-haze air, clear sky

WET Category (17-20): Low-Light, Wet Conditions

ID	Description
17	predawn blue hour, wet road, subtle back-light along the road axis
18	blue hour, wet road, car-friendly side-light
19	twilight, wet road, residual glow, clear sky
20	night, wet street, clear sky (buildings visible → warm interior lights glowing)

Style Templates

Built-in style transformations:

pop_art_1960s - Bright colors, bold graphics, commercial aesthetics
bauhaus - Geometric forms, primary colors, modernist principles
art_deco - Geometric patterns, luxurious details, streamlined forms
cyberpunk - Neon lights, high-tech elements, dystopian atmosphere
minimalist - Clean lines, negative space, essential elements only
impressionist - Visible brushstrokes, emphasis on light
noir - Dramatic shadows, high contrast, moody atmosphere
futuristic - Sleek forms, advanced materials, sci-fi elements
vintage - Retro colors, grain, nostalgic atmosphere
brutalist - Raw concrete, geometric forms, bold structure

Custom styles can be added using free-form descriptions.

API Documentation

PromptOrchestrator Class

Core Methods

apply_lighting_modifier(base_prompt, modifier_id, preserve_base=True)

result = orchestrator.apply_lighting_modifier(
    "Modern building exterior", 
    modifier_id=7,  # Golden hour
    preserve_base=True  # Append vs replace
)

apply_style_transformation(base_prompt, style, maintain_composition=True)

result = orchestrator.apply_style_transformation(
    "Vintage car in garage",
    style="cyberpunk",
    maintain_composition=True
)

generate_variation_batch(base_prompt, modifier_ids=None, include_styles=None)

variations = orchestrator.generate_variation_batch(
    "Sports car on highway",
    modifier_ids=[1, 7, 18],  # Specific modifiers
    include_styles=["noir", "cyberpunk"]
)
# Returns list of dicts with keys: id, type, category, description, prompt

smart_variation(base_prompt, intent)

result = orchestrator.smart_variation(
    "Car on street",
    intent="make it golden hour with dramatic lighting"
)

Utility Methods

get_modifiers_by_category(category: ModifierCategory)

from prompt_orchestrator import ModifierCategory

dry_mods = orchestrator.get_modifiers_by_category(ModifierCategory.DRY)
wet_mods = orchestrator.get_modifiers_by_category(ModifierCategory.WET)

get_modifiers_by_tags(tags: List[str])

night_mods = orchestrator.get_modifiers_by_tags(["night", "moonlit"])

export_variations(variations, format="txt")

output = orchestrator.export_variations(variations, format="json")
print(output)

BatchProcessor Class

Methods

process_single_prompt(base_prompt, config)

from batch_processor import BatchProcessor

processor = BatchProcessor(output_dir="my_prompts")

config = {
    "lighting_ids": "all",  # or [1,7,18] or "dry" or "wet"
    "styles": ["cyberpunk", "noir"],
    "export_format": "json"
}

variations = processor.process_single_prompt("Base prompt here", config)

process_multiple_prompts(prompts, config, output_filename)

prompts = [
    "Sports car on highway",
    "Modern building exterior",
    "Product photography setup"
]

output_path = processor.process_multiple_prompts(
    prompts=prompts,
    config=config,
    output_filename="batch_output"
)

create_preset_collection(base_prompt, preset)

# Available presets:
# - "full_day_cycle": All DRY modifiers
# - "wet_night": All WET modifiers  
# - "key_moments": Selected dramatic moments
# - "commercial": Best for commercial photography
# - "artistic": Artistic lighting + style variations

variations = processor.create_preset_collection(
    "Product shot", 
    preset="commercial"
)

generate_comparison_set(base_prompt, modifier_pairs)

comparisons = processor.generate_comparison_set(
    "Architecture shot",
    modifier_pairs=[
        (4, 7),   # Midday vs Golden Hour
        (11, 18)  # Night dry vs Night wet
    ]
)

Use Cases & Examples

1. Automotive Photography Variations

orchestrator = PromptOrchestrator()

base = "Luxury sports car on mountain road, dramatic landscape"

# Generate complete day cycle
variations = orchestrator.generate_variation_batch(
    base, 
    modifier_ids=list(range(1, 17))  # All DRY modifiers
)

# Add wet night variations for drama
wet_variations = orchestrator.generate_variation_batch(
    base,
    modifier_ids=[17, 18, 19, 20]
)

2. Product Photography Set

processor = BatchProcessor()

products = [
    "Smartwatch on minimal white surface",
    "Luxury perfume bottle with reflections",
    "Designer sunglasses, clean background"
]

# Use commercial preset for all
for product in products:
    vars = processor.create_preset_collection(product, "commercial")
    # vars contains optimal lighting for product shots

3. Architectural Visualization

base = "Modern glass office building, urban context"

# Morning through evening progression
morning_to_evening = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]

variations = orchestrator.generate_variation_batch(
    base,
    modifier_ids=morning_to_evening
)

# Add style variations
style_vars = orchestrator.generate_variation_batch(
    base,
    modifier_ids=[7],  # Just golden hour
    include_styles=["brutalist", "minimalist", "futuristic"]
)

4. Batch Processing from File

Create prompts.txt:

Sports car on coastal highway
Modern architecture, glass facade
Vintage motorcycle in garage
Product photography, minimal setup

Then process:

python cli.py --input-file prompts.txt --category all --output results.csv

5. Smart Variation Examples

base = "Car parked on city street"

# Natural language variations
variants = [
    orchestrator.smart_variation(base, "make it golden hour"),
    orchestrator.smart_variation(base, "convert to wet night scene"),
    orchestrator.smart_variation(base, "cyberpunk style"),
    orchestrator.smart_variation(base, "morning sunrise lighting")
]

Advanced Features

Custom Pipelines

Create custom transformation sequences:

def add_fog(prompt):
    return f"{prompt}, atmospheric fog, reduced visibility"

def add_motion_blur(prompt):
    return f"{prompt}, motion blur effect, dynamic"

# Apply custom pipeline
result = orchestrator.create_custom_pipeline(
    "Sports car on track",
    transformations=[
        lambda p: orchestrator.apply_lighting_modifier(p, 7),
        add_fog,
        add_motion_blur
    ]
)

Filtering and Querying

# Get all night modifiers
night_mods = orchestrator.get_modifiers_by_tags(["night"])

# Get all side-light modifiers
side_light = orchestrator.get_modifiers_by_tags(["side-light"])

# Combine multiple tags
dramatic = orchestrator.get_modifiers_by_tags(["golden-hour", "sunset", "blue-hour"])

Comparison Sets for A/B Testing

processor = BatchProcessor()

# Generate comparison pairs
comparisons = processor.generate_comparison_set(
    "Product on pedestal",
    modifier_pairs=[
        (3, 7),   # Hard light vs Golden hour
        (4, 11),  # Midday vs Night
        (7, 18)   # Golden hour dry vs Blue hour wet
    ]
)

# Each comparison contains variant_a and variant_b with full prompts

CLI Command Reference

List Commands

# List all modifiers
python cli.py --list-modifiers

# List all styles
python cli.py --list-styles

Single Prompt Commands

# Apply specific modifier
python cli.py -p "Your prompt here" -m 7

# Apply category
python cli.py -p "Your prompt" -c dry

# Apply multiple specific modifiers
python cli.py -p "Your prompt" --modifiers 1,7,18

# Apply style
python cli.py -p "Your prompt" -s cyberpunk

# Use preset
python cli.py -p "Your prompt" --preset key_moments

# Smart variation
python cli.py -p "Your prompt" --smart "make it golden hour"

Batch Commands

# Process file with all modifiers
python cli.py -i prompts.txt -c all -o results.json

# Process file with DRY only
python cli.py -i prompts.txt -c dry -f csv -o dry_only.csv

# Process with preset
python cli.py -i prompts.txt --preset commercial -o commercial.txt

Output Options

# Print to stdout
python cli.py -p "Prompt" -m 7 --print-only

# Save to specific file
python cli.py -p "Prompt" -c all -o my_results.json

# Choose format explicitly
python cli.py -p "Prompt" -c all -f csv -o output.csv

Export Formats

JSON Format

[
  {
    "base_prompt": "Sports car on highway",
    "variations": [
      {
        "id": "lighting_7",
        "type": "lighting",
        "category": "dry",
        "description": "golden hour, warm low-angle side-light, clear sky",
        "prompt": "Sports car on highway, golden hour, warm low-angle side-light, clear sky"
      }
    ]
  }
]

CSV Format

base_prompt,variation_id,type,category,description,prompt
"Sports car","lighting_7","lighting","dry","golden hour...","Sports car, golden hour..."

TXT Format

BASE PROMPT: Sports car on highway
================================================================================

[lighting_7] LIGHTING - dry
Description: golden hour, warm low-angle side-light, clear sky
Prompt: Sports car on highway, golden hour, warm low-angle side-light, clear sky
--------------------------------------------------------------------------------

Best Practices

1. Choose the Right Modifier Category

DRY modifiers (1-16): Universal, work with any subject
WET modifiers (17-20): Dramatic, best for urban/street scenes with reflections

2. Layering Transformations

# Good: Layer lighting + style
base = orchestrator.apply_lighting_modifier("Base prompt", 7)
final = orchestrator.apply_style_transformation(base, "cyberpunk", maintain_composition=False)

# Better: Use batch generation
variations = orchestrator.generate_variation_batch(
    "Base prompt",
    modifier_ids=[7],
    include_styles=["cyberpunk"]
)

3. Preset Selection

Commercial: Product shots, crisp lighting (modifiers 3, 4, 7, 11)
Key Moments: Portfolios, dramatic variety (1, 7, 8, 10, 18, 20)
Full Day Cycle: Time-lapse visualization (all DRY modifiers)
Artistic: Creative projects (golden hour + styles)

4. Batch Processing Efficiency

# Efficient: Process all prompts with same config
processor.process_multiple_prompts(
    prompts=large_prompt_list,
    config=single_config,
    output_filename="bulk_output"
)

# Less efficient: Loop with individual processing

Contributing & Customization

Adding Custom Modifiers

from prompt_orchestrator import LightingModifier, ModifierCategory

custom_mod = LightingModifier(
    id=21,
    description="stormy weather, dramatic dark clouds, side-light",
    category=ModifierCategory.DRY,
    tags=["storm", "dramatic", "weather"]
)

orchestrator.modifiers[21] = custom_mod

Adding Custom Styles

orchestrator.custom_style_templates["my_style"] = \
    "custom aesthetic with specific characteristics"

# Use it
result = orchestrator.apply_style_transformation(base, "my_style")

Performance Notes

In-memory processing: All operations are fast, no external API calls
Batch operations: Optimized for processing hundreds of prompts
No dependencies: Uses only Python standard library

Troubleshooting

Q: My prompts are too long

# Use preserve_base=False to replace instead of append
result = orchestrator.apply_lighting_modifier(base, 7, preserve_base=False)

Q: I need specific lighting combinations

# Create custom pipeline
def custom_combo(p):
    # Your custom logic
    return modified_prompt

result = orchestrator.create_custom_pipeline(base, [custom_combo, ...])

Q: Smart variation not working as expected

# Smart variation uses keyword matching - be specific
# Good: "make it golden hour with warm side light"
# Less good: "make it nice"

ComfyUI Integration

This package provides 9 custom nodes for ComfyUI:

Lighting Modifier (Single) - Apply precise lighting to prompts
Batch Variation Generator - Generate multiple variations at once
Style Transform - Apply artistic styles
Smart Variation (NLP) - Natural language prompt modification
Preset Collection - Optimized modifier sets
Modifier Info - Display modifier information
Prompt Combiner - Merge text inputs
Random Modifier - Apply random modifiers with seed control
Multi-Style Layer - Layer multiple styles

See README_COMFYUI.md for detailed ComfyUI usage.

License

MIT License - Free for commercial and personal use

Support

For issues or feature requests, please open an issue on GitHub: https://github.com/MushroomFleet/ComfyUI-Variationator

Version History

v1.0.0 - Initial release with 20 modifiers, style system, batch processing, CLI, and 9 ComfyUI nodes

Citation

https://github.com/MushroomFleet/ComfyUI-Variationator

📚 Citation

Academic Citation

If you use this codebase in your research or project, please cite:

@software{comfyui_variationator,
  title = {ComfyUI Variationator: automating image prompt variations},
  author = {[Drift Johnson]},
  year = {2025},
  url = {https://github.com/MushroomFleet/ComfyUI-Variationator},
  version = {1.0.0}
}

README.md

ComfyUI Variationator