ConsistentlyInconsistentYT--Pixeltovoxelprojector/examples/README.md

8K Motion Tracking System - Example Applications

This directory contains comprehensive example applications demonstrating the capabilities of the 8K motion tracking system.

Overview

The examples progress from simple to complex, showcasing different aspects of the system:

1. basic_tracking.py - Simple single-pair tracking (beginner)
2. multi_camera_demo.py - Full 10-camera system (advanced)
3. drone_tracking_sim.py - 200 drone simulation (testing)
4. streaming_client.py - Real-time data streaming (integration)
5. calibration_tool.py - Camera calibration (setup)

Requirements

Common Requirements

• Python 3.8 or higher
• NumPy
• System modules from ../src

Optional Requirements

• Matplotlib (for visualization)
• OpenCV (cv2) - for actual calibration with real images
• LZ4 - for compressed streaming

Installation

# Install from project root
pip install -r requirements.txt

# Or install minimal requirements
pip install numpy

---

1. Basic Tracking Example

File: basic_tracking.py

Simple demonstration of single camera pair tracking with minimal configuration.

Features

• Single mono-thermal camera pair
• Basic object detection and tracking
• Voxel visualization
• Real-time motion coordinate display
• Minimal setup required

Usage

# Basic usage (30 seconds, camera pair 0)
python basic_tracking.py

# Specify duration
python basic_tracking.py --duration 60

# Different camera pair
python basic_tracking.py --camera-id 1 --duration 120

# With visualization
python basic_tracking.py --visualize

# Save tracking output
python basic_tracking.py --save-output tracking_data.json

Command-Line Options

Option	Description	Default
--camera-id ID	Camera pair ID	0
--duration SEC	Run duration in seconds	30
--visualize	Enable 3D visualization	False
--save-output FILE	Save tracking data to file	None

Output Example

==============================================================
BASIC TRACKING SYSTEM - Frame 450
==============================================================
Uptime:           15.0s
FPS:              30.1
Active Tracks:    8
Confirmed Tracks: 6
Detections:       4
Latency:          12.45 ms
--------------------------------------------------------------
Active Tracks:
  Track   0: pos=(  125.3,  -45.2) vel=( -2.1,   3.5) conf=0.89
  Track   1: pos=( -234.1,   89.7) vel=(  4.2,  -1.8) conf=0.92
  ...
--------------------------------------------------------------
Camera Status:    2/2 streaming
Avg Temperature:  47.3°C
==============================================================

---

2. Multi-Camera Demo

File: multi_camera_demo.py

Demonstrates the full-scale system with 10 camera pairs providing 360° coverage.

Features

• 10 mono-thermal camera pairs (20 cameras total)
• Circular array for 360° coverage
• Synchronized acquisition
• Multi-camera fusion
• Real-time performance monitoring
• System health dashboard
• Stress testing capability

Usage

# Normal operation (60 seconds)
python multi_camera_demo.py

# Extended run
python multi_camera_demo.py --duration 300

# Show detailed health metrics
python multi_camera_demo.py --show-health

# Save performance metrics
python multi_camera_demo.py --save-metrics metrics.json

# Stress test with 200 targets
python multi_camera_demo.py --stress-test --duration 120

# Custom number of pairs
python multi_camera_demo.py --num-pairs 5

Command-Line Options

Option	Description	Default
--duration SEC	Run duration in seconds	60
--show-health	Display detailed health metrics	False
--save-metrics FILE	Save metrics to JSON file	None
--stress-test	Run with 200 targets	False
--num-pairs N	Number of camera pairs	10

Output Example

================================================================================
MULTI-CAMERA TRACKING SYSTEM - Frame 1800
================================================================================
Uptime:             60.0s
FPS:                30.0
Frame Time:         32.1 ms

Tracking:
  Active Tracks:    156
  Confirmed:        149
  Detections:       168
  Latency:          45.23 ms

Multi-Camera Fusion:
  Avg Observations: 3.2 cameras/target
  Coverage:         360°

