{"id":31051742,"url":"https://github.com/kanugurajesh/kociemba","last_synced_at":"2026-05-11T07:03:41.966Z","repository":{"id":307795487,"uuid":"1030668004","full_name":"kanugurajesh/kociemba","owner":"kanugurajesh","description":"Cube solver using kociemba","archived":false,"fork":false,"pushed_at":"2025-08-02T07:32:26.000Z","size":400,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-02T09:56:27.267Z","etag":null,"topics":["fastapi","html-css-javascript","kociemba","python3"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kanugurajesh.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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}},"created_at":"2025-08-02T04:27:56.000Z","updated_at":"2025-08-02T07:32:29.000Z","dependencies_parsed_at":"2025-08-02T09:56:30.532Z","dependency_job_id":"9ddbf3df-3625-4994-879d-bd97962cd9d0","html_url":"https://github.com/kanugurajesh/kociemba","commit_stats":null,"previous_names":["kanugurajesh/kociemba"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/kanugurajesh/kociemba","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kanugurajesh%2Fkociemba","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kanugurajesh%2Fkociemba/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kanugurajesh%2Fkociemba/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kanugurajesh%2Fkociemba/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kanugurajesh","download_url":"https://codeload.github.com/kanugurajesh/kociemba/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kanugurajesh%2Fkociemba/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":275189758,"owners_count":25420645,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-14T02:00:10.474Z","response_time":75,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["fastapi","html-css-javascript","kociemba","python3"],"created_at":"2025-09-15T00:52:27.889Z","updated_at":"2026-05-11T07:03:36.923Z","avatar_url":"https://github.com/kanugurajesh.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Rubik's Cube 3D Visualizer \u0026 Solver\n\nA modern, interactive 3D Rubik's Cube web application featuring real-time manipulation, elegant animations, and integrated solving capabilities. Built with Three.js for frontend visualization and FastAPI backend for cube logic and solving algorithms.\n\n## ✨ Features\n\n### 🎮 Interactive 3D Experience\n- **Immersive 3D Visualization**: Fully interactive 3D cube rendered with Three.js\n- **Smooth Animations**: Fluid face rotations and transitions with customizable timing\n- **Intuitive Controls**: Keyboard-based manipulation using standard Rubik's cube notation\n- **Modern UI**: Clean, dark-themed interface with animated backgrounds and tooltips\n\n### 🧩 Cube Manipulation\n- **Standard Notation Support**: Full support for F, R, U, L, D, B face rotations\n- **Direction Control**: Toggle between clockwise and counterclockwise rotations\n- **Middle Layer Moves**: M-slice rotations for advanced solving techniques\n- **Move History**: Undo functionality to reverse any move sequence\n\n### 🔧 Solving Capabilities\n- **Kociemba Algorithm**: Optimal solving using the two-phase Kociemba algorithm\n- **Real-time Solutions**: Get step-by-step solutions for any valid cube state\n- **Solution Display**: Visual presentation of move sequences with progress tracking\n- **Auto-solve Mode**: Watch the cube solve itself with animated move execution\n\n### 🎨 Enhanced User Interface\n- **Responsive Design**: Optimized for both desktop and mobile devices\n- **Visual Feedback**: Real-time action display and move notifications\n- **Status Indicators**: Clear feedback for solving progress and cube state\n- **Accessibility**: Keyboard shortcuts and ARIA-compliant interface elements\n\n## 🚀 Quick Start\n\n### Prerequisites\n- **Frontend**: Modern web browser with WebGL support\n- **Backend**: Python 3.7+ with pip\n\n### Installation\n\n1. **Clone the repository**\n   ```bash\n   git clone https://github.com/kanugurajesh/kociemba\n   cd kociemba\n   ```\n\n2. **Set up the backend**\n   ```bash\n   cd backend\n   pip install -r requirements.txt\n   python server.py\n   ```\n\n3. **Launch the frontend**\n   - Open `index.html` in your web browser\n   - Or serve using a local HTTP server:\n     ```bash\n     python -m http.server 5500\n     ```\n\n## 🎯 How to Use\n\n### Basic Controls\n\n| Key | Action | Description |\n|-----|--------|-------------|\n| `F` | Front face | Rotate front face |\n| `R` | Right face | Rotate right face |\n| `U` | Up face | Rotate top face |\n| `L` | Left face | Rotate left face |\n| `D` | Down face | Rotate bottom face |\n| `B` | Back face | Rotate back face |\n| `M` | Middle slice | Rotate middle vertical slice |\n\n### Direction Control\n- `1` - Clockwise rotation (default)\n- `2` - Counterclockwise rotation (adds ' to notation)\n\n### Interface Actions\n- **Solve Button**: Generate and display optimal solution\n- **Undo Button**: Reverse the last move\n- **Reset Button**: Return cube to solved state\n- **Direction Toggle**: Switch between clockwise/counterclockwise modes\n\n### Advanced Features\n- **Auto-solve**: Click solve to see step-by-step solution execution\n- **Move History**: Full undo/redo functionality for all moves\n- **State Persistence**: Cube state maintained across browser sessions\n\n## 🛠 Technical Architecture\n\n### Frontend (Three.js)\n```\nmodules/\n├── main.js           # Application entry point and update loop\n├── sceneManager.js   # 3D scene setup and rendering\n├── rubik.js          # Cube geometry and face rotations\n├── animations.js     # Animation timing and interpolation\n├── keyHandler.js     # Keyboard input processing\n├── ui.js             # User interface updates\n├── api.js            # Backend communication\n├── modes.js          # Application modes and states\n├── motion.js         # Movement mechanics\n├── action_utils.js   # User action processing\n└── solutionService.js # Solution execution and display\n```\n\n### Backend (FastAPI + Python)\n```\nbackend/\n├── server.py         # FastAPI application and CORS setup\n├── cube_engine.py    # Core cube logic and Kociemba integration\n└── requirements.txt  # Python dependencies\n```\n\n## 📡 API Reference\n\n### Endpoints\n\n#### `POST /move`\nExecute a cube move and update internal state.\n\n**Request:**\n```json\n{\n  \"move\": \"R\"\n}\n```\n\n**Response:**\n```json\n{\n  \"move\": \"R\",\n  \"cube_string\": \"UUUUUULLLURRURRURRFFFFFFFFFRRRDDDDDDLLDLLDLLDBBBBBBBBB\"\n}\n```\n\n#### `GET /solve`\nGet optimal solution for current cube state.\n\n**Response:**\n```json\n{\n  \"solutionString\": \"R U R' U' R' F R2 U' R' U' R U R' F'\",\n  \"parsedMoves\": [\"R\", \"U\", \"R'\", \"U'\", \"R'\", \"F\", [\"R\", \"R\"], \"U'\", \"R'\", \"U'\", \"R\", \"U\", \"R'\", \"F'\"]\n}\n```\n\n#### `POST /reset-cube`\nReset cube to solved state.\n\n**Response:**\n```json\n{}\n```\n\n## 🎨 Customization\n\n### Cube Colors\nModify colors in `rubik.js`:\n```javascript\nlet blueMaterial = new THREE.MeshBasicMaterial({ color: 0x003DA5 });\nlet greenMaterial = new THREE.MeshBasicMaterial({ color: 0x009A44 });\n// ... additional materials\n```\n\n### Animation Timing\nAdjust animation speed in `animations.js`:\n```javascript\nconst ANIMATION_DURATION = 300; // milliseconds\n```\n\n### UI Theme\nCustomize visual theme in the CSS variables within `index.html`:\n```css\n:root {\n  --bg-primary: #0a0a0f;\n  --accent-primary: #00d4ff;\n  --accent-secondary: #7c3aed;\n  /* ... additional theme variables */\n}\n```\n\n## 🔧 Development\n\n### Adding New Moves\n1. **Backend**: Add move logic to `cube_engine.py` in the `Polyhedron` class\n2. **Frontend**: Update the move dispatcher in `keyHandler.js`\n3. **Animation**: Define rotation parameters in `animations.js`\n\n### Custom Algorithms\nExtend the solution service in `solutionService.js` to support custom solving algorithms or move sequences.\n\n### Performance Optimization\n- Enable/disable animations based on device capabilities\n- Implement level-of-detail for complex cube states\n- Cache frequently used geometries and materials\n\n## 🚀 Deployment\n\n### Production Configuration\n1. **Backend**: Set environment variables for production\n   ```bash\n   export ENV=production\n   export PORT=8080\n   ```\n\n2. **Frontend**: Update API endpoints in `api.js` for production URLs\n\n3. **CORS**: Configure allowed origins in `server.py`\n\n### Docker Support\n```dockerfile\n# Example Dockerfile for backend\nFROM python:3.9-slim\nCOPY backend/ /app\nWORKDIR /app\nRUN pip install -r requirements.txt\nCMD [\"python\", \"server.py\"]\n```\n\n## 🤝 Contributing\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n### Code Style\n- **JavaScript**: Use ES6+ modules and modern syntax\n- **Python**: Follow PEP 8 conventions\n- **Comments**: Document complex algorithms and cube transformations\n\n## 📝 License\n\nThis project is licensed under the MIT License - see the LICENSE file for details.\n\n## 🙏 Acknowledgments\n\n- **Three.js** - 3D graphics library powering the visualization\n- **Kociemba Algorithm** - Optimal cube solving implementation\n- **FastAPI** - Modern Python web framework for the backend\n- **Bootstrap** - UI components and responsive design\n\n## 📊 Technical Details\n\n### Cube State Representation\n- **Internal Format**: 6×3×3 NumPy array representing cube faces\n- **Kociemba String**: 54-character string for solver integration\n- **Face Order**: U (Up), R (Right), F (Front), D (Down), L (Left), B (Back)\n\n### Performance Metrics\n- **Solving Speed**: Average 20 moves for optimal solutions\n- **Animation FPS**: 60fps smooth animations on modern browsers\n- **Load Time**: \u003c 2 seconds initial load with Three.js\n\n### Browser Compatibility\n- **Chrome**: 90+ ✅\n- **Firefox**: 88+ ✅  \n- **Safari**: 14+ ✅\n- **Edge**: 90+ ✅\n\n## 🐛 Known Issues\n\n- Mobile touch controls not yet implemented\n- Large solution sequences may cause UI lag\n- Backend requires restart after solving complex states (rare)\n\n## 🔮 Future Enhancements\n\n- [ ] Touch and swipe controls for mobile devices\n- [ ] Multiple solving algorithms (CFOP, Roux, ZZ)\n- [ ] Scramble generation with difficulty levels\n- [ ] Multiplayer solving competitions\n- [ ] 3D cube customization (textures, effects)\n- [ ] Voice commands for hands-free operation\n- [ ] AR/VR support for immersive experience\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkanugurajesh%2Fkociemba","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkanugurajesh%2Fkociemba","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkanugurajesh%2Fkociemba/lists"}