API Reference — Vehicle Analytics

Endpoint REST API untuk membuat pipeline Vehicle Analytics pada stream Visionaire4, event streaming via WebSocket, dan struktur event JSON per varian.

← Kembali ke Vehicle Analytics

Pengenalan, varian, persyaratan kamera, dan konfigurasi.

Varian & Cara Kerja

Delapan varian pipeline dan perbedaannya.

Konfigurasi

Referensi lengkap parameter body pipeline per varian.

Endpoint pipeline (/pipeline/...) memanggil Visionaire API — basis URL dikonfigurasi lewat variabel VISIONAIRE_API_URL (default: http://localhost:4004). Autentikasi mengikuti konfigurasi deployment Visionaire4 Anda. Untuk detail instalasi dan konfigurasi layanan, lihat halaman Instalasi Dependensi.

Manajemen Pipeline

Endpoint untuk membuat, membaca konfigurasi, memperbarui, dan menghapus pipeline Vehicle Analytics. Halaman ini mendokumentasikan penuh NFV4-MVA dan NFV4-MVAA — dua varian multi-logic utama. Enam varian lain (NFV4-MVAS, NFV4-VC, NFV4-VC-HW, NFV4-VD, NFV4-VAS, NFV4-VCAT) memakai endpoint dengan bentuk yang sama — ganti segmen terakhir path dengan analytic_id yang diinginkan, dan sesuaikan body request sesuai Konfigurasi. Detail perbedaan tiap varian ada di Varian & Cara Kerja.

Authorization

bearerAuth

AuthorizationBearer <token>

In: header

Path Parameters

node_num*integer

Nomor node. Gunakan 0 untuk deployment single-node.

stream_id*string

ID stream video yang akan dianalisis.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

object_confidence_threshold?number

Threshold confidence global untuk deteksi kendaraan, dipakai oleh sub-analitik yang tidak mengirim override sendiri.

Default0.4

Formatfloat

Range0 <= value <= 1

colordet_crop_w?number

Rasio lebar crop bounding box yang dipakai saat mengekstrak warna kendaraan (NFV4-MVAA).

Default0.8

Formatfloat

colordet_crop_h?number

Rasio tinggi crop bounding box untuk klasifikasi warna (NFV4-MVAA).

Default0.8

Formatfloat

sub_analytics?array<|||>

Konfigurasi tiap sub-analitik yang ingin diaktifkan. Setiap objek wajib memiliki name dan is_active.

Response Body

`application/json`

curl -X POST "http://localhost:4004/pipeline/0/stream_001/NFV4-MVA" \  -H "Content-Type: application/json" \  -d '{    "object_confidence_threshold": 0.4,    "sub_analytics": [      {        "name": "counting",        "is_active": true,        "dumping_sampling_time": 1000,        "areas": [          {            "name": "Gate A",            "points": [              {                "x": 0.2,                "y": 0.5              },              {                "x": 0.8,                "y": 0.5              }            ],            "direction": "both"          }        ]      },      {        "name": "roi_counting",        "is_active": false      },      {        "name": "dwelling",        "is_active": false      },      {        "name": "density",        "is_active": false      }    ]  }'

{  "code": 200,  "message": "pipeline successfully created",  "node_num": 0,  "stream_id": "stream_001",  "analytic_id": "NFV4-MVA"}

{  "code": 400,  "message": "analytic_id=NFV4-MVA is already exists in stream=stream_001 !"}

{  "code": 404,  "message": "stream_id: stream_001 is not exists"}

Authorization

bearerAuth

AuthorizationBearer <token>

In: header

Path Parameters

node_num*integer

Nomor node. Gunakan 0 untuk deployment single-node.

stream_id*string

ID stream video yang akan dianalisis.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

object_confidence_threshold?number

Threshold confidence global untuk deteksi kendaraan, dipakai oleh sub-analitik yang tidak mengirim override sendiri.

Default0.4

Formatfloat

Range0 <= value <= 1

colordet_crop_w?number

Rasio lebar crop bounding box yang dipakai saat mengekstrak warna kendaraan (NFV4-MVAA).

Default0.8

Formatfloat

colordet_crop_h?number

Rasio tinggi crop bounding box untuk klasifikasi warna (NFV4-MVAA).

Default0.8

Formatfloat

sub_analytics?array<|||>

Konfigurasi tiap sub-analitik yang ingin diaktifkan. Setiap objek wajib memiliki name dan is_active.

Response Body

`application/json`

curl -X PUT "http://localhost:4004/pipeline/0/stream_001/NFV4-MVA" \  -H "Content-Type: application/json" \  -d '{    "object_confidence_threshold": 0.5,    "sub_analytics": [      {        "name": "counting",        "is_active": true,        "object_confidence_threshold": 0.5      }    ]  }'

{  "code": 200,  "message": "pipeline successfully updated",  "node_num": 0,  "stream_id": "stream_001",  "analytic_id": "NFV4-MVA"}

{  "code": 400,  "message": "invalid configuration"}

{  "code": 404,  "message": "pipeline not found"}

Authorization

bearerAuth

AuthorizationBearer <token>

In: header

Path Parameters

node_num*integer

Nomor node. Gunakan 0 untuk deployment single-node.

stream_id*string

ID stream video yang akan dianalisis.

Response Body

`application/json`

curl -X GET "http://localhost:4004/pipeline/0/stream_001/NFV4-MVA"

{  "code": 200,  "message": "configuration has been successfully retrieved from the runtime pipeline",  "data": {    "object_confidence_threshold": 0.4,    "sub_analytics": [      {        "name": "counting",        "is_active": true,        "areas": []      }    ]  }}

{  "code": 400,  "message": "analytic_id: NFV4-MVA is not exists given stream_id: stream_001"}

Authorization

bearerAuth

AuthorizationBearer <token>

In: header

Path Parameters

node_num*integer

Nomor node. Gunakan 0 untuk deployment single-node.

stream_id*string

ID stream video yang akan dianalisis.

Response Body

`application/json`

curl -X DELETE "http://localhost:4004/pipeline/0/stream_001/NFV4-MVA"

{  "code": 200,  "message": "pipeline successfully deleted",  "node_num": 0,  "stream_id": "stream_001",  "analytic_id": "NFV4-MVA"}

{  "code": 404,  "message": "pipeline not found"}

Authorization

bearerAuth

AuthorizationBearer <token>

In: header

Path Parameters

node_num*integer

Nomor node. Gunakan 0 untuk deployment single-node.

stream_id*string

ID stream video yang akan dianalisis.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

object_confidence_threshold?number

Threshold confidence global untuk deteksi kendaraan, dipakai oleh sub-analitik yang tidak mengirim override sendiri.

Default0.4

Formatfloat

Range0 <= value <= 1

colordet_crop_w?number

Rasio lebar crop bounding box yang dipakai saat mengekstrak warna kendaraan (NFV4-MVAA).

Default0.8

Formatfloat

colordet_crop_h?number

Rasio tinggi crop bounding box untuk klasifikasi warna (NFV4-MVAA).

Default0.8

Formatfloat

sub_analytics?array<|||>

Konfigurasi tiap sub-analitik yang ingin diaktifkan. Setiap objek wajib memiliki name dan is_active.

Response Body

`application/json`

curl -X POST "http://localhost:4004/pipeline/0/stream_001/NFV4-MVAA" \  -H "Content-Type: application/json" \  -d '{    "object_confidence_threshold": 0.4,    "colordet_crop_w": 0.8,    "colordet_crop_h": 0.8,    "sub_analytics": [      {        "name": "counting",        "is_active": true,        "areas": [          {            "name": "Gate A",            "points": [              {                "x": 0.2,                "y": 0.5              },              {                "x": 0.8,                "y": 0.5              }            ],            "direction": "both"          }        ],        "attributes": {          "color": true,          "type": true,          "brand": false        }      },      {        "name": "roi_counting",        "is_active": false      },      {        "name": "dwelling",        "is_active": false      },      {        "name": "density",        "is_active": false      }    ]  }'

{  "code": 200,  "message": "pipeline successfully created",  "node_num": 0,  "stream_id": "stream_001",  "analytic_id": "NFV4-MVAA"}

{  "code": 400,  "message": "analytic_id=NFV4-MVAA is already exists in stream=stream_001 !"}

Authorization

bearerAuth

AuthorizationBearer <token>

In: header

Path Parameters

node_num*integer

Nomor node. Gunakan 0 untuk deployment single-node.

stream_id*string

ID stream video yang akan dianalisis.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

object_confidence_threshold?number

Threshold confidence global untuk deteksi kendaraan, dipakai oleh sub-analitik yang tidak mengirim override sendiri.

Default0.4

Formatfloat

Range0 <= value <= 1

colordet_crop_w?number

Rasio lebar crop bounding box yang dipakai saat mengekstrak warna kendaraan (NFV4-MVAA).

Default0.8

Formatfloat

colordet_crop_h?number

Rasio tinggi crop bounding box untuk klasifikasi warna (NFV4-MVAA).

Default0.8

Formatfloat

sub_analytics?array<|||>

Konfigurasi tiap sub-analitik yang ingin diaktifkan. Setiap objek wajib memiliki name dan is_active.

Response Body

`application/json`

curl -X PUT "http://localhost:4004/pipeline/0/stream_001/NFV4-MVAA" \  -H "Content-Type: application/json" \  -d '{    "sub_analytics": [      {        "name": "counting",        "is_active": true,        "attributes": {          "brand": true,          "brand_confidence_threshold": 0.4        }      }    ]  }'

{  "code": 200,  "message": "pipeline successfully updated",  "node_num": 0,  "stream_id": "stream_001",  "analytic_id": "NFV4-MVAA"}

Authorization

bearerAuth

AuthorizationBearer <token>

In: header

Path Parameters

node_num*integer

Nomor node. Gunakan 0 untuk deployment single-node.

stream_id*string

ID stream video yang akan dianalisis.

Response Body

`application/json`

curl -X GET "http://localhost:4004/pipeline/0/stream_001/NFV4-MVAA"

{  "code": 200,  "message": "configuration has been successfully retrieved from the runtime pipeline",  "data": {    "object_confidence_threshold": 0.4,    "colordet_crop_w": 0.8,    "colordet_crop_h": 0.8,    "sub_analytics": [      {        "name": "counting",        "is_active": true,        "areas": []      }    ]  }}

Authorization

bearerAuth

AuthorizationBearer <token>

In: header

Path Parameters

node_num*integer

Nomor node. Gunakan 0 untuk deployment single-node.

stream_id*string

ID stream video yang akan dianalisis.

Response Body

`application/json`

curl -X DELETE "http://localhost:4004/pipeline/0/stream_001/NFV4-MVAA"

{  "code": 200,  "message": "pipeline successfully deleted",  "node_num": 0,  "stream_id": "stream_001",  "analytic_id": "NFV4-MVAA"}

Event Streaming (WebSocket)

Visionaire4 mengirim setiap event hasil deteksi/inferensi melalui WebSocket. Untuk berlangganan event yang dihasilkan oleh pipeline Vehicle Analytics pada stream tertentu, buka koneksi WebSocket ke endpoint berikut:

ws://<host>:4004/event_channel/{node_num}/{stream_id}/{analytic_id}

Segmen terakhir harus sama dengan analytic_id pipeline yang dibuat (mis. NFV4-MVA, NFV4-MVAA, NFV4-VC). Setelah koneksi terbuka, server langsung mendorong (push) setiap event ke client tanpa perlu handshake atau pesan subscribe. Tutup koneksi untuk berhenti menerima event.

Parameter Path

Parameter	Tipe	Deskripsi
`node_num`	integer	Nomor node tempat stream berjalan (`0` = master)
`stream_id`	string	ID stream yang akan dipantau

Query Parameter (Opsional)

Parameter	Tipe	Deskripsi
`logic`	string	Filter event berdasarkan nama logic (`counting`, `roi_counting`, `dwelling`, `density`, `speed`) yang aktif pada pipeline multi-logic. Tanpa parameter ini, semua event dari analitik akan dikirim.

Contoh Koneksi

const ws = new WebSocket(
  'ws://localhost:4004/event_channel/0/<stream_id>/NFV4-MVA'
);

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_id>/NFV4-MVA"
    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())

