Disable stabilized feature by default. Need ,more time to test

This commit is contained in:
2026-05-04 09:39:07 +10:00
parent fa6d95de82
commit 03a63142ec
4 changed files with 649 additions and 7 deletions
+437
View File
@@ -0,0 +1,437 @@
"""Generate the ANSODEngine Tracker / Stabilization developer-guide PDF.
Run:
python build_anscore_devguide_pdf.py
Output:
ANSODEngine_Tracker_Stabilization_Guide.pdf (next to this script)
"""
from pathlib import Path
from reportlab.lib import colors
from reportlab.lib.enums import TA_LEFT
from reportlab.lib.pagesizes import A4
from reportlab.lib.styles import ParagraphStyle, getSampleStyleSheet
from reportlab.lib.units import mm
from reportlab.platypus import (
PageBreak,
Paragraph,
SimpleDocTemplate,
Spacer,
Table,
TableStyle,
)
OUTPUT = Path(__file__).with_name("ANSODEngine_Tracker_Stabilization_Guide.pdf")
# --------------------------------------------------------------------------- #
# Styles #
# --------------------------------------------------------------------------- #
styles = getSampleStyleSheet()
H1 = ParagraphStyle(
"H1", parent=styles["Heading1"],
fontName="Helvetica-Bold", fontSize=18, leading=22,
spaceBefore=4, spaceAfter=10, textColor=colors.HexColor("#0B3D91"),
)
H2 = ParagraphStyle(
"H2", parent=styles["Heading2"],
fontName="Helvetica-Bold", fontSize=13, leading=16,
spaceBefore=14, spaceAfter=6, textColor=colors.HexColor("#0B3D91"),
)
H3 = ParagraphStyle(
"H3", parent=styles["Heading3"],
fontName="Helvetica-Bold", fontSize=11, leading=14,
spaceBefore=10, spaceAfter=4, textColor=colors.HexColor("#222222"),
)
BODY = ParagraphStyle(
"Body", parent=styles["BodyText"],
fontName="Helvetica", fontSize=9.5, leading=13,
spaceBefore=2, spaceAfter=4, alignment=TA_LEFT,
)
NOTE = ParagraphStyle(
"Note", parent=BODY,
leftIndent=10, fontSize=9, textColor=colors.HexColor("#444444"),
)
CODE = ParagraphStyle(
"Code", parent=BODY,
fontName="Courier", fontSize=8.5, leading=11,
leftIndent=8, rightIndent=8, spaceBefore=4, spaceAfter=8,
backColor=colors.HexColor("#F4F4F4"),
borderColor=colors.HexColor("#D0D0D0"), borderWidth=0.5,
borderPadding=4,
)
TABLE_HEADER = ParagraphStyle(
"TH", parent=BODY, fontName="Helvetica-Bold", fontSize=9, leading=12,
textColor=colors.white,
)
TABLE_CELL = ParagraphStyle(
"TC", parent=BODY, fontSize=9, leading=12, spaceBefore=0, spaceAfter=0,
)
TABLE_CELL_MONO = ParagraphStyle(
"TCM", parent=TABLE_CELL, fontName="Courier", fontSize=8.5,
)
# --------------------------------------------------------------------------- #
# Helpers #
# --------------------------------------------------------------------------- #
def p(text, style=BODY):
return Paragraph(text, style)
def code_block(lines):
"""Multi-line code block, preserves indentation by replacing spaces with  ."""
body = "<br/>".join(
line.replace(" ", "&nbsp;").replace("<", "&lt;").replace(">", "&gt;")
for line in lines
)
# restore tag rendering for our own tags
body = body.replace("&lt;br/&gt;", "<br/>")
return Paragraph(body, CODE)
def make_table(header, rows, col_widths=None, mono_cols=None):
"""rows: list[list[str]]. mono_cols: indices that should use monospace."""
mono_cols = mono_cols or set()
def cell(text, col_idx):
style = TABLE_CELL_MONO if col_idx in mono_cols else TABLE_CELL
return Paragraph(text, style)
data = [[Paragraph(h, TABLE_HEADER) for h in header]]
for row in rows:
data.append([cell(c, i) for i, c in enumerate(row)])
t = Table(data, colWidths=col_widths, repeatRows=1)
t.setStyle(TableStyle([
("BACKGROUND", (0, 0), (-1, 0), colors.HexColor("#0B3D91")),
("TEXTCOLOR", (0, 0), (-1, 0), colors.white),
("ALIGN", (0, 0), (-1, -1), "LEFT"),
("VALIGN", (0, 0), (-1, -1), "TOP"),
("FONTSIZE", (0, 0), (-1, -1), 9),
("BOTTOMPADDING", (0, 0), (-1, 0), 6),
("TOPPADDING", (0, 0), (-1, 0), 6),
("BOTTOMPADDING", (0, 1), (-1, -1), 4),
("TOPPADDING", (0, 1), (-1, -1), 4),
("LEFTPADDING", (0, 0), (-1, -1), 5),
("RIGHTPADDING", (0, 0), (-1, -1), 5),
("ROWBACKGROUNDS", (0, 1), (-1, -1),
[colors.white, colors.HexColor("#F4F7FB")]),
("GRID", (0, 0), (-1, -1), 0.4, colors.HexColor("#B0B7C3")),
]))
return t
# --------------------------------------------------------------------------- #
# Document content #
# --------------------------------------------------------------------------- #
def build_story():
s = []
# Title
s.append(p(
"ANSODEngine &mdash; Tracker &amp; Stabilization Developer Guide",
H1,
))
s.append(p(
"Module: <b>ANSODEngine</b> &nbsp;&middot;&nbsp; "
"Base class: <b>ANSCENTER::ANSODBase</b> &nbsp;&middot;&nbsp; "
"Affects every OD engine subclass "
"(ANSRTYOLO, ANSONNXYOLO, ANSYOLOV12RTOD, etc.)",
NOTE,
))
s.append(Spacer(1, 6))
# ── 1. Default state after model load ─────────────────────────────────
s.append(p("1. Default state after model load", H2))
s.append(p(
"Every engine derived from <b>ANSODBase</b> finishes "
"<font face='Courier'>Initialize</font> / "
"<font face='Courier'>LoadModel</font> / "
"<font face='Courier'>LoadModelFromFolder</font> "
"with these defaults:"
))
s.append(make_table(
["Feature", "Default", "Source of default"],
[
["Tracker (BYTETrack / UCMC / OCSORT)",
"<b>ON</b>",
"Loaders auto-call SetTracker(BYTETRACK, true) "
"(ANSODEngine.cpp:77, 110, 139, 174, 246, 260)"],
["Stabilization (ghost injection + EMA + hysteresis + "
"class consistency)",
"<b>OFF</b>",
"Member initializer _stabilizationEnabled = false; "
"no auto-enable"],
],
col_widths=[55*mm, 18*mm, 95*mm],
))
s.append(Spacer(1, 4))
s.append(p(
"<b>Notes.</b> Tracker assigns a <font face='Courier'>trackId</font> "
"to detections and (when stabilization is on) lets the tracker "
"predict bridging &ldquo;ghost&rdquo; boxes. "
"Stabilization is opt-in and requires the tracker. "
"It cannot run standalone.",
NOTE,
))
# ── 2. Public setters &mdash; invariant table ─────────────────────────
s.append(p("2. Public setters &mdash; invariant table", H2))
s.append(p(
"The single invariant maintained by the API: "
"<b>stabilization requires tracker</b> "
"(<font face='Courier'>stab=true &rArr; tracker=true</font>)."
))
s.append(make_table(
["Call", "_trackerEnabled", "_stabilizationEnabled", "Why"],
[
["SetTracker(type, true)",
"&rarr; true",
"unchanged",
"Tracker is independently useful. Don&rsquo;t side-effect stab."],
["SetTracker(type, false)",
"&rarr; false",
"<b>&rarr; false</b> (forced)",
"Stabilization can&rsquo;t run without tracker. Forced clear "
"keeps the flag honest."],
["SetStabilization(true, hist, miss)",
"<b>&rarr; true</b> (auto if off)",
"&rarr; true",
"Stabilization needs tracker. Auto-enables it."],
["SetStabilization(false)",
"unchanged",
"&rarr; false",
"Tracker stays usable on its own."],
["SetStabilizationParameters(json)",
"unchanged",
"unchanged",
"Tunes thresholds only; does not toggle either flag."],
["SetTrackerParameters(json)",
"unchanged",
"unchanged",
"Tunes tracker params only; no-op if tracker is off."],
],
col_widths=[55*mm, 28*mm, 32*mm, 53*mm],
mono_cols={0},
))
# ── 3. Reachable runtime states ───────────────────────────────────────
s.append(p("3. Reachable runtime states", H2))
s.append(make_table(
["_trackerEnabled", "_stabilizationEnabled", "What runs at inference"],
[
["false", "false",
"Raw detections only. No trackId. No ghosts."],
["true", "false",
"Detections + trackId assignment. <b>No ghosts, no EMA, "
"no hysteresis.</b> &nbsp;&larr; default"],
["true", "true",
"Full pipeline: tracking + ghost injection + EMA confidence + "
"hysteresis + class consistency + stale-history pruning."],
["false", "true",
"<b>Unreachable</b> &mdash; invariant prevents it."],
],
col_widths=[35*mm, 42*mm, 91*mm],
mono_cols={0, 1},
))
# ── 4. Caller recipes ─────────────────────────────────────────────────
s.append(p("4. How to opt in / out (caller recipes)", H2))
s.append(make_table(
["Goal", "Sequence"],
[
["Default (tracker only, no stabilization)",
"Nothing. Just load the model."],
["Tracker only, explicit",
"SetTracker(BYTETRACK, true)"],
["Tracker + stabilization",
"SetStabilization(true, 20, 5) &nbsp; (auto-enables tracker)"],
["Tracker + stabilization with custom thresholds",
"SetStabilization(true) then SetStabilizationParameters(json)"],
["Disable everything",
"SetTracker(BYTETRACK, false) &nbsp; (also clears stabilization)"],
["Switch tracker type without losing stabilization",
"SetTracker(UCMC, true) then SetStabilization(true) "
"if it was on"],
],
col_widths=[70*mm, 98*mm],
mono_cols={1},
))
s.append(PageBreak())
# ── 5. Stabilization parameters ──────────────────────────────────────
s.append(p("5. Stabilization parameters", H2))
s.append(p(
"Apply only when stabilization is on. "
"<font face='Courier'>SetStabilization(enabled, historySize, "
"maxMisses)</font> arguments:"
))
s.append(make_table(
["Param", "Default", "Min / clamp", "Effect"],
[
["historySize", "20", "&ge; 5",
"Frames retained in _detectionQueue per camera."],
["maxMisses", "5", "&ge; 1",
"Frames a ghost may persist before pruning. "
"History pruned at 2&times;maxMisses unseen frames."],
],
col_widths=[30*mm, 18*mm, 22*mm, 98*mm],
mono_cols={0},
))
s.append(Spacer(1, 6))
s.append(p(
"<font face='Courier'>SetStabilizationParameters(json)</font> "
"&mdash; all keys optional:",
))
s.append(make_table(
["Key", "Default", "Range", "Purpose"],
[
["hysteresis_enter", "model threshold", "float, 0 = auto",
"Confidence needed for a <i>new</i> track to appear."],
["hysteresis_keep", "0.65 &times; enter", "float, 0 = auto",
"Lower threshold to <i>keep</i> an established track visible."],
["ema_alpha", "0.30", "[0.01, 1.0]",
"EMA weight for new observations (lower = smoother)."],
["track_boost_min_frames", "10", "&ge; 1",
"Frames before a track is &ldquo;established&rdquo; and gets "
"confidence boost."],
["track_boost_amount", "0.05", "[0.0, 0.5]",
"Confidence bonus for established tracks."],
["class_consistency_frames", "5", "&ge; 1",
"Consecutive frames of a new class required before accepting "
"a class switch on an established track."],
["confidence_decay", "0.85", "[0.1, 1.0]",
"Per-miss multiplier on ghost confidence."],
["min_confidence", "0.15", "[0.0, 1.0]",
"Floor below which ghosts are dropped."],
],
col_widths=[45*mm, 28*mm, 28*mm, 67*mm],
mono_cols={0},
))
# ── 6. Performance & memory ─────────────────────────────────────────
s.append(p("6. Performance &amp; memory characteristics", H2))
s.append(make_table(
["Aspect", "Tracker only", "Tracker + Stabilization"],
[
["Per-frame CPU cost",
"BYTETrack association, ~O(N&middot;M)",
"+ EMA / hysteresis / class-consistency loop O(N) + "
"history-prune O(K)"],
["Mutex acquisitions per inference",
"1 extra inside ApplyTracking",
"2 extra (ApplyTracking + StabilizeDetections) on the "
"engine&rsquo;s _mutex"],
["Result vector size",
"= real detections",
"= real detections + ghost objects in grace window"],
["Per-camera state",
"ANSMOT instance + BYTETrack removed_stracks_ "
"(capped at 1000)",
"+ _trackHistories (pruned at unseen &gt; 2&times;maxMisses) "
"+ _detectionQueue (capped at historySize)"],
["Bounded?",
"Yes &mdash; caps in BYTETrack (kRemovedCap=1000)",
"Yes &mdash; explicit prune in StabilizeDetections Phase 3"],
],
col_widths=[50*mm, 55*mm, 63*mm],
))
# ── 7. Diagnostic logging ────────────────────────────────────────────
s.append(p("7. Diagnostic logging", H2))
s.append(p(
"Every flag transition emits a DebugView line via "
"<font face='Courier'>ANS_DBG(\"ANSOD_StabState\", &hellip;)</font>:"
))
s.append(code_block([
"[ANSOD_StabState] this=<engine_ptr> "
"SetTracker(true,type=N) tracker=0->1 stab=0 (unchanged)",
"[ANSOD_StabState] this=<engine_ptr> "
"SetTracker(false) tracker=1->0 stab=1->0",
"[ANSOD_StabState] this=<engine_ptr> "
"SetStabilization(true,hist=20,miss=5) tracker=1->1 stab=0->1",
"[ANSOD_StabState] this=<engine_ptr> "
"SetStabilization(false) tracker=1 (unchanged) stab=1->0",
]))
s.append(p(
"Capture with DebugView (or any ANSCORE log) and "
"<font face='Courier'>grep ANSOD_StabState</font> to audit which "
"engine instances run with which flags in production.",
NOTE,
))
# ── 8. Behavior change vs previous build ─────────────────────────────
s.append(p("8. Behavior change vs. previous build", H2))
s.append(p(
"For developers updating from the prior version of ANSCORE."
))
s.append(make_table(
["Behavior", "Before", "After"],
[
["SetTracker(true) side-effect on stabilization",
"Auto-set stabilization to true",
"<b>No effect on stabilization</b>"],
["SetTracker(false) side-effect on stabilization",
"None (could leave stab=true while tracker=false)",
"<b>Forced stabilization to false</b>"],
["Default after model load",
"tracker=ON, stabilization=ON",
"tracker=ON, <b>stabilization=OFF</b>"],
["SetStabilization(true) auto-enable tracker",
"Yes",
"Yes (unchanged)"],
["SetStabilization(false) side-effect on tracker",
"None",
"None (unchanged)"],
],
col_widths=[60*mm, 53*mm, 55*mm],
))
s.append(Spacer(1, 6))
s.append(p(
"<b>Migration note.</b> If your application relied on the old "
"auto-enable to get stabilization for free, add an explicit "
"<font face='Courier'>SetStabilization(true)</font> call after "
"model load. ANSLPR&rsquo;s defensive "
"<font face='Courier'>SetStabilization(false)</font> calls remain "
"correct (now redundant but harmless).",
NOTE,
))
# ── Footer / version note ────────────────────────────────────────────
s.append(Spacer(1, 14))
s.append(p(
"<i>This guide reflects the ANSODEngine API as of the &lsquo;tracker/"
"stabilization invariant&rsquo; cleanup. File references point to "
"modules/ANSODEngine/ANSODEngine.cpp and "
"modules/ANSODEngine/ANSEngineCommon.h.</i>",
NOTE,
))
return s
# --------------------------------------------------------------------------- #
# Build #
# --------------------------------------------------------------------------- #
def main():
doc = SimpleDocTemplate(
str(OUTPUT),
pagesize=A4,
leftMargin=18*mm, rightMargin=18*mm,
topMargin=18*mm, bottomMargin=18*mm,
title="ANSODEngine — Tracker & Stabilization Developer Guide",
author="ANSCORE",
)
story = build_story()
doc.build(story)
print(f"Wrote {OUTPUT}")
if __name__ == "__main__":
main()