DevDex
Explore
← BACK
@krtxnsh / spiral-dome

spiral-dome

TypeScript ⭐ 0
▶ Demo </> Source

README

Open on GitHub ↗

🌐 Spatial Dome

An immersive 3D photo sphere experience powered by hand tracking and gesture controls. Transform your memories into an interactive spatial gallery where you control the view with your hands.

MIT License
React
Three.js
MediaPipe

✨ Features

🎯 Core Functionality

  • 3D Photo Sphere: Images arranged in a beautiful Fibonacci sphere distribution
  • Hand Tracking: Real-time hand detection and gesture recognition using MediaPipe
  • Gesture Controls:
    • ✋ Open hand to rotate the sphere
    • ✊ Fist to zoom in/out
    • 👋 Swipe/wave to spin with momentum
  • Smart Image Upload: Drag-and-drop or click to upload multiple images
  • Persistent Storage: Your images are saved locally using localStorage

🚀 Performance Optimizations

Intelligent Image Processing

The app implements a sophisticated image optimization system to reduce memory usage while maintaining visual quality:

  • Smart Resizing: Images are automatically resized to 1024px on the longest edge (1K texture = ~4MB VRAM)
  • Format Conversion: All images are converted to WebP format with 80% quality for superior compression
  • Lazy Loading: Full-resolution images are only loaded when in focus, dramatically reducing memory usage
  • Mobile-Optimized: Special handling for mobile devices with lower VRAM capacities

Note: Your original images remain untouched on your device. The optimization only affects the in-app display to ensure smooth performance across all devices.

Performance Features
  • Adaptive Frame Rates:
    • Desktop: 30 FPS hand tracking
    • Mobile: 15 FPS to conserve battery
  • Smooth Motion: Advanced interpolation and dampening for jitter-free controls
  • GPU Acceleration: Uses GPU delegates for MediaPipe hand detection
  • Responsive Design: Optimized layouts for both mobile and desktop

🎮 How to Use

  1. Grant Camera Permission: Allow access to your webcam when prompted
  2. Upload Images: Click "Add Images" to upload your photos
  3. Control with Gestures:
    • Show your hand to the camera
    • Move your hand to rotate the sphere
    • Make a fist to zoom in
    • Wave or swipe quickly to give the sphere momentum
  4. Touch/Mouse Controls: The sphere also supports traditional mouse/touch controls

🛠️ Tech Stack

  • Frontend Framework: React 19.2.4 with TypeScript
  • 3D Rendering: Three.js 0.182.0 via React Three Fiber
  • Hand Tracking: MediaPipe Tasks Vision 0.10.14
  • Build Tool: Vite 6.2.0
  • UI Components: Lucide React for icons
  • Analytics: Vercel Analytics

📦 Installation

Prerequisites

  • Node.js (v16 or higher)
  • A webcam for hand tracking features

Steps

  1. Clone the repository:
git clone https://github.com/itsmeved24/Spatial-Dome.git
cd Spatial-Dome
  1. Install dependencies:
npm install
  1. Start the development server:
npm run dev
  1. Open your browser and navigate to the local development URL (typically http://localhost:5173)

🏗️ Build for Production

npm run build

The optimized production build will be in the dist folder.

🎨 Architecture

Key Components

  • App.tsx: Main application component managing state and localStorage
  • PhotoSphere.tsx: 3D scene with camera controls and sphere rendering
  • SphereItem.tsx: Individual photo items with hover effects
  • HandTracker.tsx: MediaPipe integration for hand detection and gesture recognition
  • UploadUI.tsx: File upload interface with drag-and-drop support
  • imageProcessor.ts: Smart image optimization and compression utilities

Data Flow

  1. User uploads images → processImage() optimizes them
  2. Processed images stored in localStorage as Base64
  3. Images positioned using Fibonacci sphere algorithm
  4. Hand tracking updates camera position/rotation in real-time
  5. Gesture strength controls zoom level smoothly

🔒 Privacy

  • Local-First: All images are processed and stored locally in your browser
  • No Server Upload: Your photos never leave your device
  • Camera-Only: Hand tracking uses your camera but doesn't record or transmit video

📱 Browser Compatibility

  • ✅ Chrome/Edge (Recommended)
  • ✅ Safari (iOS and macOS)
  • ✅ Firefox
  • ⚠️ Requires webcam access for gesture controls

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🤝 Contributing

Contributions, issues, and feature requests are welcome! Feel free to check the issues page.

👨‍💻 Author

Ved

🙏 Acknowledgments

  • MediaPipe team for the amazing hand tracking library
  • Three.js community for the powerful 3D rendering engine
  • React Three Fiber for the seamless React integration

Made with ❤️ by Vansia

📜 Full License Text

MIT License

Copyright (c) 2026 Vansia

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.