{"id":31684461,"url":"https://github.com/akash1331/3d-viewer","last_synced_at":"2026-04-13T21:31:29.308Z","repository":{"id":317589303,"uuid":"1068056092","full_name":"akash1331/3d-viewer","owner":"akash1331","description":"A modern and interactive 3D model viewer.","archived":false,"fork":false,"pushed_at":"2025-10-02T16:49:53.000Z","size":8473,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-12T03:43:54.576Z","etag":null,"topics":["3d","camera","gltf-viewer","obj-viewer","reactjs","threejs","typescript"],"latest_commit_sha":null,"homepage":"https://3dvi.netlify.app/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/akash1331.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-01T19:37:47.000Z","updated_at":"2025-10-02T16:49:57.000Z","dependencies_parsed_at":null,"dependency_job_id":"2eef0453-4e67-45c2-ba6a-ef9123534d34","html_url":"https://github.com/akash1331/3d-viewer","commit_stats":null,"previous_names":["akash1331/3d-viewer"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/akash1331/3d-viewer","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/akash1331%2F3d-viewer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/akash1331%2F3d-viewer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/akash1331%2F3d-viewer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/akash1331%2F3d-viewer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/akash1331","download_url":"https://codeload.github.com/akash1331/3d-viewer/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/akash1331%2F3d-viewer/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31771803,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-13T20:17:16.280Z","status":"ssl_error","status_checked_at":"2026-04-13T20:17:08.216Z","response_time":93,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["3d","camera","gltf-viewer","obj-viewer","reactjs","threejs","typescript"],"created_at":"2025-10-08T08:08:30.819Z","updated_at":"2026-04-13T21:31:29.299Z","avatar_url":"https://github.com/akash1331.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🎥 3D Viewer\r\n\r\nA modern, interactive 3D model viewer built with React, Three.js, and TypeScript. This application provides advanced camera controls, multiple viewport layouts, and comprehensive 3D model loading capabilities.\r\n\r\n## 🌟 Features\r\n\r\n### 🎯 **Core Functionality**\r\n- **Multi-format 3D Model Support**: Load OBJ, GLTF/GLB, FBX, STL, and PLY files\r\n- **Interactive 3D Viewport**: Real-time 3D rendering with orbit controls\r\n- **Advanced Camera System**: Multiple camera positions with smooth transitions\r\n- **Camera Animation**: Create custom camera animations with keyframes\r\n- **Responsive Design**: Optimized for different screen sizes\r\n\r\n### 📸 **Camera Management**\r\n- **Preset Camera Views**: Front, Back, Top, Left, Right views\r\n- **Custom Camera Positions**: Create and save custom viewing angles\r\n- **Camera Settings**: Adjustable FOV, near/far planes, and frustum visualization\r\n- **Smooth Transitions**: Animated camera movements between positions\r\n- **Camera Frustum Visualization**: Visual representation of camera viewing area\r\n\r\n### 🎬 **Animation System**\r\n- **Keyframe Animation**: Create smooth camera animations between multiple positions\r\n- **Easing Options**: Linear, ease-in, ease-out, and ease-in-out transitions\r\n- **Duration Control**: Customizable animation timing (1-60 seconds)\r\n- **Real-time Preview**: Live animation playback with stop/start controls\r\n\r\n### 🎨 **User Interface**\r\n- **Tabbed Interface**: Organized controls for 3D Objects, Cameras, and Animation\r\n- **Visual Feedback**: Loading states, error indicators, and progress tracking\r\n- **Accessibility**: ARIA labels and keyboard navigation support\r\n- **Modern Design**: Clean, professional interface with hover effects\r\n\r\n## 🏗️ Architecture\r\n\r\n### 📁 **Project Structure**\r\n```\r\nsrc/\r\n├── components/           # React components\r\n│   ├── css/             # Component-specific CSS files\r\n│   ├── App.tsx          # Main application component\r\n│   ├── ControlsPanel.tsx # Main control interface\r\n│   ├── Viewport.tsx     # 3D rendering viewport\r\n│   ├── ViewportManager.tsx # Viewport layout management\r\n│   ├── ObjectLoader.tsx # 3D model file loading\r\n│   ├── CameraManager.tsx # Camera position management\r\n│   ├── AdvancedCameraControls.tsx # Camera settings\r\n│   ├── CameraAnimator.tsx # Animation controls\r\n│   └── CameraFrustum.tsx # Camera frustum visualization\r\n├── hooks/               # Custom React hooks\r\n│   └── useModelLoader.ts # 3D model loading logic\r\n├── types/               # TypeScript definitions\r\n│   └── index.ts         # Type definitions and constants\r\n└── main.tsx            # Application entry point\r\n```\r\n\r\n### 🔧 **Technology Stack**\r\n- **React 19.1.1**: Modern React with hooks and functional components\r\n- **TypeScript 5.9.3**: Type safety and enhanced development experience\r\n- **Three.js 0.180.0**: 3D graphics rendering and model loading\r\n- **React Three Fiber 9.3.0**: React renderer for Three.js\r\n- **React Three Drei 10.7.6**: Useful helpers and components for R3F\r\n- **Vite 7.1.7**: Fast build tool and development server\r\n\r\n### 🎨 **Design Patterns**\r\n- **Component Composition**: Modular, reusable components\r\n- **Custom Hooks**: Separated business logic (useModelLoader)\r\n- **Type Safety**: Comprehensive TypeScript definitions\r\n- **Constants Centralization**: All hardcoded values in centralized constants\r\n- **CSS Modules**: Component-scoped styling\r\n\r\n## 🚀 Getting Started\r\n\r\n### 📋 **Prerequisites**\r\n- Node.js (version 20 or higher)\r\n- npm or yarn package manager\r\n- Modern web browser with WebGL support\r\n\r\n### 💿 **Installation**\r\n```bash\r\n# Clone the repository\r\ngit clone \u003crepository-url\u003e\r\ncd 3d-viewer\r\n\r\n# Install dependencies\r\nnpm install\r\n\r\n# Start development server\r\nnpm run dev\r\n```\r\n\r\n### 🏃‍♂️ **Running the Application**\r\n```bash\r\n# Development mode with hot reload\r\nnpm run dev\r\n\r\n# Build for production\r\nnpm run build\r\n\r\n# Preview production build\r\nnpm run preview\r\n```\r\n\r\nThe application will be available at `http://localhost:3000`\r\n\r\n## 📖 Usage Guide\r\n\r\n### 🎯 **Loading 3D Models**\r\n1. Navigate to the **\"3D Object\"** tab in the controls panel\r\n2. Click **\"Upload 3D Model\"** to select a file from your computer\r\n3. Supported formats: `.obj`, `.gltf`, `.glb`, `.fbx`, `.stl`, `.ply`\r\n4. Or click **\"Load Sample Cube\"** to load a test object\r\n\r\n### 📷 **Managing Cameras**\r\n1. Switch to the **\"Cameras\"** tab\r\n2. **Predefined Views**: Click any preset button (Front, Back, Top, etc.)\r\n3. **Custom Cameras**: \r\n   - Enter a name in the text field\r\n   - Click \"Create Camera\" to add a custom position\r\n   - Use \"View\" to switch to that camera\r\n   - Use \"Remove\" to delete unwanted positions\r\n\r\n### 🎬 **Creating Animations**\r\n1. Go to the **\"Animation\"** tab\r\n2. Select at least 2 camera positions from the list\r\n3. Adjust the duration (1-60 seconds)\r\n4. Click **\"Start Animation\"** to begin playback\r\n5. Use **\"Stop Animation\"** to halt playback\r\n\r\n### ⚙️ **Camera Settings**\r\n- **Field of View**: Adjust the camera's viewing angle (30-120°)\r\n- **Near/Far Planes**: Control rendering distance\r\n- **Show Frustum**: Visualize the camera's viewing area\r\n- **Frustum Color/Opacity**: Customize frustum appearance\r\n\r\n## 🎨 Customization\r\n\r\n### 🎯 **Adding New Model Types**\r\nTo support additional 3D model formats, modify:\r\n1. `src/types/index.ts` - Add new `ModelType` enum value\r\n2. `src/components/ObjectLoader.tsx` - Update `getModelType()` function\r\n3. `src/hooks/useModelLoader.ts` - Add loader implementation\r\n\r\n### 🌈 **Theming**\r\nAll colors and styling constants are centralized in `src/types/index.ts`:\r\n```typescript\r\nexport const COLORS = {\r\n  BACKGROUND: \"#0a0a0a\",\r\n  GRID_PRIMARY: \"#444\",\r\n  FRUSTUM_DEFAULT: \"#ff4444\",\r\n  // ... more colors\r\n} as const;\r\n```\r\n\r\n### 📐 **Camera Settings**\r\nAdjust default limits and values in `src/types/index.ts`:\r\n```typescript\r\nexport const CAMERA_LIMITS = {\r\n  FOV: { MIN: 30, MAX: 120, DEFAULT: 75 },\r\n  ANIMATION_DURATION: { MIN: 1, MAX: 60, DEFAULT: 5 },\r\n  // ... more limits\r\n} as const;\r\n```\r\n\r\n## 🔍 Troubleshooting\r\n\r\n### 🐛 **Common Issues**\r\n\r\n**Model not appearing:**\r\n- Check browser console for error messages\r\n- Verify file format is supported\r\n- Try zooming out (model might be very large/small)\r\n- Test with the sample cube first\r\n\r\n**Loading errors:**\r\n- Ensure file is not corrupted\r\n- Check file size (very large files may timeout)\r\n- Verify browser supports WebGL\r\n\r\n**Performance issues:**\r\n- Reduce model complexity\r\n- Lower polygon count\r\n- Check available system memory\r\n\r\n### 🔧 **Debug Features**\r\n- Open browser developer tools (F12)\r\n- Check Console tab for detailed loading logs\r\n- Monitor Network tab for file loading issues\r\n- Use the sample cube to verify system functionality\r\n\r\n## 🎯 Model Attribution\r\n\r\n**Note**: Any 3D models used for testing or demonstration purposes in this project are sourced from [Free3D.com](https://free3d.com/), a platform providing free 3D models for educational and commercial use. Please respect the individual licensing terms of each model when using them in your projects.\r\n\r\n## 📊 Performance Characteristics\r\n\r\n- **Startup Time**: ~2-3 seconds on modern hardware\r\n- **Model Loading**: Varies by file size (typically 1-10 seconds)\r\n- **Memory Usage**: ~50-200MB depending on model complexity\r\n- **Supported Model Sizes**: Up to ~50MB files (browser dependent)\r\n\r\n## 🔒 Browser Compatibility\r\n\r\n- **Chrome**: ✅ Fully supported (recommended)\r\n- **Firefox**: ✅ Fully supported\r\n- **Safari**: ✅ Supported with minor limitations\r\n- **Edge**: ✅ Fully supported\r\n- **Mobile**: ⚠️ Limited support (touch controls may vary)\r\n\r\n## 🤝 Contributing\r\n\r\n1. Fork the repository\r\n2. Create a feature branch: `git checkout -b feature/amazing-feature`\r\n3. Commit changes: `git commit -m 'Add amazing feature'`\r\n4. Push to branch: `git push origin feature/amazing-feature`\r\n5. Open a Pull Request\r\n\r\n## 📄 License\r\n\r\nThis project is licensed under the MIT License - see the package.json file for details.\r\n\r\n## 🙏 Acknowledgments\r\n\r\n- **Three.js Community** - For the excellent 3D graphics library\r\n- **React Three Fiber Team** - For the React integration\r\n- **Free3D.com** - For providing free 3D models for testing\r\n- **Open Source Community** - For the various tools and libraries used\r\n\r\n## 🆘 Support\r\n\r\nFor issues, questions, or contributions:\r\n1. Check the troubleshooting section above\r\n2. Search existing issues in the repository\r\n3. Create a new issue with detailed information\r\n4. Include browser version, file types, and error messages\r\n\r\n---\r\n\r\n**Happy 3D Modeling! 🚀**","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fakash1331%2F3d-viewer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fakash1331%2F3d-viewer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fakash1331%2F3d-viewer/lists"}