Skip to main content

Documentation

Complete documentation for the SAM3 detector filter.

ContentsDirect link to Contents

Core DocumentationDirect link to Core Documentation

Getting StartedDirect link to Getting Started

  1. New to the project? Start with the Main README
  2. Need configuration help? See the Configuration Guide
  3. Looking for examples? Check Scripts README
  4. Want to optimize? Read Performance Tuning

Documentation StructureDirect link to Documentation Structure

docs/
├── README.md              # This file - documentation index
├── API.md                 # Complete API reference
├── configuration.md       # Configuration guide
├── advanced-usage.md      # Advanced patterns and examples
└── performance.md         # Performance optimization guide

API OverviewDirect link to API Overview

Main ClassesDirect link to Main Classes

  • FilterSAM3Detector - Main filter class for object detection
  • FilterSAM3DetectorConfig - Configuration class

Key MethodsDirect link to Key Methods

  • setup(config) - Initialize the filter
  • process(frames) - Process frames and detect objects
  • shutdown() - Clean up resources
  • normalize_config(config) - Normalize and validate configuration

See API.md for complete documentation.

Configuration OverviewDirect link to Configuration Overview

Prompt ModesDirect link to Prompt Modes

  1. Text Prompts: Natural language descriptions

    {"text_prompt": "person"}

  2. Exemplar Images: Few-shot learning with examples

    {"exemplars_path": "./examples/"}

Key ParametersDirect link to Key Parameters

  • confidence_threshold - Detection confidence (0.0-1.0)
  • max_detections - Maximum detections per frame
  • output_masks - Include segmentation masks
  • device - Processing device (cuda/cpu/mps)

See configuration.md for details.

Common Use CasesDirect link to Common Use Cases

Basic DetectionDirect link to Basic Detection

from filter_sam3_detector import FilterSAM3Detector

config = {
    "text_prompt": "person",
    "confidence_threshold": 0.5,
}

filter = FilterSAM3Detector()
filter.setup(filter.normalize_config(config))

Pipeline IntegrationDirect link to Pipeline Integration

from openfilter.filter_runtime.filter import Filter
from openfilter.filter_runtime.filters.video_in import VideoIn
from openfilter.filter_runtime.filters.recorder import Recorder

filters = [
    (VideoIn, {"sources": "file://input.mp4"}),
    (FilterSAM3Detector, {"text_prompt": "person"}),
    (Recorder, {"path": "output.jsonl"}),
]

Filter.run_multi(filters)

See advanced-usage.md for more examples.

Performance TipsDirect link to Performance Tips

  1. Use GPU for 10-50x speedup
  2. Resize inputs to appropriate resolution (480p recommended)
  3. Disable masks if not needed (saves memory)
  4. Limit detections to reasonable numbers
  5. Optimize confidence threshold for your use case

See performance.md for detailed optimization guide.

TroubleshootingDirect link to Troubleshooting

Common issues and solutions:

  • Slow processing: Use GPU, resize inputs, limit detections
  • Memory errors: Disable masks, reduce max_detections, use CPU
  • No detections: Lower confidence threshold, check prompts
  • Import errors: Ensure package is installed correctly

See the Main README troubleshooting section for more help.

ContributingDirect link to Contributing

Found an issue or want to improve the documentation?

  1. Check existing issues
  2. Create a new issue or pull request
  3. Follow the contribution guidelines

LicenseDirect link to License

Apache-2.0