tracktable.render.render_trajectories module

Module contents

tracktable.render.render_trajectories - render trajectories in python

This is a set of function that intend to allow user-friendly rendering of trajectories. A user should be able to simply use the funection render_trajectories(trajs) passing a single parameter that is a list of trajectories and get a rendering of those trajectories, whether running as an interactive map inside of a noetbook or from the command line and saved as a static image to a file.

In addition render_trajectories supports many parameters to enable specifying a myriad of options for rendering the trajectories, including allowing users to explicitly specify the rendering backend.

tracktable.render.render_trajectories.bounding_box_for_folium(trajectories)

Translates a computed bounding box to the format needed by folium

tracktable.render.render_trajectories.common_processing(trajectories, obj_ids, line_color, color_map, gradient_hue)

Common processing functionality

Parameters

• trajectories (list) – List of Trajectories

• obj_ids (list) – List of IDs

• (name of standard color as string, hex color string (line_color) – or matplotlib color object, or list of any of these): The single color to use for all the segments in each trajectory. Overrides color_map and gradient_hue values. Can be a list of matplotlib color name strings, hex color strings or matplotlib color objects the same length as the length of the list of trajectories.

• (name of standard colormap as string or matplotlib (color_map) – color_map object or list of either): The color map to use in rendering the segments of each trajectory.

• gradient_hue (float or list of floats) – hue or list of hues (one per trajectory) to be used in definig the gradient color map (dark to light) for the trajectories. Only used if line_color and color_map are not used (set to ‘’). If line_color, color_map and gradient_hue are all unset the default behavior is to set the gradient_hue based on a hash of the object_id

Returns

trajectories, line_color, color_map and gradient_hue

tracktable.render.render_trajectories.crs_scale(zoom)

Scale the CRS based on zoom factor

tracktable.render.render_trajectories.crs_zoom(scale)

Zoom the CRS based on scale factor

tracktable.render.render_trajectories.get_bounds_zoom(map_canvas, bounds, inside=True, size=[960, 400], padding=[0, 0])

Get the zoom if the bounding box corners

Parameters

• map (Basemap) – Map containing bounding box

• bounds (point) – Long-Lat point of the bounding box corners

Keyword Arguments

• inside (bool) – Flag to indicate inside of the bounding box

• size (list) – Size of the bouning box

• padding (list) – Padding of boundries

Returns

The maximum zoom level on which the given bounds fit to the map vie in its entirety

tracktable.render.render_trajectories.get_color_mapper(color_scale, color_map)

Returns an object that can translate scalars into colors

Returns an object that can produce for any scalar the correct RGBA color from the given color_map using the given color_scale.

Parameters

• color_scale (matplotlib.colors.Normalize() or LogNorm()) – Linear or logarithmic scale

• (name of standard colormap as string or matplotlib (color_map) – color_map object or list of either): The color map to use in rendering the segments of each trajectory.

Returns

An object that can translate scalars into colors and an object that can produce for any scalar the correct RGBA color from the given color_map using the given color_scale.

tracktable.render.render_trajectories.get_constant_color_cmap(color)

Returns a colormap containing the single color given

Parameters

color (str) – Color to get colormap from

Returns

Returns a colormap containing the single color given

tracktable.render.render_trajectories.get_scale_zoom(scale, from_zoom)

Get zoom scale factor

tracktable.render.render_trajectories.hash_short_md5(string)

Given any string, returns a number between 0 and 1. The same

number is always returned given the same string. Internally uses hashlib.md5, but only uses the first quarter of the full hash

Parameters

string (str) – String to be hashed

Returns

0 or 1

tracktable.render.render_trajectories.hue_gradient_cmap(hue, chop_frac=0.29)

Returns a color map which progresses from dark to light given a

specific hue

Parameters

• hue (str or float) – the hue to generate the color map for. (0 to 1)

• chop_frac (float) – the fraction of the beginning and end of the total gradient to chop off so as to not be too light or dark.

Returns

color map object which can be passed to matplotlib’s cmap param

or render_trajectories color_map

tracktable.render.render_trajectories.in_notebook()

