motmot.FlyMovieFormat - simple, uncompressed movie storage format

This package contains code to read, write and view FlyMovieFormat files, which end with extension .fmf.

The primary design goals of FlyMovieFormat were:

• Single pass, low CPU overhead writing of lossless movies for realtime streaming applications
• Precise timestamping for correlation with other activities
• Simple format that can be read from Python, C, and MATLAB®.

These goals are acheived via using a very simple format. After an initial header containing meta-data such as image size and color coding scheme (e.g. monochromatic 8 bits per pixel, YUV422, etc.), repeated chunks of raw image data and timestamp are saved. Because the raw image data from the native camera driver is saved, no additional processing is performed. Thus, streaming of movies from camera to disk will keep the CPU free for other tasks, but it will require a lot of disk space. Furthermore, the disk bandwidth required is equivalent to the camera bandwidth (unless you save only a region of the images, or if you only save a fraction of the incoming frames).

• FlyMovieFormat (.fmf) file specification

Converting files to .fmf

The command ffmpeg2fmf will use avbin (part of Pyglet) to read a variety of movie formats and save them as .fmf files. Use it like so:

ffmpeg2fmf --format=mono8 /path/to/my/movie.mp4
# or
ffmpeg2fmf --format=mono8 /path/to/my/movie.avi

This will save a file /path/to/my/movie.fmf.

motmot.FlyMovieFormat.FlyMovieFormat

This module contains code to read and write FlyMovieFormat files, which end with extension .fmf.

Users may like to use these classes:

• FlyMovie : read .fmf files
• FlyMovieSaver : write .fmf files

The following Exception types may sometimes be raised:

• NoMoreFramesException :
• InvalidMovieFileException :

Reading an .fmf from Python

In Python accessing frames from an .fmf files is as easy as:

import motmot.FlyMovieFormat.FlyMovieFormat as FMF
import sys

fname = sys.argv[1]
fmf = FMF.FlyMovie(fname)
for frame_number in range(10):
    frame,timestamp = fmf.get_frame(frame_number)

Writing an .fmf in Python

Writing frames to an .fmf file is also easy:

import motmot.FlyMovieFormat.FlyMovieFormat as FMF
import sys
import numpy as np

fname = sys.argv[1]
fmf_saver = FMF.FlyMovieSaver(fname)

width, height = 640,480
for i in range(10):
    fake_image = np.zeros( (height,width), dtype=np.uint8)
    fake_timestamp = 0.0
    fmf_saver.add_frame(fake_image,fake_timestamp)

fmf_saver.close()

Module documentation

class motmot.FlyMovieFormat.FlyMovieFormat.FlyMovie(file, check_integrity=False)

.fmf file reader

• file : string or file object to open

Optional keyword arguments:

• check_integrity : whether to scan the last frame(s) for completeness

get_all_timestamps()

return all timestamps in .fmf file

Returns: - all_timestamps : array of timestamps

get_bits_per_pixel()

get the number of bits per pixel

Returns: - bits_per_pixel : integer, number of bits per pixel (e.g. 8)

get_height()

returns height of data, in pixels

Returns: - height : integer, height of image, in pixels

get_n_frames()

get the number of frames

Returns: - n_frames : integer, number of frames

get_next_frame(allow_partial_frames=False)

return image data for frame number

Returns:

• frame : array of image data
• timestamp : float, timestamp of image time

get_width()

returns width of data, in bytes

Returns: - width : integer, width of image, in bytes

Note, to get the width of underlying image, do this:

image_width = fmf.get_width()//(fmf.get_bits_per_pixel()//8)

seek(frame_number)

go to frame number

class motmot.FlyMovieFormat.FlyMovieFormat.FlyMovieSaver(file, version=1, seek_ok=True, format=None, bits_per_pixel=None)

.fmf file writer

• file : string or file object to open

Keyword arguments:

• version : 1 or 3, defaults to 1
• seek_ok : boolean indicating whether calling seek() is OK on this file
• format : format string (e.g. ‘MONO8’, required for version 3 only)
• bits_per_pixel : number of bits per pixel. inferred from format if not supplied.

add_frame(origframe, timestamp=nan, error_if_not_fast=False)

save a single image frame to the file

• origframe : array of image data

Optional keyword arguments:

• timestamp : double precision floating point timestamp (default: nan)
• error_if_not_fast : boolean: raise error if no origframe.dump_to_file()

add_frames(frames, timestamps=None)

add multiple image frames

• frames : arrays of image data

Optional keyword arguments:

• timestamps : double precision floating point timestamps

close()

finish writing the file

exception motmot.FlyMovieFormat.FlyMovieFormat.InvalidMovieFileException

Bases: exceptions.Exception

The file is not a valid movie file

exception motmot.FlyMovieFormat.FlyMovieFormat.NoMoreFramesException

Bases: exceptions.Exception

A frame was requested, but no more frames exist

motmot.FlyMovieFormat.FlyMovieFormat.mmap_flymovie(*args, **kwargs)

map .fmf file to RAM

Note: make mmap does not currently work with RGB images.

Note: to map a 4 GB or larger file to RAM, a 64 bit computer is required.