ConsistentlyInconsistentYT--Pixeltovoxelprojector/USAGE_GUIDE.md

8K Motion Tracking System - Usage Guide

Table of Contents

1. Quick Start
2. Configuration
3. Running the System
4. Application Architecture
5. Examples
6. Troubleshooting

Quick Start

Installation

# Clone repository
git clone https://github.com/yourusername/Pixeltovoxelprojector.git
cd Pixeltovoxelprojector

# Install dependencies
pip install -r src/requirements.txt

# Install system requirements (Ubuntu/Debian)
sudo apt-get install libyaml-dev

# Build C++ extensions (optional, for best performance)
cd src
python setup_motion_extractor.py build_ext --inplace

Basic Usage

# Run with default configuration
cd src
python main.py

# Run with custom configuration
python main.py --config path/to/config.yaml

# Run in verbose mode
python main.py --verbose

# Run in simulation mode (no hardware required)
python main.py --simulate

# Validate configuration
python main.py --validate-config

Configuration

The system is configured via a YAML file (config/system_config.yaml).

Key Configuration Sections

1. System Settings

system:
  name: "8K Motion Tracking System"
  version: "1.0.0"
  environment: "production"  # production, development, testing
  log_level: "INFO"  # DEBUG, INFO, WARNING, ERROR

2. Camera Configuration

cameras:
  num_pairs: 10
  pairs:
    - pair_id: 0
      mono:
        camera_id: 0
        ip_address: "192.168.1.100"
        width: 7680
        height: 4320
        frame_rate: 30.0
      thermal:
        camera_id: 1
        ip_address: "192.168.1.101"
        width: 7680
        height: 4320
        frame_rate: 30.0
      baseline_m: 0.5
      position: [0.0, 0.0, 10.0]

3. Voxel Grid Configuration

voxel_grid:
  center: [0.0, 0.0, 500.0]  # meters
  size: [5000.0, 5000.0, 2000.0]  # meters
  base_resolution: 1.0  # meters per voxel
  enable_lod: true
  max_memory_mb: 500

4. Detection and Tracking

detection:
  motion_threshold: 0.2
  max_tracks: 200
  detection_confidence: 0.5
  enable_kalman_filter: true

5. Performance Settings

performance:
  num_processing_threads: 8
  enable_gpu: true
  enable_memory_pooling: true
  process_priority: "high"

Running the System

Standard Operation

# 1. Ensure cameras are connected and powered
# 2. Verify network connectivity (ping camera IPs)
# 3. Run the system
cd src
python main.py --config config/system_config.yaml

Simulation Mode

For development and testing without hardware:

python main.py --simulate

This mode:

• Generates synthetic camera data
• Simulates all processing stages
• Useful for testing configurations
• No camera hardware required

With Monitoring

# Terminal 1: Run main system
python main.py --verbose

# Terminal 2: Monitor system metrics
python monitoring/system_monitor.py

# Terminal 3: View logs
tail -f logs/motion_tracking.log

Application Architecture

Component Overview

┌─────────────────────────────────────────────────────────────┐
│                      Main Application                        │
│                        (main.py)                             │
└────────────────────────┬────────────────────────────────────┘
                         │
         ┌───────────────┴──────────────┐
         │                               │
┌────────▼──────────┐         ┌─────────▼──────────┐
│  Configuration    │         │  Pipeline          │
│  Loader           │         │  Coordinator       │
└────────┬──────────┘         └─────────┬──────────┘
         │                               │
         │        ┌──────────────────────┴─────────────────┐
         │        │                                         │
         │  ┌─────▼──────┐  ┌──────────┐  ┌─────────────┐ │
         └─►│  Camera    │  │  Fusion  │  │  Voxel      │ │
            │  Manager   │  │  Manager │  │  Manager    │ │
            └─────┬──────┘  └─────┬────┘  └──────┬──────┘ │
                  │               │               │        │
            ┌─────▼───────────────▼───────────────▼──────┐ │
            │        Processing Pipeline                  │ │
            │  ┌──────────┐  ┌──────────┐  ┌──────────┐ │ │
            │  │ Motion   │→ │ Tracking │→ │ Voxel    │ │ │
            │  │ Extract  │  │          │  │ Update   │ │ │
            │  └──────────┘  └──────────┘  └──────────┘ │ │
            └────────────────────┬────────────────────────┘ │
                                 │                           │
                        ┌────────▼──────────┐               │
                        │  System Monitor   │◄──────────────┘
                        └───────────────────┘

