Upload README.md with huggingface_hub

README.md

@@ -1,3 +1,112 @@
 ---
 license: mit
+base_model: cfzd/Ultra-Fast-Lane-Detection
+tags:
+  - tflite
+  - lane-detection
+  - object-detection
+  - quantized
+  - android
+  - automotive
+  - autonomous-driving
+  - adas
+language:
+  - en
+pipeline_tag: object-detection
 ---
+
+# Car Nebula ADAS — On-Device TFLite Models
+
+Two TFLite models used by [Car Nebula](https://carnebula.app) for real-time Advanced Driver
+Assistance (ADAS) running entirely on-device on Android automotive hardware.
+
+---
+
+## Models
+
+### 1. `lane_detector.tflite` — Lane Detection
+
+| Property | Value |
+|---|---|
+| **Base model** | Ultra-Fast Lane Detection (cfzd/Ultra-Fast-Lane-Detection) |
+| **Architecture** | ResNet-18 backbone |
+| **Dataset** | TUSimple (highway lanes, US dashcam footage) |
+| **Original weights** | `tusimple_res18.pth` (official pre-trained) |
+| **Input shape** | `[1, 288, 800, 3]` — float32 or int8, NHWC |
+| **Input normalization** | ImageNet: mean `[0.485, 0.456, 0.406]`, std `[0.229, 0.224, 0.225]` |
+| **Output shape** | `[1, 201, 56, 4]` or `[1, 4, 56, 201]` |
+| **Output format** | 201 grid bins (200 x-positions + 1 no-lane) × 56 row anchors × 4 lanes |
+| **License** | MIT |
+
+**Conversion pipeline:**
+```
+tusimple_res18.pth  →  ONNX (opset 11)  →  TF SavedModel  →  TFLite
+```
+Conversion script: `convert_ufld.py` (included in the Car Nebula Android repo).
+
+**Row anchors (TUSimple, 56 rows, pixel Y in 288-px input):**
+```
+64 68 72 76 80 84 88 92 96 100 104 108 112 116 120 124 128 132 136 140
+144 148 152 156 160 164 168 172 176 180 184 188 192 196 200 204 208 212
+216 220 224 228 232 236 240 244 248 252 256 260 264 268 272 276 280 284
+```
+
+---
+
+### 2. `efficientdet_lite0.tflite` — Object Detection
+
+| Property | Value |
+|---|---|
+| **Model family** | EfficientDet Lite0 |
+| **Source** | [TensorFlow Hub](https://tfhub.dev/tensorflow/lite-model/efficientdet/lite0/detection/metadata/1) |
+| **Input shape** | `[1, 320, 320, 3]` — uint8, NHWC |
+| **Output** | Bounding boxes · class scores · class labels · detection count |
+| **Classes** | 90 COCO classes |
+| **Score threshold** | 0.38 (used by Car Nebula pipeline) |
+| **License** | Apache 2.0 |
+
+---
+
+## How the pipeline uses both models
+
+```
+Camera frame (CameraX / USB UVC)
+        │
+        ├──► EfficientDet Lite0 (every 3 frames)
+        │         └──► AdasBox list: label, bounding rect, estimated distance
+        │                   └──► HUD overlay: boxes, collision warning, top-down view
+        │
+        └──► UFLD ResNet-18 (every 3 frames)
+                  └──► Lane boundary points (left/right, top/bottom)
+                            └──► Camera overlay: seg mask, lane lines
+                                 HUD: road corridor, departure warning
+```
+
+Results are temporally smoothed between inference runs so the UI always has
+something to render even on frames that skip inference.
+
+---
+
+## Usage (Android / TFLite Java API)
+
+```kotlin
+// Load from downloaded file
+val model = FileInputStream(file).channel.use { ch ->
+    ch.map(FileChannel.MapMode.READ_ONLY, 0, file.length())
+}
+val interpreter = InterpreterApi.create(
+    model,
+    InterpreterApi.Options()
+        .setRuntime(InterpreterApi.Options.TfLiteRuntime.FROM_SYSTEM_ONLY)
+        .setNumThreads(2)
+)
+```
+
+---
+
+## Licenses
+
+| Model | License |
+|---|---|
+| `lane_detector.tflite` (UFLD ResNet-18) | [MIT](https://github.com/cfzd/Ultra-Fast-Lane-Detection/blob/master/LICENSE) |
+| `efficientdet_lite0.tflite` (TFHub) | [Apache 2.0](https://www.apache.org/licenses/LICENSE-2.0) |