FFmpeg Lens Correction for Fisheye Video

This article explains how to remove fisheye and wide-angle barrel distortion from video footage using FFmpeg's built-in lenscorrection filter. It covers the core mathematical parameters of the filter, practical command-line examples, methods for previewing your adjustments in real time, and techniques for cropping out the resulting curved borders.

Understanding the lenscorrection Filter

The lenscorrection filter corrects radial distortion caused by wide-angle and fisheye lenses. It calculates the displacement of pixels relative to the optical center of the image based on four main parameters:

  • cx: The horizontal center of distortion, expressed as a fraction of the total width. The default is 0.5 (the exact center).
  • cy: The vertical center of distortion, expressed as a fraction of the total height. The default is 0.5 (the exact center).
  • k1: The correction coefficient for the primary (quadratic) distortion. Positive values correct barrel (fisheye) distortion, while negative values correct pincushion distortion.
  • k2: The correction coefficient for the secondary (edge/quartic) distortion. This fine-tunes the correction at the outer edges and corners of the frame.

Basic Command Syntax

To remove fisheye distortion from an MP4 file, apply the filter via the -vf (video filter) flag:

ffmpeg -i input.mp4 -vf "lenscorrection=cx=0.5:cy=0.5:k1=0.22:k2=0.05" -c:a copy output.mp4

In this command:

  • cx=0.5:cy=0.5 sets the correction point directly in the middle of the frame.
  • k1=0.22 pulls the bulging center inward to flatten straight lines.
  • k2=0.05 provides minor adjustments to the far edges.
  • -c:a copy copies the audio stream without re-encoding to preserve quality and save processing time.

Finding the Correct Values Using ffplay

Testing correction coefficients by rendering full files is inefficient. Use ffplay to preview changes instantly:

ffplay -vf "lenscorrection=k1=0.25:k2=0.08" input.mp4

Adjust the values iteratively:

  1. Start with k2=0 and adjust k1 in increments of 0.05 until vertical elements near the center of the frame (like walls or doorframes) appear straight. Typical values for action cameras range between 0.15 and 0.35.
  2. Once the mid-frame is aligned, increment k2 between 0.01 and 0.15 to straighten curved lines along the extreme edges of the video.

Removing Resulting Black Borders

Flattening a curved image pulls pixels away from the frame boundaries, leaving curved black borders around the edges. You can eliminate these borders by chaining the crop filter immediately after the lenscorrection filter.

For example, to remove fisheye distortion and crop the video to standard 1080p dimensions:

ffmpeg -i input.mp4 -vf "lenscorrection=k1=0.22:k2=0.05,crop=1920:1080" -c:v libx264 -crf 18 -c:a copy output.mp4

Alternatively, crop by percentage to retain the aspect ratio:

ffmpeg -i input.mp4 -vf "lenscorrection=k1=0.2:k2=0.05,crop=iw*0.9:ih*0.9" -c:v libx264 -crf 18 -c:a copy output.mp4

Here, iw*0.9 and ih*0.9 crop 10% from the width and height, centering the frame automatically and removing the distorted margins.