Konfigurasi

Referensi lengkap parameter pipeline Snapshot Detection per varian, mode VLM (persona & prompt bebas), dan environment variable.

Parameter di halaman ini dikirim sebagai body JSON saat membuat pipeline (POST /pipeline/{node_num}/{stream_id}/{analytic_id}) atau mengubahnya (PUT pada endpoint yang sama). Semua parameter bersifat opsional kecuali disebutkan wajib.

Snapshot Detection tidak memiliki preset konfigurasi (tidak ada add_config_preset di kode) dan sebagian besar varian tidak mendaftarkan default terverbose ke endpoint GET /config/pipeline/{analytic_id}/ — hanya NFV4D-RIOT dan NFV4D-VLM yang melakukannya. Untuk varian lain, gunakan tabel di halaman ini sebagai referensi default, bukan endpoint config.

Parameter Umum

Parameter berikut didefinisikan di snapshot_cfg_base dan menjadi basis bagi hampir semua varian:

Parameter	Tipe	Default	Deskripsi
`address`	string	Berbeda per kelompok varian — lihat Persyaratan — Dependensi	Base URL layanan AI eksternal. Otomatis dinormalisasi (ditambahkan `http://` dan trailing `/`).
`dump_interval`	integer (detik)	`5` untuk hampir semua varian	Interval minimum antar siklus inferensi/dump. Lihat catatan default di bawah — beberapa nilai yang tampak di kode ternyata tidak dipakai saat runtime.
`always_dump`	boolean	`false`	Bila `true`, event tetap diterbitkan walau kondisi target tidak terpenuhi.
`images_num`	integer	`4`	Untuk varian VLM multi-Frame: jumlah Frame yang dikumpulkan menjadi collage. Dipaksa ke rentang 1–6 (nilai di luar rentang otomatis dipangkas, disertai `LOG(WARNING)`).
`interval_capture`	float (detik)	`0.5`	Untuk varian VLM multi-Frame: jeda antar capture Frame yang akan disusun menjadi collage.
`is_dump_collage`	boolean	`true`	Untuk varian VLM multi-Frame: bila `true` snapshot yang dikirim/didump adalah collage; bila `false` satu Frame tunggal.
`areas`	array	`[]`	Format berbeda per kelompok — polygon ROI untuk varian deteksi, garis acuan untuk `WLM`. Lihat tab per varian di bawah.

Default dump_interval yang sebenarnya dipakai

Kode di configs.hpp mendeklarasikan dump_interval berbeda-beda per struct config terluar (mis. flood_config::dump_interval = 10, vmfg_config::dump_interval = 10, rcma_config::dump_interval = 10). Nilai-nilai ini tidak pernah dibaca oleh dispatcher — snapshot.cpp selalu membaca SnapshotType::routine_cfg::dump_interval, yaitu struct *_prompt_cfg yang mewarisi snapshot_cfg_base tanpa override. Akibatnya, default dump_interval yang benar-benar dipakai saat parameter tidak dikirim adalah 5 detik untuk semua varian, kecuali:

NFV4D-WLM — dipaksa naik ke minimum 10 detik saat runtime (wlm_loop()), berapapun nilai yang dikirim.
NFV4D-RIOT — default diambil dari environment variable V4_RIOT_DUMP_INTERVAL (default "10"), bukan 5.

Endpoint GET /config/pipeline/NFV4D-VLM/ juga menampilkan default dump_interval: 30 dan always_dump: true — ini adalah nilai tampilan verbose-config yang berbeda dari nilai runtime sebenarnya (5 detik, false). Jika perilaku spesifik dibutuhkan, kirim dump_interval/always_dump secara eksplisit alih-alih mengandalkan default.

Format `areas` (ROI polygon)

Berlaku untuk NFV4D-OVOD, NFV4D-PSMO, NFV4D-PPHO, NFV4D-FISO, NFV4D-PPFA:

{
  "areas": [
    {
      "name": "Zona Produksi",
      "roi_type": "whitelist",
      "points": [
        { "x": 0.1, "y": 0.1 },
        { "x": 0.9, "y": 0.1 },
        { "x": 0.9, "y": 0.9 },
        { "x": 0.1, "y": 0.9 }
      ]
    }
  ]
}

points minimal 3 titik, koordinat normalized 0–1 (nilai di luar 0–1 dipangkas ke tepi frame).
roi_type bernilai whitelist (default bila tidak dikirim) atau blacklist.
Bila areas tidak dikirim, ROI default mencakup seluruh frame (whitelist).
intersect_threshold (float, default 0.1) mengatur rasio irisan minimum antara bounding box objek dan polygon agar dianggap berada di dalam area.

