API Reference — Snapshot Detection

Endpoint REST API untuk membuat, mengelola, dan memantau pipeline Snapshot Detection (varian NFV4D-*).

← Kembali ke Snapshot Detection

Penjelasan mekanisme, daftar varian, konfigurasi, dan best practice Snapshot Detection.

People Analytics

Counting, dwelling, density, dan attribute classification berbasis tracker.

Semua endpoint pada halaman ini menggunakan basis URL dari variabel VISIONAIRE_API_URL yang dikonfigurasi pada instalasi Visionaire (default: http://localhost:4004). Tidak ada autentikasi tambahan yang diperlukan selain akses jaringan ke host tersebut — pastikan port sudah dapat dijangkau dari klien Anda.

Manajemen Pipeline

Endpoint untuk membuat, memantau, dan menghapus pipeline Snapshot Detection. Setiap pipeline diidentifikasi oleh kombinasi node_num, stream_id, dan analytic_id.

{analytic_id} adalah salah satu dari 15 varian NFV4D-* (lihat Daftar Varian di bawah). Semua varian menggunakan path endpoint yang sama — perbedaannya hanya pada isi config body saat pembuatan.

Buat Pipeline Snapshot Detection

POST /pipeline/{node_num}/{stream_id}/{analytic_id}

Parameter Path

Parameter	Tipe	Deskripsi
`node_num`	integer	Nomor node tempat pipeline akan berjalan (`0` = master).
`stream_id`	string	ID stream yang akan dianalisis.
`analytic_id`	string	ID varian Snapshot Detection (`NFV4D-FISO`, `NFV4D-OVOD`, dll.).

Contoh per Varian

FISO menggunakan OVOD dengan kelas yang sudah ditetapkan. Anda hanya perlu menentukan address Snapshot API dan opsional dump_confidence.

curl -X POST http://localhost:4004/pipeline/0/stream_factory_01/NFV4D-FISO \
  -H "Content-Type: application/json" \
  -d '{
    "config": {
      "address": "http://snapshot-api:4008",
      "dump_interval": 5,
      "dump_confidence": 0.30,
      "areas": [
        {
          "name": "Zona Produksi",
          "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}
          ]
        }
      ]
    }
  }'

PSMO mendeteksi orang merokok menggunakan OVOD dengan context person wrap cigarette.

curl -X POST http://localhost:4004/pipeline/0/stream_warehouse_03/NFV4D-PSMO \
  -H "Content-Type: application/json" \
  -d '{
    "config": {
      "address": "http://snapshot-api:4008",
      "dump_interval": 5,
      "dump_confidence": 0.30,
      "areas": [
        {
          "name": "Area No Smoking",
          "points": [
            {"x": 0.0, "y": 0.0},
            {"x": 1.0, "y": 0.0},
            {"x": 1.0, "y": 1.0},
            {"x": 0.0, "y": 1.0}
          ]
        }
      ]
    }
  }'

OVOD memerlukan daftar classes yang ingin dideteksi. Anda dapat menambahkan additional_params untuk relasi antar objek.

curl -X POST http://localhost:4004/pipeline/0/stream_lobby_07/NFV4D-OVOD \
  -H "Content-Type: application/json" \
  -d '{
    "config": {
      "address": "http://snapshot-api:4008",
      "dump_interval": 5,
      "classes": ["person", "backpack", "luggage"],
      "confidence": 0.5,
      "additional_params": {
        "box_th": 0.3,
        "text_th": 0.25
      },
      "areas": [
        {
          "name": "Main Lobby",
          "points": [
            {"x": 0.1, "y": 0.2},
            {"x": 0.9, "y": 0.2},
            {"x": 0.9, "y": 0.95},
            {"x": 0.1, "y": 0.95}
          ]
        }
      ]
    }
  }'

VMFG menggunakan VLM multi-Frame. images_num dan interval_capture mengontrol collage yang dikirim ke VLM.

curl -X POST http://localhost:4004/pipeline/0/stream_publicarea_02/NFV4D-VMFG \
  -H "Content-Type: application/json" \
  -d '{
    "config": {
      "address": "http://snapshot-api:4008",
      "dump_interval": 10,
      "images_num": 4,
      "interval_capture": 0.5,
      "is_dump_collage": true
    }
  }'

Response Sukses (201 Created)

{
  "status": "success",
  "message": "Pipeline NFV4D-FISO created on node 0 stream stream_factory_01"
}

Status Pipeline

GET /pipeline/{node_num}/{stream_id}/{analytic_id}

Mengembalikan status pipeline yang sedang berjalan, termasuk konfigurasi aktif dan informasi node.

curl http://localhost:4004/pipeline/0/stream_factory_01/NFV4D-FISO

Response

