updated

README.md

@@ -7,32 +7,180 @@ sdk: docker
 pinned: false
 ---
 
-# HF-Shapes
+# 3D Interactive Scene
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+3D Interactive Scene is a captivating web application that lets you explore and customize stunning 3D geometries in real-time through your browser.
 
-## Docker Setup
+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.
 
-This project uses Docker for containerization. The default configuration runs on port 7860 which is compatible with Hugging Face Spaces.
+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.
 
-### Running with Docker
+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
-# Build and start the container
-docker compose up app
+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
 
-# For development with hot-reloading
-docker compose up dev
+- `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
 ```
 
-### Environment Variables
+## 🎨 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.
 
-- `PORT`: The port on which the server will run (default: 7860)
+## 🌐 Deployment
 
-### Troubleshooting
+This project is optimized for deployment on Hugging Face Spaces:
 
-If you encounter issues with the container starting:
+- 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.
+
+---
 
-1. Check if the port 7860 is already in use
-2. Ensure the application built successfully
-3. Review the container logs for more details
+Built with ❤️ using React, Three.js, and modern web technologies.