Update ALPR developer guide

This commit is contained in:
2026-05-05 04:41:33 +10:00
parent d03c2c1138
commit b0002b4a4b
2 changed files with 217 additions and 91 deletions
+111 -10
View File
@@ -371,23 +371,124 @@ def build_story():
# ── 1.8 Pipeline integration ─────────────────────────────────────────
s.append(PageBreak())
s.append(p("1.8 Pipeline integration", H2))
s.append(p("<b>shouldUseALPRChecker</b> &mdash; full-frame vs pipeline auto-detect:"))
s.append(p(
"<b>Pipeline mode always bypasses the ALPRChecker, regardless of "
"how <font face='Courier'>_enableALPRChecker</font> is set.</b> Two "
"independent mechanisms enforce this:"
))
s.append(p(
"<b>Mechanism 1 &mdash; dedicated batch entry point (hard bypass).</b> "
"<font face='Courier'>ANSALPR_RunInferencesBatch_LV</font> / "
"<font face='Courier'>_LV_V2</font> "
"(<font face='Courier'>dllmain.cpp:836, 1405</font>) routes through "
"<font face='Courier'>engine-&gt;RunInferencesBatch(...)</font>. The "
"implementations at "
"<font face='Courier'>ANSALPR_OD::RunInferencesBatch</font> "
"(line 2637) and "
"<font face='Courier'>ANSALPR_OCR::RunInferencesBatch</font> "
"(line 1863) contain <b>zero references</b> to the checker &mdash; "
"no <font face='Courier'>shouldUseALPRChecker</font>, no "
"<font face='Courier'>checkPlateByTrackId</font>, no "
"<font face='Courier'>tryReuseLockedText</font>, no "
"<font face='Courier'>ensureUniquePlateText</font>. The flag is "
"never read on this path. Header contract at "
"<font face='Courier'>ANSLPR.h:163-178</font>: "
"&ldquo;Tracker, voting, spatial dedup, and per-camera "
"accumulating state are all bypassed.&rdquo;"
))
s.append(p(
"<b>Mechanism 2 &mdash; auto-detect floors on the regular "
"<font face='Courier'>RunInference</font> path.</b> "
"<font face='Courier'>shouldUseALPRChecker</font> applies a chain "
"of gates; the last two reject pipeline crops even when the "
"flag is on:"
))
s.append(code_block([
"if not _enableALPRChecker.load(relaxed): return false // master switch",
"if imageSize.width < MIN_FULLFRAME_WIDTH: return false // crop -> bypass",
"if !_enableTrackerVoting: return false // OD master (1)",
"if !_enableALPRChecker.load(relaxed): return false // user flag (2)",
"if imageSize.width < MIN_FULLFRAME_WIDTH: return false // HARD FLOOR (3)",
" // = 1000 px",
"tracker = _imageSizeTrackers[cameraId]",
"if imageSize == tracker.lastSize:",
" if ++tracker.consistentCount >= CONFIRM_THRESHOLD:",
"if imageSize == tracker.lastSize: // CONSISTENCY (4)",
" if ++tracker.consistentCount >= CONFIRM_THRESHOLD: // = 5 frames",
" tracker.detectedFullFrame = true",
"else:",
" tracker.lastSize = imageSize; consistentCount = 1",
" tracker.detectedFullFrame = false",
" tracker.lastSize = imageSize; consistentCount = 1 // reset on any",
" tracker.detectedFullFrame = false // mismatch",
"return tracker.detectedFullFrame",
]))
s.append(p(
"Real video gives pixel-identical frame sizes; pre-cropped calls "
"vary by a few pixels. Full-frame mode engages only after consistent "
"frames are seen, so voting kicks in once we're certain.",
"Gates (3) and (4) make the bypass automatic for cropped inputs:"
))
s.append(make_table(
["Pipeline indicator", "Effect", "Independent of flag?"],
[
["<font face='Courier'>width &lt; 1000 px</font> "
"(<font face='Courier'>MIN_FULLFRAME_WIDTH</font>)",
"Returns <font face='Courier'>false</font> immediately, "
"before the auto-detect state machine runs.",
"<b>Yes</b> &mdash; rejects all small crops unconditionally "
"after the flag check passes."],
["Frame size varies between calls",
"<font face='Courier'>consistentCount</font> resets to 1 on "
"every mismatch; <font face='Courier'>detectedFullFrame</font> "
"stays <font face='Courier'>false</font>. Pre-cropped vehicle "
"ROIs (e.g. 496&times;453, 497&times;455, &hellip;) never "
"accumulate consistency.",
"<b>Yes</b> &mdash; the consistency requirement is independent "
"of the user flag."],
],
col_widths=[60*mm, 70*mm, 38*mm],
))
s.append(Spacer(1, 4))
s.append(p(
"<b>Practical guarantee.</b> Even if a caller sets "
"<font face='Courier'>SetALPRCheckerEnabled(true)</font> and feeds "
"pipeline crops, voting stays off per camera because the auto-detect "
"never flips <font face='Courier'>detectedFullFrame</font> to true. "
"Mixing full-frame and pipeline calls on different cameras works "
"cleanly: the per-camera <font face='Courier'>_imageSizeTrackers</font> "
"entry tracks each camera's mode independently.",
NOTE,
))
s.append(p("Caller path &times; flag matrix", H3))
s.append(make_table(
["Caller path", "Input characteristic",
"Flag = OFF", "Flag = ON"],
[
["<font face='Courier'>RunInferencesBatch</font> "
"(pipeline batch, LV/V2)",
"any size, any consistency",
"<b>bypassed</b> (hard)",
"<b>bypassed</b> (hard, flag never read)"],
["<font face='Courier'>RunInference</font>",
"full video frames "
"(&ge; 1000 px, consistent size)",
"bypassed",
"active after 5 consistent frames"],
["<font face='Courier'>RunInference</font>",
"cropped vehicle ROI "
"(&lt; 1000 px)",
"bypassed",
"<b>bypassed by MIN_FULLFRAME_WIDTH floor</b>"],
["<font face='Courier'>RunInference</font>",
"varying-size crops "
"(&ge; 1000 px but inconsistent)",
"bypassed",
"<b>bypassed by consistency reset</b>"],
],
col_widths=[55*mm, 50*mm, 30*mm, 33*mm],
mono_cols={2, 3},
))
s.append(Spacer(1, 4))
s.append(p(
"In effect, the flag answers a single question: <i>&ldquo;if the "
"caller is sending real video frames from this camera, should I "
"stabilize the output?&rdquo;</i> It has no effect on pipeline / "
"cropped inputs &mdash; those are always raw OCR.",
NOTE,
))