Decoding Image sequences¶

DeFFcode's FFdecoder API supports a wide-ranging media streams as input to its source parameter, which also includes Image Sequences such as Sequential(img%03d.png) and Glob pattern(*.png) as well as Single looping image.

We'll discuss both briefly in the following recipes:

DeFFcode APIs requires FFmpeg executable

DeFFcode APIs MUST requires valid FFmpeg executable for all of its core functionality, and any failure in detection will raise RuntimeError immediately. Follow dedicated FFmpeg Installation doc ➶ for its installation.

Additional Python Dependencies for following recipes

Following recipes requires additional python dependencies which can be installed easily as below:

OpenCV: OpenCV is required for previewing video frames. You can easily install it directly via pip:

OpenCV installation from source

You can also follow online tutorials for building & installing OpenCV on Windows, Linux, MacOS and Raspberry Pi machines manually from its source.

Make sure not to install both pip and source version together. Otherwise installation will fail to work!

Other OpenCV binaries

OpenCV maintainers also provide additional binaries via pip that contains both main modules and contrib/extra modules opencv-contrib-python, and for server (headless) environments like opencv-python-headless and opencv-contrib-python-headless. You can also install any one of them in similar manner. More information can be found here.
```
pip install opencv-python       
```

Always use FFdecoder API's terminate() method at the end to avoid undesired behavior.

Never name your python script deffcode.py

When trying out these recipes, never name your python script deffcode.py otherwise it will result in ModuleNotFound error.

Capturing and Previewing frames from Sequence of images¶

In this example we will capture video frames from a given Image Sequence using FFdecoder API, and preview them using OpenCV Library's cv2.imshow() method in real-time.

OpenCV expects BGR format frames in its cv2.imshow() method.

Extracting Image Sequences from a video

You can use following FFmpeg command to extract sequences of images from a video file foo.mp4:

$ ffmpeg -i foo.mp4 /path/to/image-%03d.png

The default framerate is 25 fps, therefore this command will extract 25 images/sec from the video file, and save them as sequences of images (starting from image-000.png, image-001.png, image-002.png up to image-999.png).

If there are more than 1000 frames then the last image will be overwritten with the remaining frames leaving only the last frame.

The default images width and height is same as the video.

SequentialGlob pattern

How to start with specific number image?

You can use -start_number FFmpeg parameter if you want to start with specific number image:

# define `-start_number` such as `5`
ffparams = {"-ffprefixes":["-start_number", "5"]}

# initialize and formulate the decoder with define parameters
decoder = FFdecoder('img%03d.png', verbose=True, **ffparams).formulate()

# import the necessary packages
from deffcode import FFdecoder
import cv2

# initialize and formulate the decoder with suitable source
decoder = FFdecoder("/path/to/pngs/img%03d.png", frame_format="bgr24", verbose=True).formulate()

# grab the BGR24 frame from the decoder
for frame in decoder.generateFrame():

    # check if frame is None
    if frame is None:
        break

    # {do something with the frame here}

    # Show output window
    cv2.imshow("Output", frame)

    # check for 'q' key if pressed
    key = cv2.waitKey(1) & 0xFF
    if key == ord("q"):
        break

# close output window
cv2.destroyAllWindows()

# terminate the decoder
decoder.terminate()

Bash-style globbing (* represents any number of any characters) is useful if your images are sequential but not necessarily in a numerically sequential order.

The glob pattern is not available on Windows FFmpeg builds.

To learn more about exclusive -ffprefixes parameter. See Exclusive Parameters ➶

# import the necessary packages
from deffcode import FFdecoder
import cv2

# define `-pattern_type glob` for accepting glob pattern
ffparams = {"-ffprefixes":["-pattern_type", "glob"]}

# initialize and formulate the decoder with suitable source
decoder = FFdecoder("/path/to/pngs/img*.png", frame_format="bgr24", verbose=True, **ffparams).formulate()


# grab the GRAYSCALE frame from the decoder
for frame in decoder.generateFrame():

    # check if frame is None
    if frame is None:
        break

    # {do something with the frame here}

    # Show output window
    cv2.imshow("Output", frame)

    # check for 'q' key if pressed
    key = cv2.waitKey(1) & 0xFF
    if key == ord("q"):
        break


# close output window
cv2.destroyAllWindows()

# terminate the decoder
decoder.terminate()

Capturing and Previewing frames from Single looping image¶

In this example we will capture video frames from a Single Looping image using FFdecoder API, and preview them using OpenCV Library's cv2.imshow() method in real-time.

By default, OpenCV expects BGR format frames in its cv2.imshow() method.

To learn more about exclusive -ffprefixes parameter. See Exclusive Parameters ➶

# import the necessary packages
from deffcode import FFdecoder
import cv2

# define `-loop 1` for infinite looping
ffparams = {"-ffprefixes":["-loop", "1"]}

# initialize and formulate the decoder with suitable source
decoder = FFdecoder("img.png", frame_format="bgr24", verbose=True, **ffparams).formulate()

# grab the BGR24 frame from the decoder
for frame in decoder.generateFrame():

    # check if frame is None
    if frame is None:
        break

    # {do something with the frame here}

    # Show output window
    cv2.imshow("Output", frame)

    # check for 'q' key if pressed
    key = cv2.waitKey(1) & 0xFF
    if key == ord("q"):
        break

# close output window
cv2.destroyAllWindows()

# terminate the decoder
decoder.terminate()

Last update: January 10, 2023