Parameter Khusus per Varian

NFV4D-OVOD menerima daftar classes (prompt teks) bebas yang akan dideteksi.

Parameter	Tipe	Default	Deskripsi
`classes`	array string	`["person"]` bila tidak dikirim atau bukan array	Daftar nama objek yang ingin dideteksi. Wajib berisi minimal satu string non-kosong — bila kosong, pipeline melempar error `"input classes are empty"` saat dispatch.
`confidence`	float	`0.5`	Confidence minimum agar deteksi diterbitkan sebagai event.
`additional_params.box_th`	float	—	Box confidence threshold di sisi layanan AI eksternal.
`additional_params.text_th`	float	—	Text confidence threshold di sisi layanan AI eksternal.
`additional_params.context.name`	string	Digenerate dari `source_label`/`target_label` bila kosong	Nama label custom hasil relasi antar objek.
`additional_params.context.source_label`	string	`person`	Label sumber relasi.
`additional_params.context.target_label`	string	`person`	Label target relasi.
`additional_params.context.relation`	string	`distance`	Jenis relasi: `distance`, `iou`, `count_inside`, atau `wrap`.
`additional_params.context.operation`	string	`equal`	Operator pembanding (mis. `equal`, `more_than`).
`additional_params.context.value`	int / float / bool	Menyesuaikan `relation`	Nilai pembanding.
`intersect_threshold`	float	`0.1`	Threshold interseksi bbox dengan ROI.

Jika additional_params.context dikonfigurasi, hanya objek dengan label yang sama dengan context.name yang di-dump; bila tidak, semua objek yang lolos confidence di-dump.

NFV4D-OVIC menggunakan deskripsi teks sebagai referensi klasifikasi, dan layanan eksternal yang mengembalikan hasil sudah dalam bentuk boolean per label.

Parameter	Tipe	Default	Deskripsi
`descriptions`	array string	`[]` (wajib diisi)	Daftar deskripsi referensi (mis. `"a person standing"`).
`labels_id`	object	`{}` (wajib diisi)	Mapping nama label ke daftar index `descriptions` (mis. `{ "is_person": [0] }`).
`confidence`	float	`0.2`	Dikirim ke layanan eksternal sebagai `thresh` dikalikan 100 (unit persen).
`softmax`	boolean	`true`	Aktifkan softmax di sisi layanan eksternal.

Event diterbitkan bila minimal satu label pada respons bernilai true; pipeline_data.labels berisi seluruh map label → boolean apa adanya dari respons.

NFV4D-WLM mengukur level air dari dua garis acuan yang Anda gambar.

Parameter	Tipe	Default	Deskripsi
`areas`	array, harus persis 2 entri	3 garis bawaan pada posisi tetap (lihat catatan)	Setiap entri berisi `value` (nilai level pada garis itu) dan `points` (dua titik `{x, y}` normalized 0–1) yang mendefinisikan garis acuan terendah dan tertinggi.
`level`	integer	`3`, hanya berubah bila dikirim lebih besar dari 3	Jumlah level/garis yang diinterpolasi antara garis terendah dan tertinggi.
`dump_interval`	integer	Dipaksa minimum `10`	Nilai di bawah 10 otomatis dinaikkan ke 10 saat runtime.

Bila areas tidak berisi tepat 2 entri, kode diam-diam memakai 3 garis bawaan pada posisi tetap (bukan error) — periksa jumlah entri areas Anda jika level yang dilaporkan tidak sesuai ekspektasi. Begitu pula level hanya berlaku jika nilainya lebih besar dari 3; mengirim level: 2 tidak akan mengubah apa pun.

NFV4D-FLOD memakai model klasifikasi gambar dengan referensi tetap "normal dry road" vs "waterlogged road" — classes/descriptions tidak dapat diubah dari luar. Event diterbitkan saat label waterlogged terdeteksi dengan confidence di atas threshold.

Parameter	Tipe	Default	Deskripsi
`dump_confidence`	float	`0.50`	Threshold (0–1) untuk menerbitkan event `waterlogged`; dikonversi ×100 saat dibandingkan dengan respons layanan eksternal.

pipeline_data FLOD berisi baik key top-level bernama sesuai label (mis. "waterlogged": 87.3) maupun attributes.classification.{label, confidence} — lihat Struktur Event.

Keempat varian ini berbasis deteksi objek dengan prompt classes yang sudah ditetapkan di kode — Anda hanya dapat mengoverride dump_confidence, address, dan areas.

