API Reference — Crowd Estimation

Endpoint REST API untuk membuat, mengelola, dan memantau pipeline Crowd Estimation (NFV4-CE), beserta struktur event.

Konfigurasi

Referensi lengkap parameter areas, interval, dan confidence.

People Analytics

Tracking dan counting per orang — pasangan untuk skenario kerumunan kurang padat.

Semua endpoint pada halaman ini menggunakan basis URL dari variabel VISIONAIRE_API_URL yang dikonfigurasi pada instalasi Visionaire (default: http://localhost:4004). Autentikasi mengikuti konfigurasi deployment Visionaire Anda.

Manajemen Pipeline

Endpoint untuk membuat, memantau, memperbarui, dan menghapus pipeline Crowd Estimation. Setiap pipeline diidentifikasi oleh kombinasi node_num, stream_id, dan analytic_id (NFV4-CE). Stream tujuan harus sudah terdaftar lebih dulu lewat POST /streams/{node_num}.

Buat Pipeline

POST /pipeline/{node_num}/{stream_id}/NFV4-CE

curl -X POST http://localhost:4004/pipeline/0/crowd-area-1/NFV4-CE \
  -H "Content-Type: application/json" \
  -d '{
    "areas": [
      {
        "name": "Plaza Utama",
        "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}
        ]
      }
    ],
    "interval": 10
  }'

Respons sukses:

{
  "code": 200,
  "message": "pipeline successfully created",
  "node_num": 0,
  "stream_id": "crowd-area-1",
  "analytic_id": "NFV4-CE"
}

Jika pipeline dengan kombinasi stream_id + analytic_id yang sama sudah ada, endpoint mengembalikan status 400 beserta pesan error.

Update Konfigurasi Pipeline

PUT /pipeline/{node_num}/{stream_id}/NFV4-CE

Memperbarui parameter pipeline yang sedang berjalan tanpa perlu me-restart, menggunakan method dan path yang sama dengan pembuatan pipeline.

curl -X PUT http://localhost:4004/pipeline/0/crowd-area-1/NFV4-CE \
  -H "Content-Type: application/json" \
  -d '{
    "areas": [
      {
        "name": "Plaza Utama",
        "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}
        ]
      }
    ],
    "interval": 30
  }'

Body PUT tidak digabung (merge) secara parsial dengan konfigurasi lama. Selalu sertakan seluruh array areas yang ingin dipertahankan — jika areas tidak disertakan, pipeline kembali memakai ROI default tunggal yang mencakup seluruh frame. Lihat Konfigurasi untuk format lengkap areas, interval, dan confidence.

Baca Konfigurasi Pipeline

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

curl http://localhost:4004/config/pipeline/NFV4-CE/

{
  "code": 200,
  "config": {
    "areas": {},
    "env": {},
    "args": {},
    "interval": 10
  }
}

Status Pipeline

GET /pipeline/{node_num}/{stream_id}/NFV4-CE

curl http://localhost:4004/pipeline/0/crowd-area-1/NFV4-CE

Hapus Pipeline

DELETE /pipeline/{node_num}/{stream_id}/NFV4-CE

curl -X DELETE http://localhost:4004/pipeline/0/crowd-area-1/NFV4-CE

{
  "code": 200,
  "message": "pipeline successfully deleted",
  "node_num": 0,
  "stream_id": "crowd-area-1",
  "analytic_id": "NFV4-CE"
}

Event Streaming (WebSocket)

Visionaire mengirim setiap event hasil estimasi melalui WebSocket. Setelah koneksi terbuka, server langsung mendorong (push) setiap event tanpa perlu handshake atau pesan subscribe. Tutup koneksi untuk berhenti menerima event.

ws://<host>:4004/event_channel/{node_num}/{stream_id}/NFV4-CE

const ws = new WebSocket(
  'ws://localhost:4004/event_channel/0/crowd-area-1/NFV4-CE'
);

ws.onmessage = (msg) => {
  const event = JSON.parse(msg.data);
  const { area, estimation } = event.pipeline_data;
  console.log(`${area}: ${estimation} orang`);
};

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/crowd-area-1/NFV4-CE"
    async with websockets.connect(url) as ws:
        async for msg in ws:
            event = json.loads(msg)
            data = event["pipeline_data"]
            print(f"{data['area']}: {data['estimation']} orang")

asyncio.run(listen())

wscat -c ws://localhost:4004/event_channel/0/crowd-area-1/NFV4-CE

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)
`WS /event_channel/{node_num}/{stream_id}/{analytic_id}`	Event dari satu pipeline spesifik — pola yang dipakai pada contoh di atas

Visualisasi