Filter Berdasarkan Logic

ws://<host>:4004/event_channel/{node_num}/{stream_id}/NFV4-MVA?logic=counting

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

Dua cara melihat overlay visualisasi (garis counting, zona ROI, bounding box kendaraan) secara langsung, tanpa lewat WebSocket:

Halaman viewer HTML — buka GET /visual/{node_num}/{stream_id}/{analytic_id} langsung di browser. Endpoint ini mengembalikan halaman HTML bawaan yang merender overlay secara live; bukan gambar/stream yang bisa langsung ditanam lewat <img src>.
MJPEG stream — GET /mjpeg/{node_num}/{stream_id}/{analytic_id} mengembalikan multipart MJPEG stream yang bisa ditanam langsung sebagai <img src> atau dibuka di browser/media player.

# Buka di browser atau media player
http://localhost:4004/mjpeg/0/stream_001/NFV4-MVA?fps=10&height=480&jq=70

<img src="http://localhost:4004/mjpeg/0/stream_001/NFV4-MVA?fps=10&height=360"
     alt="Vehicle Analytics Preview" />

Query Parameter	Default	Keterangan
`fps`	`0`	Frame rate output MJPEG. `0` berarti tidak dibatasi eksplisit oleh parameter ini.
`height`	`320`	Tinggi frame output dalam piksel (lebar mengikuti aspek rasio).
`jq`	`60`	Kualitas kompresi JPEG (1–100, makin tinggi makin baik kualitasnya dan makin besar ukurannya).

