Skip to content

TripsLayer

Screenshot from Air Traffic Control example.

lonboard.TripsLayer

Bases: BaseArrowLayer

The TripsLayer renders animated paths that represent moving objects.

The easiest way to create a TripsLayer is by using the from_movingpandas constructor, where you can pass in a movingpandas.TrajectoryCollection.

Otherwise, this layer requires a specific Arrow input data schema to associate the timestamp of each coordinate with the spatial information in the LineString geometries.

In order to animate this layer, call the animate method.

Warning

The TripsLayer renders data representing a specific instance in time based on the current_time attribute.

If you don't see any data, use the animate method to automatically set current_time.

Passing in custom Arrow data

As with all layers, you can pass an Arrow Table into the table parameter of this layer. In the case of the TripsLayer, there must be one column in the table that is a GeoArrow LineString geometry column, tagged with the geoarrow.linestring extension name. Additionally, the get_timestamps accessor needs to be an Arrow list-typed column with a timestamp-typed child array. The get_timestamps column must have the exact same nesting as the LineString column. That is, there must be one timestamp for every coordinate in the LineString column. This is validated in data input.

auto_highlight class-attribute instance-attribute 

auto_highlight = tag(sync=True)

When true, the current object pointed to by the mouse pointer (when hovered over) is highlighted with highlightColor.

Requires pickable to be True.

  • Type: bool
  • Default: False

before_id class-attribute instance-attribute 

before_id = tag(sync=True)

The identifier of a layer in the Maplibre basemap layer stack.

This deck.gl layer will be rendered just before the layer with the given identifier. You can find such an identifier by inspecting the basemap style JSON.

For example, in the Carto Positron style, if you look at the raw JSON data, each layer has an "id" property. The first layer in the basemap stack has "id": "background". So if you pass before_id="background", you won't see your deck.gl layer because it will be rendered below all layers in the Maplibre basemap.

A common choice for Carto-based styles is to use before_id="watername_ocean" so that your deck.gl layer is rendered above the core basemap elements but below all text labels.

Info

This only has an effect when the map's basemap is a MaplibreBasemap, and the map is rendering in "interleaved" mode.

billboard class-attribute instance-attribute 

billboard = tag(sync=True)

If True, extrude the path in screen space (width always faces the camera). If False, the width always faces up.

  • Type: bool, optional
  • Default: False

cap_rounded class-attribute instance-attribute 

cap_rounded = tag(sync=True)

Type of caps. If True, draw round caps. Otherwise draw square caps.

  • Type: bool, optional
  • Default: False

current_time property 

current_time: datetime

Get the current time of the map as a datetime object.

Returns:

  • datetime –

    datetime object with current time.

extensions class-attribute instance-attribute 

extensions = tag(sync=True, **(widget_serialization))

A list of layer extension objects to add additional features to a layer.

fade_trail class-attribute instance-attribute 

fade_trail = tag(sync=True)

Whether or not the path fades out.

  • Type: bool, optional
  • Default: True

get_color class-attribute instance-attribute 

get_color = ColorAccessor(None, allow_none=True)

The color of each path in the format of [r, g, b, [a]]. Each channel is a number between 0-255 and a is 255 if not supplied.

  • Type: ColorAccessor, optional
    • If a single list or tuple is provided, it is used as the color for all paths.
    • If a numpy or pyarrow array is provided, each value in the array will be used as the color for the path at the same row index.
  • Default: [0, 0, 0, 255].

get_timestamps class-attribute instance-attribute 

get_timestamps = TimestampAccessor(None, allow_none=True)

The timestamp of each coordinate.

get_width class-attribute instance-attribute 

get_width = FloatAccessor(None, allow_none=True)

The width of each path, in units specified by width_units (default 'meters').

  • Type: FloatAccessor, optional
    • If a number is provided, it is used as the width for all paths.
    • If an array is provided, each value in the array will be used as the width for the path at the same row index.
  • Default: 1.

highlight_color class-attribute instance-attribute 

highlight_color = VariableLengthTuple(
    Int(), default_value=None, minlen=3, maxlen=4
)

RGBA color to blend with the highlighted object (the hovered over object if auto_highlight=true). When the value is a 3 component (RGB) array, a default alpha of 255 is applied.

  • Type: List or Tuple of integers
  • Default: [0, 0, 128, 128]

joint_rounded class-attribute instance-attribute 

joint_rounded = tag(sync=True)

Type of joint. If True, draw round joints. Otherwise draw miter joints.

  • Type: bool, optional
  • Default: False

miter_limit class-attribute instance-attribute 

miter_limit = tag(sync=True)

