ComfyUI Extension: ComfyUI Globetrotter Nodes
A collection of custom ComfyUI nodes and utilities for generating AI image prompts representing the diverse attire, cultures, regions, and appearances of the world. This project is designed for easy extension to new countries, cultures, and body parts, using a modular JSON-based data structure and dynamic node generation.
Custom Nodes (0)
README
ComfyUI Globetrotter Nodes
A comprehensive collection of custom ComfyUI nodes for generating culturally diverse AI image prompts. This project features a fully data-driven architecture with gender-aware attire filtering, comprehensive body part coverage, and intelligent prompt generation optimized for AI image models.
⨠Key Features
š Cultural Diversity & Authenticity
- Multi-Country Support: Dynamic nodes for countries with extensive cultural data
- Regional Variations: Detailed appearance options for different regions within countries
- Cultural Context: Activities, festivals, landmarks, and traditional colors
- Authentic Attire: Culturally accurate clothing options with detailed descriptions
š Advanced Attire System
- Gender-Aware Filtering: Clothing options automatically filter based on selected gender
- Comprehensive Body Coverage: Support for 18+ body parts including:
- Arms: Forearm, Hands, Palms, Upper_Arm, Wrists
- Head: Head, Chin, Ears, Forehead, Hair, Nose
- Legs: Legs, Ankles, Feet
- Upper_Body: Upper_Body, Chest, Shoulders
- Waist: Waist area clothing
- Rich Descriptions: Each attire item includes detailed descriptions for AI prompt generation
- Smart Randomization: Intelligent random selection with contextual awareness
š¤ AI-Optimized Prompt Generation
- Multiple Prompt Styles: AI-friendly, creative, artistic, technical, and balanced modes
- Smart Defaults: Intelligent parameter combinations that work well together
- Contextual Suggestions: Weather-activity and emotion-setting pairings
- Technical Enhancements: Quality keywords, composition rules, and lighting optimization
- LLM Integration: Optional prompt rewriting with local language models
šļø Intuitive Controls
- Simplified UI: Clear, logical control grouping with helpful tooltips
- Universal Options: Every dropdown includes "none" and "random" options
- Smart Randomization: Four levels of randomization (off, light, moderate, full)
- Reproducible Results: Seed-based consistency for repeatable outputs
- Gender-Aware Interface: Attire options automatically filtered by gender selection
š Data-Driven Architecture
- Fully Modular: All data stored in organized JSON files
- Zero Hardcoding: No attire, cultural, or prompt data in Python code
- Easy Extension: Add new countries, body parts, or attire by updating JSON files
- Robust Loading: Error-tolerant JSON loading with graceful fallbacks
š Project Structure
comfyui-globetrotter/
āāā data/ # Organized data files
ā āāā attire/ # Clothing and accessories by body part
ā ā āāā arms/ # Forearm, hands, palms, upper_arm, wrists
ā ā āāā head/ # Head, chin, ears, forehead, hair, nose
ā ā āāā legs/ # Legs, ankles, feet
ā ā āāā upper_body/ # Upper_body, chest, shoulders
ā ā āāā waist/ # Waist area clothing
ā āāā appearance/ # Regional appearance data
ā āāā poses/ # Country-specific poses
ā āāā cultural/ # Cultural activities, festivals, landmarks
ā āāā config/ # System configuration
ā ā āāā gender_config.json # Gender mapping and filtering rules
ā ā āāā prompt_config.json # Prompt generation settings
ā āāā generation/ # AI prompt optimization
ā ā āāā smart_defaults.json # Intelligent default combinations
ā ā āāā contextual_suggestions.json # Context-aware suggestions
ā ā āāā ai_prompt_structure.json # AI-optimized prompt structure
ā āāā ui/ # User interface data
ā ā āāā dynamic_node_options.json # UI dropdown options
ā ā āāā weather_moods.json # Atmospheric conditions
ā ā āāā complementary_colors.json # Color palette suggestions
ā āāā styles/ # Artistic and photographic styles
ā āāā prompts/ # LLM prompt templates
āāā globetrotter_nodes/ # Core Python modules
ā āāā dynamic_nodes.py # Main dynamic node generation
ā āāā ollama_llm_node.py # LLM integration node
ā āāā text_combiner_node.py # Text utility node
āāā requirements.txt # Python dependencies
š Installation
-
Clone the repository into your ComfyUI
custom_nodes
directory:cd /path/to/ComfyUI/custom_nodes git clone <repository-url> comfyui-globetrotter
-
Install dependencies (optional but recommended for full features):
cd comfyui-globetrotter pip install -r requirements.txt
-
Restart ComfyUI to load the new nodes.
š” Usage
Dynamic Country Nodes
Each country automatically gets its own node (e.g., "India Attire") with comprehensive options:
Core Parameters
- Age: Young adult, Adult
- Gender: Female, Male (with automatic attire filtering)
- Region: Country-specific regions (e.g., Java, Punjab, Rajasthan)
- Hair Style: Generic options + region-specific defaults
- Emotion: Confident, Serene, Joyful, Contemplative, etc.
Attire Selection (Gender-Filtered)
Individual dropdowns for each body part with culturally appropriate options:
- Arms: Forearm decorations, hand accessories, wrist jewelry
- Head: Headwear, face decorations, ear accessories
- Upper Body: Traditional tops, chest accessories, shoulder pieces
- Lower Body: Traditional bottoms, leg wear, foot attire
- Waist: Belts, sashes, waist decorations
Cultural Context
- Poses: Traditional and cultural poses
- Cultural Elements: Festivals, activities, traditions
- Settings: Markets, temples, landmarks, urban areas
- Atmosphere: Weather, lighting, mood combinations
Advanced Controls
- Detail Level: Basic, Detailed, Cinematic, Artistic, Photorealistic
- Composition: Rule of thirds, Centered, Close-up, Wide shot, etc.
- Prompt Optimization: AI-friendly, Creative, Technical, Artistic, Balanced
- Randomization: Off, Light, Moderate, Full (with smart contextual choices)
- Custom Elements: LoRA triggers, custom prompts
- Experimental: AI-powered prompt rewriting (requires transformers library)
Example Attire JSON Structure
data/attire/upper_body/in.json
{
"country": "IN",
"body_part": "upper_body",
"attires": [
{
"name": "Saree Blouse",
"type": "clothing",
"description": "A fitted upper garment worn under a saree, often short-sleeved or sleeveless, and tailored to match the saree.",
"material": ["cotton", "silk", "synthetic"],
"region": ["Nationwide"],
"gender": ["female"],
"occasion": ["daily wear", "wedding", "festival"]
},
{
"name": "Kurta",
"type": "clothing",
"description": "A loose-fitting, long tunic worn by both men and women, often paired with churidar or jeans.",
"material": ["cotton", "silk", "linen"],
"region": ["Nationwide"],
"gender": ["male", "female", "unisex"],
"occasion": ["daily wear", "casual", "formal"]
}
]
}
data/appearance/in.json
{
"country": "IN",
"regions": [
{
"name": "Punjab",
"description": "People from Punjab. Features include wheat-colored to medium brown skin and strong facial structure.",
"skin_tone": "wheat-colored to medium brown",
"hair": "black, thick and wavy"
},
{
"name": "South India",
"description": "People from Tamil Nadu, Kerala, Karnataka, and Andhra Pradesh. Features include dark to very dark skin.",
"skin_tone": "dark to very dark brown",
"hair": "black, thick and curly"
}
]
}
Gender-Aware Attire Filtering
The system automatically filters attire options based on the selected gender:
- Female: Shows items with
gender: ["female"]
orgender: ["unisex"]
- Male: Shows items with
gender: ["male"]
orgender: ["unisex"]
- Validation: Inappropriate combinations are automatically skipped during prompt generation
Utility Nodes
Text Combiner Node
- Combines multiple text inputs into a single formatted string
- Useful for complex prompt construction workflows
Ollama LLM Node
- Advanced prompt enhancement using local Ollama language models
- Includes artistic styles, camera settings, lighting options
- Dynamic loading of style configurations from JSON files
Smart Prompt Generation
AI-Optimized Output Examples
AI-Friendly Mode:
Highly detailed, best quality, rule of thirds composition, A young adult female from Punjab, India, with a confident expression, wearing Saree Blouse: A fitted upper garment worn under a saree, often short-sleeved or sleeveless, and Churidar: Traditional fitted trousers, atmosphere: golden hour
Creative Mode:
Rule of thirds composition, Highly detailed, A young adult female from the Punjab region of India, wearing Saree Blouse: A fitted upper garment worn under a saree and Churidar: Traditional fitted trousers, with a confident expression, color palette: warm earth tones, golden natural colors, atmosphere: golden hour
š§ Adding New Content
Adding a New Country
-
Create country entry in
data/countries.json
:{ "name": "Country Name", "code": "cc", "flag": "šØšØ" }
-
Add appearance data in
data/appearance/cc.json
:{ "country": "cc", "regions": [ { "name": "Region Name", "description": "Physical description", "skin_tone": "skin tone description", "hair": "hair description" } ] }
-
Create attire files in appropriate body part directories:
data/attire/head/cc.json
data/attire/upper_body/cc.json
data/attire/legs/cc.json
- etc.
-
Add cultural context (optional):
data/poses/cc.json
data/cultural/cc.json
-
Restart ComfyUI to load the new country node.
Adding New Attire Items
- Edit the appropriate JSON file (e.g.,
data/attire/head/in.json
) - Add new attire object:
{ "name": "Attire Name", "type": "clothing", "description": "Detailed description for AI prompts", "material": ["cotton", "silk"], "region": ["Region1", "Region2"], "gender": ["male", "female", "unisex"], "occasion": ["daily wear", "formal", "festival"] }
- Restart ComfyUI to load the new options.
Extending Body Part Coverage
- Create new directory under
data/attire/
(e.g.,accessories/
) - Add country-specific JSON files with the new
body_part
field - System automatically detects and includes new body parts in UI
ā” Advanced Features
Experimental LLM Rewriting
- Toggle Option: Each node includes
experimental_llm_rewrite
- Local Models: Uses Hugging Face
distilgpt2
model when available - Smart Filtering: Automatic repetition detection and removal
- Length Control: Output length limits based on prompt optimization mode
- Graceful Fallback: Silently skips if dependencies are missing
Intelligent Randomization
- Smart Random Mode: Context-aware random selections
- Seed Control: Fixed, increment, decrement, or system random
- Contextual Pairing: Weather-activity and emotion-setting combinations
- Optimal Defaults: Age-gender combinations that work well together
Prompt Optimization Modes
| Mode | Purpose | Style | |------|---------|-------| | AI-Friendly | Stable Diffusion, FLUX | Quality keywords first, clear structure | | Creative | Artistic generation | Narrative flow, artistic language | | Technical | Professional workflows | Precise technical terms | | Artistic | Fine art creation | Museum-quality descriptions | | Balanced | General purpose | Mix of technical and creative |
Configuration System
data/config/gender_config.json
{
"gender_mappings": {
"male": ["male", "unisex"],
"female": ["female", "unisex"],
"non-binary": ["unisex"]
}
}
data/config/prompt_config.json
{
"technical_enhancements": {
"detailed": "8k resolution, highly detailed",
"cinematic": "professional photography, cinematic lighting"
},
"detail_prefixes": {
"ai_friendly": {
"detailed": "highly detailed, best quality, "
}
}
}
š ļø Technical Details
Dynamic Node Generation
- Factory Pattern: Nodes created programmatically for each country
- Closure-Based: Input types capture country-specific data
- Memory Efficient: Data loaded once and cached
- Error Tolerant: Graceful handling of missing files
Gender Validation System
- Runtime Filtering: Attire validated during prompt generation
- File Discovery: Automatic detection of correct attire file paths
- Cross-Reference: Body part mapping across directory structure
- Fallback Options: Safe defaults when validation fails
Data Loading Architecture
- Lazy Loading: JSON files loaded only when needed
- Caching: Frequent data cached in memory
- Error Recovery: Default values for missing files
- Validation: Schema checking for critical fields
š Requirements
Core Dependencies
torch>=1.9.0 # PyTorch for tensor operations
torchvision>=0.10.0 # Computer vision utilities
transformers>=4.0.0 # Hugging Face transformers (for LLM features)
requests>=2.25.0 # HTTP requests for Ollama API
Optional Dependencies
accelerate # Faster model loading
safetensors # Secure tensor serialization
Installation:
pip install -r requirements.txt
System Requirements
- Python: 3.8 or higher
- ComfyUI: Latest version recommended
- Memory: 4GB+ RAM for LLM features
- Storage: ~50MB for full dataset
š¤ Contributing
Guidelines
- Follow JSON Schema: Maintain consistent data structure
- Cultural Sensitivity: Ensure authentic and respectful representation
- Test Additions: Verify new content works across gender combinations
- Documentation: Update relevant documentation for new features
Code Style
- Python: Follow PEP 8 conventions
- JSON: Use 2-space indentation
- Comments: Document complex logic and cultural context
Pull Request Process
- Fork the repository
- Create feature branch (
git checkout -b feature/new-country
) - Add your changes with appropriate tests
- Update documentation
- Submit pull request with detailed description
š License
This project is licensed under the MIT License - see the LICENSE file for details.
š Acknowledgments
- Cultural Consultants: For authentic attire and cultural information
- ComfyUI Community: For feedback and feature requests
- Open Source Libraries: Transformers, PyTorch, and other dependencies
- Contributors: Everyone who has helped expand the cultural database
š Support
- Issues: GitHub Issues
- Discussions: GitHub Discussions
- Documentation: This README and inline code comments
Made with ā¤ļø for the ComfyUI community