Varian	Classes (tetap)	Relasi (tetap)	`dump_confidence` default	`box_threshold`	`text_threshold`
`NFV4D-PSMO`	`person`, `cigarette`	`person` wrap `cigarette`	`0.30`	`0.35`	`0.25`
`NFV4D-PPHO`	`person`, `handphone`	`person` wrap `handphone`	`0.30`	`0.30`	`0.25`
`NFV4D-FISO`	`smoke`, `fire`, `cloud`, `fog`	Tidak ada — dump bila label terdeteksi adalah `smoke` atau `fire`	`0.30`	`0.30`	`0.15`
`NFV4D-PPFA`	`person`, `firearm`	`person` wrap `firearm`	`0.30`	`0.10`	`0.10`

Parameter yang dapat dikirim: dump_confidence (float), address (string), areas (ROI polygon).

Kelima varian ini menggunakan VLM untuk menjawab pertanyaan tentang Frame (atau collage Frame). Semua memakai routine yang sama (MultiFrameVLMRoutineAR) dengan pertanyaan/threshold berbeda yang tertanam di kode dan tidak dapat diubah lewat konfigurasi, kecuali NFV4D-ARVM yang wajib mengisi event_name.

Varian	`event_name` (tetap kecuali ARVM)	Ambang jawaban "yes" internal	Jumlah prompt
`NFV4D-VMFG`	`people fighting`	≥ 2 dari 3 prompt menjawab yes	3
`NFV4D-VMVD`	`vandalism event`	≥ 1 dari 1 prompt	1
`NFV4D-VMBG`	`ATM burglary event`	≥ 1 dari 1 prompt	1
`NFV4D-RIOT`	`riot event`	≥ 2 dari 3 prompt	3
`NFV4D-ARVM`	Wajib diisi via `event_name` — kosong akan melempar error saat dispatch	≥ 1 dari 1 prompt	1

Parameter yang dapat dikirim untuk semua varian di grup ini: dump_interval, address, images_num, interval_capture, is_dump_collage, always_dump, event_name (untuk ARVM, wajib; untuk varian lain diabaikan karena nama event sudah ditetapkan), answer_debug (boolean, default false — bila true, setiap jawaban VLM ikut di-dump sebagai event debug), dan prompts (array string opsional yang menggantikan prompt otomatis; hanya elemen pertama yang dipakai, menggantikan seluruh alur verifikasi bertingkat).

Khusus NFV4D-RIOT: seluruh parameter dasar (address, always_dump, dump_interval, images_num, interval_capture, is_dump_collage, enable_visual) juga dapat diatur lewat environment variable V4_RIOT_* di sisi node — lihat bagian Environment Variable.

Parameter persona dan min_votes (dijelaskan di tab "VLM Bebas & Persona") diproses oleh routine yang sama pada kelima varian ini, karena resolusi mode VLM (resolve_vlm_mode) berjalan universal untuk semua pipeline berbasis MultiFrameVLMRoutineAR. Namun hanya NFV4D-VLM yang secara resmi mengiklankan parameter ini lewat endpoint config verbose — pada varian lain di grup ini, gunakan dengan hati-hati dan uji langsung sebelum mengandalkannya di produksi.

NFV4D-VLM adalah satu-satunya varian yang secara resmi mendukung tiga mode operasi, dipilih lewat parameter persona:

Mode	Cara memilih	Perilaku
LEGACY_RAW (default)	`persona` tidak dikirim atau kosong	Satu prompt (otomatis atau dari `prompts[0]` bila Anda mengirim array `prompts`), jawaban mentah VLM langsung menjadi label event.
FREE_COT	`persona: "free"`	Menjalankan setiap prompt di `prompts` sebagai pertanyaan yes/no terpisah, lalu voting mayoritas. Wajib mengirim `prompts` (minimal 2 entri) dan `event_name` non-kosong — bila tidak, pipeline melempar error saat konfigurasi.
PRESET_PERSONA	`persona` bernilai salah satu preset	Menjalankan 3 pertanyaan observasi bawaan persona, lalu merangkumnya menjadi satu baris `[severity: X] deskripsi` yang diparse menjadi field `severity` dan `answer`. `event_name` dan `prompts` yang Anda kirim diabaikan (memakai milik persona).