Camera System:
  Streaming:        20/20
  Ready:            0
  Errors:           0
  Avg FPS:          29.8
  Avg Temp:         48.5°C

System Resources:
  Memory:           287.3 MB
  Bandwidth:        3547.2 MB/s

Requirements Check:
  FPS ≥ 30:         ✓ (30.0)
  Latency < 100ms:  ✓ (45.23 ms)
  Tracks ≤ 200:     ✓ (149)
================================================================================

Performance Metrics File

When using --save-metrics, the output JSON contains:

• System configuration
• Per-frame metrics
• Summary statistics
• Camera health data
• Tracking performance

---

3. Drone Tracking Simulation

File: drone_tracking_sim.py

Realistic simulation of tracking 200 drones with various flight patterns.

Features

• Simulates up to 200 drones
• Realistic drone physics and trajectories
• Multiple trajectory types (linear, circular, hover, zigzag, spiral, evasive)
• Detection accuracy modeling
• Ground truth comparison
• Accuracy analysis (position/velocity RMSE)
• Configurable trajectory mix

Trajectory Types

1. Linear - Straight-line flight
2. Circular - Circular patterns
3. Hover - Hovering with small drift
4. Zigzag - Zigzag patterns
5. Spiral - Spiral ascent/descent
6. Evasive - Evasive maneuvers

Usage

# Standard 200 drone simulation
python drone_tracking_sim.py

# Custom drone count
python drone_tracking_sim.py --num-drones 100 --duration 60

# Different trajectory mixes
python drone_tracking_sim.py --trajectory-mix aggressive
python drone_tracking_sim.py --trajectory-mix calm

# With visualization
python drone_tracking_sim.py --visualize

# Save accuracy analysis
python drone_tracking_sim.py --save-analysis accuracy_report.json

Command-Line Options

Option	Description	Default
--num-drones N	Number of drones	200
--duration SEC	Simulation duration	120
--visualize	Enable visualization	False
--save-analysis FILE	Save analysis to file	None
--trajectory-mix TYPE	Trajectory distribution	balanced

Trajectory Mix Options

• balanced - Mix of all trajectory types
• aggressive - More evasive and zigzag patterns
• calm - More linear and hovering patterns

Output Example

======================================================================
DRONE TRACKING SIMULATION - Frame 3600
======================================================================
Sim Time:         120.0s
Drones:           200
Detections:       192
Active Tracks:    197
Confirmed:        189
Latency:          67.89 ms

Accuracy (last 100 frames):
  Position RMSE:  1.23 m
  Velocity RMSE:  0.45 m/s
  Detection Rate: 96.8%
======================================================================

FINAL ACCURACY ANALYSIS
======================================================================
Simulation Duration:  120.0s
Total Frames:         3600
Total Drones:         200

Tracking Accuracy:
  Position RMSE:      1.18 m
  Velocity RMSE:      0.42 m/s
  Detection Rate:     97.2%

Tracker Performance:
  Tracks Created:     245
  Tracks Confirmed:   198
  Avg Latency:        68.45 ms

Requirements:
  Detection Rate >99%:  ✗ (97.2%)
  Position RMSE <5m:    ✓ (1.18m)
  Latency <100ms:       ✓
======================================================================

---

4. Streaming Client

File: streaming_client.py

Real-time client for subscribing to and visualizing motion tracking data streams.

Features

• Multiple transport options (UDP, TCP, Shared Memory)
• Real-time target display
• 3D visualization (optional)
• Target statistics and analysis
• Low-latency streaming
• Data recording capability
• Automatic reconnection

Transport Types

1. Shared Memory - Lowest latency, local only
2. UDP - Low latency, unreliable
3. TCP - Reliable, slightly higher latency

Usage

# Connect via shared memory (lowest latency)
python streaming_client.py

# Connect via UDP
python streaming_client.py --transport udp --host 192.168.1.100 --port 8888

# Connect via TCP
python streaming_client.py --transport tcp --host 192.168.1.100 --port 8889

# Run for specific duration
python streaming_client.py --duration 300