GET /mjpeg/{node_num}/{stream_id} (tanpa analytic_id) juga tersedia untuk melihat frame stream mentah tanpa overlay analitik tertentu.

Path /pipeline/{node_num}/{stream_id}/{analytic_id}/mjpeg dan /pipeline/.../snapshot yang muncul pada dokumentasi versi sebelumnya tidak ada di server — gunakan /mjpeg/{node_num}/{stream_id}/{analytic_id} dan /visual/{node_num}/{stream_id}/{analytic_id} di atas. Endpoint /config di bawah /pipeline/... juga tidak ada — gunakan GET/PUT langsung pada /pipeline/{node_num}/{stream_id}/{analytic_id} seperti didokumentasikan di Manajemen Pipeline.

Struktur Event

Setiap kali sebuah kendaraan memenuhi kriteria sebuah logic (melewati garis, masuk/keluar zona, dwelling, interval density tercapai, atau kecepatan terukur), pipeline memancarkan satu event lewat event channel WebSocket dan menyimpannya ke database node kecuali --db-disable-event-store aktif. Semua modul analitik Visionaire memakai envelope yang sama; bagian yang spesifik Vehicle Analytics ada di pipeline_data.

{
  "timestamp": 1705314600,
  "node_num": 0,
  "stream_id": "5136c6c0916cd30c",
  "stream_name": "Gerbang Tol A",
  "stream_address": "rtsp://10.7.2.50:554/stream",
  "stream_longitude": 106.823649,
  "stream_latitude": -6.261376,
  "analytic_id": "NFV4-MVA",
  "primary_text": "car",
  "secondary_text": "in",
  "pipeline_data": {
    "event_id": "1705314600-3a1f9d4c",
    "confidence": 0.88,
    "label": "car",
    "area_name": "Gate A",
    "direction": "in",
    "tracker_id": 12,
    "group_id": 0,
    "logic": "counting",
    "attributes": {
      "vehicle": { "label": "car", "confidence": 0.88 }
    }
  },
  "image_jpeg": "<base64 JPEG>"
}

