Al-Haytham Filter

The Al-Haytham Filter is a verification and benchmarking tool designed to validate output predictions from upstream filters or systems. It performs frame-by-frame comparisons against a golden dataset and reports accuracy metrics for downstream evaluation.

Features

• Prediction Verification
  Compares per-frame outputs with a ground truth JSON file and computes:

  • ROI-level matching using Intersection-over-Union (IoU)
  • Classification-level accuracy

• Golden File Generation
  Automatically switches to "golden file creation mode" if no ground truth is found, saving current predictions as the benchmark.

• Offline Mode
  Uses saved prediction data from disk (prediction_json_path) to simulate filter input during testing.

• Threshold Configuration
  Tune matching logic via:

  • iou_threshold: controls spatial ROI overlap requirement
  • acc_threshold: controls classification match tolerance

• Debug and Visualization

  • Enable frame annotations via draw_visualization: true
  • Verbose logging with debug: true to track comparison logic

• Output Reports
  Writes results to:

  • ./output/per_frame_results.json
  • ./output/per_roi_results.json

Example Output

A per_frame_results.json report may contain:

[
  {
    "frame_id": 1,
    "matched_rois": 3,
    "accuracy": 0.85,
    "iou_scores": [0.66, 0.79, 0.91]
  }
]

When to Use

Use this filter when:

• You are evaluating the correctness of a visual inference pipeline
• You need to measure the alignment between predicted and expected results
• You want to automatically generate and reuse benchmark data

Configuration Reference

Key	Type	Default	Description
offline_mode	boolean	false	Use disk-saved input data instead of upstream frames
create_golden_file	boolean	false	If true, current data will be saved as golden file
gt_json_path	string	"/app/golden_files/golden_file.json"	Path to the ground truth JSON
prediction_json_path	string	"/app/prediction_files/prediction_file.json"	Path to the predicted data JSON
iou_threshold	float	0.05	Minimum IoU for two ROIs to be considered a match
acc_threshold	float	0.05	Minimum acceptable classification accuracy
draw_visualization	boolean	false	Enable visual rendering of results
debug	boolean	false	Enable detailed logging

Note

If no ground truth file is provided, this filter will automatically enter golden file creation mode.