Nodeflux Central
PPE Analytics

API Reference — PPE Analytics

Endpoint REST API untuk membuat, mengelola, dan memantau pipeline PPE Analytics (NFV4-PPE).

← Kembali ke PPE Analytics

Penjelasan kemampuan, cara kerja, konfigurasi, dan best practice PPE Analytics.

People Analytics

Counting, dwelling, density, dan atribut demografis untuk orang.

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. Lihat Developer Guide untuk panduan lebih lanjut.

Manajemen Pipeline

Endpoint untuk membuat, memantau, dan menghapus pipeline PPE Analytics. Setiap pipeline diidentifikasi oleh kombinasi node_num, stream_id, dan analytic_id (NFV4-PPE).

Buat Pipeline PPE

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

Membuat pipeline PPE Analytics baru pada stream yang ditentukan.

Parameter Path

ParameterTipeDeskripsi
node_numintegerNomor node tempat pipeline akan berjalan (0 = master)
stream_idstringID stream yang akan dianalisis

Contoh Request

curl -X POST "http://localhost:4004/pipeline/0/stream_001/NFV4-PPE" \
  -H "Content-Type: application/json" \
  -d '{
    "config": {
      "object_confidence_threshold": 0.53,
      "colordet_crop_w": 0.4,
      "colordet_crop_h": 0.4,
      "head_protection_confidence_threshold": 0.7,
      "helmet_color_confidence_threshold": 0.5,
      "safety_glasses_confidence_threshold": 0.5,
      "face_shield_confidence_threshold": 0.5,
      "face_mask_confidence_threshold": 0.5,
      "gloves_confidence_threshold": 0.5,
      "safety_harness_confidence_threshold": 0.7,
      "protective_clothing_confidence_threshold": 0.5,
      "protective_clothing_color_confidence_threshold": 0.5,
      "footwear_type_confidence_threshold": 0.5,
      "work_context_confidence_threshold": 0.5
    },
    "logics": [
      {
        "type": "counting",
        "is_active": true,
        "dumping_sampling_time": 500,
        "dump_ignore_iou_threshold": 0.8,
        "enable_group_tracking": false,
        "minimum_tracking_height": 0.05,
        "maximum_tracking_objects": 30,
        "enable_visual_label": false,
        "areas": [
          {
            "name": "Site Entrance",
            "coordinates": [[0, 540], [1920, 540]]
          }
        ]
      },
      {
        "type": "roi_counting",
        "is_active": false
      },
      {
        "type": "dwelling",
        "is_active": false,
        "dwelling_treshold_alert_sec": 0,
        "minimum_dwelling_sec": 2,
        "idle_time_sec": 1,
        "object_intersect_threshold": 0.85,
        "minimum_object_area_size": 2000,
        "sharpness_filter_threshold": 0,
        "only_dump_exit": false
      },
      {
        "type": "density",
        "is_active": false,
        "interval": 5,
        "inside": true,
        "dump_attributes": true
      }
    ]
  }'

Update Konfigurasi Pipeline

PATCH /pipeline/{node_num}/{stream_id}/NFV4-PPE/config

Memperbarui parameter pipeline yang sedang berjalan tanpa perlu me-restart. Berguna untuk menyesuaikan threshold atau mengubah konfigurasi area secara dinamis.

Parameter Path

ParameterTipeDeskripsi
node_numintegerNomor node tempat pipeline berjalan
stream_idstringID stream yang sedang dianalisis

Contoh Request

curl -X PATCH "http://localhost:4004/pipeline/0/stream_001/NFV4-PPE/config" \
  -H "Content-Type: application/json" \
  -d '{
    "config": {
      "head_protection_confidence_threshold": 0.8,
      "safety_harness_confidence_threshold": 0.8
    }
  }'

Hapus Pipeline

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

Menghentikan dan menghapus pipeline PPE Analytics yang berjalan pada stream yang ditentukan.

Contoh Request

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

Status Pipeline

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

Mengambil status dan konfigurasi pipeline yang sedang berjalan.

Contoh Request

curl "http://localhost:4004/pipeline/0/stream_001/NFV4-PPE"

Contoh Response

{
  "analytic_id": "NFV4-PPE",
  "stream_id": "stream_001",
  "node_num": 0,
  "status": "running",
  "config": {
    "object_confidence_threshold": 0.53,
    "head_protection_confidence_threshold": 0.7,
    "safety_harness_confidence_threshold": 0.7
  }
}

