tracktable.render.map_processing.movies module

Module contents

movie_processing.py - Functions for supporting rendering a movie

Note

Cartopy v0.18.0 is required to successfully render maps and pass our internal tests.

tracktable.render.map_processing.movies.clip_trajectories_to_interval(trajectories, start_time, end_time)

tracktable.render.map_processing.movies.compute_figure_dimensions(resolution, dpi)

Compute figure dimensions in inches given resolution and dots per inch

Given an image of resolution X by Y pixels and D dots per inch, the figure’s dimensions in inches are (X/D, Y/D).

Parameters:

• ints} (resolution {list or tuple of 2) – Image resolution in pixels

• {int} (dpi) – Dots per inch for image

Returns:

Tuple of two floats containing image size in inches

tracktable.render.map_processing.movies.compute_movie_time_bounds(trajectories, user_start_time, user_end_time)

Compute start and end time for a movie

We have two ways to choose the start and end time of a movie: 1. User-specified values take precedence. 2. Absent a user preference, use the time bounds of the data.

Use this function to compute that.

Parameters:

• trajectories} (trajectories {iterable of Tracktable) – Trajectory data for movie

• {datetime.datetime} (user_end_time) – When the user wants the movie to start (can be None for ‘don’t care’)

• {datetime.datetime} – When the user wants the movie to end (can be None for ‘don’t care’)

Returns:

(start_time, end_time), both as datetime.datetime objects

Raises:

ValueError – no trajectories and no user start/end time

tracktable.render.map_processing.movies.initialize_canvas(resolution, dpi=72, facecolor='black')

Set up Matplotlib canvas for rendering

This function sets up a Matplotlib figure with specified resolution, DPI, and background/edge color.

Since font sizes are specified in points, the combination of DPI and resolution determines how large a font will appear when text is rendered into the image. One inch is 72 points, so a 12-point font will produce text where each line is (dpi / 6) pixels tall.

Parameters:

resolution (2 ints) – how large the images should be in pixels

Keyword Arguments:

• {integer} (dpi) – how many pixels per inch (pertains to text rendering). Defaults to 72.

• {string} (facecolor) – Default color for image background. Can be specified as the name of a color (‘black’), a float value for grays (0.75 == #B0B0B0), an RGBA tuple ((1, 0, 0, 1) is red), or an #RRGGBB string. Defaults to ‘black’.

Returns:

(figure, axes), where ‘figure’ is a Matplotlib figure and ‘axes’ are the default axes to render into.

tracktable.render.map_processing.movies.map_extent_as_bounding_box(axes, domain='terrestrial')

Return a Tracktable bounding box for axes’ drawable extent

This is a convenience function to grab the bounding box for a set of Matplotlib axes and transform it to a Tracktable bounding box that can be used for intersection calculations.

Note that this returns the extent of the drawable area itself without including the part of the canvas (if any) that containins decorations such as axis lines, ticks, and tick labels.

Parameters:

axes} (axes {Matplotlib) – Map for which you want the bounding box

Keyword Arguments:

{string} (domain) – Coordinate domain for bounding box (default: ‘terrestrial’)

Returns:

Tracktable bounding box from appropriate point domain

Raises:

KeyError – ‘domain’ must be one of ‘cartesian2d’ or ‘terrestrial’

tracktable.render.map_processing.movies.render_annotated_trajectories(trajectories, axes, color_map='plasma', decorate_head=False, head_size=2, head_color='white', linewidth_style='taper', linewidth=0.5, final_linewidth=0.01, scalar='progress', scalar_min=0, scalar_max=1, zorder=10)

Render decorated trajectories (with scalars) onto a map.

Given a map instance and an iterable containing trajectories, draw the trajectories onto the map with the specified appearance parameters. You can control the trajectory color, linewidth, z-order and whether or not a dot is drawn at the head of each path.

The “annotated” part of render_annotated_trajectories refers to per-point scalar metadata on each trajectory. For example, if your trajectories have a property “speed” at each point, you could render a movie where trajectories being displayed are color-coded by speed. If you supply the name of a property for the scalar_property argument, that property will be used along with colormap to determine color. If you don’t specify a property, trajectories will be colored so that traverse the entire colormap from start to finish.

Args::

axes (matplotlib Axes): Axes to render into trajectories (iterable of Tracktable trajectories): trajectories to render

Keyword Arguments:

• color_map (name of colormap or matplotlib.colors.Colormap) – Trajectory scalars will be mapped to this color map. (default: ‘plasma’)

• decorate_head (boolean) – If true, a dot will be drawn at the current position of each object on the screen. (default: False)

• head_size (float) – How large the dot should be for decorated trajectories, measured in points. (default: 2)

• head_color (string or tuple) – What color the head dot should be for decorated trajectories. Can be any Matplotlib color specification such as a color name, an ‘#RRGGBB’ string, or a tuple of RGB or RGBA values. The value ‘scalar’ means to use the scalar value at the head of the trajectory so that the dot is the same color as its trail.

• linewidth_style (string) – Either ‘constant’, in which case the lines for each trajectory will have constant width (see the linewidth parameter); or ‘taper’, in which case the line width will vary smoothly from linewidth at the object’s current position to final_linewidth at the oldest end of the trail. (default: ‘taper’)

• linewidth (float) – Width of trajectory trail subject to linewidth_style. (default: 0.5)

• final_linewidth (float) – Width of oldest end of trajectory trail. Only used when linewidth_style is ‘taper’.

• scalar (string) – Real-valued property to be used to determine trajectory color. You must make sure that this property is present at all points in the trajectory data. The default ‘progress’ scalar is added automatically. (default: ‘progress’)

• scalar_min (float) – Bottom of range of scalar values that you care about. If your scalars are outside the range (0,1), you should set this. Values below this will be treated as the minimum value. (default: 0)

• scalar_max (float) – Top of range of scalar values that you care about. If your scalars are outside the range (0,1), you should set this. Values above this will be treated as the maximum value. (default: 1)

• zorder (integer) – Z-order for drawn items. Items with a higher Z-order will appear on top of items with a lower Z-order. This is Matplotlib-specific. (default: 10)

Returns:

List of Matplotlib artists added to the figure.

Raises:

• KeyError – The desired scalar is not present

• ValueError – linewidth_style is neither ‘constant’ nor ‘taper’

Note

A gallery of Matplotlib colormaps can be found at https://matplotlib.org/3.1.1/gallery/color/colormap_reference.html

tracktable.render.map_processing.movies.setup_encoder(encoder='ffmpeg', codec=None, encoder_args=None, movie_title='Tracktable Movie', movie_artist='Tracktable Trajectory Toolkit', movie_comment='', fps=30, **kwargs)

Instantiate and configure a video encoder

Matplotlib supports video encoding with a writer interface that takes several arguments including which program to use to do the encoding and what parameters the encoder needs. This function is a convenience interface to that.

Keyword Arguments:

• encoder (string) – Name of encoder. This must be one of the values in matplotlib.animation.writers.list. Default: ‘ffmpeg’ (requires that you have FFmpeg installed on your system)

• codec (string) – Name of specific encoding algorithm to use. This is specific to the encoder you choose. Default: None (whatever the encoder prefers)

• encoder_args (list of strings) – Any arguments you wish to provide to the encoder. These are passed through to the underlying Matplotlib implementation as extra_args. More information about the encoder args can be found here: https://matplotlib.org/stable/api/_as_gen/matplotlib.animation.FFMpegWriter.html#matplotlib-animation-ffmpegwriter

• movie_title (string) – Title string to be embedded in the movie’s metadata. This is not rendered on screen. Default: “Tracktable Movie”

• movie_artist (string) – Movie creator to be embedded in the movie’s metadata. This is not rendered on screen. Default: “Tracktable Trajectory Toolkit”

• movie_comment (string) – Any other comments you want to embed in metadata. Default: empty string

• fps (int) – Desired frames per second for the result. Default: 30

Returns:

Matplotlib animation object configured with supplied parameters

Raises:

KeyError – You have requested an encoder that is not available on this system

tracktable.render.map_processing.movies.trajectories_inside_box(trajectories, bounding_box)

Filter trajectories to include only those inside a bounding box

We can speed up rendering quite a bit if we discard trajectories that do not intersect the image being rendered. This function compares each trajectory against a user-supplied bounding box (presumably the bounds for the map) and returns only those trajectories that fall within the box.

Parameters:

• trajectories} (trajectories {iterable of Tracktable) – Data to test against bounding box

• box} (bounding_box {Tracktable bounding) – box to test

Returns:

Iterable of trajectories that intersect the bounding box

Raises:

ValueError – bounding box must not be None

tracktable.render.map_processing.movies.trajectory_overlaps_interval(trajectory, start_time, end_time)

Does a trajectory overlap a time interval?

For a trajectory to overlap a time interval, it cannot be the case that it begins after the interval ends or ends before the interval begins.

Parameters:

• trajectory} (trajectory {Tracktable) – trajectory to test

• {datetime.datetime} (end_time) – Beginning of interval

• {datetime.datetime} – End of interval

Returns:

true if overlap, false if disjoint

Return type:

Boolean

tracktable.render.map_processing.movies.trajectory_time_bounds(trajectories)

Compute the collective start and end time of a set of trajectories

Parameters:

trajectories} (trajectories {iterable of Tracktable) – trajectories whose bounds you want

Returns:

Pair of Python datetimes. The first element is the earliest

timestamp in any of the trajectories. The second element is the latest timestamp.

Raises:

ValueError – input sequence is empty