{
  "analytic_id": "NFV4D-FISO",
  "stream_id": "stream_factory_01",
  "node_num": 0,
  "status": "running",
  "config": {
    "address": "http://snapshot-api:4008",
    "dump_interval": 5,
    "dump_confidence": 0.30
  }
}

Hapus Pipeline

DELETE /pipeline/{node_num}/{stream_id}/{analytic_id}

Menghentikan dan menghapus pipeline. Pipeline yang sudah dihapus tidak dapat dipulihkan; buat ulang jika diperlukan.

curl -X DELETE http://localhost:4004/pipeline/0/stream_factory_01/NFV4D-FISO

Response Sukses (200 OK)

{
  "status": "success",
  "message": "Pipeline NFV4D-FISO deleted from node 0 stream stream_factory_01"
}

Update Konfigurasi Pipeline

PUT /pipeline/{node_num}/{stream_id}/{analytic_id}/config

Memperbarui parameter konfigurasi pipeline yang sedang berjalan tanpa perlu me-restart. Hanya field yang disertakan dalam body yang akan diperbarui.

curl -X PUT http://localhost:4004/pipeline/0/stream_factory_01/NFV4D-FISO/config \
  -H "Content-Type: application/json" \
  -d '{
    "config": {
      "dump_confidence": 0.45,
      "dump_interval": 8
    }
  }'

Daftar Varian

Semua 15 varian NFV4D-* yang tersedia, dengan nama dan use case singkat.

Analytic ID	Nama Pipeline	Use Case	Snapshot API Backend
`NFV4D-OVOD`	Open Vocabulary Object Detection	Deteksi objek custom via prompt teks	NFFS-OVOD
`NFV4D-OVIC`	Open Vocabulary Image Classification	Klasifikasi gambar custom via deskripsi teks	NFFS-OVIC
`NFV4D-WLM`	Water Level Monitoring	Pengukuran level air dari garis acuan	NFFS-WLM
`NFV4D-FLOD`	Flood Monitoring	Deteksi banjir / genangan jalan	NFFS-OVIC
`NFV4D-PSMO`	Person Smoking Detection	Deteksi orang merokok	NFFS-OVOD
`NFV4D-PPHO`	Person Using Phone Detection	Deteksi orang menggunakan handphone	NFFS-OVOD
`NFV4D-FISO`	Fire and Smoke Detection	Deteksi api dan asap	NFFS-OVOD
`NFV4D-PPFA`	People with Firearm Detection	Deteksi orang membawa senjata api	NFFS-OVOD
`NFV4D-VMFG`	People Fighting	Deteksi perkelahian	NFFS-VLM
`NFV4D-VMVD`	Vandalism	Deteksi vandalisme	NFFS-VM
`NFV4D-VMBG`	ATM Burglary	Deteksi pembobolan ATM	NFFS-VM
`NFV4D-RIOT`	Riot	Deteksi kerusuhan massa	NFFS-VLM
`NFV4D-VLM`	VLM (Vision Language Model)	Analisis Frame berbasis prompt VLM bebas	NFFS-VLM
`NFV4D-ARVM`	Action Recognition	Pengenalan aksi via VLM	NFFS-VM
`NFV4D-RCMA`	Road Crash Monitoring	Deteksi kecelakaan lalu lintas	NFFS-VM

Parameter Konfigurasi

Parameter Umum (untuk semua varian)

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

Parameter	Tipe	Default	Deskripsi
`address`	string	`http://localhost:4008`	Base URL Snapshot API server. Otomatis dinormalisasi (ditambahkan `http://` dan trailing `/`).
`dump_interval`	integer (detik)	`5` (beberapa varian `10`)	Interval minimum antar siklus inferensi/dump. Minimum 1; untuk WLM minimum 10. Berfungsi sebagai cooldown.
`always_dump`	boolean	`false`	Bila `true`, event tetap diterbitkan walau tidak ada deteksi positif.
`images_num`	integer	`4`	Untuk varian VLM/AR multi-Frame: jumlah Frame yang dikumpulkan menjadi collage. Range valid 1–6.
`interval_capture`	float (detik)	`0.5`	Untuk varian VLM/AR multi-Frame: jeda antar capture Frame. Minimum 0.1.
`is_dump_collage`	boolean	`true`	Untuk varian VLM/AR: bila `true` snapshot yang dikirim adalah collage; bila `false` satu Frame tunggal.
`areas`	array polygon	`[]`	Daftar ROI dalam koordinat normalized 0–1. Hanya berlaku untuk varian dengan dukungan ROI.

Parameter Khusus per Varian