The maximum extent of a joint in ratio to the stroke width. Only works if jointRounded is False.

  • Type: float, optional
  • Default: 4

opacity class-attribute instance-attribute 

opacity = tag(sync=True)

The opacity of the layer.

  • Type: float. Must range between 0 and 1.
  • Default: 1

pickable class-attribute instance-attribute 

pickable = tag(sync=True)

Whether the layer responds to mouse pointer picking events.

This must be set to True for tooltips and other interactive elements to be available. This can also be used to only allow picking on specific layers within a map instance.

Note that picking has some performance overhead in rendering. To get the absolute best rendering performance with large data (at the cost of removing interactivity), set this to False.

  • Type: bool
  • Default: True

selected_index class-attribute instance-attribute 

selected_index = tag(sync=True)

The positional index of the most-recently clicked on row of data.

You can use this to access the full row of data from a GeoDataFrame

gdf.iloc[layer.selected_index]

Setting a value here from Python will do nothing. This attribute only exists to be updated from JavaScript on a map click. Note that pickable must be True (the default) on this layer for the JavaScript onClick handler to work; if pickable is set to False, selected_index will never update.

Note that you can use observe to call a function whenever a new value is received from JavaScript. Refer here for an example.

table class-attribute instance-attribute 

table = ArrowTableTrait(allowed_geometry_types={LINESTRING})

An Arrow table with data for this layer.

Some downstream layers will require this table to have a geospatial column. Other layers, such as the H3HexagonLayer will accept non-geospatial data in conjunction with other accessors.

trail_length class-attribute instance-attribute 

trail_length = tag(sync=True)

Trail length.

  • Type: float, optional
  • Default: 120

visible class-attribute instance-attribute 

visible = tag(sync=True)

Whether the layer is visible.

Under most circumstances, using the visible attribute to control the visibility of layers is recommended over removing/adding the layer from the Map.layers list.

In particular, toggling the visible attribute will persist the layer on the JavaScript side, while removing/adding the layer from the Map.layers list will re-download and re-render from scratch.

  • Type: bool
  • Default: True

width_max_pixels class-attribute instance-attribute 

width_max_pixels = tag(sync=True)

The maximum path width in pixels. This prop can be used to prevent the path from getting too thick when zoomed in.

  • Type: float, optional
  • Default: None

width_min_pixels class-attribute instance-attribute 

width_min_pixels = tag(sync=True)

The minimum path width in pixels. This prop can be used to prevent the path from getting too thin when zoomed out.

  • Type: float, optional
  • Default: 0

width_scale class-attribute instance-attribute 

width_scale = tag(sync=True)

The path width multiplier that multiplied to all paths.

  • Type: float, optional
  • Default: 1

width_units class-attribute instance-attribute 

width_units = tag(sync=True)

The units of the line width, one of 'meters', 'common', and 'pixels'. See unit system.

  • Type: str, optional
  • Default: 'meters'

animate 

animate(
    *, step: timedelta, fps: float = 50, strftime_fmt: str | None = None
) -> HBox

Animate this layer with an ipywidgets.Play controller.

You can change how "fast" the animation is perceived by either increasing the amount of "data time" in each animation step, or by having more animation frames per second.

As an example, passing step=timedelta(seconds=60) will set each time step of the animation to be 60 "data seconds". Setting fps=50 (the default) causes there to be 50 animation frames per second.

Note that for large data, it's possible there will be some rendering lag and data may not actually update at the desired frames per second.

If you call animate multiple times, only the most recently produced Play widget will be active and linked to the map.

Other Parameters:

  • step (timedelta) –

    the length of time in the data to progress between each animation frame.

  • fps (float) –

    the number of animation frames per second. Defaults to 50.

  • strftime_fmt (str | None) –

    the format string passed to datetime.strftime. Defaults to an inferred format string.

Returns:

from_movingpandas classmethod 

from_movingpandas(
    traj_collection: TrajectoryCollection, **kwargs: Unpack[TripsLayerKwargs]
) -> Self

Construct a TripsLayer from a MovingPandas TrajectoryCollection.

This is the simplest way to construct a TripsLayer. Under the hood, this constructor will convert the TrajectoryCollection to a GeoArrow table with a LineString geometry column for each row. It will also create a Timestamp Arrow column from the TrajectoryCollection's DatetimeIndex.

Parameters:

Other Parameters:

  • kwargs (Unpack[TripsLayerKwargs]) –

    keyword args to pass to the TripsLayer constructor.

stop_animation 

stop_animation() -> None

Stop any existing animation.

This will unlink the linking between the Play widget generated by animate and the layer.

To reanimate the map, call animate again.