Enrollment

Enrollment adalah proses mendaftarkan identitas wajah ke dalam database FREMIS-N. Saat enrollment, FREMIS-N mengekstrak representasi matematis unik dari wajah dalam foto — disebut embedding — dan menyimpannya di dalam keyspace yang ditentukan agar dapat dicari di kemudian hari. Setiap face_id dapat memiliki beberapa variasi enrollment; semakin beragam variasi yang didaftarkan, semakin baik kemampuan sistem mengenali orang tersebut dalam kondisi nyata yang bervariasi.

Apa itu Enrollment di FREMIS-N

Enrollment adalah pemetaan satu-ke-satu antara sebuah identitas dan satu atau lebih vektor embedding wajah. Setiap identitas direpresentasikan oleh face_id — string bebas yang Anda tentukan (misalnya nomor karyawan, UUID, atau nama) — yang dipetakan ke embedding-embedding yang disimpan di dalam keyspace.

Saat proses enrollment berlangsung:

1. FREMIS-N menerima gambar wajah dalam format base64
2. Wajah dideteksi dan fitur uniknya diekstrak sebagai vektor fitur (embedding)
3. Vektor tersebut disimpan di database persisten dan diindeks di indeks pencarian in-memory untuk pencarian cepat
4. Sebuah variasi baru ditambahkan ke face_id yang bersangkutan

Hasil enrollment dapat digunakan langsung untuk 1:N recognition (siapa orang ini?) maupun 1:1 matching (apakah dua foto adalah orang yang sama?).

Multi-Variasi: Mengapa Beberapa Foto Meningkatkan Akurasi

Satu identitas tidak terbatas pada satu foto. FREMIS-N mendukung multi-variasi enrollment — Anda dapat mendaftarkan beberapa foto untuk face_id yang sama dengan sudut, kondisi pencahayaan, atau ekspresi yang berbeda.

Cara kerjanya: saat recognition dilakukan, FREMIS-N mencari kecocokan terhadap semua variasi yang terdaftar untuk setiap face_id. Jika salah satu variasi menghasilkan similarity di atas threshold, identitas dianggap cocok dan variasi yang paling mirip dilaporkan dalam respons.

Setiap variasi memiliki ID unik sendiri (variation ID) yang dapat dilihat via endpoint get-variations dan dapat dihapus secara individual tanpa menghapus seluruh enrollment melalui delete-enrollment-variation.

Pipeline Enrollment

Saat request enrollment tiba, FREMIS-N menjalankan serangkaian langkah secara berurutan sebelum mengembalikan respons. Memahami alur ini membantu Anda merancang integrasi yang tepat — terutama dalam hal penanganan latensi dan pemantauan sistem di bawah beban tinggi.

Penyimpanan Embedding

IQA — Image Quality Assessment

FREMIS-N menyediakan validasi kualitas gambar opsional yang disebut IQA (Image Quality Assessment). IQA memeriksa tiga dimensi kualitas sebelum embedding diekstrak:

IQA tidak aktif secara default — gambar diterima dan diproses tanpa validasi kualitas. Untuk mengaktifkannya, sertakan parameter additional_params dalam request enrollment:

{
  "image": "<base64-encoded-image>",
  "keyspace": "employees",
  "additional_params": {
    "face_id": "emp_001",
    "min_brightness": 0.4,
    "min_sharpness": 0.3,
    "min_contrast": 0.3,
    "return_iqa_result": true
  }
}

Jika gambar tidak memenuhi ambang batas yang ditentukan, FREMIS-N mengembalikan HTTP 400 dengan detail metrik kualitas aktual versus threshold yang diharapkan — sehingga aplikasi dapat memberikan feedback spesifik kepada pengguna (misalnya "gambar terlalu gelap, mohon gunakan pencahayaan yang lebih baik").

Jika return_iqa_result: true diaktifkan dan gambar lolos IQA, respons sukses juga menyertakan nilai aktual kecerahan, ketajaman, dan kontras gambar.

Bentuk Response Enrollment

Enrollment yang berhasil mengembalikan JSON dengan struktur berikut:

{
  "face_id": "emp_001",
  "variation": "1234567890123456789",
  "face_detected": [
    {"top": 0.18, "left": 0.22, "height": 0.42, "width": 0.40}
  ]
}

Embedding vs Gambar Mentah

FREMIS-N menyediakan dua jalur enrollment:

Operasi Turunan Enrollment

Setelah identitas terdaftar, FREMIS-N menyediakan serangkaian operasi untuk manajemen dan inspeksi enrollment:

Membaca & Menginspeksi

Menghapus

Membersihkan Variasi Duplikat

Endpoint get-duplicate-variations membantu mengidentifikasi identitas yang memiliki variasi enrollment yang terlalu mirip satu sama lain. Variasi duplikat dapat menurunkan efisiensi pencarian (lebih banyak data untuk dibandingkan) tanpa menambah akurasi. Gunakan hasil endpoint ini sebagai input untuk delete-enrollment-variation guna membersihkan variasi yang redundan.

Alur Enrollment Tipikal

Tips & Troubleshooting

Enrollment Ditolak — "No Face" / "Multi-face" / "Quality" / "Quota"

API enrollment mengembalikan HTTP 400 dengan salah satu pesan berikut. Penyebab dan tindakan:

Jika IQA aktif dan respons error berisi field metrik aktual (brightness/sharpness/contrast), gunakan nilai itu untuk memberikan feedback spesifik ke pengguna — misalnya "gambar terlalu gelap, gunakan pencahayaan yang lebih baik".

Enrollment Diterima tetapi Tidak Muncul di Recognition

API mengembalikan HTTP 200 dengan variation, tetapi recognition tidak menemukan identitas tersebut.

1. Tunggu 10–30 detik lalu coba ulang. Indeks pencarian in-memory di-update di akhir pipeline enrollment; pada beban tinggi, propagasi bisa tertunda beberapa detik.
2. Verifikasi face_id dan keyspace. Bandingkan request enrollment dan request recognition — keduanya harus menggunakan nilai keyspace dan face_id yang sama persis.
3. List enrollment di keyspace. Panggil GET /v1/face/keyspace/{keyspace}/enrollment dan pastikan face_id ada dalam hasil.
4. Untuk cluster, cek semua node hidup. Coordinator merutekan enrollment ke node yang memegang partisi dari face_id. Jika node target sedang down, enrollment di-antri oleh health watchdog dan baru tersedia setelah node kembali online — lihat Cluster Sharding.

Selanjutnya