Hugging Face's logo

Spaces:
ghmk
/
character_forge
Sleeping

App Files Community
character_forge / RELEASE_NOTES.md
ghmk's picture
ghmk
Initial deployment of Character Forge
5b6e956
preview code
|
raw
history blame contribute delete
7.79 kB

Character Forge - Release Version

Release Date: November 2025 Version: 1.0.0 License: Apache 2.0

🎉 What's Included

This is the first official release of Character Forge, ready for:

  • ✅ Local installation on Windows/Linux/Mac
  • ✅ Deployment to HuggingFace Spaces
  • ✅ Integration into your own projects
  • ✅ Commercial use (Apache 2.0 licensed)

🚀 Key Features

Character Forge

Transform a single image into a complete multi-angle character sheet:

  • 2 facial views (front + side)
  • 3 body views (front + side + rear)
  • Automatic composition into single sheet
  • ~2-3 minutes generation time
  • Professional quality results

Composition Assistant

Smart multi-image composition with AI-generated prompts:

  • Upload 1-3 images
  • Auto-detect image types
  • Generate professional compositions
  • Minimal manual work required

Standard Interface

Direct text-to-image and image-to-image generation:

  • 10 aspect ratios supported
  • Temperature control (0.0-1.0)
  • High-quality output
  • Fast generation

Library Management

Organize and reuse your assets:

  • Save characters, backgrounds, styles
  • Quick access for compositions
  • Build your creative library

🔧 Backend Support

Gemini API (Cloud) - Default

  • No local installation needed
  • High quality results
  • ~$0.03 per image
  • Free tier available (1,500 requests/day)

ComfyUI (Local) - Optional

  • Complete control
  • No per-image costs
  • GPU required
  • Advanced workflows

📦 Installation

Quick Start - Local

Windows:

install.bat
set GEMINI_API_KEY=your-key-here
start.bat

Linux/Mac:

./install.sh
export GEMINI_API_KEY=your-key-here
./start.sh

HuggingFace Spaces

See docs/HUGGINGFACE_DEPLOYMENT.md

📚 Documentation

Complete documentation included:

  • README.md - Overview and quick start
  • docs/QUICK_START.md - 5-minute getting started guide
  • docs/API_KEY_SETUP.md - Complete API key setup instructions
  • docs/HUGGINGFACE_DEPLOYMENT.md - HF Spaces deployment guide
  • LICENSE - Apache 2.0 license
  • NOTICE - Third-party licenses

🔒 Security & Privacy

Your Privacy

  • API keys are YOUR responsibility
  • Use environment variables or HF Secrets
  • Never commit keys to version control
  • See docs/API_KEY_SETUP.md for best practices

🎯 Use Cases

Game Development

  • Character reference sheets for NPCs
  • Environment backgrounds
  • Texture variations
  • Scene composition

Animation

  • Character sheets for consistency
  • Background art generation
  • Style references
  • Storyboard composition

Creative Projects

  • Story illustration
  • Concept art development
  • Visual worldbuilding
  • Character design iteration

💰 Cost Estimation

Gemini API

  • Single image: ~$0.03
  • Character sheet: ~$0.15 (5 images)
  • Composition: ~$0.03-0.06
  • Free tier: 1,500 requests/day

HuggingFace Spaces

  • CPU Basic: Free
  • CPU Upgrade: $0.03/hour ($21/month 24/7)
  • Persistent storage: Free up to 50GB

🛠️ Technical Stack

Frontend

  • Streamlit: Modern Python web framework
  • PIL/Pillow: Image processing
  • NumPy: Array operations

Backend

  • Google Gemini API: AI image generation
  • ComfyUI (optional): Local generation
  • WebSocket: ComfyUI communication

Configuration

  • YAML: Configuration files
  • TOML: Streamlit configuration
  • Environment variables: Secret management

📋 Requirements

System Requirements

  • Python: 3.10 or higher
  • RAM: 2GB minimum, 4GB recommended
  • Storage: 500MB for app, more for outputs
  • Network: Internet connection (for Gemini API)