Returns True if run within a Jupyter notebook, and false otherwise

tracktable.render.render_trajectories.path_length_fraction_generator(trajectory)

Generator to produce path length fraction scalars A genertor that given a trajectory will generate a scalar for each point such that each scalar represents the fraction of the total length along the path at the associated point.

Parameters

trajectory (Trajectory) – The trajectory to use for generating scaler values

Returns

Fraction length scalar values for each point in the trajectory

tracktable.render.render_trajectories.point_popup(current_point, point_popup_properties)

Formats the popup string for a point

Parameters

• current_point (point) – Current point of the trajectory

• point_popup_properties (list) – Point properties

Returns

String of point properties

tracktable.render.render_trajectories.point_tooltip(current_point)

Formats the tooltip string for a point

Parameters

current_point (point) – Current point of the trajectory

Returns

Current points timestamp

tracktable.render.render_trajectories.progress_linewidth_generator(trajectory)

Generator to produce progress linewidth scalars A generator that given a trajectory will generate a scalar for each point such that each scalar represents a good width value for the fraction of points that come before that point in the trajectory.

Parameters

trajectory (Trajectory) – The trajectory to use for generating scaler values

Returns

Linewidth scalar values for each point in the trajectory

tracktable.render.render_trajectories.project(latlng, zoom)

Projects a geographical coordinate according to the projection of the map’s CRS then scales it according to zoom and the CRS’s Transformation

Parameters

• latlng (point) – Point to project

• zoom (int) – Zoom value to scale by

Returns

Pixel coord relative to the CRS origin

tracktable.render.render_trajectories.project_spherical_mercator(latlng)

Project the spherical mercator for a given lat long value

Parameters

latlng (point) – Point transform

Returns

Projection of spherical mercator

tracktable.render.render_trajectories.random_color()

Returns a random RGB color in hex string format

tracktable.render.render_trajectories.random_hue()

Returns a random hue value (0 to 1)

tracktable.render.render_trajectories.render_distance_geometry_folium(distance_geometry_depth, traj, map_canvas)

Renders the distance geometry calculations to the folium map

Parameters

• distance_geometry_depth (int) – The depth of the distance geometry calculation

• traj (Trajectory) – The trajectory

• map (Basemap) – Folium map

Returns

No return value

tracktable.render.render_trajectories.render_point_folium(current_point, point_popup_properties, coord, point_radius, point_color, map_canvas)

Renders a point to the folium map

Parameters

• current_point (point) – Current point of the trajectory

• point_popup_properties (list) – Point properties

• coord (tuple) – Coordinates to render point

• point_radius (int) – Size of the point to render

• point_color (str) – Color of the point to render

• map (Basemap) – Folium map

Returns

No return value

tracktable.render.render_trajectories.render_point_ipyleaflet(current_point, point_popup_properties, coord, point_radius, point_color, map_canvas)

Renders a point to the ipyleaflet map

Args: current_point (point): Current point of the trajectory point_popup_properties (list): Point properties coord (tuple): Coordinates to render point point_radius (int): Size of the point to render point_color (str): Color of the point to render map (Basemap): ipyleaflet map

Returns

No return value

tracktable.render.render_trajectories.render_trajectories(trajectories, backend='', **kwargs)

Render a list of trajectories interactively or as a static image

This function will render a list of trajectories using Folium (for interactive display) if you are in a Jupyter notebook or using Cartopy (for a static image) if you are running from a script.

Parameters

trajectories (single Tracktable trajectory or list of trajectories) – Trajectories to render

Keyword Arguments

• backend (str) – Which back end to use. This can be ‘folium’ to force Folium interactive rendering or ‘cartopy’ to force static images. Defaults to None, which lets the renderer select automatically.

• map (map object for given backend) – rather than create a new map, append to this given map

• obj_ids (str or list of str) – only display trajecteories whose object id matches the given string or a string from the given list of strings.

• map_bbox ([minLon, maxLon, minLat, maxLat]) – bounding box for custom map extent. By default automatically set to make all trajectories visible.

