Snapshot Detection

Snapshot Detection adalah keluarga analitik event-driven di Visionaire yang menjalankan deteksi berbasis Snapshot — bukan tracking per Frame. Modul ini bertindak sebagai dispatcher yang mengambil Frame dari Stream pada interval tertentu, mengirimkannya ke Snapshot API yang sesuai (deteksi objek, klasifikasi, atau VLM), lalu menerbitkan event hanya bila kejadian target benar-benar terdeteksi.

Berbeda dengan modul People Analytics atau Vehicle Analytics yang berfokus pada counting, dwelling, atau attribute classification berbasis tracker, Snapshot Detection difokuskan untuk mendeteksi kejadian (incident) dalam satu Frame atau kumpulan Frame — misalnya kebakaran, perkelahian, perilaku merokok, atau objek custom dari prompt teks.

Pengenalan / Cara Kerja Umum

Semua varian Snapshot Detection berbagi pipeline yang sama:

Karakteristik utama:

• Event-driven, bukan per Frame. Pipeline tidak menerbitkan event setiap Frame; ia menunggu kondisi deteksi terpenuhi (confidence di atas ambang, label cocok, jawaban VLM = "yes", dll.).
• Cooldown via dump_interval. Antara dua siklus inferensi terdapat jeda minimum (default 5 detik untuk sebagian besar varian; 10 detik untuk kategori VLM/event). Ini juga berperan sebagai mekanisme rate limiting agar event tidak meledak.
• Backend Snapshot API terpisah. Pipeline Visionaire bertindak sebagai dispatcher; inferensi sebenarnya dilakukan oleh service Snapshot API (NFFS-OVOD, NFFS-OVIC, NFFS-VM, NFFS-VLM) yang harus berjalan terpisah.
• Output minimal. Setiap event berisi snapshot Frame (atau cropped object) plus payload pipeline_data ringkas — tanpa tracker_id, tanpa area_count, tanpa dwelling_duration. Setiap event berdiri sendiri.

Daftar Varian

Tersedia 15 varian Snapshot Detection. Semuanya menggunakan prefix Analytic ID NFV4D-*.

Pengelompokan berdasarkan Use Case

Apa yang Dilakukan / Yang TIDAK Dilakukan

Kemampuan Bersama

• Event-driven dispatch. Event hanya diterbitkan saat kondisi target terpenuhi (deteksi positif, klasifikasi cocok, atau jawaban VLM = "yes").
• Snapshot per kejadian. Setiap event membawa cuplikan Frame (atau crop bounding box) yang menjadi bukti deteksi.
• Konfigurasi seragam. Semua varian menerima parameter dasar yang sama: address, dump_interval, dll.
• Dukungan ROI. Sebagian varian (lihat tabel di bawah) memfilter deteksi hanya pada polygon yang Anda definisikan.
• Dukungan VLM multi-Frame. Varian VMFG, VMVD, VMBG, RIOT, ARVM, dan VLM dapat menggabungkan beberapa Frame menjadi satu collage untuk meningkatkan konteks temporal.

Yang TIDAK Dilakukan

• Tidak melakukan tracking. Tidak ada tracker_id lintas event; tidak bisa menjawab pertanyaan "apakah orang yang sama muncul lagi?".
• Tidak melakukan counting/dwelling. Untuk metrik kuantitatif gunakan People Analytics atau Vehicle Analytics.
• Tidak melakukan recognition identitas. Untuk identifikasi wajah gunakan Face Recognition; untuk plat nomor gunakan License Plate Recognition.
• Tidak realtime per Frame. Inferensi terjadi pada interval dump_interval (default 5–10 detik). Bukan untuk skenario yang memerlukan latensi sub-detik per Frame.

Use Cases

Persyaratan

Kamera

Catatan tambahan per kategori:

• FISO/FLOD/WLM — pasang kamera dengan view yang jelas terhadap area pengamatan; hindari obstruksi vegetasi atau struktur.
• VMFG/VMVD/RIOT/PPFA — sudut pandang luas dengan ketinggian sedang (3–5 meter) agar konteks aksi tertangkap.
• PSMO/PPHO — resolusi orang minimal 100×200 piksel agar objek kecil (rokok, handphone) terlihat.
• OVOD/OVIC — tergantung target prompt; sesuaikan resolusi dengan ukuran objek terkecil.

Lingkungan

• CPU 3 core dan RAM 2 GB untuk pipeline dispatcher Visionaire.
• GPU resource sebagian besar berada di sisi Snapshot API server (terpisah).
• Konektivitas low-latency antara Visionaire dan Snapshot API.

Dependensi

• Snapshot API sesuai varian harus berjalan dan dapat dijangkau:
  • NFFS-OVOD/v1/object-detection untuk OVOD, PSMO, PPHO, FISO, PPFA
  • NFFS-OVIC/v1/image-classification untuk OVIC, FLOD
  • NFFS-WLM/v1/predict untuk WLM
  • NFFS-VM/v1/image-recognition untuk VMVD, VMBG, ARVM, RCMA
  • NFFS-VLM/v1/image-recognition untuk VMFG, RIOT, VLM