Field Envelope

Field	Tipe	Deskripsi
`timestamp`	int	Waktu event dalam epoch detik (UTC).
`node_num`	int	Nomor node tempat pipeline berjalan.
`stream_id`	string	Identifier stream sumber.
`stream_name`	string	Nama stream.
`stream_address`	string	URL sumber video stream.
`stream_longitude`, `stream_latitude`	float	Posisi kamera.
`analytic_id`	string	Varian pipeline yang memancarkan event — salah satu dari 8 ID pada Varian & Cara Kerja.
`primary_text`	string	Label kendaraan (`car`/`motorcycle`/`bus`/`truck`) untuk sebagian besar logic; nama zona untuk `density`; `object_id` hasil pencocokan untuk `NFV4-VCAT`; label gabungan dua objek untuk `NFV4-VAS`.
`secondary_text`	string	Arah crossing, durasi dwelling, jumlah kendaraan, atau kecepatan — tergantung logic.
`pipeline_data`	object	Detail hasil — struktur berbeda per logic, lihat tabel di bawah.
`image_jpeg`	string (base64)	Crop JPEG kendaraan (atau frame snapshot untuk `density`).

pipeline_data.event_id berformat <timestamp>-<hash8>, dibuat dari hash beberapa field event. Tidak ada event_id di level atas (top-level) dan tidak ada timestamp_ms — hanya timestamp dalam detik.

`pipeline_data` — `counting` / `roi_counting`

