Skip to content

fix(geometry): compute radial peak when k2 is zero - #649

Open
0z5a wants to merge 1 commit into
mapillary:mainfrom
0z5a:fix/radial-peak-k2-zero
Open

0z5a wants to merge 1 commit into
mapillary:mainfrom
0z5a:fix/radial-peak-k2-zero

Conversation

@0z5a

@0z5a 0z5a commented Nov 16, 2026 •

Copy link
Copy Markdown

Motivation

makeRadialPeak(k1, k2) finds the radius where the distorted radius r * (1 + k1 r^2 + k2 r^4) stops increasing. Projection clamps at that radius so that points past it do not fold back into the image (see 8a8f04d, "handle peaking radial distortion function"). It gets the radius by solving 5 k2 u^2 + 3 k1 u + 1 = 0 with the quadratic formula, which divides by a = 5 k2. When k2 === 0 the roots come out as NaN/Infinity and the function returns "no peak", even though y = r (1 + k1 r^2) with k1 < 0 clearly peaks at r = sqrt(-1 / (3 k1)).

[focal, k1, 0] is a valid perspective/fisheye parameter set, and it is what a single-coefficient radial calibration produces (SliderTransform also pads [focal, k1] to k2 = 0). For a camera like [0.85, -0.2, 0]:

  • radialPeak is Infinity, while k2 = 1e-12 gives 1.29099. The closed form and a brute-force argmax also give 1.29099.
  • A ray 63 degrees off-axis, well outside the field of view, projects to x = 0.383, which is inside the image. The clamped value is 0.85 * tan(63°) * 2/3 = 1.112.
  • For a wider k1-only camera, [0.55, -0.28, 0], unprojecting and then projecting the image corner [-0.5, -0.375] returns [124.3, 93.2].

The same value goes to the radialPeak shader uniform, and the slider transform has its own copy of the computation with the same problem.

Images reconstructed by the Mapillary platform normally have a nonzero k2, so this mostly affects camera parameters from other sources, e.g. a k1-only calibration passed in through a custom DataProviderBase.

Have you read the Contributing Guidelines?

Yes. I have completed the CLA.

Contribution

  • makeRadialPeak in src/geometry/Common.ts: when k2 === 0, return sqrt(-1 / (3 k1)) for negative k1 and Infinity otherwise.
  • SliderTransform._getRadialPeak: same branch, keeping that file's undefined for "no peak".

The k2 !== 0 path is unchanged.

Test Plan

  • Added PerspectiveCamera.radialPeak, FisheyeCamera.radialPeak and SliderTransform radial peak tests:
    • the peak value for k2 = 0
    • continuity with k2 = 1e-12
    • clamped projection of a ray past the peak
    • the corner round trip
    • controls showing k1 >= 0 still has no peak
  • 7 of the new tests fail on main and all pass with the change.
  • yarn test: 129 suites, 1745 tests pass.
  • tslint with the repo's config (config/tslint.json, as used by yarn lint) passes on the changed files.

The visual example includes a runnable provider and matching before-and-after screenshots for the main camera and slider.

makeRadialPeak solved 5 k2 u^2 + 3 k1 u + 1 = 0 with the quadratic formula, which divides by 5 k2, so k2 === 0 returned no peak even though r (1 + k1 r^2) peaks at sqrt(-1 / (3 k1)) for k1 < 0. Points past the peak then folded back into the image. Handle the linear case in makeRadialPeak and in SliderTransform._getRadialPeak.
@meta-cla meta-cla Bot added the cla signed label Nov 16, 2026
@borismasis

Copy link
Copy Markdown
Member

Thanks for the clear explanation and regression tests. The fix looks sensible from code inspection.

Could you add a reproducible visual example showing the issue this fixes?

  • An affected image or runnable custom-data-provider example, including the camera type and [focal, k1, k2] parameters.
  • Before/after screenshots at the same viewer settings, highlighting the rendering artifact.
  • A slider before/after example too, since this changes SliderTransform as well as the main camera geometry.

Given your note that Mapillary-reconstructed images normally have nonzero k2, a custom-provider example using a synthetic grid image is fine if there is no affected production image. This would help us verify the rendered result alongside the numerical tests.

@0z5a

0z5a commented Nov 17, 2026

Copy link
Copy Markdown
Author

Added a runnable custom provider and four screenshots. With the same perspective camera, viewport and zoom, the vertical field of view changes from 63.91° to 81.04° in both the viewer and the slider.

@borismasis

Copy link
Copy Markdown
Member

Thanks! The images show a real change, but not a clear “broken image becomes correct” demonstration.

These screenshots support a change in how far you can zoom out for this custom calibration. They don’t directly show the originally described problem of out-of-view content folding back into the image. The “after” also has sharp bends near the sides that need explaining.

The mathematical fix still looks valid, but the visual evidence is incomplete. Can you confirm whether this came from a real camera calibration or was found only with synthetic parameters. Also, could you attach real raw images from the camera so we could get a better sense?

@0z5a

0z5a commented Nov 22, 2026

Copy link
Copy Markdown
Author

To confirm: this was found only with synthetic parameters. I found it by reading makeRadialPeak and checking the k2 === 0 case by hand. I don't have a real camera calibration with k2 = 0 and I don't have raw images from such a camera, so I can't attach any. The grid images in the example are synthetic too.

On the sharp bends in the "after" view: that is the clamp from 8a8f04d being applied, not something new in this change. Past radialPeak, project keeps distortion at its value at the peak, so the radial mapping switches from the polynomial to a plain scale. The value is continuous there, but the slope is not, and that shows up as a bend in the grid. A camera with a small nonzero k2 already gets the same bend on main. For example, [0.55, -0.28, 1e-12] has its peak at the same radius, and the new continuity test checks that k2 = 0 now gives the same peak as k2 = 1e-12. Without the fix, k2 = 0 gets no clamp at all, while a nearly identical k2 does.

You're right that the screenshots show the wider field of view more clearly than the fold-back. If the change isn't worth taking without a real affected camera, I understand, and I'm fine with closing it.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants