UmeshAdabala commited on
Commit
b100fb3
ยท
verified ยท
1 Parent(s): 7c21703

Update README.md

Browse files
Files changed (1) hide show
  1. README.md +248 -3
README.md CHANGED
@@ -1,3 +1,248 @@
1
- ---
2
- license: mit
3
- ---
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # ๐Ÿ…ฟ Parkospace โ€” AI Parking Space Detector
2
+
3
+ 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.
4
+
5
+ ---
6
+
7
+ ## ๐Ÿง  What It Does
8
+
9
+ - ๐Ÿ“ธ Takes a photo of a parking space
10
+ - ๐Ÿ” Detects the 4 corner keypoints of the space (TL, TR, BR, BL)
11
+ - ๐Ÿ“ Estimates real-world dimensions in metres (using 2-photo perspective method)
12
+ - ๐Ÿ’ฐ Calculates Hourly / Daily / Monthly pricing automatically
13
+ - โœ๏ธ Lets users interactively adjust the rectangle (resize + move)
14
+
15
+ ---
16
+
17
+ ## ๐Ÿ—๏ธ Model Architecture
18
+
19
+ | Property | Value |
20
+ |---|---|
21
+ | Architecture | MobileNetV2 + Regression Head |
22
+ | Input | `(B, 3, 224, 224)` โ€” normalized RGB |
23
+ | Output | `(B, 8)` โ€” 4 corners `(x, y)` normalized to `[0, 1]` |
24
+ | Corner order | TL โ†’ TR โ†’ BR โ†’ BL |
25
+ | Loss function | Wing Loss |
26
+ | Total parameters | ~3.4M |
27
+ | Model size | ~13 MB |
28
+ | Inference speed | < 30ms on CPU |
29
+
30
+ ---
31
+
32
+ ## ๐Ÿ“ File Structure
33
+
34
+ ```
35
+ parkospace/
36
+ โ”œโ”€โ”€ parkospace_colab.ipynb # Complete Colab notebook (train + test + infer)
37
+ โ”œโ”€โ”€ generate_data.py # Synthetic parking image generator
38
+ โ”œโ”€โ”€ model.py # CNN model definition
39
+ โ”œโ”€โ”€ train.py # Training script
40
+ โ”œโ”€โ”€ infer.py # Inference + interactive editor + pricing
41
+ โ”œโ”€โ”€ upload_to_hf.py # HuggingFace Hub upload script
42
+ โ”œโ”€โ”€ requirements.txt # Dependencies
43
+ โ””โ”€โ”€ README.md
44
+ ```
45
+
46
+ ---
47
+
48
+ ## ๐Ÿš€ Quickstart
49
+
50
+ ### Option 1 โ€” Google Colab (Recommended)
51
+ 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.
52
+
53
+ ### Option 2 โ€” Run Locally
54
+
55
+ **1. Clone and install**
56
+ ```bash
57
+ git clone https://github.com/your-username/parkospace-detector
58
+ cd parkospace-detector
59
+ pip install -r requirements.txt
60
+ ```
61
+
62
+ **2. Generate synthetic training data**
63
+ ```bash
64
+ python generate_data.py --out data --n 5000
65
+ ```
66
+
67
+ **3. Train the model**
68
+ ```bash
69
+ python train.py --data data --epochs 30 --batch 32
70
+ ```
71
+
72
+ **4. Run inference on an image**
73
+ ```bash
74
+ python infer.py --checkpoint checkpoints/best.pt --img parking.jpg
75
+ ```
76
+
77
+ **5. Dual-image dimension estimation**
78
+ ```bash
79
+ python infer.py \
80
+ --checkpoint checkpoints/best.pt \
81
+ --length_img photo_from_length_side.jpg \
82
+ --breadth_img photo_from_breadth_side.jpg
83
+ ```
84
+
85
+ ---
86
+
87
+ ## ๐Ÿ Python API
88
+
89
+ ```python
90
+ from model import ParkingSpaceDetector
91
+ from infer import load_model, detect, calculate_pricing
92
+
93
+ # Load trained model
94
+ model = load_model("checkpoints/best.pt")
95
+
96
+ # Detect parking space corners
97
+ import cv2
98
+ img = cv2.imread("parking.jpg")
99
+ det = detect(model, img)
100
+
101
+ print("Corners (pixels):", det.corners_px)
102
+ # [[x0,y0], [x1,y1], [x2,y2], [x3,y3]] โ†’ TL, TR, BR, BL
103
+
104
+ # Calculate pricing
105
+ pricing = calculate_pricing(area_m2=15.0)
106
+ print(pricing)
107
+ # {
108
+ # "hourly_inr": 50.0,
109
+ # "daily_inr": 300.0,
110
+ # "monthly_inr": 150.0,
111
+ # "area_m2": 15.0
112
+ # }
113
+ ```
114
+
115
+ ---
116
+
117
+ ## ๐Ÿ“ Dual-Image Dimension Estimation
118
+
119
+ For accurate real-world measurements without any special equipment:
120
+
121
+ 1. **Photo 1** โ€” Stand at the **length side**, photograph across the width
122
+ 2. **Photo 2** โ€” Stand at the **breadth side**, photograph along the length
123
+
124
+ ```python
125
+ from infer import load_model, estimate_dimensions_dual
126
+ import cv2
127
+
128
+ model = load_model("checkpoints/best.pt")
129
+ length_img = cv2.imread("from_length_side.jpg")
130
+ breadth_img = cv2.imread("from_breadth_side.jpg")
131
+
132
+ dims = estimate_dimensions_dual(model, length_img, breadth_img)
133
+ # {
134
+ # "length_m": 5.2,
135
+ # "breadth_m": 2.6,
136
+ # "area_m2": 13.52
137
+ # }
138
+ ```
139
+
140
+ ---
141
+
142
+ ## ๐Ÿ’ฐ Pricing Logic
143
+
144
+ | Type | Formula | Default |
145
+ |---|---|---|
146
+ | Hourly | Fixed | โ‚น50 |
147
+ | Daily | Fixed | โ‚น300 |
148
+ | Monthly | `area_mยฒ ร— โ‚น10` | e.g. 15mยฒ โ†’ โ‚น150 |
149
+
150
+ All prices are configurable โ€” pass custom values to `calculate_pricing()`.
151
+
152
+ ---
153
+
154
+ ## ๐Ÿ‹๏ธ Training Details
155
+
156
+ | Setting | Value |
157
+ |---|---|
158
+ | Dataset | 5,000 synthetic images (OpenCV generated) |
159
+ | Train / Val split | 85% / 15% |
160
+ | Optimizer | AdamW (`lr=1e-3`, `weight_decay=1e-4`) |
161
+ | Scheduler | Cosine Annealing |
162
+ | Phase 1 (epochs 1โ€“10) | Backbone frozen, head only |
163
+ | Phase 2 (epochs 11โ€“30) | Last 5 backbone layers unfrozen |
164
+ | Augmentations | Color jitter, shadows, noise, blur, brightness |
165
+ | Best val corner error | < 10px on 224ร—224 images |
166
+
167
+ ### Training Curves
168
+
169
+ Training takes ~10 minutes on a free Colab T4 GPU.
170
+
171
+ ---
172
+
173
+ ## ๐Ÿ“ฆ Requirements
174
+
175
+ ```
176
+ torch>=2.0.0
177
+ torchvision>=0.15.0
178
+ opencv-python-headless>=4.7.0
179
+ numpy>=1.24.0
180
+ tqdm>=4.65.0
181
+ matplotlib>=3.7.0
182
+ Pillow>=9.5.0
183
+ huggingface_hub>=0.16.0
184
+ ```
185
+
186
+ Install all:
187
+ ```bash
188
+ pip install -r requirements.txt
189
+ ```
190
+
191
+ ---
192
+
193
+ ## ๐Ÿ”ฎ Roadmap
194
+
195
+ - [ ] Fine-tune on real parking space photos
196
+ - [ ] Add support for non-rectangular spaces (polygons)
197
+ - [ ] ONNX export for browser-based inference
198
+ - [ ] Integrate with Parkospace owner dashboard
199
+ - [ ] Occupied / available space detection
200
+ - [ ] Multi-space detection in a single image
201
+
202
+ ---
203
+
204
+ ## ๐Ÿค Contributing
205
+
206
+ 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.
207
+
208
+ 1. Fork the repository
209
+ 2. Create your feature branch: `git checkout -b feature/my-feature`
210
+ 3. Commit your changes: `git commit -m 'Add my feature'`
211
+ 4. Push to the branch: `git push origin feature/my-feature`
212
+ 5. Open a Pull Request
213
+
214
+ ---
215
+
216
+ ## ๐Ÿ“„ License
217
+
218
+ ```
219
+ MIT License
220
+
221
+ Copyright (c) 2025 Parkospace
222
+
223
+ Permission is hereby granted, free of charge, to any person obtaining a copy
224
+ of this software and associated documentation files (the "Software"), to deal
225
+ in the Software without restriction, including without limitation the rights
226
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
227
+ copies of the Software, and to permit persons to whom the Software is
228
+ furnished to do so, subject to the following conditions:
229
+
230
+ The above copyright notice and this permission notice shall be included in all
231
+ copies or substantial portions of the Software.
232
+
233
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
234
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
235
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
236
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
237
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
238
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
239
+ SOFTWARE.
240
+ ```
241
+
242
+ ---
243
+
244
+ ## ๐Ÿ‘ค Author
245
+
246
+ **Umesh** โ€” [Parkospace](https://github.com/ParkoSpace/in)
247
+
248
+ > Built with โค๏ธ for making parking smarter in India ๐Ÿ‡ฎ๐Ÿ‡ณ