---
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:
```bash
git clone <repository-url>
cd HF-Spaces
```

2. Install dependencies:
```bash
npm install
```

3. Start the development server:
```bash
npm run dev
```

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

## 🐳 Docker Deployment

### Using Docker Compose (Recommended)

For development:
```bash
docker-compose up dev
```

For production:
```bash
docker-compose up app
```

### Using Docker directly

Build and run:
```bash
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](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.