mappymatch.matchers.lcss.ops

Functions

add_matches_for_stationary_points(matches, ...)	Restore stationary points to the matched results.
drop_stationary_points(trace, stationary_index)	Remove stationary points from a trace while keeping the first point of each group.
find_stationary_points(trace)	Identify groups of consecutive GPS points that represent stationary positions.
join_segment(road_map, a, b)	Join two trajectory segments together, routing between them if there's a gap.
new_path(road_map, trace)	Compute a candidate path through the road network for a GPS trace.
same_trajectory_scheme(scheme1, scheme2)	Compares two trajectory schemes for equality
split_trajectory_segment(road_map, ...)	Split a trajectory segment at its cutting points into multiple sub-segments.

Classes

StationaryIndex(i_index, c_index)

An index of a stationary point in a trajectory

mappymatch.matchers.lcss.ops.join_segment(road_map: MapInterface, a: TrajectorySegment, b: TrajectorySegment) → TrajectorySegment

Join two trajectory segments together, routing between them if there's a gap.

This function concatenates two trajectory segments end-to-end. If the paths don't connect directly (i.e., the end junction of segment A doesn't match the start junction of segment B), it attempts to find a shortest path to bridge the gap.

Used during the LCSS algorithm after splitting segments to recombine them into a complete trajectory.

Args:

road_map: The road network used for finding connecting paths a: The first trajectory segment (will be the start of the combined segment) b: The second trajectory segment (will be the end of the combined segment)

Returns:

A new TrajectorySegment with combined traces and paths. If a connecting path is found, it's inserted between the two path segments. If no path exists (disconnected network components), the paths are simply concatenated.

mappymatch.matchers.lcss.ops.new_path(road_map: MapInterface, trace: Trace) → List[Road]

Compute a candidate path through the road network for a GPS trace.

This computes the shortest path from the first coordinate to the last coordinate in the trace, using the road network's shortest path algorithm. This path serves as the initial candidate path for LCSS matching.

Args:

road_map: The road network to route on trace: The GPS trace to compute a path for

Returns:

A list of Road objects representing the shortest path from the trace's first to last coordinate. Returns an empty list if the trace has fewer than 1 coordinate.

mappymatch.matchers.lcss.ops.split_trajectory_segment(road_map: MapInterface, trajectory_segment: TrajectorySegment) → List[TrajectorySegment]

Split a trajectory segment at its cutting points into multiple sub-segments.

This is a core operation in the LCSS algorithm. It divides a trajectory at identified cutting points, computes new candidate paths for each sub-segment, and merges any resulting segments that are too short (fewer than 2 trace points or 1 path edge).

The splitting process helps refine matches by allowing different parts of the trajectory to follow different paths through the network.

Args:

road_map: The road network used to compute paths for the new segments trajectory_segment: The segment to split, must have cutting_points populated

Returns:

A list of new TrajectorySegments created by splitting at cutting points. Returns the original segment unchanged if: - The trace has fewer than 2 points - No cutting points are defined - Splitting would not improve the match

Short segments (< 2 trace points or < 1 path edge) are automatically merged with adjacent segments.

mappymatch.matchers.lcss.ops.same_trajectory_scheme(scheme1: List[TrajectorySegment], scheme2: List[TrajectorySegment]) → bool

Compares two trajectory schemes for equality

Args:

scheme1: the first trajectory scheme scheme2: the second trajectory scheme

Returns:

True if the two schemes are equal, False otherwise

class mappymatch.matchers.lcss.ops.StationaryIndex(i_index: List[int], c_index: List[Any])

An index of a stationary point in a trajectory

Attributes:

trace_index: the index of the trace coord_index: the index of the coordinate

i_index: List[int]

Alias for field number 0

c_index: List[Any]

Alias for field number 1

mappymatch.matchers.lcss.ops.find_stationary_points(trace: Trace) → List[StationaryIndex]

Identify groups of consecutive GPS points that represent stationary positions.

Stationary points occur when a GPS device records multiple positions while not moving, or moving very slowly. These can be caused by waiting at traffic lights, parking, or GPS noise. Identifying them allows the LCSS matcher to handle them specially.

Points are considered stationary if they are within 0.001 meters (1mm) of the previous point - essentially the same location accounting for floating-point precision.

Args:

trace: The GPS trace to analyze for stationary points

Returns:

A list of StationaryIndex objects, each representing a group of consecutive stationary points. Each StationaryIndex contains: - i_index: List of integer indices in the trace - c_index: List of coordinate IDs

mappymatch.matchers.lcss.ops.drop_stationary_points(trace: Trace, stationary_index: List[StationaryIndex]) → Trace

Remove stationary points from a trace while keeping the first point of each group.

This is used to simplify traces before matching by collapsing groups of stationary points into single representatives. The LCSS matching is performed on the simplified trace, then stationary points are restored in the final results.

Args:

trace: The GPS trace to clean stationary_index: List of StationaryIndex objects identifying stationary point groups (from find_stationary_points)

Returns:

A new Trace with duplicate stationary points removed. For each stationary group, only the first point is retained.

mappymatch.matchers.lcss.ops.add_matches_for_stationary_points(matches: List[Match], stationary_index: List[StationaryIndex]) → List[Match]

Restore stationary points to the matched results.

After matching a simplified trace (with stationary points removed), this function adds back Match objects for all the removed stationary points. Each stationary point gets the same road match as the first point in its group, but retains its original coordinate ID.

This ensures the final MatchResult has one match for every point in the original trace.

Args:

matches: The matches from matching the simplified trace (without stationary points) stationary_index: List of StationaryIndex objects identifying which points were removed (from find_stationary_points)

Returns:

A new list of Match objects with stationary points restored, maintaining the original trace order and coordinate IDs