From fda0f6f86fbeb5192d0c5bf0e67f3f537ff0752f Mon Sep 17 00:00:00 2001 From: Tuan Nghia Nguyen Date: Fri, 21 Aug 2026 11:36:22 +1000 Subject: [PATCH] ANSFR: name the real cause when enrollment cannot compute embeddings MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Enrolling a face while the recognizer engine is down used to store the user row and silently drop the embedding: InsertUser is a pure DB write, Feature() returns empty when uninitialized, and InsertFace's size check misreported that as "Invalid embedding generated" — blaming the face. The result surfaces hours later as every match returning Unknown/2.0 with nothing in the log saying why (seen on the A400: 45 users, zero embeddings). - ANSFRBase gains a public IsInitialized() accessor (flag existed but was protected). - InsertFace / InsertMultipleFaces gate on it before computing the embedding and log the true cause: recognizer not initialized, face NOT enrolled, fix engine errors then re-enroll. - The residual invalid-embedding message now reports actual vs expected size and the remaining causes (unusable crop / recognizer reloading). - Reload() warns when the database has users but zero embeddings — the one line that identifies stale half-enrolled databases at startup. Co-Authored-By: Claude Opus 4.8 --- modules/ANSFR/ANSFR.cpp | 45 +++++++++++++++++++++++++-- modules/ANSODEngine/ANSEngineCommon.h | 5 +++ 2 files changed, 47 insertions(+), 3 deletions(-) diff --git a/modules/ANSFR/ANSFR.cpp b/modules/ANSFR/ANSFR.cpp index e603ada..1a9e5ce 100644 --- a/modules/ANSFR/ANSFR.cpp +++ b/modules/ANSFR/ANSFR.cpp @@ -634,6 +634,19 @@ namespace ANSCENTER { "Built new index with " + std::to_string(newFaissIndex->ntotal) + " embeddings, " + std::to_string(newUserDict.size()) + " users", LogLevel::Info); + // Users without a single embedding cannot ever match — every face + // comes back Unknown/2.0 and nothing else in the log says why. The + // usual cause: faces were enrolled while the recognizer engine + // could not load (InsertFace stores the user but no embedding). + if (newFaissIndex->ntotal == 0 && !newUserDict.empty()) { + LogThreadSafe("ANSFacialRecognition::Reload", + "Face database has " + std::to_string(newUserDict.size()) + + " users but ZERO embeddings — all matches will return Unknown. " + "Faces were likely enrolled while the recognizer engine was " + "failing to load (check earlier engine errors). Re-enroll the " + "users' faces once the engine loads.", LogLevel::Warn); + } + // ============================================================ // PHASE 2: Atomic swap (brief exclusive lock ~microseconds) // Inference is blocked only during this swap. @@ -1353,6 +1366,17 @@ namespace ANSCENTER { // Get largest face (CPU operation) Object faceObject = GetLargestObject(detectedFaces); + // The recognizer must be up before we can compute an embedding. + // Feature() returns empty when uninitialized, which the size check + // below would misreport as a bad face — name the real cause here. + if (!_recognizer || !_recognizer->IsInitialized()) { + LogThreadSafe("ANSFacialRecognition::InsertFace", + "Cannot enroll face for user ID " + std::to_string(userId) + + ": recognizer is NOT initialized (engine failed to load?). " + "No embedding stored — fix the engine errors, then re-enroll."); + return 0; + } + // LOCK ONLY DURING RECOGNITION (shared recognizer) std::vector embedding; { @@ -1363,8 +1387,10 @@ namespace ANSCENTER { // Validate embedding if (embedding.empty() || embedding.size() != _config._recOutputDim) { LogThreadSafe("ANSFacialRecognition::InsertFace", - "Invalid embedding generated for user ID " + std::to_string(userId) + - " (size: " + std::to_string(embedding.size()) + ")"); + "Invalid embedding for user ID " + std::to_string(userId) + + " (size: " + std::to_string(embedding.size()) + ", expected " + + std::to_string(_config._recOutputDim) + ") — face crop unusable " + "or recognizer busy/reloading. Face NOT enrolled."); return 0; } @@ -1461,6 +1487,16 @@ namespace ANSCENTER { // Get largest face Object faceObject = GetLargestObject(detectedFaces); + // Same readiness gate as InsertFace — name the real cause instead + // of letting the size check blame the face crop. + if (!_recognizer || !_recognizer->IsInitialized()) { + LogThreadSafe("ANSFacialRecognition::InsertMultipleFaces", + "Cannot enroll face for user ID " + std::to_string(userId) + + ": recognizer is NOT initialized (engine failed to load?). " + "No embedding stored — fix the engine errors, then re-enroll."); + return faceIds; + } + // LOCK ONLY DURING RECOGNITION (shared recognizer) std::vector embedding; { @@ -1470,7 +1506,10 @@ namespace ANSCENTER { if (embedding.empty() || embedding.size() != _config._recOutputDim) { LogThreadSafe("ANSFacialRecognition::InsertMultipleFaces", - "Invalid embedding generated for user ID " + std::to_string(userId)); + "Invalid embedding for user ID " + std::to_string(userId) + + " (size: " + std::to_string(embedding.size()) + ", expected " + + std::to_string(_config._recOutputDim) + ") — face crop unusable " + "or recognizer busy/reloading. Face NOT enrolled."); return faceIds; } diff --git a/modules/ANSODEngine/ANSEngineCommon.h b/modules/ANSODEngine/ANSEngineCommon.h index 8358658..99ccf2f 100644 --- a/modules/ANSODEngine/ANSEngineCommon.h +++ b/modules/ANSODEngine/ANSEngineCommon.h @@ -754,6 +754,11 @@ namespace ANSCENTER virtual void AddEmbedding(const std::string& className, const std::vector& embedding) =0; virtual bool Destroy()=0; virtual void SetMaxSlotsPerGpu(int n) {} // override in TRT-based subclasses + // True once Initialize() fully succeeded (license + model + engine). + // Callers that compute embeddings (enrollment) must check this first: + // Feature() returns an empty vector when uninitialized, which is + // indistinguishable from a bad face crop at the call site. + bool IsInitialized() const { return _isInitialized; } ~ANSFRBase(); // Utility functions