tracktable.render.paths module

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.paths.draw_traffic(traffic_map, trajectory_iterable, color_map='BrBG', color_scale=matplotlib.colors.Normalize, trajectory_scalar_generator=None, trajectory_linewidth_generator=None, linewidth=0.1, dot_size=2, dot_color='white', label_objects=False, label_generator=None, label_kwargs={}, axes=None, zorder=8, log_function=<built-in method write of _io.TextIOWrapper object>)[source]

Draw a set of (possibly decorated trajectories.

Parameters

  • traffic_map – Map projection (Basemap or Cartesian)

  • color_map – String (colormap name) or Matplotlib colormap object

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

  • trajectory_scalar_generator – Function to generate scalars for a trajectory (default None)

  • trajectory_linewidth_generator – Function to generate path widths for a trajectory (default None)

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

  • dot_size – Radius (in points, default 2) of spot that will be drawn at the head of each trajectory

  • dot_color – Color of spot that will be drawn at the head of each trajectory

  • label_objects – Boolean (default False) deciding whether to draw object_id at head of each trajectory

  • label_generator – Function to generate label for a trajectory (default None)

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

  • axes – Matplotlib axes object into which trajectories will be rendered

  • zorder – Layer into which trajectories will be drawn (default 8).

  • log_function – Function to print, save or discard informational messages

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 head of each trajectory. It will be dot_size points in radius and will be colored with whatever scalar is present at the head of the trajectory.

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

label_objects: boolean (default False)

You can optionally label the head of 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.

log_function: function(string) (default sys.stderr.write)

The draw_paths function generates occasional status messages. It will pass them to this function. You can use this to display them to the user, write them to a file or ignore them entirely.

tracktable.render.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.

tracktable.render.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.paths.unwrap_path(locs)[source]
Function:

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.

Input:

locs: a list of (lat,lon) tuples

Output:

None modifies the locs[] list in-place.