sightloom-host 0.1.7

Host model package for SightLoom: config, preprocess, adapters, photo→rank pipeline (weights stay host-side)
Documentation

sightloom-host

Host model package for SightLoom.

SightLoom ranks and remembers. This crate owns:

photo / frame → detect / embed (reference or ONNX) → SightLoom IndexSession

Features

Feature What
std (default) Config, preprocess, reference models, HostPipeline
onnx Real ONNX via pure-Rust tract (OnnxEmbedder, OnnxDetector)
download HttpModelFetcher — GET ModelSpec.uri (http/https) into the cache
image-decode JPEG/PNG → RGB for encoded PhotoViews
full onnx + download + image-decode

Weights stay on the host under .sightloom-models/ (gitignored). SightLoom never vendors .onnx. Model license and export policy are the host’s. Recommended pair: YOLOv8n (person detect) + OSNet x1.0 (512-d re-id). With default features nothing is downloaded. Enable download only for trusted config URIs.

Install

[dependencies]
sightloom-host = "0.1"   # crates.io line 0.1.7+
# optional:
# sightloom-host = { version = "0.1", features = ["onnx"] }
# sightloom-host = { version = "0.1", features = ["download", "image-decode"] }
# sightloom-host = { version = "0.1", features = ["full"] }

Quick start (reference models — no weights)

cargo run -p sightloom-host --example photo_to_subject

Weights cookbook (manifest + integrity)

Scaffold a host-side model inventory (no networks are downloaded by default):

cargo run -p sightloom-host --example weights_cookbook -- ./host-models

Writes:

  • models.manifest.json — [ModelManifest] inventory (uri / local_path / optional sha256)
  • .sightloom-models/README.txt — cache layout notes
  • host_bundle.example.json — mapped [HostBundleConfig]

Full guide: COOKBOOK.md.

use sightloom_host::{FilesystemFetcher, ModelManifest, resolve_manifest};

let manifest = ModelManifest::load_path("models.manifest.json")?;
let resolved = resolve_manifest(&manifest, &mut FilesystemFetcher)?;
// With feature `download`: HttpModelFetcher pulls ModelSpec.uri when missing.

Optional ModelSpec.sha256 (64-char hex) is checked after every resolve/download (HostError::Integrity on mismatch).

Step 2: ONNX weights

  1. Create cache (optional helper):
use sightloom_host::write_cache_readme;
write_cache_readme(std::path::Path::new(".sightloom-models"))?;
  1. Place a float32 ONNX file, e.g.:
.sightloom-models/person_reid.onnx

Embedder contract

  • Input: NCHW RGB f32 (see PreprocessConfig, default ImageNet mean/std)
  • Output: embedding vector f32 (L2-normalized by OnnxEmbedder)

Detector contract

  • Input: NCHW RGB f32 — use PreprocessConfig::yolo_detect(640, 640) (/255, no ImageNet mean/std, letterbox)
  • Output (any of):
    • YOLOv8 / v11: [1, 4+C, N] (no objectness)
    • YOLOv5: [1, N, 5+C] (objectness × class)
    • already-decoded N×6 (x1,y1,x2,y2,score,class)
  • Postprocess: letterbox invert + class-aware hard NMS
cargo run -p sightloom-host --features onnx --example onnx_detect
  1. Run:
cargo run -p sightloom-host --features onnx --example onnx_photo_search

If weights are missing the example exits with code 2 and prints setup help (CI-friendly).

Host API (HostPipeline, ONNX when present):

let mut pipe = HostPipeline::from_onnx_cache("cam", ".sightloom-models")?;
let sid = pipe.enroll_photo(jpeg)?;                 // JPEG/PNG, needs image-decode
let hits = pipe.search_photo_jpeg(jpeg, 5)?;
let tracked = pipe.ingest_frame(stamp, &rgb_frame)?;
pipe.save_package("./vision-index")?;
cargo run -p sightloom-host --features full --example host_onnx_pipeline
use sightloom_host::{EmbeddingTask, ModelSpec, ModelTask, OnnxEmbedder, PreprocessConfig};
use std::path::Path;

let mut spec = ModelSpec::embedder("person_reid", ModelTask::PersonReId, 512);
spec.local_path = Some(Path::new(".sightloom-models/person_reid.onnx").into());
spec.preprocess = PreprocessConfig::imagenet_like(128, 256);
let embedder = OnnxEmbedder::load(spec, Path::new(".sightloom-models"), EmbeddingTask::PersonReId)?;

Step 5: download + encoded photos

HTTP fetch (feature download):

use sightloom_host::{HttpModelFetcher, ModelFetcher, ModelSpec, ModelTask};
use std::path::Path;

let mut spec = ModelSpec::embedder("person_reid", ModelTask::PersonReId, 512);
spec.uri = Some("https://example.com/models/person_reid.onnx".into());
let mut fetcher = HttpModelFetcher::default();
let path = fetcher.ensure_local(&spec, Path::new(".sightloom-models"))?;
// Local cache hit skips the network on subsequent runs.

JPEG/PNG encoded photos (feature image-decode):

use sightloom_host::{decode_photo_rgb, PhotoView};

// PhotoView { encoded: Some(jpeg_or_png_bytes), frame: None, ... }
let rgb = decode_photo_rgb(&photo)?;
// ReferenceEmbedder / OnnxEmbedder call this path automatically.

Without image-decode, provide PhotoView::frame (raw RGB) or accept the reference embedder’s raw-byte fingerprint fallback (not for production re-id).

Why tract, not Microsoft ORT?

ort prebuilts are missing on some targets (e.g. x86_64-pc-windows-gnu).
tract-onnx is pure Rust, portable, and enough for step-2 host integration.
Hosts that want CUDA ORT can still implement PhotoEmbeddingAdapter themselves.

Step 3: evidence packs

cargo run -p sightloom-host --example write_evidence_pack -- ./evidence-out

Writes MOT smoke + MOTChallenge export, re-id ROC/EER, and redaction pixel reports. See evidence/README.md.

use sightloom::tracking::ByteTrackConfig;
use sightloom_host::{build_synthetic_evidence_pack, write_evidence_pack};

let pack = build_synthetic_evidence_pack("demo", &ByteTrackConfig::default()).unwrap();
assert!(pack.all_smoke_pass());
write_evidence_pack(&pack, "./evidence-out").unwrap();

Honest boundary

Path Accuracy claim
Reference embedders wiring only
Your ONNX weights + tract depends on your model
Synthetic evidence pack harness smoke only — not MOT17 / production re-id

Docs

docs.rs/sightloom-host (after publish)