| --- |
| license: mit |
| language: |
| - en |
| pipeline_tag: keypoint-detection |
| --- |
| # 🅿 Parkospace — AI Parking Space Detector |
|
|
| A lightweight **MobileNetV2-based keypoint detector** that automatically detects the 4 corners of a parking space rectangle in a photo, estimates real-world dimensions, and calculates rental pricing. Built for the [Parkospace](https://github.com/your-username/parkospace) platform. |
|
|
| --- |
|
|
| ## 🧠 What It Does |
|
|
| - 📸 Takes a photo of a parking space |
| - 🔍 Detects the 4 corner keypoints of the space (TL, TR, BR, BL) |
| - 📐 Estimates real-world dimensions in metres (using 2-photo perspective method) |
| - 💰 Calculates Hourly / Daily / Monthly pricing automatically |
| - ✏️ Lets users interactively adjust the rectangle (resize + move) |
|
|
| --- |
|
|
| ## 🏗️ Model Architecture |
|
|
| | Property | Value | |
| |---|---| |
| | Architecture | MobileNetV2 + Regression Head | |
| | Input | `(B, 3, 224, 224)` — normalized RGB | |
| | Output | `(B, 8)` — 4 corners `(x, y)` normalized to `[0, 1]` | |
| | Corner order | TL → TR → BR → BL | |
| | Loss function | Wing Loss | |
| | Total parameters | ~3.4M | |
| | Model size | ~13 MB | |
| | Inference speed | < 30ms on CPU | |
|
|
| --- |
|
|
| ## 📁 File Structure |
|
|
| ``` |
| parkospace/ |
| ├── parkospace_colab.ipynb # Complete Colab notebook (train + test + infer) |
| ├── generate_data.py # Synthetic parking image generator |
| ├── model.py # CNN model definition |
| ├── train.py # Training script |
| ├── infer.py # Inference + interactive editor + pricing |
| ├── upload_to_hf.py # HuggingFace Hub upload script |
| ├── requirements.txt # Dependencies |
| └── README.md |
| ``` |
|
|
| --- |
|
|
| ## 🚀 Quickstart |
|
|
| ### Option 1 — Google Colab (Recommended) |
| Open `parkospace_colab.ipynb` in [Google Colab](https://colab.research.google.com), switch to **T4 GPU**, and run all cells top to bottom. No setup needed. |
|
|
| ### Option 2 — Run Locally |
|
|
| **1. Clone and install** |
| ```bash |
| git clone https://github.com/your-username/parkospace-detector |
| cd parkospace-detector |
| pip install -r requirements.txt |
| ``` |
|
|
| **2. Generate synthetic training data** |
| ```bash |
| python generate_data.py --out data --n 5000 |
| ``` |
|
|
| **3. Train the model** |
| ```bash |
| python train.py --data data --epochs 30 --batch 32 |
| ``` |
|
|
| **4. Run inference on an image** |
| ```bash |
| python infer.py --checkpoint checkpoints/best.pt --img parking.jpg |
| ``` |
|
|
| **5. Dual-image dimension estimation** |
| ```bash |
| python infer.py \ |
| --checkpoint checkpoints/best.pt \ |
| --length_img photo_from_length_side.jpg \ |
| --breadth_img photo_from_breadth_side.jpg |
| ``` |
|
|
| --- |
|
|
| ## 🐍 Python API |
|
|
| ```python |
| from model import ParkingSpaceDetector |
| from infer import load_model, detect, calculate_pricing |
| |
| # Load trained model |
| model = load_model("checkpoints/best.pt") |
| |
| # Detect parking space corners |
| import cv2 |
| img = cv2.imread("parking.jpg") |
| det = detect(model, img) |
| |
| print("Corners (pixels):", det.corners_px) |
| # [[x0,y0], [x1,y1], [x2,y2], [x3,y3]] → TL, TR, BR, BL |
| |
| # Calculate pricing |
| pricing = calculate_pricing(area_m2=15.0) |
| print(pricing) |
| # { |
| # "hourly_inr": 50.0, |
| # "daily_inr": 300.0, |
| # "monthly_inr": 150.0, |
| # "area_m2": 15.0 |
| # } |
| ``` |
|
|
| --- |
|
|
| ## 📐 Dual-Image Dimension Estimation |
|
|
| For accurate real-world measurements without any special equipment: |
|
|
| 1. **Photo 1** — Stand at the **length side**, photograph across the width |
| 2. **Photo 2** — Stand at the **breadth side**, photograph along the length |
|
|
| ```python |
| from infer import load_model, estimate_dimensions_dual |
| import cv2 |
| |
| model = load_model("checkpoints/best.pt") |
| length_img = cv2.imread("from_length_side.jpg") |
| breadth_img = cv2.imread("from_breadth_side.jpg") |
| |
| dims = estimate_dimensions_dual(model, length_img, breadth_img) |
| # { |
| # "length_m": 5.2, |
| # "breadth_m": 2.6, |
| # "area_m2": 13.52 |
| # } |
| ``` |
|
|
| --- |
|
|
| ## 💰 Pricing Logic |
|
|
| | Type | Formula | Default | |
| |---|---|---| |
| | Hourly | Fixed | ₹50 | |
| | Daily | Fixed | ₹300 | |
| | Monthly | `area_m² × ₹10` | e.g. 15m² → ₹150 | |
|
|
| All prices are configurable — pass custom values to `calculate_pricing()`. |
|
|
| --- |
|
|
| ## 🏋️ Training Details |
|
|
| | Setting | Value | |
| |---|---| |
| | Dataset | 5,000 synthetic images (OpenCV generated) | |
| | Train / Val split | 85% / 15% | |
| | Optimizer | AdamW (`lr=1e-3`, `weight_decay=1e-4`) | |
| | Scheduler | Cosine Annealing | |
| | Phase 1 (epochs 1–10) | Backbone frozen, head only | |
| | Phase 2 (epochs 11–30) | Last 5 backbone layers unfrozen | |
| | Augmentations | Color jitter, shadows, noise, blur, brightness | |
| | Best val corner error | < 10px on 224×224 images | |
|
|
| ### Training Curves |
|
|
| Training takes ~10 minutes on a free Colab T4 GPU. |
|
|
| --- |
|
|
| ## 📦 Requirements |
|
|
| ``` |
| torch>=2.0.0 |
| torchvision>=0.15.0 |
| opencv-python-headless>=4.7.0 |
| numpy>=1.24.0 |
| tqdm>=4.65.0 |
| matplotlib>=3.7.0 |
| Pillow>=9.5.0 |
| huggingface_hub>=0.16.0 |
| ``` |
|
|
| Install all: |
| ```bash |
| pip install -r requirements.txt |
| ``` |
|
|
| --- |
|
|
| ## 🔮 Roadmap |
|
|
| - [ ] Fine-tune on real parking space photos |
| - [ ] Add support for non-rectangular spaces (polygons) |
| - [ ] ONNX export for browser-based inference |
| - [ ] Integrate with Parkospace owner dashboard |
| - [ ] Occupied / available space detection |
| - [ ] Multi-space detection in a single image |
|
|
| --- |
|
|
| ## 🤝 Contributing |
|
|
| Contributions are welcome! If you have real parking space photos you'd like to contribute to improve the model, please open an issue or pull request. |
|
|
| 1. Fork the repository |
| 2. Create your feature branch: `git checkout -b feature/my-feature` |
| 3. Commit your changes: `git commit -m 'Add my feature'` |
| 4. Push to the branch: `git push origin feature/my-feature` |
| 5. Open a Pull Request |
|
|
| --- |
|
|
| ## 📄 License |
|
|
| ``` |
| MIT License |
| |
| Copyright (c) 2025 Parkospace |
| |
| 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. |
| ``` |
|
|
| --- |
|
|
| ## 👤 Author |
|
|
| **UmeshAdabala** — [Parkospace](https://github.com/ParkoSpace/in) |
|
|
| > Built with ❤️ for making parking smarter in India 🇮🇳 |
