Changelog

Protege Model filter release notes

v0.1.32 - 2026-09-23

Changed

• Bump the openfilter dependency to 1.4.0

v0.1.31 - 2026-08-21

Added

• ByteTrack tracking, opt-in via enable_tracking (PLAT-1524). A pipeline that needed track ids had to use filter-deimv2-detection, which only loads DEIMv2, so tracking and the choice between RT-DETR and DEIMv2 were the same decision. This filter serves any Protege artifact, so putting the tracker here separates them. The id is what lets a downstream filter run once per object rather than once per frame: colour and description on a car in view for 200 frames becomes one call instead of 200. Off by default, since it costs a tracker update per frame and only pays off when something downstream keys on the id. One tracker per topic rather than one global, because two camera streams share a model instance and a single tracker would match an object in one feed against an object in the other. Ids are emitted as tracker_ids, parallel to rois, so consumers that index into rois positionally are unaffected. A tracker failure degrades to untracked rather than dropping the frame: a detection without an id is still a detection.

Fixed

• Clamp boxes at the frame edge instead of dropping them (PLAT-1567). This changes detection output on every pipeline, including those that never turn tracking on. A 1e-6 tolerance check sat above the existing clamp in _validate_bbox and returned early, so a normalised box even fractionally outside [0, 1] was rejected rather than clamped. Measured on a DEIMv2 weapons model over 80 images: 71 boxes dropped against 112 delivered, 39% of the model's output, nine of them gun. It was also not architecture-neutral: over 120 frames DEIMv2 emitted 8.0% out-of-range boxes and RT-DETR 0.0%, so the reject penalised one architecture and skewed any comparison between them made through this filter. Boxes up to OUT_OF_RANGE_LIMIT (0.05, 5% of the frame) outside range are now clamped and kept; beyond that they are still dropped and logged, since the coordinates are wrong rather than imprecise. Expect detection counts to rise on DEIMv2 pipelines after this release.

v0.1.30 - 2026-08-20

Fixed

• Accept Protege's task name for object detection (FILTER-637). Protege writes task = "object_detection" into a trained artifact's run_config; this filter calls that task "detection" and compared the two strings without normalising, so autodetection raised on every object-detection artifact Protege produces, DEIMv2 and RT-DETR alike. That is why every detection script under scripts/ passes protege_task explicitly: the workaround lived in the callers. The alias is applied at all three points a task can arrive from: config, PROTEGE_TASK, and the artifact itself.

Changed

• Bump the openfilter dependency to 1.3.0
• protege-runtime~=0.33.0 becomes protege-runtime[transformers]>=0.33.15,<0.34. 0.33.15 is the first release carrying DEIMv2 support, so the old specifier could resolve to a release that cannot load these artifacts at all.
• transformers moves from 4.x to 5.x, and stops being a direct dependency of this project. It was transformers>=4.45,<5 here; DEIMv2 landed in transformers 5.10 and is absent from 4.57, so 4.x cannot load these artifacts. The floor now comes from protege-runtime[transformers], which declares transformers>=5.10,<6, verified in the runtime's pyproject.toml at v0.33.15, the floor of the range above, so the extra owns it across every version this project accepts. Nothing in this repository imports transformers, so a second declaration here was a pin held on a transitive's behalf and one that could drift out of step with it. This is the largest compatibility change in the release: anything downstream pinned to transformers 4.x will conflict.

v0.1.29 - 2026-08-10

Changed

• Build the image on openfilter-base (weekly apt-upgraded python-slim) instead of a stale python:X.Y.Z-slim pin, clearing the OS-package CVEs the pin carried.
• Update the openfilter dependency to 1.2.2

v0.1.28 - 2026-08-04

Added

• Distributed OTel Tracing (FILTER-466): Fully generic, context-gated OpenTelemetry tracer spans (model.preprocess, model.inference, model.cuda_sync, and model.postprocess) inside all concrete model classes (DetectionModel, ClassificationModel, OCRModel). Spans seamlessly parent and nest under the incoming ZeroMQ per-frame traceparent, enabling end-to-end distributed trace waterfalls across complex pipelines.
• Temporal Batching and Batched Inference (FILTER-466): Implemented a highly optimized process_batch method in FilterProtegeModel to stack individual frame tensors into a single GPU/device tensor, invoke a single batched forward pass on CUDA, and scatter results back. Yields up to 1.8x throughput gains for batched streams.

Changed