Data Flow

1. Camera Acquisition

   • Cameras capture 8K frames at 30 FPS
   • Hardware-triggered synchronization
   • Frame buffering and management

2. Motion Extraction

   • C++ accelerated motion detection
   • Thermal-mono fusion
   • Coordinate extraction

3. Tracking

   • Multi-target Kalman filter tracking
   • Track management (200+ simultaneous)
   • Occlusion handling

4. Voxel Updates

   • 3D position mapping
   • Multi-resolution LOD grid
   • Memory-efficient updates

5. Streaming

   • Real-time coordinate streaming
   • Network protocol (UDP/TCP/Shared Memory)
   • Low-latency delivery

Examples

Example 1: Basic System Startup

#!/usr/bin/env python3
from main import MotionTrackingSystem

# Create system
system = MotionTrackingSystem(
    config_file='config/system_config.yaml',
    verbose=True,
    simulate=False
)

# Load configuration
system.load_configuration()

# Initialize components
system.initialize_components()

# Start system
system.start()

# Run for 60 seconds
import time
time.sleep(60)

# Stop system
system.stop()

Example 2: Custom Coordinate Callback

from main import MotionTrackingSystem

def coordinate_callback(result):
    """Custom callback for coordinate streaming"""
    print(f"Frame {result.frame_number}: {len(result.confirmed_tracks)} tracks")
    for track in result.confirmed_tracks:
        print(f"  Track {track['track_id']}: ({track['x']:.1f}, {track['y']:.1f})")

# Initialize system
system = MotionTrackingSystem('config/system_config.yaml')
system.load_configuration()
system.initialize_components()

# Register callback
system.pipeline.register_coordinate_callback(coordinate_callback)

# Start and run
system.start()
system.run()

Example 3: Monitor System Status

import time
from main import MotionTrackingSystem

system = MotionTrackingSystem('config/system_config.yaml')
system.load_configuration()
system.initialize_components()
system.start()

try:
    while True:
        # Get system status
        if system.coordinator:
            status = system.coordinator.get_system_status()
            print(f"Health: {status['overall_health']}")
            print(f"Uptime: {status['uptime_seconds']:.1f}s")

        # Get pipeline metrics
        if system.pipeline:
            metrics = system.pipeline.get_metrics()
            print(f"FPS: {metrics['throughput_fps']:.1f}")
            print(f"Latency: {metrics['avg_latency_ms']:.1f}ms")

        time.sleep(5)

except KeyboardInterrupt:
    system.stop()

Example 4: Configuration Validation

from main import MotionTrackingSystem

# Validate configuration without running
system = MotionTrackingSystem('config/system_config.yaml')

if system.load_configuration():
    print("✓ Configuration is valid")

    # Print summary
    print(f"Cameras: {system.config['cameras']['num_pairs']} pairs")
    print(f"Voxel grid: {system.config['voxel_grid']['size']}")
    print(f"Max tracks: {system.config['detection']['max_tracks']}")
else:
    print("✗ Configuration is invalid")

Command-Line Interface

Available Options

python main.py [OPTIONS]

Options:
  --config PATH         Path to configuration file
                        (default: config/system_config.yaml)

  -v, --verbose         Enable verbose logging

  --simulate            Run in simulation mode (no hardware)

  --validate-config     Validate configuration and exit

  --version             Show version and exit

  -h, --help            Show help message and exit

