managed-portal/managed/people_flow_project/docs/plans/2026-04-08-deepface-portable-weights-design.md

Portable DeepFace Weights Design

Goal: Make DeepFace reuse bundled project weights regardless of where the project directory is unpacked.

Problem: The current native launcher sets DEEPFACE_HOME to a project-local .deepface directory. DeepFace then appends its own .deepface/weights segment, so runtime lookup becomes PROJECT_ROOT/.deepface/.deepface/weights, which bypasses the bundled weights/deepface directory and triggers redundant downloads.

Approach Options:

1. Copy bundled weights into the current user's default ~/.deepface/weights directory before startup. This matches DeepFace's default lookup behavior and avoids hard-coded absolute paths. It works whether the project lives under /home/x/people, /home/xiaozheng/people, or any other directory.

2. Keep using DEEPFACE_HOME and reshape the project-local directory tree to match DeepFace's nested expectations. This avoids duplicating files but is more fragile and easier to break when DeepFace internals change.

Recommendation: Use option 1. Update the native setup and launcher scripts to sync weights/deepface/*.h5 into ~/.deepface/weights and stop overriding DEEPFACE_HOME.

Validation: Confirm the RTSP process starts without downloading retinaface.h5, age_model_weights.h5, or gender_model_weights.h5, and verify the launcher still works after changing only the project root path.