diff --git a/.claude/settings.local.json b/.claude/settings.local.json index dc0b182..4344da6 100644 --- a/.claude/settings.local.json +++ b/.claude/settings.local.json @@ -187,7 +187,31 @@ "PowerShell($candidates = @\\(\"handle64.exe\",\"handle.exe\"\\); $found = $null; foreach \\($c in $candidates\\) { $p = Get-Command $c -ErrorAction SilentlyContinue; if \\($p\\) { $found = $p.Source; break } }; if \\($found\\) { Write-Output \"FOUND: $found\"; & $found -nobanner -accepteula \"anslicensing.dll\" 2>$null } else { Write-Output \"handle.exe not in PATH\" })", "PowerShell(Get-CimInstance Win32_Process -Filter \"ProcessId=22688\")", "PowerShell(Get-CimInstance Win32_Process -Filter \"ParentProcessId=22688\")", - "Bash(taskkill //F //PID 50352)" + "Bash(taskkill //F //PID 50352)", + "Bash(awk -F'\\\\t' '/\\\\[TRT_Leak\\\\]/' \"C:/Users/nghia/Downloads/ANSLEGION.log1.log\")", + "Bash(awk -F'\\\\t' '/\\\\[MEDIA_Leak\\\\]/' \"C:/Users/nghia/Downloads/ANSLEGION.log1.log\")", + "Bash(awk -F'\\\\t' '/\\\\[MEDIA_Leak\\\\]/ {print $2, $4}' \"C:/Users/nghia/Downloads/ANSLEGION.log1.log\")", + "Bash(awk 'NR==1 || NR%50==0 || NR>510')", + "Bash(awk -F'\\\\t' '/\\\\[TRT_Leak\\\\]/ {if \\($4 !~ /creates=0 destroys=0 net=0 cached=0/\\) print NR\": \"$0}' \"C:/Users/nghia/Downloads/ANSLEGION.log1.log\")", + "Bash(awk '-F\\\\t' ' *)", + "Bash(awk -F'\\\\t' '/\\\\[TRT_Build\\\\]/' \"C:/Users/nghia/Downloads/ANSLEGION.log1.log\")", + "Bash(awk -F'\\\\t' '/VRAM/ {print $2, $4}' \"C:/Users/nghia/Downloads/ANSLEGION.log1.log\")", + "Bash(awk 'NR==1 || NR%2000==0')", + "Bash(awk -F'\\\\t' '/\\\\[ALPR_Track\\\\]|\\\\[ALPR_TrackId\\\\]/' \"C:/Users/nghia/Downloads/ANSLEGION.log1.log\")", + "Bash(awk -F'\\\\t' '/\\\\[ANSCUSTOM_Infer\\\\]/' \"C:/Users/nghia/Downloads/ANSLEGION.log1.log\")", + "Bash(sort -t= -k2 -n -r)", + "Bash(awk -F'\\\\t' '/\\\\[ALPR_TrackId\\\\]/' \"C:/Users/nghia/Downloads/ANSLEGION.log1.log\")", + "Bash(awk -F'\\\\t' '/\\\\[ANSMOT\\\\]/' \"C:/Users/nghia/Downloads/ANSLEGION.log1.log\")", + "Bash(awk '-F\\\\t' '/\\\\[ANSMOT\\\\] BYTETracker state/ { *)", + "Bash(awk -F'\\\\t' '/setInputShape/' \"C:/Users/nghia/Downloads/ANSLEGION.log1.log\")", + "Bash(awk -F'\\\\t' '/CUDA graph CAPTURE starting/' \"C:/Users/nghia/Downloads/ANSLEGION.log1.log\")", + "Bash(awk '-F\\\\t' '/setInputShape/{ *)", + "Bash(python -m pip install reportlab --quiet)", + "Bash(python build_anscore_devguide_pdf.py)", + "Bash(python -c \"from pypdf import PdfReader; r = PdfReader\\(r'C:/Projects/CLionProjects/ANSCORE/ANSODEngine_Tracker_Stabilization_Guide.pdf'\\); print\\('pages:', len\\(r.pages\\)\\)\")", + "Bash(python -c \"import reportlab.pdfbase.pdfmetrics; print\\('pages: \\(pypdf not available — file size confirms\\)'\\)\")", + "Bash(python -m pip install pypdf --quiet)", + "Bash(python -c \"from pypdf import PdfReader; r = PdfReader\\(r'C:/Projects/CLionProjects/ANSCORE/ANSODEngine_Tracker_Stabilization_Guide.pdf'\\); print\\('pages:', len\\(r.pages\\)\\); print\\('first page text \\(head\\):', r.pages[0].extract_text\\(\\)[:300].replace\\(chr\\(10\\), ' '\\)\\)\")" ] } } diff --git a/ANSODEngine_Tracker_Stabilization_Guide.pdf b/ANSODEngine_Tracker_Stabilization_Guide.pdf new file mode 100644 index 0000000..43e0e34 --- /dev/null +++ b/ANSODEngine_Tracker_Stabilization_Guide.pdf @@ -0,0 +1,149 @@ +%PDF-1.4 +%“Œ‹ž ReportLab Generated PDF document (opensource) +1 0 obj +<< +/F1 2 0 R /F2 3 0 R /F3 4 0 R /F4 5 0 R /F5 8 0 R +>> +endobj +2 0 obj +<< +/BaseFont /Helvetica /Encoding /WinAnsiEncoding /Name /F1 /Subtype /Type1 /Type /Font +>> +endobj +3 0 obj +<< +/BaseFont /Helvetica-Bold /Encoding /WinAnsiEncoding /Name /F2 /Subtype /Type1 /Type /Font +>> +endobj +4 0 obj +<< +/BaseFont /Courier /Encoding /WinAnsiEncoding /Name /F3 /Subtype /Type1 /Type /Font +>> +endobj +5 0 obj +<< +/BaseFont /Symbol /Name /F4 /Subtype /Type1 /Type /Font +>> +endobj +6 0 obj +<< +/Contents 14 0 R /MediaBox [ 0 0 595.2756 841.8898 ] /Parent 13 0 R /Resources << +/Font 1 0 R /ProcSet [ /PDF /Text /ImageB /ImageC /ImageI ] +>> /Rotate 0 /Trans << + +>> + /Type /Page +>> +endobj +7 0 obj +<< +/Contents 15 0 R /MediaBox [ 0 0 595.2756 841.8898 ] /Parent 13 0 R /Resources << +/Font 1 0 R /ProcSet [ /PDF /Text /ImageB /ImageC /ImageI ] +>> /Rotate 0 /Trans << + +>> + /Type /Page +>> +endobj +8 0 obj +<< +/BaseFont /Helvetica-Oblique /Encoding /WinAnsiEncoding /Name /F5 /Subtype /Type1 /Type /Font +>> +endobj +9 0 obj +<< +/Contents 16 0 R /MediaBox [ 0 0 595.2756 841.8898 ] /Parent 13 0 R /Resources << +/Font 1 0 R /ProcSet [ /PDF /Text /ImageB /ImageC /ImageI ] +>> /Rotate 0 /Trans << + +>> + /Type /Page +>> +endobj +10 0 obj +<< +/Contents 17 0 R /MediaBox [ 0 0 595.2756 841.8898 ] /Parent 13 0 R /Resources << +/Font 1 0 R /ProcSet [ /PDF /Text /ImageB /ImageC /ImageI ] +>> /Rotate 0 /Trans << + +>> + /Type /Page +>> +endobj +11 0 obj +<< +/PageMode /UseNone /Pages 13 0 R /Type /Catalog +>> +endobj +12 0 obj +<< +/Author (ANSCORE) /CreationDate (D:20260504092543+10'00') /Creator (\(unspecified\)) /Keywords () /ModDate (D:20260504092543+10'00') /Producer (ReportLab PDF Library - \(opensource\)) + /Subject (\(unspecified\)) /Title (ANSODEngine \204 Tracker & Stabilization Developer Guide) /Trapped /False +>> +endobj +13 0 obj +<< +/Count 4 /Kids [ 6 0 R 7 0 R 9 0 R 10 0 R ] /Type /Pages +>> +endobj +14 0 obj +<< +/Filter [ /ASCII85Decode /FlateDecode ] /Length 2736 +>> +stream +Gb!#^D0+_q%fW&,JPS5Y-II_#MsYW_+\eKPp,:#NENdt3cZBkZMRA]q=/%Y:rq_526qOiDU2E".:D?_M5nF%4#@IfSp`]4=g&QN8JG1u*#_dsC`6p5>I"_=TjGst;pTu^"-e\Zmr'V9WF2VCQ:]:,kgZ,"idbo.;hn*jGm<[,md^:&*^'`?K-eL'Mo8p"c4]mg4EC0F#_P?I*lJXqZS*kg[k)e0MpJX&#.,IqJ]EW`MY\!8R`%(bAoS,@-:2$JB(?S%8TC_^5EhkW6JU>JgP+tqjKrBME^Y$b3@3jb6.T%?;J2/@6X@;QK2q-4BbR8Bq;#NZE,d%HMQR%@?MZiinJ"eiaWBlRJRo`oG>E6#V6d"ciF29BrQ"dk&2W+trDtkpQi@WnYdhG3"3+F=nm0"VSQVrKjpk-ds6[NspEWZS7_4[14jjohdYNp4i4HU_6cr][_"B_aasQga#\!(G"6;=RS+dOc[h&C&]^TJ;6e[#B'qB'k@nH0DH/L(?VIIV_N7MCOS-"-N"mMJP`?8*A5"#D^>]fgs;=BRXJ&EYjMT*?5pC.IW'8Ko.R;1bg!kq_'_GNk/:9!gVU0YAjS5*l*lrn5h0Qr-0VGj]GN_ZQ^_`>+I@GlWf4N/]:i`MHu-I'0d1Vq-8I?sEPB2b>A.L'=rL-^]8*pVg(,4mk?@Dp7*YE!;cbR+I>L:M\uZpuA#)#DI\8+Fkf^6LW'7%_jE)8l>+hBaZVZ!S@D@$\\$C\fcVC`Z$Hmiji_W2="*#jY.Nqd1.\fg6MRqDD*?#1EaWOLH38m`&\!83V[QPY"/uPl\2L6X\8&,*N'm/kVF8)ilrprD_IBSVm,$U(hd%jUe$Y=$EW4mS")pJr=FmL:=V7,m,k2&A:s[.(OsUd:[![eMR$ER$r>MBIusl/qVJ0a2TgK6*mJLT@TEce.L6js.g0[""Cg,RJHS?j:^j>^A9o#%e]>is[2lQ]l#_OZgR&HRA[EPDh8Pn\qB8N^+qFHan/UEdX;m&%#8\CEG_b=(N3SIWqZ',T*c@%*22e-i,(M`uNgB,VA;IkeS-5G0[nW5+X>i:&&Qfj*V`K4Z4b^]Z;T?6QL(_W6d2+_JgkZ&Nff"U@+c^6"W>D!T:baEa4(OV52f91Hr5HqY[$SA9r:Jt-(p)8)>:M^5oJ&sAC.IJ[YkUu3pk$+XO>)$6P;@.'5fh4S9Vc(R[.tW#k;Zn\-d$C'8Y^"aW>pBb^tQj8T<8;Y#.dFbMMX^l^XHG&]-0p,_NsE`\^]N[h.o1SP0.V$E!Lmc`S.;rS,;3iQg3dL;nXpWIkI"K(/rg^+G^HpK)Qo?EY4UC)D/q^jltDB/p3Ao%aNZrU[5@7u?3b2c3147s79-\)O5h+$a6F;#_L7BC)Jl%hfmWW.eTW4]7YAGt2#`0dHq?Q#@db6/C:=Jsn5h:7A@?8FPJouoBJl792%9b-rZKK*Po&IU.M*BZ1P.@rE6EZbuF9\A?kW69^>FeGEDr8]3mL5Ck&WI7g=P`!EL/(M.!g[n4M.s$\"&agj2hdYTQN^HV'fAZ^5n7$d'.;g$`j(FM80b""o>nP1?+i3%>JMeAV1u3t^e145e-JXmN7T:%Bb7t0lTs2C[;1'F'Q0A?Wob-?qhf#gUn628O@k0Dgd2Z+[.m#YUe#J?p)I+GBVBS%.;51$\BVR$`Rg!M0/'q"mY?\UgAZ)Drq26f['oeAo;EM4pTW:OJDlrDhft]qlJGVH-LBlt9CPpJtG`E"JQJLo(m9@0#GW;Rb_\uME+LM0SM&;3uL=ap$Np?qEM`mr#6B09:7rM[bN6&*d`ImklJXY"9U!C/>RVM6W;3./,FXE;L;uO"FAY,!8.rI:nQEY%FLc-00#Mh)>p"8It1J2M&_HglULO2r&IrJbpQYE@#sZ?i(U!Uf=Xp.AsBR1If8h,LrLWG>b*$9KgrQ!ZId=N'mMJ*p,o4;/N'o@lq.=.P?4(#.,97\uhaa4+-GVJa,k*=d&gVPW.$\M=j>JPU0,@0kUqbJGB2(R_8@c-.UnhKt-\9gA,8W.<>$q_VT0i]@Qa+ZgJhI[ob5MdZkRkh7ZLC/k@'bW+b&D"-_)PP0'^'^,BkZ(ZVHZq]0hgcTF&p2FtAlJRa4"c&lY***p``)%`t<^4g7CM;!Gi?YO8cpFng/2O5t(>hb&.%+[*OW^i@O;`q-PJ7+Xl!k;~>endstream +endobj +15 0 obj +<< +/Filter [ /ASCII85Decode /FlateDecode ] /Length 924 +>> +stream +Gatm:9lo#B&A@Zcp./)U8?sf$a!OO0l.7c.4`lF:j+uVm=MtuOl*'R0?t2.8&>l4R61!n(^>5[t"r%:m^Z.>i70r)F)))QZ'UU!E_U!09%\Uec@e)6Q=_Tu(5u#D>/>B+g"NIE=Xn*X7GBl7`^$Et#m93FrJ!";hII+3Y(n!OK"lUi6fUBjicU,HXrMR>R2^asSPa&3`F*>,67mUQJSB>jf-8o:q);PnrZe%`4E_F6^U[(DmFTV[-Ibb");&+1gtc5lp'I$.anXn1g0+=,G4&D.MMqEVNt`Ja?Ri!g_gO>_i(5DNk`t?/mSL!R)5CRQ$RT1qnMp]Jbo/fhtQc,.PgW66<2*V+P7j%lu:D+[R]#N)ATdeh6k9pYe1kNL%/;W6M(3-Yh/,qKW4CJ_W_=M,+%<2DJp,A@ML1`$at6!seb`B:ZqA@qSC05iCZX\"HH;%sFgXDXNc:]6=U"^";ib>:e=nKhgXG*l)VgXBjW$b&0O@L)3(kX75iMjei^CCoR8+!FY8=DK"724+J/X6_P@O"8^JNGjm5[?fOCX,lth.`-UWDm?m/V-^tg_9d=HD'O*-&>JlJd3+r,Pr2#GjOjQ[%d>,u[>cXJ-[qF8Uid`rV;'AU)6.O*OX]/QmI"$+JLgHk!4CB>]+D>8C-Hj3g>b#28pC2B3Yg4+N3$8(3.?g*GB!d4k+!M/Q,0WFendstream +endobj +16 0 obj +<< +/Filter [ /ASCII85Decode /FlateDecode ] /Length 3062 +>> +stream +GauHNlYkN;'*"Q<@^$piC6L%korrPJm%J9Z4kqr4g>i`GX:L%pe$`F_nsXUSm"bPoDb.QY]rYHT5n_A:Aqp3mk=H!`J#N3*>lhTdJ;Y?RPek6WW2Z9Un/e_S:4>F$ktGlg'5#l*7^f'R[S?9T*7fs\:h'Vh1L*Cdcn4"Wfa'Ko';S3@2?l:FO9G`$-l07%TNO>2a53R5pj[On+,-rm2Vs>3Hm;t6_\[QB/VWtQ5BVRFDFop>2r0Yp,d6rW@BTN;Y/Udj#25R>3d?B-`':j[%ma15n-'Iut:9doH$;%/ZXs@P.mO%RJf0MlhPh1JE8'9Qf"ahN"Q0Y:?k.*p:*L*cnGOKqbO+]kh/MopX[lpL481^HsPK]*Y`Jn#/11msl*4jPu=P]na=O`>;=99"%m.hfs!@korL*g^d%E,.rhf;ij%8:cm`m^E<]X3M_5g+"=2e3pKl;lNLB,P1N4!I/+&Mn44;lbn+L6r4(AL(_Af$=sPJ]\LaHleu,>ApsD+"h[1B6#3G(Po2[T0A76:YOH/UZ>@6")L?@dA>&%Rl\LfKtgtiFPA+k74UQr,MPVe/,p5$56$"^rca]soMo=InL9!82*f=APKMLQQrf_R:Bib^1k8BTJ5I1:D\XZ$(B)lLr]ULZ2#D=3pq'E@j1JBQS/usE"IqZ`Yj5'J`r41LZ)GIUkQOY4p("t?6FdEO_rn.Yqbu"L>eX>a/6)9M`aZtiDHC=d5"0;-`*4!)oGd1.DK>X&grI6@+.?/\9>*TgN'#-c07b"joEQ=@D#=\!5mjsp&NMdD%*@Ca5Qmg%ICU>=N9W.i[KQE;=Mho$=X-s[6R$+RH#Pn;%t\ZB)JYD.b6(C,?.8_-BAane!$%=:6Nu5#AtR[lIJ`-TU+"(Mj';D<8n<]9@=Nm9+@jRAAFUhU6X#4RXQrL%)"?=2;3Z&!iC\A0,'#g=Rik$rq8b:@J_ebp';McCi8LZ(D'DY#AhU3aai[5T[O!#BW+pP06a:)ilpRE*GlCMXGO.^@e9L\KNAhXQ%'-qIV]:J_30()BfN_>Wc.2n+3u[:I-f+?SYi709g79iZ1q]4/TtBrp/Ub[@N(6V6Lb^#k3m2cT;VgVDCod4!l>'jn$n:4:qM=ft?eQ-g/igL:oL>nmgL'&kKWU:DAdkF4+FUFKrB[c>1^MQIA)t:Y_eHO=h5BI*#K1-#YGm<]hVJ,L*LZ,tEQ:R_g=osVY1:r#A"75tX$rSqT-),-LFbm!dgjK:>"rqmgTJ&qDRHAb1ZAcj$:7"?%j_aP8i&'V(BYjKc?QEH_5":^WLku!`?ap.pd8SiPH+NT%^&)[bN3FPEjqE(3&'hX#6N[^sEU`:`'U'6sK+A7q2Og9=0gf!-r4eg!Sjd3!1Wt#Ad5QP@-:pr.88^fq2Rn/4Dn8o>=_Zu"m!IjChN;6%!kroeU)]XSm[A5$gsZQJP9`qnj:$FBV,`C@3mb>[5@9Q=aRidWC8erIk.L;O8ubjW_=8r`?(OM&?JsKn4!tTWt.FF*RRcYq9f1,&X9)7^K]GcMjF6[^XVZ*2+Z_UW$mUPP0e*pU#1JJr@`3:3q0=:R1bM4AJ99Ynh8dr%*;'o?.[/L?2Bu.@9,.6A&;cadV'4WI-SS[NQudiI]BRMTV02^Eq+;5k#!:BiTCu."(E@mj%AZI9O&OdZIfjE[D08QWCk$*($m-f5U:FRW3QI~>endstream +endobj +17 0 obj +<< +/Filter [ /ASCII85Decode /FlateDecode ] /Length 1615 +>> +stream +Gatm;lYiOf&HD15@Qot=6J1C6WMu,KX/iDF-*\q"F`lERK"5?Vnjn**lT<:A%JYM?Sh5;?)GRb/6kFX*4%IXsY.W8#uY'Diq_1E%&/D&B#oh7%Ka>r%G:S(B8)UrNqJ=%a#^&gWs=dLoX4S^,$)=Xa6Zn(1r%-Cn_qb\r@?=83lg@*W(09:q!q/CK4fZD?E:ZbFqZq1%u5MY*JmZmta8/<+m.i%Ipf($W>q(q8!r@44!qB24"rp2H]=K:Etq,\L:RKd`Y4L)]RVI>0Eoo2_Ha18>]R2@ReMP)":.EJ`p<\+W.DOg"1DVZLK,h]F"-N]#PY?/_ZdI/`XU6kW;O(dQIk(MBu@8+"A5CPoh^p]ILDG.GcN4FZb";=irhHpW*GN-A8,dhS]J*5%LXNngJ[6X?eLQC*=5o=;gSU7>['-lcTP-O.!!%'[Rk>l,c;N/*L;(dofAXjW)2MNZBJ"cGGJ`6SZU+T"o)T46&t^r'QRq4^I_82ttV[I[H4B6b+8CUD\@D"mQb(^8r-)X`Ocem"aOgL7:.*XIF?d.NqiG/lsN,pb7UX^EFVT&;oXp7EaKS52u4@e]ZeU$isb)$R=r\#i+k?RskfB3fp[6dPh8%Fi^9#@KE[POa(IXu5;[%L.!PYHg3Jn+5#hNe7$^rk;-LB53MWp-UHP*=J>Fq/<3Oa22hoD2qYd:.!ean5>I/0#?a72EHd;Q9Bh1F4DSqm@&\6F@g`3P-Ark;"1V63'Dl"+dbDobgldR)CgWm_"Gsl5a*+/0I43BDQ-G/>%;@5Xuk"d%(1J"`^u*Jm(I"tV?G$n>]-nlendstream +endobj +xref +0 18 +0000000000 65535 f +0000000061 00000 n +0000000132 00000 n +0000000239 00000 n +0000000351 00000 n +0000000456 00000 n +0000000533 00000 n +0000000738 00000 n +0000000943 00000 n +0000001058 00000 n +0000001263 00000 n +0000001469 00000 n +0000001539 00000 n +0000001857 00000 n +0000001936 00000 n +0000004764 00000 n +0000005779 00000 n +0000008933 00000 n +trailer +<< +/ID +[<5308ad286f7ed61e1c31de3c2e9f2ace><5308ad286f7ed61e1c31de3c2e9f2ace>] +% ReportLab generated PDF document -- digest (opensource) + +/Info 12 0 R +/Root 11 0 R +/Size 18 +>> +startxref +10640 +%%EOF diff --git a/build_anscore_devguide_pdf.py b/build_anscore_devguide_pdf.py new file mode 100644 index 0000000..1b37ce5 --- /dev/null +++ b/build_anscore_devguide_pdf.py @@ -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 = "
".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() diff --git a/modules/ANSODEngine/ANSODEngine.cpp b/modules/ANSODEngine/ANSODEngine.cpp index f1c480f..0aede5d 100644 --- a/modules/ANSODEngine/ANSODEngine.cpp +++ b/modules/ANSODEngine/ANSODEngine.cpp @@ -418,10 +418,24 @@ namespace ANSCENTER } } + const bool prevTracker = _trackerEnabled; + const bool prevStab = _stabilizationEnabled; + _trackerEnabled = enabled; _trackerType = trackerType; - if (!enabled) return true; + if (!enabled) { + // Invariant: stabilization requires the tracker. Disabling the + // tracker forces stabilization off so the flag does not lie — + // otherwise StabilizeDetections is dead code (gated on + // _trackerEnabled in the inference path) but introspection + // would still report stabilization as on. + _stabilizationEnabled = false; + ANS_DBG("ANSOD_StabState", + "this=%p SetTracker(false) tracker=%d->0 stab=%d->0", + (void*)this, (int)prevTracker, (int)prevStab); + return true; + } // Store config so per-camera trackers can be created lazily _trackerMotType = 1; // default BYTETRACK @@ -447,10 +461,14 @@ namespace ANSCENTER } } - // Auto-enable stabilization with defaults when tracker is enabled - if (!_stabilizationEnabled) { - _stabilizationEnabled = true; - } + // Note: stabilization is NOT auto-enabled here. Tracker can run + // without stabilization (raw trackId assignment, no ghost + // injection / EMA / hysteresis). Callers that want stabilization + // must opt in explicitly via SetStabilization(true), which + // auto-enables the tracker if needed. + ANS_DBG("ANSOD_StabState", + "this=%p SetTracker(true,type=%d) tracker=%d->1 stab=%d (unchanged)", + (void*)this, (int)trackerType, (int)prevTracker, (int)prevStab); return true; } @@ -463,8 +481,13 @@ namespace ANSCENTER bool ANSODBase::SetStabilization(bool enabled, int historySize, int maxMisses) { std::lock_guard lock(_mutex); try { + const bool prevTracker = _trackerEnabled; + const bool prevStab = _stabilizationEnabled; + if (enabled) { - // Auto-enable tracker if not already enabled + // Invariant: stabilization requires tracker. Auto-enable + // tracker if currently off so the flag is meaningful at + // runtime (StabilizeDetections is gated on _trackerEnabled). if (!_trackerEnabled) { if (!SetTracker(_trackerType, true)) { _logger.LogError("ANSODBase::SetStabilization", @@ -476,9 +499,18 @@ namespace ANSCENTER _stabilizationQueueSize = static_cast(std::max(historySize, 5)); _stabilizationMaxConsecutiveMisses = std::max(maxMisses, 1); QUEUE_SIZE = _stabilizationQueueSize; + ANS_DBG("ANSOD_StabState", + "this=%p SetStabilization(true,hist=%d,miss=%d) tracker=%d->%d stab=%d->1", + (void*)this, historySize, maxMisses, + (int)prevTracker, (int)_trackerEnabled, (int)prevStab); } else { + // Disabling stabilization leaves the tracker untouched — + // tracker is independently useful (raw trackId assignment). _stabilizationEnabled = false; + ANS_DBG("ANSOD_StabState", + "this=%p SetStabilization(false) tracker=%d (unchanged) stab=%d->0", + (void*)this, (int)prevTracker, (int)prevStab); } return true; }