API reference

ODMax’s API currently consists of two classes, the Video class, and the Frame class. The classes are based on calls of functions. We highly recommend to use the two classes, as these will provide most if not all functionality useful for extracting frames, extracting and including GPS data in frame writing, projection of 360-degree imagery to cube-faces, plotting and writing to files. Of course you can also use the called functions for more flexibility.

Note

We expect to integrate ODMax’s API with WebODM in the near future. This will enable direct uploads of ODMax derived stills into WebODM projects. WebODM is a powerful, free and open-source web-based photogrammetry software. See https://www.opendronemap.org/webodm/ for more information.

In the remaining sections, we describe the API classes, and the functions they are based on.

Video class

odmax.Video.__init__(self, fn)

Create a new Video instance. Properties of the video, relevant for extracting frames will be extracted. Also GPS information, if available (tested for GoPro .mp4 format) will be automatically extracted, provided that exiftool is available on your system and in your system’s path. You will receive warnings if exiftool is not available.

Parameters

fn – filename of video file on disk

odmax.Video.get_frame(self, n, reproject=False, **kwargs)

Get one Frame from Video for processing

Parameters

  • n – int, frame number

  • reproject – bool, set to True if you want to reproject to 6 cube-faces

  • kwargs – keyword arguments for cube reprojection, see odmax.process.reproject_cube.

Returns

odmax.Frame instance

odmax.Video.get_gps(self, t)

Returns GPS information at given timestamp t (measured as time epoch, e.g. returned from datetime.timestamp)

Parameters

t – float from datetime.timestamp (i.e. seconds since 1970-01-01 00:00:00)

Returns

Pandas DataFrame row with location (lat, lon, elev) and index as time epoch, using linear interpolation

odmax.Video.plot_gps(self, geographical=False, figsize=(13, 8), ax=None, crs=None, tiles=None, plot_kwargs={}, zoom_level=8, tiles_kwargs={})

Make a simple plot of the gps track in the Video

Parameters

  • geographical – bool, use a geographical plot, default False, requires cartopy to be installed

  • figsize – tuple, passed to plt.figure as figsize

  • ax – pass an axes that you already have, to add to existing axes

  • crs – cartopy.crs object, coordinate reference system (default: cartopy.crs.PlateCarree())

  • tiles – str, name of cartopy.io.img_tiles WMTS WMTS service, default: None, can be e.g. “OSM”, “QuadtreeTiles”, “GoogleTiles”

  • zoom_level – int, zoom level for chosen tile service, default 8.

  • plot_kwargs – dictionary of options to pass to matplotlib.pyplot.plot

  • tiles_kwargs – dictionary of options to pass to cartopy.axes.add_image

Returns

axes object

Frame class

odmax.Frame.__init__(self, img, n, t, coord, exif=False, exif_dict={})

Create a new Frame instance. A Frame holds the image, but also which frame number it came from, the coordinate of the frame if GPS information is available, and the EXIF tag that belongs to the frame, comprised of a dictionary

Parameters

  • img – ND-array [M, N, 3] holding the RGB image

  • n – frame number

  • t – timestamp as datetime.datetime object

  • coord – pandas DataFrame row holding latitude, longitude, elevation and time

  • exif_dict – dict, holding EXIF tag information, e.g. exif_dict[“GPS”] should contain a dict with GPS tags

odmax.Frame.plot(self, figsize=(8, 8), rows=2, cols=3)
Parameters

  • figsize – tuple (height, width) of figure, default: (8, 8)

  • rows – int, number of rows to use for plotting 6 cube-faces, default: 2

  • cols – int, number of cols to use for plotting 6 cube-faces, default: 3

Returns

f, ax, figure and axes handle

odmax.Frame.to_bytes(self, encoder='jpg')

Write a frame to one or more bytestreams, ready to push to an online service. If cube-face reprojection has been used 6 images will be written in a list of bytestreams

Parameters

encoder – str, default is “jpg”

Returns

bytestream

odmax.Frame.to_file(self, path='.', prefix='still', encoder='jpg')

Write a frame to one or multiple files. If cube-face reprojection has been used 6 images will be written at the selected path and prefix. Names of files will follow the following conventions: In case no reprojection used: <path>/<prefix>_<frame_number>.<encoder> In case cube-face reprojection is applied: <path>/<prefix>_<frame_number>_<cube face>.<encoder>

where cube_face is one of “F”, “R”, “B”, “L”, “U”, “D” as suffixes for “front”, “right”, “back”, “left”, “up” and “down”.

Parameters

  • path – str, Path to write frames to

  • prefix – str, Prefix for files

  • encoder – str, default is “jpg”

Returns

str, output filename; or list of str filenames

Input-output

odmax.io.get_frame_number(f, time)[source]

Get the frame number belonging to the defined time in seconds.

Parameters

  • f – pointer to opened video file

  • time – seconds from start of video

Returns

odmax.io.get_gpx(fn)[source]

Reads the gpx track from a video and writes it to a file.

Parameters

fn – video filename

Returns

parsed gpx data

odmax.io.open_file(fn)[source]

Open file for reading by cv2.

Parameters

fn – video file (cv2 compatible)

Returns

cv2 pointer to file

odmax.io.read_frame(f, n)[source]

Reads frame number n from opened video file f.

Parameters

  • f – pointer to opened video file

  • n – frame number

Returns

img, blob containing frame

odmax.io.to_pil(array)[source]

Converts ND-array into PIL object

Parameters

array – ND-array with colors (3rd dimension) in RGB order

Returns

PIL image

odmax.io.write_frame(img, fn, encoder='jpg', exif_dict={})[source]

Writes a frame to a file or bytestream. If a 6-face cube list is provided, 6 files will be written using “F”, “R”, “B”, “L”, “U”, “D” as suffixes for “front”, “right”, “back”, “left”, “up” and “down”.

Parameters

  • img – ndarray or list of 6 ndarrays of size [H, W, 3]

  • fn – path or io.BytesIO object to write frame to

  • encoder – PIL compatible encoder to use for writing

  • exif_dict – dictionary with EXIF tag groups and tags within groups (e.g. “GPS”)

Returns

Processing

odmax.process.reproject_cube(img, **kwargs)[source]

Reprojects image to a cube projection.

Parameters

  • img – ndarray with dimensions [H, W, 3] containing image

  • face_w – int defining the length of each face of the cube (default: 256)

  • mode – str defining the reprojection mode, can be ‘bilinear’ or ‘nearest’

  • overlap – float, defining the amount of overlap on face edges defined as ratio of face_w (e.g. 0.1). If not set, this will default to 0.1

Returns

list of ndarrays in shape of [H, W, 3] containing images of cube faces