Skip to content

README.md

Latest commit

 

History

History
146 lines (97 loc) · 3.58 KB

README.md

File metadata and controls

146 lines (97 loc) · 3.58 KB

🎨 Cuby Recognition API

GitHub stars GitHub forks GitHub issues GitHub last commit

📝 Description

A Flask API that receives 6 centered images of a scrambled Rubik's Cube and returns the cube string (color layout) by detecting each sticker's color using OpenCV and a trained KNN model in HSV space.

🔗 Related Projects

✨ Features

  • 📷 Color detection from HSV-processed images
  • 🤖 KNN classifier trained on HSV color samples
  • 🧪 Full test suite: unit, integration
  • 🐳 Docker-ready + GitHub Actions CI/CD
  • 🔄 Real-time color recognition
  • 📊 High accuracy color detection

🚀 Setup

🔧 Requirements

  • Python 3.10+
  • OpenCV
  • Flask
  • Scikit-learn

🛠️ Installation

  1. Clone the repository:
git clone https://github.com/Cuby-Project/Cuby-recognition-API.git
  1. Install dependencies:
pip install -r requirements.txt
  1. Generate and train color model:
make train

This runs:

  • generate_synthetic_dataset.py: generates HSV data for W, Y, R, O, B, G
  • train_color_model.py: trains and saves a KNN classifier

🌐 API Usage

Endpoint: /cubeFacesToCubeString

Method: POST Content-Type: multipart/form-data

Fields: Upload 6 images named exactly:

  • face1, face2, face3, face4, face5, face6

Returns:

{
  "cube_string": "UUUUUUUUURRRRRRRRRFFFFFFFFFDDDDDDDDDLLLLLLLLLBBBBBBBBB"
}

Optional (if solver is included):

{
  "cube_string": "...",
  "solution": "R U R' U'"
}

🧪 Testing

Unit & Integration Tests

make test

Coverage Report

make coverage

Docker Test

make docker-test

🐳 Docker

Build the Image

docker build -t rubik-api .

Run the API

docker run -p 5000:5000 rubik-api

🤝 Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

  1. Fork the Project
  2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
  3. Commit your Changes (git commit -m 'Add some AmazingFeature')
  4. Push to the Branch (git push origin feature/AmazingFeature)
  5. Open a Pull Request

📄 License

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

📞 Support