• Update openfilter[all] to >=1.2.1 (from the compatible-release ~=1.1.2, which capped at <1.2.0 and rejected openfilter 1.2.0).
• Replaced the exact opencv-python-headless==4.13.0.92 pin with the bounded range >=4.13.0.92,<6 (floor raised to avoid the 4.13.0.90 packaging bug). The models and the filter import cv2 directly, so the dependency stays declared, but opencv also arrives transitively through openfilter and an exact pin here conflicts the moment that transitive constraint moves.
• Regenerated uv.lock against the updated specifiers. The lock also carried pre-existing drift and now records pytest 9.0.3, matching the dev extra; it had been left at 9.0.2.
• Chicago Street View geolocation dataset pipeline (FILTER-412): Added geolocation scripts and configurations to build datasets for mapillary corpus creation, processing dashcam labels, VPR classification/view-generation, regression manifests, and pipeline evaluation. Also implemented SQRModel for Simultaneous Quantile Regression (loaded dynamically when task_type="sqr_regression").
• Pin the Docker base to python:3.11.12-slim.
• Refresh the docker-compose.yaml / docker-compose-aggregation.yaml openfilter utility image tags to 1.2.1 and pin the filter's own image to the release version.
• Switch dev-tooling pins to >= ranges.
• Build the image from source (COPY . . + pip install .) instead of re-installing the published GAR wheel by version. This makes the image consistent with the rest of the fleet and lets the release PR's dry-run-publish actually validate the new version's build (previously it could only pull an already-published wheel, so a version bump had no pre-merge image validation). The customer-facing wheel is still published independently by publish-python-wheel; protege-runtime/protege resolve from the private GAR index via the short-lived gar_token, everything else from PyPI. Also exclude .git/tests/ from the build context.

v0.1.27 - 2026-04-24

Fixed

• Restore # Changelog as the top-level RELEASE.md header (previous release accidentally prepended a stray # v0.1.26 H1).

v0.1.26 - 2026-04-23

Fixed

• Restore GAR token in filter.mk build-image for protege-runtime GAR-only dependency

v0.1.25 - 2026-04-23

Changed

• Bump openfilter SDK to >=0.1.30
• Add source-paths release gate to CI workflow

v0.1.24 - 2026-04-21

Changed

• Bump protege-runtime floor from ==0.8.5 to ~=0.20.0 (compatible-release, caps at <0.21.0). The large numerical jump reflects two things: (a) the protege/protege-runtime/protege-pipelines triplet was reunified from separate repos into a workspace and aligned to 0.19.0 for lockstep versioning, then (b) bumped to 0.20.0 for the layering inversion (runtime no longer depends on training code). Only two real release cycles of behavior change, not twelve.
• Update AlignCollate import from protege.ocr to protege.model_runtime.ocr to match its post-inversion canonical location in the standalone runtime wheel.

Removed

• Breaking: Dropped support for Python 3.10 and 3.12. protege-runtime 0.20.0 requires >=3.11, <3.12, so filter-protege-model now does too. Downstream consumers on 3.10 or 3.12 must either pin an older filter-protege-model or upgrade to 3.11.

v0.1.23 - 2026-04-20

Changed

• Simplify filter.mk build-image (plain docker build, DOCKER_TAG)

v0.1.22 - 2026-04-15

Changed

• Add create-release.yaml workflow for GAR premium publishing (push + PR + workflow_dispatch)
• Remove old ci.yaml (shared premium workflow replaces it, removes JFROG secrets)
• Switch to shared security-scan workflow with gcloud_auth
• Enable gcloud_auth_build for Docker build GAR access

v0.1.21 - 2026-04-04

Fixed

• Restore VERSION and VERSION_SHA metadata files in Docker image for openfilter's FilterContext (OpenLineage events, metrics). Lost when migrating from filter_base to python:3.11-slim in v0.1.15.

v0.1.20 - 2026-04-04

Fixed

• Bump opencv-python-headless from 4.13.0.90 to 4.13.0.92 to fix ImportError: libxcb.so.1 in slim containers (packaging bug in 4.13.0.90)
• Bump openfilter minimum from 0.1.26 to 0.1.27
• Update docker-compose openfilter container images to 0.1.27

v0.1.19 - 2026-04-02

Changed

• Rename filter_runtime to openfilter CLI in Makefile and filter.mk
• Update protege-runtime dependency from 0.8.3 to 0.8.5 (opencv-python-headless + onnxsim pin)

v0.1.18 - 2026-04-02

Fixed

• Switch opencv-python to opencv-python-headless to fix ImportError: libxcb.so.1 in headless GKE containers

v0.1.17 - 2026-04-02

Changed

• Update openfilter runtime to 0.1.26 (adds OPENFILTER_APPEND_LD_LIBRARY_PATH and OPENFILTER_APPEND_PATH env vars for GKE GPU driver path injection, CUDA/GPU validation at startup, standardized FILTER_* env var support for core I/O filters)
• Update docker-compose openfilter container images to 0.1.26

v0.1.16 - 2026-04-01

Added

• Enhanced documentation with comprehensive example scripts section in README
• Merged documentation files (index.md into overview.md)

v0.1.15 - 2026-04-01

Changed

• Migrate Docker image from legacy oci to premium-filters GAR registry (PLAT-715)
• Migrate Dockerfile from legacy filter_base image to standard python:3.11-slim build (PLAT-796)
• Remove unused MODEL_IMAGE infrastructure (Dockerfile.model, build/publish targets)

v0.1.14 - 2026-03-09

Fixed

• Pin onnxsim<0.5 to use pre-built wheels (avoids cmake requirement)

v0.1.13 - 2026-03-09

Fixed

• Update openfilter dependency to 0.1.21 (Monitoring updates)

