Initial commit: scene-actor-extraction pipeline

Source (KPN++ pipeline nodes, ArcFace embedders, SCRFD/YuNet detectors,
gallery builder), build scripts, and eval artifacts.

- external/KPN as a git submodule (gitea.tourolle.paris/dtourolle/KPN)
- ONNX models tracked via Git LFS (models/*.onnx)
- generated outputs, TensorRT engines, reference repos, and media ignored

src/config.hpp

@@ -0,0 +1,72 @@
+#pragma once
+#include "ort_provider.hpp"
+#include <string>
+
+inline const std::string kDefaultDetectorModel = std::string(SAE_MODELS_DIR) + "/scrfd_500m_bnkps.onnx";
+inline const std::string kDefaultArcfaceModel  = std::string(SAE_MODELS_DIR) + "/arcface_w600k_r50.onnx";
+
+enum class Verbosity {
+    minimal,   // actor names + merged time windows only
+    standard,  // per-frame detail: bbox, similarity, unknowns logged
+    xray,      // Jellyfin-Xray format: {"second": ["Actor", ...], ...}
+};
+// debug verbosity = compile with -DSAE_DEBUG → scene_analyze_debug binary
+
+struct Config {
+    // ── Input ─────────────────────────────────────────────────────────────────
+    std::string movie_path;
+    std::string gallery_path;    // gallery.json produced by build_gallery
+
+    // ── Output ───────────────────────────────────────────────────────────────
+    std::string output_path;     // annotations.json
+    Verbosity   verbosity{Verbosity::minimal};
+
+    // ── Sampling ─────────────────────────────────────────────────────────────
+    float  sample_fps{1.0f};     // frames to analyse per second of movie
+    float  max_decode_fps{0.f};  // wall-clock cap on source decode rate (0 = uncapped)
+    double start_sec{0.0};       // seek to this timestamp before sampling
+    double end_sec{-1.0};        // stop at this timestamp (-1 = end of file)
+
+    // ── Detection (SCRFD-500MF via cv::dnn::Net) ──────────────────────────────
+    std::string detector_model;
+    std::string detector_engine;       // optional path to pre-built TRT engine; bypasses ORT
+    int         max_faces{10};         // pipeline cap: keep only the N largest faces
+    float       min_face_px{40.f};    // discard detections narrower or shorter than this
+    float       detector_conf{0.5f};
+    float       detector_nms{0.4f};
+
+    // ── Recognition (ArcFace ONNX) ────────────────────────────────────────────
+    std::string arcface_model;
+    std::string arcface_engine;        // optional path to a pre-built TRT engine; bypasses ORT
+    int         embed_batch_size{4};    // max faces per ORT Run() call — bounds per-call latency
+    float       match_prior{0.5f};        // base-rate prior; 0.5 = use calibrated sigmoid directly
+    float       prob_threshold{0.99f};    // posterior P(match | sim, prior) threshold
+    float       match_threshold{0.45f};   // cosine distance hard ceiling fallback (no calibration)
+    float       match_ratio{0.80f};       // ratio test fallback: accept if best/second < ratio
+    float       match_ratio_ceil{0.65f};  // ratio test only fires below this absolute distance
+
+    // ── Cut detection ────────────────────────────────────────────────────────
+    float cut_threshold{0.70f};         // grayscale histogram correlation below this → hard cut
+
+    // ── Face tracking (frame-to-frame) ───────────────────────────────────────
+    float track_alpha{0.4f};            // cost weight: 0=embedding only, 1=spatial only
+    float track_min_iou{0.1f};          // IoU below which spatial link alone is rejected
+    float track_max_embed_dist{0.7f};   // cosine dist above which embedding link alone is rejected
+    int   track_max_frames_missing{5};  // expire track after N consecutive missed frames
+    int   track_min_frames{3};          // frames before track mean replaces per-frame embedding
+
+    // ── Scene tracking ────────────────────────────────────────────────────────
+    double extinction_sec{5.0};   // keep actor active this many seconds after last detection
+    double anneal_sec{2.0};       // merge actor windows separated by less than this into one epoch
+
+    // ── TensorRT ──────────────────────────────────────────────────────────────
+    // Only active when OrtProvider::TensorRT is detected.
+    // INT8 is unsafe for ArcFace without a calibration table.
+    TrtConfig trt{};   // fp16=true, int8=false, cache_dir="./trt_cache"
+
+    // ── Debug output (only used when SAE_DEBUG is defined) ───────────────────
+#ifdef SAE_DEBUG
+    std::string debug_dir{"debug_frames"};
+    float       crop_context{1.5f};   // bbox expansion factor for context crop
+#endif
+};