Parameter	Tipe	Default	Deskripsi
`persona`	string	`""` (LEGACY_RAW)	Kosongkan untuk LEGACY_RAW; `"free"` untuk FREE_COT; atau salah satu preset: `public_safety`, `traffic_monitoring`, `industrial_safety`, `retail_loss_prevention`. ID persona lain akan melempar error `"unknown persona id"`.
`prompts`	array string	`["what activity in 3 words?"]`	LEGACY_RAW: hanya elemen pertama dipakai. FREE_COT: seluruh array dijalankan sebagai CoT vote (wajib ≥ 2 entri). Diabaikan pada PRESET_PERSONA.
`event_name`	string	`""`	Wajib diisi non-kosong untuk FREE_COT (dipakai sebagai label event). Diabaikan pada LEGACY_RAW (memakai default `"vlm"`) dan PRESET_PERSONA (memakai nama event bawaan persona).
`min_votes`	integer	`0` (berarti mayoritas ketat: `N/2 + 1`, mis. 3→2, 4→3, 5→3)	Hanya berlaku pada FREE_COT — jumlah minimum jawaban "yes" agar event bernilai `true`.
`is_raw_answer_dump`	boolean	`true`	Hanya relevan pada LEGACY_RAW — bila `true`, jawaban VLM mentah langsung menjadi label event tanpa normalisasi "yes"/"no".
`always_dump`	boolean	`false` (walau endpoint config verbose menampilkan `true` — lihat catatan default di atas)	Bila `true`, event tetap diterbitkan meski jawaban bukan "yes" (khusus LEGACY_RAW/FREE_COT).

Persona preset yang tersedia beserta vocabulary severity-nya:

Persona	Vocabulary Severity
`public_safety`	`normal`, `suspicious`, `aggressive`, `critical`
`traffic_monitoring`	`normal`, `degraded`, `incident`, `emergency`
`industrial_safety`	`normal`, `violation`, `hazard`, `emergency`
`retail_loss_prevention`	`normal`, `suspicious`, `confrontation`, `theft`

Bila jawaban ringkasan VLM tidak mengikuti format [severity: X] deskripsi yang diharapkan, severity diisi "parse_failed"; bila X di luar vocabulary persona, diisi "out_of_vocab".

NFV4D-RCMA memakai VLM single-Frame dengan prompt yang dibangun dari event_name.

Parameter	Tipe	Default	Deskripsi
`event_name`	string	`unexpected vehicle crash`	Disisipkan ke prompt otomatis `"is there any {event_name} in the frame?"`. Wajib tidak kosong — bila kosong, pipeline melempar error saat dispatch.
`address`	string	Lihat Persyaratan — Dependensi	Base URL layanan AI eksternal.

Label event RCMA tidak dapat dikonfigurasi — selalu "crash is Detected" (dari konstanta label = "crash" di kode), berapapun event_name yang Anda kirim. event_name hanya memengaruhi isi prompt yang dikirim ke VLM, bukan label event yang diterbitkan.

Berbeda dari varian VLM multi-Frame, RCMA tidak mendukung always_dump, images_num, persona, atau prompts — event hanya diterbitkan saat VLM menjawab mengandung "yes".

Environment Variable

Hanya NFV4D-RIOT yang membaca konfigurasi dari environment variable node (dibaca sekali saat proses start, dengan utils::get_env):

Variable	Setara parameter API	Default
`V4_RIOT_ADDRESS`	`address`	`http://localhost:4008`
`V4_RIOT_ALWAYS_DUMP`	`always_dump`	`0` (false)
`V4_RIOT_DUMP_INTERVAL`	`dump_interval`	`10`
`V4_RIOT_IMAGES_NUM`	`images_num`	`4`
`V4_RIOT_INTERVAL_CAPTURE`	`interval_capture`	`0.5`
`V4_RIOT_IS_DUMP_COLLAGE`	`is_dump_collage`	`0` (false)
`V4_RIOT_ENABLE_VISUAL`	Overlay bounding box hasil VLM di live view	`1` (true)

Varian lain (termasuk NFV4D-VLM) tidak memiliki environment variable khusus — semua konfigurasi dikirim lewat body pipeline.

Argumen Aplikasi

Argumen berikut berlaku untuk seluruh node dan tidak spesifik ke Snapshot Detection, tetapi menentukan alamat default layanan AI eksternal untuk 9 dari 15 varian (lihat Persyaratan — Dependensi):

Argumen	Default	Fungsi
`--fremis-coordinator-address`	`127.0.0.1:4006`	Alamat fallback untuk `address` pada `OVOD`, `OVIC`, `WLM`, `PSMO`, `PPHO`, `FISO`, `PPFA`, `FLOD`, `RCMA` bila tidak dikirim di body pipeline. Argumen yang sama juga dipakai layanan atribut Face Recognition.

Penjelasan lengkap ada di Configuration Reference.