{"id":29996548,"url":"https://github.com/eddieoz/bananaforge","last_synced_at":"2025-08-17T21:34:29.799Z","repository":{"id":303433466,"uuid":"1011889772","full_name":"eddieoz/BananaForge","owner":"eddieoz","description":"🎨 Professional AI-powered multi-layer 3D printing optimization tool that converts 2D images into optimized multi-layer 3D models for color printing with advanced transparency mixing.","archived":false,"fork":false,"pushed_at":"2025-07-23T07:37:21.000Z","size":395,"stargazers_count":3,"open_issues_count":1,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-16T06:29:38.523Z","etag":null,"topics":["3d-printer","3d-printing","3dprinting","art","cli-app","cuda","hueforge","machine-learning","python"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/eddieoz.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-07-01T13:40:37.000Z","updated_at":"2025-08-11T18:58:03.000Z","dependencies_parsed_at":"2025-07-07T16:28:00.237Z","dependency_job_id":"09e76628-afe2-483a-8eda-7309cda4bbaa","html_url":"https://github.com/eddieoz/BananaForge","commit_stats":null,"previous_names":["eddieoz/bananaforge"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/eddieoz/BananaForge","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eddieoz%2FBananaForge","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eddieoz%2FBananaForge/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eddieoz%2FBananaForge/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eddieoz%2FBananaForge/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/eddieoz","download_url":"https://codeload.github.com/eddieoz/BananaForge/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eddieoz%2FBananaForge/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":270912460,"owners_count":24666737,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-17T02:00:09.016Z","response_time":129,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["3d-printer","3d-printing","3dprinting","art","cli-app","cuda","hueforge","machine-learning","python"],"created_at":"2025-08-05T02:47:31.535Z","updated_at":"2025-08-17T21:34:29.779Z","avatar_url":"https://github.com/eddieoz.png","language":"Python","funding_links":["https://www.buymeacoffee.com/eddieoz"],"categories":[],"sub_categories":[],"readme":"# BananaForge\n\n🎨 **Professional AI-powered multi-layer 3D printing optimization tool** that converts 2D images into optimized multi-layer 3D models for color printing with advanced transparency mixing.\n\n[![Version](https://img.shields.io/badge/version-1.0.0-blue.svg)]()\n[![Python](https://img.shields.io/badge/python-3.8%2B-blue.svg)]()\n[![PyTorch](https://img.shields.io/badge/PyTorch-2.0%2B-red.svg)]()\n[![License](https://img.shields.io/badge/license-MIT-green.svg)]()\n\n## ✨ What Makes BananaForge Special\n\nBananaForge uses cutting-edge AI optimization to create multi-color 3D prints with **30% fewer material swaps** and professional-quality results:\n\n- 🧠 **AI-Powered Optimization**: PyTorch-based differentiable optimization with Gumbel softmax sampling\n- 🌈 **Advanced Transparency Mixing**: Create more colors with fewer materials through strategic layer transparency\n- 🎯 **Intelligent Material Selection**: LAB color space optimization for perceptual accuracy\n- ⚡ **GPU Acceleration**: CUDA and MPS support for fast processing\n- 📊 **Professional Output**: STL files, HueForge projects, detailed cost analysis\n\n## 🚀 Quick Start\n\n```bash\n# Install BananaForge\npip install -e .\n\n# Convert your first image\nbananaforge convert photo.jpg --materials materials.csv\n\n# With transparency mixing for fewer material swaps\nbananaforge convert photo.jpg --enable-transparency --materials materials.csv --max-materials 6\n```\n\n## 🎨 Advanced Transparency Features\n\nBananaForge introduces **transparency-based color mixing** that revolutionizes multi-color 3D printing:\n\n### Three-Layer Opacity Model\n- **33% opacity**: Light transparency for subtle color mixing\n- **67% opacity**: Medium transparency for gradient effects  \n- **100% opacity**: Full color for vibrant base layers\n\n### Smart Material Savings\n- **30%+ reduction** in material swaps\n- **Intelligent base layer** optimization for maximum contrast\n- **Gradient detection** for smooth color transitions\n- **Cost analysis** with detailed savings reports\n\n```bash\n# Enable transparency features with full options\nbananaforge convert image.jpg \\\n  --enable-transparency \\\n  --opacity-levels \"0.33,0.67,1.0\" \\\n  --optimize-base-layers \\\n  --enable-gradients \\\n  --materials materials.csv \\\n  --max-materials 6 \\\n  --max-layers 25 \\\n  --mixed-precision \\\n  --export-format \"stl,instructions,cost_report,transparency_analysis\" \\\n  --output ./transparent_model/\n```\n\n## 🛠 Installation\n\n### Development Installation (Current)\n```bash\ngit clone https://github.com/eddieoz/BananaForge.git\ncd BananaForge\npip install -e .[dev]\n```\n\n### Verify Installation\n```bash\nbananaforge version\nbananaforge --help\n```\n\n## 🏗 Architecture Overview\n\n### Core Components\n- **Enhanced Optimization Engine**: Discrete validation, learning rate scheduling, mixed precision\n- **Advanced Image Processing**: LAB color space, saturation enhancement, color-preserving resize\n- **Intelligent Height Map System**: Two-stage K-means clustering, multi-threaded initialization\n- **Transparency Mixing System**: Physics-based alpha compositing, gradient processing\n- **Professional Output**: STL with alpha support, HueForge projects, detailed analytics\n\n### Key Technologies\n- **PyTorch**: Differentiable optimization with automatic mixed precision\n- **LAB Color Space**: Perceptually uniform color calculations\n- **Gumbel Softmax**: Discrete optimization with gradient flow\n- **Multi-threading**: Parallel processing for complex operations\n\n## 📚 Documentation\n\n- **[Quick Start Guide](docs/quickstart.md)** - Get started in 5 minutes\n- **[Materials Guide](docs/materials.md)** - Managing filaments and color matching\n- **[CLI Reference](docs/cli-reference.md)** - Complete command reference\n- **[API Reference](docs/api-reference.md)** - Python programming interface\n- **[Configuration](docs/configuration.md)** - Advanced settings and workflows\n- **[Examples](docs/examples/README.md)** - Real-world usage examples\n\n## 🧪 Testing\n\n```bash\n# Run all tests\npytest tests/ -v\n\n# Run with coverage\npytest tests/ --cov=bananaforge --cov-report=html\n\n# Run specific feature tests\npytest tests/test_feature4_5_transparency_color_mixing.py -v\n```\n\n## 🤝 Contributing\n\nWe welcome contributions! This project follows TDD/BDD development practices.\n\n1. **Fork the repository**\n2. **Create a feature branch**: `git checkout -b feature/amazing-feature`\n3. **Write tests first**: Follow our BDD scenarios in `tests/`\n4. **Implement features**: Make tests pass\n5. **Submit a pull request**\n\n## 📄 License\n\nMIT License - see [LICENSE](LICENSE) for details.\n\n## 🙏 Acknowledgments\n\n- Built with ❤️ using PyTorch and modern AI techniques\n- Inspired by the 3D printing and computer vision communities\n- Special thanks to HueForge and Autoforge for pioneering multi-color 3D printing workflows\n\n## Buy me a coffee\nDid you like it? [Buy me a coffee](https://www.buymeacoffee.com/eddieoz)\n\n[![Buy me a coffee](https://ipfs.io/ipfs/QmR6W4L3XiozMQc3EjfFeqSkcbu3cWnhZBn38z2W2FuTMZ?filename=buymeacoffee.webp)](https://www.buymeacoffee.com/eddieoz)\n\nOr drop me a tip through Lightning Network: ⚡ [getalby.com/p/eddieoz](https://getalby.com/p/eddieoz)","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feddieoz%2Fbananaforge","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Feddieoz%2Fbananaforge","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feddieoz%2Fbananaforge/lists"}