Usage Examples

# Basic run with default config
python main.py

# Run with custom config
python main.py --config my_config.yaml

# Verbose logging
python main.py --verbose

# Simulation mode for testing
python main.py --simulate

# Just validate the configuration
python main.py --validate-config

Troubleshooting

Common Issues

1. Configuration File Not Found

Error: Configuration file not found: config/system_config.yaml

Solution: Ensure the config file exists or specify the correct path:

python main.py --config /path/to/config.yaml

2. Camera Connection Failed

Error: Failed to connect camera 0 at 192.168.1.100

Solution:

• Verify camera is powered on
• Check network connectivity: ping 192.168.1.100
• Ensure IP address is correct in config
• Check firewall settings

3. Insufficient Memory

Error: Failed to allocate voxel grid: out of memory

Solution:

• Reduce voxel_grid.max_memory_mb in config
• Enable compression: voxel_grid.enable_compression: true
• Use higher resolution: voxel_grid.base_resolution: 2.0

4. Low FPS Performance

Warning: FPS below target: 15.2 / 30.0

Solution:

• Enable GPU: performance.enable_gpu: true
• Increase threads: performance.num_processing_threads: 16
• Reduce resolution in cameras section
• Enable hardware acceleration

5. High CPU Usage

Warning: CPU utilization critical: 95%

Solution:

• Reduce number of processing threads
• Enable GPU acceleration
• Optimize detection thresholds
• Check for runaway processes

Debug Mode

Enable debug logging for detailed information:

# In config file
logging:
  levels:
    root: "DEBUG"
    camera: "DEBUG"
    pipeline: "DEBUG"

Or use verbose mode:

python main.py --verbose

Performance Profiling

# Enable profiling
python -m cProfile -o profile.stats main.py

# View results
python -m pstats profile.stats

Log Files

Logs are written to:

• logs/motion_tracking.log - Main application log
• logs/system_metrics.json - Performance metrics
• logs/profile.txt - Profiling data (if enabled)

Getting Help

1. Check logs: tail -f logs/motion_tracking.log
2. View system status via monitoring interface
3. Run configuration validation: python main.py --validate-config
4. Open an issue on GitHub with logs and configuration

Advanced Usage

Custom Pipeline Configuration

You can customize the processing pipeline:

from pipeline import ProcessingPipeline, PipelineConfig

custom_config = PipelineConfig(
    target_fps=60.0,
    enable_fusion=True,
    enable_tracking=True,
    num_processing_threads=16
)

pipeline = ProcessingPipeline(
    config=custom_config,
    camera_manager=camera_mgr,
    voxel_manager=voxel_mgr,
    fusion_manager=fusion_mgr,
    tracker=tracker
)

Network Streaming

Configure network streaming in the config file:

network:
  protocol: "mtrtp"
  transport: "udp"  # udp, tcp, shared_memory
  udp:
    host: "0.0.0.0"
    port: 8888
  compression: "lz4"
  stream_coordinates: true

Recording Sessions

Enable data recording:

recording:
  enabled: true
  output_dir: "recordings"
  record_motion_data: true
  record_tracking_data: true

Performance Tips

1. Enable GPU Acceleration

   performance:
     enable_gpu: true
   

2. Optimize Threading

   • Set threads to 2x CPU cores for I/O bound
   • Set threads to 1x CPU cores for CPU bound

3. Use Hardware Triggers

   cameras:
     trigger:
       enabled: true
       source: "external"
   

4. Enable Memory Pooling

   performance:
     enable_memory_pooling: true
     preallocate_buffers: true
   

5. Tune Network Settings

   cameras:
     network:
       packet_size: 9000  # Jumbo frames
       packet_delay: 1000
   

---

For more information, see:

• README.md - Project overview
• IMPLEMENTATION_SUMMARY.md - Technical details
• PERFORMANCE_REPORT.md - Performance analysis