API Reference — Face Recognition

Manajemen Pipeline

Endpoint untuk membuat dan menghapus pipeline Face Recognition pada stream video. Pipeline NFV4-FR menjalankan deteksi dan recognition standar; NFV4-FRA menambahkan analisis atribut demografis dan ekspresi wajah. Varian lain (NFV4-FRA2, NFV4-LFR, NFV4H-*) memakai endpoint dengan bentuk yang sama — ganti segmen terakhir path dengan analytic_id yang diinginkan; lihat Varian & Cara Kerja.

Endpoint yang sama juga mendukung PUT untuk mengubah parameter pipeline yang sedang berjalan tanpa restart (respons "pipeline successfully updated") dan GET untuk membaca konfigurasi aktif beserta nilai default dan preset. Body request untuk POST/PUT dijelaskan di Konfigurasi.

curl -X POST "http://localhost:4004/pipeline/0/5136c6c0916cd30c/NFV4-FR" \  -H "Content-Type: application/json" \  -d '{    "fr_primary_threshold": 0.8,    "fr_secondary_threshold": 0.4,    "mode": 0,    "similarity_threshold": 0.85,    "fr_min_face_size": 20,    "frontal_only": true,    "sampling_time_ms": 50,    "fr_timeout_dump": 1500,    "fr_sampling_size": 10,    "static_object_sensitivity": 5,    "fr_blur_filter_threshold": 3  }'

{  "analytic_id": "NFV4-FR",  "code": 200,  "message": "pipeline successfully created",  "node_num": 0,  "stream_id": "5136c6c0916cd30c"}

{  "code": 400,  "message": "Invalid request"}

{  "code": 409,  "message": "Pipeline already exists"}

{  "code": 500,  "message": "Internal server error"}

curl -X DELETE "http://localhost:4004/pipeline/0/5136c6c0916cd30c/NFV4-FR"

{  "analytic_id": "NFV4-FR",  "code": 200,  "message": "pipeline successfully deleted",  "node_num": 0,  "stream_id": "5136c6c0916cd30c"}

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

curl -X POST "http://localhost:4004/pipeline/0/5136c6c0916cd30c/NFV4-FRA" \  -H "Content-Type: application/json" \  -d '{    "mode": 1,    "similarity_threshold": 0.75,    "fr_primary_threshold": 0.7,    "frontal_only": false,    "fr_min_face_size": 20,    "fr_max_fps": 5,    "fr_sampling_size": 10,    "fr_blur_filter_threshold": 3  }'

{  "analytic_id": "NFV4-FRA",  "code": 200,  "message": "pipeline successfully created",  "node_num": 0,  "stream_id": "5136c6c0916cd30c"}

{  "code": 400,  "message": "Invalid request: missing required field 'keyspace'"}

{  "code": 400,  "message": "Invalid request: missing required field 'keyspace'"}

curl -X DELETE "http://localhost:4004/pipeline/0/5136c6c0916cd30c/NFV4-FRA"

{  "analytic_id": "NFV4-FRA",  "code": 200,  "message": "pipeline successfully deleted"}

{  "code": 400,  "message": "Invalid request: missing required field 'keyspace'"}

Enrollment & Pencarian Wajah

Operasi enrollment, recognition, dan pencarian embedding kini didokumentasikan secara penuh di section FREMIS-N. Visionaire4 meneruskan request ke service FREMIS-N — gunakan basis URL FREMIS-N (FREMIS_N_API_URL) untuk memanggil endpoint berikut secara langsung:

Event Streaming (WebSocket)

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

Pipeline NFV4-FR (face recognition standar):

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

Pipeline NFV4-FRA (face recognition + atribut demografis):

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

Segmen terakhir harus sama dengan analytic_id pipeline yang dibuat. Event NFV4-FRA/NFV4-FRA2 menyertakan field atribut di dalam pipeline_data.attributes.

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

Query Parameter (Opsional)

Format Pesan

Setiap event berbentuk JSON dengan envelope standar Visionaire dan field spesifik Face Recognition di pipeline_data. Struktur lengkapnya dijelaskan di Struktur Event di bawah.

Contoh Koneksi

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

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-FR"
    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

Jika pipeline menjalankan beberapa logic rule, Anda dapat memfilter event hanya untuk satu logic dengan menambahkan query parameter:

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

