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 α [3,4]; - a configurable number of 3D points
corners : Tensor α [pointCount,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.
Eight points are the default for a cuboid. The contract covers every supplied point; it does not assert that those points form a cuboid. The JSON parser rejects an artifact with no points, since the pointwise conditions would then hold vacuously.
Matrices, points, and boxes use the shared tensor API. The interval theorems require ordered-field arithmetic and supplied input enclosures. The JSON workflow instead checks host Float projections of one artifact; it does not establish those uncertainty assumptions or a Float-to-real bridge.
Small interval arithmetic layer #
A closed scalar interval [lo, hi].
Endpoints for the ordered-field camera uncertainty theorems; ordering is required by their membership hypotheses rather than stored in this record.
- 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]=[ac,bd]$ 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\le a$ and $0<c$.
This is the perspective-division primitive. A pinhole projection combines affine camera arithmetic
with division of 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.
If $x\in I$ and $y\in J$, then $x+y\in I+J$.
Soundness of nonnegative interval multiplication.
If I and J have nonnegative lower endpoints, then multiplication is monotone over both
intervals: $x\in I$ and $y\in J$ imply
$xy\in[I_{\mathrm{lo}}J_{\mathrm{lo}},I_{\mathrm{hi}}J_{\mathrm{hi}}]$.
Soundness of perspective-style interval division.
If $x\in\mathrm{num}$, $z\in\mathrm{den}$, $\mathrm{num}$ is nonnegative, and the denominator interval is bounded away from zero, then $x/z\in[\mathrm{num}_{\mathrm{lo}}/\mathrm{den}_{\mathrm{hi}}, \mathrm{num}_{\mathrm{hi}}/\mathrm{den}_{\mathrm{lo}}]$.
Pinhole x-coordinate interval from uncertain intrinsics and normalized coordinate.
For $u=f_xx_n+c_x$, with $f_x\ge 0$ and $x_n\ge 0$, interval arithmetic gives $u\in f_{x,I}x_{n,I}+c_{x,I}$.
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
pinholePixelIntervalNonnegative.
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]^\mathsf{T}$, while zI encloses
the positive depth row. The actual projected pixel is
$(u_{\mathrm{num}}/z,v_{\mathrm{num}}/z)$.
Instances For
A 3D point as a tensor of shape [3].
Instances For
A 3×4 camera projection matrix.
For a homogeneous point $[X,Y,Z,1]$, the raw camera coordinates are:
$$ u_{\mathrm{num}}=P_0\mathbin{\cdot}[X,Y,Z,1],\qquad v_{\mathrm{num}}=P_1\mathbin{\cdot}[X,Y,Z,1],\qquad z=P_2\mathbin{\cdot}[X,Y,Z,1]. $$
The projected pixel is $(u_{\mathrm{num}}/z,v_{\mathrm{num}}/z)$, checked only when $z>0$.
Instances For
A 2D box [xmin, ymin, xmax, ymax].
Instances For
Extract the i-th supplied 3D point as a [3] tensor.
Instances For
Raw homogeneous camera coordinate P[row] · [X,Y,Z,1].
Instances For
Positive-depth denominator used by pinhole projection.
Instances For
A compact exported 3D-box/camera certificate.
- pointCount : ℕ
Number of exported 3D points; a cuboid uses eight.
- 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 : TorchLean.Tensor α [self.pointCount, 3]
Exported 3D points, indexed by the declared count.
- bbox : Box2D α
Claimed 2D box
[xmin,ymin,xmax,ymax].
Instances For
Left edge xmin of the claimed 2D bounding box.
Instances For
Top edge ymin of the claimed 2D bounding box.
Instances For
Right edge xmax of the claimed 2D bounding box.
Instances For
Bottom edge ymax of the claimed 2D bounding box.
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.
Pinhole-intrinsics interval-to-bbox theorem for nonnegative normalized coordinates.
Assume independent intervals for focal lengths (fx, fy), normalized coordinates
$x_n=X/Z$ and $y_n=Y/Z$, and principal point (cx, cy). If the interval arithmetic result
$u\in f_{x,I}x_{n,I}+c_{x,I}$ and $v\in f_{y,I}y_{n,I}+c_{y,I}$
is contained in the claimed bbox, then every concrete camera/pixel choice satisfying those input intervals projects inside the bbox.
This is a quadrant-restricted uncertainty bridge: 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.
Homogeneous projection interval-to-bbox theorem for nonnegative numerators.
Instead of assuming the projected pixel has already been bounded, it starts from intervals over the homogeneous camera outputs:
uNumIencloses the x numerator $P_0\mathbin{\cdot}[X,Y,Z,1]$;vNumIencloses the y numerator $P_1\mathbin{\cdot}[X,Y,Z,1]$; andzIencloses the positive depth denominator $P_2\mathbin{\cdot}[X,Y,Z,1]$.
If the quotient intervals $[u_{\mathrm{lo}}/z_{\mathrm{hi}},u_{\mathrm{hi}}/z_{\mathrm{lo}}]$ and $[v_{\mathrm{lo}}/z_{\mathrm{hi}},v_{\mathrm{hi}}/z_{\mathrm{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
Validate 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
Every projected corner lies inside the image rectangle.
Instances For
The reported 2D box encloses all projected 3D corners, up to tolerance.
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_nonnegative_interval_inside_bbox_soundstarts from nonnegative 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 slack margin.
Compared with BBoxEnclosesProjection, this predicate is stricter: corners must land inside
$[x_{\min}+\mathrm{margin},x_{\max}-\mathrm{margin}] \times[y_{\min}+\mathrm{margin},y_{\max}-\mathrm{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 $\varepsilon\le\mathrm{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 checked 3D box statement exposed by the certificate workflow.
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
Acceptance by the image-size check yields the corresponding positive-size proposition.
Acceptance by the box-order check yields ordered horizontal and vertical endpoints.
Acceptance by the containment check places every claimed box edge inside the image.
Acceptance by the depth check proves that all supplied points are in front of the camera.
Acceptance by the projection check places every projected corner within the image rectangle.
Acceptance by the enclosure check places every projected corner inside the claimed box tolerance.
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 #
A verified artifact necessarily has positive image width and height.
The claimed 2D bounding box of a verified artifact lies within its image dimensions.
Every corner of a verified artifact has positive camera-space depth.
Every projected corner of a verified artifact lies within the image rectangle.
Every projected corner lies within the verified artifact's claimed box, up to its tolerance.
Float JSON checker for exported artifacts #
Schema string for camera-box artifacts. An artifact declares point_count, which must be positive
and match the number of triples in corners3d; a cuboid declares 8.
Instances For
Parse a certificate, rejecting malformed tensor dimensions and non-finite values.
The artifact must declare a positive point_count with corners3d.size = 3 * point_count. An
artifact with no points is rejected, since every pointwise condition would hold vacuously.
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
Check a camera-box certificate and raise a readable CLI error if it is rejected.