Build polish (#18)

Improve build process and documentation.
Improved ray versus capsule accuracy.
UI improvements
This commit is contained in:
Erin Catto 2026-06-28 10:44:34 -07:00 • committed by GitHub
commit 69037feaba
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
19 changed files with 1719 additions and 158 deletions

View file

@ -0,0 +1,65 @@
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 640 500" font-family="Segoe UI, Helvetica, Arial, sans-serif">
<defs>
<marker id="cBlue" viewBox="0 0 10 10" refX="8" refY="5" markerWidth="7" markerHeight="7" orient="auto"><path d="M0,0 L10,5 L0,10 z" fill="#1f6feb"/></marker>
<marker id="cRed" viewBox="0 0 10 10" refX="8" refY="5" markerWidth="7" markerHeight="7" orient="auto"><path d="M0,0 L10,5 L0,10 z" fill="#d1242f"/></marker>
<marker id="cGreen" viewBox="0 0 10 10" refX="8" refY="5" markerWidth="7" markerHeight="7" orient="auto"><path d="M0,0 L10,5 L0,10 z" fill="#1a7f37"/></marker>
</defs>
<rect width="640" height="500" fill="#ffffff"/>
<text x="24" y="32" font-size="17" font-weight="bold" fill="#222">Reduction to 2D: ray vs circle in the plane &#8869; to the axis</text>
<text x="24" y="54" font-size="13" fill="#555">Project out the axis component. The infinite cylinder becomes a circle of radius r.</text>
<!-- cylinder cross-section -->
<circle cx="270" cy="270" r="110" fill="#eaf1f8" stroke="#7fa8cc" stroke-width="1.8"/>
<text x="270" y="408" font-size="12.5" fill="#3b6790" text-anchor="middle">circle of radius r</text>
<!-- axis point (out of page) -->
<circle cx="270" cy="270" r="6" fill="none" stroke="#555" stroke-width="1.5"/>
<circle cx="270" cy="270" r="1.6" fill="#555"/>
<text x="284" y="287" font-size="12.5" fill="#555">a&#8321; (out of page)</text>
<!-- radius -->
<line x1="270" y1="270" x2="380" y2="270" stroke="#333" stroke-width="1" stroke-dasharray="4 3"/>
<text x="320" y="263" font-size="13" fill="#333">r</text>
<!-- sc: from axis to projected origin -->
<line x1="270" y1="270" x2="68" y2="97" stroke="#d1242f" stroke-width="1.8" marker-end="url(#cRed)"/>
<text x="150" y="166" font-size="13" fill="#d1242f">sc</text>
<!-- projected origin -->
<circle cx="60" cy="90" r="4" fill="#1f6feb"/>
<text x="40" y="80" font-size="12.5" fill="#1f6feb">projected origin</text>
<!-- perp: ray velocity in this plane -->
<line x1="60" y1="90" x2="102" y2="158" stroke="#1a7f37" stroke-width="1.8" marker-end="url(#cGreen)"/>
<text x="108" y="140" font-size="13" fill="#1a7f37">perp</text>
<!-- projected ray line through the circle -->
<line x1="60" y1="90" x2="250" y2="402" stroke="#1f6feb" stroke-width="1.6" stroke-dasharray="6 4"/>
<!-- intersections -->
<circle cx="161" cy="256" r="5" fill="#d1242f"/>
<text x="36" y="262" font-size="12" fill="#d1242f">near root &#8594; tr</text>
<circle cx="233" cy="373" r="5" fill="none" stroke="#333" stroke-width="1.6"/>
<text x="243" y="380" font-size="12" fill="#555">far root</text>
<!-- legend / formulas panel -->
<line x1="420" y1="118" x2="420" y2="402" stroke="#e2e2e2" stroke-width="1"/>
<text x="440" y="135" font-size="12.5" fill="#333">Quantities used by the branch</text>
<text x="440" y="165" font-size="12.5" fill="#d1242f">sc</text>
<text x="462" y="165" font-size="12.5" fill="#444">= origin offset &#8869; axis, sc2 = |sc|&#178;</text>
<text x="440" y="190" font-size="12.5" fill="#1a7f37">perp</text>
<text x="478" y="190" font-size="12.5" fill="#444">= a&#8322; &#8722; a&#8321;&#8322; a&#8321; (ray dir &#8869; axis)</text>
<text x="440" y="215" font-size="12.5" fill="#444">perp2 = |perp|&#178; = det</text>
<text x="440" y="240" font-size="12.5" fill="#444">&#946; = sc &#183; perp (signed, length)</text>
<text x="440" y="265" font-size="12.5" fill="#444">&#947; = sc2 &#8722; r&#178; &#8805; 0 (origin outside)</text>
<text x="440" y="290" font-size="12.5" fill="#444">disc = &#946;&#178; &#8722; perp2&#183;&#947;</text>
<text x="440" y="325" font-size="12.5" fill="#8a5300">&#946; &#8805; 0 &#8594; moving away &#8594; miss</text>
<text x="440" y="348" font-size="12.5" fill="#8a5300">disc &lt; 0 &#8594; never reaches r &#8594; miss</text>
<text x="440" y="378" font-size="12.5" fill="#1a7f37">otherwise: near root is the entry tr</text>
<!-- caption -->
<text x="24" y="452" font-size="12.5" fill="#444">In this plane the axis is a single point, so the problem is exactly &#8220;ray from an outside point hits a circle.&#8221;</text>
<text x="24" y="472" font-size="12.5" fill="#444">Solving here never divides by the tiny det, which is what made the general solve fail.</text>
</svg>

After

Width:  |  Height:  |  Size: 4.2 KiB

View file

@ -0,0 +1,55 @@
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 660 560" font-family="Segoe UI, Helvetica, Arial, sans-serif">
<defs>
<marker id="qEnd" viewBox="0 0 10 10" refX="8" refY="5" markerWidth="6" markerHeight="6" orient="auto"><path d="M0,0 L10,5 L0,10 z" fill="#333"/></marker>
</defs>
<rect width="660" height="560" fill="#ffffff"/>
<text x="24" y="32" font-size="17" font-weight="bold" fill="#222">The quadratic in tr, and the stable root</text>
<text x="24" y="54" font-size="13" fill="#555">Squared distance from the moving ray point to the axis, as a function of ray distance tr.</text>
<!-- axes -->
<line x1="100" y1="355" x2="610" y2="355" stroke="#333" stroke-width="1.4" marker-end="url(#qEnd)"/>
<line x1="100" y1="355" x2="100" y2="70" stroke="#333" stroke-width="1.4" marker-end="url(#qEnd)"/>
<text x="592" y="378" font-size="13" fill="#333">tr</text>
<text x="60" y="80" font-size="12.5" fill="#333">dist&#178;</text>
<!-- inside-cylinder shaded region -->
<path d="M233,250 L280,284 L340,300 L400,284 L447,250 Z" fill="#fdecef"/>
<!-- r^2 level -->
<line x1="100" y1="250" x2="590" y2="250" stroke="#d1242f" stroke-width="1.3" stroke-dasharray="6 4"/>
<text x="596" y="254" font-size="13" fill="#d1242f">r&#178;</text>
<!-- parabola -->
<polyline points="120,90 160,159 200,215 233,250 280,284 340,300 400,284 447,250 480,215 520,159 560,90"
fill="none" stroke="#1f6feb" stroke-width="2.2"/>
<!-- tr = 0 marker -->
<line x1="120" y1="90" x2="120" y2="355" stroke="#bbb" stroke-width="1" stroke-dasharray="3 3"/>
<circle cx="120" cy="90" r="4" fill="#1f6feb"/>
<text x="70" y="92" font-size="12" fill="#1f6feb">sc2</text>
<text x="104" y="372" font-size="12" fill="#555">tr = 0</text>
<!-- near root -->
<line x1="233" y1="250" x2="233" y2="355" stroke="#d1242f" stroke-width="1" stroke-dasharray="3 3"/>
<circle cx="233" cy="250" r="5" fill="#d1242f"/>
<text x="206" y="372" font-size="12.5" fill="#d1242f">tr (entry)</text>
<!-- far root -->
<circle cx="447" cy="250" r="5" fill="none" stroke="#333" stroke-width="1.6"/>
<text x="455" y="246" font-size="12" fill="#555">far root (exit)</text>
<!-- vertex -->
<circle cx="340" cy="300" r="3" fill="#1f6feb"/>
<text x="300" y="320" font-size="11.5" fill="#555">closest approach</text>
<text x="150" y="205" font-size="11.5" fill="#a23">inside the cylinder (dist&#178; &lt; r&#178;)</text>
<!-- explanation panel -->
<rect x="40" y="405" width="580" height="138" rx="6" fill="#f6f8fa" stroke="#e2e6ea" stroke-width="1"/>
<text x="56" y="428" font-size="13" font-weight="bold" fill="#222">Why tr = &#947; / (&#8722;&#946; + &#8730;disc) rather than the textbook root</text>
<text x="56" y="452" font-size="12.5" fill="#333">quadratic: perp2&#183;tr&#178; + 2&#946;&#183;tr + &#947; = 0 ( &#946; = sc&#183;perp, &#947; = sc2 &#8722; r&#178;, perp2 = det )</text>
<text x="56" y="474" font-size="12.5" fill="#333">textbook near root: tr = (&#8722;&#946; &#8722; &#8730;disc) / perp2</text>
<text x="56" y="496" font-size="12.5" fill="#8a5300">ray &#8594; parallel: perp2 &#8594; 0 and &#8730;disc &#8594; |&#946;| = &#8722;&#946; &#8658; &#8722;&#946; &#8722; &#8730;disc &#8594; 0 (cancellation), &#247; tiny perp2 &#8594; 0/0</text>
<text x="56" y="520" font-size="12.5" fill="#1a7f37">used form: tr = &#947; / (&#8722;&#946; + &#8730;disc) &#8212; denominator is a sum of two positives: no cancellation, no divide by det</text>
</svg>

After

Width:  |  Height:  |  Size: 3.5 KiB

View file

@ -0,0 +1,64 @@
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 760 410" font-family="Segoe UI, Helvetica, Arial, sans-serif">
<defs>
<marker id="mBlue" viewBox="0 0 10 10" refX="8" refY="5" markerWidth="7" markerHeight="7" orient="auto"><path d="M0,0 L10,5 L0,10 z" fill="#1f6feb"/></marker>
<marker id="mGray" viewBox="0 0 10 10" refX="8" refY="5" markerWidth="7" markerHeight="7" orient="auto"><path d="M0,0 L10,5 L0,10 z" fill="#555"/></marker>
<marker id="mRed" viewBox="0 0 10 10" refX="8" refY="5" markerWidth="7" markerHeight="7" orient="auto"><path d="M0,0 L10,5 L0,10 z" fill="#d1242f"/></marker>
<marker id="mEnd" viewBox="0 0 10 10" refX="8" refY="5" markerWidth="6" markerHeight="6" orient="auto"><path d="M0,0 L10,5 L0,10 z" fill="#333"/></marker>
<marker id="mStart" viewBox="0 0 10 10" refX="2" refY="5" markerWidth="6" markerHeight="6" orient="auto"><path d="M10,0 L0,5 L10,10 z" fill="#333"/></marker>
</defs>
<rect width="760" height="410" fill="#ffffff"/>
<text x="24" y="32" font-size="17" font-weight="bold" fill="#222">Near-parallel branch — side view (plane through the axis)</text>
<text x="24" y="54" font-size="13" fill="#555">Ray almost parallel to the capsule axis; origin outside the infinite cylinder.</text>
<!-- infinite cylinder: walls and fill -->
<rect x="60" y="185" width="645" height="130" fill="#eaf1f8"/>
<line x1="60" y1="185" x2="705" y2="185" stroke="#7fa8cc" stroke-width="1.6"/>
<line x1="60" y1="315" x2="705" y2="315" stroke="#7fa8cc" stroke-width="1.6"/>
<text x="568" y="178" font-size="12.5" fill="#3b6790">infinite cylinder wall</text>
<!-- faint hemispherical caps to show the full capsule -->
<path d="M120,185 A65,65 0 0 0 120,315" fill="none" stroke="#c4d2e0" stroke-width="1.4" stroke-dasharray="4 3"/>
<path d="M600,185 A65,65 0 0 1 600,315" fill="none" stroke="#c4d2e0" stroke-width="1.4" stroke-dasharray="4 3"/>
<!-- capsule axis -->
<line x1="60" y1="250" x2="120" y2="250" stroke="#555" stroke-width="1.5" stroke-dasharray="5 4"/>
<line x1="120" y1="250" x2="600" y2="250" stroke="#555" stroke-width="2"/>
<line x1="600" y1="250" x2="705" y2="250" stroke="#555" stroke-width="1.5" stroke-dasharray="5 4"/>
<line x1="515" y1="250" x2="560" y2="250" stroke="#555" stroke-width="2" marker-end="url(#mGray)"/>
<text x="520" y="242" font-size="12.5" fill="#555">a&#8321; (axis dir)</text>
<!-- endpoints -->
<circle cx="120" cy="250" r="3.5" fill="#333"/>
<text x="110" y="272" font-size="13" fill="#333">c&#8321;</text>
<circle cx="600" cy="250" r="3.5" fill="#333"/>
<text x="592" y="272" font-size="13" fill="#333">c&#8322;</text>
<!-- radius dimension -->
<line x1="300" y1="250" x2="300" y2="185" stroke="#333" stroke-width="1" marker-start="url(#mStart)" marker-end="url(#mEnd)"/>
<text x="306" y="222" font-size="13" fill="#333">r</text>
<!-- ray origin -->
<circle cx="150" cy="110" r="4" fill="#1f6feb"/>
<text x="86" y="103" font-size="12.5" fill="#1f6feb">ray origin</text>
<!-- sc: perpendicular offset axis -> origin -->
<line x1="150" y1="250" x2="150" y2="116" stroke="#d1242f" stroke-width="1.6" marker-end="url(#mRed)"/>
<text x="156" y="172" font-size="13" fill="#d1242f">sc</text>
<text x="156" y="190" font-size="11.5" fill="#d1242f">|sc| &gt; r</text>
<!-- the ray: origin (150,110) -> (690,235), grazes top wall at (474,185) -->
<line x1="150" y1="110" x2="690" y2="235" stroke="#1f6feb" stroke-width="2" marker-end="url(#mBlue)"/>
<text x="244" y="120" font-size="12.5" fill="#1f6feb">a&#8322; (ray dir), nearly &#8741; a&#8321;</text>
<!-- near hit on the cylinder wall -->
<circle cx="474" cy="185" r="4.5" fill="#d1242f"/>
<text x="430" y="170" font-size="12.5" fill="#d1242f">near hit on cylinder</text>
<!-- tr label along the ray -->
<text x="392" y="150" font-size="13" fill="#1f6feb">tr (ray distance)</text>
<!-- captions -->
<text x="24" y="384" font-size="12.5" fill="#444">det = 1 &#8722; (a&#8321;&#183;a&#8322;)&#178; &#8776; 0 here, so the Cramer's-rule closest-point solve divides by ~0 and loses all precision.</text>
<text x="24" y="402" font-size="12.5" fill="#444">Fix: intersect the ray with the infinite cylinder using only the parts perpendicular to the axis (next figure).</text>
</svg>

After

Width:  |  Height:  |  Size: 4.2 KiB