• show_lines (bool) – whether or not to show the line segments of the trajecotry (Default: True)

• gradient_hue (float or list of floats) – hue or list of hues (one per trajectory) to be used in definig the gradient color map (dark to light) for the trajectories. Only used if line_color and color_map are not used (set to ‘’). If line_color, color_map and gradient_hue are all unset the default behavior is to set the gradient_hue based on a hash of the object_id

• (name of standard colormap as string or matplotlib (color_map) – color_map object or list of either): The color map to use in rendering the segments of each trajectory. Overrides the gradient_hue value. Can be a list of color map objects or a list of matplotlib color map name strings the same length the length of the list of trajectories. Only used if line_color is not used (set to ‘’).

• (name of standard color as string, hex color string (line_color) – or matplotlib color object, or list of any of these): The single color to use for all the segments in each trajectory. Overrides color_map and gradient_hue values. Can be a list of matplotlib color name strings, hex color strings or matplotlib color objects the same length as the length of the list of trajectories.

• linewidth (float) – Width of the trajectory segments. (Default: folium 2.5, cartopy 2)

• show_points (bool) – whether or not to show the points along the trajecotry (Default: False)

• point_size (float) – radius of the points along the path (Default: folium 0.6, cartopy 10.0)

• = (name of standard color as string, hex color string (point_color) – or matplotlib color object, or list of any of these): The single color to use for all the points in each trajectory. Can be a list of matplotlib color name strings, hex color strings or matplotlib color objects the same length as the length of the list of trajectories. If not specified, the color matches the segment incident at the point.

• dot_size (float) – radius of a dot drawn at the latest point of each trajectory (Default: folium 0.7, cartopy 10.0)

• (name of standard color as string, hex color string or (dot_color) – matplotlib color object): Color of spot that will be drawn at the latest point of each trajecctory (Default: ‘white’)

• trajectory_scalar_generator (function) – Function to generate scalars for a trajectory (Default: path_length_fraction_generator)

• trajectory_linewidth_generator (function) – Function to generate path widths for a trajectory (Default: None)

• color_scale (matplotlib.colors.Normalize() or LogNorm()) – Linear or logarithmic scale (Default: matplotlib.colors.Normalize(vmin=0, vmax=1))

• show (bool) – whether or not to show the result (if possible) (default True) if saving to a file, might not want to view.

• save (bool) – whether or not to save the result to a file. For folium the results can be saved to an html file. For cartopy the results can be saved as an image. If no filename is given, a default filename including the timestamp is used. (default False)

• filename (str) – Path and filename to save the results to, if save is set to True. If no filename is given, a default filename including the timestamp is used.

tracktable.render.render_trajectories.render_trajectories_bokeh(trajectories, map_canvas=None, obj_ids=[], line_color='', show_lines=True, show_points=False, **kwargs)

Render a list of trajectories using the bokeh backend This function renders a list of trajectories to a bokeh map.

Currently not officially supported. Just for evaluation!

tracktable.render.render_trajectories.render_trajectories_cartopy(trajectories, map_canvas=None, obj_ids=[], map_bbox=[], show_lines=True, gradient_hue=None, color_map='', line_color='', linewidth=2.4, show_points=False, point_size=0.6, point_color='', show_dot=True, dot_size=0.7, dot_color='white', trajectory_scalar_generator=<function path_length_fraction_generator>, trajectory_linewidth_generator=None, color_scale=matplotlib.colors.Normalize, show=True, save=False, filename='', map_projection=None, transform=None, **kwargs)

Render a list of trajectories using the cartopy backend This function renders a list of trajectories to a cartopy map.

For documentation on the parameters, please see render_trajectories

tracktable.render.render_trajectories.render_trajectories_folium(trajectories, map_canvas=None, obj_ids=[], map_bbox=None, show_lines=True, gradient_hue=None, color_map='', line_color='', linewidth=2.4, show_points=False, point_size=0.6, point_color='', show_dot=True, dot_size=0.7, dot_color='white', trajectory_scalar_generator=<function path_length_fraction_generator>, trajectory_linewidth_generator=None, color_scale=matplotlib.colors.Normalize, show=False, save=False, filename='', tiles='cartodbdark_matter', attr='.', crs='EPSG3857', point_popup_properties=[], show_distance_geometry=False, distance_geometry_depth=4, show_scale=True, max_zoom=22, fast=False, **kwargs)