Python Dependencies

See requirements.txt for complete list:

  • streamlit >= 1.31.0
  • google-genai >= 0.3.0
  • Pillow >= 10.0.0
  • numpy >= 1.24.0
  • And more...

Optional

  • GPU: For local ComfyUI backend
  • Git: For cloning and updates

🐛 Known Issues

Current Limitations

  • ComfyUI backend requires manual setup
  • Maximum 3 images per composition
  • 20MB max file size per image
  • Rate limits on free tier (15/min, 1500/day)

Planned Improvements

  • More backend options
  • Batch processing
  • API endpoint for programmatic access
  • Video generation support
  • Improved caching

🤝 Contributing

We welcome contributions!

How to Contribute

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Test thoroughly
  5. Submit a pull request

What We're Looking For

  • Bug fixes
  • Documentation improvements
  • New features
  • Performance optimizations
  • UI/UX enhancements

Code Style

  • Follow PEP 8
  • Add docstrings
  • Include type hints
  • Write tests where possible

📄 License

Apache License 2.0

  • ✅ Commercial use allowed
  • ✅ Modification allowed
  • ✅ Distribution allowed
  • ✅ Private use allowed
  • ⚠️ Must include license and notice
  • ⚠️ Changes must be documented

See LICENSE for full text.

🙏 Acknowledgments

This project builds on amazing open-source work:

  • Google Gemini API - AI image generation
  • Streamlit - Web framework
  • ComfyUI - Local generation pipeline
  • Python community - Countless libraries

Thank you to all contributors and users!

📞 Support

Getting Help

  • Documentation: Check /docs folder first
  • Issues: Report bugs on GitHub
  • Discussions: Ask questions on GitHub Discussions
  • API Help: https://ai.google.dev/

Reporting Bugs

Include:

  • Description of the issue
  • Steps to reproduce
  • Expected vs actual behavior
  • Screenshots if applicable
  • System info (OS, Python version)

🗺️ Roadmap

Version 1.1 (Planned)

  • Batch processing
  • More aspect ratios
  • Improved caching
  • Performance optimizations

Version 1.2 (Planned)

  • REST API endpoint
  • Multiple backend support improvements
  • Advanced composition features
  • Better error handling

Version 2.0 (Future)

  • Video generation
  • Animation support
  • Advanced character persistence
  • Web-based editor

🎓 Learning Resources

For Beginners

  • Start with docs/QUICK_START.md
  • Follow the examples
  • Experiment with different settings
  • Join the community

For Developers

  • Check the code documentation
  • Study the plugin system
  • Review the architecture
  • Contribute improvements

For Artists

  • Explore different prompts
  • Experiment with temperature
  • Build your style library
  • Share your creations

📊 Project Stats

  • Lines of Code: ~15,000+
  • Files: 50+
  • Documentation: 5 major guides
  • Dependencies: 15+ packages
  • Supported Platforms: Windows, Linux, Mac, HuggingFace
  • License: Apache 2.0 (permissive)

🌟 Success Stories

We'd love to hear how you're using Character Forge!

Share your projects:

  • Tag us on social media
  • Post in GitHub Discussions
  • Include in your project credits

⚡ Quick Tips

For Best Results

  1. Use clear, well-lit source images
  2. Start with temperature 0.4
  3. Be specific in prompts
  4. Save good results to library
  5. Experiment and iterate

Performance

  1. Close other applications
  2. Use reasonable image sizes
  3. Consider local backend for heavy use
  4. Monitor API quotas

Cost Optimization

  1. Preview before generating
  2. Use lower temperature (fewer retries)
  3. Batch similar tasks
  4. Reuse library assets

🎯 Next Steps

After installation:

  1. ✅ Get your Gemini API key
  2. ✅ Run the installation scripts
  3. ✅ Generate your first image
  4. ✅ Try the character sheet feature
  5. ✅ Build your asset library
  6. ✅ Integrate into your workflow
  7. ✅ Share your creations!

Thank you for using Character Forge! Happy creating! 🎨

For the latest updates, visit our GitHub repository.