WarpMap

alignment.WarpMap(
    source_timeline_id,
    target_timeline_id,
    interpolation_map,
    source_unit,
    target_unit,
    source_number_type,
    target_number_type,
)

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

Name	Type	Description
source_timeline_id	str	ID of the source timeline.
target_timeline_id	str	ID of the target timeline.
interpolation_map	InterpolationMap	The underlying InterpolationMap for coordinate conversion.
source_unit	TimeUnit	Canonical unit of the source timeline.
target_unit	TimeUnit	Canonical unit of the target timeline.
source_number_type	NumberType	Canonical source-axis number type.
target_number_type	NumberType	Canonical target-axis number type.
n_anchors	int	Number of anchor points used for interpolation.

Examples

>>> warp = WarpMap.from_match_line(match_line, "audio")
>>> warp.get_coordinate_at(100.0, format="float")
45.5
>>> warp.inverse().get_coordinate_at(45.5, format="float")
100.0

See Also

timetoalign.MatchLine timetoalign.InterpolationMap

Methods

Name	Description
from_coordinate_pairs	Build a WarpMap from typed coordinate pairs or alignment anchors.
from_dict	Deserialize from dictionary.
from_match_line	Build a WarpMap from a MatchLine’s coordinate pairs.
get_coordinate	Dispatch a scalar or plural source-position warp query.
get_coordinate_at	Warp one source position to the target canonical axis.
get_coordinates_at	Warp a collection of source positions to the target axis.
inverse	Return the cached inverse map with source and target swapped.
materialise	Produce a new Timeline with all contents warped to target coordinates.
to_dict	Serialize to dictionary.

from_coordinate_pairs

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

Build a WarpMap from typed coordinate pairs or alignment anchors.

Parameters

Name	Type	Description	Default
source_timeline_id	str	ID of the source timeline.	required
target_timeline_id	str	ID of the target timeline.	required
source_coords	list[IdCoordinate] | list[AlignmentAnchor]	Source IdCoordinate values, or complete AlignmentAnchor values. Duplicate sources are averaged only when their targets are compatible.	required
target_coords	list[IdCoordinate] | None	Target IdCoordinate values when separate source coordinates are supplied; omitted for anchors.	None
source_unit	TimeUnit | None	Explicit source unit validator or inferred anchor unit.	None
target_unit	TimeUnit | None	Explicit target unit validator or inferred anchor unit.	None
source_number_type	NumberType | None	Explicit source representation validator or inferred homogeneous anchor representation.	None
target_number_type	NumberType | None	Explicit target representation validator or inferred homogeneous anchor representation.	None

Returns

Name	Type	Description
	'WarpMap'	A new WarpMap.

Raises

Name	Type	Description
	TypeError	If coordinate lists use unsupported or mixed scalar forms.
	ValueError	If fewer than two pairs exist, typed identities or axis metadata conflict, source values are ambiguous, or remaining source coordinates are not strictly increasing.

from_dict

alignment.WarpMap.from_dict(data)

Deserialize from dictionary.

Parameters

Name	Type	Description	Default
data	dict[str, Any]	Dict as produced by to_dict().	required

Returns

Name	Type	Description
	'WarpMap'	A new WarpMap.

from_match_line

alignment.WarpMap.from_match_line(
    match_line,
    target_timeline_id,
    *,
    source_unit=None,
    target_unit=None,
    source_number_type=None,
    target_number_type=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 compatible chord coordinates, and constructs the interpolation map. A repeated source coordinate with materially different targets is rejected.

Parameters

Name	Type	Description	Default
match_line	'MatchLine'	The MatchLine providing ordered stamps.	required
target_timeline_id	str	The target timeline to warp towards.	required
source_unit	'TimeUnit | None'	Explicit source unit, which must match every anchor.	None
target_unit	'TimeUnit | None'	Explicit target unit, which must match every anchor.	None
source_number_type	NumberType | None	Explicit canonical source representation.	None
target_number_type	NumberType | None	Explicit canonical target representation.	None

Returns

Name	Type	Description
	'WarpMap'	A new WarpMap.

Raises

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

get_coordinate

alignment.WarpMap.get_coordinate(
    at,
    timeline_id=None,
    *,
    format='id_coordinate',
    rounding='round',
)

Dispatch a scalar or plural source-position warp query.

Parameters

Name	Type	Description	Default
at	CoordinateInput | CoordinateCollection	One source position or a coordinate collection.	required
timeline_id	str | None	Optional target-axis identity validator.	None
format	CoordinateFormat	Requested coordinate output format.	'id_coordinate'
rounding	Rounding	Integral projection mode.	'round'

Returns

Name	Type	Description
	CoordinateResult | list[CoordinateResult] | pd.Series	The selected precise-getter result.

get_coordinate_at

alignment.WarpMap.get_coordinate_at(
    at,
    timeline_id=None,
    *,
    format='id_coordinate',
    rounding='round',
)

Warp one source position to the target canonical axis.

Parameters

Name	Type	Description	Default
at	CoordinateInput	Source position.	required
timeline_id	str | None	Optional target-axis identity validator.	None
format	CoordinateFormat	Requested coordinate output format.	'id_coordinate'
rounding	Rounding	Integral projection mode.	'round'

Returns

Name	Type	Description
	CoordinateResult | pd.Series	One target coordinate projection or a length-one Series.

get_coordinates_at

alignment.WarpMap.get_coordinates_at(
    at,
    timeline_id=None,
    *,
    format='id_coordinate',
    rounding='round',
)

Warp a collection of source positions to the target axis.

Parameters

Name	Type	Description	Default
at	CoordinateCollection	Source positions to resolve atomically.	required
timeline_id	str | None	Optional target-axis identity validator.	None
format	CoordinateFormat	Requested coordinate output format.	'id_coordinate'
rounding	Rounding	Integral projection mode.	'round'

Returns

Name	Type	Description
	list[CoordinateResult] | pd.Series	A list of projections or canonical-value Series.

inverse

alignment.WarpMap.inverse()

Return the cached inverse map with source and target swapped.

Returns

Name	Type	Description
	'WarpMap'	A WarpMap converting target coordinates back to source coordinates.

Raises

Name	Type	Description
	ValueError	If the target coordinates are not strictly monotonic (map is not invertible).

materialise

alignment.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 by calling this map. The resulting timeline:

• Has length equal to the mapped 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

Parameters

Name	Type	Description	Default
source_timeline	'Timeline'	The timeline to warp.	required

Returns

Name	Type	Description
	'Timeline'	A new Timeline with warped coordinates.

Raises

Name	Type	Description
	ValueError	If source_timeline.id does not match self.source_timeline_id.

to_dict

alignment.WarpMap.to_dict()

Serialize to dictionary.

Returns

Name	Type	Description
	dict[str, Any]	Dict with timeline IDs, units, and coordinate arrays.