LiteWing Object Tracking System (Ceiling Camera) 🛸🎯

This subsystem enables autonomous drone flight control by tracking a target object and the drone itself in real-time using a ceiling-mounted camera.

The tracking system uses color thresholding (HSV filtering) and blob analysis to calculate the relative distance and bearing between the drone and the target object, executing autonomous maneuvers to follow the target.

---

📂 Core Script

The repository is built around a single unified tracking script:

• object_tracking.py: The main application containing the CV2 capture loop, HSV-based target and drone detection, the 3-zone movement controller, and the heads-up display (HUD) visualization overlay.

---

⚙️ Tracking Mechanics & Zone Model

The tracking controller in track() operates on a 3-Zone Distance Model to maintain a safe and stable following distance relative to the target:

                  [Target Object]
                         │
                         ▼
┌─────────────────────────────────────────────────┐
│ Zone 1: Retreat (Distance < RETREAT_DIST)       │ ──► Drone backs away (move opposite)
├─────────────────────────────────────────────────┤
│ Zone 2: Maintain (RETREAT_DIST <= d < FOLLOW_D) │ ──► Drone hovers (no keys active)
├─────────────────────────────────────────────────┤
│ Zone 3: Follow (Distance >= FOLLOW_DIST)        │ ──► Drone moves toward target
└─────────────────────────────────────────────────┘

1. Detection Process

The function detect() extracts color coordinates for:

• Target (Blue): Filtered using HSV thresholds BLUE_LO and BLUE_HI.
• Drone (Green): Filtered using HSV thresholds GREEN_LO and GREEN_HI (identifying the green marker paper on top of the drone). Both masks undergo morphological erosion and dilation to filter out noise, selecting the largest contour meeting the MIN_AREA threshold.

2. Decision Matrix

Once coordinates are acquired, the delta offset ($dx, dy$) and Euclidean distance are computed. The movement axes are defined as:

• Dominant Axis Navigation: The controller identifies whether the vertical or horizontal offset is greater (vert_dom = abs(dy) >= abs(dx)) and prioritizes correcting that axis first.
• Deadzone: Adjustments are only applied if the delta exceeds DEADZONE pixels to prevent continuous jitter.
• Out-of-Bounds Protection: If either the target or the drone approaches within BOUNDARY pixels of the frame edge, the system flags the state and highlights the boundary in red.

---

🎮 Flight Controls & HUD Indicators

During operation, keyboard input is captured via msvcrt in the command window.

Keyboard Controls

Key	Action	Description
T / t	Takeoff	Arms the drone, initiates takeoff to TARGET_HEIGHT, and spawns the autonomous tracking loop thread.
L / l	Land	Disables active tracking control and initiates a soft landing sequence.
SPACE	Emergency Stop	Immediately cuts motor power (E-Stop). Use only in case of collision risk.
Q / q	Quit	Shuts down tracking, lands the drone safely if flying, releases the camera, and exits.

HUD Visual Indicators

The heads-up display overlay rendered by draw_hud() provides:

• Blue Ring / Point: Highlighted target location labeled TARGET.
• Green Ring / Point: Highlighted drone location labeled DRONE.
• Yellow Vector Arrow: Direct line showing the drone-to-target path and trajectory.
• Inner Orange Ring: The RETREAT_DIST threshold.
• Outer Green Ring: The FOLLOW_DIST threshold.
• Top-Left Status: Current tracking state (e.g., TRACKING, MAINTAINING, TOO CLOSE, TARGET LOST) colored dynamically.
• Bottom-Left Telemetry: Real-time battery voltage (Bat V) and altitude (Alt m) readout from the drone.
• Debug Badge: Shows [DEBUG] on the top-right if simulated mode is active.

---

🛠️ Setup & Installation

1. Prerequisites

Install the required tracking dependencies using the provided requirements.txt:

pip install -r requirements.txt

Important

The tracking script requires the LiteWing Drone Library to communicate with the drone. You must install the library to run the code. To learn more about its API, manual controls, and installation steps, visit the official LiteWing Library Repository.

2. Configuration Settings

Open object_tracking.py and modify the top configuration constants as needed:

• DEBUG_MODE (0 or 1): If set to 1, puts the drone library in debug mode (simulated operation).
• CAMERA_INDEX (default 1): Video capture device index (e.g., 0 for internal laptop webcam, 1 for external overhead camera).
• DRONE_IP: The local IP address of your LiteWing drone (default "192.168.43.42").
• SENSITIVITY (default 0.2): Modifier for manual/autonomous action speeds.
• TARGET_HEIGHT (default 0.4): Hover altitude in meters.
• RESIZE_WIDTH / RESIZE_HEIGHT: Output resolution configuration (leave as None to use raw camera output resolution).

3. Tuning & Customizing HSV Limits for Target/Drone Colors

The target object and drone marker colors can be changed according to your custom setup. To change the tracked target or drone marker colors, adjust these HSV thresholds in object_tracking.py:

• BLUE_LO / BLUE_HI: Lower and upper HSV boundaries for detecting the tracking target (defaults to a blue ball). Modify these coordinates to track target objects of different colors (e.g., Red, Yellow, or Orange).
• GREEN_LO / GREEN_HI: Lower and upper HSV boundaries for detecting the drone marker (defaults to green paper/tape on top of the drone). Adjust these values if your drone marker uses a different color.

Tip

Ensure the target color and drone marker color are distinct and have sufficient contrast under your lighting conditions to avoid detection overlap. You can use an HSV color-space picker tool to determine exact values for your custom targets.

---

🚀 How to Run

1. Power on your LiteWing drone and connect your PC to the drone's access point network.
2. Run the tracking script:

   python object_tracking.py

3. The LiteWing Tracker OpenCV frame window will open.
4. Press T to take off. The drone will hover and automatically track the blue target.