Tensor-native 3D box camera certificates #
This module is TorchLean's tensor-native camera-box certificate implementation.
Cube R-CNN, SAM 3D, and related systems can be treated as untrusted producers of tensors. This checker verifies the geometric contract of one exported artifact:
- a camera projection matrix
P : Tensor α (shape![3,4]); - eight 3D cuboid corners
corners : Tensor α (shape![8,3]); - image dimensions; and
- a claimed 2D enclosing box.
The checker recomputes the pinhole projection of every 3D corner and checks:
- every projected corner has positive camera depth;
- every projected pixel lies inside the image bounds; and
- the claimed 2D box itself is inside the image;
- the claimed 2D box encloses all projected corners, up to an explicit tolerance.
Why this shape?
Real 3D perception systems already speak tensors: Cube R-CNN / Omni3D predictions, PyTorch3D
utilities, and SAM-3D-style post-hoc metadata all move around matrices, points, boxes, and camera
parameters. So this module uses Spec.Tensor throughout instead of introducing a detached Vec3
island. The few abbrevs below are only names for tensor shapes.
Small interval arithmetic layer #
A closed scalar interval [lo, hi].
This intentionally stays compact: it is just enough to state and prove camera-parameter uncertainty theorems without pulling the 3D demo into a much larger interval-analysis framework.
- lo : α
Lower endpoint.
- hi : α
Upper endpoint.
Instances For
Membership in a closed scalar interval.
Instances For
The interval has nonnegative lower endpoint, hence all members are nonnegative.
Instances For
Interval addition: [a,b] + [c,d] = [a+c, b+d].
Instances For
Interval multiplication for nonnegative intervals:
[a,b] * [c,d] = [a*c, b*d] when both intervals are nonnegative.
Instances For
Interval division for a nonnegative numerator interval and a strictly positive denominator interval:
[a,b] / [c,d] = [a/d, b/c] when 0 ≤ a and 0 < c.
This is the perspective-division primitive. A pinhole projection is not just affine camera
arithmetic; it also divides homogeneous pixel numerators by positive depth. Keeping this operation
separate makes the trust boundary explicit: an exporter may provide interval enclosures for
u_num, v_num, and z, and Lean proves the quotient enclosure is sound.
Instances For
Soundness of interval addition.
Soundness of nonnegative interval multiplication.
If I and J have nonnegative lower endpoints, then multiplication is monotone over both
intervals: x ∈ I, y ∈ J implies x*y ∈ [I.lo*J.lo, I.hi*J.hi].
Soundness of perspective-style interval division.
If x ∈ num, z ∈ den, num is nonnegative, and the denominator interval is bounded away from
zero, then x / z lies in [num.lo / den.hi, num.hi / den.lo].
This theorem is the mathematical core behind the "full uncertainty envelope" for 3D boxes: depth uncertainty is handled by a certified quotient, not by an informal post-processing check.
Pinhole x-coordinate interval from uncertain intrinsics and normalized coordinate.
For u = fx * xn + cx, with fx ≥ 0 and xn ≥ 0, interval arithmetic gives:
u ∈ fxI*xnI + cxI.
Instances For
Soundness of the one-axis pinhole interval formula.
This is the camera-parameter uncertainty theorem used by the 3D geometry certificate workflow: if focal length,
principal point, and normalized coordinate are each inside certified intervals, then the resulting
pixel coordinate is inside the interval computed by pinholePixelInterval.
A pair of x/y pixel intervals enclosing a projected point under camera uncertainty.
- x : ScalarInterval α
Pixel-x interval.
- y : ScalarInterval α
Pixel-y interval.
Instances For
A concrete pixel lies inside a 2D pixel interval.
Instances For
Pixel interval obtained from homogeneous camera-coordinate intervals.
Here uNumI and vNumI enclose the first two rows of P * [X,Y,Z,1], while zI encloses the
positive depth row. The actual projected pixel is (u_num / z, v_num / z).
This formulation matches real exported tensors better than a detached Vec3 API: camera matrices,
3D corners, and interval bounds can all be produced by the same tensor pipeline, and Lean proves the
final quotient/bbox claim.
Instances For
A 3D point as a tensor of shape [3].
Instances For
A 2D point as a tensor of shape [2].
Instances For
Eight cuboid corners, stored as a tensor of shape [8, 3].
Instances For
A 3×4 camera projection matrix.
For a homogeneous point [X,Y,Z,1], the raw camera coordinates are:
u_num = P₀·[X,Y,Z,1], v_num = P₁·[X,Y,Z,1], z = P₂·[X,Y,Z,1].
The projected pixel is (u_num / z, v_num / z), checked only when z > 0.
Instances For
Projected eight-corner tensor of shape [8, 2].
Instances For
A 2D box [xmin, ymin, xmax, ymax].
Instances For
Matrix scalar accessor for tensor-shaped matrices.
Instances For
Vector scalar accessor for tensor-shaped vectors.
Instances For
Extract the i-th cuboid corner as a [3] tensor.
Instances For
Build a matrix tensor from a coordinate function. Useful for small fixtures.
Instances For
Build a vector tensor from a coordinate function. Useful for small fixtures.
Instances For
Project all eight cuboid corners.
Instances For
A compact exported 3D-box/camera certificate.
- width : α
Image width in pixels.
- height : α
Image height in pixels.
- tol : α
Tolerance used when checking the claimed enclosing box.
- camera : CameraP α
3×4 camera projection matrix.
- corners : BoxCorners α
Eight exported 3D cuboid corners.
- bbox : Box2D α
Claimed 2D box
[xmin,ymin,xmax,ymax].
Instances For
Claimed 2D box left edge.
Instances For
Claimed 2D box top edge.
Instances For
Claimed 2D box right edge.
Instances For
Claimed 2D box bottom edge.
Instances For
The pixel interval is contained in the claimed 2D box.
Instances For
If a pixel interval is contained in the claimed bbox, every concrete pixel inside that interval is also contained in the bbox.
Full pinhole-intrinsics interval-to-bbox theorem.
Assume independent intervals for focal lengths (fx, fy), normalized coordinates
(xn = X/Z, yn = Y/Z), and principal point (cx, cy). If the interval arithmetic result
u ∈ fxI*xnI + cxI, v ∈ fyI*ynI + cyI
is contained in the claimed bbox, then every concrete camera/pixel choice satisfying those input intervals projects inside the bbox.
This is the full uncertainty-envelope bridge for the camera-uncertainty workflow: uncertainty begins at camera
intrinsics and normalized camera coordinates, propagates through the pinhole equations, and ends as
a certified bbox-enclosure statement. The theorem is phrased over normalized coordinates so callers
can plug in whichever depth-interval or model-uncertainty method they use to bound X/Z and Y/Z.
Full homogeneous projection interval-to-bbox theorem.
This is the stronger robustness theorem. Instead of assuming the projected pixel has already been bounded, it starts from intervals over the homogeneous camera outputs:
uNumIencloses the x numeratorP₀ · [X,Y,Z,1];vNumIencloses the y numeratorP₁ · [X,Y,Z,1]; andzIencloses the positive depth denominatorP₂ · [X,Y,Z,1].
If the quotient intervals [uNumI.lo / zI.hi, uNumI.hi / zI.lo] and
[vNumI.lo / zI.hi, vNumI.hi / zI.lo] are inside the claimed 2D box, then every concrete camera
projection represented by those intervals is inside the box. This is exactly the guard we want for
uncertain camera intrinsics/extrinsics, bounded corner perturbations, or mixed numeric backends:
they may produce ranges for homogeneous coordinates, but Lean checks the perspective divide and
the final bbox containment.
Projected x-coordinate of corner i.
Instances For
Projected y-coordinate of corner i.
Instances For
Camera depth of corner i.
Instances For
Mathematical certificate predicates #
Image dimensions must be positive.
Instances For
Basic sanity for the reported 2D box and tolerance.
Instances For
The reported 2D box itself should lie inside the image frame.
Instances For
Every 3D corner lies in front of the camera.
Instances For
Robust projection predicates #
The single-artifact checker above says the exported projection is coherent at one numeric point. For real model outputs we also want robustness statements around that point.
There are two complementary robustness layers in this file:
homogeneous_projection_interval_inside_bbox_soundstarts from intervals over homogeneous camera outputs(u_num, v_num, z)and proves the perspective-divided pixels stay inside the claimed box.bbox_encloses_perturbed_of_marginstarts from a nominal projected pixel and proves that any bounded pixel-space perturbation stays inside the claimed box if there is enough slack.
Together they cover the two most common exporter contracts: interval-enclosed camera arithmetic and bounded downstream pixel perturbation.
The projected corners are inside the claimed 2D box with an explicit positive slack margin.
Compared with BBoxEnclosesProjection, this predicate is stricter: corners must land inside
[xmin + margin, xmax - margin] × [ymin + margin, ymax - margin]. The margin is what pays for
future uncertainty.
Instances For
px, py describe an interval-perturbed projection of every corner.
For each corner i, px i and py i are some possible projected coordinates after exporter,
renderer, rounding, or uncertainty perturbation. This predicate says those coordinates are within
eps pixels of the nominal projection recomputed from the certificate.
Instances For
The claimed 2D box encloses every perturbed projected corner.
This is the robust postcondition downstream consumers want: even after a bounded perturbation, the candidate 3D artifact still projects inside the detector's claimed 2D box.
Instances For
Projection-interval robustness theorem.
If every nominal projected corner has at least margin pixels of slack inside the box, and every
perturbed projection is within eps ≤ margin pixels of that nominal projection, then all perturbed
projections remain inside the original claimed 2D box.
This is deliberately independent of how the perturbation was produced: it can come from Float rounding, a renderer approximation, a model uncertainty interval, or an external exporter. The theorem is the certified geometry guard.
The end-user theorem-facing statement.
This says the exported detector artifact is internally coherent under its stated camera model: positive image dimensions, ordered in-frame 2D box, positive camera depth, projected corners inside the image, and claimed 2D box enclosure.
Instances For
Boolean checker and soundness theorems #
Boolean check for positive image dimensions.
Instances For
Boolean check for BBoxOrdered.
Instances For
Boolean check for BBoxInsideImage.
Instances For
Boolean check for PositiveDepths.
Instances For
Boolean check for ProjectedInImage.
Instances For
Boolean check for BBoxEnclosesProjection.
Instances For
Full Boolean checker for one exported 3D-box/camera artifact.
Instances For
Soundness of the executable checker.
This is the main theorem for the implementation: if the Boolean checker accepts an artifact, the
artifact satisfies the mathematical Verified3DBox predicate.
Consequence theorems for verified artifacts #
Float JSON checker for exported artifacts #
Expected schema string for JSON artifacts accepted by this checker.
Instances For
Tensor from a flat array. The caller is responsible for checking the length.
Instances For
Vector tensor from a flat array. The caller is responsible for checking the length.
Instances For
Parse a JSON artifact into the Float checker representation.
Instances For
Load and check a JSON 3D-box/camera certificate.
This is the bridge to Cube R-CNN/SAM-3D-style outputs. The JSON is untrusted; Lean recomputes the projection and accepts only if the tensor artifact passes the checker.
Instances For
Convenience wrapper for CLI fixtures.