Nodeflux Central
Snapshot Detection

API Reference — Snapshot Detection

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

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. Snapshot Detection tidak memanggil FREMIS-N — endpoint ini seluruhnya adalah Visionaire API sendiri; layanan AI eksternal tempat inferensi berjalan tidak diekspos lewat Visionaire API (lihat Persyaratan — Dependensi).


Manajemen Pipeline

Setiap pipeline diidentifikasi oleh kombinasi node_num, stream_id, dan analytic_id. {analytic_id} adalah salah satu dari 15 varian NFV4D-* (lihat Varian & Cara Kerja) — semua varian memakai path endpoint yang sama, perbedaannya hanya pada isi body config saat pembuatan.

Buat Pipeline

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

curl -X POST http://localhost:4004/pipeline/0/stream_factory_01/NFV4D-FISO \
  -H "Content-Type: application/json" \
  -d '{
    "config": {
      "address": "http://ai-service:4006",
      "dump_interval": 5,
      "dump_confidence": 0.30,
      "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}
          ]
        }
      ]
    }
  }'
curl -X POST http://localhost:4004/pipeline/0/stream_warehouse_03/NFV4D-PSMO \
  -H "Content-Type: application/json" \
  -d '{
    "config": {
      "address": "http://ai-service:4006",
      "dump_interval": 5,
      "dump_confidence": 0.30
    }
  }'
curl -X POST http://localhost:4004/pipeline/0/stream_lobby_07/NFV4D-OVOD \
  -H "Content-Type: application/json" \
  -d '{
    "config": {
      "address": "http://ai-service:4006",
      "dump_interval": 5,
      "classes": ["person", "backpack", "luggage"],
      "confidence": 0.5,
      "additional_params": {
        "box_th": 0.3,
        "text_th": 0.25
      }
    }
  }'
curl -X POST http://localhost:4004/pipeline/0/stream_publicarea_02/NFV4D-VMFG \
  -H "Content-Type: application/json" \
  -d '{
    "config": {
      "address": "http://ai-service:4008",
      "dump_interval": 10,
      "images_num": 4,
      "interval_capture": 0.5,
      "is_dump_collage": true
    }
  }'
curl -X POST http://localhost:4004/pipeline/0/stream_terminal_01/NFV4D-VLM \
  -H "Content-Type: application/json" \
  -d '{
    "config": {
      "address": "http://ai-service:4008",
      "dump_interval": 15,
      "persona": "public_safety"
    }
  }'

Response Sukses (200)

{
  "code": 200,
  "message": "pipeline successfully created",
  "node_num": 0,
  "stream_id": "stream_factory_01",
  "analytic_id": "NFV4D-FISO"
}

Bila pipeline dengan analytic_id yang sama sudah berjalan pada stream tersebut, request ditolak dengan status 400 dan pesan "analytic_id=<id> is already exists in stream=<stream_id> !".


Perbarui Konfigurasi Pipeline

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

Memperbarui parameter pipeline yang sedang berjalan tanpa restart. Body sama seperti POST.

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

Response sukses (200): {"code": 200, "message": "pipeline successfully updated", "node_num": 0, "stream_id": "stream_factory_01", "analytic_id": "NFV4D-FISO"}.


Baca Konfigurasi Pipeline

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

curl http://localhost:4004/pipeline/0/stream_factory_01/NFV4D-FISO
{
  "code": 200,
  "node_num": 0,
  "stream_id": "stream_factory_01",
  "analytic_id": "NFV4D-FISO",
  "config": {
    "address": "http://ai-service:4006",
    "dump_interval": 5,
    "dump_confidence": 0.3
  },
  "message": "configuration has been successfully retrieved from the db"
}

Untuk seluruh varian Snapshot Detection, endpoint ini mengembalikan konfigurasi yang tersimpan di database (persis seperti yang terakhir dikirim lewat POST/PUT), bukan konfigurasi runtime yang sudah digabung dengan default terverbose — mekanisme "verbose config registry" seperti pada Face Recognition (NFV4-FR, dst.) tidak berlaku untuk varian NFV4D-*.


Hapus Pipeline

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

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

Response sukses (200): {"code": 200, "message": "pipeline successfully deleted", "node_num": 0, "stream_id": "stream_factory_01", "analytic_id": "NFV4D-FISO"}. Pipeline yang sudah dihapus tidak dapat dipulihkan; buat ulang jika diperlukan.


Cek Default Konfigurasi Varian

GET /config/pipeline/{analytic_id}/ (atau GET /v2/config/pipeline/{analytic_id}/)

