SpinForge AI

SpinForge AI is an AI-assisted 360° object and logo spin video generator built with Python, Flask, Pillow, OpenCV, FFmpeg, and intelligent frame-based rendering. Upload an image, choose a rotation style, optionally remove the background, pick a solid background color, and export a browser-compatible MP4.

A single flat image cannot create true 3D side and back views. SpinForge AI creates clean 2D 360-style motion loops. For true object 360° output, use multi-angle photography or a 3D model workflow.

Features

• Stable centered 360° frame rendering with no object drift.
• Optional AI background removal with rembg.
• Solid custom HEX background color.
• Center Circular 360, Horizontal 360, Vertical 360, and Smooth Logo 360 modes.
• FFmpeg H.264 MP4 encoding with yuv420p and faststart.
• OpenCV fallback encoder when FFmpeg is unavailable.
• UUID file names, secure upload validation, rate limiting, and temporary file cleanup.
• Responsive, step-based Flask/Jinja frontend.
• SEO-ready pages, Open Graph metadata, Twitter cards, JSON-LD, sitemap, and robots.txt.

Screenshots

Add screenshots after deployment:

• docs/screenshots/homepage.png
• docs/screenshots/generator.png
• docs/screenshots/result-preview.png

Tech Stack

• Python 3.11+
• Flask
• Jinja templates
• Pillow
• OpenCV
• FFmpeg
• rembg / onnxruntime
• HTML5, CSS3, JavaScript
• SQLite for local generation history

Installation

pip install -r requirements.txt

Local Setup

python app.py

Open:

http://localhost:5000/tools/image-to-360-spin-video

FFmpeg Setup

FFmpeg is recommended for production-quality MP4 output.

Windows:

1. Download FFmpeg from https://ffmpeg.org/download.html.
2. Add the bin folder to your system PATH.
3. Verify with ffmpeg -version.

macOS:

brew install ffmpeg

Linux:

sudo apt update
sudo apt install ffmpeg

Usage Guide

1. Open the generator page.
2. Upload a JPG, PNG, JPEG, or WEBP image.
3. Choose whether to remove the background.
4. Pick a solid HEX background color.
5. Select a 360 rotation style.
6. Generate the video.
7. Preview and download the MP4.

Rotation Modes

• Center Circular 360: continuously rotates the image plane from 0° to 360°.
• Horizontal 360: creates a front-edge-mirrored-back-edge-front visual illusion from one image.
• Vertical 360: creates a front-edge-flipped-back-edge-front visual illusion from one image.
• Smooth Logo 360: continuous center rotation with subtle scale breathing.

Background Removal Logic

Background removal is optional and disabled by default.

• Disabled: the complete uploaded image is resized, centered, and rendered on the chosen background color.
• Enabled: rembg removes the background, alpha bbox detection crops the object once, and the object is normalized on a fixed transparent canvas before frames are rendered.

API Endpoints

• GET /
• GET /generate
• GET /tools/image-to-360-spin-video
• POST /api/upload
• POST /api/generate
• GET /outputs/<filename>
• GET /privacy-policy
• GET /terms
• GET /contact
• GET /robots.txt
• GET /sitemap.xml

Success response:

{
  "success": true,
  "video_url": "/outputs/generated_xxx.mp4",
  "frame_count": 150,
  "message": "Video generated successfully"
}

Error response:

{
  "success": false,
  "message": "Readable error message"
}

Project Structure

spinforge-ai/
├── app.py
├── requirements.txt
├── README.md
├── LICENSE
├── .gitignore
├── .env.example
├── utils/
│   ├── object_spin_generator.py
│   ├── validators.py
│   └── cleanup.py
├── templates/
│   ├── base.html
│   ├── index.html
│   ├── generate.html
│   ├── privacy.html
│   ├── terms.html
│   └── contact.html
├── static/
│   ├── css/
│   ├── js/
│   └── images/
├── uploads/
└── outputs/

Deployment Guide

SpinForge AI can be deployed on a VPS, behind Nginx, or behind Cloudflare Tunnel.

Recommended production stack:

• Gunicorn or another WSGI server
• Nginx reverse proxy
• HTTPS via Let's Encrypt or Cloudflare
• FFmpeg installed on the server
• Writable uploads/, outputs/, outputs/frames/, and data/ directories

Example Gunicorn command:

gunicorn app:app --config gunicorn.conf.py

Koyeb Deployment

SpinForge AI is Koyeb-ready and should be deployed with Docker for reliable FFmpeg and OpenCV system dependencies.

Required Environment Variables

FLASK_ENV=production
SECRET_KEY=change-this-random-secret
MAX_UPLOAD_MB=25
OUTPUT_RETENTION_HOURS=6
PORT=8000

Docker Deployment on Koyeb

1. Push the code to GitHub:

https://github.com/itisuniqueofficial-gh/spinforge-ai

2. Open the Koyeb dashboard.
3. Create a new app.
4. Choose the GitHub repository.
5. Select Dockerfile deployment.
6. Set service type to Web Service.
7. Set port to 8000.
8. Add the environment variables listed above.
9. Deploy.
10. Test these URLs:

/health
/tools/image-to-360-spin-video

Koyeb Docker Settings

Use these values in the Docker configuration screen:

Dockerfile location: Dockerfile
Entrypoint override: leave empty
Command override: leave empty
Target override: leave empty
Work directory override: leave empty
Exposed port: 8000

The Dockerfile already defines:

WORKDIR /app
CMD ["gunicorn", "app:app", "--config", "gunicorn.conf.py"]

Do not run python app.py on Koyeb. The production service should start with Gunicorn.

Local Docker Test

docker build -t spinforge-ai .
docker run -p 8000:8000 --env PORT=8000 spinforge-ai

Open:

http://localhost:8000/health
http://localhost:8000/tools/image-to-360-spin-video

Storage Warning

Koyeb's filesystem is ephemeral. Files in uploads/, outputs/, and outputs/frames/ can be deleted on restart or redeploy.

For permanent production storage, use S3/R2-compatible object storage such as Cloudflare R2.

Performance Notes

Video generation is CPU-heavy. Recommended production limits:

• Maximum duration: 10 seconds
• Maximum FPS: 30
• Maximum upload size: 25MB
• One Gunicorn worker
• Cleanup old generated files regularly

Buildpack Deployment

Buildpack deployment can work only if FFmpeg and required OpenCV libraries are available. Docker deployment is recommended because the Dockerfile installs FFmpeg and required system libraries explicitly.

Security Notes

• Never expose SECRET_KEY.
• Do not commit .env.
• Validate uploads with extension and Pillow image verification.
• Keep upload limits enabled.
• Use a production WSGI server instead of Flask debug mode.
• Keep generated files temporary and clean them regularly.

Contributing

1. Fork the repository.
2. Create a branch: git checkout -b feature/your-feature.
3. Commit your changes.
4. Push your branch.
5. Open a pull request.

See CONTRIBUTING.md for details.

Credits

Made with love by It Is Unique Official.

• GitHub Organization: https://github.com/itisuniqueofficial-gh
• Project: https://github.com/itisuniqueofficial-gh/spinforge-ai

License

This project is licensed under the MIT License. See LICENSE for details.