People Analytics (MPAA / MPA2)

People Analytics adalah modul analitik video real-time untuk mendeteksi orang, menghitung pergerakan, mengukur durasi tinggal, mengestimasi kepadatan, serta mengklasifikasi atribut visual seperti usia, gender, dan warna pakaian. Modul ini tersedia dalam dua varian publik: NFV4-MPAA (model atribut generasi pertama) dan NFV4-MPA2 (model atribut generasi baru dengan cakupan atribut yang jauh lebih luas).

Pilih Varian

Kedua varian memiliki kemampuan analitik dasar yang identik (counting, ROI counting, dwelling, density) dan berbagi konfigurasi inti yang sama. Perbedaan utama terletak pada model klasifikasi atribut yang digunakan.

Kapan memilih NFV4-MPAA: ketika kebutuhan atribut terbatas pada demografi dasar (usia, gender) dan informasi pakaian sederhana, dan Anda ingin tetap kompatibel dengan integrasi yang sudah dirancang untuk skema atribut versi pertama.

Kapan memilih NFV4-MPA2: ketika Anda membutuhkan atribut visual yang lebih kaya — misalnya jenis pakaian (T-shirt, Jacket, Dress), warna alas kaki, ekspresi wajah, atau deteksi barang bawaan (belonging seperti Backpack, Handbag, Handphone, Carrying child, dll.). MPA2 juga memiliki granularitas usia lebih baik (memisahkan Teen dari Adult) dan label head_covering yang lebih lengkap (termasuk Helmet untuk konteks keselamatan kerja).

Kemampuan

Atribut yang Didukung

Kedua varian memberikan setiap deteksi orang sekumpulan atribut. Bila confidence atribut di bawah threshold yang dikonfigurasi, label otomatis menjadi Unknown (untuk multi-class) atau dinegasikan menjadi No <label> (untuk binary seperti mask/glasses/gloves).

Atribut bersama (MPAA dan MPA2):

Atribut tambahan eksklusif MPA2:

Yang TIDAK Dilakukan

• Identifikasi atau pengenalan wajah — gunakan Face Recognition untuk itu
• Pelacakan orang lintas kamera (cross-camera tracking)
• Pengenalan plat kendaraan — gunakan License Plate Recognition
• Analisis kendaraan — gunakan Vehicle Analytics

Use Cases

Cara Kerja

Setiap frame video didekode dan dilewatkan ke komponen deteksi orang. Tracker kemudian melacak identitas setiap individu lintas frame menggunakan bounding box dan confidence score. Setiap deteksi dikirim ke attribute classifier yang menghasilkan nilai atribut beserta confidence-nya — model yang digunakan ditentukan oleh varian (MPAA atau MPA2).

Hasil tracking kemudian diproses secara paralel oleh empat sub-analytics: Counting (crossing garis virtual), ROI Counting (masuk/keluar polygon), Dwelling (durasi tinggal di area), dan Density (estimasi jumlah orang periodik). Event dihasilkan sesuai logic yang aktif dan dikirim melalui event bus ke sistem downstream.

Persyaratan

Kamera

Pemasangan untuk Counting:

• Sudut kamera 30–45 derajat dari horizontal — hindari top-down penuh karena mengurangi akurasi tracking
• Tinggi optimal 2,5–3,5 meter
• Pastikan seluruh lebar jalur masuk/keluar terlihat tanpa obstruksi

Pemasangan untuk Density / Crowd:

• Posisi lebih tinggi (3–5 meter) dengan sudut lebih curam untuk cakupan area lebih luas
• Hindari backlight atau sumber cahaya langsung ke lensa
• Pencahayaan minimal 100 lux di area yang dimonitor

Lingkungan

• GPU NVIDIA (TensorRT) atau Intel (OpenVINO) untuk akselerasi inferensi
• RAM minimal 2 GB per pipeline
• GPU memory: ~700 MB per pipeline (kedua varian membundel deteksi orang + classifier atribut). MPA2 menggunakan model atribut generasi baru — pantau penggunaan memori aktual saat deployment, terutama bila menjalankan banyak pipeline paralel.
• CPU: minimal 3 core per pipeline