Dua cara melihat overlay visualisasi (outline ROI, titik kepadatan, label estimasi) secara langsung:

Halaman viewer HTML — buka GET /visual/{node_num}/{stream_id}/NFV4-CE 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}/NFV4-CE 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/crowd-area-1/NFV4-CE?fps=10&height=480&jq=70

<img src="http://localhost:4004/mjpeg/0/crowd-area-1/NFV4-CE?fps=10&height=360"
     alt="Crowd Estimation 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.

Modul Terkait

People Analytics

Tracking individu, line-crossing counting, dwelling, dan atribut demografis untuk kerumunan kecil hingga sedang.

Face Recognition

Deteksi dan pengenalan wajah real-time dengan database identitas (NFV4-FR, NFV4-FRA, NFV4-LFR).

Struktur Event

Pipeline menerbitkan satu event per ROI setiap interval detik. Event dikirim melalui event channel WebSocket dan disimpan ke database node kecuali --db-disable-event-store aktif.

Semua modul analitik Visionaire memakai envelope yang sama; bagian yang spesifik Crowd Estimation ada di pipeline_data.

{
  "timestamp": 1748996200,
  "node_num": 0,
  "stream_id": "crowd-area-1",
  "stream_name": "Plaza Utama Kamera 1",
  "stream_address": "rtsp://10.7.2.60:554/stream",
  "stream_longitude": 106.823649,
  "stream_latitude": -6.261376,
  "analytic_id": "NFV4-CE",
  "primary_text": "23",
  "secondary_text": "Plaza Utama",
  "pipeline_data": {
    "event_id": "1748996200-1a2b3c4d",
    "area": "Plaza Utama",
    "estimation": 23,
    "history_min": 18,
    "history_max": 31,
    "interval": 10
  },
  "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	Selalu `"NFV4-CE"` untuk pipeline ini.
`primary_text`	string	Label estimasi yang sama dengan yang digambar pada overlay — angka tunggal (mis. `"23"`) jika nilai minimum dan maksimum pada interval sama, atau rentang `"min-max"` (mis. `"18-31"`) jika berbeda.
`secondary_text`	string	Nama ROI area, sama dengan `pipeline_data.area`.
`pipeline_data`	object	Detail estimasi — lihat tabel berikutnya.
`image_jpeg`	string (base64)	Crop JPEG frame pada area sekitar ROI saat event diterbitkan.

Field `pipeline_data`

Field	Tipe	Deskripsi
`event_id`	string	ID unik event berformat `<timestamp>-<hash8>`.
`area`	string	Nama ROI area sesuai `name` yang didefinisikan dalam `areas`.
`estimation`	integer	Estimasi rata-rata jumlah orang dalam ROI ini selama interval terakhir.
`history_min`	integer	Estimasi minimum yang tercatat pada ROI ini selama interval terakhir.
`history_max`	integer	Estimasi maksimum yang tercatat pada ROI ini selama interval terakhir.
`interval`	integer	Durasi interval (dalam frame, praktis ≈ detik karena pipeline berjalan 1 FPS) yang aktif saat event ini diterbitkan.

Bagi integrator: gunakan history_min/history_max bersama estimation untuk menilai stabilitas angka pada satu interval — lonjakan besar antara keduanya sering menandakan mode deteksi pelengkap kepadatan rendah baru saja menyala/mati. Lihat Troubleshooting.

Contoh Event

{
  "analytic_id": "NFV4-CE",
  "stream_id": "crowd-area-1",
  "node_num": 0,
  "timestamp": 1748996200,
  "primary_text": "23",
  "secondary_text": "Plaza Utama",
  "pipeline_data": {
    "area": "Plaza Utama",
    "estimation": 23,
    "history_min": 18,
    "history_max": 31,
    "interval": 10
  }
}

{
  "analytic_id": "NFV4-CE",
  "stream_id": "crowd-area-1",
  "node_num": 0,
  "timestamp": 1748997000,
  "primary_text": "290-412",
  "secondary_text": "Plaza Utama",
  "pipeline_data": {
    "area": "Plaza Utama",
    "estimation": 347,
    "history_min": 290,
    "history_max": 412,
    "interval": 30
  }
}

API Reference — Crowd Estimation

← Kembali ke Crowd Estimation

Konfigurasi

People Analytics

Manajemen Pipeline

Buat Pipeline

Update Konfigurasi Pipeline

Baca Konfigurasi Pipeline

Status Pipeline

Hapus Pipeline

Event Streaming (WebSocket)

Endpoint Channel Lainnya

Visualisasi

Modul Terkait

People Analytics

Face Recognition

Struktur Event

Field Envelope

Field `pipeline_data`

Contoh Event

On this page