Disable stabilized feature by default. Need ,more time to test
This commit is contained in:
@@ -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(" ", " ").replace("<", "<").replace(">", ">")
|
||||
for line in lines
|
||||
)
|
||||
# restore tag rendering for our own tags
|
||||
body = body.replace("<br/>", "<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 — Tracker & Stabilization Developer Guide",
|
||||
H1,
|
||||
))
|
||||
s.append(p(
|
||||
"Module: <b>ANSODEngine</b> · "
|
||||
"Base class: <b>ANSCENTER::ANSODBase</b> · "
|
||||
"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 “ghost” boxes. "
|
||||
"Stabilization is opt-in and requires the tracker. "
|
||||
"It cannot run standalone.",
|
||||
NOTE,
|
||||
))
|
||||
|
||||
# ── 2. Public setters — invariant table ─────────────────────────
|
||||
s.append(p("2. Public setters — invariant table", H2))
|
||||
s.append(p(
|
||||
"The single invariant maintained by the API: "
|
||||
"<b>stabilization requires tracker</b> "
|
||||
"(<font face='Courier'>stab=true ⇒ tracker=true</font>)."
|
||||
))
|
||||
s.append(make_table(
|
||||
["Call", "_trackerEnabled", "_stabilizationEnabled", "Why"],
|
||||
[
|
||||
["SetTracker(type, true)",
|
||||
"→ true",
|
||||
"unchanged",
|
||||
"Tracker is independently useful. Don’t side-effect stab."],
|
||||
["SetTracker(type, false)",
|
||||
"→ false",
|
||||
"<b>→ false</b> (forced)",
|
||||
"Stabilization can’t run without tracker. Forced clear "
|
||||
"keeps the flag honest."],
|
||||
["SetStabilization(true, hist, miss)",
|
||||
"<b>→ true</b> (auto if off)",
|
||||
"→ true",
|
||||
"Stabilization needs tracker. Auto-enables it."],
|
||||
["SetStabilization(false)",
|
||||
"unchanged",
|
||||
"→ 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> ← default"],
|
||||
["true", "true",
|
||||
"Full pipeline: tracking + ghost injection + EMA confidence + "
|
||||
"hysteresis + class consistency + stale-history pruning."],
|
||||
["false", "true",
|
||||
"<b>Unreachable</b> — 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) (auto-enables tracker)"],
|
||||
["Tracker + stabilization with custom thresholds",
|
||||
"SetStabilization(true) then SetStabilizationParameters(json)"],
|
||||
["Disable everything",
|
||||
"SetTracker(BYTETRACK, false) (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", "≥ 5",
|
||||
"Frames retained in _detectionQueue per camera."],
|
||||
["maxMisses", "5", "≥ 1",
|
||||
"Frames a ghost may persist before pruning. "
|
||||
"History pruned at 2×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> "
|
||||
"— 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 × 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", "≥ 1",
|
||||
"Frames before a track is “established” and gets "
|
||||
"confidence boost."],
|
||||
["track_boost_amount", "0.05", "[0.0, 0.5]",
|
||||
"Confidence bonus for established tracks."],
|
||||
["class_consistency_frames", "5", "≥ 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 & memory characteristics", H2))
|
||||
s.append(make_table(
|
||||
["Aspect", "Tracker only", "Tracker + Stabilization"],
|
||||
[
|
||||
["Per-frame CPU cost",
|
||||
"BYTETrack association, ~O(N·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’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 > 2×maxMisses) "
|
||||
"+ _detectionQueue (capped at historySize)"],
|
||||
["Bounded?",
|
||||
"Yes — caps in BYTETrack (kRemovedCap=1000)",
|
||||
"Yes — 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\", …)</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’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 ‘tracker/"
|
||||
"stabilization invariant’ 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()
|
||||
Reference in New Issue
Block a user