Field	Tipe	Deskripsi
`event_id`	string	ID unik event.
`confidence`	float	Confidence deteksi kendaraan.
`label`	string	`car`, `motorcycle`, `bus`, atau `truck`.
`area_name`	string	Nama garis (`counting`) atau zona (`roi_counting`) yang dilewati.
`direction`	string	`in` atau `out`.
`tracker_id`	int	ID tracking untuk asosiasi antar frame.
`group_id`	int	ID grup jika `enable_group_tracking` aktif; `0` jika tidak.
`logic`	string	`"counting"` atau `"roi_counting"`.
`attributes.vehicle`	object	`{label, confidence}` — selalu ada.
`attributes.color`/`type`/`brand`	object	`{label, confidence}` — hanya pada `NFV4-MVAA`, dan hanya jika atributnya aktif serta label bukan `motorcycle` (untuk `type`/`brand`).

`pipeline_data` — `dwelling`

Field	Tipe	Deskripsi
`event_id`	string	ID unik event.
`confidence`	float	Confidence deteksi kendaraan.
`label`	string	Label kendaraan.
`area_name`	string	Nama zona dwelling.
`time_in`	int	Epoch ms saat kendaraan mulai dwelling.
`duration`	int	Durasi dwelling (detik).
`tracker_id`	int	ID tracking.
`group_id`	int	ID grup jika group tracking aktif.
`logic`	string	`"dwelling"`.
`attributes`	object	Berisi `vehicle`, `from`, `to` (`from`/`to` selalu kosong pada varian multi-logic — field warisan dari template internal).
`time_out`	int \| null	Epoch ms saat kendaraan keluar zona; `null` jika belum keluar (dump akibat alert/time-over).
`time_alert`	int \| null	Epoch ms saat alert dini dipicu (`dwelling_treshold_alert_sec`); `null` jika tidak ada alert.

`pipeline_data` — `density`

Field	Tipe	Deskripsi
`interval`	int	Interval pelaporan (detik).
`area`	string	Nama zona density.
`estimation`	int	Estimasi jumlah kendaraan dalam zona.
`logic`	string	`"density"`.
`detected`	array	Rincian per kendaraan: `tracker_id`, `label`, `confidence`, `bbox`, dan `attributes` (jika `dump_attributes: true` dan `NFV4-MVAA`).

`pipeline_data` — `speed` (`NFV4-MVAS` saja)

Field	Tipe	Deskripsi
`event_id`	string	ID unik event.
`confidence`	float	Confidence deteksi kendaraan.
`label`	string	Label kendaraan.
`area_name`	string	Nama zona speed (jika dikonfigurasi).
`speed_kmh`	float	Estimasi kecepatan kendaraan (km/jam). Tidak akurat tanpa 4 titik `plane_calibration.points` — lihat Keterbatasan.
`tracker_id`	int	ID tracking.
`group_id`	int	ID grup.
`logic`	string	`"speed"`.
`attributes.vehicle`	object	`{label, confidence}` — selalu ada. `color`/`type`/`brand` tidak muncul untuk `NFV4-MVAS` (lihat Keterbatasan).

`pipeline_data` — `NFV4-VAS` (aerial overlap)

Field	Tipe	Deskripsi
`duration`	float	Durasi (detik) kedua objek tumpang-tindih.
`time_start`	float	Epoch detik saat overlap mulai.
`time_end`	float	Epoch detik saat overlap berakhir.
`object`	array[2]	Dua objek yang tumpang-tindih, masing-masing `{label, confidence, bbox}` (`bbox`: `[left, top, width, height]` dalam piksel).

`pipeline_data` — `NFV4-VCAT` (vehicle matching)

Field	Tipe	Deskripsi
`confidence`	float	Similarity terbaik terhadap kandidat di database embedding (0–1).
`label`	string	`object_id` kandidat dengan similarity tertinggi.
`variation`	string	ID variasi enrollment yang cocok.
`area_name`	string	Nama garis yang dilewati.
`direction`	string	Arah crossing.
`tracker_id`	int	ID tracking.

API Reference — Vehicle Analytics

← Kembali ke Vehicle Analytics

Varian & Cara Kerja

Konfigurasi

200application/json

400application/json

404application/json

200application/json

400application/json

404application/json

200application/json

400application/json

200application/json

404application/json

200application/json

400application/json

200application/json

200application/json

200application/json

On this page

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`