Parameter Konfigurasi

Parameter Global

ParameterDeskripsiDefault
object_confidence_thresholdConfidence minimum untuk deteksi orang0.53
colordet_crop_wRasio lebar crop untuk klasifikasi atribut warna0.4
colordet_crop_hRasio tinggi crop untuk klasifikasi atribut warna0.4

Parameter Counting Logic

ParameterDeskripsiDefault
dumping_sampling_timeInterval agregasi event saat orang melewati garis (ms)500
dump_ignore_iou_thresholdThreshold IoU untuk deduplication crossing0.8
enable_group_trackingAktifkan group/crowd trackingfalse
minimum_tracking_heightTinggi minimum bbox (rasio terhadap frame)0.05
maximum_tracking_objectsJumlah maksimum objek yang di-track30
enable_visual_labelTampilkan label pada visualisasifalse

Parameter Dwelling Logic

ParameterDeskripsiDefault
dwelling_treshold_alert_secDurasi (detik) sebelum alert dikirim (0 = nonaktif)0
minimum_dwelling_secDurasi minimum dwelling untuk generate event2
idle_time_secGrace period setelah keluar ROI sebelum timer direset1
object_intersect_thresholdThreshold interseksi orang dengan ROI0.85
minimum_object_area_sizeArea minimum bbox dalam piksel²2000
sharpness_filter_thresholdThreshold sharpness untuk dump dwelling0
only_dump_exitHanya dump saat orang keluar ROIfalse

Penulisan dwelling_treshold_alert_sec mengikuti kunci konfigurasi yang diterima oleh source code (typo treshold adalah disengaja sesuai source).

Parameter Density Logic

ParameterDeskripsiDefault
intervalInterval pelaporan kepadatan (detik)5
insideHitung orang di dalam ROI (true) atau di luar (false)true
dump_attributesSertakan atribut PPE per orang dalam event densitytrue

Threshold Atribut PPE

Setiap atribut PPE memiliki threshold confidence-nya sendiri. Bila confidence di bawah threshold, label atribut tersebut diset menjadi Unknown.

ParameterDeskripsiDefault
head_protection_confidence_thresholdThreshold deteksi pelindung kepala0.5
helmet_color_confidence_thresholdThreshold deteksi warna helmet0.5
safety_glasses_confidence_thresholdThreshold deteksi safety glasses0.5
face_shield_confidence_thresholdThreshold deteksi face shield0.5
face_mask_confidence_thresholdThreshold deteksi face mask0.5
gloves_confidence_thresholdThreshold deteksi gloves0.5
safety_harness_confidence_thresholdThreshold deteksi safety harness0.5
protective_clothing_confidence_thresholdThreshold deteksi protective clothing0.5
protective_clothing_color_confidence_thresholdThreshold warna protective clothing0.5
footwear_type_confidence_thresholdThreshold jenis alas kaki0.5
work_context_confidence_thresholdThreshold konteks lingkungan kerja0.5

Format Event

Setiap event memiliki struktur top-level berikut:

FieldTipeDeskripsi
analytic_idstringSelalu NFV4-PPE
stream_idstringID stream yang diproses
stream_namestringNama stream
node_numintegerNomor node yang memproses
timestampinteger (ms)Unix timestamp event (millisecond)
primary_textstringTeks utama event
secondary_textstringTeks pelengkap
image_jpegstring (base64)Cuplikan frame saat event terjadi
pipeline_dataobjectPayload utama hasil sub-analytic

Field pipeline_data

FieldTipeTersedia Pada
logicstringsemua (counting, roi_counting, dwelling, density)
labelstringcounting, roi_counting, dwelling (selalu "person")
confidencefloatcounting, roi_counting, dwelling
tracker_idintegercounting, roi_counting, dwelling
group_idintegercounting, roi_counting, dwelling
area_namestringcounting, roi_counting, dwelling
directionstringcounting, roi_counting ("in" / "out")
time_in / time_out / time_alertinteger (ms)dwelling
durationfloat (detik)dwelling
attributesobjectcounting, roi_counting, dwelling
areastringdensity (nama ROI)
estimationintegerdensity (jumlah orang dalam ROI)
intervalinteger (detik)density
detectedarraydensity (rincian per orang)
event_idstringsemua (hash unik per event)

Field attributes berisi map atribut PPE yang aktif. Setiap atribut adalah objek { "label": "...", "confidence": 0.0–1.0 }. Atribut dengan confidence di bawah threshold akan memiliki label: "Unknown".

