pub struct IndexSession { /* private fields */ }Expand description
Host-facing session: multi-source tracker + identity gallery + VisionIndex.
Implementations§
Source§impl IndexSession
impl IndexSession
Sourcepub fn new(
name: impl Into<String>,
track_config: ByteTrackConfig,
) -> Result<Self, SessionError>
pub fn new( name: impl Into<String>, track_config: ByteTrackConfig, ) -> Result<Self, SessionError>
Creates a session with a validated tracker config and empty index/gallery.
§Errors
Returns tracker configuration errors.
Sourcepub fn set_track_ann_kind(&mut self, kind: Option<AnnKind>)
pub fn set_track_ann_kind(&mut self, kind: Option<AnnKind>)
Configures track-embedding ANN (None disables; exact scan each query).
Prefer AnnKind::hnsw_default for large track galleries; LSH for
lightweight approx; brute force for tiny sets / correctness checks.
Sourcepub fn calibrate_identity_thresholds(
&self,
pairs: &[(EmbeddingRef, EmbeddingRef, bool)],
n_thresholds: usize,
) -> Result<CalibrationReport, SessionError>
pub fn calibrate_identity_thresholds( &self, pairs: &[(EmbeddingRef, EmbeddingRef, bool)], n_thresholds: usize, ) -> Result<CalibrationReport, SessionError>
Calibrates re-id accept/reject thresholds from labeled embedding pairs.
Each triple is (embedding_a, embedding_b, genuine). Returns the ROC/EER
report without mutating config — call Self::apply_identity_calibration
to install recommended thresholds.
§Errors
Propagates store / calibration errors.
Sourcepub fn apply_identity_calibration(
&mut self,
report: &CalibrationReport,
) -> Result<(), SessionError>
pub fn apply_identity_calibration( &mut self, report: &CalibrationReport, ) -> Result<(), SessionError>
Applies a calibration report to the gallery resolve config.
§Errors
Propagates config validation errors.
Sourcepub const fn track_ann_kind(&self) -> Option<AnnKind>
pub const fn track_ann_kind(&self) -> Option<AnnKind>
Current track ANN kind.
Sourcepub fn set_retention_policy(&mut self, policy: RetentionPolicy)
pub fn set_retention_policy(&mut self, policy: RetentionPolicy)
Sets retention / privacy policy (applied via Self::apply_retention).
Sourcepub fn retention_policy(&self) -> &RetentionPolicy
pub fn retention_policy(&self) -> &RetentionPolicy
Current retention policy.
Sourcepub fn retention_policy_mut(&mut self) -> &mut RetentionPolicy
pub fn retention_policy_mut(&mut self) -> &mut RetentionPolicy
Mutable retention policy (legal holds / TTLs).
Sourcepub fn apply_retention(&mut self) -> RetentionReport
pub fn apply_retention(&mut self) -> RetentionReport
Applies retention limits with legal holds and per-source TTLs.
Sourcepub fn forget_subject(&mut self, subject_id: SubjectId) -> RetentionReport
pub fn forget_subject(&mut self, subject_id: SubjectId) -> RetentionReport
Forgets a subject: clears labels from tracks/memory; optional gallery scrub.
Legal-hold subjects are not forgotten (forgotten_subjects = 0).
Sourcepub fn search_photo_with_adapter<A: PhotoEmbeddingAdapter>(
&mut self,
photo: &PhotoView<'_>,
adapter: &mut A,
top_k: usize,
) -> Result<Vec<PhotoSearchHit>, SessionError>
pub fn search_photo_with_adapter<A: PhotoEmbeddingAdapter>( &mut self, photo: &PhotoView<'_>, adapter: &mut A, top_k: usize, ) -> Result<Vec<PhotoSearchHit>, SessionError>
Photo → embedding (host adapter) → multi-factor gallery search.
Completes the killer path without shipping model weights in SightLoom:
host implements crate::PhotoEmbeddingAdapter, then ranking lives here.
§Errors
Adapter or identity search failures.
Sourcepub fn prometheus_metrics(&self) -> String
pub fn prometheus_metrics(&self) -> String
Prometheus text exposition for ingest metrics (no network I/O).
Sourcepub fn otlp_metrics_json(&self) -> String
pub fn otlp_metrics_json(&self) -> String
OTLP-shaped metrics JSON for host collectors / OpenTelemetry bridges.
Sourcepub fn metric_points(&self) -> Vec<MetricPoint>
pub fn metric_points(&self) -> Vec<MetricPoint>
Neutral metric points for a custom crate::MetricsExporter.
Sourcepub fn export_metrics_to<E: MetricsExporter>(
&self,
exporter: &mut E,
) -> Result<(), E::Error>
pub fn export_metrics_to<E: MetricsExporter>( &self, exporter: &mut E, ) -> Result<(), E::Error>
Sourcepub fn detect_anomalies_with<D: AnomalyDetector>(
&mut self,
detector: &mut D,
) -> Result<usize, D::Error>
pub fn detect_anomalies_with<D: AnomalyDetector>( &mut self, detector: &mut D, ) -> Result<usize, D::Error>
Runs a pluggable sightloom_analysis::AnomalyDetector and stores events.
§Errors
Propagates detector errors.
Sourcepub fn set_ingest_policy(&mut self, policy: IngestPolicy)
pub fn set_ingest_policy(&mut self, policy: IngestPolicy)
Overrides ingest policy (late / OOO / queue hints).
Sourcepub fn set_memory_build_config(&mut self, config: MemoryBuildConfig)
pub fn set_memory_build_config(&mut self, config: MemoryBuildConfig)
Configures appearance/visit materialization gaps.
Sourcepub fn set_memory_auto_rebuild(&mut self, config: MemoryAutoRebuild)
pub fn set_memory_auto_rebuild(&mut self, config: MemoryAutoRebuild)
Enables or configures automatic memory rebuild during ingest.
Pass every_n_frames: 0 to disable. When enabled, every accepted frame
counts toward the threshold (multi-source frames share one counter).
Sourcepub const fn memory_auto_rebuild(&self) -> MemoryAutoRebuild
pub const fn memory_auto_rebuild(&self) -> MemoryAutoRebuild
Current auto-rebuild schedule.
Sourcepub const fn frames_since_memory_rebuild(&self) -> u64
pub const fn frames_since_memory_rebuild(&self) -> u64
Accepted frames counted since the last auto memory rebuild.
Sourcepub const fn last_auto_memory_rebuild(&self) -> Option<(usize, usize, usize)>
pub const fn last_auto_memory_rebuild(&self) -> Option<(usize, usize, usize)>
Counts from the last auto rebuild, if any: (appearances, visits, subjects).
Sourcepub fn maybe_auto_rebuild_memory(&mut self) -> Option<(usize, usize, usize)>
pub fn maybe_auto_rebuild_memory(&mut self) -> Option<(usize, usize, usize)>
Runs memory rebuild if the auto schedule threshold is met.
Returns the rebuild counts when a rebuild ran.
Sourcepub fn rebuild_appearances_and_visits(&mut self) -> (usize, usize)
pub fn rebuild_appearances_and_visits(&mut self) -> (usize, usize)
Rebuilds appearances and visits from effective track samples.
Idempotent: replaces existing appearance/visit tables. Returns
(appearance_count, visit_count).
Sourcepub fn rebuild_subject_profiles(&mut self) -> usize
pub fn rebuild_subject_profiles(&mut self) -> usize
Rebuilds index.subjects from appearances (or track samples).
Preserves host-supplied labels and embeddings. When a gallery subject has a reference embedding and the profile has none, copies that handle. Returns the number of subject profiles.
Sourcepub fn rebuild_memory_from_tracks(&mut self) -> (usize, usize, usize)
pub fn rebuild_memory_from_tracks(&mut self) -> (usize, usize, usize)
Rebuilds appearances, visits, then subject profiles in one call.
Returns (appearances, visits, subjects).
Sourcepub fn set_subject_label(
&mut self,
subject_id: SubjectId,
label: impl Into<String>,
)
pub fn set_subject_label( &mut self, subject_id: SubjectId, label: impl Into<String>, )
Sets a host display label on an existing (or empty) subject profile.
Sourcepub fn plan_redaction_subject(
&mut self,
subject_id: SubjectId,
tag: u32,
) -> usize
pub fn plan_redaction_subject( &mut self, subject_id: SubjectId, tag: u32, ) -> usize
Plans blur-subject redaction intervals from appearances of subject_id.
Replaces any existing redaction table. Returns the number of intervals.
Sourcepub fn plan_redaction_blur_others(
&mut self,
keep_subject: SubjectId,
tag: u32,
) -> usize
pub fn plan_redaction_blur_others( &mut self, keep_subject: SubjectId, tag: u32, ) -> usize
Plans blur-everyone-except keep_subject from appearances of others.
Replaces any existing redaction table. Returns the number of intervals.
Sourcepub fn plan_redaction_uncertain(&mut self, tag: u32) -> usize
pub fn plan_redaction_uncertain(&mut self, tag: u32) -> usize
Plans uncertain-hold provenance from re-id uncertain intervals.
Replaces any existing redaction table. Returns the number of intervals.
Sourcepub fn clear_redaction_intervals(&mut self)
pub fn clear_redaction_intervals(&mut self)
Clears the redaction provenance table.
Sourcepub fn export_redaction_intervals_json(&self) -> Result<String, SessionError>
pub fn export_redaction_intervals_json(&self) -> Result<String, SessionError>
JSON export of redaction provenance intervals (demo step 10 / Intelligence handoff).
§Errors
Returns serialization failures.
Sourcepub const fn ingest_metrics(&self) -> IngestMetrics
pub const fn ingest_metrics(&self) -> IngestMetrics
Returns ingest metrics snapshot.
Sourcepub fn apply_source_lifecycle(&mut self, event: &SourceLifecycle)
pub fn apply_source_lifecycle(&mut self, event: &SourceLifecycle)
Applies a source lifecycle event (watermark + optional tracker reset).
Hosts call this when cameras disconnect / reconnect. SightLoom is not a
media broker — it only clears motion / watermark state when asked.
Sourcepub fn uncertain_intervals(&self) -> Vec<IdentityInterval>
pub fn uncertain_intervals(&self) -> Vec<IdentityInterval>
Uncertain identity intervals from the gallery audit trail.
Sourcepub fn seed_subject_from_box(
&mut self,
stamp: FrameStamp,
bbox: Rect,
score: f32,
class_id: Option<ClassId>,
subject_id: Option<SubjectId>,
) -> Result<(TrackedDetection, SubjectId), SessionError>
pub fn seed_subject_from_box( &mut self, stamp: FrameStamp, bbox: Rect, score: f32, class_id: Option<ClassId>, subject_id: Option<SubjectId>, ) -> Result<(TrackedDetection, SubjectId), SessionError>
Seeds a subject onto a host-provided box (click demo): ingest one detection, assign a new or existing subject to the resulting track key.
§Errors
Propagates tracker / ingest errors.
Sourcepub fn seed_click(
&mut self,
stamp: FrameStamp,
bbox: Rect,
score: f32,
subject_id: Option<SubjectId>,
) -> Result<SeedResult, SessionError>
pub fn seed_click( &mut self, stamp: FrameStamp, bbox: Rect, score: f32, subject_id: Option<SubjectId>, ) -> Result<SeedResult, SessionError>
Demo helper: seed click box and return a compact crate::SeedResult.
§Errors
Propagates tracker / ingest errors.
Sourcepub fn assign_subject(&mut self, key: TrackKey, subject_id: SubjectId)
pub fn assign_subject(&mut self, key: TrackKey, subject_id: SubjectId)
Manually assigns a subject to a track key (host-accepted special box / tid).
Sourcepub fn accept_host_track(
&mut self,
source_id: SourceId,
local_track_id: TrackId,
subject_id: Option<SubjectId>,
) -> TrackKey
pub fn accept_host_track( &mut self, source_id: SourceId, local_track_id: TrackId, subject_id: Option<SubjectId>, ) -> TrackKey
Accepts a host-known local track id + optional subject (special frame/tid).
Does not re-run the tracker; only updates identity maps and latest sample.
Sourcepub fn export_track_spans(&self) -> Vec<TrackSpanExport>
pub fn export_track_spans(&self) -> Vec<TrackSpanExport>
Exports effective track/mask spans for host MaskTimeline construction.
Sourcepub fn export_mot_challenge(&self, source_id: Option<SourceId>) -> String
pub fn export_mot_challenge(&self, source_id: Option<SourceId>) -> String
Exports effective tracks as MOTChallenge text for host TrackEval.
When source_id is Some, only that camera is included. Frame index is
TrackSample.frame_index + 1 (1-based). Track id prefers track_uid
when set, else local track id.
Sourcepub fn export_track_spans_json(&self) -> Result<String, SessionError>
pub fn export_track_spans_json(&self) -> Result<String, SessionError>
JSON export of effective track spans (host-friendly, no pixels).
§Errors
Returns serialization failures.
Sourcepub fn export_uncertain_intervals_json(&self) -> Result<String, SessionError>
pub fn export_uncertain_intervals_json(&self) -> Result<String, SessionError>
JSON export of uncertain identity intervals for demo step 5.
§Errors
Returns serialization failures.
Sourcepub fn set_anomaly_config(&mut self, config: StatAnomalyConfig)
pub fn set_anomaly_config(&mut self, config: StatAnomalyConfig)
Sets statistical anomaly detection thresholds.
Sourcepub fn freeze_anomaly_baseline(&mut self)
pub fn freeze_anomaly_baseline(&mut self)
Freezes the current index as the anomaly baseline (history window).
Sourcepub fn freeze_scoped_anomaly_baselines(&self) -> ScopedBaselineStore
pub fn freeze_scoped_anomaly_baselines(&self) -> ScopedBaselineStore
Freezes scoped (subject + camera) baselines from the live index.
Used with Self::detect_and_store_anomalies_scoped.
Sourcepub fn calibrate_anomaly_far(
&self,
target_far: f32,
) -> Option<FarCalibrationReport>
pub fn calibrate_anomaly_far( &self, target_far: f32, ) -> Option<FarCalibrationReport>
Calibrates statistical z-threshold to a target false-alarm rate on the current index series (treated as a normal history window).
Returns None when history is too thin.
Sourcepub fn apply_anomaly_far(&mut self, report: &FarCalibrationReport)
pub fn apply_anomaly_far(&mut self, report: &FarCalibrationReport)
Applies a FAR calibration report to the session anomaly config.
Sourcepub fn detect_and_store_anomalies_scoped(
&mut self,
store: &ScopedBaselineStore,
) -> usize
pub fn detect_and_store_anomalies_scoped( &mut self, store: &ScopedBaselineStore, ) -> usize
Runs statistical detection with subject/camera scoped baselines.
§Returns
Number of new anomaly events stored.
Sourcepub fn mine_and_store_patterns(&mut self) -> usize
pub fn mine_and_store_patterns(&mut self) -> usize
Mines patterns from the live index and appends them to index.patterns.
Returns the number of new patterns.
Sourcepub fn detect_and_store_anomalies(&mut self) -> usize
pub fn detect_and_store_anomalies(&mut self) -> usize
Runs statistical anomaly detection and appends to index.anomalies.
Uses a frozen baseline when present; otherwise builds baseline from the same live series (useful only with enough history).
Returns the number of new anomalies.
Sourcepub fn detect_and_store_graph_anomalies(
&mut self,
config: GraphAnomalyConfig,
history: Option<&AnalysisSeries>,
strict_unknown: bool,
) -> usize
pub fn detect_and_store_graph_anomalies( &mut self, config: GraphAnomalyConfig, history: Option<&AnalysisSeries>, strict_unknown: bool, ) -> usize
Runs graph / multi-camera relational anomalies and stores events.
Uses the session camera topology (strict_unknown hops impossible when
no edge) plus a relational baseline fitted from history series when
provided, otherwise from the live index.
Returns the number of new anomalies.
Sourcepub fn analysis_series(&self) -> AnalysisSeries
pub fn analysis_series(&self) -> AnalysisSeries
Builds an analysis series view of the current index (read-only helper).
Sourcepub fn query_subjects(&self, query: &SubjectQuery) -> Vec<SubjectHit>
pub fn query_subjects(&self, query: &SubjectQuery) -> Vec<SubjectHit>
Runs a subject query against the live index.
Sourcepub fn build_subject_reel(
&self,
subject_id: SubjectId,
max_gap_ns: i64,
) -> EvidenceReel
pub fn build_subject_reel( &self, subject_id: SubjectId, max_gap_ns: i64, ) -> EvidenceReel
Builds a coalesced evidence reel for a subject (handles only, no pixels).
Sourcepub fn build_subject_reel_samples(&self, subject_id: SubjectId) -> EvidenceReel
pub fn build_subject_reel_samples(&self, subject_id: SubjectId) -> EvidenceReel
Builds one sample-per-segment reel for a subject.
Sourcepub fn store_subject_reel(
&mut self,
subject_id: SubjectId,
max_gap_ns: i64,
tag: u32,
) -> EvidenceReel
pub fn store_subject_reel( &mut self, subject_id: SubjectId, max_gap_ns: i64, tag: u32, ) -> EvidenceReel
Builds a coalesced reel and stores it on the index (package-persisted).
Sourcepub fn evidence_reels(&self) -> &[EvidenceReel]
pub fn evidence_reels(&self) -> &[EvidenceReel]
Stored evidence reels (package / snapshot).
Sourcepub fn clear_evidence_reels(&mut self)
pub fn clear_evidence_reels(&mut self)
Clears stored evidence reels.
Sourcepub fn revise_latest_track_sample(
&mut self,
key: TrackKey,
bbox: Rect,
confidence: f32,
mask_ref: Option<u64>,
) -> Option<u64>
pub fn revise_latest_track_sample( &mut self, key: TrackKey, bbox: Rect, confidence: f32, mask_ref: Option<u64>, ) -> Option<u64>
Appends a revision that supersedes the latest effective sample for key.
Returns the new sample id when a prior sample existed.
Sourcepub fn rank_subjects(&self) -> Vec<SubjectRank>
pub fn rank_subjects(&self) -> Vec<SubjectRank>
Ranks subjects by track-sample frequency (most frequent first).
Sourcepub fn most_frequent_subject_reel(
&self,
max_gap_ns: i64,
) -> Option<(SubjectRank, EvidenceReel)>
pub fn most_frequent_subject_reel( &self, max_gap_ns: i64, ) -> Option<(SubjectRank, EvidenceReel)>
Most frequent subject + coalesced evidence reel (handles only).
Sourcepub fn enroll_subject_photos(
&mut self,
modality: SubjectModality,
photos: &[Vec<f32>],
) -> Result<SubjectId, SessionError>
pub fn enroll_subject_photos( &mut self, modality: SubjectModality, photos: &[Vec<f32>], ) -> Result<SubjectId, SessionError>
Registers a subject and attaches one or more reference photo embeddings.
Hosts compute embeddings externally (detector / face model). SightLoom
only stores vectors and ranks them.
§Errors
Propagates embedding validation errors.
Sourcepub fn add_subject_photo(
&mut self,
subject_id: SubjectId,
vector: impl Into<Vec<f32>>,
) -> Result<EmbeddingRef, SessionError>
pub fn add_subject_photo( &mut self, subject_id: SubjectId, vector: impl Into<Vec<f32>>, ) -> Result<EmbeddingRef, SessionError>
Sourcepub fn search_by_photo(
&mut self,
vector: impl Into<Vec<f32>>,
modality: SubjectModality,
top_k: usize,
) -> Result<Vec<PhotoSearchHit>, SessionError>
pub fn search_by_photo( &mut self, vector: impl Into<Vec<f32>>, modality: SubjectModality, top_k: usize, ) -> Result<Vec<PhotoSearchHit>, SessionError>
Searches enrolled subjects by a query photo embedding (top-k).
§Errors
Propagates embedding / resolve errors.
Sourcepub fn search_photo_with_reels(
&mut self,
vector: impl Into<Vec<f32>>,
modality: SubjectModality,
top_k: usize,
max_gap_ns: i64,
) -> Result<Vec<PhotoSearchResult>, SessionError>
pub fn search_photo_with_reels( &mut self, vector: impl Into<Vec<f32>>, modality: SubjectModality, top_k: usize, max_gap_ns: i64, ) -> Result<Vec<PhotoSearchResult>, SessionError>
Sourcepub fn add_source(&mut self, entry: SourceEntry)
pub fn add_source(&mut self, entry: SourceEntry)
Registers a media source on the index header.
Sourcepub fn set_auto_assign_subjects(&mut self, enabled: bool)
pub fn set_auto_assign_subjects(&mut self, enabled: bool)
Enables or disables automatic subject assignment on Accept matches.
Sourcepub fn set_default_modality(&mut self, modality: SubjectModality)
pub fn set_default_modality(&mut self, modality: SubjectModality)
Sets the default re-id modality used when callers omit one.
Sourcepub fn set_embedding_model_id(&mut self, model_id: impl Into<String>)
pub fn set_embedding_model_id(&mut self, model_id: impl Into<String>)
Records an embedding model identity/version for session checkpoints.
Sourcepub fn set_resolve_config(
&mut self,
config: ResolveConfig,
) -> Result<(), SessionError>
pub fn set_resolve_config( &mut self, config: ResolveConfig, ) -> Result<(), SessionError>
Sourcepub fn index(&self) -> &VisionIndex
pub fn index(&self) -> &VisionIndex
Returns a shared reference to the live index.
Sourcepub fn index_mut(&mut self) -> &mut VisionIndex
pub fn index_mut(&mut self) -> &mut VisionIndex
Mutable access for advanced entity writers (appearances, subjects, …).
Sourcepub fn gallery(&self) -> &SubjectGallery
pub fn gallery(&self) -> &SubjectGallery
Returns the identity gallery.
Sourcepub fn gallery_mut(&mut self) -> &mut SubjectGallery
pub fn gallery_mut(&mut self) -> &mut SubjectGallery
Mutable access to the identity gallery.
Sourcepub fn tracker(&self) -> &MultiSourceTracker
pub fn tracker(&self) -> &MultiSourceTracker
Multi-source tracker pool.
Sourcepub fn register_subject(&mut self, modality: SubjectModality) -> SubjectId
pub fn register_subject(&mut self, modality: SubjectModality) -> SubjectId
Registers a new subject identity in the gallery.
Sourcepub fn add_subject_reference(
&mut self,
subject_id: SubjectId,
sample: ReferenceSample,
) -> Result<(), SessionError>
pub fn add_subject_reference( &mut self, subject_id: SubjectId, sample: ReferenceSample, ) -> Result<(), SessionError>
Adds a positive/negative/unlabeled reference sample to a subject.
§Errors
Propagates gallery errors when the subject is unknown.
Sourcepub fn note_track_embedding(
&mut self,
key: TrackKey,
vector: impl Into<Vec<f32>>,
at: MediaTime,
) -> Result<EmbeddingRef, SessionError>
pub fn note_track_embedding( &mut self, key: TrackKey, vector: impl Into<Vec<f32>>, at: MediaTime, ) -> Result<EmbeddingRef, SessionError>
Inserts an embedding vector and records it for a composite track key.
§Errors
Propagates embedding store validation errors.
Sourcepub fn note_track_embedding_for(
&mut self,
source_id: SourceId,
track_id: TrackId,
vector: impl Into<Vec<f32>>,
at: MediaTime,
) -> Result<EmbeddingRef, SessionError>
pub fn note_track_embedding_for( &mut self, source_id: SourceId, track_id: TrackId, vector: impl Into<Vec<f32>>, at: MediaTime, ) -> Result<EmbeddingRef, SessionError>
Convenience: note embedding for (source_id, track_id).
§Errors
Propagates embedding store validation errors.
Sourcepub fn note_track_embeddings_batch(
&mut self,
items: &[(TrackKey, Vec<f32>, MediaTime)],
) -> Result<usize, SessionError>
pub fn note_track_embeddings_batch( &mut self, items: &[(TrackKey, Vec<f32>, MediaTime)], ) -> Result<usize, SessionError>
Notes many track embeddings in one call (batch continuous embedding path).
§Errors
First store validation error.
Sourcepub fn detect_ingest_and_embed_tracks<D, E>(
&mut self,
stamp: FrameStamp,
frame: &FrameView<'_>,
detector: &mut D,
embedder: &mut E,
) -> Result<Vec<TrackedDetection>, SessionError>
pub fn detect_ingest_and_embed_tracks<D, E>( &mut self, stamp: FrameStamp, frame: &FrameView<'_>, detector: &mut D, embedder: &mut E, ) -> Result<Vec<TrackedDetection>, SessionError>
Detect → track → host embed every track box → store embeddings.
Continuous per-frame track embedding path: host owns the embed model.
§Errors
Detector / tracker / embedder failures.
Sourcepub fn set_source_accept_threshold(
&mut self,
source_id: SourceId,
threshold: f32,
)
pub fn set_source_accept_threshold( &mut self, source_id: SourceId, threshold: f32, )
Sets per-camera accept threshold override.
Sourcepub fn clear_source_accept_threshold(&mut self, source_id: SourceId) -> bool
pub fn clear_source_accept_threshold(&mut self, source_id: SourceId) -> bool
Clears per-camera accept override.
Sourcepub fn set_camera_topology(&mut self, topology: CameraTopology)
pub fn set_camera_topology(&mut self, topology: CameraTopology)
Sets camera topology for cross-source identity hard gates.
Sourcepub fn camera_topology(&self) -> &CameraTopology
pub fn camera_topology(&self) -> &CameraTopology
Active camera topology.
Sourcepub fn subject_for_track_key(&self, key: TrackKey) -> Option<SubjectId>
pub fn subject_for_track_key(&self, key: TrackKey) -> Option<SubjectId>
Returns the subject currently assigned to a composite track key, if any.
Sourcepub fn subject_for_track(
&self,
source_id: SourceId,
track_id: TrackId,
) -> Option<SubjectId>
pub fn subject_for_track( &self, source_id: SourceId, track_id: TrackId, ) -> Option<SubjectId>
Returns the subject for (source_id, local track_id).
Sourcepub fn track_uid(&self, key: TrackKey) -> Option<TrackUid>
pub fn track_uid(&self, key: TrackKey) -> Option<TrackUid>
Looks up the global TrackUid for a composite key.
Sourcepub fn ingest_detections(
&mut self,
stamp: FrameStamp,
detections: &[Detection],
) -> Result<Vec<TrackedDetection>, SessionError>
pub fn ingest_detections( &mut self, stamp: FrameStamp, detections: &[Detection], ) -> Result<Vec<TrackedDetection>, SessionError>
Sourcepub fn ingest_detections_keyed(
&mut self,
stamp: FrameStamp,
detections: &[Detection],
idempotency_key: u64,
) -> Result<Vec<TrackedDetection>, SessionError>
pub fn ingest_detections_keyed( &mut self, stamp: FrameStamp, detections: &[Detection], idempotency_key: u64, ) -> Result<Vec<TrackedDetection>, SessionError>
Like Self::ingest_detections, but records a host idempotency key.
When idempotency_key != 0 and that key already exists on a track sample
or observation, returns SessionError::DuplicateIdempotencyKey without
mutating tracker state.
§Errors
Propagates tracker / policy / duplicate-key errors.
Sourcepub fn detect_and_ingest<D: DetectorAdapter>(
&mut self,
stamp: FrameStamp,
frame: &FrameView<'_>,
detector: &mut D,
) -> Result<Vec<TrackedDetection>, SessionError>
pub fn detect_and_ingest<D: DetectorAdapter>( &mut self, stamp: FrameStamp, frame: &FrameView<'_>, detector: &mut D, ) -> Result<Vec<TrackedDetection>, SessionError>
Runs a host crate::DetectorAdapter then ingests detections.
§Errors
Returns detector or ingest errors.
Sourcepub fn push_observation(&mut self, observation: Observation)
pub fn push_observation(&mut self, observation: Observation)
Pushes a rich observation onto the index (optional parallel host path).
Sourcepub fn revise_observation(
&mut self,
prior_id: u64,
observation: Observation,
) -> bool
pub fn revise_observation( &mut self, prior_id: u64, observation: Observation, ) -> bool
Revises an observation by id (supersedes prior row).
Returns false when prior_id is unknown.
Sourcepub fn effective_observations(&self) -> Vec<Observation>
pub fn effective_observations(&self) -> Vec<Observation>
Effective observations (not superseded).
Sourcepub fn query_spatial(&self, query: &SpatialQuery) -> Vec<SpatialHit>
pub fn query_spatial(&self, query: &SpatialQuery) -> Vec<SpatialHit>
Spatial query over effective track samples.
Sourcepub fn query_ast(&self, root: &QueryNode) -> Vec<SubjectHit>
pub fn query_ast(&self, root: &QueryNode) -> Vec<SubjectHit>
Boolean query AST over subjects (And / Or / Not / predicates).
Sourcepub fn stream_subjects(
&self,
filter: SubjectQuery,
page_size: usize,
) -> StreamingSubjectQuery
pub fn stream_subjects( &self, filter: SubjectQuery, page_size: usize, ) -> StreamingSubjectQuery
Starts a streaming subject query (page_size for
sightloom_index::StreamingSubjectQuery::next_page).
Sourcepub fn stream_next_page(
&self,
stream: &mut StreamingSubjectQuery,
) -> Vec<SubjectHit>
pub fn stream_next_page( &self, stream: &mut StreamingSubjectQuery, ) -> Vec<SubjectHit>
Advances a streaming query one page against the live index.
Sourcepub fn stream_poll_new(
&self,
stream: &mut StreamingSubjectQuery,
force: bool,
) -> Vec<SubjectHit>
pub fn stream_poll_new( &self, stream: &mut StreamingSubjectQuery, force: bool, ) -> Vec<SubjectHit>
Polls a streaming query for newly matching subjects since last advance.
Sourcepub fn parse_nl_query(text: &str) -> Result<NlParseResult, NlParseError>
pub fn parse_nl_query(text: &str) -> Result<NlParseResult, NlParseError>
Parses restricted English into a query AST (deterministic, no LLM).
§Errors
Returns parse errors when the phrase is empty or unrecognized.
Sourcepub fn query_nl(
&self,
text: &str,
) -> Result<(NlParseResult, Vec<SubjectHit>), NlParseError>
pub fn query_nl( &self, text: &str, ) -> Result<(NlParseResult, Vec<SubjectHit>), NlParseError>
Sourcepub fn latest_identity_audit(
&self,
key: TrackKey,
) -> Option<&IdentityAuditEvent>
pub fn latest_identity_audit( &self, key: TrackKey, ) -> Option<&IdentityAuditEvent>
Latest identity audit event for a track key, if any.
Sourcepub fn identity_hypotheses(&self, key: TrackKey) -> Vec<IdentityMatch>
pub fn identity_hypotheses(&self, key: TrackKey) -> Vec<IdentityMatch>
Ranked identity hypotheses from the latest audit row for key.
Sourcepub fn ingest_detection_batch(
&mut self,
frames: &[(FrameStamp, Vec<Detection>)],
) -> Result<Vec<Vec<TrackedDetection>>, SessionError>
pub fn ingest_detection_batch( &mut self, frames: &[(FrameStamp, Vec<Detection>)], ) -> Result<Vec<Vec<TrackedDetection>>, SessionError>
Ingests multiple frames in order (strict: first error aborts the batch).
§Errors
Propagates the first ingest/tracker error.
Sourcepub fn ingest_detection_batch_soft(
&mut self,
frames: &[(FrameStamp, Vec<Detection>)],
) -> Result<Vec<Vec<TrackedDetection>>, SessionError>
pub fn ingest_detection_batch_soft( &mut self, frames: &[(FrameStamp, Vec<Detection>)], ) -> Result<Vec<Vec<TrackedDetection>>, SessionError>
Soft multi-frame ingest: late / OOO / drop policy rejections are skipped (already counted in metrics); hard tracker errors still abort.
Returns one entry per accepted frame only.
§Errors
Returns tracker failures (non-policy).
Sourcepub fn drain_frame_queue(
&mut self,
queue: &mut FrameQueue,
max_frames: Option<usize>,
) -> Result<Vec<Vec<TrackedDetection>>, SessionError>
pub fn drain_frame_queue( &mut self, queue: &mut FrameQueue, max_frames: Option<usize>, ) -> Result<Vec<Vec<TrackedDetection>>, SessionError>
Pops and ingests up to max_frames from a host crate::ingest::FrameQueue.
Soft on policy rejects; updates metrics.queue_hwm from the queue HWM.
§Errors
Returns hard tracker errors.
Sourcepub fn resolve_track_identity(
&mut self,
key: TrackKey,
modality: Option<SubjectModality>,
at: MediaTime,
) -> Result<(TrackFragment, Vec<IdentityMatch>), SessionError>
pub fn resolve_track_identity( &mut self, key: TrackKey, modality: Option<SubjectModality>, at: MediaTime, ) -> Result<(TrackFragment, Vec<IdentityMatch>), SessionError>
Aggregates pending embeddings for a track key, resolves identity, and patches the latest track sample when a subject is assigned.
§Errors
Returns identity errors when no pending embeddings exist or pooling fails.
Sourcepub fn search_tracks_by_embedding(
&mut self,
vector: impl Into<Vec<f32>>,
top_k: usize,
) -> Result<Vec<TrackEmbeddingHit>, SessionError>
pub fn search_tracks_by_embedding( &mut self, vector: impl Into<Vec<f32>>, top_k: usize, ) -> Result<Vec<TrackEmbeddingHit>, SessionError>
Searches track embeddings (not only enrolled subjects) by cosine similarity.
Hosts call Self::note_track_embedding while ingesting video so tracks
become searchable before / without gallery enrollment.
§Errors
Propagates embedding store errors.
Sourcepub fn resolve_pending_identities(
&mut self,
at: MediaTime,
modality: Option<SubjectModality>,
) -> Result<usize, SessionError>
pub fn resolve_pending_identities( &mut self, at: MediaTime, modality: Option<SubjectModality>, ) -> Result<usize, SessionError>
Resolves identity for every track that has pending embeddings.
Each pending key carries its own source_id — frames from different
cameras are never mixed into one resolve context.
Returns the number of tracks resolved.
§Errors
Propagates the first identity resolution error.
Sourcepub fn confirm_identity(
&mut self,
audit_id: u64,
confirm: bool,
subject_id: Option<SubjectId>,
key: TrackKey,
) -> Result<(), SessionError>
pub fn confirm_identity( &mut self, audit_id: u64, confirm: bool, subject_id: Option<SubjectId>, key: TrackKey, ) -> Result<(), SessionError>
Applies a manual identity confirmation and patches the track map/sample.
§Errors
Propagates gallery audit lookup errors.
Sourcepub fn open_identity_cases(&self) -> Vec<&IdentityAuditEvent>
pub fn open_identity_cases(&self) -> Vec<&IdentityAuditEvent>
Open multi-hypothesis / uncertain identity cases awaiting host UI.
Sourcepub fn accept_identity_hypothesis(
&mut self,
audit_id: u64,
subject_id: SubjectId,
) -> Result<(), SessionError>
pub fn accept_identity_hypothesis( &mut self, audit_id: u64, subject_id: SubjectId, ) -> Result<(), SessionError>
Accepts one hypothesis subject for an open audit case and assigns the track.
§Errors
Unknown audit / subject not in hypotheses.
Sourcepub fn dismiss_identity_case(
&mut self,
audit_id: u64,
) -> Result<(), SessionError>
pub fn dismiss_identity_case( &mut self, audit_id: u64, ) -> Result<(), SessionError>
Sourcepub fn uncertain_intervals_gapped(
&self,
max_gap_ns: Option<i64>,
) -> Vec<IdentityInterval>
pub fn uncertain_intervals_gapped( &self, max_gap_ns: Option<i64>, ) -> Vec<IdentityInterval>
Uncertain intervals with optional coalescing gap (nanoseconds).
Sourcepub fn assigned_identity_view(&self) -> Vec<(SourceId, TrackId, SubjectId)>
pub fn assigned_identity_view(&self) -> Vec<(SourceId, TrackId, SubjectId)>
Current assigned identity view (latest confirmed/assigned per track).
Sourcepub fn identity_audit_view(&self) -> &[IdentityAuditEvent]
pub fn identity_audit_view(&self) -> &[IdentityAuditEvent]
Immutable identity audit trail.
Sourcepub fn track_samples_audit(&self) -> &[TrackSample]
pub fn track_samples_audit(&self) -> &[TrackSample]
Track samples: full audit (including superseded) vs effective current view.
Sourcepub fn track_samples_effective(&self) -> Vec<TrackSample>
pub fn track_samples_effective(&self) -> Vec<TrackSample>
Effective track samples (not superseded).
Sourcepub fn ingest_zone_updates<const N: usize>(
&mut self,
stamp: FrameStamp,
zone: &mut ZoneAnalytics<'_, N>,
tracked: &[TrackedDetection],
) -> Result<usize, SessionError>
pub fn ingest_zone_updates<const N: usize>( &mut self, stamp: FrameStamp, zone: &mut ZoneAnalytics<'_, N>, tracked: &[TrackedDetection], ) -> Result<usize, SessionError>
Feeds tracked boxes into a zone monitor and records envelopes.
Envelopes inherit any subject already assigned to the track key.
§Errors
Returns SessionError::Analytics when the zone monitor cannot accept
an update (capacity / output).
Sourcepub fn store_mask_bytes(&mut self, bytes: impl Into<Vec<u8>>) -> u64
pub fn store_mask_bytes(&mut self, bytes: impl Into<Vec<u8>>) -> u64
Stores a compact mask blob and returns its handle value for track rows.
Sourcepub fn attach_mask_to_latest_track(
&mut self,
key: TrackKey,
mask_ref: u64,
) -> bool
pub fn attach_mask_to_latest_track( &mut self, key: TrackKey, mask_ref: u64, ) -> bool
Attaches a mask handle by appending a correction sample for a track key.
Sourcepub fn materialize_json(&self) -> Result<String, SessionError>
pub fn materialize_json(&self) -> Result<String, SessionError>
Sourcepub fn save_package(&self, dir: impl AsRef<Path>) -> Result<(), SessionError>
pub fn save_package(&self, dir: impl AsRef<Path>) -> Result<(), SessionError>
Saves the live VisionIndex as an on-disk package directory.
Also writes gallery.json (identity gallery + track embedding index)
into the active generation so package load can restore re-id state
without a full session checkpoint.
§Errors
Returns package I/O or serialization failures.
Sourcepub fn save_checkpoint(&self, dir: impl AsRef<Path>) -> Result<(), SessionError>
pub fn save_checkpoint(&self, dir: impl AsRef<Path>) -> Result<(), SessionError>
Saves index package and full live session runtime checkpoint.
After a process restart, Self::load_checkpoint continues ingest with
the same counters, tracker/Kalman state, gallery embeddings, and pending
identity work.
§Errors
Returns package or checkpoint serialization failures.
Sourcepub fn load_package(
dir: impl AsRef<Path>,
track_config: ByteTrackConfig,
) -> Result<Self, SessionError>
pub fn load_package( dir: impl AsRef<Path>, track_config: ByteTrackConfig, ) -> Result<Self, SessionError>
Loads a package directory into a new session (fresh tracker/gallery).
Prefer Self::load_checkpoint when continuing live ingest.
§Errors
Returns package load or tracker config failures.
Sourcepub fn load_checkpoint(dir: impl AsRef<Path>) -> Result<Self, SessionError>
pub fn load_checkpoint(dir: impl AsRef<Path>) -> Result<Self, SessionError>
Loads index package + full session runtime checkpoint.
§Errors
Returns I/O, deserialization, or restore failures.
Sourcepub fn bottom_center(bbox: Rect) -> Point
pub fn bottom_center(bbox: Rect) -> Point
Helper for tests: bottom-center anchor point of a box.