Build polish (#18)
Improve build process and documentation. Improved ray versus capsule accuracy. UI improvements
This commit is contained in:
parent
0c8ef46931
commit
69037feaba
19 changed files with 1719 additions and 158 deletions
65
docs/images/rc_parallel_crosssection.svg
Normal file
65
docs/images/rc_parallel_crosssection.svg
Normal 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 ⊥ 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₁ (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 → 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 ⊥ axis, sc2 = |sc|²</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₂ − a₁₂ a₁ (ray dir ⊥ axis)</text>
|
||||
<text x="440" y="215" font-size="12.5" fill="#444">perp2 = |perp|² = det</text>
|
||||
<text x="440" y="240" font-size="12.5" fill="#444">β = sc · perp (signed, length)</text>
|
||||
<text x="440" y="265" font-size="12.5" fill="#444">γ = sc2 − r² ≥ 0 (origin outside)</text>
|
||||
<text x="440" y="290" font-size="12.5" fill="#444">disc = β² − perp2·γ</text>
|
||||
|
||||
<text x="440" y="325" font-size="12.5" fill="#8a5300">β ≥ 0 → moving away → miss</text>
|
||||
<text x="440" y="348" font-size="12.5" fill="#8a5300">disc < 0 → never reaches r → 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 “ray from an outside point hits a circle.”</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 |
55
docs/images/rc_parallel_quadratic.svg
Normal file
55
docs/images/rc_parallel_quadratic.svg
Normal 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²</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²</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² < r²)</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 = γ / (−β + √disc) rather than the textbook root</text>
|
||||
<text x="56" y="452" font-size="12.5" fill="#333">quadratic: perp2·tr² + 2β·tr + γ = 0 ( β = sc·perp, γ = sc2 − r², perp2 = det )</text>
|
||||
<text x="56" y="474" font-size="12.5" fill="#333">textbook near root: tr = (−β − √disc) / perp2</text>
|
||||
<text x="56" y="496" font-size="12.5" fill="#8a5300">ray → parallel: perp2 → 0 and √disc → |β| = −β ⇒ −β − √disc → 0 (cancellation), ÷ tiny perp2 → 0/0</text>
|
||||
<text x="56" y="520" font-size="12.5" fill="#1a7f37">used form: tr = γ / (−β + √disc) — denominator is a sum of two positives: no cancellation, no divide by det</text>
|
||||
</svg>
|
||||
|
After Width: | Height: | Size: 3.5 KiB |
64
docs/images/rc_parallel_setup.svg
Normal file
64
docs/images/rc_parallel_setup.svg
Normal 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₁ (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₁</text>
|
||||
<circle cx="600" cy="250" r="3.5" fill="#333"/>
|
||||
<text x="592" y="272" font-size="13" fill="#333">c₂</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| > 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₂ (ray dir), nearly ∥ a₁</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 − (a₁·a₂)² ≈ 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 |
Loading…
Reference in a new issue