Mengembalikan daftar parameter yang didaftarkan varian tersebut sebagai "verbose config" — dipakai antara lain untuk membangun form konfigurasi di UI.

Dari 15 varian NFV4D-*, hanya NFV4D-RIOT dan NFV4D-VLM yang mendaftarkan verbose config (lihat Konfigurasi). Memanggil endpoint ini untuk 13 varian lainnya (NFV4D-OVOD, NFV4D-OVIC, NFV4D-WLM, NFV4D-FLOD, NFV4D-PSMO, NFV4D-PPHO, NFV4D-FISO, NFV4D-PPFA, NFV4D-VMFG, NFV4D-VMVD, NFV4D-VMBG, NFV4D-ARVM, NFV4D-RCMA) akan mengembalikan daftar configs kosong — gunakan tabel parameter di halaman Konfigurasi sebagai referensi untuk varian-varian tersebut.

Tidak ada endpoint preset (GET /config/preset/{analytic_id}/ selalu kosong untuk NFV4D-*) — Snapshot Detection tidak mendaftarkan preset apa pun.


Event Streaming (WebSocket)

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

Visionaire mengirim setiap event hasil dispatch melalui WebSocket. Setelah koneksi terbuka, server langsung mendorong (push) setiap event ke client tanpa handshake atau pesan subscribe tambahan.

Parameter Path

ParameterTipeDeskripsi
node_numintegerNomor node tempat pipeline berjalan (0 = master).
stream_idstringID Stream yang dipantau.
analytic_idstringID 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())

Endpoint Channel Lainnya

EndpointCakupan
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)

Live View (MJPEG)

GET /mjpeg/{node_num}/{stream_id}/{analytic_id} menghasilkan MJPEG stream dengan overlay pipeline (ROI, bounding box) — berguna untuk memverifikasi konfigurasi areas secara visual. Tanpa {analytic_id} (GET /mjpeg/{node_num}/{stream_id}), endpoint ini menampilkan stream mentah tanpa overlay analitik apa pun.

Query Parameter

ParameterTipeDefaultDeskripsi
fpsinteger0Frame per detik output MJPEG.
heightinteger320Tinggi output dalam piksel.
jqinteger60Kualitas JPEG (0–100).
curl "http://localhost:4004/mjpeg/0/stream_factory_01/NFV4D-FISO?fps=10&height=480&jq=70"

GET /visual/{node_num}/{stream_id}/{analytic_id} bukan endpoint MJPEG — ia mengembalikan halaman HTML viewer, bukan gambar/stream langsung. Untuk mengambil MJPEG secara terprogram, gunakan /mjpeg/... di atas. Path /pipeline/{node_num}/{stream_id}/{analytic_id}/mjpeg dan /pipeline/.../snapshot yang muncul di dokumentasi versi lama tidak ada — endpoint MJPEG selalu berada di bawah prefix /mjpeg/..., terpisah dari /pipeline/....


Struktur Event

Semua event Snapshot Detection memakai envelope yang sama dengan modul analitik Visionaire lainnya. Bagian spesifik per varian ada di pipeline_data.

{
  "timestamp": 1714800000,
  "node_num": 1,
  "stream_id": "stream_factory_01",
  "stream_name": "Gudang Produksi",
  "stream_address": "rtsp://10.7.2.60:554/stream",
  "stream_longitude": 106.823649,
  "stream_latitude": -6.261376,
  "analytic_id": "NFV4D-FISO",
  "primary_text": "fire",
  "secondary_text": "0.812000",
  "pipeline_data": {
    "event_id": "1714800000-1a2b3c4d",
    "label": "fire",
    "confidence": 0.812
  },
  "image_jpeg": "<base64 JPEG>"
}

Field Envelope

FieldTipeDeskripsi
timestampintWaktu event dalam epoch detik (UTC).
node_numintNomor node tempat pipeline berjalan.
stream_idstringIdentifier stream sumber.
stream_namestringNama stream.
stream_addressstringURL sumber video stream.
stream_longitude, stream_latitudefloatPosisi kamera.
analytic_idstringVarian pipeline yang memancarkan event (NFV4D-*).
primary_textstringTeks utama event — bervariasi per varian (label objek, nama event VLM, atau angka level WLM).
secondary_textstringTeks pelengkap — bervariasi per varian (confidence, atau kosong).
pipeline_dataobjectPayload spesifik per varian — lihat tabel di bawah.
image_jpegstring (base64)Snapshot Frame (atau crop objek/collage) yang menjadi bukti deteksi.

Tidak ada event_id di level atas envelope — event_id (format <timestamp>-<hash8>) hanya ada di dalam pipeline_data.

Field pipeline_data per Kelompok Varian