Contoh Event

{
  "analytic_id": "NFV4-PPE",
  "stream_id": "stream_001",
  "timestamp": 1705314600000,
  "primary_text": "person",
  "secondary_text": "in",
  "pipeline_data": {
    "logic": "counting",
    "label": "person",
    "confidence": 0.86,
    "tracker_id": 5,
    "group_id": 0,
    "area_name": "Site Entrance",
    "direction": "in",
    "attributes": {
      "head_protection": { "label": "Helmet", "confidence": 0.91 },
      "helmet_color": { "label": "Yellow", "confidence": 0.83 },
      "safety_glasses": { "label": "Unknown", "confidence": 0.42 },
      "face_shield": { "label": "No Face Shield", "confidence": 0.88 },
      "face_mask": { "label": "No Face Mask", "confidence": 0.81 },
      "gloves": { "label": "Gloves", "confidence": 0.74 },
      "safety_harness": { "label": "No Safety Harness", "confidence": 0.79 },
      "protective_clothing": { "label": "Vest", "confidence": 0.87 },
      "protective_clothing_color": { "label": "Orange", "confidence": 0.84 },
      "footwear_type": { "label": "Safety Boots", "confidence": 0.71 },
      "work_context": { "label": "Construction", "confidence": 0.66 }
    },
    "event_id": "1705314600000-3a1f9d4c"
  }
}

Subscribe Event Channel (WebSocket)

WS /event_channel/{node_num}/{stream_id}/NFV4-PPE

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

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

Setelah koneksi terbuka, server akan langsung mendorong (push) setiap event ke client tanpa perlu handshake atau pesan subscribe. Tutup koneksi untuk berhenti menerima event.

Parameter Path

ParameterTipeDeskripsi
node_numintegerNomor node tempat stream berjalan (0 = master)
stream_idstringID stream yang akan dipantau

Query Parameter (Opsional)

ParameterTipeDeskripsi
logicstringFilter event berdasarkan nama logic rule yang aktif pada pipeline. Tanpa parameter ini, semua event dari analitik akan dikirim.

Contoh Koneksi

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

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-PPE"
    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 --include \
  --no-buffer \
  --header "Connection: Upgrade" \
  --header "Upgrade: websocket" \
  --header "Sec-WebSocket-Key: $(openssl rand -base64 16)" \
  --header "Sec-WebSocket-Version: 13" \
  "http://localhost:4004/event_channel/0/<stream_id>/NFV4-PPE"

Visualisasi (MJPEG)

GET /mjpeg/{node_num}/{stream_id}/NFV4-PPE

Mengambil stream MJPEG dengan overlay deteksi dari pipeline yang berjalan. Berguna untuk verifikasi konfigurasi area dan validasi hasil deteksi secara visual.

Parameter Query (Opsional)

ParameterTipeDeskripsiDefault
fpsintegerFrame rate output MJPEG15
heightintegerTinggi frame output dalam piksel480

Contoh

# Buka di browser untuk preview langsung
http://localhost:4004/mjpeg/0/stream_001/NFV4-PPE?fps=15&height=480

Modul Terkait

People Analytics

Counting, dwelling, density, dan atribut demografis (usia, gender, warna pakaian) untuk orang.

Snapshot Detection

Deteksi objek berbasis snapshot periodik tanpa pipeline video persisten.

Face Recognition

Kenali identitas wajah pekerja secara real-time dengan enrollment dan matching.

PPE Analytics

Analitik real-time untuk monitoring kepatuhan Personal Protective Equipment (PPE) — helmet, vest, gloves, masker, dan atribut keselamatan kerja lainnya.

Snapshot Detection

Event-driven detection analytics (fire, smoking, fighting, dll.) berbasis Snapshot Dispatcher Visionaire 4.

On this page

Manajemen PipelineBuat Pipeline PPEParameter PathContoh RequestUpdate Konfigurasi PipelineParameter PathContoh RequestHapus PipelineContoh RequestStatus PipelineContoh RequestContoh ResponseParameter KonfigurasiParameter GlobalParameter Counting LogicParameter Dwelling LogicParameter Density LogicThreshold Atribut PPEFormat EventField pipeline_dataContoh EventSubscribe Event Channel (WebSocket)Parameter PathQuery Parameter (Opsional)Contoh KoneksiVisualisasi (MJPEG)Parameter Query (Opsional)ContohModul Terkait