Dependencies

• Visionaire API berjalan di port default 4004
• Stream video sudah terdaftar dan dapat diakses oleh Visionaire

Setting Up

Konfigurasi

Parameter API

Global

Counting Logic

Konfigurasi garis (field areas di dalam logic counting):

Contoh ringkas:

{
  "name": "counting",
  "is_active": true,
  "areas": [
    {
      "name": "Main Entrance",
      "points": [{"x": 0.2, "y": 0.5}, {"x": 0.8, "y": 0.5}],
      "direction": "both"
    }
  ]
}

Untuk roi_counting, dwelling, dan density, gunakan field areas berisi polygon (minimal 3 titik) dengan format points yang sama.

Dwelling Logic

Density Logic

Attribute Thresholds

Semua threshold di bawah ini berlaku untuk kedua varian dengan default 0.5. Naikkan threshold untuk hasil lebih konservatif (lebih banyak label menjadi Unknown atau dinegasikan); turunkan untuk recall lebih tinggi.

Threshold bersama (MPAA & MPA2):

Threshold tambahan eksklusif MPA2:

Output yang Dihasilkan

Setiap event memiliki struktur top-level berikut, dengan detail spesifik logic berada di field pipeline_data:

Field pipeline_data per Logic

Setiap event mewakili satu hasil dari sub-analytic — bukan array. Misalnya satu event counting berisi satu orang yang melewati garis.

Contoh Event

{
  "analytic_id": "NFV4-MPAA",
  "stream_id": "stream_001",
  "timestamp": 1705314600000,
  "primary_text": "person",
  "secondary_text": "in",
  "pipeline_data": {
    "logic": "counting",
    "label": "person",
    "confidence": 0.85,
    "tracker_id": 5,
    "area_name": "Main Entrance",
    "direction": "in",
    "attributes": {
      "person": { "label": "person", "confidence": 0.85 },
      "age": { "label": "Adult", "confidence": 0.88 },
      "gender": { "label": "Male", "confidence": 0.92 },
      "mask": { "label": "No mask", "confidence": 0.95 },
      "glasses": { "label": "No glasses", "confidence": 0.88 },
      "head_covering": { "label": "None", "confidence": 0.81 },
      "upper_color": { "label": "Blue", "confidence": 0.79 },
      "lower_color": { "label": "Black", "confidence": 0.84 }
    },
    "event_id": "1705314600000-3a1f9d4c"
  }
}

{
  "analytic_id": "NFV4-MPA2",
  "stream_id": "stream_001",
  "timestamp": 1705314600000,
  "primary_text": "person",
  "secondary_text": "in",
  "pipeline_data": {
    "logic": "counting",
    "label": "person",
    "confidence": 0.85,
    "tracker_id": 5,
    "area_name": "Main Entrance",
    "direction": "in",
    "attributes": {
      "person": { "label": "person", "confidence": 0.85 },
      "age": { "label": "Adult", "confidence": 0.88 },
      "gender": { "label": "Male", "confidence": 0.92 },
      "mask": { "label": "No mask", "confidence": 0.95 },
      "glasses": { "label": "No glasses", "confidence": 0.88 },
      "gloves": { "label": "No gloves", "confidence": 0.91 },
      "head_covering": { "label": "No head covering", "confidence": 0.83 },
      "upper_color": { "label": "Blue", "confidence": 0.79 },
      "lower_color": { "label": "Black", "confidence": 0.84 },
      "upper_cloth": { "label": "T-shirt", "confidence": 0.77 },
      "lower_cloth": { "label": "Trousers", "confidence": 0.81 },
      "body_type": { "label": "Average", "confidence": 0.74 },
      "face_expression": { "label": "Neutral", "confidence": 0.69 },
      "footwear_color": { "label": "Black", "confidence": 0.72 },
      "belonging": [
        { "label": "Backpack", "confidence": 0.82 },
        { "label": "Handphone", "confidence": 0.66 }
      ]
    },
    "event_id": "1705314600000-3a1f9d4c"
  }
}