Endpoint Channel Lainnya

Untuk mendengarkan event yang lebih luas (lintas analitik atau lintas stream), gunakan endpoint berikut yang dijelaskan pada Developer Guide:

Struktur Event

Pipeline memancarkan satu event setiap kali sebuah wajah selesai diproses dan lolos semua filter. Event dikirim melalui event channel WebSocket (/event_channel/{node_num}/{stream_id}/{analytic_id}) dan disimpan ke database node kecuali --db-disable-event-store aktif. Cara berlangganan dijelaskan pada Event Streaming di atas.

Semua modul analitik Visionaire memakai envelope yang sama; bagian yang spesifik Face Recognition ada di pipeline_data.

{
  "timestamp": 1705314600,
  "node_num": 0,
  "stream_id": "5136c6c0916cd30c",
  "stream_name": "Lobby Utama",
  "stream_address": "rtsp://10.7.2.50:554/stream",
  "stream_longitude": 106.823649,
  "stream_latitude": -6.261376,
  "analytic_id": "NFV4-FR",
  "primary_text": "employee_456",
  "secondary_text": "",
  "pipeline_data": {
    "event_id": "1705314600-1a2b3c4d",
    "face_id": "employee_456",
    "similarity": 0.92,
    "status": "KNOWN",
    "track_id": 1,
    "variation": "var_1",
    "confidence_detection": 0.98,
    "detection_size": { "w": 120, "h": 150 },
    "sharpness_score": 8.5,
    "std_dev": 0.97,
    "message": "success",
    "attributes": {
      "detection": { "confidence": 0.98, "label": "face" },
      "recognition": {
        "confidence": 0.92,
        "label": "employee_456",
        "face_id": "employee_456",
        "variation": "var_1"
      }
    },
    "top_anonymous": {
      "face_id": "",
      "similarity": 0,
      "variation": "",
      "message": "",
      "new_anonymous": false
    }
  },
  "image_jpeg": "<base64 JPEG>"
}

Field Envelope

Field pipeline_data

Identitas Anonim

Saat similarity tertinggi di keyspace utama berada di bawah similarity_threshold, pipeline mencari wajah tersebut di keyspace anonim (--fr-anynomous-keyspace-name, default anonymous):

• Jika ditemukan dengan similarity di atas threshold → top_anonymous.face_id berisi ID anonim yang sudah ada, new_anonymous: false.
• Jika tidak ditemukan → wajah didaftarkan ke keyspace anonim melalui enrollment-by-embedding, dan event membawa ID anonim baru dengan new_anonymous: true.

Dengan cara ini, orang yang belum di-enroll tetap mendapat ID konsisten antar kemunculan — berguna untuk menghitung pengunjung unik atau menandai orang yang berulang kali muncul. Pada event UNKNOWN, pipeline_data.face_id juga diisi dengan ID anonim ini.

Matikan fitur ini dengan --fr-anonymous-enable=false jika Anda tidak ingin wajah tak dikenal disimpan ke FREMIS-N.

Atribut Demografis (NFV4-FRA, NFV4-FRA2)

Pada varian dengan atribut, objek attributes diperluas dengan hasil klasifikasi. Setiap atribut berbentuk { "label": "...", "confidence": 0.xx }; atribut yang confidence-nya di bawah threshold diberi label: "unknown", dan atribut yang dinonaktifkan tidak muncul.

"attributes": {
  "detection": { "confidence": 0.98, "label": "face" },
  "recognition": { "confidence": 0.92, "label": "employee_456", "face_id": "employee_456", "variation": "var_1" },
  "gender": { "label": "male", "confidence": 0.93 },
  "age": { "label": "adult", "confidence": 0.81 },
  "glasses": { "label": "no_glasses", "confidence": 0.88 },
  "mask": { "label": "no_mask", "confidence": 0.95 },
  "head_covering": { "label": "none", "confidence": 0.90 },
  "upper_color": { "label": "black", "confidence": 0.77 },
  "lower_color": { "label": "blue", "confidence": 0.71 },
  "face_expression": { "label": "Neutral", "confidence": 0.84 }
}

Varian Hybrid tidak mengisi atribut ini meskipun service atribut teregistrasi — lihat Varian & Cara Kerja.