Add migration markdown

Author: Saumya Saksena

MIGRATION.md

@@ -0,0 +1,317 @@
+# Migration Guide: Legacy → Modern
+
+## Quick Comparison
+
+### Old Code Structure
+
+```
+telloCV-masked-rcnn.py  # 500+ lines of everything
+tracker.py              # Color-based tracking
+requirements.txt        # Ancient dependencies
+```
+
+### New Code Structure
+
+```
+tello_vision/
+├── detectors/          # Modular detection backends
+├── tello_controller.py # Drone control
+├── visualizer.py       # Rendering
+└── app.py              # Clean main app
+```
+
+## Key Changes
+
+### 1. Model Loading
+
+**Old (Matterport Mask R-CNN):**
+
+```python
+from mrcnn import model as modellib
+from mrcnn.config import Config
+
+class InferenceConfig(Config):
+    NAME = "coco"
+    GPU_COUNT = 1
+    IMAGES_PER_GPU = 1
+
+config = InferenceConfig()
+model = modellib.MaskRCNN(mode="inference", config=config, model_dir='./')
+model.load_weights('mask_rcnn_coco.h5', by_name=True)
+```
+
+**New (YOLOv8):**
+
+```python
+from tello_vision.detectors.base_detector import BaseDetector
+
+detector = BaseDetector.create_detector('yolov8', {
+    'model': 'yolov8n-seg.pt',
+    'device': 'cuda',
+    'confidence': 0.5
+})
+detector.load_model()
+```
+
+### 2. Detection
+
+**Old:**
+
+```python
+results = model.detect([image], verbose=0)
+r = results[0]
+boxes = r['rois']
+masks = r['masks']
+class_ids = r['class_ids']
+scores = r['scores']
+```
+
+**New:**
+
+```python
+result = detector.detect(frame)
+
+for detection in result.detections:
+    class_name = detection.class_name
+    confidence = detection.confidence
+    bbox = detection.bbox
+    mask = detection.mask  # Already in correct format
+```
+
+### 3. Drone Control
+
+**Old (TelloPy):**
+
+```python
+import tellopy
+
+drone = tellopy.Tello()
+drone.connect()
+drone.takeoff()
+drone.up(50)
+```
+
+**New (djitellopy):**
+
+```python
+from tello_vision.tello_controller import TelloController
+
+drone = TelloController(config)
+drone.connect()
+drone.takeoff()
+drone.move_up(50)
+```
+
+### 4. Video Streaming
+
+**Old:**
+
+```python
+import av
+
+container = av.open(drone.get_video_stream())
+for packet in container.demux():
+    for frame in packet.decode():
+        # Process frame
+```
+
+**New:**
+
+```python
+frame = drone.get_frame()  # Simple!
+```
+
+### 5. Visualization
+
+**Old (Manual drawing):**
+
+```python
+def display_instances(image, boxes, masks, class_ids, class_names, scores):
+    # 50+ lines of manual drawing code
+    for i in range(n_instances):
+        # Draw mask
+        # Draw box
+        # Draw label
+    return image
+```
+
+**New:**
+
+```python
+from tello_vision.visualizer import Visualizer
+
+visualizer = Visualizer(config)
+frame = visualizer.draw_detections(frame, result)
+```
+
+### 6. Configuration
+
+**Old (Hardcoded):**
+
+```python
+SPEED = 50
+CONFIDENCE = 0.7
+MODEL_PATH = 'mask_rcnn_coco.h5'
+```
+
+**New (YAML):**
+
+```yaml
+# config.yaml
+detector:
+  backend: "yolov8"
+  yolov8:
+    model: "yolov8n-seg.pt"
+    confidence: 0.5
+
+drone:
+  speed: 50
+```
+
+## Converting Your Custom Code
+
+### In case you customized detection:
+
+**Old pattern:**
+
+```python
+# Custom class filtering in display_instances
+if class_names[class_ids[i]] not in ['person', 'car']:
+    continue
+```
+
+**New pattern:**
+
+```python
+# In config.yaml
+detector:
+  target_classes: ["person", "car"]
+
+# Or programmatically:
+result = result.filter_by_class(['person', 'car'])
+```
+
+### If you added tracking:
+
+**Old pattern:**
+
+```python
+# Embedded in main loop
+if tracking:
+    # Complex tracking logic mixed with everything
+```
+
+**New pattern:**
+
+```python
+# Separate tracker class
+from tello_vision.detectors.base_detector import DetectionResult
+
+class MyTracker:
+    def update(self, result: DetectionResult):
+        # Clean tracking logic
+        pass
+```
+
+### If you modified controls:
+
+**Old pattern:**
+
+```python
+# In TelloCV class
+def on_press(self, key):
+    if key == keyboard.Key.tab:
+        self.drone.takeoff()
+```
+
+**New pattern:**
+
+```python
+# In config.yaml
+controls:
+  takeoff: "tab"
+  custom_action: "x"
+
+# Or extend TelloController
+class MyController(TelloController):
+    def custom_action(self):
+        # Your logic
+```
+
+## Performance Improvements
+
+| Metric       | Old  | New (YOLOv8n) | Improvement     |
+| ------------ | ---- | ------------- | --------------- |
+| FPS (1050Ti) | 4.6  | 25-30         | **5-6x faster** |
+| FPS (CPU)    | ~1   | 2-3           | 2-3x faster     |
+| Memory       | ~4GB | ~2GB          | 50% less        |
+| Load time    | 30s  | 5s            | 6x faster       |
+| Code lines   | 500+ | 50            | 10x cleaner     |
+
+## Common Pitfalls
+
+### 1. Color Format
+
+- Old: Sometimes RGB, sometimes BGR
+- New: Consistently BGR (OpenCV standard)
+
+### 2. Mask Format
+
+- Old: 3D array, needs reshaping
+- New: 2D binary mask, ready to use
+
+### 3. Coordinates
+
+- Old: (y1, x1, y2, x2) format
+- New: (x1, y1, x2, y2) format
+
+### 4. Threading
+
+- Old: Manual thread management
+- New: Built-in async support
+
+## Step-by-Step Migration
+
+1. **Install new version:**
+
+   ```bash
+   ./install.sh
+   ```
+
+2. **Update dependencies:**
+   - Remove old `requirements.txt`
+   - Use `pyproject.toml` instead
+
+3. **Port configuration:**
+   - Extract hardcoded values
+   - Add to `config.yaml`
+
+4. **Refactor detection:**
+   - Replace Mask R-CNN calls with detector API
+   - Update result parsing
+
+5. **Update drone control:**
+   - Replace TelloPy with TelloController
+   - Use new control methods
+
+6. **Test incrementally:**
+   ```bash
+   python examples/test_detector.py  # Test detection only
+   python -m tello_vision.app        # Full system
+   ```
+
+## Need Help?
+
+- Check `examples/` directory for reference implementations
+- Run `python examples/benchmark.py` to test your setup
+- See README.md for detailed API docs
+
+## Still Using Old Features?
+
+If you need features from the old codebase that aren't in v2.0:
+
+1. **Color-based tracking:** Check `examples/object_follower.py`
+2. **Custom keyboard controls:** Extend `TelloController`
+3. **Specific model:** Implement custom `BaseDetector`
+
+Open an issue if you need help porting something specific!