438 lines
17 KiB
Python
438 lines
17 KiB
Python
"""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()
|