tracktable.render.map_processing.paths module

Module contents

tracktable.render.paths - Functions to render trajectories as curves on a map

If you’re trying to figure out how to render a bunch of trajectories, take a look at draw_traffic and at tracktable/examples/render_trajectories_from_csv.py. Those will get you pointed in the right direction.

tracktable.render.map_processing.paths.concat_color_maps(color_maps, scalars_list, color_scale)[source]

Concatenate a list of color maps into a single color map with adjusted scalars and color_scale

Lists are assumed to be the same length

Parameters

  • color_maps (list) – a list of color_maps to concatenate

  • scalars_list (list[numpy arrays]) – a list of numpy arrays where each array contains the scalars associated with the respective color_map

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

Returns

Concatenated, scaled and adjusted single color map

tracktable.render.map_processing.paths.draw_traffic(traffic_map, trajectory_iterable, color_map='BrBG', color_scale=matplotlib.colors.Normalize, trajectory_scalar_generator=None, trajectory_linewidth_generator=None, linewidth=1, dot_size=2, dot_color='white', label_objects=False, label_generator=None, label_kwargs={}, axes=None, zorder=8, transform=cartopy.crs.Geodetic, show_points=False, point_size=12, point_color='', show_lines=True)[source]

Draw a set of (possibly decorated trajectories.

Parameters

  • traffic_map – Map projection (Basemap or Cartesian)

  • trajectory_iterable –

Keyword Arguments

  • color_map (str or Matplotlib colormap) – The name of a registered color map (Default: ‘BrBG’)

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

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

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

  • linewidth (float) – Constant linewidth if no generator is supplied (default 0.1, measured in points) (Default: 1)

  • dot_size (float) – Radius (in points) of a dot dawn at the latest point of each trajectory (Default: 2)

  • dot_color (str) – Color of spot that will be drawn at the latest point of each trajectory (Default: ‘white’)

  • label_objects (bool) – Whether to draw object_id at latest point of each trajectory (Default: False)

  • label_generator (TrajectoryPoint function) – Function to generate label for a trajectory (Default: None)

  • label_kwargs (dict) – Dictionary of arguments to be passed to labeler (FIXME) (Default: dict())

  • axes (Matplotlib axes) – The axis frame that will hold the Matplotlib artists that will render the trajectories (Default: None)

  • zorder (int) – Layer into which trajectories will be drawn (Default: 8)

  • transform (cartopy.crs.CRS) – The input projection (Default: cartopy.crs.Geodetic())

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

  • point_size (float) – Radius of the points along the path (in points default=12) (Default: 12)

  • point_color (str) – Color of the points along the path (Default: ‘’)

  • show_lines (bool) – Whether or not to show the trajectory lines (Default: True)

Returns

List of Matplotlib artists

Parameters in more detail:

traffic_map: Map instance (no default)

Cartopy GeoAxes instance of the space in which trajectories will be rendered. We don’t actually render into this object. Instead we use it to project points from longitude/latitude space down into the map’s local coordinate system. Take a look at tracktable.render.maps for several ways to create this map including a few convenience functions for common regions.

trajectory_iterable: iterable(Trajectory) (no default)

Sequence of Trajectory objects. We will traverse this exactly once. It can be any Python iterable.

color_map: Matplotlib color map or string (default ‘BrBG’)

Either a Matplotlib color map object or a string denoting the name of a registered color map. See the Matplotlib documentation for the names of the built-ins and the tracktable.render.colormaps module for several more examples and a way to create your own.

color_scale: Matplotlib color normalizer (default Normalize())

Object that maps your scalar range onto a colormap. This will usually be either matplotlib.colors.Normalize() or matplotlib.colors.LogNorm() for linear and logarithmic mapping respectively.

trajectory_scalar_generator: function(Trajectory) -> list(float)

You can color each line segment in a trajectory with your choice of scalars. This argument must be a function that computes those scalars for a trajectory or else None if you don’t care. The scalar function should take a Trajectory as its input and return a list of len(trajectory) - 1 scalars, one for each line segment to be drawn.

trajectory_linewidth_generator: function(Trajectory) -> list(float)

Just as you can generate a scalar (and thus a color) for each line segment, you can also generate a width for that segment. If you supply a value for this argument then it should take a Trajectory as its input and return a list of len(trajectory)-1 scalars specifying the width for each segment. This value is measured in points. If you need a single linewidth all the way through use the ‘linewidth’ argument.

linewidth: float (default 0.1)

This is the stroke width measured in points that will be used to draw the line segments in each trajectory. If you need different per-segment widths then use trajectory_linewidth_generator.

dot_size: float (default 2)

If this value is non-zero then a dot will be drawn at the point on each trajectory that has the largest timestamp. It will be dot_size points in radius and will be colored with whatever scalar is present at that point of the trajectory.

TODO: Add a point_size_generator argument to allow programmatic control of this argument.

label_objects: boolean (default False)

You can optionally label the point with the largest timestamp in each trajectory. To do so you must supply ‘label_objects=True’ and also a function for the label_generator argument.

label_generator: function(TrajectoryPoint) -> string

Construct a label for the specified trajectory. The result must be a string. This argument is ignored if label_objects is False.

TODO: Test whether Unicode strings will work here.

label_text_kwargs: dict (default empty)

We ultimately render labels using matplotlib.axes.Text(). If you want to pass in arguments to change the font, font size, angle or other parameters, specify them here.

axes: matplotlib.axes.Axes (default pyplot.gca())

This is the axis frame that will hold the Matplotlib artists that will render the trajectories. By default it will be whatever pyplot thinks the current axis set is.

zorder: int (default 8)

Height level where the trajectories will be drawn. If you want them to be on top of the map and anything else you draw on it then make this value large. It has no range limit.

transform: cartopy.crs.CRS (default cartopy.crs.Geodetic())

The input projection. Needed to get nearly any projection but PlateCarree to work correctly.

show_points: boolean (default False)

True if points along the trajectory should be rendered

point_size: int (default 12)

If show_poitns is true, the size of the markers rendered at each point in the trajectory.

point_color: string (default ‘’)

If show_points is true, the color of the markers rendered at each point in the trajectory

show_lines: boolean (default True)

True if the trajectory lines (piecewise-linear path) should be rendered

tracktable.render.map_processing.paths.points_to_segments(point_list, maximum_distance=None) → segment_list[source]

Given a list of N points, create a list of the N-1 line segments that connect them. Each segment is a list containing two points. If a value is supplied for maximum_distance, any segment longer than that distance will be ignored.

In English: We discard outliers.

Parameters

point_list (list) – List of points to be connected

Keyword Arguments

maximum_distance (float) – Maximum length that a segment can be

Returns

Segements that connect the points

tracktable.render.map_processing.paths.remove_duplicate_points(trajectory)[source]

Create a new trajectory with no adjacent duplicate points

Duplicate positions in a trajectory lead to degenerate line segments. This, in turn, gives some of the back-end renderers fits. The cleanest thing to do is to use the input trajectory to compute a new one s.t. no segments are degenerate.

There’s still one problem case: if the entire trajectory is a single position, you will get back a trajectory where the only two points (beginning and end) are at the same position.

Parameters

trajectory (tracktable.core.Trajectory) – trajectory to de-duplicate

Returns

New trajectory with some of the points from the input

tracktable.render.map_processing.paths.unwrap_path(locs)[source]
Inspects a list of [lat, lon] coordinates. If the trajectory crosses

the antimeridian (180 deg. Long), ‘unwrap’ the trajectory by projecting longitudinal values onto >+180 or <-180. This will prevent horizontal lines from streaking across a mercator projection, when plotting the trajectory in mapping packages like Folium. Operates by comparing pairs of elements (coord. point tuples) for the entire list.

Parameters

locs (list) – A list of (lat,lon) tuples

Returns

No return value, modifies the locs[] list in-place.