Vision and Face Enrollment

Vision & Face Enrollment

---

How vision drives attention

1. Bridge grabs JPEG frames via ffmpeg (COMSTAR_CAMERA_SOURCE).
2. At ambient_fps / engaged_fps, posts to CodeProject.AI detection.
3. On person, runs face recognize until votes accumulate for a userid.
4. FaceRecognized → Engaged → AO session headers use that userid.

API details: Contracts — CodeProject.AI.

The kiosk does not show a camera preview. If Chrome "has no camera," that is expected.

---

Enroll a face

Enrollment is an HTTP call to CodeProject.AI. The userid you register becomes the AO session identity.

Script (preferred)

cd /opt/comstar/src   # or repo root
./scripts/enroll_face.sh <userid>

Defaults: camera /dev/video0, CPAI from env/CPAI_URL. Override with COMSTAR_CAMERA_SOURCE, CPAI_URL, COMSTAR_ENROLL_DIR.

Manual curl

curl -X POST "http://ai-server.lan:32168/v1/vision/face/register" \
  -F "userid=zlatko" \
  -F "image1=@enroll/01.jpg" \
  -F "image2=@enroll/02.jpg" \
  -F "image3=@enroll/03.jpg"

Verify:

curl -X POST "http://ai-server.lan:32168/v1/vision/face/list"
curl -X POST "http://ai-server.lan:32168/v1/vision/face/recognize" \
  -F "image=@test.jpg" -F "min_confidence=0.5"

---

Enrollment tips

Enroll from the terminal itself. Capture frames using the actual camera, at the actual distance, under the actual lighting where COMSTAR will live. Enrollment-condition mismatch is the single largest cause of flaky recognition. Good studio photos make it worse.

• Ten to twenty frames across a few sessions beats three perfect ones.
• Raise recognize_votes before you lower face_confidence.
• DeepStack-derived embeddings are adequate for a household at 1–2 m facing the camera; they degrade at oblique angles and low light.

---

Identity → session mapping

CPAI returns a biometric faceId. When directory resolve is enabled, the bridge maps comstarFaceId → FreeIPA uid / displayName (see Directory Identity).

ReachConnectionConfig(
  headers: {
    'x-agentic-user-name': resolvedUid,          // FreeIPA uid
    'x-agentic-session-id': 'comstar-$resolvedUid',
    'x-warpgate-token': token,
  },
)

Unrecognised face or directory miss (when required) → guest / restricted overlay depending on attention.stranger_mode.

Enrollment: ./scripts/enroll_face.sh <ipa-uid> verifies FreeIPA and registers comstarFaceId with CPAI.

---

Related pages

• Attention Model
• Contracts — CodeProject.AI
• Troubleshooting
• Baselines