• Konfigurasi address di pipeline harus mengarah ke base URL Snapshot API server (default http://localhost:4008).
• Stream video sudah terdaftar di Visionaire dan dapat diakses oleh node yang akan menjalankan pipeline.

Setting Up

Konfigurasi

Parameter API Umum

Parameter berikut tersedia untuk semua varian Snapshot Detection (didefinisikan di snapshot_cfg_base):

ROI dan Group Loop

Penanganan loop dan dukungan ROI berbeda per varian:

Parameter Khusus per Varian

Output yang Dihasilkan

Struktur Event

Semua event Snapshot Detection memiliki struktur top-level yang sama dengan event analitik Visionaire lainnya. Payload spesifik per varian berada di field pipeline_data.

Field pipeline_data per Tipe Varian

Contoh Event

{
  "analytic_id": "NFV4D-FISO",
  "stream_id": "stream_factory_01",
  "node_num": 1,
  "timestamp": 1714800000000,
  "primary_text": "fire",
  "secondary_text": "0.812000",
  "pipeline_data": {
    "label": "fire",
    "confidence": 0.812
  }
}

{
  "analytic_id": "NFV4D-PSMO",
  "stream_id": "stream_warehouse_03",
  "node_num": 1,
  "timestamp": 1714800120000,
  "primary_text": "person smoking",
  "secondary_text": "0.421000",
  "pipeline_data": {
    "label": "person smoking",
    "confidence": 0.421
  }
}

{
  "analytic_id": "NFV4D-OVOD",
  "stream_id": "stream_lobby_07",
  "node_num": 2,
  "timestamp": 1714800300000,
  "primary_text": "Main Lobby: person",
  "secondary_text": "0.762000",
  "pipeline_data": {
    "dump": true
  }
}

{
  "analytic_id": "NFV4D-RIOT",
  "stream_id": "stream_publicarea_02",
  "node_num": 1,
  "timestamp": 1714800600000,
  "primary_text": "Riot is Detected",
  "secondary_text": "",
  "pipeline_data": {
    "event": true,
    "answer": "yes"
  }
}

{
  "analytic_id": "NFV4D-WLM",
  "stream_id": "stream_river_05",
  "node_num": 1,
  "timestamp": 1714800900000,
  "primary_text": "900",
  "secondary_text": "",
  "pipeline_data": {
    "level": 900
  }
}

Best Practices

Setting dump_interval

• Untuk skenario keselamatan kritis (FISO, PPFA), gunakan dump_interval rendah (5 detik) agar response cepat.
• Untuk skenario rate-limited (RIOT, VMFG), pertahankan dump_interval di 10 detik atau lebih agar event tidak meledak saat insiden berlangsung lama.
• Untuk WLM atau monitoring lingkungan yang lambat berubah, naikkan dump_interval ke 30–60 detik untuk hemat resource.

Penggunaan ROI

• Untuk varian yang mendukung ROI (OVOD, PSMO, PPHO, FISO, PPFA), definisikan polygon yang membatasi area pengamatan untuk mengurangi false positive di area tidak relevan.
• ROI juga membantu memberi konteks lokasi (nama area) pada event.

Tuning threshold

• dump_confidence adalah filter terakhir di sisi pipeline. Untuk environment dengan banyak false positive, naikkan ke 0.5–0.7.
• Untuk skenario yang tidak boleh ada miss (mis. fire detection di gudang material berbahaya), turunkan ke 0.2–0.3 dan terima trade-off lebih banyak alert.

Reliability Webhook

• Untuk event critical (RIOT, VMBG, FISO), gunakan transport dengan retry/idempotency.
• Pertimbangkan persistensi event di sisi receiver agar lost event dapat di-replay.

Pemilihan multi-Frame vs single-Frame VLM

• VMFG dan RIOT (prompts_size = 3) menggunakan dua-tahap verifikasi: jawaban awal + verifikasi tambahan. Akurasi lebih tinggi, latensi lebih besar.
• VMVD, VMBG, ARVM (prompts_size = 1) hanya satu prompt — lebih cepat, tetapi lebih rentan false positive.

Limitations

• Tidak ada tracking. Setiap event berdiri sendiri; tidak bisa menjawab pertanyaan "apakah orang yang sama muncul lagi 5 detik kemudian?".
• Tidak ada counting/dwelling. Untuk metrik kuantitatif (berapa orang, berapa lama), gunakan modul People Analytics atau Vehicle Analytics.
• Akurasi sangat bergantung pada kondisi lapangan. Pencahayaan, sudut kamera, occlusion, dan kualitas codec semuanya berpengaruh.
• Resource VLM/OVOD lebih berat. Varian VLM (VMFG, VMVD, VMBG, RIOT, VLM, ARVM) dan OVOD memerlukan GPU memory dan compute lebih besar di sisi Snapshot API server.
• Latency dispatch. Karena event hanya muncul tiap dump_interval detik, kejadian yang lebih singkat dari interval bisa terlewat.
• Snapshot API harus tersedia. Bila Snapshot API tidak dapat dijangkau, pipeline akan men-set side message error tetapi tidak menerbitkan event.
• Beberapa default tertanam di service. Mengubah classes/prompt di luar yang dapat dikonfigurasi (mis. mengganti list dump_classes FISO) memerlukan perubahan di sisi service Snapshot API.

Modul Terkait