FieldTipeTersedia Pada
event_idstringSemua varian
labelstringDeteksi ROI: OVOD (bila context dikonfigurasi), PSMO, PPHO, FISO, PPFA
confidencefloatDeteksi ROI: PSMO, PPHO, FISO, PPFA
dumpbooleanOVOD tanpa context — penanda dump (selalu true saat event diterbitkan)
labelsobjectOVIC — mapping label → boolean apa adanya dari respons layanan eksternal
<label> (dinamis)floatFLOD — nilai confidence mentah untuk label yang cocok (mis. "waterlogged": 87.3)
attributes.classification.label / .confidencestring / floatFLOD
levelnumberWLM
eventbooleanSemua varian VLM (VMFG, VMVD, VMBG, RIOT, VLM mode LEGACY_RAW/FREE_COT, ARVM, RCMA) — true bila kondisi target terpenuhi
answerstringSemua varian VLM — jawaban dari VLM (mentah pada LEGACY_RAW, "yes"/"no" pada FREE_COT, deskripsi hasil parsing pada PRESET_PERSONA)
personastringNFV4D-VLM — kosong pada LEGACY_RAW, "free" pada FREE_COT, atau nama preset pada PRESET_PERSONA
severitystringNFV4D-VLM mode PRESET_PERSONA — salah satu vocabulary persona, atau "parse_failed"/"out_of_vocab"
votes / min_votesintNFV4D-VLM mode FREE_COT
cot_answersarray stringNFV4D-VLM mode FREE_COT dan PRESET_PERSONA — jawaban mentah tiap prompt CoT
detectionsarrayOpsional pada varian VLM bila jawaban mengandung koordinat lokasi terparsir

Contoh Event per Varian

{
  "analytic_id": "NFV4D-FISO",
  "stream_id": "stream_factory_01",
  "node_num": 1,
  "timestamp": 1714800000,
  "primary_text": "fire",
  "secondary_text": "0.812000",
  "pipeline_data": { "event_id": "1714800000-1a2b3c4d", "label": "fire", "confidence": 0.812 }
}
{
  "analytic_id": "NFV4D-PSMO",
  "stream_id": "stream_warehouse_03",
  "node_num": 1,
  "timestamp": 1714800120,
  "primary_text": "person smoking",
  "secondary_text": "0.421000",
  "pipeline_data": { "event_id": "1714800120-9f8e7d6c", "label": "person smoking", "confidence": 0.421 }
}
{
  "analytic_id": "NFV4D-OVOD",
  "stream_id": "stream_lobby_07",
  "node_num": 2,
  "timestamp": 1714800300,
  "primary_text": "Main Lobby: person",
  "secondary_text": "0.762000",
  "pipeline_data": { "event_id": "1714800300-2b3c4d5e", "dump": true }
}
{
  "analytic_id": "NFV4D-WLM",
  "stream_id": "stream_river_05",
  "node_num": 1,
  "timestamp": 1714800900,
  "primary_text": "900",
  "secondary_text": "",
  "pipeline_data": { "event_id": "1714800900-4d5e6f70", "level": 900 }
}
{
  "analytic_id": "NFV4D-FLOD",
  "stream_id": "stream_road_02",
  "node_num": 1,
  "timestamp": 1714801200,
  "primary_text": "waterlogged",
  "secondary_text": "87.300 %",
  "pipeline_data": {
    "event_id": "1714801200-5e6f7081",
    "waterlogged": 87.3,
    "attributes": { "classification": { "label": "waterlogged", "confidence": 87.3 } }
  }
}
{
  "analytic_id": "NFV4D-RIOT",
  "stream_id": "stream_publicarea_02",
  "node_num": 1,
  "timestamp": 1714800600,
  "primary_text": "Riot is Detected",
  "secondary_text": "",
  "pipeline_data": { "event_id": "1714800600-6f708192", "event": true, "answer": "yes" }
}
{
  "analytic_id": "NFV4D-VLM",
  "stream_id": "stream_terminal_01",
  "node_num": 1,
  "timestamp": 1714801500,
  "primary_text": "public safety event: suspicious",
  "secondary_text": "Two people arguing near the ticket counter, no physical contact observed.",
  "pipeline_data": {
    "event_id": "1714801500-708192a3",
    "event": true,
    "answer": "Two people arguing near the ticket counter, no physical contact observed.",
    "persona": "public_safety",
    "severity": "suspicious",
    "cot_answers": [
      "Two people are standing close, gesturing animatedly.",
      "Two people visible, body language agitated.",
      "No weapons or broken objects visible; raised voices only."
    ]
  }
}

On this page