WarpMap

WarpMap(
    source_timeline_id,
    target_timeline_id,
    interpolation_map,
    source_unit=None,
    target_unit=None,
)

Bidirectional coordinate warping derived from alignment data.

A WarpMap converts coordinates from a source timeline to a target timeline (and back) using linear interpolation between anchor points extracted from a timetoalign.MatchLine.

Internally it delegates to an timetoalign.maps.interpolation.InterpolationMap for O(log n) lookup. The materialise() method produces a complete copy of a source timetoalign.Timeline with all coordinates warped to the target’s coordinate space.

Attributes: source_timeline_id: ID of the source timeline. target_timeline_id: ID of the target timeline. interpolation_map: The underlying InterpolationMap for coordinate conversion. source_unit: Unit of the source timeline (optional, informational). target_unit: Unit of the target timeline (optional, informational). n_anchors: Number of anchor points used for interpolation.

Examples: >>> warp = WarpMap.from_match_line(match_line, “audio”) >>> warp.forward(100.0) # score coord -> audio coord 45.5 >>> warp.inverse(45.5) # audio coord -> score coord 100.0

See Also: timetoalign.MatchLine timetoalign.InterpolationMap

Attributes

Name	Description
is_invertible	Whether the inverse mapping is defined.
n_anchors	Number of anchor points used for interpolation.
source_coords	The source coordinate anchor points (read-only).
target_coords	The target coordinate anchor points (read-only).

Methods

Name	Description
forward	Convert source coordinate(s) to target coordinate(s).
from_coordinate_pairs	Build a WarpMap from explicit coordinate arrays.
from_dict	Deserialize from dictionary.
from_match_line	Build a WarpMap from a MatchLine’s coordinate pairs.
inverse	Convert target coordinate(s) to source coordinate(s).
materialise	Produce a new Timeline with all contents warped to target coordinates.
to_dict	Serialize to dictionary.

forward

WarpMap.forward(coord)

Convert source coordinate(s) to target coordinate(s).

Uses linear interpolation between anchor points, with linear extrapolation outside the anchor range.

Args: coord: One or more source coordinates.

Returns: Corresponding target coordinate(s).

from_coordinate_pairs

WarpMap.from_coordinate_pairs(
    source_timeline_id,
    target_timeline_id,
    source_coords,
    target_coords,
    *,
    source_unit=None,
    target_unit=None,
)

Build a WarpMap from explicit coordinate arrays.

This lower-level constructor is useful when coordinate pairs are already available (e.g. from a Parquet file or external alignment tool) and do not need to be extracted from a MatchLine.

Args: source_timeline_id: ID of the source timeline. target_timeline_id: ID of the target timeline. source_coords: Sorted source coordinates (strictly increasing). target_coords: Corresponding target coordinates. source_unit: Unit of the source timeline (optional). target_unit: Unit of the target timeline (optional).

Returns: A new WarpMap.

Raises: ValueError: If fewer than 2 coordinate pairs, or if source_coords are not strictly increasing.

from_dict

WarpMap.from_dict(data)

Deserialize from dictionary.

Args: data: Dict as produced by to_dict().

Returns: A new WarpMap.

from_match_line

WarpMap.from_match_line(
    match_line,
    target_timeline_id,
    *,
    source_unit=None,
    target_unit=None,
)

Build a WarpMap from a MatchLine’s coordinate pairs.

Extracts (source_coord, target_coord) pairs from the MatchLine for the given target timeline, deduplicates by source coordinate (averaging target values for chords), and constructs the interpolation map.

Args: match_line: The MatchLine providing ordered stamps. target_timeline_id: The target timeline to warp towards. source_unit: Unit of the source timeline (optional). target_unit: Unit of the target timeline (optional).

Returns: A new WarpMap.

Raises: ValueError: If fewer than 2 coordinate pairs are available. ValueError: If target_timeline_id is not in the MatchLine’s target timelines.

inverse

WarpMap.inverse(coord)

Convert target coordinate(s) to source coordinate(s).

Uses linear interpolation between anchor points, with linear extrapolation outside the anchor range.

Args: coord: One or more target coordinates.

Returns: Corresponding source coordinate(s).

Raises: ValueError: If the target coordinates are not strictly monotonic (map is not invertible).

materialise

WarpMap.materialise(source_timeline)

Produce a new Timeline with all contents warped to target coordinates.

Creates a complete copy of the source timeline where every coordinate (events, children, regions) is converted via forward(). The resulting timeline:

• Has length equal to forward(source_timeline.length)
• Preserves the source’s unit (unless target_unit differs)
• Contains warped copies of all events
• Contains warped copies of all children (recursively)
• Contains warped copies of all regions
• Carries an inverse WarpMap as a ConversionMap for traceability

Args: source_timeline: The timeline to warp.

Returns: A new Timeline with warped coordinates.

Raises: ValueError: If source_timeline.id does not match self.source_timeline_id.

to_dict

WarpMap.to_dict()

Serialize to dictionary.

Returns: Dict with timeline IDs, units, and coordinate arrays.