Image Prompt Orchestration System

A powerful Python system for automating image prompt variations with 20 plug-and-play lighting modifiers and unlimited style transformations.

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

# No external dependencies required - uses Python standard library
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"

---

License

MIT License - Free for commercial and personal use

Support

For issues or feature requests, please provide:

1. Your base prompt
2. Desired modifier/transformation
3. Expected vs actual output

---

Version History

• v1.0 - Initial release with 20 modifiers, style system, batch processing, CLI