README.md

metadata

title: HF-Shapes
emoji: 🟥
colorFrom: purple
colorTo: blue
sdk: docker
pinned: false

3D Interactive Scene

3D Interactive Scene is a captivating web application that lets you explore and customize stunning 3D geometries in real-time through your browser.

Built with React and Three.js, this interactive experience allows you to choose from six different 3D shapes (cube, sphere, torus, icosahedron, octahedron, and dodecahedron), customize their colors and textures, adjust animation speeds and scales, and toggle beautiful visual effects like bloom and chromatic aberration.

With intuitive mouse controls for navigation, dynamic lighting, procedural textures, and a sleek modern interface, it's perfect for anyone interested in 3D graphics, creative experimentation, or simply enjoying mesmerizing interactive art.

Whether you're a developer learning 3D web technologies, an artist exploring digital forms, or just someone who loves beautiful interactive experiences, this application offers an engaging way to play with 3D geometry and visual effects right in your web browser.

✨ Features

• Interactive 3D Geometries: Choose from multiple shapes including cube, sphere, torus, icosahedron, octahedron, and dodecahedron
• Real-time Customization: Adjust colors, textures, animation speed, and scale
• Visual Effects: Toggle post-processing effects including bloom and chromatic aberration
• Responsive Design: Modern UI with Tailwind CSS styling
• Orbital Controls: Navigate around the 3D scene with mouse/touch controls
• Dynamic Lighting: Advanced lighting setup with ambient, point, and spot lights
• Procedural Textures: Custom Voronoi noise textures for enhanced visual appeal

🚀 Quick Start

Prerequisites

• Node.js 18 or higher
• npm or yarn package manager

Installation

1. Clone the repository:

git clone <repository-url>
cd HF-Spaces

2. Install dependencies:

npm install

3. Start the development server:

npm run dev

4. Open your browser and navigate to http://localhost:5173

🐳 Docker Deployment

Using Docker Compose (Recommended)

For development:

docker-compose up dev

For production:

docker-compose up app

Using Docker directly

Build and run:

docker build -t 3d-scene .
docker run -p 7860:7860 3d-scene

🛠️ Available Scripts

• npm run dev - Start development server
• npm run build - Build for production
• npm run preview - Preview production build
• npm run lint - Run ESLint

🎮 Usage

1. Geometry Selection: Choose from 6 different 3D shapes using the geometry buttons
2. Color Customization: Use the color picker to change the object's color
3. Texture Toggle: Switch between wireframe and textured materials
4. Animation Speed: Adjust rotation speed with the slider
5. Scale Control: Resize the object using the scale slider
6. Visual Effects: Toggle post-processing effects for enhanced visuals
7. Camera Controls:
   • Left mouse: Rotate view
   • Right mouse: Pan
   • Scroll: Zoom in/out

🏗️ Tech Stack

• Frontend Framework: React 18 with TypeScript
• 3D Graphics: Three.js with React Three Fiber
• 3D Utilities: React Three Drei for common 3D components
• Post-processing: React Three Postprocessing for visual effects
• Styling: Tailwind CSS
• Icons: Lucide React
• Build Tool: Vite
• Deployment: Docker with Nginx

📁 Project Structure

HF-Spaces/
├── src/
│   ├── components/
│   │   └── Scene.tsx          # Main 3D scene component
│   ├── App.tsx                # Root application component
│   ├── main.tsx              # Application entry point
│   └── index.css             # Global styles
├── public/                   # Static assets
├── docker-compose.yml        # Docker composition
├── Dockerfile               # Production Docker image
├── start.sh                # Application startup script
└── package.json            # Dependencies and scripts

🎨 Customization

Adding New Geometries

To add a new 3D shape:

1. Add the geometry type to the ShapeProps interface in Scene.tsx
2. Update the getGeometry() function with your new shape
3. Add the corresponding option to geometryOptions array

Modifying Visual Effects

The application uses React Three Postprocessing for effects. You can customize or add new effects in the EffectComposer section of the SceneContent component.

Texture Customization

The createVoronoiTexture() function generates procedural textures. Modify this function to create different patterns and materials.

🌐 Deployment

This project is optimized for deployment on Hugging Face Spaces:

• Default port: 7860 (configurable via PORT environment variable)
• Health checks included for container orchestration
• Optimized build process with fallback npm configurations
• Static file serving with serve package

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

This project is open source and available under the MIT License.

🔧 Troubleshooting

Common Issues

• Build fails: Try npm install --legacy-peer-deps if you encounter peer dependency issues
• Port conflicts: Change the port in docker-compose.yml or set the PORT environment variable
• Performance issues: Reduce the number of stars in the scene or disable post-processing effects

Performance Optimization

• The application automatically adjusts device pixel ratio for optimal performance
• Post-processing effects can be disabled for better performance on lower-end devices
• Geometry complexity can be reduced by modifying the geometry arguments

📞 Support

If you encounter any issues or have questions, please open an issue in the repository or contact the maintainers.

---

Built with ❤️ using React, Three.js, and modern web technologies.