Render a list of trajectories using the folium backend This function renders a list of trajectories to a folium map.

For documentation on the parameters, please see render_trajectories

tracktable.render.render_trajectories.render_trajectories_ipyleaflet(trajectories, map_canvas=None, obj_ids=[], map_bbox=None, show_lines=True, gradient_hue=None, color_map='', line_color='', linewidth=2.4, show_points=False, point_size=0.6, point_color='', show_dot=True, dot_size=0.7, dot_color='white', trajectory_scalar_generator=<function path_length_fraction_generator>, trajectory_linewidth_generator=None, color_scale=matplotlib.colors.Normalize, show=False, save=False, filename='', tiles='cartodbdark_matter', attr='.', point_popup_properties=[], show_distance_geometry=False, distance_geometry_depth=4, show_scale=True, max_zoom=22, **kwargs)

Render a list of trajectories using the ipyleaflet backend This function renders a list of trajectories to a ipyleaflet map.

For documentation on the parameters, please see render_trajectories

tracktable.render.render_trajectories.render_trajectories_separate(trajectories, backend='', **kwargs)

Render a list of trajectories such that each trajectory is rendered separately in its own map. See render_trajectories for parameters

Parameters

trajectories (Tracktable trajectory or list of trajectory objects) – List of trajectories to render

Keyword Arguments

• backend (str) – The backend to use for rendering default is folium if in a notebook and cartopy otherwise.

• kwargs (dict) – Additional parameters to customize the rendered trajectory

Returns

No return value

tracktable.render.render_trajectories.render_trajectory(trajectory, backend='', **kwargs)

Render a single trajectory This function allows users to render a single trajectory, and just calls render_trajectories, which also handles single trajectories.

Parameters

trajectory (Trajectory) – The trajectory object to render

Keyword Arguments

• backend (str) – the rendering backend (cartopy, folium, etc) default is folium if in a notebook and cartopy otherwise.

• kwargs (dict) – see render_trajectories for other arguments

Returns

No return value

tracktable.render.render_trajectories.setup_colors(line_color, color_map, gradient_hue, point_color, color_scale, objid, i, linewidth_generator)

Processes the color optins and returns the current color maps This function determines what the current color map should be for lines and points given the various releated parameters and returns color maps for points and for lines.

Parameters

• (name of standard color as string, hex color string (line_color) – or matplotlib color object, or list of any of these): The single color to use for all the segments in each trajectory. Overrides color_map and gradient_hue values. Can be a list of matplotlib color name strings, hex color strings or matplotlib color objects the same length as the length of the list of trajectories.

• (name of standard colormap as string or matplotlib (color_map) – color_map object or list of either): The color map to use in rendering the segments of each trajectory.

• gradient_hue (float or list of floats) – hue or list of hues (one per trajectory) to be used in definig the gradient color map (dark to light) for the trajectories. Only used if line_color and color_map are not used (set to ‘’). If line_color, color_map and gradient_hue are all unset the default behavior is to set the gradient_hue based on a hash of the object_id

• = (name of standard color as string, hex color string (point_color) – or matplotlib color object, or list of any of these): The single color to use for all the points in each trajectory. Can be a list of matplotlib color name strings, hex color strings or matplotlib color objects the same length as the length of the list of trajectories. If not specified, the color matches the segment incident at the point.

• color_scale (matplotlib.colors.Normalize() or LogNorm()) – Linear or logarithmic scale

• objid (str) – ID used for MD5 Hash

• i (int) – Index for lists

• linewidth_generator (function) – Function to generate linewidths

Returns

Current color maps

tracktable.render.render_trajectories.transform(point, scale)

Transform the given point based on the scale factor

Parameters

• point (point) – Point transform

• scale (int) – Scale factor to transform by

Returns

Scaled (x,y) values