Improve build process and documentation. Improved ray versus capsule accuracy. UI improvements
11 KiB
Ray vs capsule: the near-parallel branch
This note explains the det < FLT_EPSILON block inside b3RayCastCapsule
(src/capsule.c). That block is the fallback used when the ray is almost parallel
to the capsule axis, where the normal closest-point solve falls apart numerically.
float det = 1.0f - a12 * a12;
if ( det < FLT_EPSILON )
{
// Ray nearly parallel to the capsule axis...
b3Vec3 perp = b3MulSub( a2, a12, a1 ); // a2 - a12*a1
float perp2 = b3LengthSquared( perp );
float beta = b3Dot( sc, perp );
float gamma = sc2 - r * r;
float disc = beta * beta - perp2 * gamma;
if ( beta >= 0.0f || disc < 0.0f )
{
return output; // miss
}
tr = gamma / ( -beta + sqrtf( disc ) ); // near intersection distance
}
1. What is already known when we reach this block
b3RayCastCapsule casts a ray against a capsule (a cylinder capped by two
hemispheres). By the time we reach line 232, several things are settled:
| symbol | meaning | code |
|---|---|---|
c1, c2 |
the two capsule centers (ends of the core segment) | shape->center1/2 |
r |
capsule radius | shape->radius |
axis = a1 |
unit vector along the capsule axis, c2 − c1 normalized |
line 127 |
s |
ray origin relative to c1 |
line 123 |
u |
how far the origin projects along the axis, dot(s, a1) |
line 130 |
sc |
the part of s perpendicular to the axis (axis → origin) |
line 136 |
sc2 |
` | sc |
a2 = rayAxis |
unit ray direction | line 177 |
a12 |
dot(a1, a2), the cosine of the angle between ray and axis |
line 226 |
Two facts from the code above this branch matter a lot here:
- The origin is outside the infinite cylinder. The earlier
sc2 < r*rtest (line 142) already handled the inside case and returned. So heresc2 ≥ r². - The ray has nonzero length and was not rejected by the projected-extent early out (line 187).
det = 1 − a12². Since a12 is the cosine of the angle between the two unit axes,
det = 1 − cos²θ = sin²θ. It is the squared sine of the angle between the ray and
the capsule axis.
2. Why a special case at all
The general path (the else branch, lines 258–288) solves for the closest points
between the infinite ray and the infinite axis with Cramer's rule, dividing by
det:
float invDet = 1.0f / det;
float t1 = ( sa1 - a12 * sa2 ) * invDet;
float t2 = ( a12 * sa1 - sa2 ) * invDet;
When the ray is nearly parallel to the axis, θ → 0, so det = sin²θ → 0 and
1/det → ∞. Every quantity computed through invDet is multiplied by a huge,
rounding-amplified number. The "closest point on the axis" becomes meaningless, and
a ray that is slowly closing in on the capsule side can be missed entirely.
FLT_EPSILON (≈ 1.19e-7) is the cutoff, and the threshold is not arbitrary. det
is computed as 1 − a12*a12 with a12 ≈ 1, a subtraction of two nearly-equal
numbers. Its absolute rounding error is about one ulp of 1.0, i.e. FLT_EPSILON. So
once the true det shrinks to ~FLT_EPSILON, the computed det has essentially no
correct bits left, and 1/det (> 8 million here) faithfully amplifies that garbage.
Below the cutoff we branch to a method that never forms 1/det.
3. The idea: collapse the axis and solve ray-vs-circle
When the ray is almost parallel to the axis, the interesting motion is not along the axis, it is the slow drift across it. So drop the axis component entirely and work in the 2D plane perpendicular to the axis.
In that plane:
- The infinite cylinder becomes a circle of radius
r. - The capsule axis collapses to a single point (the circle's center).
- The ray origin projects to a point at distance
√sc2 > r(outside the circle). - The ray's direction projects to the in-plane velocity
perp.
The 3D "ray vs infinite cylinder" problem becomes the flat "ray from an outside
point hits a circle" problem, which has no det in it.
4. Line by line
perp = b3MulSub( a2, a12, a1 ) → a2 − a12·a1
This is the ray direction with its along-axis part removed: the component of a2
perpendicular to the axis. The comment notes you could also get a perpendicular
vector with a cross product, but subtracting the parallel part is cheaper and is
exactly the in-plane velocity we want. It is dimensionless (built from unit vectors).
A useful identity: because a1 and a2 are unit vectors,
|perp|² = |a2 − a12·a1|²
= 1 − 2·a12² + a12²
= 1 − a12²
= det
So perp2 is mathematically the same tiny number as det. That is fine — we
never divide by it in the end (see §6); it only appears multiplied into disc,
where being tiny does no harm.
perp2 = b3LengthSquared( perp )
The squared length of that in-plane velocity. Equal to det, as just shown.
beta = b3Dot( sc, perp )
Project the origin's perpendicular offset sc onto the in-plane velocity perp.
sc has length units and perp is dimensionless, so beta carries length units.
Its sign is what matters: beta is half the rate of change of the squared distance
to the axis at the start of the ray. beta < 0 means the projected point is moving
toward the axis; beta ≥ 0 means it is moving away (or tangent).
gamma = sc2 − r*r
How far outside the cylinder the origin sits, in squared-length units. Because the
origin is outside, gamma ≥ 0.
disc = beta*beta − perp2*gamma
The discriminant of the quadratic derived in §5. Sign units are length². If it is
negative, the (infinite) ray never gets within r of the axis.
The early out: if ( beta >= 0.0f || disc < 0.0f ) return
Two distinct ways to miss:
beta ≥ 0— the origin is already outside and the ray is heading away from the axis (or running tangent to it). It will never come back, so no side hit.disc < 0— the ray's closest approach to the axis is still more thanraway. The infinite cylinder is never reached.
tr = gamma / ( -beta + sqrtf( disc ) )
The distance along the ray (in length units, since a2 is a unit vector) to the
near intersection with the infinite cylinder — where the ray first crosses into
the circle. The unusual algebraic form is deliberate; §6 explains it.
5. Where the quadratic comes from
Walk a point along the ray and ask when its perpendicular distance to the axis equals
r. Relative to c1, the ray point at distance tr is s + tr·a2. Its component
perpendicular to the axis is the sum of the perpendicular parts of each term:
perp_offset(tr) = sc + tr·perp
(sc is the perpendicular part of s; perp is the perpendicular part of a2.)
Set its squared length equal to r²:
|sc + tr·perp|² = r²
sc2 + 2·tr·(sc·perp) + tr²·|perp|² = r²
perp2·tr² + 2·beta·tr + gamma = 0 (gamma = sc2 − r²)
A plain quadratic A·tr² + B·tr + C = 0 with A = perp2, B = 2·beta, C = gamma.
Its discriminant (over 4) is beta² − perp2·gamma, i.e. disc. The two roots are the
entry and exit distances of the ray through the infinite cylinder; we want the near
(entry) one.
6. Why the root is written gamma / (−beta + √disc)
The textbook near root of perp2·tr² + 2·beta·tr + gamma = 0 is
tr = (−beta − √disc) / perp2
This is a trap exactly in the regime we are in:
perp2 = detis tiny, so dividing by it amplifies error.- As the ray approaches parallel,
perp2·gamma → 0, sodisc → beta²and√disc → |beta|. Since we already passed thebeta ≥ 0test, herebeta < 0, so|beta| = −beta. The numerator−beta − √disc → −beta − (−beta) = 0: a catastrophic cancellation. The expression collapses to0 / 0.
Multiply numerator and denominator by the conjugate (−beta + √disc) (equivalently,
use the product-of-roots identity tr_near · tr_far = gamma / perp2):
tr = gamma / (−beta + √disc)
Now the denominator is a sum of two positive quantities (−beta > 0 and
√disc ≥ 0), so there is no cancellation, and perp2 has vanished from the
expression — no division by the tiny determinant. Because gamma ≥ 0 and the
denominator is > 0, the result satisfies tr ≥ 0 automatically.
This mirrors the same trick used elsewhere in the file: b3RayCastSphere and the
else branch here both intersect relative to the closest point precisely to dodge
this kind of round-off.
Limiting sanity check. If the ray is exactly parallel (a12 = 1), then
perp = a2 − a1 = 0, so perp2 = 0 and beta = dot(sc, 0) = 0. The beta ≥ 0
test fires and we return a miss — the correct answer, since a parallel ray that
starts outside the cylinder can only ever hit an endcap, never the side. The
division is never reached, so perp2 = 0 is harmless.
7. Units recap
Everything stays dimensionally consistent, which is a quick way to sanity-check the algebra:
| quantity | units |
|---|---|
perp, perp2, a12, det |
dimensionless |
beta = sc·perp |
length |
gamma = sc2 − r² |
length² |
disc = beta² − perp2·gamma |
length² |
tr = gamma / (−beta + √disc) |
length² / length = length |
tr is a true distance along the ray, not a fraction — the same convention the rest
of the function uses before the final fraction is formed.
8. What happens to tr afterward
Both branches (parallel and general) converge on the same tail code, which treats
tr as a candidate hit distance on the infinite cylinder and then decides what
the capsule actually does there:
- Range check (line 291): reject if
tr < 0or beyond the ray's max length. - Map to the axis (line 297):
tc = u + tr·a12is where the hit projects along the axis, measured fromc1. - Endcap handoff: if
tc < 0the hit is past thec1end, so cast against the sphere atc1; iftc > length, cast against the sphere atc2. This is how the near-parallel case still reports endcap hits correctly. - Side hit (lines 324–333): otherwise the hit is genuinely on the cylindrical
wall. Compute the point
c1 + s + tr·a2, the outward normal (the point minus its projection onto the axis, normalized), and the fraction.
So this whole block has one job: produce a numerically trustworthy tr for the
cylinder intersection when the ray is nearly parallel. The shared tail does the rest.
Figures
The three SVGs referenced above live in docs/images/:
rc_parallel_setup.svg— side view: why the parallel case is hard.rc_parallel_crosssection.svg— the 2D reduction to ray-vs-circle.rc_parallel_quadratic.svg— the quadratic, its roots, and the cancellation fix.