FFmpeg: Unexpected Image Rotation with Overlay and Arbitrary Angle

To fix unexpected image rotation with overlays in FFmpeg, you must use the correct mathematical constant M_PI instead of PI and calculate the output dimensions properly to prevent cropping. The standard approach involves using the rotate filter with a valid expression for the angle and ensuring the bounding box calculation accounts for the rotated width and height. This ensures the overlay remains fully visible without distortion or unexpected shifting during the compositing process.

Correcting Mathematical Constants

One of the most common reasons for failure when rotating images arbitrarily is the misuse of mathematical constants. In FFmpeg’s filter graph expressions, the variable PI is not defined by default. Attempting to use PI/4 will result in an error because the parser does not recognize PI. Instead, you must use the built-in constant M_PI, which represents the value of pi (approximately 3.14159). For example, if you want to rotate an image by 45 degrees, you should express this as M_PI/4. Using PI/4 will cause the command to fail immediately. This distinction is critical for any arbitrary angle calculation within the filter chain. Always verify that your expressions use M_PI when trigonometric functions or angular calculations are involved.

Calculating Output Dimensions Correctly

Another frequent source of issues is incorrect bounding box calculation. When you rotate an image, the bounding box that contains the rotated content changes size. A common mistake is using ow=iw+oh to define the output width. This formula is mathematically incorrect for determining the bounding box of a rotated rectangle. The correct way to calculate the new width (ow) and height (oh) depends on whether the rotation angle causes the original width or height to become the dominant dimension. For a general arbitrary rotation, you can use the following logic:

• If the absolute difference between the sine and cosine of the angle is small, the bounding box is roughly the same as the original.
• However, for precise control, FFmpeg provides variables iw (input width) and ih (input height).

A robust method is to let FFmpeg auto-size the output by omitting explicit ow and oh assignments in simple cases, or using the rotate filter's ability to expand the frame. If you must specify dimensions manually, ensure you account for the hypotenuse of the rotated shape. For instance, if rotating by 45 degrees, the new width and height will be larger than the original. Using ow=iw*sqrt(2) and oh=ih*sqrt(2) is an approximation, but relying on FFmpeg's automatic expansion via the rotate filter is often safer.

Constructing the Filter Graph

The core solution lies in constructing a valid filter graph that combines the rotation and overlay operations correctly. You need to apply the rotation to the input image before compositing it onto the background video or image. Here is a corrected command structure:

ffmpeg -i background.mp4 -i overlay.png -filter_complex "[1:v]rotate=M_PI/4:ow=rotw(M_PI/4):oh=roth(M_PI/4)[rotated];[0:v][rotated]overlay=(W-w)/2:(H-h)/2" -c:a copy output.mp4

In this example:

• [1:v] refers to the second input (the overlay image).
• rotate=M_PI/4 applies a 45-degree rotation using the correct constant.
• ow=rotw(M_PI/4) and oh=roth(M_PI/4) automatically calculate the correct output width and height based on the rotation angle, preventing clipping.
• The overlay filter then places the rotated image onto the background video ([0:v]).

Using rotw() and roth() functions is highly recommended over manual arithmetic because they handle the geometry precisely for any angle. This avoids the errors associated with incorrect formulas like iw+oh.

Handling Transparency and Positioning

When overlaying a rotated PNG with transparency, ensure that the alpha channel is preserved. The overlay filter supports transparency by default if the input format supports it. However, if you notice artifacts or black backgrounds, check that the overlay file actually has an alpha channel. Positioning the overlay after rotation can also be tricky. The coordinates (W-w)/2 and (H-h)/2 center the overlay based on the rotated dimensions. If you want to position it relative to the original unrotated size, you may need to adjust these offsets. Always preview the output with different angles to ensure the positioning logic holds up. For more details on managing overlays, see Adding Green Video Overlay with FFmpeg: Define Interval. This resource explains how to manage overlay timing and placement effectively. Additionally, if you are concerned about quality loss during rotation, refer to FFmpeg Image Rotation Causes Loss of Quality, which discusses interpolation methods to maintain sharpness.

Frequently Asked Questions

Why does my rotation command fail with 'undefined PI'?

FFmpeg does not recognize PI as a variable; it only recognizes M_PI. You must replace all instances of PI with M_PI in your filter expressions to resolve syntax errors.

How do I prevent the image from being cropped during rotation?

Use the rotw() and roth() functions in the rotate filter to automatically calculate the correct bounding box dimensions. This ensures the entire rotated image fits within the output frame without manual calculation errors.

Can I rotate an image by an arbitrary degree value?

Yes, you can use any expression involving M_PI. For example, 30 degrees is M_PI/6, and 90 degrees is M_PI/2. Ensure the expression evaluates to radians, not degrees.

What if the overlay appears blurry after rotation?

Blurry output often results from default interpolation methods. You can specify a higher quality interpolation in the rotate filter by adding interp=bilinear or interp=linear to improve sharpness, though this may impact performance.

Does the order of filters matter in the complex graph?

Yes, always apply rotation to the specific stream (e.g., [1:v]rotate=...) before combining it with other streams in the overlay filter. Applying rotation after overlaying can lead to unexpected coordinate shifts and alignment issues.