API Reference

Core Modules

gpmf.parse

class gpmf.parse.KLVItem(key, length, value)

Bases: tuple

key

Alias for field number 0

length

Alias for field number 1

value

Alias for field number 2

class gpmf.parse.KLVLength(type, size, repeat)

Bases: tuple

repeat

Alias for field number 2

size

Alias for field number 1

type

Alias for field number 0

gpmf.parse.ceil4(x)

Find the closest greater or equal multiple of 4

Parameters:

x (int) – The size

Returns:

x_ceil – The closest greater integer which is a multiple of 4.

Return type:

int

gpmf.parse.parse_payload(x, fourcc, type_str, size, repeat)

Parse the payload

Parameters:

• x (byte) – The byte array corresponding to the payload

• fourcc (str) – The fourcc code

• type_str (str) – The type of the value

• size (int) – The size of the value

• repeat (int) – The number of times the value is repeated.

Returns:

payload – The parsed payload. the actual type depends on the type_str and the size and repeat values.

Return type:

object

gpmf.parse.iter_klv(x)

Iterate on KLV items.

Parameters:

x (byte) – The byte array corresponding to the stream.

Returns:

klv_gen – A generator of (fourcc, (type_str, size, repeat), payload) tuples.

Return type:

generator

gpmf.parse.filter_klv(x, filter_fourcc)

Filter only KLV items with chosen fourcc code.

Parameters:

• x (byte) – The input stream

• filter_fourcc (list of str) – A list of FourCC codes

Returns:

klv_gen – De-nested generator of (fourcc, (type_str, size, repeat), payload) with only chosen fourcc

Return type:

generator

gpmf.parse.expand_klv(x)

Expand the klv items

Convert generators of klv items produced by iter_klv to lists.

Parameters:

x

gpmf.gps

class gpmf.gps.GPSData(description, timestamp, precision, fix, latitude, longitude, altitude, speed_2d, speed_3d, units, npoints)

Bases: tuple

altitude

Alias for field number 6

description

Alias for field number 0

fix

Alias for field number 3

latitude

Alias for field number 4

longitude

Alias for field number 5

npoints

Alias for field number 10

precision

Alias for field number 2

speed_2d

Alias for field number 7

speed_3d

Alias for field number 8

timestamp

Alias for field number 1

units

Alias for field number 9

gpmf.gps.extract_gps_blocks(stream)

Extract GPS data blocks from binary stream

This is a generator on lists KVLItem objects. In the GPMF stream, GPS data comes into blocks of several different data items. For each of these blocks we return a list.

Parameters:

stream (bytes) – The raw GPMF binary stream

Returns:

gps_items_generator – Generator of lists of KVLItem objects

Return type:

generator

gpmf.gps.parse_gps_block(gps_block)

Turn GPS data blocks into GPSData objects

Supports both GPS5 (Hero 5-10) and GPS9 (Hero 11+) streams

Parameters:

gps_block (list of KVLItem) – A list of KVLItem corresponding to a GPS data block.

Returns:

gps_data – A GPSData object holding the GPS information of a block.

Return type:

GPSData

gpmf.gps.make_pgx_segment(gps_blocks, first_only=False, speeds_as_extensions=True)

Convert a list of GPSData objects into a GPX track segment.

Parameters:

• gps_blocks (list of GPSData) – A list of GPSData objects

• first_only (bool, optional (default=False)) – If True use only the first GPS entry of each data block.

• speeds_as_extensions (bool, optional (default=True)) – If True, include 2d and 3d speed values as exentensions of the GPX trackpoints. This is especially useful when saving to GPX 1.1 format.

Returns:

gpx_segment – A gpx track segment.

Return type:

gpxpy.gpx.GPXTrackSegment

gpmf.io

gpmf.io.find_gpmf_stream(fname)

Find the reference to the GPMF Stream in the video file

Parameters:

fname (str) – The input file

Returns:

stream_info – The GPMF Stream info.

Return type:

dict

Raises:

RuntimeError – If no stream found.:

gpmf.io.extract_gpmf_stream(fname, verbose=False)

Extract GPMF binary data from video files

Parameters:

• fname (str) – The input file

• verbose (bool, optional (default=False)) – If True, display ffmpeg messages.

Returns:

gpmf_data – The raw GPMF binary stream

Return type:

bytes

gpmf.gps_plot

gpmf.gps_plot.to_dataframe(gps_data_blocks)

Convert a sequence of GPSData into pandas dataframe.

Parameters:

gps_data_blocks (seq of GPSData) – A sequence of GPSData objects

Returns:

df_gps – The output dataframe

Return type:

pandas.DataFrame

gpmf.gps_plot.filter_outliers(x)

Filter outliers based on 0.01 and 0.99 quantiles

gpmf.gps_plot.plot_gps_trace(latlon, min_tile_size=10, map_provider=None, zoom=12, figsize=(10, 10), proj_crs='EPSG:2154', color='tab:red')

Plot a (lat, lon) coordinates on a Map

Parameters:

• latlon (numpy.ndarray) – Array of (latitude, longitude) coordinates

• min_tile_size (int, optional (default=10)) – Minimum size of the map in km

• map_provider (dict) – Dictionnary describing a map provider as given by contextly.providers. If None contextily.providers.OpenStreetMap.Mapnik is used.

• zoom (int, optional (default=12)) – The zoom level used.

• figsize (tuple of int, optional (default=(10, 10))) – The matplotlib figure size

• proj_crs (str or geopandas.CRS object, optional (default="EPSG:2154")) – The projection system used to compute distances on the map. The default value corresponds to the Lambert 93 system.

• color (str, optional (default="tab:red")) – The color used to plot the track.

gpmf.gps_plot.plot_gps_trace_from_stream(stream, first_only=False, min_tile_size=10, map_provider=None, zoom=12, figsize=(10, 10), proj_crs='EPSG:2154', output_path=None, precision_max=3.0, color='tab:red')

Plot GPS data from a string on a map.

Parameters:

• stream (bytes) – The raw GPMF binary stream.

• min_tile_size (int, optional (default=10)) – Minimum size of the map in km

• map_provider (dict) – Dictionnary describing a map provider as given by contextly.providers. If None contextily.providers.OpenStreetMap.Mapnik is used.

• zoom (int, optional (default=12)) – The zoom level used.

• figsize (tuple of int, optional (default=(10, 10))) – The matplotlib figure size

• proj_crs (str or geopandas.CRS object, optional (default="EPSG:2154")) – The projection system used to compute distances on the map. The default value corresponds to the Lambert 93 system.

• color (str, optional (default="tab:red")) – The color used to plot the track.