"""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 = "
".join( line.replace(" ", " ").replace("<", "<").replace(">", ">") for line in lines ) # restore tag rendering for our own tags body = body.replace("<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: ANSODEngine  ·  " "Base class: ANSCENTER::ANSODBase  ·  " "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 ANSODBase finishes " "Initialize / " "LoadModel / " "LoadModelFromFolder " "with these defaults:" )) s.append(make_table( ["Feature", "Default", "Source of default"], [ ["Tracker (BYTETrack / UCMC / OCSORT)", "ON", "Loaders auto-call SetTracker(BYTETRACK, true) " "(ANSODEngine.cpp:77, 110, 139, 174, 246, 260)"], ["Stabilization (ghost injection + EMA + hysteresis + " "class consistency)", "OFF", "Member initializer _stabilizationEnabled = false; " "no auto-enable"], ], col_widths=[55*mm, 18*mm, 95*mm], )) s.append(Spacer(1, 4)) s.append(p( "Notes. Tracker assigns a trackId " "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: " "stabilization requires tracker " "(stab=true ⇒ tracker=true)." )) 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", "→ false (forced)", "Stabilization can’t run without tracker. Forced clear " "keeps the flag honest."], ["SetStabilization(true, hist, miss)", "→ true (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. No ghosts, no EMA, " "no hysteresis.  ← default"], ["true", "true", "Full pipeline: tracking + ghost injection + EMA confidence + " "hysteresis + class consistency + stale-history pruning."], ["false", "true", "Unreachable — 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. " "SetStabilization(enabled, historySize, " "maxMisses) 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( "SetStabilizationParameters(json) " "— all keys optional:", )) s.append(make_table( ["Key", "Default", "Range", "Purpose"], [ ["hysteresis_enter", "model threshold", "float, 0 = auto", "Confidence needed for a new track to appear."], ["hysteresis_keep", "0.65 × enter", "float, 0 = auto", "Lower threshold to keep 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 " "ANS_DBG(\"ANSOD_StabState\", …):" )) s.append(code_block([ "[ANSOD_StabState] this= " "SetTracker(true,type=N) tracker=0->1 stab=0 (unchanged)", "[ANSOD_StabState] this= " "SetTracker(false) tracker=1->0 stab=1->0", "[ANSOD_StabState] this= " "SetStabilization(true,hist=20,miss=5) tracker=1->1 stab=0->1", "[ANSOD_StabState] this= " "SetStabilization(false) tracker=1 (unchanged) stab=1->0", ])) s.append(p( "Capture with DebugView (or any ANSCORE log) and " "grep ANSOD_StabState 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", "No effect on stabilization"], ["SetTracker(false) side-effect on stabilization", "None (could leave stab=true while tracker=false)", "Forced stabilization to false"], ["Default after model load", "tracker=ON, stabilization=ON", "tracker=ON, stabilization=OFF"], ["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( "Migration note. If your application relied on the old " "auto-enable to get stabilization for free, add an explicit " "SetStabilization(true) call after " "model load. ANSLPR’s defensive " "SetStabilization(false) calls remain " "correct (now redundant but harmless).", NOTE, )) # ── Footer / version note ──────────────────────────────────────────── s.append(Spacer(1, 14)) s.append(p( "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.", 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()