Clipper

A specialized OpenFilter component that extracts regions of interest (ROIs) from video frames using either detection metadata or predefined polygons. Supports multiple cropping modes, flexible output options, and comprehensive configuration validation.

Features

• Multiple Cropping Modes: Polygon-based cropping, detection-based cropping, and legacy environment-based configuration
• Flexible Output Options: Create new frames for cropped regions or modify original frames in-place
• Topic Selection Modes: Process all topics, main only, or selected topics from a configured list
• Configuration Validation: Prevents typos with helpful error messages and suggestions
• Backward Compatibility: Supports legacy configuration via environment variables

Quick Start

Prerequisites

IMPORTANT! You need access to OpenFilter and the required dependencies:

# Install OpenFilter (if not already installed)
pip install openfilter

# Install the crop filter
pip install filter-crop

Installation

# Create virtual environment
virtualenv venv
source venv/bin/activate

# Install the filter
make install

Basic Usage

from openfilter import Filter

# Simple polygon cropping pipeline
filters = [
    Filter("VideoIn", {
        "sources": "file://sample_video.mp4",
        "outputs": "tcp://127.0.0.1:5550"
    }),
    Filter("FilterCrop", {
        "sources": "tcp://127.0.0.1:5550",
        "outputs": "tcp://127.0.0.1:5551",
        "polygon_points": "[[(100, 100), (400, 100), (400, 300), (100, 300)]]",
        "output_prefix": "cropped_",
        "topic_mode": "all"
    }),
    Filter("Webvis", {
        "sources": "tcp://127.0.0.1:5551",
        "outputs": "tcp://127.0.0.1:8080"
    })
]

Filter.run_multi(filters, exit_time=30.0)

Documentation

For comprehensive documentation including:

• Complete configuration reference
• Sample pipelines and use cases
• Troubleshooting guides
• API documentation

Refer to docs/overview.md

Development

Running Locally

# Run the filter locally
make run

# Navigate to http://localhost:8000 to see the output

Running in Docker

# Build the filter docker image
make build-image

# Generate docker-compose.yaml (if needed)
make compose

# Run the containerized filter
make run-image

Testing

# Run unit tests
make test

# Run specific test files
pytest tests/test_filter_crop.py -v
pytest tests/test_smoke_simple.py -v
pytest tests/test_integration_config_normalization.py -v

Configuration Examples

Basic Polygon Crop

{
    "id": "polygon_cropper",
    "sources": "tcp://127.0.0.1:5550",
    "outputs": "tcp://127.0.0.1:5551",
    "polygon_points": "[[(100, 100), (400, 100), (400, 300), (100, 300)]]",
    "output_prefix": "cropped_",
    "topic_mode": "all"
}

Detection-Based Crop

{
    "id": "detection_cropper",
    "sources": "tcp://127.0.0.1:5550",
    "outputs": "tcp://127.0.0.1:5551",
    "detection_key": "detections",
    "detection_class_field": "class",
    "detection_roi_field": "rois",
    "topic_mode": "main_only"
}

In-Place Modification

{
    "id": "inplace_cropper",
    "sources": "tcp://127.0.0.1:5550",
    "outputs": "tcp://127.0.0.1:5551",
    "polygon_points": "[[(100, 100), (400, 100), (400, 300), (100, 300)]]",
    "mutate_original_frames": true,
    "topic_mode": "main_only"
}

Multi-Camera Processing

{
    "id": "multi_camera_cropper",
    "sources": ["tcp://127.0.0.1:5550", "tcp://127.0.0.1:5551"],
    "outputs": "tcp://127.0.0.1:5552",
    "polygon_points": "[[(50, 50), (300, 50), (300, 250), (50, 250)]]",
    "topic_mode": "selected",
    "topics": ["camera1", "camera2"],
    "output_prefix": "region_"
}

Use Cases

• Security Camera Monitoring: Extract specific regions from security camera feeds
• Object Detection and Extraction: Extract detected objects for further analysis
• Multi-Camera Surveillance: Process multiple camera feeds with selective region extraction
• Content Creation and Editing: Extract specific regions for content creation

See docs/overview.md for detailed use case examples and sample pipelines.

Configuration Reference

Required Configuration

Optional Configuration

Error Handling

The filter provides helpful error messages for common configuration mistakes:

• Typo Prevention: Unknown config key "polygon_point". Did you mean "polygon_points"?
• Invalid Polygon: Polygon must have at least three vertices.
• Missing Output Prefix: output_prefix cannot be empty when mutate_original_frames is False