# With visualization
python streaming_client.py --visualize

# Save received data
python streaming_client.py --save-data stream_data.json

# Custom statistics interval
python streaming_client.py --stats-interval 10

Command-Line Options

Option	Description	Default
--transport TYPE	Transport: udp, tcp, shared_memory	shared_memory
--host HOST	Server host address	127.0.0.1
--port PORT	Server port	8888
--duration SEC	Run duration (None = indefinite)	None
--visualize	Enable 3D visualization	False
--save-data FILE	Save received data	None
--stats-interval SEC	Statistics interval	5

Output Example

======================================================================
STREAMING CLIENT STATUS
======================================================================
Connection:       shared_memory
Uptime:           45.2s
Messages:         1356
Message Rate:     30.0 msg/s
Avg Latency:      2.34 ms

Targets:
  Total Seen:     87
  Active (5s):    23
  Update Rate:    156 updates/s

Top Active Targets:
  Target   5: updates= 245 age=42.3s conf=0.95 max_speed=18.2m/s
  Target  12: updates= 198 age=38.7s conf=0.91 max_speed=14.5m/s
  Target  23: updates= 176 age=35.2s conf=0.88 max_speed=16.8m/s
  ...

Subscriber Stats:
  Received:       1356
  Dropped:        3
  Errors:         0
  Throughput:     30.0 msg/s
  Bandwidth:      1.2 MB/s
======================================================================

---

5. Calibration Tool

File: calibration_tool.py

Interactive tool for camera calibration and validation.

Features

• Intrinsic calibration (individual cameras)
• Stereo calibration (camera pairs)
• Mono-thermal registration
• Checkerboard/circle pattern detection
• Calibration validation
• Quality assessment
• Parameter export to JSON
• Batch calibration for all pairs

Calibration Workflow

1. Intrinsic Calibration - Calibrate individual camera parameters
2. Stereo Calibration - Calibrate relative geometry between pair
3. Registration - Register mono and thermal images
4. Validation - Verify calibration quality
5. Export - Save parameters to files

Usage

# Calibrate single pair (complete workflow)
python calibration_tool.py --pair-id 0

# Specify calibration target
python calibration_tool.py --target checkerboard --pair-id 0
python calibration_tool.py --target circles --pair-id 1

# Custom number of calibration images
python calibration_tool.py --num-images 30 --pair-id 0

# With validation
python calibration_tool.py --validate --pair-id 0

# Export to custom directory
python calibration_tool.py --export-dir ./my_calibration --pair-id 0

# Calibrate all 10 pairs
python calibration_tool.py --all-pairs --num-images 25

# Show calibration report
python calibration_tool.py --report

Command-Line Options

Option	Description	Default
--pair-id ID	Camera pair to calibrate	0
--target TYPE	Target: checkerboard, circles	checkerboard
--num-images N	Number of calibration images	20
--validate	Run validation after calibration	False
--export-dir DIR	Export directory	calibration
--all-pairs	Calibrate all 10 pairs	False
--report	Show calibration report	False

Output Example

======================================================================
COMPLETE CALIBRATION WORKFLOW - Pair 0
======================================================================

This will perform:
  1. Mono camera intrinsic calibration
  2. Thermal camera intrinsic calibration
  3. Stereo pair calibration
  4. Mono-thermal registration
  5. Validation
======================================================================

======================================================================
INTRINSIC CALIBRATION - Pair 0 MONO Camera
======================================================================

1. Capturing 20 calibration images...
2. Detecting calibration pattern...
Pattern detection: 20/20 successful (100.0%)
3. Computing camera calibration...

✓ Calibration successful!

Intrinsic Parameters:
  Focal Length:     fx=9216.0, fy=9216.0
  Principal Point:  cx=3840.0, cy=2160.0
  Distortion:       [0.05 -0.02 0.0 0.0 0.01]
  Reprojection Error: 0.387 pixels
======================================================================

... (continues for thermal, stereo, registration) ...