{
  "analytic_id": "NFV4-MPAA",
  "stream_id": "stream_001",
  "timestamp": 1705314600000,
  "primary_text": "Restricted Zone",
  "secondary_text": "45.000 s",
  "pipeline_data": {
    "logic": "dwelling",
    "label": "person",
    "confidence": 0.75,
    "tracker_id": 12,
    "area_name": "Restricted Zone",
    "time_in": 1705314555000,
    "time_out": null,
    "time_alert": null,
    "duration": 45.0,
    "attributes": {
      "person": { "label": "person", "confidence": 0.75 },
      "from": { "label": "", "confidence": 0 },
      "to": { "label": "", "confidence": 0 }
    }
  }
}

{
  "analytic_id": "NFV4-MPA2",
  "stream_id": "stream_001",
  "timestamp": 1705314600000,
  "primary_text": "Lobby",
  "secondary_text": "25",
  "pipeline_data": {
    "logic": "density",
    "interval": 10,
    "area": "Lobby",
    "estimation": 25,
    "detected": [
      {
        "tracker_id": 7,
        "label": "person",
        "confidence": 0.82,
        "bbox": { "top": 150, "left": 100, "width": 80, "height": 220 }
      }
    ]
  }
}

Best Practices

Penempatan Kamera

• Gunakan sudut 30–45 derajat dari horizontal — top-down penuh menurunkan akurasi tracking
• Tinggi optimal 2,5–3,5 meter untuk counting; 3–5 meter untuk density/crowd coverage
• Pastikan coverage area tanpa blind spot dan hindari backlight atau cahaya langsung ke lensa
• Resolusi objek terkecil yang dimonitor minimal 50×100 piksel di frame

Konfigurasi Counting

• Letakkan garis 1–2 meter di dalam ruangan dari pintu untuk menghindari false count dari orang yang hanya lewat di depan
• Gunakan direction: "both" untuk pintu dua arah; pisahkan garis in/out untuk jalur searah
• Sesuaikan dumping_sampling_time dengan kecepatan jalan rata-rata di area tersebut

Konfigurasi Dwelling

• ROI harus mencakup seluruh area target — margin sedikit lebih besar lebih baik
• Set minimum_dwelling_sec sesuai definisi "loitering" untuk konteks Anda
• Gunakan idle_time_sec yang cukup agar orang yang bergerak sedikit tidak mereset timer

Akurasi Atribut

• Atribut wajah (age, gender, mask, glasses, face_expression) membutuhkan resolusi wajah minimal 50×50 piksel — kamera tidak boleh terlalu jauh
• Atribut pakaian dan body_type bekerja optimal pada bbox orang penuh (tidak ter-occlude di bawah pinggang)
• Pastikan pencahayaan frontal dan merata; hindari situasi backlit
• Filter hasil dengan attribute threshold yang sesuai konteks (mis. naikkan threshold mask untuk compliance monitoring ketat)

Limitations

• Occlusion parah: Jika lebih dari 50% tubuh tertutup (oleh orang lain atau objek), akurasi tracking menurun dan dapat menyebabkan ID tracker berganti
• Kerumunan sangat padat (>50 orang): Tracking individual menjadi tidak andal; pertimbangkan menggunakan Crowd Estimation (NFV4-CE) untuk estimasi kepadatan tinggi
• Top-down penuh (bird's eye view): Angle ini menyulitkan tracker untuk mempertahankan identity linkage; gunakan sudut miring 30–45 derajat
• Atribut dalam kondisi pencahayaan rendah: Akurasi attribute classification turun signifikan di bawah 100 lux
• Warna pakaian bermotif: Warna pattern/motif akan dideteksi sebagai warna dominan yang mungkin tidak selalu akurat
• Memilih varian: Setelah pipeline dibuat, varian tidak bisa diubah — Anda harus menghapus pipeline dan membuat ulang dengan analytic_id baru. Pilih varian sejak awal sesuai kebutuhan atribut (lihat Pilih Varian)
• Atribut MPA2 lanjutan: body_type, face_expression, dan belonging memiliki keandalan yang bervariasi tergantung sudut dan kualitas frame; selalu validasi dengan threshold yang sesuai sebelum digunakan untuk decision-making otomatis

Modul Terkait