tracktable.render.map_processing.parallel_movies module

Module contents

movie_processing.py - Functions for supporting rendering a parallel movie

Note

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

class tracktable.render.map_processing.parallel_movies.BatchMovieRenderer

Bases: object

Render a single batch of frames for a movie.

We parallelize movie rendering by chopping the movie up into small batches of frames, placing those batches into a queue and then allowing one or more render processes to perform tasks from that queue. This allows us to trade off the need for load balancing (so that all worker processes stay busy) with the overhead of encoding a movie stream.

This class encapsulates all the information we need to go out and render a single batch. Our intent is to make this process thread-safe although it may be some time before an implementation using threads instead of processes is efficient.

Note: This API is going to get cleaned up a lot as I refactor

movie-making to support different types of movies (heatmap especially).

basemap

Map instance to render into

Type:

mpl_toolkits.basemap.Basemap

trajectories

Reusable sequence of Trajectory objects

Type:

list

trail_duration

Length of trail to draw behind moving objects (seconds)

Type:

int

figure

Top-level image container

Type:

matplotlib.Figure

dpi

Dots per inch to use when rendering text into figure

Type:

int

savefig_kwargs

Any extra arguments to pass to Matplotlib’s savefig() such as border size or tight_layout parameters

Type:

dict

trajectory_rendering_kwargs

Any extra arguments to pass to the trajectory renderer such as linewidth, annotation functions or z-order

Type:

dict

axes

Axes to which actors will be added

Type:

matplotlib.axes.Axes

fps

Frames per second for movie

Type:

integer

all_args

All arguments from command line

Type:

argparse.Namespace

temp_directory

Destination for encoded frame batches

Type:

path

start_time

Data before this time will not be in the movie

Type:

datetime

end_time

Data after this time will not be in the movie

Type:

datetime

movie_kwargs

Extra arguments (such as metadata) to pass to movie encoding

Type:

dict

num_frames_overall

Number of frames in entire movie, not just each chunk

Type:

integer

utc_offset

Argument to pass to clock rendered on map

Type:

integer

timezone_label

Text annotation to be added to clock

Type:

string

render_frame_batch(batch_info)

Render a single group of frames.

In order to preserve maximum image quality, we encode each movie chunk with FFMPEG’s ‘ffv1’ lossless codec. We will maintain lossless encoding until right at the end when we encode the final movie with the user’s desired compression parameters.

Parameters:

batch_info (list) – Group of ( numeric_id, start_frame_number, num_frames, temp_directory )

Returns:

Filename (with path) for encoded movie fragment

tracktable.render.map_processing.parallel_movies.concatenate_movie_chunks(chunk_filenames, tmpdir)

Assemble individual movie chunks into a single movie

In addition to encoding, decoding and multiplexing media streams, FFMPEG has a convenient mode called “concat” that will append one bitstream to another without re-encoding. We take advantage of that to assemble the frame batches into a single movie.

Parameters:

• chunk_filenames (list) – Filenames of movie batches. These batches must be in order.

• tmpdir (string) – Path to directory where raw footage should be stored.

Side Effects:

• Individual frame batches will be concatenated into a movie called ‘assembled.mkv’ in the temporary directory.

• Frame batches will be removed after concatenation.

• A temporary file ‘concat_recipe’ will be created when this function is called and removed after encoding is complete.

tracktable.render.map_processing.parallel_movies.encode_final_movie(output_filename, tmpdir, encoder_args)

Re-encode the finished movie to user specifications.

We generate the movie originally using a lossless encoding. This results in a very large file. Typically the user will want it in a different format that’s easier to move around. This function does that with a call to ffmpeg.

Parameters:

• output_filename (string) – User-specified filename for the finished movie

• tmpdir (string) – Path to work directory

• args (argparse.Namespace) – All arguments parsed from command line

Side Effects:

Movie will be transcoded from its intermediate format and written to the output file.

tracktable.render.map_processing.parallel_movies.parallel_movie_rendering(trajectories, map_canvas, color_map, decorate_head, head_size, head_color, linewidth_style, linewidth, final_linewidth, scalar, scalar_min, scalar_max, zorder, dpi, figure, movie_writer, filename, first_frame, num_frames, trail_duration, frame_duration, first_frame_time, savefig_kwargs)

tracktable.render.map_processing.parallel_movies.remove_movie_chunks(tmpdir, filenames)

Clean up intermediate movies.

Remove the individual movie chunks as well as the assembled raw footage.

Parameters:

• tmpdir (string) – Path to work directory

• filenames (list) – List of filenames for intermediate footage

tracktable.render.map_processing.parallel_movies.render_frame_batch(batch)

Worker function to hand off a frame batch to the renderer.

This is a convenient wrapper that lets us use multiprocessing.map_async() to process frame batches.

Parameters:

batch (list) – Frame batch information for renderer

Returns:

Whatever comes back from the batch renderer (generally a filename)