======================================================================
CALIBRATION VALIDATION - Pair 0
======================================================================

1. Intrinsic Calibration:
   Mono:    ✓ (error=0.387px)
   Thermal: ✓ (error=0.421px)

2. Stereo Calibration:
   Status:  ✓
   Reproj:  0.523px
   Epipolar: 0.287px

3. Mono-Thermal Registration:
   Status:  ✓
   Error:   1.834px
   MI:      0.892

----------------------------------------------------------------------
Overall: ✓ VALID
======================================================================

✓ Calibration exported successfully

Calibration Files

Exported calibration files (JSON format):

• pair_0_calibration.json - Complete calibration data
• Contains:
  • Camera intrinsics (focal length, distortion)
  • Stereo parameters (baseline, rotation, translation)
  • Registration parameters (homography, mapping)
  • Quality metrics

---

Integration Examples

Example 1: Run Basic Tracking and Stream Data

# Terminal 1: Start basic tracking (generates motion data)
python basic_tracking.py --duration 300

# Terminal 2: Connect streaming client
python streaming_client.py --save-data motion_log.json

Example 2: Calibrate and Validate System

# Calibrate all camera pairs
python calibration_tool.py --all-pairs --num-images 25

# Validate with drone simulation
python drone_tracking_sim.py --num-drones 200 --save-analysis validation.json

# View calibration report
python calibration_tool.py --report

Example 3: Performance Testing

# Stress test multi-camera system
python multi_camera_demo.py --stress-test --duration 300 --save-metrics stress_test.json

# Analyze results
python -c "import json; data=json.load(open('stress_test.json')); print('Avg FPS:', data['summary']['avg_fps'])"

---

Performance Expectations

Basic Tracking (1 pair, 50 targets)

• FPS: 30+
• Latency: 10-20 ms
• Memory: < 100 MB
• CPU: Single core

Multi-Camera (10 pairs, 100 targets)

• FPS: 30+
• Latency: 40-60 ms
• Memory: 200-400 MB
• Bandwidth: 3-4 GB/s (compressed)

Stress Test (10 pairs, 200 targets)

• FPS: 28-30
• Latency: 60-80 ms
• Memory: 400-500 MB
• CPU: Multi-core utilized

Drone Simulation (200 drones)

• Position RMSE: < 2 m
• Velocity RMSE: < 0.5 m/s
• Detection Rate: 95-98%
• Latency: 60-80 ms

---

Troubleshooting

Common Issues

1. Import Errors

# Ensure you run from examples directory
cd /path/to/Pixeltovoxelprojector/examples
python basic_tracking.py

2. Shared Memory Connection Failed

# Check if shared memory exists
ls -la /dev/shm/

# Try UDP instead
python streaming_client.py --transport udp

3. Low FPS

# Reduce number of targets
python multi_camera_demo.py --num-pairs 5

# Check system resources
htop

4. Calibration Pattern Not Detected

# Ensure proper lighting
# Use higher contrast checkerboard
# Increase number of images
python calibration_tool.py --num-images 30

---

Development Notes

Simulated vs Real Implementation

These examples use simulated data for demonstration purposes:

• Camera frames are simulated (random data)
• Detections are generated algorithmically
• No actual hardware required

For Real Hardware

To use with real cameras:

1. Replace simulate_detections() with actual frame grabbing
2. Implement real detection algorithms (YOLO, etc.)
3. Add actual calibration pattern detection (OpenCV)
4. Connect to real GigE Vision cameras
5. Implement real coordinate streaming protocol

Key Files to Modify

• basic_tracking.py: Line ~150 (simulate_detections)
• multi_camera_demo.py: Line ~300 (simulate_multi_camera_detections)
• calibration_tool.py: Line ~100 (simulate_calibration_images)

---

Additional Resources

• System Architecture
• API Documentation
• Performance Tuning
• Hardware Setup

---

License

See LICENSE file for details.

Support

For issues or questions:

• Open an issue on GitHub
• Contact: support@motiontracking.com
• Documentation: https://docs.motiontracking.com