meteor_detect/docs/watermark_overlay.md

Watermark Overlay System

Overview

The Watermark Overlay System is a feature that enables the addition of contextual information as visual overlays on video frames. This is particularly useful for scientific observations, providing critical metadata directly on the visual recording such as timestamps, geographical coordinates, and environmental conditions.

Key Features

1. Multiple Data Sources: Integrates information from:

   • System timestamp
   • GPS coordinates and camera orientation
   • Environmental sensors (temperature, humidity)
   • Custom text

2. Flexible Positioning: Supports placement in:

   • Top-left corner
   • Top-right corner
   • Bottom-left corner
   • Bottom-right corner
   • Custom pixel coordinates

3. Customizable Appearance:

   • Configurable font scale and thickness
   • Custom text and background colors
   • Optional background with transparency
   • Adjustable padding

4. Adaptive Formatting:

   • Configurable timestamp format
   • Multiple coordinate formats (decimal degrees or DMS)
   • Temperature units (Celsius or Fahrenheit)

Implementation Details

The watermark system is implemented in src/overlay/watermark.rs and consists of:

WatermarkOptions

Configuration class that controls all aspects of the watermark:

pub struct WatermarkOptions {
    pub enabled: bool,
    pub position: WatermarkPosition,
    pub font_scale: f64,
    pub thickness: i32,
    pub color: (u8, u8, u8, u8),
    pub background: bool,
    pub background_color: (u8, u8, u8, u8),
    pub padding: i32,
    pub content: Vec<WatermarkContent>,
    pub time_format: String,
    pub coordinate_format: String,
    pub temperature_format: String,
}

WatermarkPosition

Enum defining where the watermark appears on the frame:

pub enum WatermarkPosition {
    TopLeft,
    TopRight,
    BottomLeft,
    BottomRight,
    Custom(u32, u32),
}

WatermarkContent

Enum specifying what information to include:

pub enum WatermarkContent {
    Timestamp,
    GpsCoordinates,
    Environment,
    CameraOrientation,
    Custom(String),
}

Watermark Class

The Watermark class handles the actual rendering of information onto frames, with methods for:

• Creating watermarks with custom options
• Applying the watermark to video frames
• Formatting GPS coordinates, timestamps, and temperature

Integration with Frame Hooks

The watermark system is integrated into the application through the frame hook system:

1. A Watermark instance is created during application startup
2. It's wrapped in a BasicFrameHook and registered with the HookManager
3. When frames are processed by the pipeline, the hook manager calls the watermark's apply method

This implementation allows for:

• Clean separation of concerns
• Dynamically enabling/disabling the watermark
• Concurrent frame processing with other hooks

Example Configuration

The watermark can be configured in the application's configuration file:

[watermark]
enabled = true
position = "BottomLeft"
font_scale = 0.6
thickness = 1
color = [255, 255, 255, 255]  # White
background = true
background_color = [0, 0, 0, 128]  # Semi-transparent black
padding = 8
content = ["Timestamp", "GpsCoordinates", "Environment"]
time_format = "%Y-%m-%d %H:%M:%S%.3f"
coordinate_format = "decimal"
temperature_format = "C"

Performance Considerations

The watermark system uses OpenCV for text rendering and is designed to be efficient. Some considerations:

1. When disabled, the watermark has minimal overhead as it returns early
2. Text measurement and position calculations are done once per frame
3. Rendering is optimized for minimal impact on frame processing pipeline
4. The background rectangle is drawn as a single operation for efficiency

For extremely resource-constrained systems, consider:

• Using a smaller font scale
• Reducing the number of content items
• Enabling the watermark only when necessary

Use Cases

1. Scientific Validation: Adding timestamps and coordinates for scientific validity of observations
2. Calibration: Including environmental data for calibration of optical measurements
3. Field Work: Recording location information automatically during mobile observations
4. Data Processing: Simplifying post-processing by having metadata directly in the frames
5. Public Outreach: Including attribution or explanatory information on videos shared publicly

The watermark overlay system provides a robust way to ensure all critical metadata is permanently associated with visual observations, enhancing the scientific and practical value of the recorded video.