Changed

• Relax openfilter version constraint from exact pin to ~=0.1.0 for cascade rebuild compatibility

v0.1.12 - 2026-01-28

Fixed

• Update openfilter dependency to 0.1.20 (fixes UnboundLocalError in filter error handling)

v0.1.11 - 2026-01-21

Fixed

• Updated dependencies to latest versions
• CVE: update opencv-python-headless to 4.13.0 (fixes ffmpeg security vulnerability) via OpenFilter 0.1.18

v0.1.10 - 2026-01-16

Fixed

• Fixed release notes quoting issue that broke gh release create command by replacing double quotes with single quotes in changelog text

Planned

• Support for additional model types (segmentation)
• Enhanced visualization options
• Performance optimizations
• Additional configuration options
• Add security scan workflow

v0.1.9 - 2026-01-16

Fixed

• Fixed CUDA illegal memory access error by adding proper synchronization after inference
• Added CUDA synchronization in DetectionModel and ClassificationModel to prevent accessing GPU tensors before operations complete
• Improved bounding box validation with tolerance for floating-point precision issues
• Enhanced error handling for CUDA operations with proper cache clearing
• Added safe tensor-to-CPU conversion before accessing values to prevent memory access errors
• Optimized CUDA synchronization to occur once per frame instead of multiple times per detection

v0.1.8 - 2025-10-24

Fixed

• Updated protege-runtime dependency to latest version

v0.1.7 - 2025-10-21

Added

• Added support for object detection and bounding box visualization

v0.1.6 - 2025-10-17

Added

• Added support for multilabel classification in the filter model.

Changed

• Refactored core module structure to better support aggregation and multilabel flows
• Extracted aggregation pipeline into filter_protege_model/aggregation.py
• Consolidated shared helpers into filter_protege_model/utils.py
• Simplified filter_protege_model/filter.py by modularizing model handling and reducing duplication

v0.1.5 - 2025-10-13

Fix

• Adjusted classification label size to be proportionally scaled to frame dimensions in a more subtle and controlled way

v0.1.4 - 2025-10-08

Added

• Model data aggregation functionality with demo script
• Docker compose configuration for aggregation services
• Enhanced filter capabilities for combined model processing

v0.1.3 - 2025-10-07

Added

• Added visualization_source_topic to select the image source for main visualization frames (e.g., main, viz_chit, viz_bowl).

v0.1.2 - 2025-10-06

Fixed

• Fixed CUDA multiprocessing error by setting spawn method in filter.py
• Fixed device mismatch error by ensuring input tensors are moved to correct device
• Fixed image brightness/contrast issues in visualization by preserving original image colors

v0.1.1 - 2025-08-11

Added

• ClassificationModel concrete implementation for image classification tasks
• DetectionModel concrete implementation for object detection tasks
• Enhanced model detection with support for multiple model types
• Improved error handling and validation for model loading
• Additional configuration options for model-specific parameters
• Support for model-specific preprocessing and postprocessing
• Enhanced logging with model-specific information
• Better performance monitoring for different model types

Added (Dataset Generation)

• OCR Image Saving: Automatic image saving with OCR prediction filenames
• Dataset Generation Script: generate_labels.py for creating training datasets
• Environment Variables: FILTER_OCR_SAVE_IMGS and FILTER_OCR_SAVE_DIR support
• Smart File Management: Automatic directory creation and collision prevention
• Dataset Workflow: Complete pipeline from OCR processing to training dataset creation

Technical Improvements (Dataset Tools)

• Intelligent Naming: Uses OCR predictions as filenames for easy dataset organization
• Sanitization: Handles special characters and enforces filename length limits
• Timestamped Organization: Creates organized folder structure for each processing run
• JSON Label Generation: Standardized format for training dataset labels

Technical Details

• Enhanced BaseModel architecture with model-specific implementations
• Improved model loading and validation mechanisms
• Better integration with Protege Runtime
• Enhanced configuration management for different model types
• Comprehensive testing framework for all model types

v0.1.0 - 2025-08-07

Added

• Initial Release: new Protege Model filter
• BaseModel abstract class for extensible model architecture
• OCRModel concrete implementation for text recognition
• Optional visualization with separate ZMQ topics
• Auto-detection of model task type and architecture
• Performance monitoring and statistics
• Comprehensive error handling and validation
• Environment variable configuration support
• Real-time video processing capabilities
• Web interface integration via Webvis filter

Features

• Multi-task Support: Framework for OCR, detection, classification tasks
• Real-time Processing: Processes video streams in real-time
• Configurable Models: Supports custom model artifacts
• Optional Visualization: Configurable visualization with separate output topics
• BaseModel Architecture: Abstract class for consistent model interfaces
• Performance Control: Visualization can be disabled for better performance
• Extensible Design: Easy to add new model types by inheriting from BaseModel

Technical Details

• Compatible with Protege Runtime v0.8.1
• OpenFilter pipeline integration
• Support for CPU and CUDA devices
• Configurable confidence thresholds
• OCR preprocessing with customizable dimensions
• Comprehensive logging and error reporting