box3d/docs/raycast_capsule_parallel.md
Erin Catto 69037feaba
Build polish (#18)
Improve build process and documentation.
Improved ray versus capsule accuracy.
UI improvements
2026-06-28 10:44:34 -07:00

11 KiB
Raw Blame History

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*r test (line 142) already handled the inside case and returned. So here sc2 ≥ 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.

Side view of the near-parallel configuration


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.

Cross-section perpendicular to the axis


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 than r away. 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.

The quadratic and its roots


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 = det is tiny, so dividing by it amplifies error.
  • As the ray approaches parallel, perp2·gamma → 0, so disc → beta² and √disc → |beta|. Since we already passed the beta ≥ 0 test, here beta < 0, so |beta| = −beta. The numerator −beta − √disc → −beta − (−beta) = 0: a catastrophic cancellation. The expression collapses to 0 / 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:

  1. Range check (line 291): reject if tr < 0 or beyond the ray's max length.
  2. Map to the axis (line 297): tc = u + tr·a12 is where the hit projects along the axis, measured from c1.
  3. Endcap handoff: if tc < 0 the hit is past the c1 end, so cast against the sphere at c1; if tc > length, cast against the sphere at c2. This is how the near-parallel case still reports endcap hits correctly.
  4. 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.