Parameter	Tipe	Default	Deskripsi
`classes`	array string	— (wajib diisi)	Daftar nama objek yang ingin dideteksi.
`confidence`	float	`0.5`	Threshold confidence minimum untuk menerbitkan event.
`additional_params.box_th`	float	—	Box confidence threshold di sisi API.
`additional_params.text_th`	float	—	Text confidence threshold di sisi API.
`additional_params.context.name`	string	—	Nama label custom hasil relasi.
`additional_params.context.source_label`	string	—	Label sumber relasi.
`additional_params.context.target_label`	string	—	Label target relasi.
`additional_params.context.relation`	string	—	Tipe relasi: `distance`, `iou`, `count_inside`, atau `wrap`.
`additional_params.context.operation`	string	—	Operator pembanding (mis. `equal`, `more_than`).
`additional_params.context.value`	any	—	Nilai pembanding.
`intersect_threshold`	float	`0.1`	Threshold interseksi bbox dengan ROI.

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`.
`confidence`	float	`0.2`	Threshold confidence (dikalikan 100 di sisi API).
`softmax`	boolean	`true`	Aktifkan softmax di sisi API.

Parameter	Tipe	Default	Deskripsi
`areas`	array	— (wajib diisi)	Daftar garis acuan, masing-masing berisi `value` (level) dan `points` (dua titik dalam koordinat normalized 0–1).
`level`	integer	`3`	Jumlah level acuan.
`dump_interval`	integer	`10`	Minimum 10 detik untuk WLM (otomatis dinaikkan bila lebih kecil).

FLOD menggunakan model OVIC dengan referensi tetap — tidak memerlukan classes atau descriptions tambahan.

Parameter	Tipe	Default	Deskripsi
`dump_confidence`	float	`0.50`	Threshold untuk menerbitkan event `waterlogged`.
`dump_interval`	integer	`10`	Cooldown khusus FLOD.

Keempat varian ini berbasis OVOD dengan prompt classes yang sudah ditetapkan oleh service. Anda hanya perlu mengoverride threshold bila diperlukan.

Varian	Prompt Classes (internal)	Relasi (internal)	`dump_confidence` default	`box_threshold`	`text_threshold`
PSMO	`person`, `cigarette`	`person` wrap `cigarette`	`0.30`	`0.35`	`0.25`
PPHO	`person`, `handphone`	`person` wrap `handphone`	`0.30`	`0.30`	`0.25`
FISO	`smoke`, `fire`, `cloud`, `fog`	(tidak ada)	`0.30`	`0.30`	`0.15`
PPFA	`person`, `firearm`	`person` wrap `firearm`	`0.30`	`0.10`	`0.10`

Parameter yang dapat dioverride via konfigurasi pipeline: dump_confidence, dump_interval, address, areas.

Varian ini menggunakan VLM untuk menjawab pertanyaan tentang Frame atau collage Frame.

Varian	`event_name` (internal)	`min_answer_choice`	`prompts_size`	`dump_interval` default
VMFG	`people fighting`	2	3	`10`
VMVD	`vandalism event`	1	1	`10`
VMBG	`ATM burglary event`	1	1	`10`
RIOT	`riot event`	2	3	`10`
ARVM	— (wajib diisi)	1	1	`10`

Parameter yang dapat dioverride via konfigurasi pipeline: event_name (wajib untuk ARVM), dump_interval, address, images_num, interval_capture, is_dump_collage.

Parameter	Tipe	Default	Deskripsi
`event_name`	string	`vlm`	Nama event.
`is_raw_answer_dump`	boolean	`true`	Bila `true`, jawaban VLM langsung dijadikan label event.

min_answer_choice diset ke 1000 sehingga setiap dispatch menghasilkan event berisi jawaban mentah VLM — tidak ada agregasi yes/no.

Parameter	Tipe	Default	Deskripsi
`event_name`	string	`unexpected vehicle crash`	Nama event (digunakan dalam prompt VLM).
`label`	string	`crash`	Label event yang dipublikasikan saat VLM menjawab "yes".
`dump_interval`	integer	`10`	Cooldown antar dispatch.

Format Event

Field Top-Level

Semua event Snapshot Detection memiliki struktur top-level yang sama:

Field	Tipe	Deskripsi
`analytic_id`	string	ID varian (`NFV4D-*`).
`stream_id`	string	ID Stream sumber.
`node_num`	integer	Node yang menjalankan pipeline.
`timestamp`	integer (ms)	Unix timestamp event dalam millisecond.
`primary_text`	string	Teks utama event (label objek, jawaban VLM, atau nama event).
`secondary_text`	string	Teks pelengkap (mis. confidence atau jawaban mentah).
`image_jpeg`	string (base64)	Cuplikan Frame atau cropped object.
`pipeline_data`	object	Payload spesifik per varian (lihat di bawah).

Field `pipeline_data` per Tipe Varian

Field	Tipe	Tersedia Pada
`label`	string	Detection (OVOD, PSMO, PPHO, FISO, PPFA)
`confidence`	float	Detection (OVOD, PSMO, PPHO, FISO, PPFA)
`dump`	boolean	OVOD (penanda dump)
`labels`	object	OVIC (mapping label → boolean)
`attributes.classification.label`	string	FLOD
`attributes.classification.confidence`	float	FLOD
`level`	number	WLM
`event`	boolean	VLM-based (VMFG, VMVD, VMBG, RIOT, VLM, ARVM, RCMA)
`answer`	string	VLM-based — jawaban mentah dari VLM
`attributes`	object	VLM-based (opsional)
`detections`	array	VLM-based (opsional)

Contoh Event

{
  "analytic_id": "NFV4D-FISO",
  "stream_id": "stream_factory_01",
  "node_num": 1,
  "timestamp": 1714800000000,
  "primary_text": "fire",
  "secondary_text": "0.812000",
  "image_jpeg": "<base64-encoded JPEG>",
  "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",
  "image_jpeg": "<base64-encoded JPEG>",
  "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",
  "image_jpeg": "<base64-encoded JPEG>",
  "pipeline_data": {
    "dump": true
  }
}

{
  "analytic_id": "NFV4D-VMFG",
  "stream_id": "stream_publicarea_02",
  "node_num": 1,
  "timestamp": 1714800600000,
  "primary_text": "People Fighting is Detected",
  "secondary_text": "",
  "image_jpeg": "<base64-encoded collage JPEG>",
  "pipeline_data": {
    "event": true,
    "answer": "yes"
  }
}

WS /event_channel/{node_num}/{stream_id}/{analytic_id}

Visionaire4 mendorong setiap event hasil deteksi melalui WebSocket. Setelah koneksi terbuka, server langsung mengirim event tanpa handshake atau pesan subscribe tambahan.

Parameter Path

Parameter	Tipe	Deskripsi
`node_num`	integer	Nomor node tempat pipeline berjalan (`0` = master).
`stream_id`	string	ID Stream yang dipantau.
`analytic_id`	string	ID varian Snapshot Detection (mis. `NFV4D-FISO`).

Contoh Koneksi

const ws = new WebSocket(
  'ws://localhost:4004/event_channel/0/stream_factory_01/NFV4D-FISO'
);

ws.onmessage = (msg) => {
  const event = JSON.parse(msg.data);
  console.log(event.primary_text, event.pipeline_data);
};

ws.onerror = (err) => console.error('WebSocket error', err);
ws.onclose = () => console.log('Disconnected');

import asyncio
import json
import websockets

async def listen():
    url = "ws://localhost:4004/event_channel/0/stream_factory_01/NFV4D-FISO"
    async with websockets.connect(url) as ws:
        async for msg in ws:
            event = json.loads(msg)
            print(event["primary_text"], event["pipeline_data"])

asyncio.run(listen())

curl --no-buffer \
  -H "Connection: Upgrade" \
  -H "Upgrade: websocket" \
  -H "Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==" \
  -H "Sec-WebSocket-Version: 13" \
  http://localhost:4004/event_channel/0/stream_factory_01/NFV4D-FISO

Endpoint Channel Lainnya

Endpoint	Cakupan
`WS /event_channel/`	Semua event dari seluruh node
`WS /event_channel/{node_num}/`	Semua event dari satu node
`WS /event_channel/{node_num}/{stream_id}`	Semua event dari satu stream (semua analitik)

Visualisasi (MJPEG)

GET /mjpeg/{node_num}/{stream_id}/{analytic_id}?fps=15&height=480

Menghasilkan stream MJPEG dari pipeline yang sedang berjalan. Berguna untuk memverifikasi bahwa ROI dan overlay sudah dikonfigurasi dengan benar.

Query Parameter

Parameter	Tipe	Default	Deskripsi
`fps`	integer	`15`	Frame per detik output MJPEG.
`height`	integer	`480`	Tinggi output dalam piksel (aspek rasio dipertahankan).

Contoh

# Buka di browser atau media player yang mendukung MJPEG
http://localhost:4004/mjpeg/0/stream_factory_01/NFV4D-FISO?fps=10&height=720

API Reference — Snapshot Detection

← Kembali ke Snapshot Detection

People Analytics

Manajemen Pipeline

Buat Pipeline Snapshot Detection

Parameter Path

Contoh per Varian

Response Sukses (201 Created)

Status Pipeline

Response

Hapus Pipeline

Response Sukses (200 OK)

Update Konfigurasi Pipeline

Daftar Varian

Parameter Konfigurasi

Parameter Umum (untuk semua varian)

Parameter Khusus per Varian

Format Event

Field Top-Level

Field `pipeline_data` per Tipe Varian

Contoh Event

Parameter Path

Contoh Koneksi

Endpoint Channel Lainnya

Visualisasi (MJPEG)

Query Parameter

Contoh

Modul Terkait

People Analytics

PPE Detection

Crowd Estimation

On this page