back

ffmpeg with still image formats:
equirectangular panorama to
cubemap and cube faces and back.

FFmpeg is the leading multimedia framework, able to decode, encode, transcode, mux, demux, stream, filter and play pretty much anything that humans and machines have created. It supports the most obscure ancient formats up to the cutting edge. No matter if they were designed by some standards committee, the community or a corporation.
Thanks FFmpeg Dev.

I started to use the open source command line tool, "ffmpeg" version 4.3.1 (now 6.1) in panoramic photography. The scripts should work for Mac and Linux, and with adjustments PC, see "info".



equirectangular.jpg

I've added a set of 6 small (480x480 px) cubic faces and an equirectangular (1920x960 px) in .tif, download: "cube.zip"

The new filter "v360" converts 360° videos/images between various formats. Here I'm converting an equirectangular panorama to a cubemap (strip) in 6x1 format (horizontal).
ffmpeg v360 filter
v360 filter, cubemap face names: right 'r', left 'l', up 'u', down 'd', forward 'f', back 'b'. Default value is 'rludfb'. Any order is possible (but not usable). To get the forward cubemap face placed first in the cubemap, set order thus:
ffmpeg -i eq.tif -vf "v360=input=e:output=c6x1:out_forder=fbrlud" cubemap_fbrlud.tif



cubemap_fbrlud.jpg

"input=" and "output=" are optional, "e" can also be written "equirect" for equirectangular, here the forward cubemap face will be placed last:
ffmpeg -i eq.tif -vf "v360=equirect:c6x1:out_forder=brludf" cubemap_brludf.tif



eq.gif   Going through the cube face names in default order 'rludfb'.

Make a new folder "dir" and untile the cubemap six faces into it:
ffmpeg untile filter
ffmpeg -i cubemap.tif -vf "untile=6x1" dir/%d.tif
or keep the "brlud" part of the cubemap intact, from a cubemap of 2880x480 px:
ffmpeg -i cubemap_brludf.tif -vf "crop=2400:480:0:0" brlud.tif

To extract the forward cube face, from a cubemap of 2880x480 px. (Or use the untile filter.)
ffmpeg crop filter
and here are good examples of cropping
ffmpeg -i cubemap.tif -vf "crop=480:480:1920:0" face05f.tif

Reassemble the cubemap:
ffmpeg tile filter
v360 filter, cubemap face names: right 'r', left 'l', up 'u', down 'd', forward 'f', back 'b'. Default value is 'rludfb'. Extract each cubemap and rename right to 1.tif, left to 2.tif etc. Then reassemble them.
ffmpeg -i dir/%d.tif -filter_complex "tile=6x1" dir/cubemap01.tif
or
ffmpeg -i dir/1.tif -i dir/2.tif -i dir/3.tif -i dir/4.tif -i dir/5.tif -i dir/6.tif -filter_complex 'hstack=inputs=6' dir/cubemap01.tif

The v360 filter can convert the cubemap back to equirectangular:
ffmpeg -i cubemap01.tif -vf "v360=c6x1:e" equirectangular01.png

Any valid cubemap horizontal strip order: "rludfb" (default), "ludfbr", "udfbrl", "dfbrlu", "fbrlud" or "brludf" gives the same resulting equirectangular image, no horizontal (yaw) change.

To shift the equirectangular image horizontally, use yaw (in degrees):
ffmpeg -i equirectangular01.png -vf "v360=input=e:output=e:yaw=90" equirectangular_90.png
Yaw will offset (wrap around) pixels from one side of the equirectangular image to the other. Range -180 to 180.
So, combined with the former script:
ffmpeg -i cubemap01.tif -vf "v360=c6x1:e:yaw=90" equirectangular_90.png



equirectangular_90.jpg, offset 90° horizontally, compare with the equirectangular at the top of this page.

 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
The ffmpeg filter v360 cubemap order 'rludfb' is used in 'OpenGL', 'Unity', 'NVIDIA Texture Tools Exporter', 'Samsung Gear VR', etc., it's origin might be 'Pixar’s PhotoRealistic RenderMan'.

It is not the same order as used by Adobe, Apple, Black Magic Design's DaVinci Resolve / Fusion, Hugin, Pano2VR, Panotools, PTGui, Quake II or RealViz: try 'frblud' ('lrudbf' in Black Magic Design) if you need to use cubemap in these tools. Tell me if I made any errors. Example: "change cubemap order"
 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Alexander Refsum Jensenius shows a good use of this here:
Pre-processing Garmin VIRB 360 recordings with FFmpeg

Now in January 2024, I'm using ffmpeg 6.1, GNU bash v. 5.2 and zsh 5.9 on MacOS Ventura 13.6.3, Apple M1.

back