matching

`sleap_io.model.matching` ¶

Unified matcher system for comparing and matching data structures during merging.

This module provides configurable matchers for comparing skeletons, instances, tracks, and videos during merge operations. The matchers use various strategies to determine when data structures should be considered equivalent during merging.

Key features: - Skeleton matching: exact, structure-based, overlap, and subset matching - Instance matching: spatial proximity, track identity, and bounding box IoU - Track matching: by name or object identity - Identity matching: by name or object identity - Category matching: by name or object identity - Video matching: path, basename, content, and auto matching

Video matching supports path-based, filename-based, content-based, and automatic strategies.

Classes:

Name	Description
`Category`	Ground-truth class membership of a detection (e.g. species, sex, condition).
`CategoryMatchMethod`	Methods for matching categories.
`CategoryMatcher`	Matcher for comparing and matching categories.
`ConflictResolution`	Information about a conflict that was resolved during merging.
`ErrorMode`	Error handling modes for merge operations.
`FrameStrategy`	Strategies for handling frame merging.
`Identity`	Ground-truth animal identity, persistent across sessions and videos.
`IdentityMatchMethod`	Methods for matching global identities.
`IdentityMatcher`	Matcher for comparing and matching global identities.
`Instance`	This class represents a ground truth instance such as an animal.
`InstanceMatchMethod`	Methods for matching instances.
`InstanceMatcher`	Matcher for comparing and matching instances.
`LabeledFrame`	Labeled data for a single frame of a video.
`MatchResult`	Result of matching two Labels objects.
`MergeError`	Base exception for merge errors.
`MergeProgressBar`	Context manager for merge progress tracking using tqdm.
`MergeResult`	Result of a merge operation.
`Skeleton`	A description of a set of landmark types and connections between them.
`SkeletonMatchMethod`	Methods for matching skeletons.
`SkeletonMatcher`	Matcher for comparing and matching skeletons.
`SkeletonMismatchError`	Raised when skeletons don't match during merge.
`Track`	An object that represents the same animal/object across multiple detections.
`TrackMatchMethod`	Methods for matching tracks.
`TrackMatcher`	Matcher for comparing and matching tracks.
`Video`	`Video` class used by sleap to represent videos and data associated with them.
`VideoMatchMethod`	Methods for matching videos.
`VideoMatcher`	Matcher for comparing and matching videos.

Functions:

Name	Description
`is_same_file`	Check if two videos refer to the same underlying file.
`original_videos_conflict`	Check if two videos have conflicting original_video references.
`shapes_compatible`	Check if two videos have compatible shapes.

Attributes:

Name	Type	Description
`AUTO_VIDEO_MATCHER`		Matcher for comparing and matching videos.
`BASENAME_VIDEO_MATCHER`		Matcher for comparing and matching videos.
`DUPLICATE_MATCHER`		Matcher for comparing and matching instances.
`IDENTITY_INSTANCE_MATCHER`		Matcher for comparing and matching instances.
`IDENTITY_TRACK_MATCHER`		Matcher for comparing and matching tracks.
`IMAGE_DEDUP_VIDEO_MATCHER`		Matcher for comparing and matching videos.
`IOU_MATCHER`		Matcher for comparing and matching instances.
`NAME_CATEGORY_MATCHER`		Matcher for comparing and matching categories.
`NAME_IDENTITY_MATCHER`		Matcher for comparing and matching global identities.
`NAME_TRACK_MATCHER`		Matcher for comparing and matching tracks.
`OVERLAP_SKELETON_MATCHER`		Matcher for comparing and matching skeletons.
`PATH_VIDEO_MATCHER`		Matcher for comparing and matching videos.
`SHAPE_VIDEO_MATCHER`		Matcher for comparing and matching videos.
`STRUCTURE_SKELETON_MATCHER`		Matcher for comparing and matching skeletons.
`SUBSET_SKELETON_MATCHER`		Matcher for comparing and matching skeletons.
`TYPE_CHECKING`		Returns True when the argument is true, False otherwise.
`__cached__`		str(object='') -> str
`__doc__`		str(object='') -> str
`__file__`		str(object='') -> str
`__name__`		str(object='') -> str
`__package__`		str(object='') -> str

`AUTO_VIDEO_MATCHER = VideoMatcher(method=<VideoMatchMethod.AUTO: 'auto'>, strict=False, content_frames=3, compare_predictions='auto', compare_images=False, image_similarity_threshold=0.05)` `module-attribute` ¶

Matcher for comparing and matching videos.

Attributes:

Name	Type	Description
`method`		The matching method to use. Can be a VideoMatchMethod enum value or a string that will be converted to the enum. Default is AUTO.
`strict`		Whether to use strict path matching for the PATH method. When True, paths must be exactly identical. When False, paths are normalized before comparison. Only used when method is PATH. Default is False.
`content_frames`		Minimum number of matching frames required for pose/image matching to confirm a match. If fewer common frames exist, requires all of them to match. Default 3.
`compare_predictions`		Whether to include predicted instances in pose matching. "auto" (default): Include only if video has 100% predictions (no user instances). True: Always include predictions. False: Never include predictions (user instances only).
`compare_images`		Whether to compare frame images via pixel similarity. Expensive operation requiring frame decoding. Default False.
`image_similarity_threshold`		Maximum mean pixel difference (0-1 scale, normalized by 255) for images to be considered matching. Only used when compare_images=True. Default 0.05 (~13/255 pixels).

Notes

For AUTO method, use find_match() when matching against a list of candidates. The match() method for AUTO uses a simplified pairwise check that doesn't include the full leaf-uniqueness algorithm.

`BASENAME_VIDEO_MATCHER = VideoMatcher(method=<VideoMatchMethod.BASENAME: 'basename'>, strict=False, content_frames=3, compare_predictions='auto', compare_images=False, image_similarity_threshold=0.05)` `module-attribute` ¶

Matcher for comparing and matching videos.

Attributes:

Name	Type	Description
`method`		The matching method to use. Can be a VideoMatchMethod enum value or a string that will be converted to the enum. Default is AUTO.
`strict`		Whether to use strict path matching for the PATH method. When True, paths must be exactly identical. When False, paths are normalized before comparison. Only used when method is PATH. Default is False.
`content_frames`		Minimum number of matching frames required for pose/image matching to confirm a match. If fewer common frames exist, requires all of them to match. Default 3.
`compare_predictions`		Whether to include predicted instances in pose matching. "auto" (default): Include only if video has 100% predictions (no user instances). True: Always include predictions. False: Never include predictions (user instances only).
`compare_images`		Whether to compare frame images via pixel similarity. Expensive operation requiring frame decoding. Default False.
`image_similarity_threshold`		Maximum mean pixel difference (0-1 scale, normalized by 255) for images to be considered matching. Only used when compare_images=True. Default 0.05 (~13/255 pixels).

Notes

For AUTO method, use find_match() when matching against a list of candidates. The match() method for AUTO uses a simplified pairwise check that doesn't include the full leaf-uniqueness algorithm.

`DUPLICATE_MATCHER = InstanceMatcher(method=<InstanceMatchMethod.SPATIAL: 'spatial'>, threshold=5.0)` `module-attribute` ¶

Matcher for comparing and matching instances.

Attributes:

Name	Type	Description
`method`		The matching method to use. Can be an InstanceMatchMethod enum value or a string that will be converted to the enum. Default is SPATIAL.
`threshold`		The threshold value used for matching. For SPATIAL method, this is the maximum pixel distance. For IOU method, this is the minimum IoU value. Not used for IDENTITY method. Default is 5.0.

`IDENTITY_INSTANCE_MATCHER = InstanceMatcher(method=<InstanceMatchMethod.IDENTITY: 'identity'>, threshold=5.0)` `module-attribute` ¶

Matcher for comparing and matching instances.

Attributes:

Name	Type	Description
`method`		The matching method to use. Can be an InstanceMatchMethod enum value or a string that will be converted to the enum. Default is SPATIAL.
`threshold`		The threshold value used for matching. For SPATIAL method, this is the maximum pixel distance. For IOU method, this is the minimum IoU value. Not used for IDENTITY method. Default is 5.0.

`IDENTITY_TRACK_MATCHER = TrackMatcher(method=<TrackMatchMethod.IDENTITY: 'identity'>)` `module-attribute` ¶

Matcher for comparing and matching tracks.

Attributes:

Name	Type	Description
`method`		The matching method to use. Can be a TrackMatchMethod enum value or a string that will be converted to the enum. Default is IDENTITY (matches only the same Track object; correctness-first). Use NAME to match by track name.

`IMAGE_DEDUP_VIDEO_MATCHER = VideoMatcher(method=<VideoMatchMethod.IMAGE_DEDUP: 'image_dedup'>, strict=False, content_frames=3, compare_predictions='auto', compare_images=False, image_similarity_threshold=0.05)` `module-attribute` ¶

Matcher for comparing and matching videos.

Attributes:

Name	Type	Description
`method`		The matching method to use. Can be a VideoMatchMethod enum value or a string that will be converted to the enum. Default is AUTO.
`strict`		Whether to use strict path matching for the PATH method. When True, paths must be exactly identical. When False, paths are normalized before comparison. Only used when method is PATH. Default is False.
`content_frames`		Minimum number of matching frames required for pose/image matching to confirm a match. If fewer common frames exist, requires all of them to match. Default 3.
`compare_predictions`		Whether to include predicted instances in pose matching. "auto" (default): Include only if video has 100% predictions (no user instances). True: Always include predictions. False: Never include predictions (user instances only).
`compare_images`		Whether to compare frame images via pixel similarity. Expensive operation requiring frame decoding. Default False.
`image_similarity_threshold`		Maximum mean pixel difference (0-1 scale, normalized by 255) for images to be considered matching. Only used when compare_images=True. Default 0.05 (~13/255 pixels).

Notes

For AUTO method, use find_match() when matching against a list of candidates. The match() method for AUTO uses a simplified pairwise check that doesn't include the full leaf-uniqueness algorithm.

`IOU_MATCHER = InstanceMatcher(method=<InstanceMatchMethod.IOU: 'iou'>, threshold=0.5)` `module-attribute` ¶

Matcher for comparing and matching instances.

Attributes:

Name	Type	Description
`method`		The matching method to use. Can be an InstanceMatchMethod enum value or a string that will be converted to the enum. Default is SPATIAL.
`threshold`		The threshold value used for matching. For SPATIAL method, this is the maximum pixel distance. For IOU method, this is the minimum IoU value. Not used for IDENTITY method. Default is 5.0.

`NAME_CATEGORY_MATCHER = CategoryMatcher(method=<CategoryMatchMethod.NAME: 'name'>)` `module-attribute` ¶

Matcher for comparing and matching categories.

Attributes:

Name	Type	Description
`method`		The matching method to use. Can be a CategoryMatchMethod enum value or a string that will be converted to the enum. Default is NAME (matches by the category `name`, which survives serialization and cross-file merges).

`NAME_IDENTITY_MATCHER = IdentityMatcher(method=<IdentityMatchMethod.NAME: 'name'>)` `module-attribute` ¶

Matcher for comparing and matching global identities.

Attributes:

Name	Type	Description
`method`		The matching method to use. Can be an IdentityMatchMethod enum value or a string that will be converted to the enum. Default is NAME (matches by the identity `name`, which survives serialization and cross-file merges).

`NAME_TRACK_MATCHER = TrackMatcher(method=<TrackMatchMethod.NAME: 'name'>)` `module-attribute` ¶

Matcher for comparing and matching tracks.

Attributes:

Name	Type	Description
`method`		The matching method to use. Can be a TrackMatchMethod enum value or a string that will be converted to the enum. Default is IDENTITY (matches only the same Track object; correctness-first). Use NAME to match by track name.

`OVERLAP_SKELETON_MATCHER = SkeletonMatcher(method=<SkeletonMatchMethod.OVERLAP: 'overlap'>, require_same_order=False, min_overlap=0.7)` `module-attribute` ¶

Matcher for comparing and matching skeletons.

Attributes:

Name	Type	Description
`method`		The matching method to use. Can be a SkeletonMatchMethod enum value or a string that will be converted to the enum. Default is STRUCTURE.
`require_same_order`		Whether to require nodes in the same order for STRUCTURE matching. Only used when method is STRUCTURE. Default is False.
`min_overlap`		Minimum Jaccard similarity required for OVERLAP matching. Only used when method is OVERLAP. Default is 0.5.

`PATH_VIDEO_MATCHER = VideoMatcher(method=<VideoMatchMethod.PATH: 'path'>, strict=True, content_frames=3, compare_predictions='auto', compare_images=False, image_similarity_threshold=0.05)` `module-attribute` ¶

Matcher for comparing and matching videos.

Attributes:

Name	Type	Description
`method`		The matching method to use. Can be a VideoMatchMethod enum value or a string that will be converted to the enum. Default is AUTO.
`strict`		Whether to use strict path matching for the PATH method. When True, paths must be exactly identical. When False, paths are normalized before comparison. Only used when method is PATH. Default is False.
`content_frames`		Minimum number of matching frames required for pose/image matching to confirm a match. If fewer common frames exist, requires all of them to match. Default 3.
`compare_predictions`		Whether to include predicted instances in pose matching. "auto" (default): Include only if video has 100% predictions (no user instances). True: Always include predictions. False: Never include predictions (user instances only).
`compare_images`		Whether to compare frame images via pixel similarity. Expensive operation requiring frame decoding. Default False.
`image_similarity_threshold`		Maximum mean pixel difference (0-1 scale, normalized by 255) for images to be considered matching. Only used when compare_images=True. Default 0.05 (~13/255 pixels).

Notes

For AUTO method, use find_match() when matching against a list of candidates. The match() method for AUTO uses a simplified pairwise check that doesn't include the full leaf-uniqueness algorithm.

`SHAPE_VIDEO_MATCHER = VideoMatcher(method=<VideoMatchMethod.SHAPE: 'shape'>, strict=False, content_frames=3, compare_predictions='auto', compare_images=False, image_similarity_threshold=0.05)` `module-attribute` ¶

Matcher for comparing and matching videos.

Attributes:

Name	Type	Description
`method`		The matching method to use. Can be a VideoMatchMethod enum value or a string that will be converted to the enum. Default is AUTO.
`strict`		Whether to use strict path matching for the PATH method. When True, paths must be exactly identical. When False, paths are normalized before comparison. Only used when method is PATH. Default is False.
`content_frames`		Minimum number of matching frames required for pose/image matching to confirm a match. If fewer common frames exist, requires all of them to match. Default 3.
`compare_predictions`		Whether to include predicted instances in pose matching. "auto" (default): Include only if video has 100% predictions (no user instances). True: Always include predictions. False: Never include predictions (user instances only).
`compare_images`		Whether to compare frame images via pixel similarity. Expensive operation requiring frame decoding. Default False.
`image_similarity_threshold`		Maximum mean pixel difference (0-1 scale, normalized by 255) for images to be considered matching. Only used when compare_images=True. Default 0.05 (~13/255 pixels).

Notes

For AUTO method, use find_match() when matching against a list of candidates. The match() method for AUTO uses a simplified pairwise check that doesn't include the full leaf-uniqueness algorithm.

`STRUCTURE_SKELETON_MATCHER = SkeletonMatcher(method=<SkeletonMatchMethod.STRUCTURE: 'structure'>, require_same_order=False, min_overlap=0.5)` `module-attribute` ¶

Matcher for comparing and matching skeletons.

Attributes:

Name	Type	Description
`method`		The matching method to use. Can be a SkeletonMatchMethod enum value or a string that will be converted to the enum. Default is STRUCTURE.
`require_same_order`		Whether to require nodes in the same order for STRUCTURE matching. Only used when method is STRUCTURE. Default is False.
`min_overlap`		Minimum Jaccard similarity required for OVERLAP matching. Only used when method is OVERLAP. Default is 0.5.

`SUBSET_SKELETON_MATCHER = SkeletonMatcher(method=<SkeletonMatchMethod.SUBSET: 'subset'>, require_same_order=False, min_overlap=0.5)` `module-attribute` ¶

Matcher for comparing and matching skeletons.

Attributes:

Name	Type	Description
`method`		The matching method to use. Can be a SkeletonMatchMethod enum value or a string that will be converted to the enum. Default is STRUCTURE.
`require_same_order`		Whether to require nodes in the same order for STRUCTURE matching. Only used when method is STRUCTURE. Default is False.
`min_overlap`		Minimum Jaccard similarity required for OVERLAP matching. Only used when method is OVERLAP. Default is 0.5.

`TYPE_CHECKING = False` `module-attribute` ¶

Returns True when the argument is true, False otherwise. The builtins True and False are the only two instances of the class bool. The class bool is a subclass of the class int, and cannot be subclassed.

`cached = '/home/runner/work/sleap-io/sleap-io/sleap_io/model/pycache/matching.cpython-313.pyc'` `module-attribute` ¶

str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.str() (if defined) or repr(object). encoding defaults to 'utf-8'. errors defaults to 'strict'.

doc = 'Unified matcher system for comparing and matching data structures during merging.\n\nThis module provides configurable matchers for comparing skeletons, instances, tracks,\nand videos during merge operations. The matchers use various strategies to determine\nwhen data structures should be considered equivalent during merging.\n\nKey features:\n- Skeleton matching: exact, structure-based, overlap, and subset matching\n- Instance matching: spatial proximity, track identity, and bounding box IoU\n- Track matching: by name or object identity\n- Identity matching: by name or object identity\n- Category matching: by name or object identity\n- Video matching: path, basename, content, and auto matching\n\nVideo matching supports path-based, filename-based, content-based, and\nautomatic strategies.\n' `module-attribute` ¶

str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.str() (if defined) or repr(object). encoding defaults to 'utf-8'. errors defaults to 'strict'.

`file = '/home/runner/work/sleap-io/sleap-io/sleap_io/model/matching.py'` `module-attribute` ¶

str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.str() (if defined) or repr(object). encoding defaults to 'utf-8'. errors defaults to 'strict'.

`name = 'sleap_io.model.matching'` `module-attribute` ¶

str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.str() (if defined) or repr(object). encoding defaults to 'utf-8'. errors defaults to 'strict'.

`package = 'sleap_io.model'` `module-attribute` ¶

str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.str() (if defined) or repr(object). encoding defaults to 'utf-8'. errors defaults to 'strict'.

`Category` ¶

Ground-truth class membership of a detection (e.g. species, sex, condition).

Where Track is an ephemeral temporal trajectory within a single video and Identity names a specific individual across videos, Category names the class an individual belongs to -- a group of individuals that share some attribute, typically assigned by classification or retrieved via re-ID (e.g. "female_fly", "fur_shaved", "mouse"). The per-detection binding is stored on Instance.category (and the analogous slot on the other detection modalities), alongside an optional category_score (assignment confidence) and category_embedding (the appearance vector it was classified from).

Attributes:

Name	Type	Description
`name`		Human-readable name for this category (e.g., `"female_fly"`). Not required to be unique, but `name` is how categories are matched across separately-loaded files and merges.
`metadata`		Arbitrary string-keyed, string-valued metadata (e.g. `{"color": "#e6194b", "supercategory": "insect"}`). Empty by default.

Notes

Category objects use object-identity equality (eq=False), matching Track and Identity. Use matches() (default method="name") to compare categories across files, where Python object identity is not meaningful.

Methods:

Name	Description
`__init__`	Method generated by attrs for class Category.
`__repr__`	Return a readable string representation.
`__setattr__`	Method generated by attrs for class Category.
`matches`	Check if this category matches another category.

Source code in sleap_io/model/category.py

@define(eq=False)
class Category:
    """Ground-truth class membership of a detection (e.g. species, sex, condition).

    Where `Track` is an ephemeral temporal trajectory within a single video and
    `Identity` names a specific individual across videos, `Category` names the
    *class* an individual belongs to -- a group of individuals that share some
    attribute, typically assigned by classification or retrieved via re-ID (e.g.
    ``"female_fly"``, ``"fur_shaved"``, ``"mouse"``). The per-detection binding is
    stored on ``Instance.category`` (and the analogous slot on the other detection
    modalities), alongside an optional ``category_score`` (assignment confidence)
    and ``category_embedding`` (the appearance vector it was classified from).

    Attributes:
        name: Human-readable name for this category (e.g., ``"female_fly"``). Not
            required to be unique, but ``name`` is how categories are matched
            across separately-loaded files and merges.
        metadata: Arbitrary string-keyed, string-valued metadata (e.g.
            ``{"color": "#e6194b", "supercategory": "insect"}``). Empty by default.

    Notes:
        `Category` objects use object-identity equality (``eq=False``), matching
        `Track` and `Identity`. Use `matches()` (default ``method="name"``) to
        compare categories across files, where Python object identity is not
        meaningful.
    """

    name: str = field(default="", validator=instance_of(str))
    metadata: dict[str, str] = field(factory=dict, validator=instance_of(dict))

    def matches(self, other: "Category", method: str = "name") -> bool:
        """Check if this category matches another category.

        Args:
            other: Another category to compare with.
            method: Matching method:

                - ``"name"`` (default): match by the `name` attribute, which
                  survives serialization and cross-file merges.
                - ``"identity"``: match by Python object identity (same object).

        Returns:
            True if the categories match according to the specified method.

        Raises:
            ValueError: If `method` is not one of the supported values.
        """
        if method == "name":
            return self.name == other.name
        elif method == "identity":
            return self is other
        else:
            raise ValueError(f"Unknown matching method: {method}")

    def __repr__(self) -> str:
        """Return a readable string representation."""
        return f'Category(name="{self.name}")'

`annotations = {'name': 'str', 'metadata': 'dict[str, str]'}` `class-attribute` ¶

dict() -> new empty dictionary dict(mapping) -> new dictionary initialized from a mapping object's (key, value) pairs dict(iterable) -> new dictionary initialized as if via: d = {} for k, v in iterable: d[k] = v dict(**kwargs) -> new dictionary initialized with the name=value pairs in the keyword argument list. For example: dict(one=1, two=2)

`__attrs_own_setattr__ = True` `class-attribute` ¶

Returns True when the argument is true, False otherwise. The builtins True and False are the only two instances of the class bool. The class bool is a subclass of the class int, and cannot be subclassed.

`__attrs_props__ = ClassProps(is_exception=False, is_slotted=True, has_weakref_slot=True, is_frozen=False, kw_only=<KeywordOnly.NO: 'no'>, collected_fields_by_mro=True, added_init=True, added_repr=False, added_eq=False, added_ordering=False, hashability=<Hashability.LEAVE_ALONE: 'leave_alone'>, added_match_args=True, added_str=False, added_pickling=True, on_setattr_hook=<function pipe.<locals>.wrapped_pipe at 0x7f08471ce840>, field_transformer=None)` `class-attribute` ¶

Effective class properties as derived from parameters to attr.s() or define() decorators.

This is the same data structure that attrs uses internally to decide how to construct the final class.

Warning:

This feature is currently **experimental** and is not covered by our
strict backwards-compatibility guarantees.

Attributes:

Name	Type	Description
`is_exception`	`bool`	Whether the class is treated as an exception class.
`is_slotted`	`bool`	Whether the class is `slotted <slotted classes>`.
`has_weakref_slot`	`bool`	Whether the class has a slot for weak references.
`is_frozen`	`bool`	Whether the class is frozen.
`kw_only`	`KeywordOnly`	Whether / how the class enforces keyword-only arguments on the `__init__` method.
`collected_fields_by_mro`	`bool`	Whether the class fields were collected by method resolution order. That is, correctly but unlike `dataclasses`.
`added_init`	`bool`	Whether the class has an attrs-generated `__init__` method.
`added_repr`	`bool`	Whether the class has an attrs-generated `__repr__` method.
`added_eq`	`bool`	Whether the class has attrs-generated equality methods.
`added_ordering`	`bool`	Whether the class has attrs-generated ordering methods.
`hashability`	`Hashability`	How `hashable <hashing>` the class is.
`added_match_args`	`bool`	Whether the class supports positional `match <match>` over its fields.
`added_str`	`bool`	Whether the class has an attrs-generated `__str__` method.
`added_pickling`	`bool`	Whether the class has attrs-generated `__getstate__` and `__setstate__` methods for `pickle`.
`on_setattr_hook`	`Callable[[Any, Attribute[Any], Any], Any] \| None`	The class's `__setattr__` hook.
`field_transformer`	`Callable[[Attribute[Any]], Attribute[Any]] \| None`	The class's `field transformers <transform-fields>`.

.. versionadded:: 25.4.0

doc = 'Ground-truth class membership of a detection (e.g. species, sex, condition).\n\nWhere `Track` is an ephemeral temporal trajectory within a single video and\n`Identity` names a specific individual across videos, `Category` names the\nclass an individual belongs to -- a group of individuals that share some\nattribute, typically assigned by classification or retrieved via re-ID (e.g.\n``"female_fly"``, ``"fur_shaved"``, ``"mouse"``). The per-detection binding is\nstored on ``Instance.category`` (and the analogous slot on the other detection\nmodalities), alongside an optional ``category_score`` (assignment confidence)\nand ``category_embedding`` (the appearance vector it was classified from).\n\nAttributes:\n name: Human-readable name for this category (e.g., ``"female_fly"``). Not\n required to be unique, but ``name`` is how categories are matched\n across separately-loaded files and merges.\n metadata: Arbitrary string-keyed, string-valued metadata (e.g.\n ``{"color": "#e6194b", "supercategory": "insect"}``). Empty by default.\n\nNotes:\n `Category` objects use object-identity equality (``eq=False``), matching\n `Track` and `Identity`. Use `matches()` (default ``method="name"``) to\n compare categories across files, where Python object identity is not\n meaningful.\n' `class-attribute` ¶

str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.str() (if defined) or repr(object). encoding defaults to 'utf-8'. errors defaults to 'strict'.

`firstlineno = 9` `class-attribute` ¶

int([x]) -> integer int(x, base=10) -> integer

Convert a number or string to an integer, or return 0 if no arguments are given. If x is a number, return x.int(). For floating-point numbers, this truncates towards zero.

If x is not a number or if base is given, then x must be a string, bytes, or bytearray instance representing an integer literal in the given base. The literal can be preceded by '+' or '-' and be surrounded by whitespace. The base defaults to 10. Valid bases are 0 and 2-36. Base 0 means to interpret the base from the string as an integer iteral.

`__match_args__ = ('name', 'metadata')` `class-attribute` ¶

Built-in immutable sequence.

If no argument is given, the constructor returns an empty tuple. If iterable is specified the tuple is initialized from iterable's items.

If the argument is a tuple, the return value is the same object.

`module = 'sleap_io.model.category'` `class-attribute` ¶

str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.str() (if defined) or repr(object). encoding defaults to 'utf-8'. errors defaults to 'strict'.

`slots = ('name', 'metadata', 'weakref')` `class-attribute` ¶

Built-in immutable sequence.

If no argument is given, the constructor returns an empty tuple. If iterable is specified the tuple is initialized from iterable's items.

If the argument is a tuple, the return value is the same object.

`__static_attributes__ = ()` `class-attribute` ¶

Built-in immutable sequence.

If no argument is given, the constructor returns an empty tuple. If iterable is specified the tuple is initialized from iterable's items.

If the argument is a tuple, the return value is the same object.

`weakref` `property` ¶

list of weak references to the object

`init(name='', metadata=NOTHING)` ¶

Method generated by attrs for class Category.

Source code in sleap_io/model/category.py

"""Category data structure for ground-truth class membership of detections."""

from __future__ import annotations

from attrs import define, field
from attrs.validators import instance_of


@define(eq=False)
class Category:

`repr()` ¶

Return a readable string representation.

Source code in sleap_io/model/category.py

def __repr__(self) -> str:
    """Return a readable string representation."""
    return f'Category(name="{self.name}")'

`setattr(name, val)` ¶

Method generated by attrs for class Category.

`matches(other, method='name')` ¶

Check if this category matches another category.

Parameters:

Name	Type	Description	Default
`other`	`Category`	Another category to compare with.	required
`method`	`str`	Matching method: `"name"` (default): match by the `name` attribute, which survives serialization and cross-file merges. `"identity"`: match by Python object identity (same object).	`'name'`

Returns:

Type	Description
`bool`	True if the categories match according to the specified method.

Raises:

Type	Description
`ValueError`	If `method` is not one of the supported values.

Source code in sleap_io/model/category.py

def matches(self, other: "Category", method: str = "name") -> bool:
    """Check if this category matches another category.

    Args:
        other: Another category to compare with.
        method: Matching method:

            - ``"name"`` (default): match by the `name` attribute, which
              survives serialization and cross-file merges.
            - ``"identity"``: match by Python object identity (same object).

    Returns:
        True if the categories match according to the specified method.

    Raises:
        ValueError: If `method` is not one of the supported values.
    """
    if method == "name":
        return self.name == other.name
    elif method == "identity":
        return self is other
    else:
        raise ValueError(f"Unknown matching method: {method}")

`CategoryMatchMethod` ¶

Bases: builtins.str, enum.Enum

Methods for matching categories.

Attributes:

Name	Type	Description
`NAME`		Match categories by their `name` attribute, which survives serialization and cross-file merges (default).
`IDENTITY`		Match categories by Python object identity (same object).

Source code in sleap_io/model/matching.py

class CategoryMatchMethod(str, Enum):
    """Methods for matching categories.

    Attributes:
        NAME: Match categories by their `name` attribute, which survives
            serialization and cross-file merges (default).
        IDENTITY: Match categories by Python object identity (same object).
    """

    NAME = "name"
    IDENTITY = "identity"

`IDENTITY = <CategoryMatchMethod.IDENTITY: 'identity'>` `class-attribute` ¶

Methods for matching categories.

Attributes:

Name	Type	Description
`NAME`		Match categories by their `name` attribute, which survives serialization and cross-file merges (default).
`IDENTITY`		Match categories by Python object identity (same object).

`NAME = <CategoryMatchMethod.NAME: 'name'>` `class-attribute` ¶

Methods for matching categories.

Attributes:

Name	Type	Description
`NAME`		Match categories by their `name` attribute, which survives serialization and cross-file merges (default).
`IDENTITY`		Match categories by Python object identity (same object).

doc = 'Methods for matching categories.\n\nAttributes:\n NAME: Match categories by their `name` attribute, which survives\n serialization and cross-file merges (default).\n IDENTITY: Match categories by Python object identity (same object).\n' `class-attribute` ¶

str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.str() (if defined) or repr(object). encoding defaults to 'utf-8'. errors defaults to 'strict'.

`module = 'sleap_io.model.matching'` `class-attribute` ¶

str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.str() (if defined) or repr(object). encoding defaults to 'utf-8'. errors defaults to 'strict'.

`CategoryMatcher` ¶

Matcher for comparing and matching categories.

Attributes:

Name	Type	Description
`method`		The matching method to use. Can be a CategoryMatchMethod enum value or a string that will be converted to the enum. Default is NAME (matches by the category `name`, which survives serialization and cross-file merges).

Methods:

Name	Description
`__eq__`	Method generated by attrs for class CategoryMatcher.
`__init__`	Method generated by attrs for class CategoryMatcher.
`__repr__`	Method generated by attrs for class CategoryMatcher.
`__setattr__`	Method generated by attrs for class CategoryMatcher.
`match`	Check if two categories match according to the configured method.

Source code in sleap_io/model/matching.py

@attrs.define
class CategoryMatcher:
    """Matcher for comparing and matching categories.

    Attributes:
        method: The matching method to use. Can be a CategoryMatchMethod enum
            value or a string that will be converted to the enum. Default is
            NAME (matches by the category `name`, which survives serialization
            and cross-file merges).
    """

    method: CategoryMatchMethod | str = attrs.field(
        default=CategoryMatchMethod.NAME,
        converter=lambda x: CategoryMatchMethod(x) if isinstance(x, str) else x,
    )

    def match(self, category1: Category, category2: Category) -> bool:
        """Check if two categories match according to the configured method."""
        return category1.matches(category2, method=self.method.value)

`annotations = {'method': 'CategoryMatchMethod | str'}` `class-attribute` ¶

dict() -> new empty dictionary dict(mapping) -> new dictionary initialized from a mapping object's (key, value) pairs dict(iterable) -> new dictionary initialized as if via: d = {} for k, v in iterable: d[k] = v dict(**kwargs) -> new dictionary initialized with the name=value pairs in the keyword argument list. For example: dict(one=1, two=2)

`__attrs_own_setattr__ = True` `class-attribute` ¶

Returns True when the argument is true, False otherwise. The builtins True and False are the only two instances of the class bool. The class bool is a subclass of the class int, and cannot be subclassed.

`__attrs_props__ = ClassProps(is_exception=False, is_slotted=True, has_weakref_slot=True, is_frozen=False, kw_only=<KeywordOnly.NO: 'no'>, collected_fields_by_mro=True, added_init=True, added_repr=True, added_eq=True, added_ordering=False, hashability=<Hashability.UNHASHABLE: 'unhashable'>, added_match_args=True, added_str=False, added_pickling=True, on_setattr_hook=<function pipe.<locals>.wrapped_pipe at 0x7f08471ce840>, field_transformer=None)` `class-attribute` ¶

Effective class properties as derived from parameters to attr.s() or define() decorators.

This is the same data structure that attrs uses internally to decide how to construct the final class.

Warning:

This feature is currently **experimental** and is not covered by our
strict backwards-compatibility guarantees.

Attributes:

Name	Type	Description
`is_exception`	`bool`	Whether the class is treated as an exception class.
`is_slotted`	`bool`	Whether the class is `slotted <slotted classes>`.
`has_weakref_slot`	`bool`	Whether the class has a slot for weak references.
`is_frozen`	`bool`	Whether the class is frozen.
`kw_only`	`KeywordOnly`	Whether / how the class enforces keyword-only arguments on the `__init__` method.
`collected_fields_by_mro`	`bool`	Whether the class fields were collected by method resolution order. That is, correctly but unlike `dataclasses`.
`added_init`	`bool`	Whether the class has an attrs-generated `__init__` method.
`added_repr`	`bool`	Whether the class has an attrs-generated `__repr__` method.
`added_eq`	`bool`	Whether the class has attrs-generated equality methods.
`added_ordering`	`bool`	Whether the class has attrs-generated ordering methods.
`hashability`	`Hashability`	How `hashable <hashing>` the class is.
`added_match_args`	`bool`	Whether the class supports positional `match <match>` over its fields.
`added_str`	`bool`	Whether the class has an attrs-generated `__str__` method.
`added_pickling`	`bool`	Whether the class has attrs-generated `__getstate__` and `__setstate__` methods for `pickle`.
`on_setattr_hook`	`Callable[[Any, Attribute[Any], Any], Any] \| None`	The class's `__setattr__` hook.
`field_transformer`	`Callable[[Attribute[Any]], Attribute[Any]] \| None`	The class's `field transformers <transform-fields>`.

.. versionadded:: 25.4.0

doc = 'Matcher for comparing and matching categories.\n\nAttributes:\n method: The matching method to use. Can be a CategoryMatchMethod enum\n value or a string that will be converted to the enum. Default is\n NAME (matches by the category `name`, which survives serialization\n and cross-file merges).\n' `class-attribute` ¶

str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.str() (if defined) or repr(object). encoding defaults to 'utf-8'. errors defaults to 'strict'.

`firstlineno = 925` `class-attribute` ¶

int([x]) -> integer int(x, base=10) -> integer

Convert a number or string to an integer, or return 0 if no arguments are given. If x is a number, return x.int(). For floating-point numbers, this truncates towards zero.

If x is not a number or if base is given, then x must be a string, bytes, or bytearray instance representing an integer literal in the given base. The literal can be preceded by '+' or '-' and be surrounded by whitespace. The base defaults to 10. Valid bases are 0 and 2-36. Base 0 means to interpret the base from the string as an integer iteral.

`__match_args__ = ('method',)` `class-attribute` ¶

Built-in immutable sequence.

If no argument is given, the constructor returns an empty tuple. If iterable is specified the tuple is initialized from iterable's items.

If the argument is a tuple, the return value is the same object.

`module = 'sleap_io.model.matching'` `class-attribute` ¶

str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.str() (if defined) or repr(object). encoding defaults to 'utf-8'. errors defaults to 'strict'.

`slots = ('method', 'weakref')` `class-attribute` ¶

Built-in immutable sequence.

If no argument is given, the constructor returns an empty tuple. If iterable is specified the tuple is initialized from iterable's items.

If the argument is a tuple, the return value is the same object.

`__static_attributes__ = ()` `class-attribute` ¶

Built-in immutable sequence.

If no argument is given, the constructor returns an empty tuple. If iterable is specified the tuple is initialized from iterable's items.

If the argument is a tuple, the return value is the same object.

`weakref` `property` ¶

list of weak references to the object

`eq(other)` ¶

Method generated by attrs for class CategoryMatcher.

Source code in sleap_io/model/matching.py

automatic strategies.
"""

from __future__ import annotations

from enum import Enum

`init(method=<CategoryMatchMethod.NAME: 'name'>)` ¶

Method generated by attrs for class CategoryMatcher.

Source code in sleap_io/model/matching.py

from typing import TYPE_CHECKING, Any

import attrs

`repr()` ¶

Method generated by attrs for class CategoryMatcher.

Source code in sleap_io/model/matching.py

"""Unified matcher system for comparing and matching data structures during merging.

This module provides configurable matchers for comparing skeletons, instances, tracks,
and videos during merge operations. The matchers use various strategies to determine
when data structures should be considered equivalent during merging.

Key features:
- Skeleton matching: exact, structure-based, overlap, and subset matching
- Instance matching: spatial proximity, track identity, and bounding box IoU
- Track matching: by name or object identity
- Identity matching: by name or object identity
- Category matching: by name or object identity
- Video matching: path, basename, content, and auto matching

Video matching supports path-based, filename-based, content-based, and

`setattr(name, val)` ¶

Method generated by attrs for class CategoryMatcher.

Source code in sleap_io/model/matching.py

        return match

# IMAGE MATCHING: Compare frame images (opt-in)
if self.compare_images:
    match = self._match_by_images(incoming, viable)
    if match is not None:
        return match

# No match found

`match(category1, category2)` ¶

Check if two categories match according to the configured method.

Source code in sleap_io/model/matching.py

def match(self, category1: Category, category2: Category) -> bool:
    """Check if two categories match according to the configured method."""
    return category1.matches(category2, method=self.method.value)

`ConflictResolution` ¶

Information about a conflict that was resolved during merging.

Attributes:

Name	Type	Description
`frame`		The labeled frame where the conflict occurred.
`conflict_type`		Type of conflict. Emitted values are `"instance_conflict"` (an instance pair conflicted under the chosen frame strategy) and `"negative_flag_conflict"` (the `is_negative` background marker was cleared because the merged frame now contains a user pose).
`original_data`		The original data before resolution.
`new_data`		The new/incoming data that caused the conflict.
`resolution`		Description of how the conflict was resolved.

Methods:

Name	Description
`__eq__`	Method generated by attrs for class ConflictResolution.
`__init__`	Method generated by attrs for class ConflictResolution.
`__repr__`	Method generated by attrs for class ConflictResolution.

Source code in sleap_io/model/matching.py

@attrs.define
class ConflictResolution:
    """Information about a conflict that was resolved during merging.

    Attributes:
        frame: The labeled frame where the conflict occurred.
        conflict_type: Type of conflict. Emitted values are
            ``"instance_conflict"`` (an instance pair conflicted under the
            chosen frame strategy) and ``"negative_flag_conflict"`` (the
            ``is_negative`` background marker was cleared because the merged
            frame now contains a user pose).
        original_data: The original data before resolution.
        new_data: The new/incoming data that caused the conflict.
        resolution: Description of how the conflict was resolved.
    """

    frame: LabeledFrame
    conflict_type: str
    original_data: Any
    new_data: Any
    resolution: str

`annotations = {'frame': 'LabeledFrame', 'conflict_type': 'str', 'original_data': 'Any', 'new_data': 'Any', 'resolution': 'str'}` `class-attribute` ¶

dict() -> new empty dictionary dict(mapping) -> new dictionary initialized from a mapping object's (key, value) pairs dict(iterable) -> new dictionary initialized as if via: d = {} for k, v in iterable: d[k] = v dict(**kwargs) -> new dictionary initialized with the name=value pairs in the keyword argument list. For example: dict(one=1, two=2)

`__attrs_own_setattr__ = False` `class-attribute` ¶

Returns True when the argument is true, False otherwise. The builtins True and False are the only two instances of the class bool. The class bool is a subclass of the class int, and cannot be subclassed.

`__attrs_props__ = ClassProps(is_exception=False, is_slotted=True, has_weakref_slot=True, is_frozen=False, kw_only=<KeywordOnly.NO: 'no'>, collected_fields_by_mro=True, added_init=True, added_repr=True, added_eq=True, added_ordering=False, hashability=<Hashability.UNHASHABLE: 'unhashable'>, added_match_args=True, added_str=False, added_pickling=True, on_setattr_hook=<function pipe.<locals>.wrapped_pipe at 0x7f08471ce840>, field_transformer=None)` `class-attribute` ¶

Effective class properties as derived from parameters to attr.s() or define() decorators.

This is the same data structure that attrs uses internally to decide how to construct the final class.

Warning:

This feature is currently **experimental** and is not covered by our
strict backwards-compatibility guarantees.

Attributes:

Name	Type	Description
`is_exception`	`bool`	Whether the class is treated as an exception class.
`is_slotted`	`bool`	Whether the class is `slotted <slotted classes>`.
`has_weakref_slot`	`bool`	Whether the class has a slot for weak references.
`is_frozen`	`bool`	Whether the class is frozen.
`kw_only`	`KeywordOnly`	Whether / how the class enforces keyword-only arguments on the `__init__` method.
`collected_fields_by_mro`	`bool`	Whether the class fields were collected by method resolution order. That is, correctly but unlike `dataclasses`.
`added_init`	`bool`	Whether the class has an attrs-generated `__init__` method.
`added_repr`	`bool`	Whether the class has an attrs-generated `__repr__` method.
`added_eq`	`bool`	Whether the class has attrs-generated equality methods.
`added_ordering`	`bool`	Whether the class has attrs-generated ordering methods.
`hashability`	`Hashability`	How `hashable <hashing>` the class is.
`added_match_args`	`bool`	Whether the class supports positional `match <match>` over its fields.
`added_str`	`bool`	Whether the class has an attrs-generated `__str__` method.
`added_pickling`	`bool`	Whether the class has attrs-generated `__getstate__` and `__setstate__` methods for `pickle`.
`on_setattr_hook`	`Callable[[Any, Attribute[Any], Any], Any] \| None`	The class's `__setattr__` hook.
`field_transformer`	`Callable[[Attribute[Any]], Attribute[Any]] \| None`	The class's `field transformers <transform-fields>`.

.. versionadded:: 25.4.0

doc = 'Information about a conflict that was resolved during merging.\n\nAttributes:\n frame: The labeled frame where the conflict occurred.\n conflict_type: Type of conflict. Emitted values are\n ``"instance_conflict"`` (an instance pair conflicted under the\n chosen frame strategy) and ``"negative_flag_conflict"`` (the\n ``is_negative`` background marker was cleared because the merged\n frame now contains a user pose).\n original_data: The original data before resolution.\n new_data: The new/incoming data that caused the conflict.\n resolution: Description of how the conflict was resolved.\n' `class-attribute` ¶

str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.str() (if defined) or repr(object). encoding defaults to 'utf-8'. errors defaults to 'strict'.

`firstlineno = 1321` `class-attribute` ¶

int([x]) -> integer int(x, base=10) -> integer

Convert a number or string to an integer, or return 0 if no arguments are given. If x is a number, return x.int(). For floating-point numbers, this truncates towards zero.

If x is not a number or if base is given, then x must be a string, bytes, or bytearray instance representing an integer literal in the given base. The literal can be preceded by '+' or '-' and be surrounded by whitespace. The base defaults to 10. Valid bases are 0 and 2-36. Base 0 means to interpret the base from the string as an integer iteral.

`__match_args__ = ('frame', 'conflict_type', 'original_data', 'new_data', 'resolution')` `class-attribute` ¶

Built-in immutable sequence.

If no argument is given, the constructor returns an empty tuple. If iterable is specified the tuple is initialized from iterable's items.

If the argument is a tuple, the return value is the same object.

`module = 'sleap_io.model.matching'` `class-attribute` ¶

str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.str() (if defined) or repr(object). encoding defaults to 'utf-8'. errors defaults to 'strict'.

`slots = ('frame', 'conflict_type', 'original_data', 'new_data', 'resolution', 'weakref')` `class-attribute` ¶

Built-in immutable sequence.

If no argument is given, the constructor returns an empty tuple. If iterable is specified the tuple is initialized from iterable's items.

If the argument is a tuple, the return value is the same object.

`__static_attributes__ = ()` `class-attribute` ¶

Built-in immutable sequence.

If no argument is given, the constructor returns an empty tuple. If iterable is specified the tuple is initialized from iterable's items.

If the argument is a tuple, the return value is the same object.

`weakref` `property` ¶

list of weak references to the object

`eq(other)` ¶

Method generated by attrs for class ConflictResolution.

Source code in sleap_io/model/matching.py

automatic strategies.
"""

from __future__ import annotations

from enum import Enum
from typing import TYPE_CHECKING, Any

import attrs
import numpy as np

`init(frame, conflict_type, original_data, new_data, resolution)` ¶

Method generated by attrs for class ConflictResolution.

Source code in sleap_io/model/matching.py

from sleap_io.model.category import Category
from sleap_io.model.identity import Identity
from sleap_io.model.instance import Instance, Track
from sleap_io.model.labeled_frame import LabeledFrame
from sleap_io.model.skeleton import Skeleton

`repr()` ¶

Method generated by attrs for class ConflictResolution.

Source code in sleap_io/model/matching.py

"""Unified matcher system for comparing and matching data structures during merging.

This module provides configurable matchers for comparing skeletons, instances, tracks,
and videos during merge operations. The matchers use various strategies to determine
when data structures should be considered equivalent during merging.

Key features:
- Skeleton matching: exact, structure-based, overlap, and subset matching
- Instance matching: spatial proximity, track identity, and bounding box IoU
- Track matching: by name or object identity
- Identity matching: by name or object identity
- Category matching: by name or object identity
- Video matching: path, basename, content, and auto matching

Video matching supports path-based, filename-based, content-based, and

`ErrorMode` ¶

Bases: builtins.str, enum.Enum

Error handling modes for merge operations.

Attributes:

Name	Type	Description
`CONTINUE`		Continue merging on errors, collecting them in the result.
`STRICT`		Raise an exception on the first error encountered.
`WARN`		Issue warnings about errors but continue merging.

Source code in sleap_io/model/matching.py

class ErrorMode(str, Enum):
    """Error handling modes for merge operations.

    Attributes:
        CONTINUE: Continue merging on errors, collecting them in the result.
        STRICT: Raise an exception on the first error encountered.
        WARN: Issue warnings about errors but continue merging.
    """

    CONTINUE = "continue"
    STRICT = "strict"
    WARN = "warn"

`CONTINUE = <ErrorMode.CONTINUE: 'continue'>` `class-attribute` ¶

Error handling modes for merge operations.

Attributes:

Name	Type	Description
`CONTINUE`		Continue merging on errors, collecting them in the result.
`STRICT`		Raise an exception on the first error encountered.
`WARN`		Issue warnings about errors but continue merging.

`STRICT = <ErrorMode.STRICT: 'strict'>` `class-attribute` ¶

Error handling modes for merge operations.

Attributes:

Name	Type	Description
`CONTINUE`		Continue merging on errors, collecting them in the result.
`STRICT`		Raise an exception on the first error encountered.
`WARN`		Issue warnings about errors but continue merging.

`WARN = <ErrorMode.WARN: 'warn'>` `class-attribute` ¶

Error handling modes for merge operations.

Attributes:

Name	Type	Description
`CONTINUE`		Continue merging on errors, collecting them in the result.
`STRICT`		Raise an exception on the first error encountered.
`WARN`		Issue warnings about errors but continue merging.

`doc = 'Error handling modes for merge operations.\n\nAttributes:\n CONTINUE: Continue merging on errors, collecting them in the result.\n STRICT: Raise an exception on the first error encountered.\n WARN: Issue warnings about errors but continue merging.\n'` `class-attribute` ¶

str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.str() (if defined) or repr(object). encoding defaults to 'utf-8'. errors defaults to 'strict'.

`module = 'sleap_io.model.matching'` `class-attribute` ¶

str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.str() (if defined) or repr(object). encoding defaults to 'utf-8'. errors defaults to 'strict'.

`FrameStrategy` ¶

Bases: builtins.str, enum.Enum

Strategies for handling frame merging.

Attributes:

Name	Type	Description
`AUTO`		Automatic merging that preserves user labels over predictions when they overlap.
`KEEP_ORIGINAL`		Always keep instances from the original (base) frame.
`KEEP_NEW`		Always keep instances from the new (incoming) frame.
`KEEP_BOTH`		Keep all instances from both frames without filtering.
`UPDATE_TRACKS`		Update track assignments only without modifying poses.
`REPLACE_PREDICTIONS`		Keep user instances from base, remove base predictions, add only predictions from incoming frame.

Source code in sleap_io/model/matching.py

class FrameStrategy(str, Enum):
    """Strategies for handling frame merging.

    Attributes:
        AUTO: Automatic merging that preserves user labels over predictions when
            they overlap.
        KEEP_ORIGINAL: Always keep instances from the original (base) frame.
        KEEP_NEW: Always keep instances from the new (incoming) frame.
        KEEP_BOTH: Keep all instances from both frames without filtering.
        UPDATE_TRACKS: Update track assignments only without modifying poses.
        REPLACE_PREDICTIONS: Keep user instances from base, remove base predictions,
            add only predictions from incoming frame.
    """

    AUTO = "auto"
    KEEP_ORIGINAL = "keep_original"
    KEEP_NEW = "keep_new"
    KEEP_BOTH = "keep_both"
    UPDATE_TRACKS = "update_tracks"
    REPLACE_PREDICTIONS = "replace_predictions"

`AUTO = <FrameStrategy.AUTO: 'auto'>` `class-attribute` ¶

Strategies for handling frame merging.

Attributes:

Name	Type	Description
`AUTO`		Automatic merging that preserves user labels over predictions when they overlap.
`KEEP_ORIGINAL`		Always keep instances from the original (base) frame.
`KEEP_NEW`		Always keep instances from the new (incoming) frame.
`KEEP_BOTH`		Keep all instances from both frames without filtering.
`UPDATE_TRACKS`		Update track assignments only without modifying poses.
`REPLACE_PREDICTIONS`		Keep user instances from base, remove base predictions, add only predictions from incoming frame.

`KEEP_BOTH = <FrameStrategy.KEEP_BOTH: 'keep_both'>` `class-attribute` ¶

Strategies for handling frame merging.

Attributes:

Name	Type	Description
`AUTO`		Automatic merging that preserves user labels over predictions when they overlap.
`KEEP_ORIGINAL`		Always keep instances from the original (base) frame.
`KEEP_NEW`		Always keep instances from the new (incoming) frame.
`KEEP_BOTH`		Keep all instances from both frames without filtering.
`UPDATE_TRACKS`		Update track assignments only without modifying poses.
`REPLACE_PREDICTIONS`		Keep user instances from base, remove base predictions, add only predictions from incoming frame.

`KEEP_NEW = <FrameStrategy.KEEP_NEW: 'keep_new'>` `class-attribute` ¶

Strategies for handling frame merging.

Attributes:

Name	Type	Description
`AUTO`		Automatic merging that preserves user labels over predictions when they overlap.
`KEEP_ORIGINAL`		Always keep instances from the original (base) frame.
`KEEP_NEW`		Always keep instances from the new (incoming) frame.
`KEEP_BOTH`		Keep all instances from both frames without filtering.
`UPDATE_TRACKS`		Update track assignments only without modifying poses.
`REPLACE_PREDICTIONS`		Keep user instances from base, remove base predictions, add only predictions from incoming frame.

`KEEP_ORIGINAL = <FrameStrategy.KEEP_ORIGINAL: 'keep_original'>` `class-attribute` ¶

Strategies for handling frame merging.

Attributes:

Name	Type	Description
`AUTO`		Automatic merging that preserves user labels over predictions when they overlap.
`KEEP_ORIGINAL`		Always keep instances from the original (base) frame.
`KEEP_NEW`		Always keep instances from the new (incoming) frame.
`KEEP_BOTH`		Keep all instances from both frames without filtering.
`UPDATE_TRACKS`		Update track assignments only without modifying poses.
`REPLACE_PREDICTIONS`		Keep user instances from base, remove base predictions, add only predictions from incoming frame.

`REPLACE_PREDICTIONS = <FrameStrategy.REPLACE_PREDICTIONS: 'replace_predictions'>` `class-attribute` ¶

Strategies for handling frame merging.

Attributes:

Name	Type	Description
`AUTO`		Automatic merging that preserves user labels over predictions when they overlap.
`KEEP_ORIGINAL`		Always keep instances from the original (base) frame.
`KEEP_NEW`		Always keep instances from the new (incoming) frame.
`KEEP_BOTH`		Keep all instances from both frames without filtering.
`UPDATE_TRACKS`		Update track assignments only without modifying poses.
`REPLACE_PREDICTIONS`		Keep user instances from base, remove base predictions, add only predictions from incoming frame.

`UPDATE_TRACKS = <FrameStrategy.UPDATE_TRACKS: 'update_tracks'>` `class-attribute` ¶

Strategies for handling frame merging.

Attributes:

Name	Type	Description
`AUTO`		Automatic merging that preserves user labels over predictions when they overlap.
`KEEP_ORIGINAL`		Always keep instances from the original (base) frame.
`KEEP_NEW`		Always keep instances from the new (incoming) frame.
`KEEP_BOTH`		Keep all instances from both frames without filtering.
`UPDATE_TRACKS`		Update track assignments only without modifying poses.
`REPLACE_PREDICTIONS`		Keep user instances from base, remove base predictions, add only predictions from incoming frame.

doc = 'Strategies for handling frame merging.\n\nAttributes:\n AUTO: Automatic merging that preserves user labels over predictions when\n they overlap.\n KEEP_ORIGINAL: Always keep instances from the original (base) frame.\n KEEP_NEW: Always keep instances from the new (incoming) frame.\n KEEP_BOTH: Keep all instances from both frames without filtering.\n UPDATE_TRACKS: Update track assignments only without modifying poses.\n REPLACE_PREDICTIONS: Keep user instances from base, remove base predictions,\n add only predictions from incoming frame.\n' `class-attribute` ¶

str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.str() (if defined) or repr(object). encoding defaults to 'utf-8'. errors defaults to 'strict'.

`module = 'sleap_io.model.matching'` `class-attribute` ¶

str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.str() (if defined) or repr(object). encoding defaults to 'utf-8'. errors defaults to 'strict'.

`Identity` ¶

Ground-truth animal identity, persistent across sessions and videos.

Unlike Track (an ephemeral temporal trajectory within a single video), Identity represents a known animal that can be recognized across videos, sessions, and experiments. In multi-view setups, multiple per-camera Tracks may map to a single Identity. The per-detection binding is stored on Instance.identity (and the analogous slot on the other detection modalities); the triangulated multi-view binding is stored on InstanceGroup.identity.

Attributes:

Name	Type	Description
`name`		Human-readable name for this identity (e.g., `"mouse_A"`). Not required to be unique, but `name` is how identities are matched across separately-loaded files and merges.
`metadata`		Arbitrary string-keyed, string-valued metadata (e.g. `{"color": "#e6194b", "strain": "C57BL/6"}`). Empty by default.

Notes

Identity objects use object-identity equality (eq=False), matching Track. Use matches() (default method="name") to compare identities across files, where Python object identity is not meaningful.

Methods:

Name	Description
`__init__`	Method generated by attrs for class Identity.
`__repr__`	Return a readable string representation.
`__setattr__`	Method generated by attrs for class Identity.
`matches`	Check if this identity matches another identity.

Source code in sleap_io/model/identity.py

@define(eq=False)
class Identity:
    """Ground-truth animal identity, persistent across sessions and videos.

    Unlike `Track` (an ephemeral temporal trajectory within a single video),
    `Identity` represents a known animal that can be recognized across videos,
    sessions, and experiments. In multi-view setups, multiple per-camera `Track`s
    may map to a single `Identity`. The per-detection binding is stored on
    ``Instance.identity`` (and the analogous slot on the other detection
    modalities); the triangulated multi-view binding is stored on
    ``InstanceGroup.identity``.

    Attributes:
        name: Human-readable name for this identity (e.g., ``"mouse_A"``). Not
            required to be unique, but ``name`` is how identities are matched
            across separately-loaded files and merges.
        metadata: Arbitrary string-keyed, string-valued metadata (e.g.
            ``{"color": "#e6194b", "strain": "C57BL/6"}``). Empty by default.

    Notes:
        `Identity` objects use object-identity equality (``eq=False``), matching
        `Track`. Use `matches()` (default ``method="name"``) to compare identities
        across files, where Python object identity is not meaningful.
    """

    name: str = field(default="", validator=instance_of(str))
    metadata: dict[str, str] = field(factory=dict, validator=instance_of(dict))

    def matches(self, other: "Identity", method: str = "name") -> bool:
        """Check if this identity matches another identity.

        Args:
            other: Another identity to compare with.
            method: Matching method:

                - ``"name"`` (default): match by the `name` attribute, which
                  survives serialization and cross-file merges.
                - ``"identity"``: match by Python object identity (same object).

        Returns:
            True if the identities match according to the specified method.

        Raises:
            ValueError: If `method` is not one of the supported values.
        """
        if method == "name":
            return self.name == other.name
        elif method == "identity":
            return self is other
        else:
            raise ValueError(f"Unknown matching method: {method}")

    def __repr__(self) -> str:
        """Return a readable string representation."""
        return f'Identity(name="{self.name}")'

`annotations = {'name': 'str', 'metadata': 'dict[str, str]'}` `class-attribute` ¶

dict() -> new empty dictionary dict(mapping) -> new dictionary initialized from a mapping object's (key, value) pairs dict(iterable) -> new dictionary initialized as if via: d = {} for k, v in iterable: d[k] = v dict(**kwargs) -> new dictionary initialized with the name=value pairs in the keyword argument list. For example: dict(one=1, two=2)

`__attrs_own_setattr__ = True` `class-attribute` ¶

Returns True when the argument is true, False otherwise. The builtins True and False are the only two instances of the class bool. The class bool is a subclass of the class int, and cannot be subclassed.

`__attrs_props__ = ClassProps(is_exception=False, is_slotted=True, has_weakref_slot=True, is_frozen=False, kw_only=<KeywordOnly.NO: 'no'>, collected_fields_by_mro=True, added_init=True, added_repr=False, added_eq=False, added_ordering=False, hashability=<Hashability.LEAVE_ALONE: 'leave_alone'>, added_match_args=True, added_str=False, added_pickling=True, on_setattr_hook=<function pipe.<locals>.wrapped_pipe at 0x7f08471ce840>, field_transformer=None)` `class-attribute` ¶

Effective class properties as derived from parameters to attr.s() or define() decorators.

This is the same data structure that attrs uses internally to decide how to construct the final class.

Warning:

This feature is currently **experimental** and is not covered by our
strict backwards-compatibility guarantees.

Attributes:

Name	Type	Description
`is_exception`	`bool`	Whether the class is treated as an exception class.
`is_slotted`	`bool`	Whether the class is `slotted <slotted classes>`.
`has_weakref_slot`	`bool`	Whether the class has a slot for weak references.
`is_frozen`	`bool`	Whether the class is frozen.
`kw_only`	`KeywordOnly`	Whether / how the class enforces keyword-only arguments on the `__init__` method.
`collected_fields_by_mro`	`bool`	Whether the class fields were collected by method resolution order. That is, correctly but unlike `dataclasses`.
`added_init`	`bool`	Whether the class has an attrs-generated `__init__` method.
`added_repr`	`bool`	Whether the class has an attrs-generated `__repr__` method.
`added_eq`	`bool`	Whether the class has attrs-generated equality methods.
`added_ordering`	`bool`	Whether the class has attrs-generated ordering methods.
`hashability`	`Hashability`	How `hashable <hashing>` the class is.
`added_match_args`	`bool`	Whether the class supports positional `match <match>` over its fields.
`added_str`	`bool`	Whether the class has an attrs-generated `__str__` method.
`added_pickling`	`bool`	Whether the class has attrs-generated `__getstate__` and `__setstate__` methods for `pickle`.
`on_setattr_hook`	`Callable[[Any, Attribute[Any], Any], Any] \| None`	The class's `__setattr__` hook.
`field_transformer`	`Callable[[Attribute[Any]], Attribute[Any]] \| None`	The class's `field transformers <transform-fields>`.

.. versionadded:: 25.4.0

doc = 'Ground-truth animal identity, persistent across sessions and videos.\n\nUnlike `Track` (an ephemeral temporal trajectory within a single video),\n`Identity` represents a known animal that can be recognized across videos,\nsessions, and experiments. In multi-view setups, multiple per-camera `Track`s\nmay map to a single `Identity`. The per-detection binding is stored on\n``Instance.identity`` (and the analogous slot on the other detection\nmodalities); the triangulated multi-view binding is stored on\n``InstanceGroup.identity``.\n\nAttributes:\n name: Human-readable name for this identity (e.g., ``"mouse_A"``). Not\n required to be unique, but ``name`` is how identities are matched\n across separately-loaded files and merges.\n metadata: Arbitrary string-keyed, string-valued metadata (e.g.\n ``{"color": "#e6194b", "strain": "C57BL/6"}``). Empty by default.\n\nNotes:\n `Identity` objects use object-identity equality (``eq=False``), matching\n `Track`. Use `matches()` (default ``method="name"``) to compare identities\n across files, where Python object identity is not meaningful.\n' `class-attribute` ¶

str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.str() (if defined) or repr(object). encoding defaults to 'utf-8'. errors defaults to 'strict'.

`firstlineno = 9` `class-attribute` ¶

int([x]) -> integer int(x, base=10) -> integer

Convert a number or string to an integer, or return 0 if no arguments are given. If x is a number, return x.int(). For floating-point numbers, this truncates towards zero.

If x is not a number or if base is given, then x must be a string, bytes, or bytearray instance representing an integer literal in the given base. The literal can be preceded by '+' or '-' and be surrounded by whitespace. The base defaults to 10. Valid bases are 0 and 2-36. Base 0 means to interpret the base from the string as an integer iteral.

`__match_args__ = ('name', 'metadata')` `class-attribute` ¶

Built-in immutable sequence.

If no argument is given, the constructor returns an empty tuple. If iterable is specified the tuple is initialized from iterable's items.

If the argument is a tuple, the return value is the same object.

`module = 'sleap_io.model.identity'` `class-attribute` ¶

str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.str() (if defined) or repr(object). encoding defaults to 'utf-8'. errors defaults to 'strict'.

`slots = ('name', 'metadata', 'weakref')` `class-attribute` ¶

Built-in immutable sequence.

If no argument is given, the constructor returns an empty tuple. If iterable is specified the tuple is initialized from iterable's items.

If the argument is a tuple, the return value is the same object.

`__static_attributes__ = ()` `class-attribute` ¶

Built-in immutable sequence.

If no argument is given, the constructor returns an empty tuple. If iterable is specified the tuple is initialized from iterable's items.

If the argument is a tuple, the return value is the same object.

`weakref` `property` ¶

list of weak references to the object

`init(name='', metadata=NOTHING)` ¶

Method generated by attrs for class Identity.

Source code in sleap_io/model/identity.py

"""Identity data structure for ground-truth animal identification."""

from __future__ import annotations

from attrs import define, field
from attrs.validators import instance_of


@define(eq=False)
class Identity:

`repr()` ¶

Return a readable string representation.

Source code in sleap_io/model/identity.py

def __repr__(self) -> str:
    """Return a readable string representation."""
    return f'Identity(name="{self.name}")'

`setattr(name, val)` ¶

Method generated by attrs for class Identity.

`matches(other, method='name')` ¶

Check if this identity matches another identity.

Parameters:

Name	Type	Description	Default
`other`	`Identity`	Another identity to compare with.	required
`method`	`str`	Matching method: `"name"` (default): match by the `name` attribute, which survives serialization and cross-file merges. `"identity"`: match by Python object identity (same object).	`'name'`

Returns:

Type	Description
`bool`	True if the identities match according to the specified method.

Raises:

Type	Description
`ValueError`	If `method` is not one of the supported values.

Source code in sleap_io/model/identity.py

def matches(self, other: "Identity", method: str = "name") -> bool:
    """Check if this identity matches another identity.

    Args:
        other: Another identity to compare with.
        method: Matching method:

            - ``"name"`` (default): match by the `name` attribute, which
              survives serialization and cross-file merges.
            - ``"identity"``: match by Python object identity (same object).

    Returns:
        True if the identities match according to the specified method.

    Raises:
        ValueError: If `method` is not one of the supported values.
    """
    if method == "name":
        return self.name == other.name
    elif method == "identity":
        return self is other
    else:
        raise ValueError(f"Unknown matching method: {method}")

`IdentityMatchMethod` ¶

Bases: builtins.str, enum.Enum

Methods for matching global identities.

Attributes:

Name	Type	Description
`NAME`		Match identities by their `name` attribute, which survives serialization and cross-file merges (default).
`IDENTITY`		Match identities by Python object identity (same object).

Source code in sleap_io/model/matching.py

class IdentityMatchMethod(str, Enum):
    """Methods for matching global identities.

    Attributes:
        NAME: Match identities by their `name` attribute, which survives
            serialization and cross-file merges (default).
        IDENTITY: Match identities by Python object identity (same object).
    """

    NAME = "name"
    IDENTITY = "identity"

`IDENTITY = <IdentityMatchMethod.IDENTITY: 'identity'>` `class-attribute` ¶

Methods for matching global identities.

Attributes:

Name	Type	Description
`NAME`		Match identities by their `name` attribute, which survives serialization and cross-file merges (default).
`IDENTITY`		Match identities by Python object identity (same object).

`NAME = <IdentityMatchMethod.NAME: 'name'>` `class-attribute` ¶

Methods for matching global identities.

Attributes:

Name	Type	Description
`NAME`		Match identities by their `name` attribute, which survives serialization and cross-file merges (default).
`IDENTITY`		Match identities by Python object identity (same object).

doc = 'Methods for matching global identities.\n\nAttributes:\n NAME: Match identities by their `name` attribute, which survives\n serialization and cross-file merges (default).\n IDENTITY: Match identities by Python object identity (same object).\n' `class-attribute` ¶

str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.str() (if defined) or repr(object). encoding defaults to 'utf-8'. errors defaults to 'strict'.

`module = 'sleap_io.model.matching'` `class-attribute` ¶

str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.str() (if defined) or repr(object). encoding defaults to 'utf-8'. errors defaults to 'strict'.

`IdentityMatcher` ¶

Matcher for comparing and matching global identities.

Attributes:

Name	Type	Description
`method`		The matching method to use. Can be an IdentityMatchMethod enum value or a string that will be converted to the enum. Default is NAME (matches by the identity `name`, which survives serialization and cross-file merges).

Methods:

Name	Description
`__eq__`	Method generated by attrs for class IdentityMatcher.
`__init__`	Method generated by attrs for class IdentityMatcher.
`__repr__`	Method generated by attrs for class IdentityMatcher.
`__setattr__`	Method generated by attrs for class IdentityMatcher.
`match`	Check if two identities match according to the configured method.

Source code in sleap_io/model/matching.py

@attrs.define
class IdentityMatcher:
    """Matcher for comparing and matching global identities.

    Attributes:
        method: The matching method to use. Can be an IdentityMatchMethod enum
            value or a string that will be converted to the enum. Default is
            NAME (matches by the identity `name`, which survives serialization
            and cross-file merges).
    """

    method: IdentityMatchMethod | str = attrs.field(
        default=IdentityMatchMethod.NAME,
        converter=lambda x: IdentityMatchMethod(x) if isinstance(x, str) else x,
    )

    def match(self, identity1: Identity, identity2: Identity) -> bool:
        """Check if two identities match according to the configured method."""
        return identity1.matches(identity2, method=self.method.value)

`annotations = {'method': 'IdentityMatchMethod | str'}` `class-attribute` ¶

dict() -> new empty dictionary dict(mapping) -> new dictionary initialized from a mapping object's (key, value) pairs dict(iterable) -> new dictionary initialized as if via: d = {} for k, v in iterable: d[k] = v dict(**kwargs) -> new dictionary initialized with the name=value pairs in the keyword argument list. For example: dict(one=1, two=2)

`__attrs_own_setattr__ = True` `class-attribute` ¶

Returns True when the argument is true, False otherwise. The builtins True and False are the only two instances of the class bool. The class bool is a subclass of the class int, and cannot be subclassed.

`__attrs_props__ = ClassProps(is_exception=False, is_slotted=True, has_weakref_slot=True, is_frozen=False, kw_only=<KeywordOnly.NO: 'no'>, collected_fields_by_mro=True, added_init=True, added_repr=True, added_eq=True, added_ordering=False, hashability=<Hashability.UNHASHABLE: 'unhashable'>, added_match_args=True, added_str=False, added_pickling=True, on_setattr_hook=<function pipe.<locals>.wrapped_pipe at 0x7f08471ce840>, field_transformer=None)` `class-attribute` ¶

Effective class properties as derived from parameters to attr.s() or define() decorators.

This is the same data structure that attrs uses internally to decide how to construct the final class.

Warning:

This feature is currently **experimental** and is not covered by our
strict backwards-compatibility guarantees.

Attributes:

Name	Type	Description
`is_exception`	`bool`	Whether the class is treated as an exception class.
`is_slotted`	`bool`	Whether the class is `slotted <slotted classes>`.
`has_weakref_slot`	`bool`	Whether the class has a slot for weak references.
`is_frozen`	`bool`	Whether the class is frozen.
`kw_only`	`KeywordOnly`	Whether / how the class enforces keyword-only arguments on the `__init__` method.
`collected_fields_by_mro`	`bool`	Whether the class fields were collected by method resolution order. That is, correctly but unlike `dataclasses`.
`added_init`	`bool`	Whether the class has an attrs-generated `__init__` method.
`added_repr`	`bool`	Whether the class has an attrs-generated `__repr__` method.
`added_eq`	`bool`	Whether the class has attrs-generated equality methods.
`added_ordering`	`bool`	Whether the class has attrs-generated ordering methods.
`hashability`	`Hashability`	How `hashable <hashing>` the class is.
`added_match_args`	`bool`	Whether the class supports positional `match <match>` over its fields.
`added_str`	`bool`	Whether the class has an attrs-generated `__str__` method.
`added_pickling`	`bool`	Whether the class has attrs-generated `__getstate__` and `__setstate__` methods for `pickle`.
`on_setattr_hook`	`Callable[[Any, Attribute[Any], Any], Any] \| None`	The class's `__setattr__` hook.
`field_transformer`	`Callable[[Attribute[Any]], Attribute[Any]] \| None`	The class's `field transformers <transform-fields>`.

.. versionadded:: 25.4.0

doc = 'Matcher for comparing and matching global identities.\n\nAttributes:\n method: The matching method to use. Can be an IdentityMatchMethod enum\n value or a string that will be converted to the enum. Default is\n NAME (matches by the identity `name`, which survives serialization\n and cross-file merges).\n' `class-attribute` ¶

str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.str() (if defined) or repr(object). encoding defaults to 'utf-8'. errors defaults to 'strict'.

`firstlineno = 904` `class-attribute` ¶

int([x]) -> integer int(x, base=10) -> integer

Convert a number or string to an integer, or return 0 if no arguments are given. If x is a number, return x.int(). For floating-point numbers, this truncates towards zero.

If x is not a number or if base is given, then x must be a string, bytes, or bytearray instance representing an integer literal in the given base. The literal can be preceded by '+' or '-' and be surrounded by whitespace. The base defaults to 10. Valid bases are 0 and 2-36. Base 0 means to interpret the base from the string as an integer iteral.

`__match_args__ = ('method',)` `class-attribute` ¶

Built-in immutable sequence.

If no argument is given, the constructor returns an empty tuple. If iterable is specified the tuple is initialized from iterable's items.

If the argument is a tuple, the return value is the same object.

`module = 'sleap_io.model.matching'` `class-attribute` ¶

str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.str() (if defined) or repr(object). encoding defaults to 'utf-8'. errors defaults to 'strict'.

`slots = ('method', 'weakref')` `class-attribute` ¶

Built-in immutable sequence.

If no argument is given, the constructor returns an empty tuple. If iterable is specified the tuple is initialized from iterable's items.

If the argument is a tuple, the return value is the same object.

`__static_attributes__ = ()` `class-attribute` ¶

Built-in immutable sequence.

If no argument is given, the constructor returns an empty tuple. If iterable is specified the tuple is initialized from iterable's items.

If the argument is a tuple, the return value is the same object.

`weakref` `property` ¶

list of weak references to the object

`eq(other)` ¶

Method generated by attrs for class IdentityMatcher.

Source code in sleap_io/model/matching.py

automatic strategies.
"""

from __future__ import annotations

from enum import Enum

`init(method=<IdentityMatchMethod.NAME: 'name'>)` ¶

Method generated by attrs for class IdentityMatcher.

Source code in sleap_io/model/matching.py

from typing import TYPE_CHECKING, Any

import attrs

`repr()` ¶

Method generated by attrs for class IdentityMatcher.

Source code in sleap_io/model/matching.py

"""Unified matcher system for comparing and matching data structures during merging.

This module provides configurable matchers for comparing skeletons, instances, tracks,
and videos during merge operations. The matchers use various strategies to determine
when data structures should be considered equivalent during merging.

Key features:
- Skeleton matching: exact, structure-based, overlap, and subset matching
- Instance matching: spatial proximity, track identity, and bounding box IoU
- Track matching: by name or object identity
- Identity matching: by name or object identity
- Category matching: by name or object identity
- Video matching: path, basename, content, and auto matching

Video matching supports path-based, filename-based, content-based, and

`setattr(name, val)` ¶

Method generated by attrs for class IdentityMatcher.

Source code in sleap_io/model/matching.py

        return match

# IMAGE MATCHING: Compare frame images (opt-in)
if self.compare_images:
    match = self._match_by_images(incoming, viable)
    if match is not None:
        return match

# No match found

`match(identity1, identity2)` ¶

Check if two identities match according to the configured method.

Source code in sleap_io/model/matching.py

def match(self, identity1: Identity, identity2: Identity) -> bool:
    """Check if two identities match according to the configured method."""
    return identity1.matches(identity2, method=self.method.value)

`Instance` ¶

This class represents a ground truth instance such as an animal.

An Instance has a set of landmarks (points) that correspond to a Skeleton. Each point is associated with a Node in the skeleton. The points are stored in a structured numpy array with columns for x, y, visible, complete and name.

The Instance may also be associated with a Track which links multiple instances together across frames or videos.

Attributes:

Name	Type	Description
`points`		A numpy structured array with columns for xy, visible and complete. The array should have shape `(n_nodes,)`. This representation is useful for performance efficiency when working with large datasets.
`skeleton`		The `Skeleton` that describes the `Node`s and `Edge`s associated with this instance.
`track`		An optional `Track` associated with a unique animal/object across frames or videos.
`tracking_score`		The score associated with the `Track` assignment. This is typically the value from the score matrix used in an identity assignment. This is `None` if the instance is not associated with a track or if the track was assigned manually.
`identity`		An optional `Identity` representing the global, ground-truth animal this instance belongs to (persistent across videos/sessions). Unlike `track` (an ephemeral, video-local tracklet), `Identity` is the cross-file re-identification key. `None` if no global identity is assigned.
`identity_score`		The score associated with the `identity` assignment (e.g. the cosine similarity to a re-ID gallery prototype). This is `None` if the instance has no identity or the identity was assigned manually. Kept separate from `tracking_score` (short-term tracklet vs long-term identity).
`from_predicted`		The `PredictedInstance` (if any) that this instance was initialized from. This is used with human-in-the-loop workflows.
`identity_embedding`		An optional `Embedding` describing this instance's appearance for re-identification (e.g. a vector produced by a re-ID model). `None` by default.
`category`		An optional `Category` representing the class this instance belongs to (e.g. `"female_fly"`, `"fur_shaved"`), typically assigned by classification or re-ID. Mirrors `identity` but groups by class rather than individual. `None` if no category is assigned.
`category_score`		The score associated with the `category` assignment (e.g. the classifier confidence). `None` if the instance has no category or the category was assigned manually.
`category_embedding`		An optional `Embedding` describing this instance's appearance for classification (the vector the `category` was classified from). `None` by default.

Methods:

Name	Description
`__attrs_post_init__`	Convert the points array after initialization.
`__getitem__`	Return the point associated with a node.
`__init__`	Method generated by attrs for class Instance.
`__len__`	Return the number of points in the instance.
`__repr__`	Return a readable representation of the instance.
`__setattr__`	Method generated by attrs for class Instance.
`__setitem__`	Set the point associated with a node.
`bounding_box`	Get the bounding box of visible points.
`empty`	Create an empty instance with no points.
`from_numpy`	Create an instance object from a numpy array.
`numpy`	Return the instance points as a `(n_nodes, 2)` numpy array.
`overlaps_with`	Check if this instance overlaps with another based on bounding box IoU.
`replace_skeleton`	Replace the skeleton associated with the instance.
`same_identity_as`	Check if this instance has the same identity as another instance.
`same_pose_as`	Check if this instance has the same pose as another instance.
`to_bbox`	Create a bounding box from this instance.
`to_centroid`	Create a `Centroid` from this instance.
`to_mask`	Rasterize this instance's ROI geometry into a segmentation mask.
`to_roi`	Create a region-of-interest geometry from this instance.
`update_skeleton`	Update or replace the skeleton associated with the instance.

Source code in sleap_io/model/instance.py

@attrs.define(auto_attribs=True, slots=True, eq=False)
class Instance:
    """This class represents a ground truth instance such as an animal.

    An `Instance` has a set of landmarks (points) that correspond to a `Skeleton`. Each
    point is associated with a `Node` in the skeleton. The points are stored in a
    structured numpy array with columns for x, y, visible, complete and name.

    The `Instance` may also be associated with a `Track` which links multiple instances
    together across frames or videos.

    Attributes:
        points: A numpy structured array with columns for xy, visible and complete. The
            array should have shape `(n_nodes,)`. This representation is useful for
            performance efficiency when working with large datasets.
        skeleton: The `Skeleton` that describes the `Node`s and `Edge`s associated with
            this instance.
        track: An optional `Track` associated with a unique animal/object across frames
            or videos.
        tracking_score: The score associated with the `Track` assignment. This is
            typically the value from the score matrix used in an identity assignment.
            This is `None` if the instance is not associated with a track or if the
            track was assigned manually.
        identity: An optional `Identity` representing the global, ground-truth animal
            this instance belongs to (persistent across videos/sessions). Unlike
            `track` (an ephemeral, video-local tracklet), `Identity` is the cross-file
            re-identification key. `None` if no global identity is assigned.
        identity_score: The score associated with the `identity` assignment (e.g. the
            cosine similarity to a re-ID gallery prototype). This is `None` if the
            instance has no identity or the identity was assigned manually. Kept
            separate from `tracking_score` (short-term tracklet vs long-term identity).
        from_predicted: The `PredictedInstance` (if any) that this instance was
            initialized from. This is used with human-in-the-loop workflows.
        identity_embedding: An optional `Embedding` describing this instance's
            appearance for re-identification (e.g. a vector produced by a re-ID
            model). ``None`` by default.
        category: An optional `Category` representing the *class* this instance
            belongs to (e.g. ``"female_fly"``, ``"fur_shaved"``), typically
            assigned by classification or re-ID. Mirrors `identity` but groups by
            class rather than individual. `None` if no category is assigned.
        category_score: The score associated with the `category` assignment (e.g.
            the classifier confidence). `None` if the instance has no category or
            the category was assigned manually.
        category_embedding: An optional `Embedding` describing this instance's
            appearance for classification (the vector the `category` was
            classified from). ``None`` by default.
    """

    points: PointsArray = attrs.field(eq=attrs.cmp_using(eq=np.array_equal))
    skeleton: Skeleton
    track: Track | None = None
    tracking_score: float | None = None
    identity: Identity | None = None
    identity_score: float | None = None
    category: Category | None = attrs.field(default=None, converter=to_category)
    category_score: float | None = None
    from_predicted: "PredictedInstance | None" = None
    identity_embedding: Embedding | None = attrs.field(default=None, repr=False)
    category_embedding: Embedding | None = attrs.field(default=None, repr=False)

    @classmethod
    def empty(
        cls,
        skeleton: Skeleton,
        track: Track | None = None,
        tracking_score: float | None = None,
        identity: Identity | None = None,
        identity_score: float | None = None,
        category: Category | None = None,
        category_score: float | None = None,
        identity_embedding: Embedding | None = None,
        category_embedding: Embedding | None = None,
        from_predicted: "PredictedInstance | None" = None,
    ) -> "Instance":
        """Create an empty instance with no points.

        Args:
            skeleton: The `Skeleton` that this `Instance` is associated with.
            track: An optional `Track` associated with a unique animal/object across
                frames or videos.
            tracking_score: The score associated with the `Track` assignment. This is
                typically the value from the score matrix used in an identity
                assignment. This is `None` if the instance is not associated with a
                track or if the track was assigned manually.
            identity: An optional global `Identity` for this instance.
            identity_score: The score associated with the `identity` assignment.
            category: An optional `Category` (class) for this instance.
            category_score: The score associated with the `category` assignment.
            identity_embedding: An optional re-ID `Embedding` for this instance.
            category_embedding: An optional classification `Embedding` for this
                instance.
            from_predicted: The `PredictedInstance` (if any) that this instance was
                initialized from. This is used with human-in-the-loop workflows.

        Returns:
            An `Instance` with an empty numpy array of shape `(n_nodes,)`.
        """
        points = PointsArray.empty(len(skeleton))
        points["name"] = skeleton.node_names

        return cls(
            points=points,
            skeleton=skeleton,
            track=track,
            tracking_score=tracking_score,
            identity=identity,
            identity_score=identity_score,
            category=category,
            category_score=category_score,
            identity_embedding=identity_embedding,
            category_embedding=category_embedding,
            from_predicted=from_predicted,
        )

    @classmethod
    def _convert_points(
        cls, points_data: np.ndarray | dict | list, skeleton: Skeleton
    ) -> PointsArray:
        """Convert points to a structured numpy array if needed."""
        if isinstance(points_data, dict):
            return PointsArray.from_dict(points_data, skeleton)
        elif isinstance(points_data, (list, np.ndarray)):
            if isinstance(points_data, list):
                points_data = np.array(points_data)

            points = PointsArray.from_array(points_data)
            points["name"] = skeleton.node_names
            return points
        else:
            raise ValueError("points must be a numpy array or dictionary.")

    @classmethod
    def from_numpy(
        cls,
        points_data: np.ndarray,
        skeleton: Skeleton,
        track: Track | None = None,
        tracking_score: float | None = None,
        identity: Identity | None = None,
        identity_score: float | None = None,
        category: Category | None = None,
        category_score: float | None = None,
        identity_embedding: Embedding | None = None,
        category_embedding: Embedding | None = None,
        from_predicted: "PredictedInstance | None" = None,
    ) -> "Instance":
        """Create an instance object from a numpy array.

        Args:
            points_data: A numpy array of shape `(n_nodes, D)` corresponding to the
                points of the skeleton. Values of `np.nan` indicate "missing" nodes and
                will be reflected in the "visible" field.

                If `D == 2`, the array should have columns for x and y.
                If `D == 3`, the array should have columns for x, y and visible.
                If `D == 4`, the array should have columns for x, y, visible and
                complete.

                If this is provided as a structured array, it will be used without copy
                if it has the correct dtype. Otherwise, a new structured array will be
                created reusing the provided data.
            skeleton: The `Skeleton` that this `Instance` is associated with. It should
                have `n_nodes` nodes.
            track: An optional `Track` associated with a unique animal/object across
                frames or videos.
            tracking_score: The score associated with the `Track` assignment. This is
                typically the value from the score matrix used in an identity
                assignment. This is `None` if the instance is not associated with a
                track or if the track was assigned manually.
            identity: An optional global `Identity` for this instance.
            identity_score: The score associated with the `identity` assignment.
            category: An optional `Category` (class) for this instance.
            category_score: The score associated with the `category` assignment.
            identity_embedding: An optional re-ID `Embedding` for this instance.
            category_embedding: An optional classification `Embedding` for this
                instance.
            from_predicted: The `PredictedInstance` (if any) that this instance was
                initialized from. This is used with human-in-the-loop workflows.

        Returns:
            An `Instance` object with the specified points.
        """
        return cls(
            points=points_data,
            skeleton=skeleton,
            track=track,
            tracking_score=tracking_score,
            identity=identity,
            identity_score=identity_score,
            category=category,
            category_score=category_score,
            identity_embedding=identity_embedding,
            category_embedding=category_embedding,
            from_predicted=from_predicted,
        )

    def __attrs_post_init__(self):
        """Convert the points array after initialization."""
        if not isinstance(self.points, PointsArray):
            self.points = self._convert_points(self.points, self.skeleton)

        # Ensure points have node names
        if "name" in self.points.dtype.names and not all(self.points["name"]):
            self.points["name"] = self.skeleton.node_names

    def numpy(
        self,
        invisible_as_nan: bool = True,
    ) -> np.ndarray:
        """Return the instance points as a `(n_nodes, 2)` numpy array.

        Args:
            invisible_as_nan: If `True` (the default), points that are not visible will
                be set to `np.nan`. If `False`, they will be whatever the stored value
                of `Instance.points["xy"]` is.

        Returns:
            A numpy array of shape `(n_nodes, 2)` corresponding to the points of the
            skeleton. Values of `np.nan` indicate "missing" nodes.

        Notes:
            This will always return a copy of the array.

            If you need to avoid making a copy, just access the `Instance.points["xy"]`
            attribute directly. This will not replace invisible points with `np.nan`.
        """
        if invisible_as_nan:
            return np.where(
                self.points["visible"].reshape(-1, 1), self.points["xy"], np.nan
            )
        else:
            return self.points["xy"].copy()

    @property
    def centroid_xy(self) -> tuple[float, float] | None:
        """Mean of visible point coordinates as ``(x, y)``, or ``None``.

        Returns:
            A tuple ``(x, y)`` representing the center of mass of all visible
            points, or ``None`` if no points are visible.
        """
        pts = self.numpy(invisible_as_nan=True)
        visible = ~np.isnan(pts[:, 0])
        if not visible.any():
            return None
        return float(pts[visible, 0].mean()), float(pts[visible, 1].mean())

    def to_centroid(
        self,
        method: str = "center_of_mass",
        node: int | str | None = None,
        fallback: str | None = None,
        error_on_empty: bool = False,
        **kwargs,
    ) -> "Centroid":
        """Create a ``Centroid`` from this instance.

        Delegates to ``Centroid.from_pose()``. A ``PredictedInstance`` yields a
        ``PredictedCentroid`` carrying its ``score``; any other instance yields a
        ``UserCentroid``. Metadata (``track``, ``tracking_score``, ``identity``,
        ``identity_score``, ``identity_embedding``, ``category``,
        ``category_score``, ``category_embedding``, ``instance=self``) is
        propagated.

        Args:
            method: Computation method (``"center_of_mass"``, ``"bbox_center"``,
                ``"geometric_median"``, or ``"anchor"``).
            node: Node specification for the ``"anchor"`` method. Can be a node
                name (str) or index (int).
            fallback: For the ``"anchor"`` method, a non-anchor method to fall
                back to when the anchor node is occluded.
            error_on_empty: If ``True``, raise ``ValueError`` when there are no
                visible points instead of returning a degenerate (NaN) centroid.
            **kwargs: Additional keyword arguments passed to the centroid
                constructor.

        Returns:
            A ``UserCentroid`` or ``PredictedCentroid`` depending on the
            instance type.

        Raises:
            ValueError: For an unknown ``method``, a missing ``node`` for the
                ``"anchor"`` method, an invalid ``node`` type, or (when
                ``error_on_empty`` is ``True``) when there are no visible points.
        """
        from sleap_io.model.centroid import Centroid

        return Centroid.from_pose(
            self,
            method=method,
            node=node,
            fallback=fallback,
            error_on_empty=error_on_empty,
            **kwargs,
        )

    def to_bbox(
        self,
        mode: str = "tight",
        size: float | tuple[float, float] | None = None,
        padding: float | tuple[float, float] = 0.0,
        node: int | str | None = None,
        center_method: str = "center_of_mass",
        rotated: bool = False,
        error_on_empty: bool = False,
    ) -> "BoundingBox":
        """Create a bounding box from this instance.

        A ``PredictedInstance`` yields a ``PredictedBoundingBox`` carrying its
        ``score``; any other instance yields a ``UserBoundingBox``. Metadata
        (``track``, ``tracking_score``, ``identity``, ``identity_score``,
        ``identity_embedding``, ``category``, ``category_score``,
        ``category_embedding``, ``instance=self``) is propagated.

        Args:
            mode: ``"tight"`` to fit the visible points, or ``"centered"`` to
                build a fixed-``size`` box centered on a computed centroid.
            size: Box size for ``mode="centered"``. A scalar yields a square box;
                a ``(w, h)`` tuple sets width and height independently. Required
                for ``mode="centered"``.
            padding: Amount to inflate the box outward. Scalar applies to both
                axes; a ``(px, py)`` tuple applies per-axis. Negative values
                shrink the box.
            node: Node specification passed to the centroid computation for
                ``mode="centered"`` with ``center_method="anchor"``.
            center_method: Centroid method used to locate the box center for
                ``mode="centered"`` (see :meth:`to_centroid`).
            rotated: For ``mode="tight"``, if ``True`` fit a minimum-area oriented
                box from the convex hull of visible points; otherwise fit an
                axis-aligned box.
            error_on_empty: If ``True``, raise ``ValueError`` when there are no
                visible points instead of returning a degenerate (NaN) box.

        Returns:
            A ``BoundingBox`` enclosing the instance (or NaN corners if empty).

        Raises:
            ValueError: For an unknown ``mode``, a missing ``size`` for
                ``mode="centered"``, or (when ``error_on_empty`` is ``True``)
                when there are no visible points.
        """
        from sleap_io.model.bbox import PredictedBoundingBox, UserBoundingBox
        from sleap_io.model.roi import (
            _apply_padding,
            _geometry_to_bbox_coords,
            _pose_to_geometry,
        )

        nan = float("nan")
        angle = 0.0

        if mode == "tight":
            pts = self.numpy(invisible_as_nan=True)
            visible = ~np.isnan(pts[:, 0])
            if not visible.any():
                if error_on_empty:
                    raise ValueError("No visible points to compute bounding box.")
                x1 = y1 = x2 = y2 = nan
            elif rotated:
                hull = _pose_to_geometry(
                    pts, self.skeleton.edge_inds, method="convex_hull"
                )
                x1, y1, x2, y2, angle = _geometry_to_bbox_coords(hull, rotated=True)
                x1, y1, x2, y2 = _apply_padding(x1, y1, x2, y2, padding)
            else:
                vis = pts[visible]
                x1 = float(vis[:, 0].min())
                y1 = float(vis[:, 1].min())
                x2 = float(vis[:, 0].max())
                y2 = float(vis[:, 1].max())
                x1, y1, x2, y2 = _apply_padding(x1, y1, x2, y2, padding)
        elif mode == "centered":
            if size is None:
                raise ValueError("'size' is required for mode='centered'.")
            centroid = self.to_centroid(
                method=center_method, node=node, error_on_empty=error_on_empty
            )
            if centroid.is_empty:
                x1 = y1 = x2 = y2 = nan
            else:
                cx, cy = centroid.xy
                if isinstance(size, (tuple, list)):
                    w, h = size
                else:
                    w = h = size
                x1 = cx - w / 2
                y1 = cy - h / 2
                x2 = cx + w / 2
                y2 = cy + h / 2
                x1, y1, x2, y2 = _apply_padding(x1, y1, x2, y2, padding)
        else:
            raise ValueError(f"Unknown mode {mode!r}. Expected 'tight' or 'centered'.")

        kwargs = dict(
            x1=x1,
            y1=y1,
            x2=x2,
            y2=y2,
            angle=angle,
            track=self.track,
            tracking_score=self.tracking_score,
            identity=self.identity,
            identity_score=self.identity_score,
            identity_embedding=self.identity_embedding,
            category=self.category,
            category_score=self.category_score,
            category_embedding=self.category_embedding,
            instance=self,
        )
        if isinstance(self, PredictedInstance):
            return PredictedBoundingBox(score=self.score, **kwargs)
        return UserBoundingBox(**kwargs)

    def to_roi(
        self,
        method: str = "shapes",
        node_radius: float = 0.0,
        edge_radius: float = 0.0,
        radius: float = 0.0,
        quad_segs: int = 8,
        error_on_empty: bool = False,
    ) -> "ROI":
        """Create a region-of-interest geometry from this instance.

        A ``PredictedInstance`` yields a ``PredictedROI`` carrying its ``score``;
        any other instance yields a ``UserROI``. Metadata (``track``,
        ``tracking_score``, ``identity``, ``identity_score``,
        ``identity_embedding``, ``category``, ``category_score``,
        ``category_embedding``, ``instance=self``) is propagated.

        Args:
            method: ``"shapes"`` to union buffered node points and/or edge
                segments, or ``"convex_hull"`` to take the convex hull of the
                visible points.
            node_radius: Buffer radius around each visible node (``"shapes"``
                only).
            edge_radius: Buffer radius around each fully-visible edge segment
                (``"shapes"`` only).
            radius: Optional buffer applied to the convex hull
                (``"convex_hull"`` only).
            quad_segs: Number of segments used to approximate a quarter circle
                when buffering.
            error_on_empty: If ``True``, raise ``ValueError`` when the resulting
                geometry is empty instead of returning an empty-geometry ROI.

        Returns:
            A ``ROI`` whose geometry encloses the instance (an empty ``Polygon``
            if there are no visible points).

        Raises:
            ValueError: If ``method="shapes"`` with both ``node_radius`` and
                ``edge_radius`` equal to 0 (a misconfiguration, always raised),
                for an unknown ``method``, or (when ``error_on_empty`` is
                ``True``) when the resulting geometry is empty.
        """
        from sleap_io.model.roi import PredictedROI, UserROI, _pose_to_geometry

        # Misconfiguration: raise before the empty-points check so that an empty
        # instance still surfaces the error.
        if method == "shapes" and node_radius == 0 and edge_radius == 0:
            raise ValueError(
                "method='shapes' requires at least one of node_radius or "
                "edge_radius to be > 0."
            )

        geom = _pose_to_geometry(
            self.numpy(invisible_as_nan=True),
            self.skeleton.edge_inds,
            method=method,
            node_radius=node_radius,
            edge_radius=edge_radius,
            radius=radius,
            quad_segs=quad_segs,
        )

        if geom.is_empty and error_on_empty:
            raise ValueError("No visible points to compute ROI geometry.")

        kwargs = dict(
            geometry=geom,
            track=self.track,
            tracking_score=self.tracking_score,
            identity=self.identity,
            identity_score=self.identity_score,
            identity_embedding=self.identity_embedding,
            category=self.category,
            category_score=self.category_score,
            category_embedding=self.category_embedding,
            instance=self,
        )
        if isinstance(self, PredictedInstance):
            return PredictedROI(score=self.score, **kwargs)
        return UserROI(**kwargs)

    def to_mask(self, height: int, width: int, **roi_kwargs) -> "SegmentationMask":
        """Rasterize this instance's ROI geometry into a segmentation mask.

        Equivalent to ``self.to_roi(**roi_kwargs).to_mask(height, width)``,
        except that a zero-area hull (``method="convex_hull"`` over fewer than
        three visible points yields a ``Point`` or ``LineString``) rasterizes to
        an all-background mask here instead of raising. A ``PredictedInstance``
        yields a ``PredictedSegmentationMask`` carrying its ``score``; any other
        instance yields a ``UserSegmentationMask``. Metadata is propagated.

        Args:
            height: Height of the output mask in pixels.
            width: Width of the output mask in pixels.
            **roi_kwargs: Keyword arguments forwarded to :meth:`to_roi` (e.g.
                ``method``, ``node_radius``, ``edge_radius``, ``radius``,
                ``quad_segs``, ``error_on_empty``).

        Returns:
            A ``SegmentationMask`` with the rasterized geometry (all background
            if the geometry is empty or has zero area).

        Raises:
            ValueError: Propagated from :meth:`to_roi` for a ``"shapes"``
                misconfiguration, an unknown method, or (when
                ``error_on_empty`` is ``True``) an empty geometry.
        """
        from shapely.geometry import MultiPolygon, Polygon

        error_on_empty = roi_kwargs.pop("error_on_empty", False)
        roi = self.to_roi(error_on_empty=error_on_empty, **roi_kwargs)

        # A non-empty but non-fillable geometry (e.g. convex_hull of <3 visible
        # points -> Point/LineString) has zero area; rasterize it as all
        # background rather than letting _rasterize_geometry raise a TypeError.
        rasterizable = isinstance(roi.geometry, (Polygon, MultiPolygon))
        if roi.geometry.is_empty or not rasterizable:
            from sleap_io.model.mask import (
                PredictedSegmentationMask,
                UserSegmentationMask,
            )

            empty = np.zeros((height, width), dtype=bool)
            kwargs = dict(
                track=self.track,
                tracking_score=self.tracking_score,
                identity=self.identity,
                identity_score=self.identity_score,
                category=self.category,
                instance=self,
            )
            if isinstance(self, PredictedInstance):
                return PredictedSegmentationMask.from_numpy(
                    empty, score=self.score, **kwargs
                )
            return UserSegmentationMask.from_numpy(empty, **kwargs)

        return roi.to_mask(height, width)

    def __getitem__(self, node: int | str | Node) -> np.ndarray:
        """Return the point associated with a node."""
        if type(node) is not int:
            node = self.skeleton.index(node)

        return self.points[node]

    def __setitem__(self, node: int | str | Node, value):
        """Set the point associated with a node.

        Args:
            node: The node to set the point for. Can be an integer index, string name,
                or Node object.
            value: A tuple or array-like of length 2 containing (x, y) coordinates.

        Notes:
            This sets the point coordinates and marks the point as visible.
        """
        if type(node) is not int:
            node = self.skeleton.index(node)

        if len(value) < 2:
            raise ValueError("Value must have at least 2 elements (x, y)")

        self.points[node]["xy"] = value[:2]
        self.points[node]["visible"] = True

    def __len__(self) -> int:
        """Return the number of points in the instance."""
        return len(self.points)

    def __repr__(self) -> str:
        """Return a readable representation of the instance."""
        pts = self.numpy().tolist()
        track = f'"{self.track.name}"' if self.track is not None else self.track

        return f"Instance(points={pts}, track={track})"

    @property
    def n_visible(self) -> int:
        """Return the number of visible points in the instance."""
        return sum(self.points["visible"])

    @property
    def is_empty(self) -> bool:
        """Return `True` if no points are visible on the instance."""
        return ~(self.points["visible"].any())

    def update_skeleton(self, names_only: bool = False):
        """Update or replace the skeleton associated with the instance.

        Args:
            names_only: If `True`, only update the node names in the points array. If
                `False`, the points array will be updated to match the new skeleton.
        """
        if names_only:
            # Update the node names.
            self.points["name"] = self.skeleton.node_names
            return

        # Find correspondences.
        new_node_inds, old_node_inds = self.skeleton.match_nodes(self.points["name"])

        # Update the points.
        new_points = PointsArray.empty(len(self.skeleton))
        new_points[new_node_inds] = self.points[old_node_inds]
        new_points["name"] = self.skeleton.node_names
        self.points = new_points

    def replace_skeleton(
        self,
        new_skeleton: Skeleton,
        node_names_map: dict[str, str] | None = None,
    ):
        """Replace the skeleton associated with the instance.

        Args:
            new_skeleton: The new `Skeleton` to associate with the instance.
            node_names_map: Dictionary mapping nodes in the old skeleton to nodes in the
                new skeleton. Keys and values should be specified as lists of strings.
                If not provided, only nodes with identical names will be mapped. Points
                associated with unmapped nodes will be removed.

        Notes:
            This method will update the `Instance.skeleton` attribute and the
            `Instance.points` attribute in place (a copy is made of the points array).

            It is recommended to use `Labels.replace_skeleton` instead of this method if
            more flexible node mapping is required.
        """
        # Update skeleton object.
        # old_skeleton = self.skeleton
        self.skeleton = new_skeleton

        # Get node names with replacements from node map if possible.
        # old_node_names = old_skeleton.node_names
        old_node_names = self.points["name"].tolist()
        if node_names_map is not None:
            old_node_names = [node_names_map.get(node, node) for node in old_node_names]

        # Find correspondences.
        new_node_inds, old_node_inds = self.skeleton.match_nodes(old_node_names)
        # old_node_inds = np.array(old_node_inds).reshape(-1, 1)
        # new_node_inds = np.array(new_node_inds).reshape(-1, 1)

        # Update the points.
        new_points = PointsArray.empty(len(self.skeleton))
        new_points[new_node_inds] = self.points[old_node_inds]
        self.points = new_points
        self.points["name"] = self.skeleton.node_names

    def same_pose_as(self, other: "Instance", tolerance: float = None) -> bool:
        """Check if this instance has the same pose as another instance.

        Args:
            other: Another instance to compare with.
            tolerance: Maximum distance (in pixels) between corresponding points
                for them to be considered the same. If None (default), uses exact
                comparison including proper NaN handling.

        Returns:
            True if the instances have the same pose within tolerance, False otherwise.

        Notes:
            Two instances are considered to have the same pose if:
            - They have the same skeleton structure
            - When tolerance is None: All coordinates match exactly (including NaN)
            - When tolerance is specified: All visible points are within tolerance
              distance and NaN patterns match exactly
        """
        # Check skeleton compatibility
        if not self.skeleton.matches(other.skeleton):
            return False

        if tolerance is None:
            # Exact comparison using numpy arrays with proper NaN handling
            return np.array_equal(self.numpy(), other.numpy(), equal_nan=True)
        else:
            # Tolerance-based comparison with proper NaN handling
            self_array = self.numpy()
            other_array = other.numpy()

            # First, check if NaN patterns match exactly
            self_nan_mask = np.isnan(self_array)
            other_nan_mask = np.isnan(other_array)
            if not np.array_equal(self_nan_mask, other_nan_mask):
                return False

            # Get mask for non-NaN values
            non_nan_mask = ~self_nan_mask

            # If all values are NaN, they're considered equal
            if not non_nan_mask.any():
                return True

            # Calculate distances only for non-NaN points
            self_pts = self_array[non_nan_mask]
            other_pts = other_array[non_nan_mask]

            # Reshape to handle the coordinate pairs properly
            self_pts = self_pts.reshape(-1, 2)
            other_pts = other_pts.reshape(-1, 2)

            distances = np.linalg.norm(self_pts - other_pts, axis=1)

            return np.all(distances <= tolerance)

    def same_identity_as(self, other: "Instance") -> bool:
        """Check if this instance has the same identity as another instance.

        Args:
            other: Another instance to compare with.

        Returns:
            True if both instances share the same identity, False otherwise.

        Notes:
            Global `Identity` takes precedence: if both instances carry an
            `Identity`, they match when their `name`s match (which survives
            serialization and cross-file merges). Otherwise this falls back to
            the ephemeral `Track`, where instances match only when they share the
            same `Track` object (by object identity, not just by name).
        """
        if self.identity is not None and other.identity is not None:
            return self.identity.matches(other.identity, method="name")
        if self.track is None or other.track is None:
            return False
        return self.track is other.track

    def overlaps_with(self, other: "Instance", iou_threshold: float = 0.5) -> bool:
        """Check if this instance overlaps with another based on bounding box IoU.

        Args:
            other: Another instance to compare with.
            iou_threshold: Minimum IoU (Intersection over Union) value to consider
                the instances as overlapping.

        Returns:
            True if the instances overlap above the threshold, False otherwise.

        Notes:
            Overlap is computed using the bounding boxes of visible points.
            If either instance has no visible points, they don't overlap.
        """
        # Get visible points for both instances
        self_visible = self.points["visible"]
        other_visible = other.points["visible"]

        if not self_visible.any() or not other_visible.any():
            return False

        # Calculate bounding boxes
        self_pts = self.points["xy"][self_visible]
        other_pts = other.points["xy"][other_visible]

        self_bbox = np.array(
            [
                [np.min(self_pts[:, 0]), np.min(self_pts[:, 1])],  # min x, y
                [np.max(self_pts[:, 0]), np.max(self_pts[:, 1])],  # max x, y
            ]
        )

        other_bbox = np.array(
            [
                [np.min(other_pts[:, 0]), np.min(other_pts[:, 1])],
                [np.max(other_pts[:, 0]), np.max(other_pts[:, 1])],
            ]
        )

        # Calculate intersection
        intersection_min = np.maximum(self_bbox[0], other_bbox[0])
        intersection_max = np.minimum(self_bbox[1], other_bbox[1])

        if np.any(intersection_min >= intersection_max):
            # No intersection
            return False

        intersection_area = np.prod(intersection_max - intersection_min)

        # Calculate union
        self_area = np.prod(self_bbox[1] - self_bbox[0])
        other_area = np.prod(other_bbox[1] - other_bbox[0])
        union_area = self_area + other_area - intersection_area

        # Calculate IoU
        iou = intersection_area / union_area if union_area > 0 else 0

        return iou >= iou_threshold

    def bounding_box(self) -> np.ndarray | None:
        """Get the bounding box of visible points.

        Returns:
            A numpy array of shape (2, 2) with [[min_x, min_y], [max_x, max_y]],
            or None if there are no visible points.
        """
        visible = self.points["visible"]
        if not visible.any():
            return None

        pts = self.points["xy"][visible]
        return np.array(
            [
                [np.min(pts[:, 0]), np.min(pts[:, 1])],
                [np.max(pts[:, 0]), np.max(pts[:, 1])],
            ]
        )

`annotations = {'points': 'PointsArray', 'skeleton': 'Skeleton', 'track': 'Track | None', 'tracking_score': 'float | None', 'identity': 'Identity | None', 'identity_score': 'float | None', 'category': 'Category | None', 'category_score': 'float | None', 'from_predicted': "'PredictedInstance | None'", 'identity_embedding': 'Embedding | None', 'category_embedding': 'Embedding | None'}` `class-attribute` ¶

dict() -> new empty dictionary dict(mapping) -> new dictionary initialized from a mapping object's (key, value) pairs dict(iterable) -> new dictionary initialized as if via: d = {} for k, v in iterable: d[k] = v dict(**kwargs) -> new dictionary initialized with the name=value pairs in the keyword argument list. For example: dict(one=1, two=2)

`__attrs_own_setattr__ = True` `class-attribute` ¶

Returns True when the argument is true, False otherwise. The builtins True and False are the only two instances of the class bool. The class bool is a subclass of the class int, and cannot be subclassed.

`__attrs_props__ = ClassProps(is_exception=False, is_slotted=True, has_weakref_slot=True, is_frozen=False, kw_only=<KeywordOnly.NO: 'no'>, collected_fields_by_mro=True, added_init=True, added_repr=False, added_eq=False, added_ordering=False, hashability=<Hashability.LEAVE_ALONE: 'leave_alone'>, added_match_args=True, added_str=False, added_pickling=True, on_setattr_hook=<function pipe.<locals>.wrapped_pipe at 0x7f08471ce840>, field_transformer=None)` `class-attribute` ¶

Effective class properties as derived from parameters to attr.s() or define() decorators.

This is the same data structure that attrs uses internally to decide how to construct the final class.

Warning:

This feature is currently **experimental** and is not covered by our
strict backwards-compatibility guarantees.

Attributes:

Name	Type	Description
`is_exception`	`bool`	Whether the class is treated as an exception class.
`is_slotted`	`bool`	Whether the class is `slotted <slotted classes>`.
`has_weakref_slot`	`bool`	Whether the class has a slot for weak references.
`is_frozen`	`bool`	Whether the class is frozen.
`kw_only`	`KeywordOnly`	Whether / how the class enforces keyword-only arguments on the `__init__` method.
`collected_fields_by_mro`	`bool`	Whether the class fields were collected by method resolution order. That is, correctly but unlike `dataclasses`.
`added_init`	`bool`	Whether the class has an attrs-generated `__init__` method.
`added_repr`	`bool`	Whether the class has an attrs-generated `__repr__` method.
`added_eq`	`bool`	Whether the class has attrs-generated equality methods.
`added_ordering`	`bool`	Whether the class has attrs-generated ordering methods.
`hashability`	`Hashability`	How `hashable <hashing>` the class is.
`added_match_args`	`bool`	Whether the class supports positional `match <match>` over its fields.
`added_str`	`bool`	Whether the class has an attrs-generated `__str__` method.
`added_pickling`	`bool`	Whether the class has attrs-generated `__getstate__` and `__setstate__` methods for `pickle`.
`on_setattr_hook`	`Callable[[Any, Attribute[Any], Any], Any] \| None`	The class's `__setattr__` hook.
`field_transformer`	`Callable[[Attribute[Any]], Attribute[Any]] \| None`	The class's `field transformers <transform-fields>`.

.. versionadded:: 25.4.0

doc = 'This class represents a ground truth instance such as an animal.\n\nAn `Instance` has a set of landmarks (points) that correspond to a `Skeleton`. Each\npoint is associated with a `Node` in the skeleton. The points are stored in a\nstructured numpy array with columns for x, y, visible, complete and name.\n\nThe `Instance` may also be associated with a `Track` which links multiple instances\ntogether across frames or videos.\n\nAttributes:\n points: A numpy structured array with columns for xy, visible and complete. The\n array should have shape `(n_nodes,)`. This representation is useful for\n performance efficiency when working with large datasets.\n skeleton: The `Skeleton` that describes the `Node`s and `Edge`s associated with\n this instance.\n track: An optional `Track` associated with a unique animal/object across frames\n or videos.\n tracking_score: The score associated with the `Track` assignment. This is\n typically the value from the score matrix used in an identity assignment.\n This is `None` if the instance is not associated with a track or if the\n track was assigned manually.\n identity: An optional `Identity` representing the global, ground-truth animal\n this instance belongs to (persistent across videos/sessions). Unlike\n `track` (an ephemeral, video-local tracklet), `Identity` is the cross-file\n re-identification key. `None` if no global identity is assigned.\n identity_score: The score associated with the `identity` assignment (e.g. the\n cosine similarity to a re-ID gallery prototype). This is `None` if the\n instance has no identity or the identity was assigned manually. Kept\n separate from `tracking_score` (short-term tracklet vs long-term identity).\n from_predicted: The `PredictedInstance` (if any) that this instance was\n initialized from. This is used with human-in-the-loop workflows.\n identity_embedding: An optional `Embedding` describing this instance\'s\n appearance for re-identification (e.g. a vector produced by a re-ID\n model). ``None`` by default.\n category: An optional `Category` representing the class this instance\n belongs to (e.g. ``"female_fly"``, ``"fur_shaved"``), typically\n assigned by classification or re-ID. Mirrors `identity` but groups by\n class rather than individual. `None` if no category is assigned.\n category_score: The score associated with the `category` assignment (e.g.\n the classifier confidence). `None` if the instance has no category or\n the category was assigned manually.\n category_embedding: An optional `Embedding` describing this instance\'s\n appearance for classification (the vector the `category` was\n classified from). ``None`` by default.\n' `class-attribute` ¶

str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.str() (if defined) or repr(object). encoding defaults to 'utf-8'. errors defaults to 'strict'.

`firstlineno = 397` `class-attribute` ¶

int([x]) -> integer int(x, base=10) -> integer

Convert a number or string to an integer, or return 0 if no arguments are given. If x is a number, return x.int(). For floating-point numbers, this truncates towards zero.

If x is not a number or if base is given, then x must be a string, bytes, or bytearray instance representing an integer literal in the given base. The literal can be preceded by '+' or '-' and be surrounded by whitespace. The base defaults to 10. Valid bases are 0 and 2-36. Base 0 means to interpret the base from the string as an integer iteral.

`__match_args__ = ('points', 'skeleton', 'track', 'tracking_score', 'identity', 'identity_score', 'category', 'category_score', 'from_predicted', 'identity_embedding', 'category_embedding')` `class-attribute` ¶

Built-in immutable sequence.

If no argument is given, the constructor returns an empty tuple. If iterable is specified the tuple is initialized from iterable's items.

If the argument is a tuple, the return value is the same object.

`module = 'sleap_io.model.instance'` `class-attribute` ¶

str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.str() (if defined) or repr(object). encoding defaults to 'utf-8'. errors defaults to 'strict'.

`slots = ('points', 'skeleton', 'track', 'tracking_score', 'identity', 'identity_score', 'category', 'category_score', 'from_predicted', 'identity_embedding', 'category_embedding', 'weakref')` `class-attribute` ¶

Built-in immutable sequence.

If no argument is given, the constructor returns an empty tuple. If iterable is specified the tuple is initialized from iterable's items.

If the argument is a tuple, the return value is the same object.

`__static_attributes__ = ('points', 'skeleton')` `class-attribute` ¶

Built-in immutable sequence.

If no argument is given, the constructor returns an empty tuple. If iterable is specified the tuple is initialized from iterable's items.

If the argument is a tuple, the return value is the same object.

`weakref` `property` ¶

list of weak references to the object

`centroid_xy` `property` ¶

Mean of visible point coordinates as (x, y), or None.

Returns:

Type	Description
	A tuple `(x, y)` representing the center of mass of all visible points, or `None` if no points are visible.

`is_empty` `property` ¶

Return True if no points are visible on the instance.

`n_visible` `property` ¶

Return the number of visible points in the instance.

`__attrs_post_init__()` ¶

Convert the points array after initialization.

Source code in sleap_io/model/instance.py

def __attrs_post_init__(self):
    """Convert the points array after initialization."""
    if not isinstance(self.points, PointsArray):
        self.points = self._convert_points(self.points, self.skeleton)

    # Ensure points have node names
    if "name" in self.points.dtype.names and not all(self.points["name"]):
        self.points["name"] = self.skeleton.node_names

`getitem(node)` ¶

Return the point associated with a node.

Source code in sleap_io/model/instance.py

def __getitem__(self, node: int | str | Node) -> np.ndarray:
    """Return the point associated with a node."""
    if type(node) is not int:
        node = self.skeleton.index(node)

    return self.points[node]

`init(points, skeleton, track=None, tracking_score=None, identity=None, identity_score=None, category=None, category_score=None, from_predicted=None, identity_embedding=None, category_embedding=None)` ¶

Method generated by attrs for class Instance.

Source code in sleap_io/model/instance.py

"""Data structures for data associated with a single instance such as an animal.

The `Instance` class is a SLEAP data structure that contains a collection of points that
correspond to landmarks within a `Skeleton`.

`PredictedInstance` additionally contains metadata associated with how the instance was
estimated, such as confidence scores.
"""

from __future__ import annotations

from typing import TYPE_CHECKING

import attrs

`len()` ¶

Return the number of points in the instance.

Source code in sleap_io/model/instance.py

def __len__(self) -> int:
    """Return the number of points in the instance."""
    return len(self.points)

`repr()` ¶

Return a readable representation of the instance.

Source code in sleap_io/model/instance.py

def __repr__(self) -> str:
    """Return a readable representation of the instance."""
    pts = self.numpy().tolist()
    track = f'"{self.track.name}"' if self.track is not None else self.track

    return f"Instance(points={pts}, track={track})"

`setattr(name, val)` ¶

Method generated by attrs for class Instance.

Source code in sleap_io/model/instance.py

if np.any(intersection_min >= intersection_max):
    # No intersection
    return False

intersection_area = np.prod(intersection_max - intersection_min)

# Calculate union
self_area = np.prod(self_bbox[1] - self_bbox[0])
other_area = np.prod(other_bbox[1] - other_bbox[0])

`setitem(node, value)` ¶

Set the point associated with a node.

Parameters:

Name	Type	Description	Default
`node`	`int \| str \| Node`	The node to set the point for. Can be an integer index, string name, or Node object.	required
`value`		A tuple or array-like of length 2 containing (x, y) coordinates.	required

Notes

This sets the point coordinates and marks the point as visible.

Source code in sleap_io/model/instance.py

def __setitem__(self, node: int | str | Node, value):
    """Set the point associated with a node.

    Args:
        node: The node to set the point for. Can be an integer index, string name,
            or Node object.
        value: A tuple or array-like of length 2 containing (x, y) coordinates.

    Notes:
        This sets the point coordinates and marks the point as visible.
    """
    if type(node) is not int:
        node = self.skeleton.index(node)

    if len(value) < 2:
        raise ValueError("Value must have at least 2 elements (x, y)")

    self.points[node]["xy"] = value[:2]
    self.points[node]["visible"] = True

`bounding_box()` ¶

Get the bounding box of visible points.

Returns:

Type	Description
`ndarray \| None`	A numpy array of shape (2, 2) with [[min_x, min_y], [max_x, max_y]], or None if there are no visible points.

Source code in sleap_io/model/instance.py

def bounding_box(self) -> np.ndarray | None:
    """Get the bounding box of visible points.

    Returns:
        A numpy array of shape (2, 2) with [[min_x, min_y], [max_x, max_y]],
        or None if there are no visible points.
    """
    visible = self.points["visible"]
    if not visible.any():
        return None

    pts = self.points["xy"][visible]
    return np.array(
        [
            [np.min(pts[:, 0]), np.min(pts[:, 1])],
            [np.max(pts[:, 0]), np.max(pts[:, 1])],
        ]
    )

`empty(skeleton, track=None, tracking_score=None, identity=None, identity_score=None, category=None, category_score=None, identity_embedding=None, category_embedding=None, from_predicted=None)` `classmethod` ¶

Create an empty instance with no points.

Parameters:

Name	Type	Description	Default
`skeleton`	`Skeleton`	The `Skeleton` that this `Instance` is associated with.	required
`track`	`Track \| None`	An optional `Track` associated with a unique animal/object across frames or videos.	`None`
`tracking_score`	`float \| None`	The score associated with the `Track` assignment. This is typically the value from the score matrix used in an identity assignment. This is `None` if the instance is not associated with a track or if the track was assigned manually.	`None`
`identity`	`Identity \| None`	An optional global `Identity` for this instance.	`None`
`identity_score`	`float \| None`	The score associated with the `identity` assignment.	`None`
`category`	`Category \| None`	An optional `Category` (class) for this instance.	`None`
`category_score`	`float \| None`	The score associated with the `category` assignment.	`None`
`identity_embedding`	`Embedding \| None`	An optional re-ID `Embedding` for this instance.	`None`
`category_embedding`	`Embedding \| None`	An optional classification `Embedding` for this instance.	`None`
`from_predicted`	`PredictedInstance \| None`	The `PredictedInstance` (if any) that this instance was initialized from. This is used with human-in-the-loop workflows.	`None`

Returns:

Type	Description
`Instance`	An `Instance` with an empty numpy array of shape `(n_nodes,)`.

Source code in sleap_io/model/instance.py

@classmethod
def empty(
    cls,
    skeleton: Skeleton,
    track: Track | None = None,
    tracking_score: float | None = None,
    identity: Identity | None = None,
    identity_score: float | None = None,
    category: Category | None = None,
    category_score: float | None = None,
    identity_embedding: Embedding | None = None,
    category_embedding: Embedding | None = None,
    from_predicted: "PredictedInstance | None" = None,
) -> "Instance":
    """Create an empty instance with no points.

    Args:
        skeleton: The `Skeleton` that this `Instance` is associated with.
        track: An optional `Track` associated with a unique animal/object across
            frames or videos.
        tracking_score: The score associated with the `Track` assignment. This is
            typically the value from the score matrix used in an identity
            assignment. This is `None` if the instance is not associated with a
            track or if the track was assigned manually.
        identity: An optional global `Identity` for this instance.
        identity_score: The score associated with the `identity` assignment.
        category: An optional `Category` (class) for this instance.
        category_score: The score associated with the `category` assignment.
        identity_embedding: An optional re-ID `Embedding` for this instance.
        category_embedding: An optional classification `Embedding` for this
            instance.
        from_predicted: The `PredictedInstance` (if any) that this instance was
            initialized from. This is used with human-in-the-loop workflows.

    Returns:
        An `Instance` with an empty numpy array of shape `(n_nodes,)`.
    """
    points = PointsArray.empty(len(skeleton))
    points["name"] = skeleton.node_names

    return cls(
        points=points,
        skeleton=skeleton,
        track=track,
        tracking_score=tracking_score,
        identity=identity,
        identity_score=identity_score,
        category=category,
        category_score=category_score,
        identity_embedding=identity_embedding,
        category_embedding=category_embedding,
        from_predicted=from_predicted,
    )

`from_numpy(points_data, skeleton, track=None, tracking_score=None, identity=None, identity_score=None, category=None, category_score=None, identity_embedding=None, category_embedding=None, from_predicted=None)` `classmethod` ¶

Create an instance object from a numpy array.

Parameters:

Name	Type	Description	Default
`points_data`	`ndarray`	A numpy array of shape `(n_nodes, D)` corresponding to the points of the skeleton. Values of `np.nan` indicate "missing" nodes and will be reflected in the "visible" field. If `D == 2`, the array should have columns for x and y. If `D == 3`, the array should have columns for x, y and visible. If `D == 4`, the array should have columns for x, y, visible and complete. If this is provided as a structured array, it will be used without copy if it has the correct dtype. Otherwise, a new structured array will be created reusing the provided data.	required
`skeleton`	`Skeleton`	The `Skeleton` that this `Instance` is associated with. It should have `n_nodes` nodes.	required
`track`	`Track \| None`	An optional `Track` associated with a unique animal/object across frames or videos.	`None`
`tracking_score`	`float \| None`	The score associated with the `Track` assignment. This is typically the value from the score matrix used in an identity assignment. This is `None` if the instance is not associated with a track or if the track was assigned manually.	`None`
`identity`	`Identity \| None`	An optional global `Identity` for this instance.	`None`
`identity_score`	`float \| None`	The score associated with the `identity` assignment.	`None`
`category`	`Category \| None`	An optional `Category` (class) for this instance.	`None`
`category_score`	`float \| None`	The score associated with the `category` assignment.	`None`
`identity_embedding`	`Embedding \| None`	An optional re-ID `Embedding` for this instance.	`None`
`category_embedding`	`Embedding \| None`	An optional classification `Embedding` for this instance.	`None`
`from_predicted`	`PredictedInstance \| None`	The `PredictedInstance` (if any) that this instance was initialized from. This is used with human-in-the-loop workflows.	`None`

Returns:

Type	Description
`Instance`	An `Instance` object with the specified points.

Source code in sleap_io/model/instance.py

@classmethod
def from_numpy(
    cls,
    points_data: np.ndarray,
    skeleton: Skeleton,
    track: Track | None = None,
    tracking_score: float | None = None,
    identity: Identity | None = None,
    identity_score: float | None = None,
    category: Category | None = None,
    category_score: float | None = None,
    identity_embedding: Embedding | None = None,
    category_embedding: Embedding | None = None,
    from_predicted: "PredictedInstance | None" = None,
) -> "Instance":
    """Create an instance object from a numpy array.

    Args:
        points_data: A numpy array of shape `(n_nodes, D)` corresponding to the
            points of the skeleton. Values of `np.nan` indicate "missing" nodes and
            will be reflected in the "visible" field.

            If `D == 2`, the array should have columns for x and y.
            If `D == 3`, the array should have columns for x, y and visible.
            If `D == 4`, the array should have columns for x, y, visible and
            complete.

            If this is provided as a structured array, it will be used without copy
            if it has the correct dtype. Otherwise, a new structured array will be
            created reusing the provided data.
        skeleton: The `Skeleton` that this `Instance` is associated with. It should
            have `n_nodes` nodes.
        track: An optional `Track` associated with a unique animal/object across
            frames or videos.
        tracking_score: The score associated with the `Track` assignment. This is
            typically the value from the score matrix used in an identity
            assignment. This is `None` if the instance is not associated with a
            track or if the track was assigned manually.
        identity: An optional global `Identity` for this instance.
        identity_score: The score associated with the `identity` assignment.
        category: An optional `Category` (class) for this instance.
        category_score: The score associated with the `category` assignment.
        identity_embedding: An optional re-ID `Embedding` for this instance.
        category_embedding: An optional classification `Embedding` for this
            instance.
        from_predicted: The `PredictedInstance` (if any) that this instance was
            initialized from. This is used with human-in-the-loop workflows.

    Returns:
        An `Instance` object with the specified points.
    """
    return cls(
        points=points_data,
        skeleton=skeleton,
        track=track,
        tracking_score=tracking_score,
        identity=identity,
        identity_score=identity_score,
        category=category,
        category_score=category_score,
        identity_embedding=identity_embedding,
        category_embedding=category_embedding,
        from_predicted=from_predicted,
    )

`numpy(invisible_as_nan=True)` ¶

Return the instance points as a (n_nodes, 2) numpy array.

Parameters:

Name	Type	Description	Default
`invisible_as_nan`	`bool`	If `True` (the default), points that are not visible will be set to `np.nan`. If `False`, they will be whatever the stored value of `Instance.points["xy"]` is.	`True`

Returns:

Type	Description
`ndarray`	A numpy array of shape `(n_nodes, 2)` corresponding to the points of the skeleton. Values of `np.nan` indicate "missing" nodes.

Notes

This will always return a copy of the array.

If you need to avoid making a copy, just access the Instance.points["xy"] attribute directly. This will not replace invisible points with np.nan.

Source code in sleap_io/model/instance.py

def numpy(
    self,
    invisible_as_nan: bool = True,
) -> np.ndarray:
    """Return the instance points as a `(n_nodes, 2)` numpy array.

    Args:
        invisible_as_nan: If `True` (the default), points that are not visible will
            be set to `np.nan`. If `False`, they will be whatever the stored value
            of `Instance.points["xy"]` is.

    Returns:
        A numpy array of shape `(n_nodes, 2)` corresponding to the points of the
        skeleton. Values of `np.nan` indicate "missing" nodes.

    Notes:
        This will always return a copy of the array.

        If you need to avoid making a copy, just access the `Instance.points["xy"]`
        attribute directly. This will not replace invisible points with `np.nan`.
    """
    if invisible_as_nan:
        return np.where(
            self.points["visible"].reshape(-1, 1), self.points["xy"], np.nan
        )
    else:
        return self.points["xy"].copy()

`overlaps_with(other, iou_threshold=0.5)` ¶

Check if this instance overlaps with another based on bounding box IoU.

Parameters:

Name	Type	Description	Default
`other`	`Instance`	Another instance to compare with.	required
`iou_threshold`	`float`	Minimum IoU (Intersection over Union) value to consider the instances as overlapping.	`0.5`

Returns:

Type	Description
`bool`	True if the instances overlap above the threshold, False otherwise.

Notes

Overlap is computed using the bounding boxes of visible points. If either instance has no visible points, they don't overlap.

Source code in sleap_io/model/instance.py

def overlaps_with(self, other: "Instance", iou_threshold: float = 0.5) -> bool:
    """Check if this instance overlaps with another based on bounding box IoU.

    Args:
        other: Another instance to compare with.
        iou_threshold: Minimum IoU (Intersection over Union) value to consider
            the instances as overlapping.

    Returns:
        True if the instances overlap above the threshold, False otherwise.

    Notes:
        Overlap is computed using the bounding boxes of visible points.
        If either instance has no visible points, they don't overlap.
    """
    # Get visible points for both instances
    self_visible = self.points["visible"]
    other_visible = other.points["visible"]

    if not self_visible.any() or not other_visible.any():
        return False

    # Calculate bounding boxes
    self_pts = self.points["xy"][self_visible]
    other_pts = other.points["xy"][other_visible]

    self_bbox = np.array(
        [
            [np.min(self_pts[:, 0]), np.min(self_pts[:, 1])],  # min x, y
            [np.max(self_pts[:, 0]), np.max(self_pts[:, 1])],  # max x, y
        ]
    )

    other_bbox = np.array(
        [
            [np.min(other_pts[:, 0]), np.min(other_pts[:, 1])],
            [np.max(other_pts[:, 0]), np.max(other_pts[:, 1])],
        ]
    )

    # Calculate intersection
    intersection_min = np.maximum(self_bbox[0], other_bbox[0])
    intersection_max = np.minimum(self_bbox[1], other_bbox[1])

    if np.any(intersection_min >= intersection_max):
        # No intersection
        return False

    intersection_area = np.prod(intersection_max - intersection_min)

    # Calculate union
    self_area = np.prod(self_bbox[1] - self_bbox[0])
    other_area = np.prod(other_bbox[1] - other_bbox[0])
    union_area = self_area + other_area - intersection_area

    # Calculate IoU
    iou = intersection_area / union_area if union_area > 0 else 0

    return iou >= iou_threshold

`replace_skeleton(new_skeleton, node_names_map=None)` ¶

Replace the skeleton associated with the instance.

Parameters:

Name	Type	Description	Default
`new_skeleton`	`Skeleton`	The new `Skeleton` to associate with the instance.	required
`node_names_map`	`dict[str, str] \| None`	Dictionary mapping nodes in the old skeleton to nodes in the new skeleton. Keys and values should be specified as lists of strings. If not provided, only nodes with identical names will be mapped. Points associated with unmapped nodes will be removed.	`None`

Notes

This method will update the Instance.skeleton attribute and the Instance.points attribute in place (a copy is made of the points array).

It is recommended to use Labels.replace_skeleton instead of this method if more flexible node mapping is required.

Source code in sleap_io/model/instance.py

def replace_skeleton(
    self,
    new_skeleton: Skeleton,
    node_names_map: dict[str, str] | None = None,
):
    """Replace the skeleton associated with the instance.

    Args:
        new_skeleton: The new `Skeleton` to associate with the instance.
        node_names_map: Dictionary mapping nodes in the old skeleton to nodes in the
            new skeleton. Keys and values should be specified as lists of strings.
            If not provided, only nodes with identical names will be mapped. Points
            associated with unmapped nodes will be removed.

    Notes:
        This method will update the `Instance.skeleton` attribute and the
        `Instance.points` attribute in place (a copy is made of the points array).

        It is recommended to use `Labels.replace_skeleton` instead of this method if
        more flexible node mapping is required.
    """
    # Update skeleton object.
    # old_skeleton = self.skeleton
    self.skeleton = new_skeleton

    # Get node names with replacements from node map if possible.
    # old_node_names = old_skeleton.node_names
    old_node_names = self.points["name"].tolist()
    if node_names_map is not None:
        old_node_names = [node_names_map.get(node, node) for node in old_node_names]

    # Find correspondences.
    new_node_inds, old_node_inds = self.skeleton.match_nodes(old_node_names)
    # old_node_inds = np.array(old_node_inds).reshape(-1, 1)
    # new_node_inds = np.array(new_node_inds).reshape(-1, 1)

    # Update the points.
    new_points = PointsArray.empty(len(self.skeleton))
    new_points[new_node_inds] = self.points[old_node_inds]
    self.points = new_points
    self.points["name"] = self.skeleton.node_names

`same_identity_as(other)` ¶

Check if this instance has the same identity as another instance.

Parameters:

Name	Type	Description	Default
`other`	`Instance`	Another instance to compare with.	required

Returns:

Type	Description
`bool`	True if both instances share the same identity, False otherwise.

Notes

Global Identity takes precedence: if both instances carry an Identity, they match when their names match (which survives serialization and cross-file merges). Otherwise this falls back to the ephemeral Track, where instances match only when they share the same Track object (by object identity, not just by name).

Source code in sleap_io/model/instance.py

def same_identity_as(self, other: "Instance") -> bool:
    """Check if this instance has the same identity as another instance.

    Args:
        other: Another instance to compare with.

    Returns:
        True if both instances share the same identity, False otherwise.

    Notes:
        Global `Identity` takes precedence: if both instances carry an
        `Identity`, they match when their `name`s match (which survives
        serialization and cross-file merges). Otherwise this falls back to
        the ephemeral `Track`, where instances match only when they share the
        same `Track` object (by object identity, not just by name).
    """
    if self.identity is not None and other.identity is not None:
        return self.identity.matches(other.identity, method="name")
    if self.track is None or other.track is None:
        return False
    return self.track is other.track

`same_pose_as(other, tolerance=None)` ¶

Check if this instance has the same pose as another instance.

Parameters:

Name	Type	Description	Default
`other`	`Instance`	Another instance to compare with.	required
`tolerance`	`float`	Maximum distance (in pixels) between corresponding points for them to be considered the same. If None (default), uses exact comparison including proper NaN handling.	`None`

Returns:

Type	Description
`bool`	True if the instances have the same pose within tolerance, False otherwise.

Notes

Two instances are considered to have the same pose if: - They have the same skeleton structure - When tolerance is None: All coordinates match exactly (including NaN) - When tolerance is specified: All visible points are within tolerance distance and NaN patterns match exactly

Source code in sleap_io/model/instance.py

def same_pose_as(self, other: "Instance", tolerance: float = None) -> bool:
    """Check if this instance has the same pose as another instance.

    Args:
        other: Another instance to compare with.
        tolerance: Maximum distance (in pixels) between corresponding points
            for them to be considered the same. If None (default), uses exact
            comparison including proper NaN handling.

    Returns:
        True if the instances have the same pose within tolerance, False otherwise.

    Notes:
        Two instances are considered to have the same pose if:
        - They have the same skeleton structure
        - When tolerance is None: All coordinates match exactly (including NaN)
        - When tolerance is specified: All visible points are within tolerance
          distance and NaN patterns match exactly
    """
    # Check skeleton compatibility
    if not self.skeleton.matches(other.skeleton):
        return False

    if tolerance is None:
        # Exact comparison using numpy arrays with proper NaN handling
        return np.array_equal(self.numpy(), other.numpy(), equal_nan=True)
    else:
        # Tolerance-based comparison with proper NaN handling
        self_array = self.numpy()
        other_array = other.numpy()

        # First, check if NaN patterns match exactly
        self_nan_mask = np.isnan(self_array)
        other_nan_mask = np.isnan(other_array)
        if not np.array_equal(self_nan_mask, other_nan_mask):
            return False

        # Get mask for non-NaN values
        non_nan_mask = ~self_nan_mask

        # If all values are NaN, they're considered equal
        if not non_nan_mask.any():
            return True

        # Calculate distances only for non-NaN points
        self_pts = self_array[non_nan_mask]
        other_pts = other_array[non_nan_mask]

        # Reshape to handle the coordinate pairs properly
        self_pts = self_pts.reshape(-1, 2)
        other_pts = other_pts.reshape(-1, 2)

        distances = np.linalg.norm(self_pts - other_pts, axis=1)

        return np.all(distances <= tolerance)

`to_bbox(mode='tight', size=None, padding=0.0, node=None, center_method='center_of_mass', rotated=False, error_on_empty=False)` ¶

Create a bounding box from this instance.

A PredictedInstance yields a PredictedBoundingBox carrying its score; any other instance yields a UserBoundingBox. Metadata (track, tracking_score, identity, identity_score, identity_embedding, category, category_score, category_embedding, instance=self) is propagated.

Parameters:

Name	Type	Description	Default
`mode`	`str`	`"tight"` to fit the visible points, or `"centered"` to build a fixed-`size` box centered on a computed centroid.	`'tight'`
`size`	`float \| tuple[float, float] \| None`	Box size for `mode="centered"`. A scalar yields a square box; a `(w, h)` tuple sets width and height independently. Required for `mode="centered"`.	`None`
`padding`	`float \| tuple[float, float]`	Amount to inflate the box outward. Scalar applies to both axes; a `(px, py)` tuple applies per-axis. Negative values shrink the box.	`0.0`
`node`	`int \| str \| None`	Node specification passed to the centroid computation for `mode="centered"` with `center_method="anchor"`.	`None`
`center_method`	`str`	Centroid method used to locate the box center for `mode="centered"` (see :meth:`to_centroid`).	`'center_of_mass'`
`rotated`	`bool`	For `mode="tight"`, if `True` fit a minimum-area oriented box from the convex hull of visible points; otherwise fit an axis-aligned box.	`False`
`error_on_empty`	`bool`	If `True`, raise `ValueError` when there are no visible points instead of returning a degenerate (NaN) box.	`False`

Returns:

Type	Description
`BoundingBox`	A `BoundingBox` enclosing the instance (or NaN corners if empty).

Raises:

Type	Description
`ValueError`	For an unknown `mode`, a missing `size` for `mode="centered"`, or (when `error_on_empty` is `True`) when there are no visible points.

Source code in sleap_io/model/instance.py

def to_bbox(
    self,
    mode: str = "tight",
    size: float | tuple[float, float] | None = None,
    padding: float | tuple[float, float] = 0.0,
    node: int | str | None = None,
    center_method: str = "center_of_mass",
    rotated: bool = False,
    error_on_empty: bool = False,
) -> "BoundingBox":
    """Create a bounding box from this instance.

    A ``PredictedInstance`` yields a ``PredictedBoundingBox`` carrying its
    ``score``; any other instance yields a ``UserBoundingBox``. Metadata
    (``track``, ``tracking_score``, ``identity``, ``identity_score``,
    ``identity_embedding``, ``category``, ``category_score``,
    ``category_embedding``, ``instance=self``) is propagated.

    Args:
        mode: ``"tight"`` to fit the visible points, or ``"centered"`` to
            build a fixed-``size`` box centered on a computed centroid.
        size: Box size for ``mode="centered"``. A scalar yields a square box;
            a ``(w, h)`` tuple sets width and height independently. Required
            for ``mode="centered"``.
        padding: Amount to inflate the box outward. Scalar applies to both
            axes; a ``(px, py)`` tuple applies per-axis. Negative values
            shrink the box.
        node: Node specification passed to the centroid computation for
            ``mode="centered"`` with ``center_method="anchor"``.
        center_method: Centroid method used to locate the box center for
            ``mode="centered"`` (see :meth:`to_centroid`).
        rotated: For ``mode="tight"``, if ``True`` fit a minimum-area oriented
            box from the convex hull of visible points; otherwise fit an
            axis-aligned box.
        error_on_empty: If ``True``, raise ``ValueError`` when there are no
            visible points instead of returning a degenerate (NaN) box.

    Returns:
        A ``BoundingBox`` enclosing the instance (or NaN corners if empty).

    Raises:
        ValueError: For an unknown ``mode``, a missing ``size`` for
            ``mode="centered"``, or (when ``error_on_empty`` is ``True``)
            when there are no visible points.
    """
    from sleap_io.model.bbox import PredictedBoundingBox, UserBoundingBox
    from sleap_io.model.roi import (
        _apply_padding,
        _geometry_to_bbox_coords,
        _pose_to_geometry,
    )

    nan = float("nan")
    angle = 0.0

    if mode == "tight":
        pts = self.numpy(invisible_as_nan=True)
        visible = ~np.isnan(pts[:, 0])
        if not visible.any():
            if error_on_empty:
                raise ValueError("No visible points to compute bounding box.")
            x1 = y1 = x2 = y2 = nan
        elif rotated:
            hull = _pose_to_geometry(
                pts, self.skeleton.edge_inds, method="convex_hull"
            )
            x1, y1, x2, y2, angle = _geometry_to_bbox_coords(hull, rotated=True)
            x1, y1, x2, y2 = _apply_padding(x1, y1, x2, y2, padding)
        else:
            vis = pts[visible]
            x1 = float(vis[:, 0].min())
            y1 = float(vis[:, 1].min())
            x2 = float(vis[:, 0].max())
            y2 = float(vis[:, 1].max())
            x1, y1, x2, y2 = _apply_padding(x1, y1, x2, y2, padding)
    elif mode == "centered":
        if size is None:
            raise ValueError("'size' is required for mode='centered'.")
        centroid = self.to_centroid(
            method=center_method, node=node, error_on_empty=error_on_empty
        )
        if centroid.is_empty:
            x1 = y1 = x2 = y2 = nan
        else:
            cx, cy = centroid.xy
            if isinstance(size, (tuple, list)):
                w, h = size
            else:
                w = h = size
            x1 = cx - w / 2
            y1 = cy - h / 2
            x2 = cx + w / 2
            y2 = cy + h / 2
            x1, y1, x2, y2 = _apply_padding(x1, y1, x2, y2, padding)
    else:
        raise ValueError(f"Unknown mode {mode!r}. Expected 'tight' or 'centered'.")

    kwargs = dict(
        x1=x1,
        y1=y1,
        x2=x2,
        y2=y2,
        angle=angle,
        track=self.track,
        tracking_score=self.tracking_score,
        identity=self.identity,
        identity_score=self.identity_score,
        identity_embedding=self.identity_embedding,
        category=self.category,
        category_score=self.category_score,
        category_embedding=self.category_embedding,
        instance=self,
    )
    if isinstance(self, PredictedInstance):
        return PredictedBoundingBox(score=self.score, **kwargs)
    return UserBoundingBox(**kwargs)

`to_centroid(method='center_of_mass', node=None, fallback=None, error_on_empty=False, **kwargs)` ¶

Create a Centroid from this instance.

Delegates to Centroid.from_pose(). A PredictedInstance yields a PredictedCentroid carrying its score; any other instance yields a UserCentroid. Metadata (track, tracking_score, identity, identity_score, identity_embedding, category, category_score, category_embedding, instance=self) is propagated.

Parameters:

Name	Type	Description	Default
`method`	`str`	Computation method (`"center_of_mass"`, `"bbox_center"`, `"geometric_median"`, or `"anchor"`).	`'center_of_mass'`
`node`	`int \| str \| None`	Node specification for the `"anchor"` method. Can be a node name (str) or index (int).	`None`
`fallback`	`str \| None`	For the `"anchor"` method, a non-anchor method to fall back to when the anchor node is occluded.	`None`
`error_on_empty`	`bool`	If `True`, raise `ValueError` when there are no visible points instead of returning a degenerate (NaN) centroid.	`False`
`**kwargs`		Additional keyword arguments passed to the centroid constructor.	required

Returns:

Type	Description
`Centroid`	A `UserCentroid` or `PredictedCentroid` depending on the instance type.

Raises:

Type	Description
`ValueError`	For an unknown `method`, a missing `node` for the `"anchor"` method, an invalid `node` type, or (when `error_on_empty` is `True`) when there are no visible points.

Source code in sleap_io/model/instance.py

def to_centroid(
    self,
    method: str = "center_of_mass",
    node: int | str | None = None,
    fallback: str | None = None,
    error_on_empty: bool = False,
    **kwargs,
) -> "Centroid":
    """Create a ``Centroid`` from this instance.

    Delegates to ``Centroid.from_pose()``. A ``PredictedInstance`` yields a
    ``PredictedCentroid`` carrying its ``score``; any other instance yields a
    ``UserCentroid``. Metadata (``track``, ``tracking_score``, ``identity``,
    ``identity_score``, ``identity_embedding``, ``category``,
    ``category_score``, ``category_embedding``, ``instance=self``) is
    propagated.

    Args:
        method: Computation method (``"center_of_mass"``, ``"bbox_center"``,
            ``"geometric_median"``, or ``"anchor"``).
        node: Node specification for the ``"anchor"`` method. Can be a node
            name (str) or index (int).
        fallback: For the ``"anchor"`` method, a non-anchor method to fall
            back to when the anchor node is occluded.
        error_on_empty: If ``True``, raise ``ValueError`` when there are no
            visible points instead of returning a degenerate (NaN) centroid.
        **kwargs: Additional keyword arguments passed to the centroid
            constructor.

    Returns:
        A ``UserCentroid`` or ``PredictedCentroid`` depending on the
        instance type.

    Raises:
        ValueError: For an unknown ``method``, a missing ``node`` for the
            ``"anchor"`` method, an invalid ``node`` type, or (when
            ``error_on_empty`` is ``True``) when there are no visible points.
    """
    from sleap_io.model.centroid import Centroid

    return Centroid.from_pose(
        self,
        method=method,
        node=node,
        fallback=fallback,
        error_on_empty=error_on_empty,
        **kwargs,
    )

`to_mask(height, width, **roi_kwargs)` ¶

Rasterize this instance's ROI geometry into a segmentation mask.

Equivalent to self.to_roi(**roi_kwargs).to_mask(height, width), except that a zero-area hull (method="convex_hull" over fewer than three visible points yields a Point or LineString) rasterizes to an all-background mask here instead of raising. A PredictedInstance yields a PredictedSegmentationMask carrying its score; any other instance yields a UserSegmentationMask. Metadata is propagated.

Parameters:

Name	Type	Description	Default
`height`	`int`	Height of the output mask in pixels.	required
`width`	`int`	Width of the output mask in pixels.	required
`**roi_kwargs`		Keyword arguments forwarded to :meth:`to_roi` (e.g. `method`, `node_radius`, `edge_radius`, `radius`, `quad_segs`, `error_on_empty`).	required

Returns:

Type	Description
`SegmentationMask`	A `SegmentationMask` with the rasterized geometry (all background if the geometry is empty or has zero area).

Raises:

Type	Description
`ValueError`	Propagated from :meth:`to_roi` for a `"shapes"` misconfiguration, an unknown method, or (when `error_on_empty` is `True`) an empty geometry.

Source code in sleap_io/model/instance.py

def to_mask(self, height: int, width: int, **roi_kwargs) -> "SegmentationMask":
    """Rasterize this instance's ROI geometry into a segmentation mask.

    Equivalent to ``self.to_roi(**roi_kwargs).to_mask(height, width)``,
    except that a zero-area hull (``method="convex_hull"`` over fewer than
    three visible points yields a ``Point`` or ``LineString``) rasterizes to
    an all-background mask here instead of raising. A ``PredictedInstance``
    yields a ``PredictedSegmentationMask`` carrying its ``score``; any other
    instance yields a ``UserSegmentationMask``. Metadata is propagated.

    Args:
        height: Height of the output mask in pixels.
        width: Width of the output mask in pixels.
        **roi_kwargs: Keyword arguments forwarded to :meth:`to_roi` (e.g.
            ``method``, ``node_radius``, ``edge_radius``, ``radius``,
            ``quad_segs``, ``error_on_empty``).

    Returns:
        A ``SegmentationMask`` with the rasterized geometry (all background
        if the geometry is empty or has zero area).

    Raises:
        ValueError: Propagated from :meth:`to_roi` for a ``"shapes"``
            misconfiguration, an unknown method, or (when
            ``error_on_empty`` is ``True``) an empty geometry.
    """
    from shapely.geometry import MultiPolygon, Polygon

    error_on_empty = roi_kwargs.pop("error_on_empty", False)
    roi = self.to_roi(error_on_empty=error_on_empty, **roi_kwargs)

    # A non-empty but non-fillable geometry (e.g. convex_hull of <3 visible
    # points -> Point/LineString) has zero area; rasterize it as all
    # background rather than letting _rasterize_geometry raise a TypeError.
    rasterizable = isinstance(roi.geometry, (Polygon, MultiPolygon))
    if roi.geometry.is_empty or not rasterizable:
        from sleap_io.model.mask import (
            PredictedSegmentationMask,
            UserSegmentationMask,
        )

        empty = np.zeros((height, width), dtype=bool)
        kwargs = dict(
            track=self.track,
            tracking_score=self.tracking_score,
            identity=self.identity,
            identity_score=self.identity_score,
            category=self.category,
            instance=self,
        )
        if isinstance(self, PredictedInstance):
            return PredictedSegmentationMask.from_numpy(
                empty, score=self.score, **kwargs
            )
        return UserSegmentationMask.from_numpy(empty, **kwargs)

    return roi.to_mask(height, width)

`to_roi(method='shapes', node_radius=0.0, edge_radius=0.0, radius=0.0, quad_segs=8, error_on_empty=False)` ¶

Create a region-of-interest geometry from this instance.

A PredictedInstance yields a PredictedROI carrying its score; any other instance yields a UserROI. Metadata (track, tracking_score, identity, identity_score, identity_embedding, category, category_score, category_embedding, instance=self) is propagated.

Parameters:

Name	Type	Description	Default
`method`	`str`	`"shapes"` to union buffered node points and/or edge segments, or `"convex_hull"` to take the convex hull of the visible points.	`'shapes'`
`node_radius`	`float`	Buffer radius around each visible node (`"shapes"` only).	`0.0`
`edge_radius`	`float`	Buffer radius around each fully-visible edge segment (`"shapes"` only).	`0.0`
`radius`	`float`	Optional buffer applied to the convex hull (`"convex_hull"` only).	`0.0`
`quad_segs`	`int`	Number of segments used to approximate a quarter circle when buffering.	`8`
`error_on_empty`	`bool`	If `True`, raise `ValueError` when the resulting geometry is empty instead of returning an empty-geometry ROI.	`False`

Returns:

Type	Description
`ROI`	A `ROI` whose geometry encloses the instance (an empty `Polygon` if there are no visible points).

Raises:

Type	Description
`ValueError`	If `method="shapes"` with both `node_radius` and `edge_radius` equal to 0 (a misconfiguration, always raised), for an unknown `method`, or (when `error_on_empty` is `True`) when the resulting geometry is empty.

Source code in sleap_io/model/instance.py

def to_roi(
    self,
    method: str = "shapes",
    node_radius: float = 0.0,
    edge_radius: float = 0.0,
    radius: float = 0.0,
    quad_segs: int = 8,
    error_on_empty: bool = False,
) -> "ROI":
    """Create a region-of-interest geometry from this instance.

    A ``PredictedInstance`` yields a ``PredictedROI`` carrying its ``score``;
    any other instance yields a ``UserROI``. Metadata (``track``,
    ``tracking_score``, ``identity``, ``identity_score``,
    ``identity_embedding``, ``category``, ``category_score``,
    ``category_embedding``, ``instance=self``) is propagated.

    Args:
        method: ``"shapes"`` to union buffered node points and/or edge
            segments, or ``"convex_hull"`` to take the convex hull of the
            visible points.
        node_radius: Buffer radius around each visible node (``"shapes"``
            only).
        edge_radius: Buffer radius around each fully-visible edge segment
            (``"shapes"`` only).
        radius: Optional buffer applied to the convex hull
            (``"convex_hull"`` only).
        quad_segs: Number of segments used to approximate a quarter circle
            when buffering.
        error_on_empty: If ``True``, raise ``ValueError`` when the resulting
            geometry is empty instead of returning an empty-geometry ROI.

    Returns:
        A ``ROI`` whose geometry encloses the instance (an empty ``Polygon``
        if there are no visible points).

    Raises:
        ValueError: If ``method="shapes"`` with both ``node_radius`` and
            ``edge_radius`` equal to 0 (a misconfiguration, always raised),
            for an unknown ``method``, or (when ``error_on_empty`` is
            ``True``) when the resulting geometry is empty.
    """
    from sleap_io.model.roi import PredictedROI, UserROI, _pose_to_geometry

    # Misconfiguration: raise before the empty-points check so that an empty
    # instance still surfaces the error.
    if method == "shapes" and node_radius == 0 and edge_radius == 0:
        raise ValueError(
            "method='shapes' requires at least one of node_radius or "
            "edge_radius to be > 0."
        )

    geom = _pose_to_geometry(
        self.numpy(invisible_as_nan=True),
        self.skeleton.edge_inds,
        method=method,
        node_radius=node_radius,
        edge_radius=edge_radius,
        radius=radius,
        quad_segs=quad_segs,
    )

    if geom.is_empty and error_on_empty:
        raise ValueError("No visible points to compute ROI geometry.")

    kwargs = dict(
        geometry=geom,
        track=self.track,
        tracking_score=self.tracking_score,
        identity=self.identity,
        identity_score=self.identity_score,
        identity_embedding=self.identity_embedding,
        category=self.category,
        category_score=self.category_score,
        category_embedding=self.category_embedding,
        instance=self,
    )
    if isinstance(self, PredictedInstance):
        return PredictedROI(score=self.score, **kwargs)
    return UserROI(**kwargs)

`update_skeleton(names_only=False)` ¶

Update or replace the skeleton associated with the instance.

Parameters:

Name	Type	Description	Default
`names_only`	`bool`	If `True`, only update the node names in the points array. If `False`, the points array will be updated to match the new skeleton.	`False`

Source code in sleap_io/model/instance.py

def update_skeleton(self, names_only: bool = False):
    """Update or replace the skeleton associated with the instance.

    Args:
        names_only: If `True`, only update the node names in the points array. If
            `False`, the points array will be updated to match the new skeleton.
    """
    if names_only:
        # Update the node names.
        self.points["name"] = self.skeleton.node_names
        return

    # Find correspondences.
    new_node_inds, old_node_inds = self.skeleton.match_nodes(self.points["name"])

    # Update the points.
    new_points = PointsArray.empty(len(self.skeleton))
    new_points[new_node_inds] = self.points[old_node_inds]
    new_points["name"] = self.skeleton.node_names
    self.points = new_points

`InstanceMatchMethod` ¶

Bases: builtins.str, enum.Enum

Methods for matching instances.

Attributes:

Name	Type	Description
`SPATIAL`		Match instances by spatial proximity using Euclidean distance.
`IDENTITY`		Match instances by track identity (same track object).
`IOU`		Match instances by bounding box Intersection over Union.

Source code in sleap_io/model/matching.py

class InstanceMatchMethod(str, Enum):
    """Methods for matching instances.

    Attributes:
        SPATIAL: Match instances by spatial proximity using Euclidean distance.
        IDENTITY: Match instances by track identity (same track object).
        IOU: Match instances by bounding box Intersection over Union.
    """

    SPATIAL = "spatial"
    IDENTITY = "identity"
    IOU = "iou"

`IDENTITY = <InstanceMatchMethod.IDENTITY: 'identity'>` `class-attribute` ¶

Methods for matching instances.

Attributes:

Name	Type	Description
`SPATIAL`		Match instances by spatial proximity using Euclidean distance.
`IDENTITY`		Match instances by track identity (same track object).
`IOU`		Match instances by bounding box Intersection over Union.

`IOU = <InstanceMatchMethod.IOU: 'iou'>` `class-attribute` ¶

Methods for matching instances.

Attributes:

Name	Type	Description
`SPATIAL`		Match instances by spatial proximity using Euclidean distance.
`IDENTITY`		Match instances by track identity (same track object).
`IOU`		Match instances by bounding box Intersection over Union.

`SPATIAL = <InstanceMatchMethod.SPATIAL: 'spatial'>` `class-attribute` ¶

Methods for matching instances.

Attributes:

Name	Type	Description
`SPATIAL`		Match instances by spatial proximity using Euclidean distance.
`IDENTITY`		Match instances by track identity (same track object).
`IOU`		Match instances by bounding box Intersection over Union.

`doc = 'Methods for matching instances.\n\nAttributes:\n SPATIAL: Match instances by spatial proximity using Euclidean distance.\n IDENTITY: Match instances by track identity (same track object).\n IOU: Match instances by bounding box Intersection over Union.\n'` `class-attribute` ¶

str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.str() (if defined) or repr(object). encoding defaults to 'utf-8'. errors defaults to 'strict'.

`module = 'sleap_io.model.matching'` `class-attribute` ¶

str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.str() (if defined) or repr(object). encoding defaults to 'utf-8'. errors defaults to 'strict'.

`InstanceMatcher` ¶

Matcher for comparing and matching instances.

Attributes:

Name	Type	Description
`method`		The matching method to use. Can be an InstanceMatchMethod enum value or a string that will be converted to the enum. Default is SPATIAL.
`threshold`		The threshold value used for matching. For SPATIAL method, this is the maximum pixel distance. For IOU method, this is the minimum IoU value. Not used for IDENTITY method. Default is 5.0.

Methods:

Name	Description
`__eq__`	Method generated by attrs for class InstanceMatcher.
`__init__`	Method generated by attrs for class InstanceMatcher.
`__repr__`	Method generated by attrs for class InstanceMatcher.
`__setattr__`	Method generated by attrs for class InstanceMatcher.
`find_matches`	Find all matching instances between two lists.
`match`	Check if two instances match according to the configured method.

Source code in sleap_io/model/matching.py

@attrs.define
class InstanceMatcher:
    """Matcher for comparing and matching instances.

    Attributes:
        method: The matching method to use. Can be an InstanceMatchMethod enum value
            or a string that will be converted to the enum. Default is SPATIAL.
        threshold: The threshold value used for matching. For SPATIAL method, this is
            the maximum pixel distance. For IOU method, this is the minimum IoU value.
            Not used for IDENTITY method. Default is 5.0.
    """

    method: InstanceMatchMethod | str = attrs.field(
        default=InstanceMatchMethod.SPATIAL,
        converter=lambda x: InstanceMatchMethod(x) if isinstance(x, str) else x,
    )
    threshold: float = 5.0

    def match(self, instance1: Instance, instance2: Instance) -> bool:
        """Check if two instances match according to the configured method."""
        if self.method == InstanceMatchMethod.SPATIAL:
            return instance1.same_pose_as(instance2, tolerance=self.threshold)
        elif self.method == InstanceMatchMethod.IDENTITY:
            return instance1.same_identity_as(instance2)
        elif self.method == InstanceMatchMethod.IOU:
            return instance1.overlaps_with(instance2, iou_threshold=self.threshold)
        else:
            raise ValueError(f"Unknown instance match method: {self.method}")

    def find_matches(
        self, instances1: list[Instance], instances2: list[Instance]
    ) -> list[tuple[int, int, float]]:
        """Find all matching instances between two lists.

        Returns:
            List of (idx1, idx2, score) tuples for matching instances.
        """
        matches = []

        for i, inst1 in enumerate(instances1):
            for j, inst2 in enumerate(instances2):
                if self.match(inst1, inst2):
                    # Calculate match score based on method
                    if self.method == InstanceMatchMethod.SPATIAL:
                        # Use inverse distance as score
                        pts1 = inst1.numpy()
                        pts2 = inst2.numpy()
                        valid = ~(np.isnan(pts1[:, 0]) | np.isnan(pts2[:, 0]))
                        if valid.any():
                            distances = np.linalg.norm(
                                pts1[valid] - pts2[valid], axis=1
                            )
                            score = 1.0 / (1.0 + np.mean(distances))
                        else:
                            score = 0.0
                    elif self.method == InstanceMatchMethod.IOU:
                        # Calculate actual IoU as score
                        bbox1 = inst1.bounding_box()
                        bbox2 = inst2.bounding_box()
                        if bbox1 is not None and bbox2 is not None:
                            # Calculate IoU
                            intersection_min = np.maximum(bbox1[0], bbox2[0])
                            intersection_max = np.minimum(bbox1[1], bbox2[1])
                            if np.all(intersection_min < intersection_max):
                                intersection_area = np.prod(
                                    intersection_max - intersection_min
                                )
                                area1 = np.prod(bbox1[1] - bbox1[0])
                                area2 = np.prod(bbox2[1] - bbox2[0])
                                union_area = area1 + area2 - intersection_area
                                score = (
                                    intersection_area / union_area
                                    if union_area > 0
                                    else 0
                                )
                            else:
                                score = 0.0
                        else:
                            score = 0.0
                    else:
                        score = 1.0  # Binary match for identity

                    matches.append((i, j, score))

        return matches

`annotations = {'method': 'InstanceMatchMethod | str', 'threshold': 'float'}` `class-attribute` ¶

dict() -> new empty dictionary dict(mapping) -> new dictionary initialized from a mapping object's (key, value) pairs dict(iterable) -> new dictionary initialized as if via: d = {} for k, v in iterable: d[k] = v dict(**kwargs) -> new dictionary initialized with the name=value pairs in the keyword argument list. For example: dict(one=1, two=2)

`__attrs_own_setattr__ = True` `class-attribute` ¶

Returns True when the argument is true, False otherwise. The builtins True and False are the only two instances of the class bool. The class bool is a subclass of the class int, and cannot be subclassed.

`__attrs_props__ = ClassProps(is_exception=False, is_slotted=True, has_weakref_slot=True, is_frozen=False, kw_only=<KeywordOnly.NO: 'no'>, collected_fields_by_mro=True, added_init=True, added_repr=True, added_eq=True, added_ordering=False, hashability=<Hashability.UNHASHABLE: 'unhashable'>, added_match_args=True, added_str=False, added_pickling=True, on_setattr_hook=<function pipe.<locals>.wrapped_pipe at 0x7f08471ce840>, field_transformer=None)` `class-attribute` ¶

Effective class properties as derived from parameters to attr.s() or define() decorators.

This is the same data structure that attrs uses internally to decide how to construct the final class.

Warning:

This feature is currently **experimental** and is not covered by our
strict backwards-compatibility guarantees.

Attributes:

Name	Type	Description
`is_exception`	`bool`	Whether the class is treated as an exception class.
`is_slotted`	`bool`	Whether the class is `slotted <slotted classes>`.
`has_weakref_slot`	`bool`	Whether the class has a slot for weak references.
`is_frozen`	`bool`	Whether the class is frozen.
`kw_only`	`KeywordOnly`	Whether / how the class enforces keyword-only arguments on the `__init__` method.
`collected_fields_by_mro`	`bool`	Whether the class fields were collected by method resolution order. That is, correctly but unlike `dataclasses`.
`added_init`	`bool`	Whether the class has an attrs-generated `__init__` method.
`added_repr`	`bool`	Whether the class has an attrs-generated `__repr__` method.
`added_eq`	`bool`	Whether the class has attrs-generated equality methods.
`added_ordering`	`bool`	Whether the class has attrs-generated ordering methods.
`hashability`	`Hashability`	How `hashable <hashing>` the class is.
`added_match_args`	`bool`	Whether the class supports positional `match <match>` over its fields.
`added_str`	`bool`	Whether the class has an attrs-generated `__str__` method.
`added_pickling`	`bool`	Whether the class has attrs-generated `__getstate__` and `__setstate__` methods for `pickle`.
`on_setattr_hook`	`Callable[[Any, Attribute[Any], Any], Any] \| None`	The class's `__setattr__` hook.
`field_transformer`	`Callable[[Attribute[Any]], Attribute[Any]] \| None`	The class's `field transformers <transform-fields>`.

.. versionadded:: 25.4.0

`doc = 'Matcher for comparing and matching instances.\n\nAttributes:\n method: The matching method to use. Can be an InstanceMatchMethod enum value\n or a string that will be converted to the enum. Default is SPATIAL.\n threshold: The threshold value used for matching. For SPATIAL method, this is\n the maximum pixel distance. For IOU method, this is the minimum IoU value.\n Not used for IDENTITY method. Default is 5.0.\n'` `class-attribute` ¶

str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.str() (if defined) or repr(object). encoding defaults to 'utf-8'. errors defaults to 'strict'.

`firstlineno = 796` `class-attribute` ¶

int([x]) -> integer int(x, base=10) -> integer

Convert a number or string to an integer, or return 0 if no arguments are given. If x is a number, return x.int(). For floating-point numbers, this truncates towards zero.

If x is not a number or if base is given, then x must be a string, bytes, or bytearray instance representing an integer literal in the given base. The literal can be preceded by '+' or '-' and be surrounded by whitespace. The base defaults to 10. Valid bases are 0 and 2-36. Base 0 means to interpret the base from the string as an integer iteral.

`__match_args__ = ('method', 'threshold')` `class-attribute` ¶

Built-in immutable sequence.

If no argument is given, the constructor returns an empty tuple. If iterable is specified the tuple is initialized from iterable's items.

If the argument is a tuple, the return value is the same object.

`module = 'sleap_io.model.matching'` `class-attribute` ¶

str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.str() (if defined) or repr(object). encoding defaults to 'utf-8'. errors defaults to 'strict'.

`slots = ('method', 'threshold', 'weakref')` `class-attribute` ¶

Built-in immutable sequence.

If no argument is given, the constructor returns an empty tuple. If iterable is specified the tuple is initialized from iterable's items.

If the argument is a tuple, the return value is the same object.

`__static_attributes__ = ()` `class-attribute` ¶

Built-in immutable sequence.

If no argument is given, the constructor returns an empty tuple. If iterable is specified the tuple is initialized from iterable's items.

If the argument is a tuple, the return value is the same object.

`weakref` `property` ¶

list of weak references to the object

`eq(other)` ¶

Method generated by attrs for class InstanceMatcher.

Source code in sleap_io/model/matching.py

automatic strategies.
"""

from __future__ import annotations

from enum import Enum
from typing import TYPE_CHECKING, Any

`init(method=<InstanceMatchMethod.SPATIAL: 'spatial'>, threshold=5.0)` ¶

Method generated by attrs for class InstanceMatcher.

Source code in sleap_io/model/matching.py

import attrs
import numpy as np

`repr()` ¶

Method generated by attrs for class InstanceMatcher.

Source code in sleap_io/model/matching.py

"""Unified matcher system for comparing and matching data structures during merging.

This module provides configurable matchers for comparing skeletons, instances, tracks,
and videos during merge operations. The matchers use various strategies to determine
when data structures should be considered equivalent during merging.

Key features:
- Skeleton matching: exact, structure-based, overlap, and subset matching
- Instance matching: spatial proximity, track identity, and bounding box IoU
- Track matching: by name or object identity
- Identity matching: by name or object identity
- Category matching: by name or object identity
- Video matching: path, basename, content, and auto matching

Video matching supports path-based, filename-based, content-based, and

`setattr(name, val)` ¶

Method generated by attrs for class InstanceMatcher.

Source code in sleap_io/model/matching.py

        return match

# IMAGE MATCHING: Compare frame images (opt-in)
if self.compare_images:
    match = self._match_by_images(incoming, viable)
    if match is not None:
        return match

# No match found

`find_matches(instances1, instances2)` ¶

Find all matching instances between two lists.

Returns:

Type	Description
`list[tuple[int, int, float]]`	List of (idx1, idx2, score) tuples for matching instances.

Source code in sleap_io/model/matching.py

def find_matches(
    self, instances1: list[Instance], instances2: list[Instance]
) -> list[tuple[int, int, float]]:
    """Find all matching instances between two lists.

    Returns:
        List of (idx1, idx2, score) tuples for matching instances.
    """
    matches = []

    for i, inst1 in enumerate(instances1):
        for j, inst2 in enumerate(instances2):
            if self.match(inst1, inst2):
                # Calculate match score based on method
                if self.method == InstanceMatchMethod.SPATIAL:
                    # Use inverse distance as score
                    pts1 = inst1.numpy()
                    pts2 = inst2.numpy()
                    valid = ~(np.isnan(pts1[:, 0]) | np.isnan(pts2[:, 0]))
                    if valid.any():
                        distances = np.linalg.norm(
                            pts1[valid] - pts2[valid], axis=1
                        )
                        score = 1.0 / (1.0 + np.mean(distances))
                    else:
                        score = 0.0
                elif self.method == InstanceMatchMethod.IOU:
                    # Calculate actual IoU as score
                    bbox1 = inst1.bounding_box()
                    bbox2 = inst2.bounding_box()
                    if bbox1 is not None and bbox2 is not None:
                        # Calculate IoU
                        intersection_min = np.maximum(bbox1[0], bbox2[0])
                        intersection_max = np.minimum(bbox1[1], bbox2[1])
                        if np.all(intersection_min < intersection_max):
                            intersection_area = np.prod(
                                intersection_max - intersection_min
                            )
                            area1 = np.prod(bbox1[1] - bbox1[0])
                            area2 = np.prod(bbox2[1] - bbox2[0])
                            union_area = area1 + area2 - intersection_area
                            score = (
                                intersection_area / union_area
                                if union_area > 0
                                else 0
                            )
                        else:
                            score = 0.0
                    else:
                        score = 0.0
                else:
                    score = 1.0  # Binary match for identity

                matches.append((i, j, score))

    return matches

`match(instance1, instance2)` ¶

Check if two instances match according to the configured method.

Source code in sleap_io/model/matching.py

def match(self, instance1: Instance, instance2: Instance) -> bool:
    """Check if two instances match according to the configured method."""
    if self.method == InstanceMatchMethod.SPATIAL:
        return instance1.same_pose_as(instance2, tolerance=self.threshold)
    elif self.method == InstanceMatchMethod.IDENTITY:
        return instance1.same_identity_as(instance2)
    elif self.method == InstanceMatchMethod.IOU:
        return instance1.overlaps_with(instance2, iou_threshold=self.threshold)
    else:
        raise ValueError(f"Unknown instance match method: {self.method}")

`LabeledFrame` ¶

Labeled data for a single frame of a video.

Attributes:

Name	Type	Description
`video`		The `Video` associated with this `LabeledFrame`.
`frame_idx`		The index of the `LabeledFrame` in the `Video`.
`instances`		List of `Instance` objects associated with this `LabeledFrame`.
`is_negative`		If True, this frame is explicitly marked as containing no instances (a "negative" or background frame for training). This is distinct from frames that are simply empty (e.g., instances were deleted).
`centroids`		List of `Centroid` annotations for this frame.
`bboxes`		List of `BoundingBox` annotations for this frame.
`masks`		List of `SegmentationMask` annotations for this frame.
`label_images`		List of `LabelImage` annotations for this frame.
`rois`		List of `ROI` annotations for this frame.

Notes

Instances of this class are hashed by identity, not by value. This means that two LabeledFrame instances with the same attributes will NOT be considered equal in a set or dict.

Methods:

Name	Description
`__getitem__`	Return the `Instance` at `key` index in the `instances` list.
`__init__`	Method generated by attrs for class LabeledFrame.
`__iter__`	Iterate over `Instance`s in `instances` list.
`__len__`	Return the number of instances in the frame.
`__repr__`	Method generated by attrs for class LabeledFrame.
`__setattr__`	Method generated by attrs for class LabeledFrame.
`append`	Append an annotation to the appropriate frame-level container.
`convert`	Convert annotations between detection modalities.
`matches`	Check if this frame matches another frame's identity.
`merge`	Merge instances from another frame into this frame.
`numpy`	Return all instances in the frame as a numpy array.
`remove_empty_instances`	Remove all instances with no visible points.
`remove_predictions`	Remove all predicted instances and annotations from the frame.
`similarity_to`	Calculate instance overlap metrics with another frame.

Source code in sleap_io/model/labeled_frame.py

@define(eq=False)
class LabeledFrame:
    """Labeled data for a single frame of a video.

    Attributes:
        video: The `Video` associated with this `LabeledFrame`.
        frame_idx: The index of the `LabeledFrame` in the `Video`.
        instances: List of `Instance` objects associated with this `LabeledFrame`.
        is_negative: If True, this frame is explicitly marked as containing no
            instances (a "negative" or background frame for training). This is
            distinct from frames that are simply empty (e.g., instances were deleted).
        centroids: List of `Centroid` annotations for this frame.
        bboxes: List of `BoundingBox` annotations for this frame.
        masks: List of `SegmentationMask` annotations for this frame.
        label_images: List of `LabelImage` annotations for this frame.
        rois: List of `ROI` annotations for this frame.

    Notes:
        Instances of this class are hashed by identity, not by value. This means that
        two `LabeledFrame` instances with the same attributes will NOT be considered
        equal in a set or dict.
    """

    video: Video
    frame_idx: int = field(converter=int)
    instances: list[Instance | PredictedInstance] = field(factory=list)
    is_negative: bool = field(default=False)
    centroids: "list[Centroid]" = field(factory=list)
    bboxes: "list[BoundingBox]" = field(factory=list)
    masks: "list[SegmentationMask]" = field(factory=list)
    label_images: "list[LabelImage]" = field(factory=list)
    rois: "list[ROI]" = field(factory=list)

    def append(
        self,
        annotation: (
            "Instance | PredictedInstance | Centroid"
            " | BoundingBox | SegmentationMask | LabelImage | ROI"
        ),
    ) -> None:
        """Append an annotation to the appropriate frame-level container.

        Routes the annotation to the correct list based on its type:
        ``Instance``/``PredictedInstance`` → ``instances``,
        ``Centroid`` → ``centroids``, ``BoundingBox`` → ``bboxes``,
        ``SegmentationMask`` → ``masks``, ``LabelImage`` → ``label_images``,
        ``ROI`` → ``rois``.

        Args:
            annotation: The annotation object to add.

        Raises:
            TypeError: If the annotation type is not recognized.
        """
        from sleap_io.model.bbox import BoundingBox
        from sleap_io.model.centroid import Centroid
        from sleap_io.model.label_image import LabelImage
        from sleap_io.model.mask import SegmentationMask
        from sleap_io.model.roi import ROI

        if isinstance(annotation, (Instance, PredictedInstance)):
            self.instances.append(annotation)
        elif isinstance(annotation, Centroid):
            self.centroids.append(annotation)
        elif isinstance(annotation, BoundingBox):
            self.bboxes.append(annotation)
        elif isinstance(annotation, SegmentationMask):
            self.masks.append(annotation)
        elif isinstance(annotation, LabelImage):
            self.label_images.append(annotation)
        elif isinstance(annotation, ROI):
            self.rois.append(annotation)
        else:
            raise TypeError(
                f"Cannot append {type(annotation).__name__} to LabeledFrame. "
                f"Expected one of: Instance, PredictedInstance, Centroid, "
                f"BoundingBox, SegmentationMask, LabelImage, ROI."
            )

    def __len__(self) -> int:
        """Return the number of instances in the frame."""
        return len(self.instances)

    def __getitem__(self, key: int) -> Instance | PredictedInstance:
        """Return the `Instance` at `key` index in the `instances` list."""
        return self.instances[key]

    def __iter__(self):
        """Iterate over `Instance`s in `instances` list."""
        return iter(self.instances)

    @property
    def user_instances(self) -> list[Instance]:
        """Frame instances that are user-labeled (`Instance` objects)."""
        return [inst for inst in self.instances if type(inst) is Instance]

    @property
    def has_user_instances(self) -> bool:
        """Return True if the frame has any user-labeled instances."""
        for inst in self.instances:
            if type(inst) is Instance:
                return True
        return False

    @property
    def is_user_labeled(self) -> bool:
        """Return True if frame has user instances/annotations OR is negative.

        This property indicates whether the frame represents intentional user
        annotation, either through labeled instances, user annotations
        (centroids, bboxes, ROIs, masks, label images), or explicit marking as a
        negative/background frame.
        """
        from sleap_io.model.label_image import PredictedLabelImage
        from sleap_io.model.mask import PredictedSegmentationMask

        return (
            self.has_user_instances
            or self.is_negative
            or any(not c.is_predicted for c in self.centroids)
            or any(not b.is_predicted for b in self.bboxes)
            or any(not r.is_predicted for r in self.rois)
            or any(not isinstance(m, PredictedSegmentationMask) for m in self.masks)
            or any(not isinstance(li, PredictedLabelImage) for li in self.label_images)
        )

    @property
    def predicted_instances(self) -> list[Instance]:
        """Frame instances that are predicted by a model (`PredictedInstance`)."""
        return [inst for inst in self.instances if type(inst) is PredictedInstance]

    @property
    def has_predicted_instances(self) -> bool:
        """Return True if the frame has any predicted instances."""
        for inst in self.instances:
            if type(inst) is PredictedInstance:
                return True
        return False

    def numpy(self) -> np.ndarray:
        """Return all instances in the frame as a numpy array.

        Returns:
            Points as a numpy array of shape `(n_instances, n_nodes, 2)`.

            Note that the order of the instances is arbitrary.
        """
        n_instances = len(self.instances)
        n_nodes = len(self.instances[0]) if n_instances > 0 else 0
        pts = np.full((n_instances, n_nodes, 2), np.nan)
        for i, inst in enumerate(self.instances):
            pts[i] = inst.numpy()[:, 0:2]
        return pts

    @property
    def image(self) -> np.ndarray:
        """Return the image of the frame as a numpy array."""
        return self.video[self.frame_idx]

    @property
    def unused_predictions(self) -> list[Instance]:
        """Return a list of "unused" `PredictedInstance` objects in frame.

        This is all of the `PredictedInstance` objects which do not have a corresponding
        `Instance` in the same track in the same frame.
        """
        unused_predictions = []
        any_tracks = [inst.track for inst in self.instances if inst.track is not None]
        if len(any_tracks):
            # Use tracks to determine which predicted instances have been used
            used_tracks = [
                inst.track
                for inst in self.instances
                if type(inst) is Instance and inst.track is not None
            ]
            unused_predictions = [
                inst
                for inst in self.instances
                if inst.track not in used_tracks and type(inst) is PredictedInstance
            ]

        else:
            # Use from_predicted to determine which predicted instances have been used
            # TODO: should we always do this instead of using tracks?
            used_instances = [
                inst.from_predicted
                for inst in self.instances
                if inst.from_predicted is not None
            ]
            unused_predictions = [
                inst
                for inst in self.instances
                if type(inst) is PredictedInstance and inst not in used_instances
            ]

        return unused_predictions

    @property
    def unused_predicted_masks(self) -> list["SegmentationMask"]:
        """Return predicted masks in this frame not yet adopted by a user mask.

        A `PredictedSegmentationMask` is considered *adopted* (and so excluded
        from the result) when some `UserSegmentationMask` in the same frame
        either links to it via `from_predicted` (checked first) or, lacking an
        explicit link, spatially overlaps it (bbox-centroid distance within 5 px,
        the auto-merge default). This mirrors the link-first, spatial-fallback
        precedence used by the auto-merge cascade and supports the
        "retrain only what a human corrected" workflow.

        This is the segmentation-mask analogue of `unused_predictions` (which
        covers `PredictedInstance` objects).

        Returns:
            The `PredictedSegmentationMask` objects with no adopting user mask.
        """
        from sleap_io.model.mask import PredictedSegmentationMask

        predicted = [m for m in self.masks if isinstance(m, PredictedSegmentationMask)]
        if not predicted:
            return []
        user_masks = [m for m in self.masks if not m.is_predicted]

        adopted: set[int] = set()
        # Link-first: predicted masks explicitly adopted via from_predicted.
        for u in user_masks:
            src = getattr(u, "from_predicted", None)
            if src is not None:
                adopted.add(id(src))
        # Spatial fallback: a user mask overlaps a still-unadopted prediction.
        remaining = [m for m in predicted if id(m) not in adopted]
        if remaining and user_masks:
            for self_idx, _other_idx, _score in _find_annotation_matches(
                remaining, user_masks, "masks", 5.0
            ):
                adopted.add(id(remaining[self_idx]))

        return [m for m in predicted if id(m) not in adopted]

    def remove_predictions(self):
        """Remove all predicted instances and annotations from the frame."""
        from sleap_io.model.bbox import PredictedBoundingBox
        from sleap_io.model.centroid import PredictedCentroid
        from sleap_io.model.label_image import PredictedLabelImage
        from sleap_io.model.mask import PredictedSegmentationMask
        from sleap_io.model.roi import PredictedROI

        self.instances = [inst for inst in self.instances if type(inst) is Instance]
        self.centroids = [
            c for c in self.centroids if not isinstance(c, PredictedCentroid)
        ]
        self.bboxes = [
            b for b in self.bboxes if not isinstance(b, PredictedBoundingBox)
        ]
        self.masks = [
            m for m in self.masks if not isinstance(m, PredictedSegmentationMask)
        ]
        self.label_images = [
            li for li in self.label_images if not isinstance(li, PredictedLabelImage)
        ]
        self.rois = [r for r in self.rois if not isinstance(r, PredictedROI)]

    def remove_empty_instances(self):
        """Remove all instances with no visible points."""
        self.instances = [inst for inst in self.instances if not inst.is_empty]

    def convert(
        self,
        to: str,
        source: str = "pose",
        inplace: bool = False,
        **kwargs,
    ) -> list:
        """Convert annotations between detection modalities.

        Reads every annotation of the ``source`` modality from this frame and
        converts each one to the ``to`` modality by dispatching to the matching
        per-object verb (``to_centroid``, ``to_bbox``, ``to_mask``, ``to_roi`` or
        ``to_pose``). Keyword arguments are forwarded unchanged to the per-object
        verb (e.g. ``height``/``width`` for ``to="mask"``).

        Args:
            to: Target modality, one of ``"pose"``, ``"centroid"``, ``"bbox"``,
                ``"mask"`` or ``"roi"``.
            source: Source modality, one of ``"pose"``, ``"centroid"``, ``"bbox"``,
                ``"mask"`` or ``"roi"``. Reads from the matching frame list
                (``instances``, ``centroids``, ``bboxes``, ``masks`` or ``rois``).
            inplace: If ``True``, append each produced annotation to this frame
                (via `append`) in addition to returning them. If ``False``
                (default), the frame is left unmodified.
            **kwargs: Forwarded to the per-object conversion verb.

        Returns:
            A list of the produced annotations (one per source annotation), of the
            ``to`` modality.

        Raises:
            ValueError: If ``to`` or ``source`` is not a recognized modality, if
                ``to="pose"`` is requested from a non-centroid source (only
                ``centroid`` → ``pose`` is defined), or if a source annotation
                lacks the target conversion verb.
        """
        modalities = {
            "pose": "instances",
            "centroid": "centroids",
            "bbox": "bboxes",
            "mask": "masks",
            "roi": "rois",
        }
        if to not in modalities:
            raise ValueError(
                f"Unknown target modality {to!r}. Expected one of: "
                f"{', '.join(modalities)}."
            )
        if source not in modalities:
            raise ValueError(
                f"Unknown source modality {source!r}. Expected one of: "
                f"{', '.join(modalities)}."
            )
        if to == "pose" and source != "centroid":
            raise ValueError(
                f"Conversion from {source!r} to 'pose' is not supported; only "
                "'centroid' -> 'pose' is defined."
            )

        verb = "to_pose" if to == "pose" else f"to_{to}"
        sources = getattr(self, modalities[source])

        results = []
        for obj in sources:
            method = getattr(obj, verb, None)
            if method is None:
                raise ValueError(
                    f"Cannot convert {source!r} to {to!r}: "
                    f"{type(obj).__name__} has no {verb}() method."
                )
            result = method(**kwargs)
            results.append(result)
            if inplace:
                self.append(result)
        return results

    def matches(self, other: "LabeledFrame", video_must_match: bool = True) -> bool:
        """Check if this frame matches another frame's identity.

        Args:
            other: Another LabeledFrame to compare with.
            video_must_match: If True, frames must be from the same video.
                If False, only frame index needs to match.

        Returns:
            True if the frames have the same identity, False otherwise.

        Notes:
            Frame identity is determined by video and frame index.
            This does not compare the instances within the frame.
        """
        if self.frame_idx != other.frame_idx:
            return False

        if video_must_match:
            # Check if videos are the same object
            if self.video is other.video:
                return True
            # Check if videos have matching paths
            return self.video.matches_path(other.video, strict=False)

        return True

    def similarity_to(self, other: "LabeledFrame") -> dict[str, any]:
        """Calculate instance overlap metrics with another frame.

        Args:
            other: Another LabeledFrame to compare with.

        Returns:
            A dictionary with similarity metrics:
            - 'n_user_self': Number of user instances in this frame
            - 'n_user_other': Number of user instances in the other frame
            - 'n_pred_self': Number of predicted instances in this frame
            - 'n_pred_other': Number of predicted instances in the other frame
            - 'n_overlapping': Number of instances that overlap (by IoU)
            - 'mean_pose_distance': Mean distance between matching poses
        """
        metrics = {
            "n_user_self": len(self.user_instances),
            "n_user_other": len(other.user_instances),
            "n_pred_self": len(self.predicted_instances),
            "n_pred_other": len(other.predicted_instances),
            "n_overlapping": 0,
            "mean_pose_distance": None,
        }

        # Count overlapping instances and compute pose distances
        pose_distances = []
        for inst1 in self.instances:
            for inst2 in other.instances:
                # Check if instances overlap
                if inst1.overlaps_with(inst2, iou_threshold=0.1):
                    metrics["n_overlapping"] += 1

                    # If they have the same skeleton, compute pose distance
                    if inst1.skeleton.matches(inst2.skeleton):
                        # Get visible points for both
                        pts1 = inst1.numpy()
                        pts2 = inst2.numpy()

                        # Compute distances for visible points in both
                        valid = ~(np.isnan(pts1[:, 0]) | np.isnan(pts2[:, 0]))
                        if valid.any():
                            distances = np.linalg.norm(
                                pts1[valid] - pts2[valid], axis=1
                            )
                            pose_distances.extend(distances.tolist())

        if pose_distances:
            metrics["mean_pose_distance"] = np.mean(pose_distances)

        return metrics

    def merge(
        self,
        other: "LabeledFrame",
        instance: "InstanceMatcher | None" = None,
        frame: str = "auto",
    ) -> tuple[list[Instance], list[tuple[Instance, Instance, str]]]:
        """Merge instances from another frame into this frame.

        Args:
            other: Another LabeledFrame to merge instances from.
            instance: Matcher to use for finding duplicate instances.
                If None, uses default spatial matching with 5px tolerance.
            frame: Merge strategy:
                - "auto": Keep user labels, update predictions only if no user label
                - "keep_original": Keep all original instances, ignore new ones
                - "keep_new": Replace with new instances
                - "keep_both": Keep all instances from both frames
                - "update_tracks": Update track and score of the original instances
                    from the new instances.
                - "replace_predictions": Keep all user instances from original frame,
                    remove all predictions from original frame, add only predictions
                    from the incoming frame. No spatial matching is performed.

        Returns:
            A tuple of (merged_instances, conflicts) where:
            - merged_instances: List of instances after merging
            - conflicts: List of (original, new, resolution) tuples for conflicts

        Notes:
            The merged instance list is returned (not assigned back) so the
            caller can decide what to do with it. Frame-level annotations
            (centroids, bboxes, masks, label images, rois) and the
            ``is_negative`` flag are updated on this frame in place.
        """
        from sleap_io.model.matching import InstanceMatcher, InstanceMatchMethod

        if instance is None:
            instance_matcher = InstanceMatcher(
                method=InstanceMatchMethod.SPATIAL, threshold=5.0
            )
        else:
            instance_matcher = instance

        conflicts = []

        if frame == "keep_original":
            self._merge_annotations(other, strategy="keep_original")
            self.is_negative, _ = _resolve_merged_is_negative(
                self.is_negative, other.is_negative, self.instances
            )
            return self.instances.copy(), conflicts
        elif frame == "keep_new":
            self._merge_annotations(other, strategy="keep_new")
            self.is_negative, _ = _resolve_merged_is_negative(
                self.is_negative, other.is_negative, other.instances
            )
            return other.instances.copy(), conflicts
        elif frame == "keep_both":
            self._merge_annotations(other, strategy="keep_both")
            self.is_negative, _ = _resolve_merged_is_negative(
                self.is_negative, other.is_negative, self.instances + other.instances
            )
            return self.instances + other.instances, conflicts
        elif frame == "update_tracks":
            # match instances and update .track and tracking score of the old instances
            matches = instance_matcher.find_matches(self.instances, other.instances)
            for self_idx, other_idx, score in matches:
                self.instances[self_idx].track = other.instances[other_idx].track
                self.instances[self_idx].tracking_score = other.instances[
                    other_idx
                ].tracking_score
            self._merge_annotations(
                other,
                strategy="update_tracks",
                threshold=instance_matcher.threshold,
            )
            self.is_negative, _ = _resolve_merged_is_negative(
                self.is_negative, other.is_negative, self.instances
            )
            return self.instances, conflicts
        elif frame == "replace_predictions":
            # Keep all user instances from original frame
            merged = [inst for inst in self.instances if type(inst) is Instance]
            # Add only predictions from incoming frame (not user instances)
            merged.extend(
                inst for inst in other.instances if type(inst) is PredictedInstance
            )
            self._merge_annotations(other, strategy="replace_predictions")
            self.is_negative, _ = _resolve_merged_is_negative(
                self.is_negative, other.is_negative, merged
            )
            # No instance conflicts to report - this is a clean replacement
            return merged, []

        # Auto merging strategy
        merged_instances = []
        used_indices = set()

        # First, keep all user instances from self
        for inst in self.instances:
            if type(inst) is Instance:
                merged_instances.append(inst)

        # Find matches between instances
        matches = instance_matcher.find_matches(self.instances, other.instances)

        # Group matches by instance in other frame
        other_to_self = {}
        for self_idx, other_idx, score in matches:
            if other_idx not in other_to_self or score > other_to_self[other_idx][1]:
                other_to_self[other_idx] = (self_idx, score)

        # Process instances from other frame
        for other_idx, other_inst in enumerate(other.instances):
            if other_idx in other_to_self:
                self_idx, score = other_to_self[other_idx]
                self_inst = self.instances[self_idx]

                # Check for conflicts
                if type(self_inst) is Instance and type(other_inst) is Instance:
                    # Both are user instances - conflict
                    conflicts.append((self_inst, other_inst, "kept_original"))
                    used_indices.add(self_idx)
                elif (
                    type(self_inst) is PredictedInstance
                    and type(other_inst) is Instance
                ):
                    # Replace prediction with user instance
                    if self_idx not in used_indices:
                        merged_instances.append(other_inst)
                        used_indices.add(self_idx)
                elif (
                    type(self_inst) is Instance
                    and type(other_inst) is PredictedInstance
                ):
                    # Keep user instance, ignore prediction
                    conflicts.append((self_inst, other_inst, "kept_user"))
                    used_indices.add(self_idx)
                else:
                    # Both are predictions - keep the new one
                    if self_idx not in used_indices:
                        merged_instances.append(other_inst)
                        used_indices.add(self_idx)
            else:
                # No match found, add new instance
                merged_instances.append(other_inst)

        # Add remaining instances from self that weren't matched
        for self_idx, self_inst in enumerate(self.instances):
            if type(self_inst) is PredictedInstance and self_idx not in used_indices:
                # Check if this prediction should be kept
                # NOTE: This defensive logic should be unreachable under normal
                # circumstances since all matched instances should have been added to
                # used_indices above. However, we keep this as a safety net for edge
                # cases or future changes.
                keep = True
                for other_idx, (matched_self_idx, _) in other_to_self.items():
                    if matched_self_idx == self_idx:
                        keep = False
                        break
                if keep:
                    merged_instances.append(self_inst)

        # Merge annotations from the other frame (spatial matching + resolution)
        self._merge_annotations(
            other, strategy="auto", threshold=instance_matcher.threshold
        )

        self.is_negative, _ = _resolve_merged_is_negative(
            self.is_negative, other.is_negative, merged_instances
        )

        return merged_instances, conflicts

    def _merge_annotations(
        self,
        other: "LabeledFrame",
        strategy: str = "keep_both",
        threshold: float = 5.0,
    ):
        """Merge annotation lists from another frame into this frame.

        Shallow-copies annotations from the other frame to avoid mutating the
        source when references are later remapped. Video and track references
        are preserved so that ``_remap_frame_annotations`` can find them in
        the mapping dicts.

        Args:
            other: The frame to merge annotations from.
            strategy: The merge strategy, matching the ``frame`` parameter of
                ``merge()``. Controls which annotations are kept:

                - ``"keep_original"``: Keep self only.
                - ``"keep_new"``: Replace with other's annotations.
                - ``"keep_both"``: Keep self + add other's (default).
                - ``"replace_predictions"``: Keep user from self, replace
                  predicted with other's predicted.
                - ``"auto"``: Spatial matching + user-vs-predicted resolution
                  cascade (mirrors instance auto-merge logic).
                - ``"update_tracks"``: Spatial matching, then update track
                  assignments on matched self annotations.
            threshold: Maximum centroid distance (pixels) for spatial matching
                in ``"auto"`` and ``"update_tracks"`` strategies.
        """
        attrs = ("centroids", "bboxes", "masks", "label_images", "rois")

        if strategy == "keep_original":
            return

        if strategy == "keep_new":
            for attr in attrs:
                memo: dict[int, Any] = {}
                new_list = [
                    _copy_with_memo(item, memo) for item in getattr(other, attr)
                ]
                _relink_from_predicted(new_list, memo)
                setattr(self, attr, new_list)
            return

        if strategy == "replace_predictions":
            for attr in attrs:
                memo = {}
                kept = [a for a in getattr(self, attr) if not a.is_predicted]
                for item in getattr(other, attr):
                    if item.is_predicted:
                        kept.append(_copy_with_memo(item, memo))
                _relink_from_predicted(kept, memo)
                setattr(self, attr, kept)
            return

        if strategy == "auto":
            for attr in attrs:
                setattr(
                    self,
                    attr,
                    _resolve_annotation_auto(
                        getattr(self, attr), getattr(other, attr), attr, threshold
                    ),
                )
            return

        if strategy == "update_tracks":
            for attr in attrs:
                _resolve_annotation_update_tracks(
                    getattr(self, attr), getattr(other, attr), attr, threshold
                )
            return

        # "keep_both" (default)
        for attr in attrs:
            memo = {}
            target = getattr(self, attr)
            existing_ids = set(id(x) for x in target)
            for item in getattr(other, attr):
                if id(item) not in existing_ids:
                    target.append(_copy_with_memo(item, memo))
            _relink_from_predicted(target, memo)

`annotations = {'video': 'Video', 'frame_idx': 'int', 'instances': 'list[Instance | PredictedInstance]', 'is_negative': 'bool', 'centroids': "'list[Centroid]'", 'bboxes': "'list[BoundingBox]'", 'masks': "'list[SegmentationMask]'", 'label_images': "'list[LabelImage]'", 'rois': "'list[ROI]'"}` `class-attribute` ¶

dict() -> new empty dictionary dict(mapping) -> new dictionary initialized from a mapping object's (key, value) pairs dict(iterable) -> new dictionary initialized as if via: d = {} for k, v in iterable: d[k] = v dict(**kwargs) -> new dictionary initialized with the name=value pairs in the keyword argument list. For example: dict(one=1, two=2)

`__attrs_own_setattr__ = True` `class-attribute` ¶

Returns True when the argument is true, False otherwise. The builtins True and False are the only two instances of the class bool. The class bool is a subclass of the class int, and cannot be subclassed.

`__attrs_props__ = ClassProps(is_exception=False, is_slotted=True, has_weakref_slot=True, is_frozen=False, kw_only=<KeywordOnly.NO: 'no'>, collected_fields_by_mro=True, added_init=True, added_repr=True, added_eq=False, added_ordering=False, hashability=<Hashability.LEAVE_ALONE: 'leave_alone'>, added_match_args=True, added_str=False, added_pickling=True, on_setattr_hook=<function pipe.<locals>.wrapped_pipe at 0x7f08471ce840>, field_transformer=None)` `class-attribute` ¶

Effective class properties as derived from parameters to attr.s() or define() decorators.

This is the same data structure that attrs uses internally to decide how to construct the final class.

Warning:

This feature is currently **experimental** and is not covered by our
strict backwards-compatibility guarantees.

Attributes:

Name	Type	Description
`is_exception`	`bool`	Whether the class is treated as an exception class.
`is_slotted`	`bool`	Whether the class is `slotted <slotted classes>`.
`has_weakref_slot`	`bool`	Whether the class has a slot for weak references.
`is_frozen`	`bool`	Whether the class is frozen.
`kw_only`	`KeywordOnly`	Whether / how the class enforces keyword-only arguments on the `__init__` method.
`collected_fields_by_mro`	`bool`	Whether the class fields were collected by method resolution order. That is, correctly but unlike `dataclasses`.
`added_init`	`bool`	Whether the class has an attrs-generated `__init__` method.
`added_repr`	`bool`	Whether the class has an attrs-generated `__repr__` method.
`added_eq`	`bool`	Whether the class has attrs-generated equality methods.
`added_ordering`	`bool`	Whether the class has attrs-generated ordering methods.
`hashability`	`Hashability`	How `hashable <hashing>` the class is.
`added_match_args`	`bool`	Whether the class supports positional `match <match>` over its fields.
`added_str`	`bool`	Whether the class has an attrs-generated `__str__` method.
`added_pickling`	`bool`	Whether the class has attrs-generated `__getstate__` and `__setstate__` methods for `pickle`.
`on_setattr_hook`	`Callable[[Any, Attribute[Any], Any], Any] \| None`	The class's `__setattr__` hook.
`field_transformer`	`Callable[[Attribute[Any]], Attribute[Any]] \| None`	The class's `field transformers <transform-fields>`.

.. versionadded:: 25.4.0

doc = 'Labeled data for a single frame of a video.\n\nAttributes:\n video: The `Video` associated with this `LabeledFrame`.\n frame_idx: The index of the `LabeledFrame` in the `Video`.\n instances: List of `Instance` objects associated with this `LabeledFrame`.\n is_negative: If True, this frame is explicitly marked as containing no\n instances (a "negative" or background frame for training). This is\n distinct from frames that are simply empty (e.g., instances were deleted).\n centroids: List of `Centroid` annotations for this frame.\n bboxes: List of `BoundingBox` annotations for this frame.\n masks: List of `SegmentationMask` annotations for this frame.\n label_images: List of `LabelImage` annotations for this frame.\n rois: List of `ROI` annotations for this frame.\n\nNotes:\n Instances of this class are hashed by identity, not by value. This means that\n two `LabeledFrame` instances with the same attributes will NOT be considered\n equal in a set or dict.\n' `class-attribute` ¶

str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.str() (if defined) or repr(object). encoding defaults to 'utf-8'. errors defaults to 'strict'.

`firstlineno = 329` `class-attribute` ¶

int([x]) -> integer int(x, base=10) -> integer

Convert a number or string to an integer, or return 0 if no arguments are given. If x is a number, return x.int(). For floating-point numbers, this truncates towards zero.

If x is not a number or if base is given, then x must be a string, bytes, or bytearray instance representing an integer literal in the given base. The literal can be preceded by '+' or '-' and be surrounded by whitespace. The base defaults to 10. Valid bases are 0 and 2-36. Base 0 means to interpret the base from the string as an integer iteral.

`__match_args__ = ('video', 'frame_idx', 'instances', 'is_negative', 'centroids', 'bboxes', 'masks', 'label_images', 'rois')` `class-attribute` ¶

Built-in immutable sequence.

If no argument is given, the constructor returns an empty tuple. If iterable is specified the tuple is initialized from iterable's items.

If the argument is a tuple, the return value is the same object.

`module = 'sleap_io.model.labeled_frame'` `class-attribute` ¶

str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.str() (if defined) or repr(object). encoding defaults to 'utf-8'. errors defaults to 'strict'.

`slots = ('video', 'frame_idx', 'instances', 'is_negative', 'centroids', 'bboxes', 'masks', 'label_images', 'rois', 'weakref')` `class-attribute` ¶

Built-in immutable sequence.

If no argument is given, the constructor returns an empty tuple. If iterable is specified the tuple is initialized from iterable's items.

If the argument is a tuple, the return value is the same object.

`__static_attributes__ = ('bboxes', 'centroids', 'instances', 'is_negative', 'label_images', 'masks', 'rois')` `class-attribute` ¶

Built-in immutable sequence.

If no argument is given, the constructor returns an empty tuple. If iterable is specified the tuple is initialized from iterable's items.

If the argument is a tuple, the return value is the same object.

`weakref` `property` ¶

list of weak references to the object

`has_predicted_instances` `property` ¶

Return True if the frame has any predicted instances.

`has_user_instances` `property` ¶

Return True if the frame has any user-labeled instances.

`image` `property` ¶

Return the image of the frame as a numpy array.

`is_user_labeled` `property` ¶

Return True if frame has user instances/annotations OR is negative.

This property indicates whether the frame represents intentional user annotation, either through labeled instances, user annotations (centroids, bboxes, ROIs, masks, label images), or explicit marking as a negative/background frame.

`predicted_instances` `property` ¶

Frame instances that are predicted by a model (PredictedInstance).

`unused_predicted_masks` `property` ¶

Return predicted masks in this frame not yet adopted by a user mask.

A PredictedSegmentationMask is considered adopted (and so excluded from the result) when some UserSegmentationMask in the same frame either links to it via from_predicted (checked first) or, lacking an explicit link, spatially overlaps it (bbox-centroid distance within 5 px, the auto-merge default). This mirrors the link-first, spatial-fallback precedence used by the auto-merge cascade and supports the "retrain only what a human corrected" workflow.

This is the segmentation-mask analogue of unused_predictions (which covers PredictedInstance objects).

Returns:

Type	Description
	The `PredictedSegmentationMask` objects with no adopting user mask.

`unused_predictions` `property` ¶

Return a list of "unused" PredictedInstance objects in frame.

This is all of the PredictedInstance objects which do not have a corresponding Instance in the same track in the same frame.

`user_instances` `property` ¶

Frame instances that are user-labeled (Instance objects).

`getitem(key)` ¶

Return the Instance at key index in the instances list.

Source code in sleap_io/model/labeled_frame.py

def __getitem__(self, key: int) -> Instance | PredictedInstance:
    """Return the `Instance` at `key` index in the `instances` list."""
    return self.instances[key]

`init(video, frame_idx, instances=NOTHING, is_negative=False, centroids=NOTHING, bboxes=NOTHING, masks=NOTHING, label_images=NOTHING, rois=NOTHING)` ¶

Method generated by attrs for class LabeledFrame.

Source code in sleap_io/model/labeled_frame.py

from sleap_io.model.instance import Instance, PredictedInstance
from sleap_io.model.video import Video

if TYPE_CHECKING:
    from sleap_io.model.bbox import BoundingBox
    from sleap_io.model.centroid import Centroid
    from sleap_io.model.label_image import LabelImage
    from sleap_io.model.mask import SegmentationMask
    from sleap_io.model.matching import InstanceMatcher
    from sleap_io.model.roi import ROI


def _annotation_centroid_xy(annotation: Any, attr: str) -> tuple[float, float] | None:
    """Extract centroid (x, y) from an annotation based on its modality.

    Args:
        annotation: An annotation object (Centroid, BoundingBox, etc.).
        attr: The attribute name indicating the modality.

    Returns:
        A tuple of (x, y) coordinates, or ``None`` if the centroid cannot be
        computed (e.g., empty mask or empty ROI geometry).
    """
    if attr == "centroids":
        return (annotation.x, annotation.y)
    elif attr == "bboxes":
        return annotation.centroid_xy
    elif attr == "rois":
        if annotation.geometry.is_empty:

`iter()` ¶

Iterate over Instances in instances list.

Source code in sleap_io/model/labeled_frame.py

def __iter__(self):
    """Iterate over `Instance`s in `instances` list."""
    return iter(self.instances)

`len()` ¶

Return the number of instances in the frame.

Source code in sleap_io/model/labeled_frame.py

def __len__(self) -> int:
    """Return the number of instances in the frame."""
    return len(self.instances)

`repr()` ¶

Method generated by attrs for class LabeledFrame.

Source code in sleap_io/model/labeled_frame.py

"""Data structures for data contained within a single video frame.

The `LabeledFrame` class is a data structure that contains `Instance`s and
`PredictedInstance`s that are associated with a single frame within a video.
"""

from __future__ import annotations

import math
from copy import copy
from typing import TYPE_CHECKING, Any

import numpy as np
from attrs import define, field

`setattr(name, val)` ¶

Method generated by attrs for class LabeledFrame.

`append(annotation)` ¶

Append an annotation to the appropriate frame-level container.

Routes the annotation to the correct list based on its type: Instance/PredictedInstance → instances, Centroid → centroids, BoundingBox → bboxes, SegmentationMask → masks, LabelImage → label_images, ROI → rois.

Parameters:

Name	Type	Description	Default
`annotation`	`Instance \| PredictedInstance \| Centroid \| BoundingBox \| SegmentationMask \| LabelImage \| ROI`	The annotation object to add.	required

Raises:

Type	Description
`TypeError`	If the annotation type is not recognized.

Source code in sleap_io/model/labeled_frame.py

def append(
    self,
    annotation: (
        "Instance | PredictedInstance | Centroid"
        " | BoundingBox | SegmentationMask | LabelImage | ROI"
    ),
) -> None:
    """Append an annotation to the appropriate frame-level container.

    Routes the annotation to the correct list based on its type:
    ``Instance``/``PredictedInstance`` → ``instances``,
    ``Centroid`` → ``centroids``, ``BoundingBox`` → ``bboxes``,
    ``SegmentationMask`` → ``masks``, ``LabelImage`` → ``label_images``,
    ``ROI`` → ``rois``.

    Args:
        annotation: The annotation object to add.

    Raises:
        TypeError: If the annotation type is not recognized.
    """
    from sleap_io.model.bbox import BoundingBox
    from sleap_io.model.centroid import Centroid
    from sleap_io.model.label_image import LabelImage
    from sleap_io.model.mask import SegmentationMask
    from sleap_io.model.roi import ROI

    if isinstance(annotation, (Instance, PredictedInstance)):
        self.instances.append(annotation)
    elif isinstance(annotation, Centroid):
        self.centroids.append(annotation)
    elif isinstance(annotation, BoundingBox):
        self.bboxes.append(annotation)
    elif isinstance(annotation, SegmentationMask):
        self.masks.append(annotation)
    elif isinstance(annotation, LabelImage):
        self.label_images.append(annotation)
    elif isinstance(annotation, ROI):
        self.rois.append(annotation)
    else:
        raise TypeError(
            f"Cannot append {type(annotation).__name__} to LabeledFrame. "
            f"Expected one of: Instance, PredictedInstance, Centroid, "
            f"BoundingBox, SegmentationMask, LabelImage, ROI."
        )

`convert(to, source='pose', inplace=False, **kwargs)` ¶

Convert annotations between detection modalities.

Reads every annotation of the source modality from this frame and converts each one to the to modality by dispatching to the matching per-object verb (to_centroid, to_bbox, to_mask, to_roi or to_pose). Keyword arguments are forwarded unchanged to the per-object verb (e.g. height/width for to="mask").

Parameters:

Name	Type	Description	Default
`to`	`str`	Target modality, one of `"pose"`, `"centroid"`, `"bbox"`, `"mask"` or `"roi"`.	required
`source`	`str`	Source modality, one of `"pose"`, `"centroid"`, `"bbox"`, `"mask"` or `"roi"`. Reads from the matching frame list (`instances`, `centroids`, `bboxes`, `masks` or `rois`).	`'pose'`
`inplace`	`bool`	If `True`, append each produced annotation to this frame (via `append`) in addition to returning them. If `False` (default), the frame is left unmodified.	`False`
`**kwargs`		Forwarded to the per-object conversion verb.	required

Returns:

Type	Description
`list`	A list of the produced annotations (one per source annotation), of the `to` modality.

Raises:

Type	Description
`ValueError`	If `to` or `source` is not a recognized modality, if `to="pose"` is requested from a non-centroid source (only `centroid` → `pose` is defined), or if a source annotation lacks the target conversion verb.

Source code in sleap_io/model/labeled_frame.py

def convert(
    self,
    to: str,
    source: str = "pose",
    inplace: bool = False,
    **kwargs,
) -> list:
    """Convert annotations between detection modalities.

    Reads every annotation of the ``source`` modality from this frame and
    converts each one to the ``to`` modality by dispatching to the matching
    per-object verb (``to_centroid``, ``to_bbox``, ``to_mask``, ``to_roi`` or
    ``to_pose``). Keyword arguments are forwarded unchanged to the per-object
    verb (e.g. ``height``/``width`` for ``to="mask"``).

    Args:
        to: Target modality, one of ``"pose"``, ``"centroid"``, ``"bbox"``,
            ``"mask"`` or ``"roi"``.
        source: Source modality, one of ``"pose"``, ``"centroid"``, ``"bbox"``,
            ``"mask"`` or ``"roi"``. Reads from the matching frame list
            (``instances``, ``centroids``, ``bboxes``, ``masks`` or ``rois``).
        inplace: If ``True``, append each produced annotation to this frame
            (via `append`) in addition to returning them. If ``False``
            (default), the frame is left unmodified.
        **kwargs: Forwarded to the per-object conversion verb.

    Returns:
        A list of the produced annotations (one per source annotation), of the
        ``to`` modality.

    Raises:
        ValueError: If ``to`` or ``source`` is not a recognized modality, if
            ``to="pose"`` is requested from a non-centroid source (only
            ``centroid`` → ``pose`` is defined), or if a source annotation
            lacks the target conversion verb.
    """
    modalities = {
        "pose": "instances",
        "centroid": "centroids",
        "bbox": "bboxes",
        "mask": "masks",
        "roi": "rois",
    }
    if to not in modalities:
        raise ValueError(
            f"Unknown target modality {to!r}. Expected one of: "
            f"{', '.join(modalities)}."
        )
    if source not in modalities:
        raise ValueError(
            f"Unknown source modality {source!r}. Expected one of: "
            f"{', '.join(modalities)}."
        )
    if to == "pose" and source != "centroid":
        raise ValueError(
            f"Conversion from {source!r} to 'pose' is not supported; only "
            "'centroid' -> 'pose' is defined."
        )

    verb = "to_pose" if to == "pose" else f"to_{to}"
    sources = getattr(self, modalities[source])

    results = []
    for obj in sources:
        method = getattr(obj, verb, None)
        if method is None:
            raise ValueError(
                f"Cannot convert {source!r} to {to!r}: "
                f"{type(obj).__name__} has no {verb}() method."
            )
        result = method(**kwargs)
        results.append(result)
        if inplace:
            self.append(result)
    return results

`matches(other, video_must_match=True)` ¶

Check if this frame matches another frame's identity.

Parameters:

Name	Type	Description	Default
`other`	`LabeledFrame`	Another LabeledFrame to compare with.	required
`video_must_match`	`bool`	If True, frames must be from the same video. If False, only frame index needs to match.	`True`

Returns:

Type	Description
`bool`	True if the frames have the same identity, False otherwise.

Notes

Frame identity is determined by video and frame index. This does not compare the instances within the frame.

Source code in sleap_io/model/labeled_frame.py

def matches(self, other: "LabeledFrame", video_must_match: bool = True) -> bool:
    """Check if this frame matches another frame's identity.

    Args:
        other: Another LabeledFrame to compare with.
        video_must_match: If True, frames must be from the same video.
            If False, only frame index needs to match.

    Returns:
        True if the frames have the same identity, False otherwise.

    Notes:
        Frame identity is determined by video and frame index.
        This does not compare the instances within the frame.
    """
    if self.frame_idx != other.frame_idx:
        return False

    if video_must_match:
        # Check if videos are the same object
        if self.video is other.video:
            return True
        # Check if videos have matching paths
        return self.video.matches_path(other.video, strict=False)

    return True

`merge(other, instance=None, frame='auto')` ¶

Merge instances from another frame into this frame.

Parameters:

Name	Type	Description	Default
`other`	`LabeledFrame`	Another LabeledFrame to merge instances from.	required
`instance`	`InstanceMatcher \| None`	Matcher to use for finding duplicate instances. If None, uses default spatial matching with 5px tolerance.	`None`
`frame`	`str`	Merge strategy: - "auto": Keep user labels, update predictions only if no user label - "keep_original": Keep all original instances, ignore new ones - "keep_new": Replace with new instances - "keep_both": Keep all instances from both frames - "update_tracks": Update track and score of the original instances from the new instances. - "replace_predictions": Keep all user instances from original frame, remove all predictions from original frame, add only predictions from the incoming frame. No spatial matching is performed.	`'auto'`

Returns:

Type	Description
`tuple[list[Instance], list[tuple[Instance, Instance, str]]]`	A tuple of (merged_instances, conflicts) where: - merged_instances: List of instances after merging - conflicts: List of (original, new, resolution) tuples for conflicts

Notes

The merged instance list is returned (not assigned back) so the caller can decide what to do with it. Frame-level annotations (centroids, bboxes, masks, label images, rois) and the is_negative flag are updated on this frame in place.

Source code in sleap_io/model/labeled_frame.py

def merge(
    self,
    other: "LabeledFrame",
    instance: "InstanceMatcher | None" = None,
    frame: str = "auto",
) -> tuple[list[Instance], list[tuple[Instance, Instance, str]]]:
    """Merge instances from another frame into this frame.

    Args:
        other: Another LabeledFrame to merge instances from.
        instance: Matcher to use for finding duplicate instances.
            If None, uses default spatial matching with 5px tolerance.
        frame: Merge strategy:
            - "auto": Keep user labels, update predictions only if no user label
            - "keep_original": Keep all original instances, ignore new ones
            - "keep_new": Replace with new instances
            - "keep_both": Keep all instances from both frames
            - "update_tracks": Update track and score of the original instances
                from the new instances.
            - "replace_predictions": Keep all user instances from original frame,
                remove all predictions from original frame, add only predictions
                from the incoming frame. No spatial matching is performed.

    Returns:
        A tuple of (merged_instances, conflicts) where:
        - merged_instances: List of instances after merging
        - conflicts: List of (original, new, resolution) tuples for conflicts

    Notes:
        The merged instance list is returned (not assigned back) so the
        caller can decide what to do with it. Frame-level annotations
        (centroids, bboxes, masks, label images, rois) and the
        ``is_negative`` flag are updated on this frame in place.
    """
    from sleap_io.model.matching import InstanceMatcher, InstanceMatchMethod

    if instance is None:
        instance_matcher = InstanceMatcher(
            method=InstanceMatchMethod.SPATIAL, threshold=5.0
        )
    else:
        instance_matcher = instance

    conflicts = []

    if frame == "keep_original":
        self._merge_annotations(other, strategy="keep_original")
        self.is_negative, _ = _resolve_merged_is_negative(
            self.is_negative, other.is_negative, self.instances
        )
        return self.instances.copy(), conflicts
    elif frame == "keep_new":
        self._merge_annotations(other, strategy="keep_new")
        self.is_negative, _ = _resolve_merged_is_negative(
            self.is_negative, other.is_negative, other.instances
        )
        return other.instances.copy(), conflicts
    elif frame == "keep_both":
        self._merge_annotations(other, strategy="keep_both")
        self.is_negative, _ = _resolve_merged_is_negative(
            self.is_negative, other.is_negative, self.instances + other.instances
        )
        return self.instances + other.instances, conflicts
    elif frame == "update_tracks":
        # match instances and update .track and tracking score of the old instances
        matches = instance_matcher.find_matches(self.instances, other.instances)
        for self_idx, other_idx, score in matches:
            self.instances[self_idx].track = other.instances[other_idx].track
            self.instances[self_idx].tracking_score = other.instances[
                other_idx
            ].tracking_score
        self._merge_annotations(
            other,
            strategy="update_tracks",
            threshold=instance_matcher.threshold,
        )
        self.is_negative, _ = _resolve_merged_is_negative(
            self.is_negative, other.is_negative, self.instances
        )
        return self.instances, conflicts
    elif frame == "replace_predictions":
        # Keep all user instances from original frame
        merged = [inst for inst in self.instances if type(inst) is Instance]
        # Add only predictions from incoming frame (not user instances)
        merged.extend(
            inst for inst in other.instances if type(inst) is PredictedInstance
        )
        self._merge_annotations(other, strategy="replace_predictions")
        self.is_negative, _ = _resolve_merged_is_negative(
            self.is_negative, other.is_negative, merged
        )
        # No instance conflicts to report - this is a clean replacement
        return merged, []

    # Auto merging strategy
    merged_instances = []
    used_indices = set()

    # First, keep all user instances from self
    for inst in self.instances:
        if type(inst) is Instance:
            merged_instances.append(inst)

    # Find matches between instances
    matches = instance_matcher.find_matches(self.instances, other.instances)

    # Group matches by instance in other frame
    other_to_self = {}
    for self_idx, other_idx, score in matches:
        if other_idx not in other_to_self or score > other_to_self[other_idx][1]:
            other_to_self[other_idx] = (self_idx, score)

    # Process instances from other frame
    for other_idx, other_inst in enumerate(other.instances):
        if other_idx in other_to_self:
            self_idx, score = other_to_self[other_idx]
            self_inst = self.instances[self_idx]

            # Check for conflicts
            if type(self_inst) is Instance and type(other_inst) is Instance:
                # Both are user instances - conflict
                conflicts.append((self_inst, other_inst, "kept_original"))
                used_indices.add(self_idx)
            elif (
                type(self_inst) is PredictedInstance
                and type(other_inst) is Instance
            ):
                # Replace prediction with user instance
                if self_idx not in used_indices:
                    merged_instances.append(other_inst)
                    used_indices.add(self_idx)
            elif (
                type(self_inst) is Instance
                and type(other_inst) is PredictedInstance
            ):
                # Keep user instance, ignore prediction
                conflicts.append((self_inst, other_inst, "kept_user"))
                used_indices.add(self_idx)
            else:
                # Both are predictions - keep the new one
                if self_idx not in used_indices:
                    merged_instances.append(other_inst)
                    used_indices.add(self_idx)
        else:
            # No match found, add new instance
            merged_instances.append(other_inst)

    # Add remaining instances from self that weren't matched
    for self_idx, self_inst in enumerate(self.instances):
        if type(self_inst) is PredictedInstance and self_idx not in used_indices:
            # Check if this prediction should be kept
            # NOTE: This defensive logic should be unreachable under normal
            # circumstances since all matched instances should have been added to
            # used_indices above. However, we keep this as a safety net for edge
            # cases or future changes.
            keep = True
            for other_idx, (matched_self_idx, _) in other_to_self.items():
                if matched_self_idx == self_idx:
                    keep = False
                    break
            if keep:
                merged_instances.append(self_inst)

    # Merge annotations from the other frame (spatial matching + resolution)
    self._merge_annotations(
        other, strategy="auto", threshold=instance_matcher.threshold
    )

    self.is_negative, _ = _resolve_merged_is_negative(
        self.is_negative, other.is_negative, merged_instances
    )

    return merged_instances, conflicts

`numpy()` ¶

Return all instances in the frame as a numpy array.

Returns:

Type	Description
`ndarray`	Points as a numpy array of shape `(n_instances, n_nodes, 2)`. Note that the order of the instances is arbitrary.

Source code in sleap_io/model/labeled_frame.py

def numpy(self) -> np.ndarray:
    """Return all instances in the frame as a numpy array.

    Returns:
        Points as a numpy array of shape `(n_instances, n_nodes, 2)`.

        Note that the order of the instances is arbitrary.
    """
    n_instances = len(self.instances)
    n_nodes = len(self.instances[0]) if n_instances > 0 else 0
    pts = np.full((n_instances, n_nodes, 2), np.nan)
    for i, inst in enumerate(self.instances):
        pts[i] = inst.numpy()[:, 0:2]
    return pts

`remove_empty_instances()` ¶

Remove all instances with no visible points.

Source code in sleap_io/model/labeled_frame.py

def remove_empty_instances(self):
    """Remove all instances with no visible points."""
    self.instances = [inst for inst in self.instances if not inst.is_empty]

`remove_predictions()` ¶

Remove all predicted instances and annotations from the frame.

Source code in sleap_io/model/labeled_frame.py

def remove_predictions(self):
    """Remove all predicted instances and annotations from the frame."""
    from sleap_io.model.bbox import PredictedBoundingBox
    from sleap_io.model.centroid import PredictedCentroid
    from sleap_io.model.label_image import PredictedLabelImage
    from sleap_io.model.mask import PredictedSegmentationMask
    from sleap_io.model.roi import PredictedROI

    self.instances = [inst for inst in self.instances if type(inst) is Instance]
    self.centroids = [
        c for c in self.centroids if not isinstance(c, PredictedCentroid)
    ]
    self.bboxes = [
        b for b in self.bboxes if not isinstance(b, PredictedBoundingBox)
    ]
    self.masks = [
        m for m in self.masks if not isinstance(m, PredictedSegmentationMask)
    ]
    self.label_images = [
        li for li in self.label_images if not isinstance(li, PredictedLabelImage)
    ]
    self.rois = [r for r in self.rois if not isinstance(r, PredictedROI)]

`similarity_to(other)` ¶

Calculate instance overlap metrics with another frame.

Parameters:

Name	Type	Description	Default
`other`	`LabeledFrame`	Another LabeledFrame to compare with.	required

Returns:

Type Description

dict[str, any]

A dictionary with similarity metrics: - 'n_user_self': Number of user instances in this frame - 'n_user_other': Number of user instances in the other frame - 'n_pred_self': Number of predicted instances in this frame - 'n_pred_other': Number of predicted instances in the other frame - 'n_overlapping': Number of instances that overlap (by IoU) - 'mean_pose_distance': Mean distance between matching poses

Source code in sleap_io/model/labeled_frame.py

def similarity_to(self, other: "LabeledFrame") -> dict[str, any]:
    """Calculate instance overlap metrics with another frame.

    Args:
        other: Another LabeledFrame to compare with.

    Returns:
        A dictionary with similarity metrics:
        - 'n_user_self': Number of user instances in this frame
        - 'n_user_other': Number of user instances in the other frame
        - 'n_pred_self': Number of predicted instances in this frame
        - 'n_pred_other': Number of predicted instances in the other frame
        - 'n_overlapping': Number of instances that overlap (by IoU)
        - 'mean_pose_distance': Mean distance between matching poses
    """
    metrics = {
        "n_user_self": len(self.user_instances),
        "n_user_other": len(other.user_instances),
        "n_pred_self": len(self.predicted_instances),
        "n_pred_other": len(other.predicted_instances),
        "n_overlapping": 0,
        "mean_pose_distance": None,
    }

    # Count overlapping instances and compute pose distances
    pose_distances = []
    for inst1 in self.instances:
        for inst2 in other.instances:
            # Check if instances overlap
            if inst1.overlaps_with(inst2, iou_threshold=0.1):
                metrics["n_overlapping"] += 1

                # If they have the same skeleton, compute pose distance
                if inst1.skeleton.matches(inst2.skeleton):
                    # Get visible points for both
                    pts1 = inst1.numpy()
                    pts2 = inst2.numpy()

                    # Compute distances for visible points in both
                    valid = ~(np.isnan(pts1[:, 0]) | np.isnan(pts2[:, 0]))
                    if valid.any():
                        distances = np.linalg.norm(
                            pts1[valid] - pts2[valid], axis=1
                        )
                        pose_distances.extend(distances.tolist())

    if pose_distances:
        metrics["mean_pose_distance"] = np.mean(pose_distances)

    return metrics

`MatchResult` ¶

Result of matching two Labels objects.

This class holds correspondence maps between items in two Labels objects, without modifying either. Useful for evaluation workflows where you need to align predictions with ground truth without merging them.

Attributes:

Name	Type	Description
`video_map`		Dictionary mapping videos from the `other` Labels to videos in `self`. Values are None if no match was found.
`skeleton_map`		Dictionary mapping skeletons from `other` to `self`.
`track_map`		Dictionary mapping tracks from `other` to `self`.

Example

Match prediction videos to ground truth for evaluation::

>>> gt_labels = sio.load_slp("ground_truth.slp")
>>> pred_labels = sio.load_slp("predictions.slp")
>>> result = gt_labels.match(pred_labels)
>>> for pred_video, gt_video in result.video_map.items():
...     if gt_video is not None:
...         print(f"{pred_video.filename} -> {gt_video.filename}")

Methods:

Name	Description
`__eq__`	Method generated by attrs for class MatchResult.
`__init__`	Method generated by attrs for class MatchResult.
`__repr__`	Method generated by attrs for class MatchResult.
`summary`	Generate a human-readable summary of the match result.

Source code in sleap_io/model/matching.py

@attrs.define
class MatchResult:
    """Result of matching two Labels objects.

    This class holds correspondence maps between items in two Labels objects,
    without modifying either. Useful for evaluation workflows where you need
    to align predictions with ground truth without merging them.

    Attributes:
        video_map: Dictionary mapping videos from the `other` Labels to videos in
            `self`. Values are None if no match was found.
        skeleton_map: Dictionary mapping skeletons from `other` to `self`.
        track_map: Dictionary mapping tracks from `other` to `self`.

    Example:
        Match prediction videos to ground truth for evaluation::

            >>> gt_labels = sio.load_slp("ground_truth.slp")
            >>> pred_labels = sio.load_slp("predictions.slp")
            >>> result = gt_labels.match(pred_labels)
            >>> for pred_video, gt_video in result.video_map.items():
            ...     if gt_video is not None:
            ...         print(f"{pred_video.filename} -> {gt_video.filename}")
    """

    video_map: dict[Video, Video | None] = attrs.field(factory=dict)
    skeleton_map: dict[Skeleton, Skeleton | None] = attrs.field(factory=dict)
    track_map: dict[Track, Track | None] = attrs.field(factory=dict)

    @property
    def unmatched_videos(self) -> list[Video]:
        """Videos from other Labels that had no match in self."""
        return [v for v, match in self.video_map.items() if match is None]

    @property
    def unmatched_skeletons(self) -> list[Skeleton]:
        """Skeletons from other Labels that had no match in self."""
        return [s for s, match in self.skeleton_map.items() if match is None]

    @property
    def unmatched_tracks(self) -> list[Track]:
        """Tracks from other Labels that had no match in self."""
        return [t for t, match in self.track_map.items() if match is None]

    @property
    def all_videos_matched(self) -> bool:
        """True if all videos from other were matched."""
        return len(self.unmatched_videos) == 0

    @property
    def all_skeletons_matched(self) -> bool:
        """True if all skeletons from other were matched."""
        return len(self.unmatched_skeletons) == 0

    @property
    def all_tracks_matched(self) -> bool:
        """True if all tracks from other were matched."""
        return len(self.unmatched_tracks) == 0

    @property
    def n_videos_matched(self) -> int:
        """Number of videos that were successfully matched."""
        return sum(1 for v in self.video_map.values() if v is not None)

    @property
    def n_skeletons_matched(self) -> int:
        """Number of skeletons that were successfully matched."""
        return sum(1 for s in self.skeleton_map.values() if s is not None)

    @property
    def n_tracks_matched(self) -> int:
        """Number of tracks that were successfully matched."""
        return sum(1 for t in self.track_map.values() if t is not None)

    def summary(self) -> str:
        """Generate a human-readable summary of the match result."""
        lines = []
        lines.append(f"Videos: {self.n_videos_matched}/{len(self.video_map)} matched")
        lines.append(
            f"Skeletons: {self.n_skeletons_matched}/{len(self.skeleton_map)} matched"
        )
        lines.append(f"Tracks: {self.n_tracks_matched}/{len(self.track_map)} matched")

        if self.unmatched_videos:
            lines.append("Unmatched videos:")
            for v in self.unmatched_videos[:5]:
                fn = v.filename if isinstance(v.filename, str) else v.filename[0]
                lines.append(f"  - {fn}")
            if len(self.unmatched_videos) > 5:
                lines.append(f"  ... and {len(self.unmatched_videos) - 5} more")

        return "\n".join(lines)

`annotations = {'video_map': 'dict[Video, Video | None]', 'skeleton_map': 'dict[Skeleton, Skeleton | None]', 'track_map': 'dict[Track, Track | None]'}` `class-attribute` ¶

dict() -> new empty dictionary dict(mapping) -> new dictionary initialized from a mapping object's (key, value) pairs dict(iterable) -> new dictionary initialized as if via: d = {} for k, v in iterable: d[k] = v dict(**kwargs) -> new dictionary initialized with the name=value pairs in the keyword argument list. For example: dict(one=1, two=2)

`__attrs_own_setattr__ = False` `class-attribute` ¶

Returns True when the argument is true, False otherwise. The builtins True and False are the only two instances of the class bool. The class bool is a subclass of the class int, and cannot be subclassed.

`__attrs_props__ = ClassProps(is_exception=False, is_slotted=True, has_weakref_slot=True, is_frozen=False, kw_only=<KeywordOnly.NO: 'no'>, collected_fields_by_mro=True, added_init=True, added_repr=True, added_eq=True, added_ordering=False, hashability=<Hashability.UNHASHABLE: 'unhashable'>, added_match_args=True, added_str=False, added_pickling=True, on_setattr_hook=<function pipe.<locals>.wrapped_pipe at 0x7f08471ce840>, field_transformer=None)` `class-attribute` ¶

Effective class properties as derived from parameters to attr.s() or define() decorators.

This is the same data structure that attrs uses internally to decide how to construct the final class.

Warning:

This feature is currently **experimental** and is not covered by our
strict backwards-compatibility guarantees.

Attributes:

Name	Type	Description
`is_exception`	`bool`	Whether the class is treated as an exception class.
`is_slotted`	`bool`	Whether the class is `slotted <slotted classes>`.
`has_weakref_slot`	`bool`	Whether the class has a slot for weak references.
`is_frozen`	`bool`	Whether the class is frozen.
`kw_only`	`KeywordOnly`	Whether / how the class enforces keyword-only arguments on the `__init__` method.
`collected_fields_by_mro`	`bool`	Whether the class fields were collected by method resolution order. That is, correctly but unlike `dataclasses`.
`added_init`	`bool`	Whether the class has an attrs-generated `__init__` method.
`added_repr`	`bool`	Whether the class has an attrs-generated `__repr__` method.
`added_eq`	`bool`	Whether the class has attrs-generated equality methods.
`added_ordering`	`bool`	Whether the class has attrs-generated ordering methods.
`hashability`	`Hashability`	How `hashable <hashing>` the class is.
`added_match_args`	`bool`	Whether the class supports positional `match <match>` over its fields.
`added_str`	`bool`	Whether the class has an attrs-generated `__str__` method.
`added_pickling`	`bool`	Whether the class has attrs-generated `__getstate__` and `__setstate__` methods for `pickle`.
`on_setattr_hook`	`Callable[[Any, Attribute[Any], Any], Any] \| None`	The class's `__setattr__` hook.
`field_transformer`	`Callable[[Attribute[Any]], Attribute[Any]] \| None`	The class's `field transformers <transform-fields>`.

.. versionadded:: 25.4.0

doc = 'Result of matching two Labels objects.\n\nThis class holds correspondence maps between items in two Labels objects,\nwithout modifying either. Useful for evaluation workflows where you need\nto align predictions with ground truth without merging them.\n\nAttributes:\n video_map: Dictionary mapping videos from the `other` Labels to videos in\n `self`. Values are None if no match was found.\n skeleton_map: Dictionary mapping skeletons from `other` to `self`.\n track_map: Dictionary mapping tracks from `other` to `self`.\n\nExample:\n Match prediction videos to ground truth for evaluation::\n\n >>> gt_labels = sio.load_slp("ground_truth.slp")\n >>> pred_labels = sio.load_slp("predictions.slp")\n >>> result = gt_labels.match(pred_labels)\n >>> for pred_video, gt_video in result.video_map.items():\n ... if gt_video is not None:\n ... print(f"{pred_video.filename} -> {gt_video.filename}")\n' `class-attribute` ¶

str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.str() (if defined) or repr(object). encoding defaults to 'utf-8'. errors defaults to 'strict'.

`firstlineno = 1416` `class-attribute` ¶

int([x]) -> integer int(x, base=10) -> integer

Convert a number or string to an integer, or return 0 if no arguments are given. If x is a number, return x.int(). For floating-point numbers, this truncates towards zero.

If x is not a number or if base is given, then x must be a string, bytes, or bytearray instance representing an integer literal in the given base. The literal can be preceded by '+' or '-' and be surrounded by whitespace. The base defaults to 10. Valid bases are 0 and 2-36. Base 0 means to interpret the base from the string as an integer iteral.

`__match_args__ = ('video_map', 'skeleton_map', 'track_map')` `class-attribute` ¶

Built-in immutable sequence.

If no argument is given, the constructor returns an empty tuple. If iterable is specified the tuple is initialized from iterable's items.

If the argument is a tuple, the return value is the same object.

`module = 'sleap_io.model.matching'` `class-attribute` ¶

str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.str() (if defined) or repr(object). encoding defaults to 'utf-8'. errors defaults to 'strict'.

`slots = ('video_map', 'skeleton_map', 'track_map', 'weakref')` `class-attribute` ¶

Built-in immutable sequence.

If no argument is given, the constructor returns an empty tuple. If iterable is specified the tuple is initialized from iterable's items.

If the argument is a tuple, the return value is the same object.

`__static_attributes__ = ()` `class-attribute` ¶

Built-in immutable sequence.

If no argument is given, the constructor returns an empty tuple. If iterable is specified the tuple is initialized from iterable's items.

If the argument is a tuple, the return value is the same object.

`weakref` `property` ¶

list of weak references to the object

`all_skeletons_matched` `property` ¶

True if all skeletons from other were matched.

`all_tracks_matched` `property` ¶

True if all tracks from other were matched.

`all_videos_matched` `property` ¶

True if all videos from other were matched.

`n_skeletons_matched` `property` ¶

Number of skeletons that were successfully matched.

`n_tracks_matched` `property` ¶

Number of tracks that were successfully matched.

`n_videos_matched` `property` ¶

Number of videos that were successfully matched.

`unmatched_skeletons` `property` ¶

Skeletons from other Labels that had no match in self.

`unmatched_tracks` `property` ¶

Tracks from other Labels that had no match in self.

`unmatched_videos` `property` ¶

Videos from other Labels that had no match in self.

`eq(other)` ¶

Method generated by attrs for class MatchResult.

Source code in sleap_io/model/matching.py

automatic strategies.
"""

from __future__ import annotations

from enum import Enum
from typing import TYPE_CHECKING, Any

`init(video_map=NOTHING, skeleton_map=NOTHING, track_map=NOTHING)` ¶

Method generated by attrs for class MatchResult.

Source code in sleap_io/model/matching.py

import attrs
import numpy as np

from sleap_io.model.category import Category
from sleap_io.model.identity import Identity
from sleap_io.model.instance import Instance, Track
from sleap_io.model.labeled_frame import LabeledFrame
from sleap_io.model.skeleton import Skeleton
from sleap_io.model.video import Video

if TYPE_CHECKING:
    from sleap_io.model.labels import Labels

`repr()` ¶

Method generated by attrs for class MatchResult.

Source code in sleap_io/model/matching.py

"""Unified matcher system for comparing and matching data structures during merging.

This module provides configurable matchers for comparing skeletons, instances, tracks,
and videos during merge operations. The matchers use various strategies to determine
when data structures should be considered equivalent during merging.

Key features:
- Skeleton matching: exact, structure-based, overlap, and subset matching
- Instance matching: spatial proximity, track identity, and bounding box IoU
- Track matching: by name or object identity
- Identity matching: by name or object identity
- Category matching: by name or object identity
- Video matching: path, basename, content, and auto matching

Video matching supports path-based, filename-based, content-based, and

`summary()` ¶

Generate a human-readable summary of the match result.

Source code in sleap_io/model/matching.py

def summary(self) -> str:
    """Generate a human-readable summary of the match result."""
    lines = []
    lines.append(f"Videos: {self.n_videos_matched}/{len(self.video_map)} matched")
    lines.append(
        f"Skeletons: {self.n_skeletons_matched}/{len(self.skeleton_map)} matched"
    )
    lines.append(f"Tracks: {self.n_tracks_matched}/{len(self.track_map)} matched")

    if self.unmatched_videos:
        lines.append("Unmatched videos:")
        for v in self.unmatched_videos[:5]:
            fn = v.filename if isinstance(v.filename, str) else v.filename[0]
            lines.append(f"  - {fn}")
        if len(self.unmatched_videos) > 5:
            lines.append(f"  ... and {len(self.unmatched_videos) - 5} more")

    return "\n".join(lines)

`MergeError` ¶

Bases: builtins.Exception

Base exception for merge errors.

Attributes:

Name	Type	Description
`message`		Human-readable error message.
`details`		Dictionary containing additional error details and context.

Methods:

Name	Description
`__init__`	Method generated by attrs for class MergeError.
`__repr__`	Method generated by attrs for class MergeError.

Source code in sleap_io/model/matching.py

@attrs.define
class MergeError(Exception):
    """Base exception for merge errors.

    Attributes:
        message: Human-readable error message.
        details: Dictionary containing additional error details and context.
    """

    message: str
    details: dict = attrs.field(factory=dict)

`annotations = {'message': 'str', 'details': 'dict'}` `class-attribute` ¶

dict() -> new empty dictionary dict(mapping) -> new dictionary initialized from a mapping object's (key, value) pairs dict(iterable) -> new dictionary initialized as if via: d = {} for k, v in iterable: d[k] = v dict(**kwargs) -> new dictionary initialized with the name=value pairs in the keyword argument list. For example: dict(one=1, two=2)

`__attrs_own_setattr__ = False` `class-attribute` ¶

Returns True when the argument is true, False otherwise. The builtins True and False are the only two instances of the class bool. The class bool is a subclass of the class int, and cannot be subclassed.

`__attrs_props__ = ClassProps(is_exception=True, is_slotted=True, has_weakref_slot=True, is_frozen=False, kw_only=<KeywordOnly.NO: 'no'>, collected_fields_by_mro=True, added_init=True, added_repr=True, added_eq=False, added_ordering=False, hashability=<Hashability.LEAVE_ALONE: 'leave_alone'>, added_match_args=True, added_str=False, added_pickling=True, on_setattr_hook=<function pipe.<locals>.wrapped_pipe at 0x7f08471ce840>, field_transformer=None)` `class-attribute` ¶

Effective class properties as derived from parameters to attr.s() or define() decorators.

This is the same data structure that attrs uses internally to decide how to construct the final class.

Warning:

This feature is currently **experimental** and is not covered by our
strict backwards-compatibility guarantees.

Attributes:

Name	Type	Description
`is_exception`	`bool`	Whether the class is treated as an exception class.
`is_slotted`	`bool`	Whether the class is `slotted <slotted classes>`.
`has_weakref_slot`	`bool`	Whether the class has a slot for weak references.
`is_frozen`	`bool`	Whether the class is frozen.
`kw_only`	`KeywordOnly`	Whether / how the class enforces keyword-only arguments on the `__init__` method.
`collected_fields_by_mro`	`bool`	Whether the class fields were collected by method resolution order. That is, correctly but unlike `dataclasses`.
`added_init`	`bool`	Whether the class has an attrs-generated `__init__` method.
`added_repr`	`bool`	Whether the class has an attrs-generated `__repr__` method.
`added_eq`	`bool`	Whether the class has attrs-generated equality methods.
`added_ordering`	`bool`	Whether the class has attrs-generated ordering methods.
`hashability`	`Hashability`	How `hashable <hashing>` the class is.
`added_match_args`	`bool`	Whether the class supports positional `match <match>` over its fields.
`added_str`	`bool`	Whether the class has an attrs-generated `__str__` method.
`added_pickling`	`bool`	Whether the class has attrs-generated `__getstate__` and `__setstate__` methods for `pickle`.
`on_setattr_hook`	`Callable[[Any, Attribute[Any], Any], Any] \| None`	The class's `__setattr__` hook.
`field_transformer`	`Callable[[Attribute[Any]], Attribute[Any]] \| None`	The class's `field transformers <transform-fields>`.

.. versionadded:: 25.4.0

`doc = 'Base exception for merge errors.\n\nAttributes:\n message: Human-readable error message.\n details: Dictionary containing additional error details and context.\n'` `class-attribute` ¶

str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.str() (if defined) or repr(object). encoding defaults to 'utf-8'. errors defaults to 'strict'.

`firstlineno = 1344` `class-attribute` ¶

int([x]) -> integer int(x, base=10) -> integer

Convert a number or string to an integer, or return 0 if no arguments are given. If x is a number, return x.int(). For floating-point numbers, this truncates towards zero.

If x is not a number or if base is given, then x must be a string, bytes, or bytearray instance representing an integer literal in the given base. The literal can be preceded by '+' or '-' and be surrounded by whitespace. The base defaults to 10. Valid bases are 0 and 2-36. Base 0 means to interpret the base from the string as an integer iteral.

`__match_args__ = ('message', 'details')` `class-attribute` ¶

Built-in immutable sequence.

If no argument is given, the constructor returns an empty tuple. If iterable is specified the tuple is initialized from iterable's items.

If the argument is a tuple, the return value is the same object.

`module = 'sleap_io.model.matching'` `class-attribute` ¶

str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.str() (if defined) or repr(object). encoding defaults to 'utf-8'. errors defaults to 'strict'.

`slots = ('message', 'details', 'weakref')` `class-attribute` ¶

Built-in immutable sequence.

If no argument is given, the constructor returns an empty tuple. If iterable is specified the tuple is initialized from iterable's items.

If the argument is a tuple, the return value is the same object.

`__static_attributes__ = ()` `class-attribute` ¶

Built-in immutable sequence.

If no argument is given, the constructor returns an empty tuple. If iterable is specified the tuple is initialized from iterable's items.

If the argument is a tuple, the return value is the same object.

`weakref` `property` ¶

list of weak references to the object

`init(message, details=NOTHING)` ¶

Method generated by attrs for class MergeError.

Source code in sleap_io/model/matching.py

automatic strategies.
"""

from __future__ import annotations

from enum import Enum
from typing import TYPE_CHECKING, Any

`repr()` ¶

Method generated by attrs for class MergeError.

Source code in sleap_io/model/matching.py

"""Unified matcher system for comparing and matching data structures during merging.

This module provides configurable matchers for comparing skeletons, instances, tracks,
and videos during merge operations. The matchers use various strategies to determine
when data structures should be considered equivalent during merging.

Key features:
- Skeleton matching: exact, structure-based, overlap, and subset matching
- Instance matching: spatial proximity, track identity, and bounding box IoU
- Track matching: by name or object identity
- Identity matching: by name or object identity
- Category matching: by name or object identity
- Video matching: path, basename, content, and auto matching

Video matching supports path-based, filename-based, content-based, and

`MergeProgressBar` ¶

Context manager for merge progress tracking using tqdm.

This provides a clean interface for tracking merge progress with visual feedback.

Example

with MergeProgressBar("Merging predictions") as progress: result = labels.merge(predictions, progress_callback=progress.callback)

Methods:

Name	Description
`__enter__`	Enter the context manager.
`__exit__`	Exit the context manager and close the progress bar.
`__init__`	Initialize the progress bar.
`callback`	Progress callback for merge operations.

Attributes:

Name	Type	Description
`__dict__`		Read-only proxy of a mapping.
`__doc__`		str(object='') -> str
`__firstlineno__`		int([x]) -> integer
`__module__`		str(object='') -> str
`__static_attributes__`		Built-in immutable sequence.
`__weakref__`		list of weak references to the object

Source code in sleap_io/model/matching.py

class MergeProgressBar:
    """Context manager for merge progress tracking using tqdm.

    This provides a clean interface for tracking merge progress with visual feedback.

    Example:
        with MergeProgressBar("Merging predictions") as progress:
            result = labels.merge(predictions, progress_callback=progress.callback)
    """

    def __init__(self, desc: str = "Merging", leave: bool = True):
        """Initialize the progress bar.

        Args:
            desc: Description to show in the progress bar.
            leave: Whether to leave the progress bar on screen after completion.
        """
        self.desc = desc
        self.leave = leave
        self.pbar = None

    def __enter__(self):
        """Enter the context manager."""
        return self

    def __exit__(self, exc_type, exc_val, exc_tb):
        """Exit the context manager and close the progress bar."""
        if self.pbar is not None:
            self.pbar.close()

    def callback(self, current: int, total: int, message: str = ""):
        """Progress callback for merge operations.

        Args:
            current: Current progress value.
            total: Total items to process.
            message: Optional message to display.
        """
        from tqdm import tqdm

        if self.pbar is None and total:
            self.pbar = tqdm(total=total, desc=self.desc, leave=self.leave)

        if self.pbar:
            if message:
                self.pbar.set_description(f"{self.desc}: {message}")
            else:
                self.pbar.set_description(self.desc)
            self.pbar.n = current
            self.pbar.refresh()

dict = mappingproxy({'module': 'sleap_io.model.matching', 'firstlineno': 1510, 'doc': 'Context manager for merge progress tracking using tqdm.\n\nThis provides a clean interface for tracking merge progress with visual feedback.\n\nExample:\n with MergeProgressBar("Merging predictions") as progress:\n result = labels.merge(predictions, progress_callback=progress.callback)\n', 'init': <function MergeProgressBar.init at 0x7f08281e1800>, 'enter': <function MergeProgressBar.enter at 0x7f08281e18a0>, 'exit': <function MergeProgressBar.exit at 0x7f08281e1ee0>, 'callback': <function MergeProgressBar.callback at 0x7f08281e2160>, '__static_attributes': ('desc', 'leave', 'pbar'), 'dict': <attribute 'dict' of 'MergeProgressBar' objects>, 'weakref': <attribute 'weakref__' of 'MergeProgressBar' objects>}) `class-attribute` ¶

Read-only proxy of a mapping.

`doc = 'Context manager for merge progress tracking using tqdm.\n\nThis provides a clean interface for tracking merge progress with visual feedback.\n\nExample:\n with MergeProgressBar("Merging predictions") as progress:\n result = labels.merge(predictions, progress_callback=progress.callback)\n'` `class-attribute` ¶

str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.str() (if defined) or repr(object). encoding defaults to 'utf-8'. errors defaults to 'strict'.

`firstlineno = 1510` `class-attribute` ¶

int([x]) -> integer int(x, base=10) -> integer

Convert a number or string to an integer, or return 0 if no arguments are given. If x is a number, return x.int(). For floating-point numbers, this truncates towards zero.

If x is not a number or if base is given, then x must be a string, bytes, or bytearray instance representing an integer literal in the given base. The literal can be preceded by '+' or '-' and be surrounded by whitespace. The base defaults to 10. Valid bases are 0 and 2-36. Base 0 means to interpret the base from the string as an integer iteral.

`module = 'sleap_io.model.matching'` `class-attribute` ¶

str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.str() (if defined) or repr(object). encoding defaults to 'utf-8'. errors defaults to 'strict'.

`__static_attributes__ = ('desc', 'leave', 'pbar')` `class-attribute` ¶

Built-in immutable sequence.

If no argument is given, the constructor returns an empty tuple. If iterable is specified the tuple is initialized from iterable's items.

If the argument is a tuple, the return value is the same object.

`weakref` `property` ¶

list of weak references to the object

`enter()` ¶

Enter the context manager.

Source code in sleap_io/model/matching.py

def __enter__(self):
    """Enter the context manager."""
    return self

`exit(exc_type, exc_val, exc_tb)` ¶

Exit the context manager and close the progress bar.

Source code in sleap_io/model/matching.py

def __exit__(self, exc_type, exc_val, exc_tb):
    """Exit the context manager and close the progress bar."""
    if self.pbar is not None:
        self.pbar.close()

`init(desc='Merging', leave=True)` ¶

Initialize the progress bar.

Parameters:

Name	Type	Description	Default
`desc`	`str`	Description to show in the progress bar.	`'Merging'`
`leave`	`bool`	Whether to leave the progress bar on screen after completion.	`True`

Source code in sleap_io/model/matching.py

def __init__(self, desc: str = "Merging", leave: bool = True):
    """Initialize the progress bar.

    Args:
        desc: Description to show in the progress bar.
        leave: Whether to leave the progress bar on screen after completion.
    """
    self.desc = desc
    self.leave = leave
    self.pbar = None

`callback(current, total, message='')` ¶

Progress callback for merge operations.

Parameters:

Name	Type	Description	Default
`current`	`int`	Current progress value.	required
`total`	`int`	Total items to process.	required
`message`	`str`	Optional message to display.	`''`

Source code in sleap_io/model/matching.py

def callback(self, current: int, total: int, message: str = ""):
    """Progress callback for merge operations.

    Args:
        current: Current progress value.
        total: Total items to process.
        message: Optional message to display.
    """
    from tqdm import tqdm

    if self.pbar is None and total:
        self.pbar = tqdm(total=total, desc=self.desc, leave=self.leave)

    if self.pbar:
        if message:
            self.pbar.set_description(f"{self.desc}: {message}")
        else:
            self.pbar.set_description(self.desc)
        self.pbar.n = current
        self.pbar.refresh()

`MergeResult` ¶

Result of a merge operation.

Attributes:

Name	Type	Description
`successful`		Whether the merge completed successfully.
`frames_merged`		Number of frames that were merged.
`instances_added`		Number of new instances added.
`instances_updated`		Number of existing instances that were updated.
`instances_skipped`		Number of instances that were skipped.
`conflicts`		List of conflicts that were resolved during merging.
`errors`		List of errors encountered during merging.

Methods:

Name	Description
`__eq__`	Method generated by attrs for class MergeResult.
`__init__`	Method generated by attrs for class MergeResult.
`__repr__`	Method generated by attrs for class MergeResult.
`summary`	Generate a human-readable summary of the merge result.

Source code in sleap_io/model/matching.py

@attrs.define
class MergeResult:
    """Result of a merge operation.

    Attributes:
        successful: Whether the merge completed successfully.
        frames_merged: Number of frames that were merged.
        instances_added: Number of new instances added.
        instances_updated: Number of existing instances that were updated.
        instances_skipped: Number of instances that were skipped.
        conflicts: List of conflicts that were resolved during merging.
        errors: List of errors encountered during merging.
    """

    successful: bool
    frames_merged: int = 0
    instances_added: int = 0
    instances_updated: int = 0
    instances_skipped: int = 0
    conflicts: list[ConflictResolution] = attrs.field(factory=list)
    errors: list[MergeError] = attrs.field(factory=list)

    def summary(self) -> str:
        """Generate a human-readable summary of the merge result."""
        lines = []

        if self.successful:
            lines.append("✓ Merge completed successfully")
        else:
            lines.append("✗ Merge completed with errors")

        lines.append(f"  Frames merged: {self.frames_merged}")
        lines.append(f"  Instances added: {self.instances_added}")

        if self.instances_updated:
            lines.append(f"  Instances updated: {self.instances_updated}")

        if self.instances_skipped:
            lines.append(f"  Instances skipped: {self.instances_skipped}")

        if self.conflicts:
            lines.append(f"  Conflicts resolved: {len(self.conflicts)}")

        if self.errors:
            lines.append(f"  Errors encountered: {len(self.errors)}")
            for error in self.errors[:5]:  # Show first 5 errors
                lines.append(f"    - {error.message}")
            if len(self.errors) > 5:
                lines.append(f"    ... and {len(self.errors) - 5} more")

        return "\n".join(lines)

`annotations = {'successful': 'bool', 'frames_merged': 'int', 'instances_added': 'int', 'instances_updated': 'int', 'instances_skipped': 'int', 'conflicts': 'list[ConflictResolution]', 'errors': 'list[MergeError]'}` `class-attribute` ¶

dict() -> new empty dictionary dict(mapping) -> new dictionary initialized from a mapping object's (key, value) pairs dict(iterable) -> new dictionary initialized as if via: d = {} for k, v in iterable: d[k] = v dict(**kwargs) -> new dictionary initialized with the name=value pairs in the keyword argument list. For example: dict(one=1, two=2)

`__attrs_own_setattr__ = False` `class-attribute` ¶

Returns True when the argument is true, False otherwise. The builtins True and False are the only two instances of the class bool. The class bool is a subclass of the class int, and cannot be subclassed.

`__attrs_props__ = ClassProps(is_exception=False, is_slotted=True, has_weakref_slot=True, is_frozen=False, kw_only=<KeywordOnly.NO: 'no'>, collected_fields_by_mro=True, added_init=True, added_repr=True, added_eq=True, added_ordering=False, hashability=<Hashability.UNHASHABLE: 'unhashable'>, added_match_args=True, added_str=False, added_pickling=True, on_setattr_hook=<function pipe.<locals>.wrapped_pipe at 0x7f08471ce840>, field_transformer=None)` `class-attribute` ¶

Effective class properties as derived from parameters to attr.s() or define() decorators.

This is the same data structure that attrs uses internally to decide how to construct the final class.

Warning:

This feature is currently **experimental** and is not covered by our
strict backwards-compatibility guarantees.

Attributes:

Name	Type	Description
`is_exception`	`bool`	Whether the class is treated as an exception class.
`is_slotted`	`bool`	Whether the class is `slotted <slotted classes>`.
`has_weakref_slot`	`bool`	Whether the class has a slot for weak references.
`is_frozen`	`bool`	Whether the class is frozen.
`kw_only`	`KeywordOnly`	Whether / how the class enforces keyword-only arguments on the `__init__` method.
`collected_fields_by_mro`	`bool`	Whether the class fields were collected by method resolution order. That is, correctly but unlike `dataclasses`.
`added_init`	`bool`	Whether the class has an attrs-generated `__init__` method.
`added_repr`	`bool`	Whether the class has an attrs-generated `__repr__` method.
`added_eq`	`bool`	Whether the class has attrs-generated equality methods.
`added_ordering`	`bool`	Whether the class has attrs-generated ordering methods.
`hashability`	`Hashability`	How `hashable <hashing>` the class is.
`added_match_args`	`bool`	Whether the class supports positional `match <match>` over its fields.
`added_str`	`bool`	Whether the class has an attrs-generated `__str__` method.
`added_pickling`	`bool`	Whether the class has attrs-generated `__getstate__` and `__setstate__` methods for `pickle`.
`on_setattr_hook`	`Callable[[Any, Attribute[Any], Any], Any] \| None`	The class's `__setattr__` hook.
`field_transformer`	`Callable[[Attribute[Any]], Attribute[Any]] \| None`	The class's `field transformers <transform-fields>`.

.. versionadded:: 25.4.0

`doc = 'Result of a merge operation.\n\nAttributes:\n successful: Whether the merge completed successfully.\n frames_merged: Number of frames that were merged.\n instances_added: Number of new instances added.\n instances_updated: Number of existing instances that were updated.\n instances_skipped: Number of instances that were skipped.\n conflicts: List of conflicts that were resolved during merging.\n errors: List of errors encountered during merging.\n'` `class-attribute` ¶

str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.str() (if defined) or repr(object). encoding defaults to 'utf-8'. errors defaults to 'strict'.

`firstlineno = 1363` `class-attribute` ¶

int([x]) -> integer int(x, base=10) -> integer

Convert a number or string to an integer, or return 0 if no arguments are given. If x is a number, return x.int(). For floating-point numbers, this truncates towards zero.

If x is not a number or if base is given, then x must be a string, bytes, or bytearray instance representing an integer literal in the given base. The literal can be preceded by '+' or '-' and be surrounded by whitespace. The base defaults to 10. Valid bases are 0 and 2-36. Base 0 means to interpret the base from the string as an integer iteral.

`__match_args__ = ('successful', 'frames_merged', 'instances_added', 'instances_updated', 'instances_skipped', 'conflicts', 'errors')` `class-attribute` ¶

Built-in immutable sequence.

If no argument is given, the constructor returns an empty tuple. If iterable is specified the tuple is initialized from iterable's items.

If the argument is a tuple, the return value is the same object.

`module = 'sleap_io.model.matching'` `class-attribute` ¶

str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.str() (if defined) or repr(object). encoding defaults to 'utf-8'. errors defaults to 'strict'.

`slots = ('successful', 'frames_merged', 'instances_added', 'instances_updated', 'instances_skipped', 'conflicts', 'errors', 'weakref')` `class-attribute` ¶

Built-in immutable sequence.

If no argument is given, the constructor returns an empty tuple. If iterable is specified the tuple is initialized from iterable's items.

If the argument is a tuple, the return value is the same object.

`__static_attributes__ = ()` `class-attribute` ¶

Built-in immutable sequence.

If no argument is given, the constructor returns an empty tuple. If iterable is specified the tuple is initialized from iterable's items.

If the argument is a tuple, the return value is the same object.

`weakref` `property` ¶

list of weak references to the object

`eq(other)` ¶

Method generated by attrs for class MergeResult.

Source code in sleap_io/model/matching.py

automatic strategies.
"""

from __future__ import annotations

from enum import Enum
from typing import TYPE_CHECKING, Any

import attrs
import numpy as np

from sleap_io.model.category import Category

`init(successful, frames_merged=0, instances_added=0, instances_updated=0, instances_skipped=0, conflicts=NOTHING, errors=NOTHING)` ¶

Method generated by attrs for class MergeResult.

Source code in sleap_io/model/matching.py

from sleap_io.model.identity import Identity
from sleap_io.model.instance import Instance, Track
from sleap_io.model.labeled_frame import LabeledFrame
from sleap_io.model.skeleton import Skeleton
from sleap_io.model.video import Video

if TYPE_CHECKING:
    from sleap_io.model.labels import Labels


class SkeletonMatchMethod(str, Enum):
    """Methods for matching skeletons.

    Attributes:

`repr()` ¶

Method generated by attrs for class MergeResult.

Source code in sleap_io/model/matching.py

"""Unified matcher system for comparing and matching data structures during merging.

This module provides configurable matchers for comparing skeletons, instances, tracks,
and videos during merge operations. The matchers use various strategies to determine
when data structures should be considered equivalent during merging.

Key features:
- Skeleton matching: exact, structure-based, overlap, and subset matching
- Instance matching: spatial proximity, track identity, and bounding box IoU
- Track matching: by name or object identity
- Identity matching: by name or object identity
- Category matching: by name or object identity
- Video matching: path, basename, content, and auto matching

Video matching supports path-based, filename-based, content-based, and

`summary()` ¶

Generate a human-readable summary of the merge result.

Source code in sleap_io/model/matching.py

def summary(self) -> str:
    """Generate a human-readable summary of the merge result."""
    lines = []

    if self.successful:
        lines.append("✓ Merge completed successfully")
    else:
        lines.append("✗ Merge completed with errors")

    lines.append(f"  Frames merged: {self.frames_merged}")
    lines.append(f"  Instances added: {self.instances_added}")

    if self.instances_updated:
        lines.append(f"  Instances updated: {self.instances_updated}")

    if self.instances_skipped:
        lines.append(f"  Instances skipped: {self.instances_skipped}")

    if self.conflicts:
        lines.append(f"  Conflicts resolved: {len(self.conflicts)}")

    if self.errors:
        lines.append(f"  Errors encountered: {len(self.errors)}")
        for error in self.errors[:5]:  # Show first 5 errors
            lines.append(f"    - {error.message}")
        if len(self.errors) > 5:
            lines.append(f"    ... and {len(self.errors) - 5} more")

    return "\n".join(lines)

`Skeleton` ¶

A description of a set of landmark types and connections between them.

Skeletons are represented by a directed graph composed of a set of Nodes (landmark types such as body parts) and Edges (connections between parts).

Attributes:

Name	Type	Description
`nodes`		A list of `Node`s. May be specified as a list of strings to create new nodes from their names.
`edges`		A list of `Edge`s. May be specified as a list of 2-tuples of string names or integer indices of `nodes`. Each edge corresponds to a pair of source and destination nodes forming a directed edge.
`symmetries`		A list of `Symmetry`s. Each symmetry corresponds to symmetric body parts, such as `"left eye", "right eye"`. This is used when applying flip (reflection) augmentation to images in order to appropriately swap the indices of symmetric landmarks.
`name`		A descriptive name for the `Skeleton`.

Methods:

Name	Description
`__attrs_post_init__`	Ensure nodes are `Node`s, edges are `Edge`s, and `Node` map is updated.
`__contains__`	Check if a node is in the skeleton.
`__getitem__`	Return a `Node` when indexing by name or integer.
`__init__`	Method generated by attrs for class Skeleton.
`__len__`	Return the number of nodes in the skeleton.
`__repr__`	Return a readable representation of the skeleton.
`__setattr__`	Method generated by attrs for class Skeleton.
`add_edge`	Add an `Edge` to the skeleton.
`add_edges`	Add multiple `Edge`s to the skeleton.
`add_node`	Add a `Node` to the skeleton.
`add_nodes`	Add multiple `Node`s to the skeleton.
`add_symmetries`	Add multiple `Symmetry` relationships to the skeleton.
`add_symmetry`	Add a symmetry relationship to the skeleton.
`get_flipped_node_inds`	Returns node indices that should be switched when horizontally flipping.
`index`	Return the index of a node specified as a `Node` or string name.
`infer_symmetries_by_name`	Infer left/right symmetric node pairs from node names.
`match_nodes`	Return the order of nodes in the skeleton.
`matches`	Check if this skeleton matches another skeleton's structure.
`node_similarities`	Calculate node overlap metrics with another skeleton.
`rebuild_cache`	Rebuild the node name/index to `Node` map caches.
`remove_node`	Remove a single node from the skeleton.
`remove_nodes`	Remove nodes from the skeleton.
`rename_node`	Rename a single node in the skeleton.
`rename_nodes`	Rename nodes in the skeleton.
`reorder_nodes`	Reorder nodes in the skeleton.
`require_node`	Return a `Node` object, handling indexing and adding missing nodes.

Source code in sleap_io/model/skeleton.py

@define(eq=False)
class Skeleton:
    """A description of a set of landmark types and connections between them.

    Skeletons are represented by a directed graph composed of a set of `Node`s (landmark
    types such as body parts) and `Edge`s (connections between parts).

    Attributes:
        nodes: A list of `Node`s. May be specified as a list of strings to create new
            nodes from their names.
        edges: A list of `Edge`s. May be specified as a list of 2-tuples of string names
            or integer indices of `nodes`. Each edge corresponds to a pair of source and
            destination nodes forming a directed edge.
        symmetries: A list of `Symmetry`s. Each symmetry corresponds to symmetric body
            parts, such as `"left eye", "right eye"`. This is used when applying flip
            (reflection) augmentation to images in order to appropriately swap the
            indices of symmetric landmarks.
        name: A descriptive name for the `Skeleton`.
    """

    def _nodes_on_setattr(self, attr, new_nodes):
        """Callback to update caches when nodes are set."""
        self.rebuild_cache(nodes=new_nodes)
        return new_nodes

    nodes: list[Node] = field(
        factory=list,
        on_setattr=_nodes_on_setattr,
    )
    edges: list[Edge] = field(factory=list)
    symmetries: list[Symmetry] = field(factory=list)
    name: str | None = None
    _name_to_node_cache: dict[str, Node] = field(init=False, repr=False, eq=False)
    _node_to_ind_cache: dict[Node, int] = field(init=False, repr=False, eq=False)

    def __attrs_post_init__(self):
        """Ensure nodes are `Node`s, edges are `Edge`s, and `Node` map is updated."""
        self._convert_nodes()
        self._convert_edges()
        self._convert_symmetries()
        self.rebuild_cache()

    def _convert_nodes(self):
        """Convert nodes to `Node` objects if needed."""
        if isinstance(self.nodes, np.ndarray):
            object.__setattr__(self, "nodes", self.nodes.tolist())
        for i, node in enumerate(self.nodes):
            if type(node) is str:
                self.nodes[i] = Node(node)

    def _convert_edges(self):
        """Convert list of edge names or integers to `Edge` objects if needed."""
        if isinstance(self.edges, np.ndarray):
            self.edges = self.edges.tolist()
        node_names = self.node_names
        for i, edge in enumerate(self.edges):
            if type(edge) is Edge:
                continue
            src, dst = edge
            if type(src) is str:
                try:
                    src = node_names.index(src)
                except ValueError:
                    raise ValueError(
                        f"Node '{src}' specified in the edge list is not in the nodes."
                    )
            if type(src) is int or (
                np.isscalar(src) and np.issubdtype(src.dtype, np.integer)
            ):
                src = self.nodes[src]

            if type(dst) is str:
                try:
                    dst = node_names.index(dst)
                except ValueError:
                    raise ValueError(
                        f"Node '{dst}' specified in the edge list is not in the nodes."
                    )
            if type(dst) is int or (
                np.isscalar(dst) and np.issubdtype(dst.dtype, np.integer)
            ):
                dst = self.nodes[dst]

            self.edges[i] = Edge(src, dst)

    def _convert_symmetries(self):
        """Convert list of symmetric node names or integers to `Symmetry` objects."""
        if isinstance(self.symmetries, np.ndarray):
            self.symmetries = self.symmetries.tolist()

        node_names = self.node_names
        for i, symmetry in enumerate(self.symmetries):
            if type(symmetry) is Symmetry:
                continue
            node1, node2 = symmetry
            if type(node1) is str:
                try:
                    node1 = node_names.index(node1)
                except ValueError:
                    raise ValueError(
                        f"Node '{node1}' specified in the symmetry list is not in the "
                        "nodes."
                    )
            if type(node1) is int or (
                np.isscalar(node1) and np.issubdtype(node1.dtype, np.integer)
            ):
                node1 = self.nodes[node1]

            if type(node2) is str:
                try:
                    node2 = node_names.index(node2)
                except ValueError:
                    raise ValueError(
                        f"Node '{node2}' specified in the symmetry list is not in the "
                        "nodes."
                    )
            if type(node2) is int or (
                np.isscalar(node2) and np.issubdtype(node2.dtype, np.integer)
            ):
                node2 = self.nodes[node2]

            self.symmetries[i] = Symmetry({node1, node2})

    def rebuild_cache(self, nodes: list[Node] | None = None):
        """Rebuild the node name/index to `Node` map caches.

        Args:
            nodes: A list of `Node` objects to update the cache with. If not provided,
                the cache will be updated with the current nodes in the skeleton. If
                nodes are provided, the cache will be updated with the provided nodes,
                but the current nodes in the skeleton will not be updated. Default is
                `None`.

        Notes:
            This function should be called when nodes or node list is mutated to update
            the lookup caches for indexing nodes by name or `Node` object.

            This is done automatically when nodes are added or removed from the skeleton
            using the convenience methods in this class.

            This method only needs to be used when manually mutating nodes or the node
            list directly.
        """
        if nodes is None:
            nodes = self.nodes
        self._name_to_node_cache = {node.name: node for node in nodes}
        self._node_to_ind_cache = {node: i for i, node in enumerate(nodes)}

    @property
    def node_names(self) -> list[str]:
        """Names of the nodes associated with this skeleton as a list of strings."""
        return [node.name for node in self.nodes]

    @property
    def edge_inds(self) -> list[tuple[int, int]]:
        """Edges indices as a list of 2-tuples."""
        return [
            (self.nodes.index(edge.source), self.nodes.index(edge.destination))
            for edge in self.edges
        ]

    @property
    def edge_names(self) -> list[str, str]:
        """Edge names as a list of 2-tuples with string node names."""
        return [(edge.source.name, edge.destination.name) for edge in self.edges]

    @property
    def symmetry_inds(self) -> list[tuple[int, int]]:
        """Symmetry indices as a list of 2-tuples."""
        return [
            tuple(sorted((self.index(symmetry[0]), self.index(symmetry[1]))))
            for symmetry in self.symmetries
        ]

    @property
    def symmetry_names(self) -> list[str, str]:
        """Symmetry names as a list of 2-tuples with string node names."""
        return [
            (self.nodes[i].name, self.nodes[j].name) for (i, j) in self.symmetry_inds
        ]

    def get_flipped_node_inds(self) -> list[int]:
        """Returns node indices that should be switched when horizontally flipping.

        This is useful as a lookup table for flipping the landmark coordinates when
        doing data augmentation.

        Example:
            >>> skel = Skeleton(["A", "B_left", "B_right", "C", "D_left", "D_right"])
            >>> skel.add_symmetry("B_left", "B_right")
            >>> skel.add_symmetry("D_left", "D_right")
            >>> skel.flipped_node_inds
            [0, 2, 1, 3, 5, 4]
            >>> pose = np.array([[0, 0], [1, 1], [2, 2], [3, 3], [4, 4], [5, 5]])
            >>> pose[skel.flipped_node_inds]
            array([[0, 0],
                   [2, 2],
                   [1, 1],
                   [3, 3],
                   [5, 5],
                   [4, 4]])
        """
        flip_idx = np.arange(len(self.nodes))
        if len(self.symmetries) > 0:
            symmetry_inds = np.array(
                [(self.index(a), self.index(b)) for a, b in self.symmetries]
            )
            flip_idx[symmetry_inds[:, 0]] = symmetry_inds[:, 1]
            flip_idx[symmetry_inds[:, 1]] = symmetry_inds[:, 0]

        flip_idx = flip_idx.tolist()
        return flip_idx

    def __len__(self) -> int:
        """Return the number of nodes in the skeleton."""
        return len(self.nodes)

    def __repr__(self) -> str:
        """Return a readable representation of the skeleton."""
        nodes = ", ".join([f'"{node}"' for node in self.node_names])
        return f"Skeleton(nodes=[{nodes}], edges={self.edge_inds})"

    def index(self, node: Node | str) -> int:
        """Return the index of a node specified as a `Node` or string name."""
        if type(node) is str:
            return self.index(self._name_to_node_cache[node])
        elif type(node) is Node:
            return self._node_to_ind_cache[node]
        else:
            raise IndexError(f"Invalid indexing argument for skeleton: {node}")

    def __getitem__(self, idx: NodeOrIndex) -> Node:
        """Return a `Node` when indexing by name or integer."""
        if type(idx) is int:
            return self.nodes[idx]
        elif type(idx) is str:
            return self._name_to_node_cache[idx]
        else:
            raise IndexError(f"Invalid indexing argument for skeleton: {idx}")

    def __contains__(self, node: NodeOrIndex) -> bool:
        """Check if a node is in the skeleton."""
        if type(node) is str:
            return node in self._name_to_node_cache
        elif type(node) is Node:
            return node in self.nodes
        elif type(node) is int:
            return 0 <= node < len(self.nodes)
        else:
            raise ValueError(f"Invalid node type for skeleton: {node}")

    def add_node(self, node: Node | str):
        """Add a `Node` to the skeleton.

        Args:
            node: A `Node` object or a string name to create a new node.

        Raises:
            ValueError: If the node already exists in the skeleton or if the node is
                not specified as a `Node` or string.
        """
        if node in self:
            raise ValueError(f"Node '{node}' already exists in the skeleton.")

        if type(node) is str:
            node = Node(node)

        if type(node) is not Node:
            raise ValueError(f"Invalid node type: {node} ({type(node)})")

        self.nodes.append(node)

        # Atomic update of the cache.
        self._name_to_node_cache[node.name] = node
        self._node_to_ind_cache[node] = len(self.nodes) - 1

    def add_nodes(self, nodes: list[Node | str]):
        """Add multiple `Node`s to the skeleton.

        Args:
            nodes: A list of `Node` objects or string names to create new nodes.
        """
        for node in nodes:
            self.add_node(node)

    def require_node(self, node: NodeOrIndex, add_missing: bool = True) -> Node:
        """Return a `Node` object, handling indexing and adding missing nodes.

        Args:
            node: A `Node` object, name or index.
            add_missing: If `True`, missing nodes will be added to the skeleton. If
                `False`, an error will be raised if the node is not found. Default is
                `True`.

        Returns:
            The `Node` object.

        Raises:
            IndexError: If the node is not found in the skeleton and `add_missing` is
                `False`.
        """
        if node not in self:
            if add_missing:
                self.add_node(node)
            else:
                raise IndexError(f"Node '{node}' not found in the skeleton.")

        if type(node) is Node:
            return node

        return self[node]

    def add_edge(
        self,
        src: NodeOrIndex | Edge | tuple[NodeOrIndex, NodeOrIndex],
        dst: NodeOrIndex | None = None,
    ):
        """Add an `Edge` to the skeleton.

        Args:
            src: The source node specified as a `Node`, name or index.
            dst: The destination node specified as a `Node`, name or index.
        """
        edge = None
        if type(src) is tuple:
            src, dst = src

        if is_node_or_index(src):
            if not is_node_or_index(dst):
                raise ValueError("Destination node must be specified.")

            src = self.require_node(src)
            dst = self.require_node(dst)
            edge = Edge(src, dst)

        if type(src) is Edge:
            edge = src

        if edge not in self.edges:
            self.edges.append(edge)

    def add_edges(self, edges: list[Edge | tuple[NodeOrIndex, NodeOrIndex]]):
        """Add multiple `Edge`s to the skeleton.

        Args:
            edges: A list of `Edge` objects or 2-tuples of source and destination nodes.
        """
        for edge in edges:
            self.add_edge(edge)

    def add_symmetry(
        self, node1: Symmetry | NodeOrIndex = None, node2: NodeOrIndex | None = None
    ):
        """Add a symmetry relationship to the skeleton.

        Args:
            node1: The first node specified as a `Node`, name or index. If a `Symmetry`
                object is provided, it will be added directly to the skeleton.
            node2: The second node specified as a `Node`, name or index.
        """
        symmetry = None
        if type(node1) is Symmetry:
            symmetry = node1
            node1, node2 = symmetry

        node1 = self.require_node(node1)
        node2 = self.require_node(node2)

        if symmetry is None:
            symmetry = Symmetry({node1, node2})

        if symmetry not in self.symmetries:
            self.symmetries.append(symmetry)

    def add_symmetries(
        self, symmetries: list[Symmetry | tuple[NodeOrIndex, NodeOrIndex]]
    ):
        """Add multiple `Symmetry` relationships to the skeleton.

        Args:
            symmetries: A list of `Symmetry` objects or 2-tuples of symmetric nodes.
        """
        for symmetry in symmetries:
            self.add_symmetry(*symmetry)

    def infer_symmetries_by_name(
        self,
        token_pairs: list[tuple[str, str]] | None = None,
    ) -> list[tuple[int, int]]:
        """Infer left/right symmetric node pairs from node names.

        Useful when a skeleton has no symmetries defined (e.g. imported from a
        format that does not carry symmetry metadata) but its node names encode
        laterality, so that flip-dependent tooling (augmentation, QC) still
        works. Names are matched by splitting on separators (`_`, `-`, `.`,
        space), camelCase boundaries, and letter/digit boundaries, then pairing
        nodes that share a stem but differ by a single left/right token. For
        example, `Ear_L`/`Ear_R`, `left_eye`/`right_eye`, `LeftPaw`/`RightPaw`,
        and `L1`/`R1` all pair up.

        This is intentionally **non-mutating** and conservative: it returns
        suggested pairs rather than writing them onto the skeleton, since a wrong
        guess would silently corrupt flip augmentation. Apply the result
        explicitly if desired, e.g.
        `skel.add_symmetries(skel.infer_symmetries_by_name())`. Node names
        without a delimited or camelCase/digit token boundary (e.g. `larm`) and
        truly non-semantic pairings (e.g. `L1`/`L2`) cannot be inferred and must
        be declared with `add_symmetry`.

        Args:
            token_pairs: List of `(left_token, right_token)` string pairs used to
                recognize laterality, matched case-insensitively against whole
                name segments. Defaults to `[("left", "right"), ("l", "r")]`.

        Returns:
            A list of `(left_index, right_index)` node-index pairs, ordered by
            left index. Each node appears in at most one pair, and only stems
            with exactly one left and one right member are paired (ambiguous
            groups are skipped).

        Example:
            >>> skel = Skeleton(["nose", "eye_L", "eye_R", "ear_L", "ear_R"])
            >>> skel.infer_symmetries_by_name()
            [(1, 2), (3, 4)]
            >>> skel.add_symmetries(skel.infer_symmetries_by_name())
            >>> skel.symmetry_names
            [('eye_L', 'eye_R'), ('ear_L', 'ear_R')]
        """
        return infer_symmetry_pairs_by_name(self.node_names, token_pairs=token_pairs)

    def rename_nodes(self, name_map: dict[NodeOrIndex, str] | list[str]):
        """Rename nodes in the skeleton.

        Args:
            name_map: A dictionary mapping old node names to new node names. Keys can be
                specified as `Node` objects, integer indices, or string names. Values
                must be specified as string names.

                If a list of strings is provided of the same length as the current
                nodes, the nodes will be renamed to the names in the list in order.

        Raises:
            ValueError: If the new node names exist in the skeleton or if the old node
                names are not found in the skeleton.

        Notes:
            This method should always be used when renaming nodes in the skeleton as it
            handles updating the lookup caches necessary for indexing nodes by name.

            After renaming, instances using this skeleton **do NOT need to be updated**
            as the nodes are stored by reference in the skeleton, so changes are
            reflected automatically.

        Example:
            >>> skel = Skeleton(["A", "B", "C"], edges=[("A", "B"), ("B", "C")])
            >>> skel.rename_nodes({"A": "X", "B": "Y", "C": "Z"})
            >>> skel.node_names
            ["X", "Y", "Z"]
            >>> skel.rename_nodes(["a", "b", "c"])
            >>> skel.node_names
            ["a", "b", "c"]
        """
        if type(name_map) is list:
            if len(name_map) != len(self.nodes):
                raise ValueError(
                    "List of new node names must be the same length as the current "
                    "nodes."
                )
            name_map = {node: name for node, name in zip(self.nodes, name_map)}

        for old_name, new_name in name_map.items():
            if type(old_name) is Node:
                old_name = old_name.name
            if type(old_name) is int:
                old_name = self.nodes[old_name].name

            if old_name not in self._name_to_node_cache:
                raise ValueError(f"Node '{old_name}' not found in the skeleton.")
            if new_name in self._name_to_node_cache:
                raise ValueError(f"Node '{new_name}' already exists in the skeleton.")

            node = self._name_to_node_cache[old_name]
            node.name = new_name
            self._name_to_node_cache[new_name] = node
            del self._name_to_node_cache[old_name]

    def rename_node(self, old_name: NodeOrIndex, new_name: str):
        """Rename a single node in the skeleton.

        Args:
            old_name: The name of the node to rename. Can also be specified as an
                integer index or `Node` object.
            new_name: The new name for the node.
        """
        self.rename_nodes({old_name: new_name})

    def remove_nodes(self, nodes: list[NodeOrIndex]):
        """Remove nodes from the skeleton.

        Args:
            nodes: A list of node names, indices, or `Node` objects to remove.

        Notes:
            This method handles updating the lookup caches necessary for indexing nodes
            by name.

            Any edges and symmetries that are connected to the removed nodes will also
            be removed.

        Warning:
            **This method does NOT update instances** that use this skeleton to reflect
            changes.

            It is recommended to use the `Labels.remove_nodes()` method which will
            update all contained to reflect the changes made to the skeleton.

            To manually update instances after this method is called, call
            `instance.update_nodes()` on each instance that uses this skeleton.
        """
        # Standardize input and make a pre-mutation copy before keys are changed.
        rm_node_objs = [self.require_node(node, add_missing=False) for node in nodes]

        # Remove nodes from the skeleton.
        for node in rm_node_objs:
            self.nodes.remove(node)
            del self._name_to_node_cache[node.name]

        # Remove edges connected to the removed nodes.
        self.edges = [
            edge
            for edge in self.edges
            if edge.source not in rm_node_objs and edge.destination not in rm_node_objs
        ]

        # Remove symmetries connected to the removed nodes.
        self.symmetries = [
            symmetry
            for symmetry in self.symmetries
            if symmetry.nodes.isdisjoint(rm_node_objs)
        ]

        # Update node index map.
        self.rebuild_cache()

    def remove_node(self, node: NodeOrIndex):
        """Remove a single node from the skeleton.

        Args:
            node: The node to remove. Can be specified as a string name, integer index,
                or `Node` object.

        Notes:
            This method handles updating the lookup caches necessary for indexing nodes
            by name.

            Any edges and symmetries that are connected to the removed node will also be
            removed.

        Warning:
            **This method does NOT update instances** that use this skeleton to reflect
            changes.

            It is recommended to use the `Labels.remove_nodes()` method which will
            update all contained instances to reflect the changes made to the skeleton.

            To manually update instances after this method is called, call
            `Instance.update_skeleton()` on each instance that uses this skeleton.
        """
        self.remove_nodes([node])

    def reorder_nodes(self, new_order: list[NodeOrIndex]):
        """Reorder nodes in the skeleton.

        Args:
            new_order: A list of node names, indices, or `Node` objects specifying the
                new order of the nodes.

        Raises:
            ValueError: If the new order of nodes is not the same length as the current
                nodes.

        Notes:
            This method handles updating the lookup caches necessary for indexing nodes
            by name.

        Warning:
            After reordering, instances using this skeleton do not need to be updated as
            the nodes are stored by reference in the skeleton.

            However, the order that points are stored in the instances will not be
            updated to match the new order of the nodes in the skeleton. This should not
            matter unless the ordering of the keys in the `Instance.points` dictionary
            is used instead of relying on the skeleton node order.

            To make sure these are aligned, it is recommended to use the
            `Labels.reorder_nodes()` method which will update all contained instances to
            reflect the changes made to the skeleton.

            To manually update instances after this method is called, call
            `Instance.update_skeleton()` on each instance that uses this skeleton.
        """
        if len(new_order) != len(self.nodes):
            raise ValueError(
                "New order of nodes must be the same length as the current nodes."
            )

        new_nodes = [self.require_node(node, add_missing=False) for node in new_order]
        self.nodes = new_nodes

    def match_nodes(self, other_nodes: list[str, Node]) -> tuple[list[int], list[int]]:
        """Return the order of nodes in the skeleton.

        Args:
            other_nodes: A list of node names or `Node` objects.

        Returns:
            A tuple of `skeleton_inds, `other_inds`.

            `skeleton_inds` contains the indices of the nodes in the skeleton that match
            the input nodes.

            `other_inds` contains the indices of the input nodes that match the nodes in
            the skeleton.

            These can be used to reorder point data to match the order of nodes in the
            skeleton.

        See also: match_nodes_cached
        """
        if isinstance(other_nodes, np.ndarray):
            other_nodes = other_nodes.tolist()
        if type(other_nodes) is not tuple:
            other_nodes = [x.name if type(x) is Node else x for x in other_nodes]

        skeleton_inds, other_inds = match_nodes_cached(
            tuple(self.node_names), tuple(other_nodes)
        )

        return list(skeleton_inds), list(other_inds)

    def matches(self, other: "Skeleton", require_same_order: bool = False) -> bool:
        """Check if this skeleton matches another skeleton's structure.

        Args:
            other: Another skeleton to compare with.
            require_same_order: If True, nodes must be in the same order.
                If False, only the node names and edges need to match.

        Returns:
            True if the skeletons match, False otherwise.

        Notes:
            Two skeletons match if they have the same nodes (by name) and edges.
            If require_same_order is True, the nodes must also be in the same order.
        """
        # Check if we have the same number of nodes
        if len(self.nodes) != len(other.nodes):
            return False

        # Check node names
        if require_same_order:
            if self.node_names != other.node_names:
                return False
        else:
            if set(self.node_names) != set(other.node_names):
                return False

        # Check edges (considering node name mapping if order differs)
        if len(self.edges) != len(other.edges):
            return False

        # Create edge sets for comparison
        self_edge_set = {
            (edge.source.name, edge.destination.name) for edge in self.edges
        }
        other_edge_set = {
            (edge.source.name, edge.destination.name) for edge in other.edges
        }

        if self_edge_set != other_edge_set:
            return False

        # Check symmetries
        if len(self.symmetries) != len(other.symmetries):
            return False

        self_sym_set = {
            frozenset(node.name for node in sym.nodes) for sym in self.symmetries
        }
        other_sym_set = {
            frozenset(node.name for node in sym.nodes) for sym in other.symmetries
        }

        return self_sym_set == other_sym_set

    def node_similarities(self, other: "Skeleton") -> dict[str, float]:
        """Calculate node overlap metrics with another skeleton.

        Args:
            other: Another skeleton to compare with.

        Returns:
            A dictionary with similarity metrics:
            - 'n_common': Number of nodes in common
            - 'n_self_only': Number of nodes only in this skeleton
            - 'n_other_only': Number of nodes only in the other skeleton
            - 'jaccard': Jaccard similarity (intersection/union)
            - 'dice': Dice coefficient (2*intersection/(n_self + n_other))
        """
        self_nodes = set(self.node_names)
        other_nodes = set(other.node_names)

        n_common = len(self_nodes & other_nodes)
        n_self_only = len(self_nodes - other_nodes)
        n_other_only = len(other_nodes - self_nodes)
        n_union = len(self_nodes | other_nodes)

        jaccard = n_common / n_union if n_union > 0 else 0
        dice = (
            2 * n_common / (len(self_nodes) + len(other_nodes))
            if (len(self_nodes) + len(other_nodes)) > 0
            else 0
        )

        return {
            "n_common": n_common,
            "n_self_only": n_self_only,
            "n_other_only": n_other_only,
            "jaccard": jaccard,
            "dice": dice,
        }

`annotations = {'nodes': 'list[Node]', 'edges': 'list[Edge]', 'symmetries': 'list[Symmetry]', 'name': 'str | None', '_name_to_node_cache': 'dict[str, Node]', '_node_to_ind_cache': 'dict[Node, int]'}` `class-attribute` ¶

dict() -> new empty dictionary dict(mapping) -> new dictionary initialized from a mapping object's (key, value) pairs dict(iterable) -> new dictionary initialized as if via: d = {} for k, v in iterable: d[k] = v dict(**kwargs) -> new dictionary initialized with the name=value pairs in the keyword argument list. For example: dict(one=1, two=2)

`__attrs_own_setattr__ = True` `class-attribute` ¶

Returns True when the argument is true, False otherwise. The builtins True and False are the only two instances of the class bool. The class bool is a subclass of the class int, and cannot be subclassed.

`__attrs_props__ = ClassProps(is_exception=False, is_slotted=True, has_weakref_slot=True, is_frozen=False, kw_only=<KeywordOnly.NO: 'no'>, collected_fields_by_mro=True, added_init=True, added_repr=False, added_eq=False, added_ordering=False, hashability=<Hashability.LEAVE_ALONE: 'leave_alone'>, added_match_args=True, added_str=False, added_pickling=True, on_setattr_hook=<function pipe.<locals>.wrapped_pipe at 0x7f08471ce840>, field_transformer=None)` `class-attribute` ¶

Effective class properties as derived from parameters to attr.s() or define() decorators.

This is the same data structure that attrs uses internally to decide how to construct the final class.

Warning:

This feature is currently **experimental** and is not covered by our
strict backwards-compatibility guarantees.

Attributes:

Name	Type	Description
`is_exception`	`bool`	Whether the class is treated as an exception class.
`is_slotted`	`bool`	Whether the class is `slotted <slotted classes>`.
`has_weakref_slot`	`bool`	Whether the class has a slot for weak references.
`is_frozen`	`bool`	Whether the class is frozen.
`kw_only`	`KeywordOnly`	Whether / how the class enforces keyword-only arguments on the `__init__` method.
`collected_fields_by_mro`	`bool`	Whether the class fields were collected by method resolution order. That is, correctly but unlike `dataclasses`.
`added_init`	`bool`	Whether the class has an attrs-generated `__init__` method.
`added_repr`	`bool`	Whether the class has an attrs-generated `__repr__` method.
`added_eq`	`bool`	Whether the class has attrs-generated equality methods.
`added_ordering`	`bool`	Whether the class has attrs-generated ordering methods.
`hashability`	`Hashability`	How `hashable <hashing>` the class is.
`added_match_args`	`bool`	Whether the class supports positional `match <match>` over its fields.
`added_str`	`bool`	Whether the class has an attrs-generated `__str__` method.
`added_pickling`	`bool`	Whether the class has attrs-generated `__getstate__` and `__setstate__` methods for `pickle`.
`on_setattr_hook`	`Callable[[Any, Attribute[Any], Any], Any] \| None`	The class's `__setattr__` hook.
`field_transformer`	`Callable[[Attribute[Any]], Attribute[Any]] \| None`	The class's `field transformers <transform-fields>`.

.. versionadded:: 25.4.0

doc = 'A description of a set of landmark types and connections between them.\n\nSkeletons are represented by a directed graph composed of a set of `Node`s (landmark\ntypes such as body parts) and `Edge`s (connections between parts).\n\nAttributes:\n nodes: A list of `Node`s. May be specified as a list of strings to create new\n nodes from their names.\n edges: A list of `Edge`s. May be specified as a list of 2-tuples of string names\n or integer indices of `nodes`. Each edge corresponds to a pair of source and\n destination nodes forming a directed edge.\n symmetries: A list of `Symmetry`s. Each symmetry corresponds to symmetric body\n parts, such as `"left eye", "right eye"`. This is used when applying flip\n (reflection) augmentation to images in order to appropriately swap the\n indices of symmetric landmarks.\n name: A descriptive name for the `Skeleton`.\n' `class-attribute` ¶

str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.str() (if defined) or repr(object). encoding defaults to 'utf-8'. errors defaults to 'strict'.

`firstlineno = 97` `class-attribute` ¶

int([x]) -> integer int(x, base=10) -> integer

Convert a number or string to an integer, or return 0 if no arguments are given. If x is a number, return x.int(). For floating-point numbers, this truncates towards zero.

If x is not a number or if base is given, then x must be a string, bytes, or bytearray instance representing an integer literal in the given base. The literal can be preceded by '+' or '-' and be surrounded by whitespace. The base defaults to 10. Valid bases are 0 and 2-36. Base 0 means to interpret the base from the string as an integer iteral.

`__match_args__ = ('nodes', 'edges', 'symmetries', 'name')` `class-attribute` ¶

Built-in immutable sequence.

If no argument is given, the constructor returns an empty tuple. If iterable is specified the tuple is initialized from iterable's items.

If the argument is a tuple, the return value is the same object.

`module = 'sleap_io.model.skeleton'` `class-attribute` ¶

str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.str() (if defined) or repr(object). encoding defaults to 'utf-8'. errors defaults to 'strict'.

`slots = ('nodes', 'edges', 'symmetries', 'name', '_name_to_node_cache', '_node_to_ind_cache', 'weakref')` `class-attribute` ¶

Built-in immutable sequence.

If no argument is given, the constructor returns an empty tuple. If iterable is specified the tuple is initialized from iterable's items.

If the argument is a tuple, the return value is the same object.

`__static_attributes__ = ('_name_to_node_cache', '_node_to_ind_cache', 'edges', 'nodes', 'symmetries')` `class-attribute` ¶

Built-in immutable sequence.

If no argument is given, the constructor returns an empty tuple. If iterable is specified the tuple is initialized from iterable's items.

If the argument is a tuple, the return value is the same object.

`weakref` `property` ¶

list of weak references to the object

`edge_inds` `property` ¶

Edges indices as a list of 2-tuples.

`edge_names` `property` ¶

Edge names as a list of 2-tuples with string node names.

`node_names` `property` ¶

Names of the nodes associated with this skeleton as a list of strings.

`symmetry_inds` `property` ¶

Symmetry indices as a list of 2-tuples.

`symmetry_names` `property` ¶

Symmetry names as a list of 2-tuples with string node names.

`__attrs_post_init__()` ¶

Ensure nodes are Nodes, edges are Edges, and Node map is updated.

Source code in sleap_io/model/skeleton.py

def __attrs_post_init__(self):
    """Ensure nodes are `Node`s, edges are `Edge`s, and `Node` map is updated."""
    self._convert_nodes()
    self._convert_edges()
    self._convert_symmetries()
    self.rebuild_cache()

`contains(node)` ¶

Check if a node is in the skeleton.

Source code in sleap_io/model/skeleton.py

def __contains__(self, node: NodeOrIndex) -> bool:
    """Check if a node is in the skeleton."""
    if type(node) is str:
        return node in self._name_to_node_cache
    elif type(node) is Node:
        return node in self.nodes
    elif type(node) is int:
        return 0 <= node < len(self.nodes)
    else:
        raise ValueError(f"Invalid node type for skeleton: {node}")

`getitem(idx)` ¶

Return a Node when indexing by name or integer.

Source code in sleap_io/model/skeleton.py

def __getitem__(self, idx: NodeOrIndex) -> Node:
    """Return a `Node` when indexing by name or integer."""
    if type(idx) is int:
        return self.nodes[idx]
    elif type(idx) is str:
        return self._name_to_node_cache[idx]
    else:
        raise IndexError(f"Invalid indexing argument for skeleton: {idx}")

`init(nodes=NOTHING, edges=NOTHING, symmetries=NOTHING, name=None)` ¶

Method generated by attrs for class Skeleton.

Source code in sleap_io/model/skeleton.py

"""Data model for skeletons.

Skeletons are collections of nodes and edges which describe the landmarks associated
with a pose model. The edges represent the connections between them and may be used
differently depending on the underlying pose model.
"""

from __future__ import annotations

import re
import typing
from functools import lru_cache

import numpy as np
from attrs import define, field

`len()` ¶

Return the number of nodes in the skeleton.

Source code in sleap_io/model/skeleton.py

def __len__(self) -> int:
    """Return the number of nodes in the skeleton."""
    return len(self.nodes)

`repr()` ¶

Return a readable representation of the skeleton.

Source code in sleap_io/model/skeleton.py

def __repr__(self) -> str:
    """Return a readable representation of the skeleton."""
    nodes = ", ".join([f'"{node}"' for node in self.node_names])
    return f"Skeleton(nodes=[{nodes}], edges={self.edge_inds})"

`setattr(name, val)` ¶

Method generated by attrs for class Skeleton.

`add_edge(src, dst=None)` ¶

Add an Edge to the skeleton.

Parameters:

Name	Type	Description	Default
`src`	`Union \| Edge \| tuple[Union, Union]`	The source node specified as a `Node`, name or index.	required
`dst`	`Union \| None`	The destination node specified as a `Node`, name or index.	`None`

Source code in sleap_io/model/skeleton.py

def add_edge(
    self,
    src: NodeOrIndex | Edge | tuple[NodeOrIndex, NodeOrIndex],
    dst: NodeOrIndex | None = None,
):
    """Add an `Edge` to the skeleton.

    Args:
        src: The source node specified as a `Node`, name or index.
        dst: The destination node specified as a `Node`, name or index.
    """
    edge = None
    if type(src) is tuple:
        src, dst = src

    if is_node_or_index(src):
        if not is_node_or_index(dst):
            raise ValueError("Destination node must be specified.")

        src = self.require_node(src)
        dst = self.require_node(dst)
        edge = Edge(src, dst)

    if type(src) is Edge:
        edge = src

    if edge not in self.edges:
        self.edges.append(edge)

`add_edges(edges)` ¶

Add multiple Edges to the skeleton.

Parameters:

Name	Type	Description	Default
`edges`	`list[Edge \| tuple[Union, Union]]`	A list of `Edge` objects or 2-tuples of source and destination nodes.	required

Source code in sleap_io/model/skeleton.py

def add_edges(self, edges: list[Edge | tuple[NodeOrIndex, NodeOrIndex]]):
    """Add multiple `Edge`s to the skeleton.

    Args:
        edges: A list of `Edge` objects or 2-tuples of source and destination nodes.
    """
    for edge in edges:
        self.add_edge(edge)

`add_node(node)` ¶

Add a Node to the skeleton.

Parameters:

Name	Type	Description	Default
`node`	`Node \| str`	A `Node` object or a string name to create a new node.	required

Raises:

Type	Description
`ValueError`	If the node already exists in the skeleton or if the node is not specified as a `Node` or string.

Source code in sleap_io/model/skeleton.py

def add_node(self, node: Node | str):
    """Add a `Node` to the skeleton.

    Args:
        node: A `Node` object or a string name to create a new node.

    Raises:
        ValueError: If the node already exists in the skeleton or if the node is
            not specified as a `Node` or string.
    """
    if node in self:
        raise ValueError(f"Node '{node}' already exists in the skeleton.")

    if type(node) is str:
        node = Node(node)

    if type(node) is not Node:
        raise ValueError(f"Invalid node type: {node} ({type(node)})")

    self.nodes.append(node)

    # Atomic update of the cache.
    self._name_to_node_cache[node.name] = node
    self._node_to_ind_cache[node] = len(self.nodes) - 1

`add_nodes(nodes)` ¶

Add multiple Nodes to the skeleton.

Parameters:

Name	Type	Description	Default
`nodes`	`list[Node \| str]`	A list of `Node` objects or string names to create new nodes.	required

Source code in sleap_io/model/skeleton.py

def add_nodes(self, nodes: list[Node | str]):
    """Add multiple `Node`s to the skeleton.

    Args:
        nodes: A list of `Node` objects or string names to create new nodes.
    """
    for node in nodes:
        self.add_node(node)

`add_symmetries(symmetries)` ¶

Add multiple Symmetry relationships to the skeleton.

Parameters:

Name	Type	Description	Default
`symmetries`	`list[Symmetry \| tuple[Union, Union]]`	A list of `Symmetry` objects or 2-tuples of symmetric nodes.	required

Source code in sleap_io/model/skeleton.py

def add_symmetries(
    self, symmetries: list[Symmetry | tuple[NodeOrIndex, NodeOrIndex]]
):
    """Add multiple `Symmetry` relationships to the skeleton.

    Args:
        symmetries: A list of `Symmetry` objects or 2-tuples of symmetric nodes.
    """
    for symmetry in symmetries:
        self.add_symmetry(*symmetry)

`add_symmetry(node1=None, node2=None)` ¶

Add a symmetry relationship to the skeleton.

Parameters:

Name	Type	Description	Default
`node1`	`Symmetry \| Union`	The first node specified as a `Node`, name or index. If a `Symmetry` object is provided, it will be added directly to the skeleton.	`None`
`node2`	`Union \| None`	The second node specified as a `Node`, name or index.	`None`

Source code in sleap_io/model/skeleton.py

def add_symmetry(
    self, node1: Symmetry | NodeOrIndex = None, node2: NodeOrIndex | None = None
):
    """Add a symmetry relationship to the skeleton.

    Args:
        node1: The first node specified as a `Node`, name or index. If a `Symmetry`
            object is provided, it will be added directly to the skeleton.
        node2: The second node specified as a `Node`, name or index.
    """
    symmetry = None
    if type(node1) is Symmetry:
        symmetry = node1
        node1, node2 = symmetry

    node1 = self.require_node(node1)
    node2 = self.require_node(node2)

    if symmetry is None:
        symmetry = Symmetry({node1, node2})

    if symmetry not in self.symmetries:
        self.symmetries.append(symmetry)

`get_flipped_node_inds()` ¶

Returns node indices that should be switched when horizontally flipping.

This is useful as a lookup table for flipping the landmark coordinates when doing data augmentation.

Example

Source code in sleap_io/model/skeleton.py

def get_flipped_node_inds(self) -> list[int]:
    """Returns node indices that should be switched when horizontally flipping.

    This is useful as a lookup table for flipping the landmark coordinates when
    doing data augmentation.

    Example:
        >>> skel = Skeleton(["A", "B_left", "B_right", "C", "D_left", "D_right"])
        >>> skel.add_symmetry("B_left", "B_right")
        >>> skel.add_symmetry("D_left", "D_right")
        >>> skel.flipped_node_inds
        [0, 2, 1, 3, 5, 4]
        >>> pose = np.array([[0, 0], [1, 1], [2, 2], [3, 3], [4, 4], [5, 5]])
        >>> pose[skel.flipped_node_inds]
        array([[0, 0],
               [2, 2],
               [1, 1],
               [3, 3],
               [5, 5],
               [4, 4]])
    """
    flip_idx = np.arange(len(self.nodes))
    if len(self.symmetries) > 0:
        symmetry_inds = np.array(
            [(self.index(a), self.index(b)) for a, b in self.symmetries]
        )
        flip_idx[symmetry_inds[:, 0]] = symmetry_inds[:, 1]
        flip_idx[symmetry_inds[:, 1]] = symmetry_inds[:, 0]

    flip_idx = flip_idx.tolist()
    return flip_idx

`index(node)` ¶

Return the index of a node specified as a Node or string name.

Source code in sleap_io/model/skeleton.py

def index(self, node: Node | str) -> int:
    """Return the index of a node specified as a `Node` or string name."""
    if type(node) is str:
        return self.index(self._name_to_node_cache[node])
    elif type(node) is Node:
        return self._node_to_ind_cache[node]
    else:
        raise IndexError(f"Invalid indexing argument for skeleton: {node}")

`infer_symmetries_by_name(token_pairs=None)` ¶

Infer left/right symmetric node pairs from node names.

Useful when a skeleton has no symmetries defined (e.g. imported from a format that does not carry symmetry metadata) but its node names encode laterality, so that flip-dependent tooling (augmentation, QC) still works. Names are matched by splitting on separators (_, -, ., space), camelCase boundaries, and letter/digit boundaries, then pairing nodes that share a stem but differ by a single left/right token. For example, Ear_L/Ear_R, left_eye/right_eye, LeftPaw/RightPaw, and L1/R1 all pair up.

This is intentionally non-mutating and conservative: it returns suggested pairs rather than writing them onto the skeleton, since a wrong guess would silently corrupt flip augmentation. Apply the result explicitly if desired, e.g. skel.add_symmetries(skel.infer_symmetries_by_name()). Node names without a delimited or camelCase/digit token boundary (e.g. larm) and truly non-semantic pairings (e.g. L1/L2) cannot be inferred and must be declared with add_symmetry.

Parameters:

Name	Type	Description	Default
`token_pairs`	`list[tuple[str, str]] \| None`	List of `(left_token, right_token)` string pairs used to recognize laterality, matched case-insensitively against whole name segments. Defaults to `[("left", "right"), ("l", "r")]`.	`None`

Returns:

Type	Description
`list[tuple[int, int]]`	A list of `(left_index, right_index)` node-index pairs, ordered by left index. Each node appears in at most one pair, and only stems with exactly one left and one right member are paired (ambiguous groups are skipped).

Example

Source code in sleap_io/model/skeleton.py

def infer_symmetries_by_name(
    self,
    token_pairs: list[tuple[str, str]] | None = None,
) -> list[tuple[int, int]]:
    """Infer left/right symmetric node pairs from node names.

    Useful when a skeleton has no symmetries defined (e.g. imported from a
    format that does not carry symmetry metadata) but its node names encode
    laterality, so that flip-dependent tooling (augmentation, QC) still
    works. Names are matched by splitting on separators (`_`, `-`, `.`,
    space), camelCase boundaries, and letter/digit boundaries, then pairing
    nodes that share a stem but differ by a single left/right token. For
    example, `Ear_L`/`Ear_R`, `left_eye`/`right_eye`, `LeftPaw`/`RightPaw`,
    and `L1`/`R1` all pair up.

    This is intentionally **non-mutating** and conservative: it returns
    suggested pairs rather than writing them onto the skeleton, since a wrong
    guess would silently corrupt flip augmentation. Apply the result
    explicitly if desired, e.g.
    `skel.add_symmetries(skel.infer_symmetries_by_name())`. Node names
    without a delimited or camelCase/digit token boundary (e.g. `larm`) and
    truly non-semantic pairings (e.g. `L1`/`L2`) cannot be inferred and must
    be declared with `add_symmetry`.

    Args:
        token_pairs: List of `(left_token, right_token)` string pairs used to
            recognize laterality, matched case-insensitively against whole
            name segments. Defaults to `[("left", "right"), ("l", "r")]`.

    Returns:
        A list of `(left_index, right_index)` node-index pairs, ordered by
        left index. Each node appears in at most one pair, and only stems
        with exactly one left and one right member are paired (ambiguous
        groups are skipped).

    Example:
        >>> skel = Skeleton(["nose", "eye_L", "eye_R", "ear_L", "ear_R"])
        >>> skel.infer_symmetries_by_name()
        [(1, 2), (3, 4)]
        >>> skel.add_symmetries(skel.infer_symmetries_by_name())
        >>> skel.symmetry_names
        [('eye_L', 'eye_R'), ('ear_L', 'ear_R')]
    """
    return infer_symmetry_pairs_by_name(self.node_names, token_pairs=token_pairs)

`match_nodes(other_nodes)` ¶

Return the order of nodes in the skeleton.

Parameters:

Name	Type	Description	Default
`other_nodes`	`list[str, Node]`	A list of node names or `Node` objects.	required

Returns:

Type	Description
`tuple[list[int], list[int]]`	A tuple of `skeleton_inds,`other_inds`. `skeleton_inds` contains the indices of the nodes in the skeleton that match the input nodes. `other_inds` contains the indices of the input nodes that match the nodes in the skeleton. These can be used to reorder point data to match the order of nodes in the skeleton.

`matches(other, require_same_order=False)` ¶

Check if this skeleton matches another skeleton's structure.

Parameters:

Name	Type	Description	Default
`other`	`Skeleton`	Another skeleton to compare with.	required
`require_same_order`	`bool`	If True, nodes must be in the same order. If False, only the node names and edges need to match.	`False`

Returns:

Type	Description
`bool`	True if the skeletons match, False otherwise.

Notes

Two skeletons match if they have the same nodes (by name) and edges. If require_same_order is True, the nodes must also be in the same order.

Source code in sleap_io/model/skeleton.py

def matches(self, other: "Skeleton", require_same_order: bool = False) -> bool:
    """Check if this skeleton matches another skeleton's structure.

    Args:
        other: Another skeleton to compare with.
        require_same_order: If True, nodes must be in the same order.
            If False, only the node names and edges need to match.

    Returns:
        True if the skeletons match, False otherwise.

    Notes:
        Two skeletons match if they have the same nodes (by name) and edges.
        If require_same_order is True, the nodes must also be in the same order.
    """
    # Check if we have the same number of nodes
    if len(self.nodes) != len(other.nodes):
        return False

    # Check node names
    if require_same_order:
        if self.node_names != other.node_names:
            return False
    else:
        if set(self.node_names) != set(other.node_names):
            return False

    # Check edges (considering node name mapping if order differs)
    if len(self.edges) != len(other.edges):
        return False

    # Create edge sets for comparison
    self_edge_set = {
        (edge.source.name, edge.destination.name) for edge in self.edges
    }
    other_edge_set = {
        (edge.source.name, edge.destination.name) for edge in other.edges
    }

    if self_edge_set != other_edge_set:
        return False

    # Check symmetries
    if len(self.symmetries) != len(other.symmetries):
        return False

    self_sym_set = {
        frozenset(node.name for node in sym.nodes) for sym in self.symmetries
    }
    other_sym_set = {
        frozenset(node.name for node in sym.nodes) for sym in other.symmetries
    }

    return self_sym_set == other_sym_set

`node_similarities(other)` ¶

Calculate node overlap metrics with another skeleton.

Parameters:

Name	Type	Description	Default
`other`	`Skeleton`	Another skeleton to compare with.	required

Returns:

Type	Description
`dict[str, float]`	A dictionary with similarity metrics: - 'n_common': Number of nodes in common - 'n_self_only': Number of nodes only in this skeleton - 'n_other_only': Number of nodes only in the other skeleton - 'jaccard': Jaccard similarity (intersection/union) - 'dice': Dice coefficient (2*intersection/(n_self + n_other))

Source code in sleap_io/model/skeleton.py

def node_similarities(self, other: "Skeleton") -> dict[str, float]:
    """Calculate node overlap metrics with another skeleton.

    Args:
        other: Another skeleton to compare with.

    Returns:
        A dictionary with similarity metrics:
        - 'n_common': Number of nodes in common
        - 'n_self_only': Number of nodes only in this skeleton
        - 'n_other_only': Number of nodes only in the other skeleton
        - 'jaccard': Jaccard similarity (intersection/union)
        - 'dice': Dice coefficient (2*intersection/(n_self + n_other))
    """
    self_nodes = set(self.node_names)
    other_nodes = set(other.node_names)

    n_common = len(self_nodes & other_nodes)
    n_self_only = len(self_nodes - other_nodes)
    n_other_only = len(other_nodes - self_nodes)
    n_union = len(self_nodes | other_nodes)

    jaccard = n_common / n_union if n_union > 0 else 0
    dice = (
        2 * n_common / (len(self_nodes) + len(other_nodes))
        if (len(self_nodes) + len(other_nodes)) > 0
        else 0
    )

    return {
        "n_common": n_common,
        "n_self_only": n_self_only,
        "n_other_only": n_other_only,
        "jaccard": jaccard,
        "dice": dice,
    }

`rebuild_cache(nodes=None)` ¶

Rebuild the node name/index to Node map caches.

Parameters:

Name	Type	Description	Default
`nodes`	`list[Node] \| None`	A list of `Node` objects to update the cache with. If not provided, the cache will be updated with the current nodes in the skeleton. If nodes are provided, the cache will be updated with the provided nodes, but the current nodes in the skeleton will not be updated. Default is `None`.	`None`

Notes

This function should be called when nodes or node list is mutated to update the lookup caches for indexing nodes by name or Node object.

This is done automatically when nodes are added or removed from the skeleton using the convenience methods in this class.

This method only needs to be used when manually mutating nodes or the node list directly.

Source code in sleap_io/model/skeleton.py

def rebuild_cache(self, nodes: list[Node] | None = None):
    """Rebuild the node name/index to `Node` map caches.

    Args:
        nodes: A list of `Node` objects to update the cache with. If not provided,
            the cache will be updated with the current nodes in the skeleton. If
            nodes are provided, the cache will be updated with the provided nodes,
            but the current nodes in the skeleton will not be updated. Default is
            `None`.

    Notes:
        This function should be called when nodes or node list is mutated to update
        the lookup caches for indexing nodes by name or `Node` object.

        This is done automatically when nodes are added or removed from the skeleton
        using the convenience methods in this class.

        This method only needs to be used when manually mutating nodes or the node
        list directly.
    """
    if nodes is None:
        nodes = self.nodes
    self._name_to_node_cache = {node.name: node for node in nodes}
    self._node_to_ind_cache = {node: i for i, node in enumerate(nodes)}

`remove_node(node)` ¶

Remove a single node from the skeleton.

Parameters:

Name	Type	Description	Default
`node`	`Union`	The node to remove. Can be specified as a string name, integer index, or `Node` object.	required

Notes

This method handles updating the lookup caches necessary for indexing nodes by name.

Any edges and symmetries that are connected to the removed node will also be removed.

Warning

This method does NOT update instances that use this skeleton to reflect changes.

It is recommended to use the Labels.remove_nodes() method which will update all contained instances to reflect the changes made to the skeleton.

To manually update instances after this method is called, call Instance.update_skeleton() on each instance that uses this skeleton.

Source code in sleap_io/model/skeleton.py

def remove_node(self, node: NodeOrIndex):
    """Remove a single node from the skeleton.

    Args:
        node: The node to remove. Can be specified as a string name, integer index,
            or `Node` object.

    Notes:
        This method handles updating the lookup caches necessary for indexing nodes
        by name.

        Any edges and symmetries that are connected to the removed node will also be
        removed.

    Warning:
        **This method does NOT update instances** that use this skeleton to reflect
        changes.

        It is recommended to use the `Labels.remove_nodes()` method which will
        update all contained instances to reflect the changes made to the skeleton.

        To manually update instances after this method is called, call
        `Instance.update_skeleton()` on each instance that uses this skeleton.
    """
    self.remove_nodes([node])

`remove_nodes(nodes)` ¶

Remove nodes from the skeleton.

Parameters:

Name	Type	Description	Default
`nodes`	`list[Union]`	A list of node names, indices, or `Node` objects to remove.	required

Notes

This method handles updating the lookup caches necessary for indexing nodes by name.

Any edges and symmetries that are connected to the removed nodes will also be removed.

Warning

This method does NOT update instances that use this skeleton to reflect changes.

It is recommended to use the Labels.remove_nodes() method which will update all contained to reflect the changes made to the skeleton.

To manually update instances after this method is called, call instance.update_nodes() on each instance that uses this skeleton.

Source code in sleap_io/model/skeleton.py

def remove_nodes(self, nodes: list[NodeOrIndex]):
    """Remove nodes from the skeleton.

    Args:
        nodes: A list of node names, indices, or `Node` objects to remove.

    Notes:
        This method handles updating the lookup caches necessary for indexing nodes
        by name.

        Any edges and symmetries that are connected to the removed nodes will also
        be removed.

    Warning:
        **This method does NOT update instances** that use this skeleton to reflect
        changes.

        It is recommended to use the `Labels.remove_nodes()` method which will
        update all contained to reflect the changes made to the skeleton.

        To manually update instances after this method is called, call
        `instance.update_nodes()` on each instance that uses this skeleton.
    """
    # Standardize input and make a pre-mutation copy before keys are changed.
    rm_node_objs = [self.require_node(node, add_missing=False) for node in nodes]

    # Remove nodes from the skeleton.
    for node in rm_node_objs:
        self.nodes.remove(node)
        del self._name_to_node_cache[node.name]

    # Remove edges connected to the removed nodes.
    self.edges = [
        edge
        for edge in self.edges
        if edge.source not in rm_node_objs and edge.destination not in rm_node_objs
    ]

    # Remove symmetries connected to the removed nodes.
    self.symmetries = [
        symmetry
        for symmetry in self.symmetries
        if symmetry.nodes.isdisjoint(rm_node_objs)
    ]

    # Update node index map.
    self.rebuild_cache()

`rename_node(old_name, new_name)` ¶

Rename a single node in the skeleton.

Parameters:

Name	Type	Description	Default
`old_name`	`Union`	The name of the node to rename. Can also be specified as an integer index or `Node` object.	required
`new_name`	`str`	The new name for the node.	required

Source code in sleap_io/model/skeleton.py

def rename_node(self, old_name: NodeOrIndex, new_name: str):
    """Rename a single node in the skeleton.

    Args:
        old_name: The name of the node to rename. Can also be specified as an
            integer index or `Node` object.
        new_name: The new name for the node.
    """
    self.rename_nodes({old_name: new_name})

`rename_nodes(name_map)` ¶

Rename nodes in the skeleton.

Parameters:

Name	Type	Description	Default
`name_map`	`dict[Union, str] \| list[str]`	A dictionary mapping old node names to new node names. Keys can be specified as `Node` objects, integer indices, or string names. Values must be specified as string names. If a list of strings is provided of the same length as the current nodes, the nodes will be renamed to the names in the list in order.	required

Raises:

Type	Description
`ValueError`	If the new node names exist in the skeleton or if the old node names are not found in the skeleton.

Notes

This method should always be used when renaming nodes in the skeleton as it handles updating the lookup caches necessary for indexing nodes by name.

After renaming, instances using this skeleton do NOT need to be updated as the nodes are stored by reference in the skeleton, so changes are reflected automatically.

Example

Source code in sleap_io/model/skeleton.py

def rename_nodes(self, name_map: dict[NodeOrIndex, str] | list[str]):
    """Rename nodes in the skeleton.

    Args:
        name_map: A dictionary mapping old node names to new node names. Keys can be
            specified as `Node` objects, integer indices, or string names. Values
            must be specified as string names.

            If a list of strings is provided of the same length as the current
            nodes, the nodes will be renamed to the names in the list in order.

    Raises:
        ValueError: If the new node names exist in the skeleton or if the old node
            names are not found in the skeleton.

    Notes:
        This method should always be used when renaming nodes in the skeleton as it
        handles updating the lookup caches necessary for indexing nodes by name.

        After renaming, instances using this skeleton **do NOT need to be updated**
        as the nodes are stored by reference in the skeleton, so changes are
        reflected automatically.

    Example:
        >>> skel = Skeleton(["A", "B", "C"], edges=[("A", "B"), ("B", "C")])
        >>> skel.rename_nodes({"A": "X", "B": "Y", "C": "Z"})
        >>> skel.node_names
        ["X", "Y", "Z"]
        >>> skel.rename_nodes(["a", "b", "c"])
        >>> skel.node_names
        ["a", "b", "c"]
    """
    if type(name_map) is list:
        if len(name_map) != len(self.nodes):
            raise ValueError(
                "List of new node names must be the same length as the current "
                "nodes."
            )
        name_map = {node: name for node, name in zip(self.nodes, name_map)}

    for old_name, new_name in name_map.items():
        if type(old_name) is Node:
            old_name = old_name.name
        if type(old_name) is int:
            old_name = self.nodes[old_name].name

        if old_name not in self._name_to_node_cache:
            raise ValueError(f"Node '{old_name}' not found in the skeleton.")
        if new_name in self._name_to_node_cache:
            raise ValueError(f"Node '{new_name}' already exists in the skeleton.")

        node = self._name_to_node_cache[old_name]
        node.name = new_name
        self._name_to_node_cache[new_name] = node
        del self._name_to_node_cache[old_name]

`reorder_nodes(new_order)` ¶

Reorder nodes in the skeleton.

Parameters:

Name	Type	Description	Default
`new_order`	`list[Union]`	A list of node names, indices, or `Node` objects specifying the new order of the nodes.	required

Raises:

Type	Description
`ValueError`	If the new order of nodes is not the same length as the current nodes.

Notes

This method handles updating the lookup caches necessary for indexing nodes by name.

Warning

After reordering, instances using this skeleton do not need to be updated as the nodes are stored by reference in the skeleton.

However, the order that points are stored in the instances will not be updated to match the new order of the nodes in the skeleton. This should not matter unless the ordering of the keys in the Instance.points dictionary is used instead of relying on the skeleton node order.

To make sure these are aligned, it is recommended to use the Labels.reorder_nodes() method which will update all contained instances to reflect the changes made to the skeleton.

To manually update instances after this method is called, call Instance.update_skeleton() on each instance that uses this skeleton.

Source code in sleap_io/model/skeleton.py

def reorder_nodes(self, new_order: list[NodeOrIndex]):
    """Reorder nodes in the skeleton.

    Args:
        new_order: A list of node names, indices, or `Node` objects specifying the
            new order of the nodes.

    Raises:
        ValueError: If the new order of nodes is not the same length as the current
            nodes.

    Notes:
        This method handles updating the lookup caches necessary for indexing nodes
        by name.

    Warning:
        After reordering, instances using this skeleton do not need to be updated as
        the nodes are stored by reference in the skeleton.

        However, the order that points are stored in the instances will not be
        updated to match the new order of the nodes in the skeleton. This should not
        matter unless the ordering of the keys in the `Instance.points` dictionary
        is used instead of relying on the skeleton node order.

        To make sure these are aligned, it is recommended to use the
        `Labels.reorder_nodes()` method which will update all contained instances to
        reflect the changes made to the skeleton.

        To manually update instances after this method is called, call
        `Instance.update_skeleton()` on each instance that uses this skeleton.
    """
    if len(new_order) != len(self.nodes):
        raise ValueError(
            "New order of nodes must be the same length as the current nodes."
        )

    new_nodes = [self.require_node(node, add_missing=False) for node in new_order]
    self.nodes = new_nodes

`require_node(node, add_missing=True)` ¶

Return a Node object, handling indexing and adding missing nodes.

Parameters:

Name	Type	Description	Default
`node`	`Union`	A `Node` object, name or index.	required
`add_missing`	`bool`	If `True`, missing nodes will be added to the skeleton. If `False`, an error will be raised if the node is not found. Default is `True`.	`True`

Returns:

Type	Description
`Node`	The `Node` object.

Raises:

Type	Description
`IndexError`	If the node is not found in the skeleton and `add_missing` is `False`.

Source code in sleap_io/model/skeleton.py

def require_node(self, node: NodeOrIndex, add_missing: bool = True) -> Node:
    """Return a `Node` object, handling indexing and adding missing nodes.

    Args:
        node: A `Node` object, name or index.
        add_missing: If `True`, missing nodes will be added to the skeleton. If
            `False`, an error will be raised if the node is not found. Default is
            `True`.

    Returns:
        The `Node` object.

    Raises:
        IndexError: If the node is not found in the skeleton and `add_missing` is
            `False`.
    """
    if node not in self:
        if add_missing:
            self.add_node(node)
        else:
            raise IndexError(f"Node '{node}' not found in the skeleton.")

    if type(node) is Node:
        return node

    return self[node]

`SkeletonMatchMethod` ¶

Bases: builtins.str, enum.Enum

Methods for matching skeletons.

Attributes:

Name	Type	Description
`EXACT`		Exact match requiring same nodes in the same order.
`STRUCTURE`		Match requiring same nodes and edges, but order doesn't matter.
`OVERLAP`		Partial match based on overlapping nodes (uses Jaccard similarity).
`SUBSET`		Match if one skeleton's nodes are a subset of another's.

Source code in sleap_io/model/matching.py

class SkeletonMatchMethod(str, Enum):
    """Methods for matching skeletons.

    Attributes:
        EXACT: Exact match requiring same nodes in the same order.
        STRUCTURE: Match requiring same nodes and edges, but order doesn't matter.
        OVERLAP: Partial match based on overlapping nodes (uses Jaccard similarity).
        SUBSET: Match if one skeleton's nodes are a subset of another's.
    """

    EXACT = "exact"
    STRUCTURE = "structure"
    OVERLAP = "overlap"
    SUBSET = "subset"

`EXACT = <SkeletonMatchMethod.EXACT: 'exact'>` `class-attribute` ¶

Methods for matching skeletons.

Attributes:

Name	Type	Description
`EXACT`		Exact match requiring same nodes in the same order.
`STRUCTURE`		Match requiring same nodes and edges, but order doesn't matter.
`OVERLAP`		Partial match based on overlapping nodes (uses Jaccard similarity).
`SUBSET`		Match if one skeleton's nodes are a subset of another's.

`OVERLAP = <SkeletonMatchMethod.OVERLAP: 'overlap'>` `class-attribute` ¶

Methods for matching skeletons.

Attributes:

Name	Type	Description
`EXACT`		Exact match requiring same nodes in the same order.
`STRUCTURE`		Match requiring same nodes and edges, but order doesn't matter.
`OVERLAP`		Partial match based on overlapping nodes (uses Jaccard similarity).
`SUBSET`		Match if one skeleton's nodes are a subset of another's.

`STRUCTURE = <SkeletonMatchMethod.STRUCTURE: 'structure'>` `class-attribute` ¶

Methods for matching skeletons.

Attributes:

Name	Type	Description
`EXACT`		Exact match requiring same nodes in the same order.
`STRUCTURE`		Match requiring same nodes and edges, but order doesn't matter.
`OVERLAP`		Partial match based on overlapping nodes (uses Jaccard similarity).
`SUBSET`		Match if one skeleton's nodes are a subset of another's.

`SUBSET = <SkeletonMatchMethod.SUBSET: 'subset'>` `class-attribute` ¶

Methods for matching skeletons.

Attributes:

Name	Type	Description
`EXACT`		Exact match requiring same nodes in the same order.
`STRUCTURE`		Match requiring same nodes and edges, but order doesn't matter.
`OVERLAP`		Partial match based on overlapping nodes (uses Jaccard similarity).
`SUBSET`		Match if one skeleton's nodes are a subset of another's.

`doc = "Methods for matching skeletons.\n\nAttributes:\n EXACT: Exact match requiring same nodes in the same order.\n STRUCTURE: Match requiring same nodes and edges, but order doesn't matter.\n OVERLAP: Partial match based on overlapping nodes (uses Jaccard similarity).\n SUBSET: Match if one skeleton's nodes are a subset of another's.\n"` `class-attribute` ¶

str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.str() (if defined) or repr(object). encoding defaults to 'utf-8'. errors defaults to 'strict'.

`module = 'sleap_io.model.matching'` `class-attribute` ¶

str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.str() (if defined) or repr(object). encoding defaults to 'utf-8'. errors defaults to 'strict'.

`SkeletonMatcher` ¶

Matcher for comparing and matching skeletons.

Attributes:

Name	Type	Description
`method`		The matching method to use. Can be a SkeletonMatchMethod enum value or a string that will be converted to the enum. Default is STRUCTURE.
`require_same_order`		Whether to require nodes in the same order for STRUCTURE matching. Only used when method is STRUCTURE. Default is False.
`min_overlap`		Minimum Jaccard similarity required for OVERLAP matching. Only used when method is OVERLAP. Default is 0.5.

Methods:

Name	Description
`__eq__`	Method generated by attrs for class SkeletonMatcher.
`__init__`	Method generated by attrs for class SkeletonMatcher.
`__repr__`	Method generated by attrs for class SkeletonMatcher.
`__setattr__`	Method generated by attrs for class SkeletonMatcher.
`match`	Check if two skeletons match according to the configured method.

Source code in sleap_io/model/matching.py

@attrs.define
class SkeletonMatcher:
    """Matcher for comparing and matching skeletons.

    Attributes:
        method: The matching method to use. Can be a SkeletonMatchMethod enum value
            or a string that will be converted to the enum. Default is STRUCTURE.
        require_same_order: Whether to require nodes in the same order for STRUCTURE
            matching. Only used when method is STRUCTURE. Default is False.
        min_overlap: Minimum Jaccard similarity required for OVERLAP matching.
            Only used when method is OVERLAP. Default is 0.5.
    """

    method: SkeletonMatchMethod | str = attrs.field(
        default=SkeletonMatchMethod.STRUCTURE,
        converter=lambda x: SkeletonMatchMethod(x) if isinstance(x, str) else x,
    )
    require_same_order: bool = False
    min_overlap: float = 0.5

    def match(self, skeleton1: Skeleton, skeleton2: Skeleton) -> bool:
        """Check if two skeletons match according to the configured method."""
        if self.method == SkeletonMatchMethod.EXACT:
            return skeleton1.matches(skeleton2, require_same_order=True)
        elif self.method == SkeletonMatchMethod.STRUCTURE:
            return skeleton1.matches(
                skeleton2, require_same_order=self.require_same_order
            )
        elif self.method == SkeletonMatchMethod.OVERLAP:
            metrics = skeleton1.node_similarities(skeleton2)
            return metrics["jaccard"] >= self.min_overlap
        elif self.method == SkeletonMatchMethod.SUBSET:
            # Check if skeleton1 nodes are subset of skeleton2
            nodes1 = set(skeleton1.node_names)
            nodes2 = set(skeleton2.node_names)
            return nodes1.issubset(nodes2)
        else:
            raise ValueError(f"Unknown skeleton match method: {self.method}")

`annotations = {'method': 'SkeletonMatchMethod | str', 'require_same_order': 'bool', 'min_overlap': 'float'}` `class-attribute` ¶

dict() -> new empty dictionary dict(mapping) -> new dictionary initialized from a mapping object's (key, value) pairs dict(iterable) -> new dictionary initialized as if via: d = {} for k, v in iterable: d[k] = v dict(**kwargs) -> new dictionary initialized with the name=value pairs in the keyword argument list. For example: dict(one=1, two=2)

`__attrs_own_setattr__ = True` `class-attribute` ¶

Returns True when the argument is true, False otherwise. The builtins True and False are the only two instances of the class bool. The class bool is a subclass of the class int, and cannot be subclassed.

`__attrs_props__ = ClassProps(is_exception=False, is_slotted=True, has_weakref_slot=True, is_frozen=False, kw_only=<KeywordOnly.NO: 'no'>, collected_fields_by_mro=True, added_init=True, added_repr=True, added_eq=True, added_ordering=False, hashability=<Hashability.UNHASHABLE: 'unhashable'>, added_match_args=True, added_str=False, added_pickling=True, on_setattr_hook=<function pipe.<locals>.wrapped_pipe at 0x7f08471ce840>, field_transformer=None)` `class-attribute` ¶

Effective class properties as derived from parameters to attr.s() or define() decorators.

This is the same data structure that attrs uses internally to decide how to construct the final class.

Warning:

This feature is currently **experimental** and is not covered by our
strict backwards-compatibility guarantees.

Attributes:

Name	Type	Description
`is_exception`	`bool`	Whether the class is treated as an exception class.
`is_slotted`	`bool`	Whether the class is `slotted <slotted classes>`.
`has_weakref_slot`	`bool`	Whether the class has a slot for weak references.
`is_frozen`	`bool`	Whether the class is frozen.
`kw_only`	`KeywordOnly`	Whether / how the class enforces keyword-only arguments on the `__init__` method.
`collected_fields_by_mro`	`bool`	Whether the class fields were collected by method resolution order. That is, correctly but unlike `dataclasses`.
`added_init`	`bool`	Whether the class has an attrs-generated `__init__` method.
`added_repr`	`bool`	Whether the class has an attrs-generated `__repr__` method.
`added_eq`	`bool`	Whether the class has attrs-generated equality methods.
`added_ordering`	`bool`	Whether the class has attrs-generated ordering methods.
`hashability`	`Hashability`	How `hashable <hashing>` the class is.
`added_match_args`	`bool`	Whether the class supports positional `match <match>` over its fields.
`added_str`	`bool`	Whether the class has an attrs-generated `__str__` method.
`added_pickling`	`bool`	Whether the class has attrs-generated `__getstate__` and `__setstate__` methods for `pickle`.
`on_setattr_hook`	`Callable[[Any, Attribute[Any], Any], Any] \| None`	The class's `__setattr__` hook.
`field_transformer`	`Callable[[Attribute[Any]], Attribute[Any]] \| None`	The class's `field transformers <transform-fields>`.

.. versionadded:: 25.4.0

doc = 'Matcher for comparing and matching skeletons.\n\nAttributes:\n method: The matching method to use. Can be a SkeletonMatchMethod enum value\n or a string that will be converted to the enum. Default is STRUCTURE.\n require_same_order: Whether to require nodes in the same order for STRUCTURE\n matching. Only used when method is STRUCTURE. Default is False.\n min_overlap: Minimum Jaccard similarity required for OVERLAP matching.\n Only used when method is OVERLAP. Default is 0.5.\n' `class-attribute` ¶

str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.str() (if defined) or repr(object). encoding defaults to 'utf-8'. errors defaults to 'strict'.

`firstlineno = 756` `class-attribute` ¶

int([x]) -> integer int(x, base=10) -> integer

Convert a number or string to an integer, or return 0 if no arguments are given. If x is a number, return x.int(). For floating-point numbers, this truncates towards zero.

If x is not a number or if base is given, then x must be a string, bytes, or bytearray instance representing an integer literal in the given base. The literal can be preceded by '+' or '-' and be surrounded by whitespace. The base defaults to 10. Valid bases are 0 and 2-36. Base 0 means to interpret the base from the string as an integer iteral.

`__match_args__ = ('method', 'require_same_order', 'min_overlap')` `class-attribute` ¶

Built-in immutable sequence.

If no argument is given, the constructor returns an empty tuple. If iterable is specified the tuple is initialized from iterable's items.

If the argument is a tuple, the return value is the same object.

`module = 'sleap_io.model.matching'` `class-attribute` ¶

str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.str() (if defined) or repr(object). encoding defaults to 'utf-8'. errors defaults to 'strict'.

`slots = ('method', 'require_same_order', 'min_overlap', 'weakref')` `class-attribute` ¶

Built-in immutable sequence.

If no argument is given, the constructor returns an empty tuple. If iterable is specified the tuple is initialized from iterable's items.

If the argument is a tuple, the return value is the same object.

`__static_attributes__ = ()` `class-attribute` ¶

Built-in immutable sequence.

If no argument is given, the constructor returns an empty tuple. If iterable is specified the tuple is initialized from iterable's items.

If the argument is a tuple, the return value is the same object.

`weakref` `property` ¶

list of weak references to the object

`eq(other)` ¶

Method generated by attrs for class SkeletonMatcher.

Source code in sleap_io/model/matching.py

automatic strategies.
"""

from __future__ import annotations

from enum import Enum
from typing import TYPE_CHECKING, Any

`init(method=<SkeletonMatchMethod.STRUCTURE: 'structure'>, require_same_order=False, min_overlap=0.5)` ¶

Method generated by attrs for class SkeletonMatcher.

Source code in sleap_io/model/matching.py

import attrs
import numpy as np

from sleap_io.model.category import Category
from sleap_io.model.identity import Identity

`repr()` ¶

Method generated by attrs for class SkeletonMatcher.

Source code in sleap_io/model/matching.py

"""Unified matcher system for comparing and matching data structures during merging.

This module provides configurable matchers for comparing skeletons, instances, tracks,
and videos during merge operations. The matchers use various strategies to determine
when data structures should be considered equivalent during merging.

Key features:
- Skeleton matching: exact, structure-based, overlap, and subset matching
- Instance matching: spatial proximity, track identity, and bounding box IoU
- Track matching: by name or object identity
- Identity matching: by name or object identity
- Category matching: by name or object identity
- Video matching: path, basename, content, and auto matching

Video matching supports path-based, filename-based, content-based, and

`setattr(name, val)` ¶

Method generated by attrs for class SkeletonMatcher.

Source code in sleap_io/model/matching.py

        return match

# IMAGE MATCHING: Compare frame images (opt-in)
if self.compare_images:
    match = self._match_by_images(incoming, viable)
    if match is not None:
        return match

# No match found

`match(skeleton1, skeleton2)` ¶

Check if two skeletons match according to the configured method.

Source code in sleap_io/model/matching.py

def match(self, skeleton1: Skeleton, skeleton2: Skeleton) -> bool:
    """Check if two skeletons match according to the configured method."""
    if self.method == SkeletonMatchMethod.EXACT:
        return skeleton1.matches(skeleton2, require_same_order=True)
    elif self.method == SkeletonMatchMethod.STRUCTURE:
        return skeleton1.matches(
            skeleton2, require_same_order=self.require_same_order
        )
    elif self.method == SkeletonMatchMethod.OVERLAP:
        metrics = skeleton1.node_similarities(skeleton2)
        return metrics["jaccard"] >= self.min_overlap
    elif self.method == SkeletonMatchMethod.SUBSET:
        # Check if skeleton1 nodes are subset of skeleton2
        nodes1 = set(skeleton1.node_names)
        nodes2 = set(skeleton2.node_names)
        return nodes1.issubset(nodes2)
    else:
        raise ValueError(f"Unknown skeleton match method: {self.method}")

`SkeletonMismatchError` ¶

Bases: sleap_io.model.matching.MergeError

Raised when skeletons don't match during merge.

Attributes:

Name	Type	Description
`__annotations__`		dict() -> new empty dictionary
`__doc__`		str(object='') -> str
`__firstlineno__`		int([x]) -> integer
`__module__`		str(object='') -> str
`__static_attributes__`		Built-in immutable sequence.

Source code in sleap_io/model/matching.py

class SkeletonMismatchError(MergeError):
    """Raised when skeletons don't match during merge."""

    pass

`annotations = {}` `class-attribute` ¶

dict() -> new empty dictionary dict(mapping) -> new dictionary initialized from a mapping object's (key, value) pairs dict(iterable) -> new dictionary initialized as if via: d = {} for k, v in iterable: d[k] = v dict(**kwargs) -> new dictionary initialized with the name=value pairs in the keyword argument list. For example: dict(one=1, two=2)

`doc = "Raised when skeletons don't match during merge."` `class-attribute` ¶

str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.str() (if defined) or repr(object). encoding defaults to 'utf-8'. errors defaults to 'strict'.

`firstlineno = 1357` `class-attribute` ¶

int([x]) -> integer int(x, base=10) -> integer

Convert a number or string to an integer, or return 0 if no arguments are given. If x is a number, return x.int(). For floating-point numbers, this truncates towards zero.

If x is not a number or if base is given, then x must be a string, bytes, or bytearray instance representing an integer literal in the given base. The literal can be preceded by '+' or '-' and be surrounded by whitespace. The base defaults to 10. Valid bases are 0 and 2-36. Base 0 means to interpret the base from the string as an integer iteral.

`module = 'sleap_io.model.matching'` `class-attribute` ¶

str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.str() (if defined) or repr(object). encoding defaults to 'utf-8'. errors defaults to 'strict'.

`__static_attributes__ = ()` `class-attribute` ¶

Built-in immutable sequence.

If no argument is given, the constructor returns an empty tuple. If iterable is specified the tuple is initialized from iterable's items.

If the argument is a tuple, the return value is the same object.

`Track` ¶

An object that represents the same animal/object across multiple detections.

This allows tracking of unique entities in the video over time and space.

A Track may also be used to refer to unique identity classes that span multiple videos, such as "female mouse".

Attributes:

Name	Type	Description
`name`		A name given to this track for identification purposes.

Notes

Tracks are compared by identity. This means that unique track objects with the same name are considered to be different.

Methods:

Name	Description
`__init__`	Method generated by attrs for class Track.
`__repr__`	Method generated by attrs for class Track.
`matches`	Check if this track matches another track.
`similarity_to`	Calculate similarity metrics with another track.

Source code in sleap_io/model/instance.py

@attrs.define(eq=False)
class Track:
    """An object that represents the same animal/object across multiple detections.

    This allows tracking of unique entities in the video over time and space.

    A `Track` may also be used to refer to unique identity classes that span multiple
    videos, such as `"female mouse"`.

    Attributes:
        name: A name given to this track for identification purposes.

    Notes:
        `Track`s are compared by identity. This means that unique track objects with the
        same name are considered to be different.
    """

    name: str = ""

    def matches(self, other: "Track", method: str = "name") -> bool:
        """Check if this track matches another track.

        Args:
            other: Another track to compare with.
            method: Matching method - "name" (match by name) or "identity"
                (match by object identity).

        Returns:
            True if the tracks match according to the specified method.
        """
        if method == "name":
            return self.name == other.name
        elif method == "identity":
            return self is other
        else:
            raise ValueError(f"Unknown matching method: {method}")

    def similarity_to(self, other: "Track") -> dict[str, any]:
        """Calculate similarity metrics with another track.

        Args:
            other: Another track to compare with.

        Returns:
            A dictionary with similarity metrics:
            - 'same_name': Whether the tracks have the same name
            - 'same_identity': Whether the tracks are the same object
            - 'name_similarity': Simple string similarity score (0-1)
        """
        # Calculate simple string similarity
        if self.name and other.name:
            # Simple character overlap similarity
            common_chars = set(self.name.lower()) & set(other.name.lower())
            all_chars = set(self.name.lower()) | set(other.name.lower())
            name_similarity = len(common_chars) / len(all_chars) if all_chars else 0
        else:
            name_similarity = 1.0 if self.name == other.name else 0.0

        return {
            "same_name": self.name == other.name,
            "same_identity": self is other,
            "name_similarity": name_similarity,
        }

`annotations = {'name': 'str'}` `class-attribute` ¶

dict() -> new empty dictionary dict(mapping) -> new dictionary initialized from a mapping object's (key, value) pairs dict(iterable) -> new dictionary initialized as if via: d = {} for k, v in iterable: d[k] = v dict(**kwargs) -> new dictionary initialized with the name=value pairs in the keyword argument list. For example: dict(one=1, two=2)

`__attrs_own_setattr__ = False` `class-attribute` ¶

Returns True when the argument is true, False otherwise. The builtins True and False are the only two instances of the class bool. The class bool is a subclass of the class int, and cannot be subclassed.

`__attrs_props__ = ClassProps(is_exception=False, is_slotted=True, has_weakref_slot=True, is_frozen=False, kw_only=<KeywordOnly.NO: 'no'>, collected_fields_by_mro=True, added_init=True, added_repr=True, added_eq=False, added_ordering=False, hashability=<Hashability.LEAVE_ALONE: 'leave_alone'>, added_match_args=True, added_str=False, added_pickling=True, on_setattr_hook=<function pipe.<locals>.wrapped_pipe at 0x7f08471ce840>, field_transformer=None)` `class-attribute` ¶

Effective class properties as derived from parameters to attr.s() or define() decorators.

This is the same data structure that attrs uses internally to decide how to construct the final class.

Warning:

This feature is currently **experimental** and is not covered by our
strict backwards-compatibility guarantees.

Attributes:

Name	Type	Description
`is_exception`	`bool`	Whether the class is treated as an exception class.
`is_slotted`	`bool`	Whether the class is `slotted <slotted classes>`.
`has_weakref_slot`	`bool`	Whether the class has a slot for weak references.
`is_frozen`	`bool`	Whether the class is frozen.
`kw_only`	`KeywordOnly`	Whether / how the class enforces keyword-only arguments on the `__init__` method.
`collected_fields_by_mro`	`bool`	Whether the class fields were collected by method resolution order. That is, correctly but unlike `dataclasses`.
`added_init`	`bool`	Whether the class has an attrs-generated `__init__` method.
`added_repr`	`bool`	Whether the class has an attrs-generated `__repr__` method.
`added_eq`	`bool`	Whether the class has attrs-generated equality methods.
`added_ordering`	`bool`	Whether the class has attrs-generated ordering methods.
`hashability`	`Hashability`	How `hashable <hashing>` the class is.
`added_match_args`	`bool`	Whether the class supports positional `match <match>` over its fields.
`added_str`	`bool`	Whether the class has an attrs-generated `__str__` method.
`added_pickling`	`bool`	Whether the class has attrs-generated `__getstate__` and `__setstate__` methods for `pickle`.
`on_setattr_hook`	`Callable[[Any, Attribute[Any], Any], Any] \| None`	The class's `__setattr__` hook.
`field_transformer`	`Callable[[Attribute[Any]], Attribute[Any]] \| None`	The class's `field transformers <transform-fields>`.

.. versionadded:: 25.4.0

doc = 'An object that represents the same animal/object across multiple detections.\n\nThis allows tracking of unique entities in the video over time and space.\n\nA `Track` may also be used to refer to unique identity classes that span multiple\nvideos, such as `"female mouse"`.\n\nAttributes:\n name: A name given to this track for identification purposes.\n\nNotes:\n `Track`s are compared by identity. This means that unique track objects with the\n same name are considered to be different.\n' `class-attribute` ¶

str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.str() (if defined) or repr(object). encoding defaults to 'utf-8'. errors defaults to 'strict'.

`firstlineno = 332` `class-attribute` ¶

int([x]) -> integer int(x, base=10) -> integer

Convert a number or string to an integer, or return 0 if no arguments are given. If x is a number, return x.int(). For floating-point numbers, this truncates towards zero.

If x is not a number or if base is given, then x must be a string, bytes, or bytearray instance representing an integer literal in the given base. The literal can be preceded by '+' or '-' and be surrounded by whitespace. The base defaults to 10. Valid bases are 0 and 2-36. Base 0 means to interpret the base from the string as an integer iteral.

`__match_args__ = ('name',)` `class-attribute` ¶

Built-in immutable sequence.

If no argument is given, the constructor returns an empty tuple. If iterable is specified the tuple is initialized from iterable's items.

If the argument is a tuple, the return value is the same object.

`module = 'sleap_io.model.instance'` `class-attribute` ¶

str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.str() (if defined) or repr(object). encoding defaults to 'utf-8'. errors defaults to 'strict'.

`slots = ('name', 'weakref')` `class-attribute` ¶

Built-in immutable sequence.

If no argument is given, the constructor returns an empty tuple. If iterable is specified the tuple is initialized from iterable's items.

If the argument is a tuple, the return value is the same object.

`__static_attributes__ = ()` `class-attribute` ¶

Built-in immutable sequence.

If no argument is given, the constructor returns an empty tuple. If iterable is specified the tuple is initialized from iterable's items.

If the argument is a tuple, the return value is the same object.

`weakref` `property` ¶

list of weak references to the object

`init(name='')` ¶

Method generated by attrs for class Track.

Source code in sleap_io/model/instance.py

from sleap_io.model.category import Category, to_category

`repr()` ¶

Method generated by attrs for class Track.

Source code in sleap_io/model/instance.py

"""Data structures for data associated with a single instance such as an animal.

The `Instance` class is a SLEAP data structure that contains a collection of points that
correspond to landmarks within a `Skeleton`.

`PredictedInstance` additionally contains metadata associated with how the instance was
estimated, such as confidence scores.
"""

from __future__ import annotations

from typing import TYPE_CHECKING

import attrs
import numpy as np

`matches(other, method='name')` ¶

Check if this track matches another track.

Parameters:

Name	Type	Description	Default
`other`	`Track`	Another track to compare with.	required
`method`	`str`	Matching method - "name" (match by name) or "identity" (match by object identity).	`'name'`

Returns:

Type	Description
`bool`	True if the tracks match according to the specified method.

Source code in sleap_io/model/instance.py

def matches(self, other: "Track", method: str = "name") -> bool:
    """Check if this track matches another track.

    Args:
        other: Another track to compare with.
        method: Matching method - "name" (match by name) or "identity"
            (match by object identity).

    Returns:
        True if the tracks match according to the specified method.
    """
    if method == "name":
        return self.name == other.name
    elif method == "identity":
        return self is other
    else:
        raise ValueError(f"Unknown matching method: {method}")

`similarity_to(other)` ¶

Calculate similarity metrics with another track.

Parameters:

Name	Type	Description	Default
`other`	`Track`	Another track to compare with.	required

Returns:

Type	Description
`dict[str, any]`	A dictionary with similarity metrics: - 'same_name': Whether the tracks have the same name - 'same_identity': Whether the tracks are the same object - 'name_similarity': Simple string similarity score (0-1)

Source code in sleap_io/model/instance.py

def similarity_to(self, other: "Track") -> dict[str, any]:
    """Calculate similarity metrics with another track.

    Args:
        other: Another track to compare with.

    Returns:
        A dictionary with similarity metrics:
        - 'same_name': Whether the tracks have the same name
        - 'same_identity': Whether the tracks are the same object
        - 'name_similarity': Simple string similarity score (0-1)
    """
    # Calculate simple string similarity
    if self.name and other.name:
        # Simple character overlap similarity
        common_chars = set(self.name.lower()) & set(other.name.lower())
        all_chars = set(self.name.lower()) | set(other.name.lower())
        name_similarity = len(common_chars) / len(all_chars) if all_chars else 0
    else:
        name_similarity = 1.0 if self.name == other.name else 0.0

    return {
        "same_name": self.name == other.name,
        "same_identity": self is other,
        "name_similarity": name_similarity,
    }

`TrackMatchMethod` ¶

Bases: builtins.str, enum.Enum

Methods for matching tracks.

Attributes:

Name	Type	Description
`NAME`		Match tracks by their name attribute.
`IDENTITY`		Match tracks by object identity (same Python object).

Source code in sleap_io/model/matching.py

class TrackMatchMethod(str, Enum):
    """Methods for matching tracks.

    Attributes:
        NAME: Match tracks by their name attribute.
        IDENTITY: Match tracks by object identity (same Python object).
    """

    NAME = "name"
    IDENTITY = "identity"

`IDENTITY = <TrackMatchMethod.IDENTITY: 'identity'>` `class-attribute` ¶

Methods for matching tracks.

Attributes:

Name	Type	Description
`NAME`		Match tracks by their name attribute.
`IDENTITY`		Match tracks by object identity (same Python object).

`NAME = <TrackMatchMethod.NAME: 'name'>` `class-attribute` ¶

Methods for matching tracks.

Attributes:

Name	Type	Description
`NAME`		Match tracks by their name attribute.
`IDENTITY`		Match tracks by object identity (same Python object).

`doc = 'Methods for matching tracks.\n\nAttributes:\n NAME: Match tracks by their name attribute.\n IDENTITY: Match tracks by object identity (same Python object).\n'` `class-attribute` ¶

str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.str() (if defined) or repr(object). encoding defaults to 'utf-8'. errors defaults to 'strict'.

`module = 'sleap_io.model.matching'` `class-attribute` ¶

str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.str() (if defined) or repr(object). encoding defaults to 'utf-8'. errors defaults to 'strict'.

`TrackMatcher` ¶

Matcher for comparing and matching tracks.

Attributes:

Name	Type	Description
`method`		The matching method to use. Can be a TrackMatchMethod enum value or a string that will be converted to the enum. Default is IDENTITY (matches only the same Track object; correctness-first). Use NAME to match by track name.

Methods:

Name	Description
`__eq__`	Method generated by attrs for class TrackMatcher.
`__init__`	Method generated by attrs for class TrackMatcher.
`__repr__`	Method generated by attrs for class TrackMatcher.
`__setattr__`	Method generated by attrs for class TrackMatcher.
`match`	Check if two tracks match according to the configured method.

Source code in sleap_io/model/matching.py

@attrs.define
class TrackMatcher:
    """Matcher for comparing and matching tracks.

    Attributes:
        method: The matching method to use. Can be a TrackMatchMethod enum value
            or a string that will be converted to the enum. Default is IDENTITY
            (matches only the same Track object; correctness-first). Use NAME to
            match by track name.
    """

    method: TrackMatchMethod | str = attrs.field(
        default=TrackMatchMethod.IDENTITY,
        converter=lambda x: TrackMatchMethod(x) if isinstance(x, str) else x,
    )

    def match(self, track1: Track, track2: Track) -> bool:
        """Check if two tracks match according to the configured method."""
        return track1.matches(track2, method=self.method.value)

`annotations = {'method': 'TrackMatchMethod | str'}` `class-attribute` ¶

dict() -> new empty dictionary dict(mapping) -> new dictionary initialized from a mapping object's (key, value) pairs dict(iterable) -> new dictionary initialized as if via: d = {} for k, v in iterable: d[k] = v dict(**kwargs) -> new dictionary initialized with the name=value pairs in the keyword argument list. For example: dict(one=1, two=2)

`__attrs_own_setattr__ = True` `class-attribute` ¶

Returns True when the argument is true, False otherwise. The builtins True and False are the only two instances of the class bool. The class bool is a subclass of the class int, and cannot be subclassed.

`__attrs_props__ = ClassProps(is_exception=False, is_slotted=True, has_weakref_slot=True, is_frozen=False, kw_only=<KeywordOnly.NO: 'no'>, collected_fields_by_mro=True, added_init=True, added_repr=True, added_eq=True, added_ordering=False, hashability=<Hashability.UNHASHABLE: 'unhashable'>, added_match_args=True, added_str=False, added_pickling=True, on_setattr_hook=<function pipe.<locals>.wrapped_pipe at 0x7f08471ce840>, field_transformer=None)` `class-attribute` ¶

Effective class properties as derived from parameters to attr.s() or define() decorators.

This is the same data structure that attrs uses internally to decide how to construct the final class.

Warning:

This feature is currently **experimental** and is not covered by our
strict backwards-compatibility guarantees.

Attributes:

Name	Type	Description
`is_exception`	`bool`	Whether the class is treated as an exception class.
`is_slotted`	`bool`	Whether the class is `slotted <slotted classes>`.
`has_weakref_slot`	`bool`	Whether the class has a slot for weak references.
`is_frozen`	`bool`	Whether the class is frozen.
`kw_only`	`KeywordOnly`	Whether / how the class enforces keyword-only arguments on the `__init__` method.
`collected_fields_by_mro`	`bool`	Whether the class fields were collected by method resolution order. That is, correctly but unlike `dataclasses`.
`added_init`	`bool`	Whether the class has an attrs-generated `__init__` method.
`added_repr`	`bool`	Whether the class has an attrs-generated `__repr__` method.
`added_eq`	`bool`	Whether the class has attrs-generated equality methods.
`added_ordering`	`bool`	Whether the class has attrs-generated ordering methods.
`hashability`	`Hashability`	How `hashable <hashing>` the class is.
`added_match_args`	`bool`	Whether the class supports positional `match <match>` over its fields.
`added_str`	`bool`	Whether the class has an attrs-generated `__str__` method.
`added_pickling`	`bool`	Whether the class has attrs-generated `__getstate__` and `__setstate__` methods for `pickle`.
`on_setattr_hook`	`Callable[[Any, Attribute[Any], Any], Any] \| None`	The class's `__setattr__` hook.
`field_transformer`	`Callable[[Attribute[Any]], Attribute[Any]] \| None`	The class's `field transformers <transform-fields>`.

.. versionadded:: 25.4.0

`doc = 'Matcher for comparing and matching tracks.\n\nAttributes:\n method: The matching method to use. Can be a TrackMatchMethod enum value\n or a string that will be converted to the enum. Default is IDENTITY\n (matches only the same Track object; correctness-first). Use NAME to\n match by track name.\n'` `class-attribute` ¶

str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.str() (if defined) or repr(object). encoding defaults to 'utf-8'. errors defaults to 'strict'.

`firstlineno = 883` `class-attribute` ¶

int([x]) -> integer int(x, base=10) -> integer

Convert a number or string to an integer, or return 0 if no arguments are given. If x is a number, return x.int(). For floating-point numbers, this truncates towards zero.

If x is not a number or if base is given, then x must be a string, bytes, or bytearray instance representing an integer literal in the given base. The literal can be preceded by '+' or '-' and be surrounded by whitespace. The base defaults to 10. Valid bases are 0 and 2-36. Base 0 means to interpret the base from the string as an integer iteral.

`__match_args__ = ('method',)` `class-attribute` ¶

Built-in immutable sequence.

If no argument is given, the constructor returns an empty tuple. If iterable is specified the tuple is initialized from iterable's items.

If the argument is a tuple, the return value is the same object.

`module = 'sleap_io.model.matching'` `class-attribute` ¶

str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.str() (if defined) or repr(object). encoding defaults to 'utf-8'. errors defaults to 'strict'.

`slots = ('method', 'weakref')` `class-attribute` ¶

Built-in immutable sequence.

If no argument is given, the constructor returns an empty tuple. If iterable is specified the tuple is initialized from iterable's items.

If the argument is a tuple, the return value is the same object.

`__static_attributes__ = ()` `class-attribute` ¶

Built-in immutable sequence.

If no argument is given, the constructor returns an empty tuple. If iterable is specified the tuple is initialized from iterable's items.

If the argument is a tuple, the return value is the same object.

`weakref` `property` ¶

list of weak references to the object

`eq(other)` ¶

Method generated by attrs for class TrackMatcher.

Source code in sleap_io/model/matching.py

automatic strategies.
"""

from __future__ import annotations

from enum import Enum

`init(method=<TrackMatchMethod.IDENTITY: 'identity'>)` ¶

Method generated by attrs for class TrackMatcher.

Source code in sleap_io/model/matching.py

from typing import TYPE_CHECKING, Any

import attrs

`repr()` ¶

Method generated by attrs for class TrackMatcher.

Source code in sleap_io/model/matching.py

"""Unified matcher system for comparing and matching data structures during merging.

This module provides configurable matchers for comparing skeletons, instances, tracks,
and videos during merge operations. The matchers use various strategies to determine
when data structures should be considered equivalent during merging.

Key features:
- Skeleton matching: exact, structure-based, overlap, and subset matching
- Instance matching: spatial proximity, track identity, and bounding box IoU
- Track matching: by name or object identity
- Identity matching: by name or object identity
- Category matching: by name or object identity
- Video matching: path, basename, content, and auto matching

Video matching supports path-based, filename-based, content-based, and

`setattr(name, val)` ¶

Method generated by attrs for class TrackMatcher.

Source code in sleap_io/model/matching.py

        return match

# IMAGE MATCHING: Compare frame images (opt-in)
if self.compare_images:
    match = self._match_by_images(incoming, viable)
    if match is not None:
        return match

# No match found

`match(track1, track2)` ¶

Check if two tracks match according to the configured method.

Source code in sleap_io/model/matching.py

def match(self, track1: Track, track2: Track) -> bool:
    """Check if two tracks match according to the configured method."""
    return track1.matches(track2, method=self.method.value)

`Video` ¶

Video class used by sleap to represent videos and data associated with them.

This class is used to store information regarding a video and its components. It is used to store the video's filename, shape, and the video's backend.

To create a Video object, use the from_filename method which will select the backend appropriately.

Attributes:

Name	Type	Description
`filename`		The filename(s) of the video. Supported extensions: "mp4", "avi", "mov", "mj2", "mkv", "h5", "hdf5", "slp", "png", "jpg", "jpeg", "tif", "tiff", "bmp", "seq". If the filename is a list, a list of image filenames are expected. If filename is a folder, it will be searched for images.
`backend`		An object that implements the basic methods for reading and manipulating frames of a specific video type.
`backend_metadata`		A dictionary of metadata specific to the backend. This is useful for storing metadata that requires an open backend (e.g., shape information) without having access to the video file itself.
`source_video`		The source video object if this is a proxy video. This is present when the video contains an embedded subset of frames from another video.
`open_backend`		Whether to open the backend when the video is available. If `True` (the default), the backend will be automatically opened if the video exists. Set this to `False` when you want to manually open the backend, or when the you know the video file does not exist and you want to avoid trying to open the file.
`_exists_cache`		Per-instance TTL cache for the result of `exists()` when the `filename` is a remote URL. Keyed by `(filename, dataset)` and storing `(exists_bool, monotonic_timestamp)`. This avoids issuing a network probe on every call (e.g. from the `is_open` property, which GUIs poll on each render). The TTL defaults to 60 seconds and can be overridden via the `SLEAP_IO_EXISTS_TTL` environment variable. The cache is cleared on `replace_filename`.

Notes

Instances of this class are hashed by identity, not by value. This means that two Video instances with the same attributes will NOT be considered equal in a set or dict.

Media Video Plugin Support

For media files (mp4, avi, etc.), the following plugins are supported: - "opencv": Uses OpenCV (cv2) for video reading - "FFMPEG": Uses imageio-ffmpeg for video reading - "pyav": Uses PyAV for video reading

Plugin aliases (case-insensitive): - opencv: "opencv", "cv", "cv2", "ocv" - FFMPEG: "FFMPEG", "ffmpeg", "imageio-ffmpeg", "imageio_ffmpeg" - pyav: "pyav", "av"

Plugin selection priority: 1. Explicitly specified plugin parameter 2. Backend metadata plugin value 3. Global default (set via sio.set_default_video_plugin) 4. Auto-detection based on available packages

`EXTS = ('mp4', 'avi', 'mov', 'mj2', 'mkv', 'h5', 'hdf5', 'slp', 'png', 'jpg', 'jpeg', 'tif', 'tiff', 'bmp', 'seq')` `class-attribute` ¶

Built-in immutable sequence.

If no argument is given, the constructor returns an empty tuple. If iterable is specified the tuple is initialized from iterable's items.

If the argument is a tuple, the return value is the same object.

`annotations = {'filename': 'str | list[str]', 'backend': 'VideoBackend | None', 'backend_metadata': 'dict[str, any]', 'source_video': "'Video | None'", 'open_backend': 'bool', '_exists_cache': 'dict[tuple[str, str | None], tuple[bool, float]]', '_url_headers': 'dict[str, str] | None', '_url_stream_mode': 'str'}` `class-attribute` ¶

dict() -> new empty dictionary dict(mapping) -> new dictionary initialized from a mapping object's (key, value) pairs dict(iterable) -> new dictionary initialized as if via: d = {} for k, v in iterable: d[k] = v dict(**kwargs) -> new dictionary initialized with the name=value pairs in the keyword argument list. For example: dict(one=1, two=2)

`__attrs_own_setattr__ = False` `class-attribute` ¶

Returns True when the argument is true, False otherwise. The builtins True and False are the only two instances of the class bool. The class bool is a subclass of the class int, and cannot be subclassed.

`__attrs_props__ = ClassProps(is_exception=False, is_slotted=True, has_weakref_slot=True, is_frozen=False, kw_only=<KeywordOnly.NO: 'no'>, collected_fields_by_mro=True, added_init=True, added_repr=False, added_eq=False, added_ordering=False, hashability=<Hashability.LEAVE_ALONE: 'leave_alone'>, added_match_args=True, added_str=False, added_pickling=True, on_setattr_hook=<function pipe.<locals>.wrapped_pipe at 0x7f08471ce840>, field_transformer=None)` `class-attribute` ¶

Effective class properties as derived from parameters to attr.s() or define() decorators.

This is the same data structure that attrs uses internally to decide how to construct the final class.

Warning:

This feature is currently **experimental** and is not covered by our
strict backwards-compatibility guarantees.

Attributes:

Name	Type	Description
`is_exception`	`bool`	Whether the class is treated as an exception class.
`is_slotted`	`bool`	Whether the class is `slotted <slotted classes>`.
`has_weakref_slot`	`bool`	Whether the class has a slot for weak references.
`is_frozen`	`bool`	Whether the class is frozen.
`kw_only`	`KeywordOnly`	Whether / how the class enforces keyword-only arguments on the `__init__` method.
`collected_fields_by_mro`	`bool`	Whether the class fields were collected by method resolution order. That is, correctly but unlike `dataclasses`.
`added_init`	`bool`	Whether the class has an attrs-generated `__init__` method.
`added_repr`	`bool`	Whether the class has an attrs-generated `__repr__` method.
`added_eq`	`bool`	Whether the class has attrs-generated equality methods.
`added_ordering`	`bool`	Whether the class has attrs-generated ordering methods.
`hashability`	`Hashability`	How `hashable <hashing>` the class is.
`added_match_args`	`bool`	Whether the class supports positional `match <match>` over its fields.
`added_str`	`bool`	Whether the class has an attrs-generated `__str__` method.
`added_pickling`	`bool`	Whether the class has attrs-generated `__getstate__` and `__setstate__` methods for `pickle`.
`on_setattr_hook`	`Callable[[Any, Attribute[Any], Any], Any] \| None`	The class's `__setattr__` hook.
`field_transformer`	`Callable[[Attribute[Any]], Attribute[Any]] \| None`	The class's `field transformers <transform-fields>`.

.. versionadded:: 25.4.0

doc = '`Video` class used by sleap to represent videos and data associated with them.\n\nThis class is used to store information regarding a video and its components.\nIt is used to store the video\'s `filename`, `shape`, and the video\'s `backend`.\n\nTo create a `Video` object, use the `from_filename` method which will select the\nbackend appropriately.\n\nAttributes:\n filename: The filename(s) of the video. Supported extensions: "mp4", "avi",\n "mov", "mj2", "mkv", "h5", "hdf5", "slp", "png", "jpg", "jpeg", "tif",\n "tiff", "bmp", "seq". If the filename is a list, a list of image filenames\n are expected. If filename is a folder, it will be searched for images.\n backend: An object that implements the basic methods for reading and\n manipulating frames of a specific video type.\n backend_metadata: A dictionary of metadata specific to the backend. This is\n useful for storing metadata that requires an open backend (e.g., shape\n information) without having access to the video file itself.\n source_video: The source video object if this is a proxy video. This is present\n when the video contains an embedded subset of frames from another video.\n open_backend: Whether to open the backend when the video is available. If `True`\n (the default), the backend will be automatically opened if the video exists.\n Set this to `False` when you want to manually open the backend, or when the\n you know the video file does not exist and you want to avoid trying to open\n the file.\n _exists_cache: Per-instance TTL cache for the result of `exists()` when the\n `filename` is a remote URL. Keyed by `(filename, dataset)` and storing\n `(exists_bool, monotonic_timestamp)`. This avoids issuing a network probe\n on every call (e.g. from the `is_open` property, which GUIs poll on each\n render). The TTL defaults to 60 seconds and can be overridden via the\n `SLEAP_IO_EXISTS_TTL` environment variable. The cache is cleared on\n `replace_filename`.\n\nNotes:\n Instances of this class are hashed by identity, not by value. This means that\n two `Video` instances with the same attributes will NOT be considered equal in a\n set or dict.\n\nMedia Video Plugin Support:\n For media files (mp4, avi, etc.), the following plugins are supported:\n - "opencv": Uses OpenCV (cv2) for video reading\n - "FFMPEG": Uses imageio-ffmpeg for video reading\n - "pyav": Uses PyAV for video reading\n\n Plugin aliases (case-insensitive):\n - opencv: "opencv", "cv", "cv2", "ocv"\n - FFMPEG: "FFMPEG", "ffmpeg", "imageio-ffmpeg", "imageio_ffmpeg"\n - pyav: "pyav", "av"\n\n Plugin selection priority:\n 1. Explicitly specified plugin parameter\n 2. Backend metadata plugin value\n 3. Global default (set via sio.set_default_video_plugin)\n 4. Auto-detection based on available packages\n\nSee Also:\n VideoBackend: The backend interface for reading video data.\n sleap_io.set_default_video_plugin: Set global default plugin.\n sleap_io.get_default_video_plugin: Get current default plugin.\n' `class-attribute` ¶

str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.str() (if defined) or repr(object). encoding defaults to 'utf-8'. errors defaults to 'strict'.

`firstlineno = 102` `class-attribute` ¶

int([x]) -> integer int(x, base=10) -> integer

Convert a number or string to an integer, or return 0 if no arguments are given. If x is a number, return x.int(). For floating-point numbers, this truncates towards zero.

If x is not a number or if base is given, then x must be a string, bytes, or bytearray instance representing an integer literal in the given base. The literal can be preceded by '+' or '-' and be surrounded by whitespace. The base defaults to 10. Valid bases are 0 and 2-36. Base 0 means to interpret the base from the string as an integer iteral.

`__match_args__ = ('filename', 'backend', 'backend_metadata', 'source_video', 'open_backend')` `class-attribute` ¶

Built-in immutable sequence.

If no argument is given, the constructor returns an empty tuple. If iterable is specified the tuple is initialized from iterable's items.

If the argument is a tuple, the return value is the same object.

`module = 'sleap_io.model.video'` `class-attribute` ¶

str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.str() (if defined) or repr(object). encoding defaults to 'utf-8'. errors defaults to 'strict'.

`slots = ('filename', 'backend', 'backend_metadata', 'source_video', 'open_backend', '_exists_cache', '_url_headers', '_url_stream_mode', 'weakref')` `class-attribute` ¶

Built-in immutable sequence.

If no argument is given, the constructor returns an empty tuple. If iterable is specified the tuple is initialized from iterable's items.

If the argument is a tuple, the return value is the same object.

`__static_attributes__ = ('backend', 'filename')` `class-attribute` ¶

Built-in immutable sequence.

If no argument is given, the constructor returns an empty tuple. If iterable is specified the tuple is initialized from iterable's items.

If the argument is a tuple, the return value is the same object.

`weakref` `property` ¶

list of weak references to the object

`crop_fill` `property` ¶

The out-of-bounds fill value for this video's crop (0 if uncropped).

`crop_rect` `property` ¶

Crop rect (x1, y1, x2, y2) in source coords, or None if uncropped.

`fps` `property` ¶

Return the frames per second of the video.

For MediaVideo backends, this reads FPS from the video container metadata. For other backends (ImageVideo, HDF5Video, TiffVideo), this returns the explicitly set value or None if not set.

Returns:

Type	Description
	The FPS if known, or None if unavailable/unknown.

`grayscale` `property` ¶

Return whether the video is grayscale.

If the video backend is not set or it cannot determine whether the video is grayscale, this will return None.

`is_cropped` `property` ¶

Whether this video is a virtual crop of another video.

`is_open` `property` ¶

Check if the video backend is open.

`original_video` `property` ¶

The root video in the provenance chain.

For embedded videos, this returns the ultimate source video by traversing the source_video chain. Returns None if this video has no source_video (i.e., it IS an original).

This property is computed by following the source_video chain to find the root. For a single-level embedding (A embeds from B), original_video returns B. For multi-level embedding (A <- B <- C), it returns C.

`shape` `property` ¶

Return the shape of the video as (num_frames, height, width, channels).

If the video backend is not set or it cannot determine the shape of the video, this will return None.

`__attrs_post_init__()` ¶

Post init syntactic sugar.

Source code in sleap_io/model/video.py

def __attrs_post_init__(self):
    """Post init syntactic sugar."""
    if self.open_backend and self.backend is None and self.exists():
        try:
            self.open()
        except Exception:
            # If we can't open the backend, just ignore it for now so we don't
            # prevent the user from building the Video object entirely.
            pass

`deepcopy(memo)` ¶

Deep copy the video object.

Source code in sleap_io/model/video.py

def __deepcopy__(self, memo):
    """Deep copy the video object."""
    if id(self) in memo:
        return memo[id(self)]

    reopen = False
    if self.is_open:
        reopen = True
        self.close()

    new_video = Video(
        filename=self.filename,
        backend=None,
        backend_metadata=self.backend_metadata.copy(),
        source_video=self.source_video,
        open_backend=self.open_backend,
    )

    memo[id(self)] = new_video

    if reopen:
        self.open()

    return new_video

`getitem(inds)` ¶

Return the frames of the video at the given indices.

Parameters:

Name	Type	Description	Default
`inds`	`int \| list[int] \| slice`	Index or list of indices of frames to read.	required

Returns:

Type	Description
`ndarray`	Frame or frames as a numpy array of shape `(height, width, channels)` if a scalar index is provided, or `(frames, height, width, channels)` if a list of indices is provided.

See also: VideoBackend.get_frame, VideoBackend.get_frames

Source code in sleap_io/model/video.py

def __getitem__(self, inds: int | list[int] | slice) -> np.ndarray:
    """Return the frames of the video at the given indices.

    Args:
        inds: Index or list of indices of frames to read.

    Returns:
        Frame or frames as a numpy array of shape `(height, width, channels)` if a
        scalar index is provided, or `(frames, height, width, channels)` if a list
        of indices is provided.

    See also: VideoBackend.get_frame, VideoBackend.get_frames
    """
    if not self.is_open:
        if self.open_backend:
            self.open()
        else:
            raise ValueError(
                "Video backend is not open. Call video.open() or set "
                "video.open_backend to True to do automatically on frame read."
            )
    return self.backend[inds]

`init(filename, backend=None, backend_metadata=NOTHING, source_video=None, open_backend=True)` ¶

Method generated by attrs for class Video.

Source code in sleap_io/model/video.py

"""Data model for videos.

The `Video` class is a SLEAP data structure that stores information regarding
a video and its components used in SLEAP.
"""

from __future__ import annotations

import os
import time
from pathlib import Path
from typing import Any

`len()` ¶

Return the length of the video as the number of frames.

Source code in sleap_io/model/video.py

def __len__(self) -> int:
    """Return the length of the video as the number of frames."""
    shape = self.shape
    return 0 if shape is None else shape[0]

`repr()` ¶

Informal string representation (for print or format).

Source code in sleap_io/model/video.py

def __repr__(self) -> str:
    """Informal string representation (for print or format)."""
    dataset = (
        f"dataset={self.backend.dataset}, "
        if getattr(self.backend, "dataset", "")
        else ""
    )
    return (
        "Video("
        f'filename="{self.filename}", '
        f"shape={self.shape}, "
        f"{dataset}"
        f"backend={type(self.backend).__name__}"
        ")"
    )

`str()` ¶

Informal string representation (for print or format).

Source code in sleap_io/model/video.py

def __str__(self) -> str:
    """Informal string representation (for print or format)."""
    return self.__repr__()

`apply_crop(path, *, frame_inds=None, fps=None, video_kwargs=None)` ¶

Bake this video's virtual crop into a new physical video file.

Materializes the cropped frames (self[i], already cropped by the virtual :class:~sleap_io.io.video_reading.CropVideoBackend) to path via :class:~sleap_io.io.video_writing.VideoWriter. The crop becomes physical: the returned video has no CropVideoBackend / /video_crops entry. baked.shape equals this video's cropped shape when the cropped width and height are multiples of 16; otherwise the H.264 encoder pads the bottom/right edges up to the next multiple of 16 (the macro-block size), so baked.shape may exceed the cropped shape on those edges. The top-left content is preserved, so coordinates stay aligned regardless.

This operation is coordinate-neutral. A virtual crop already presents cropped-frame coordinates, so baking the cropped pixels does not change any point coordinates (unlike sio transform --crop, which applies a new crop and adjusts coordinates).

Provenance is preserved: the returned video's source_video is the uncropped original — self.source_video (the parent a virtual crop is created against), or, for a manually-built crop with no parent, an uncropped view reconstructed from the crop backend's inner. So baked.source_video.shape is the uncropped shape while baked.shape is the cropped shape, and baked.grayscale is carried from this video.

Parameters:

Name	Type	Description	Default
`path`	`str \| Path`	Path to the new video file. Should end in MP4.	required
`frame_inds`	`list[int] \| ndarray \| None`	Frame indices to bake. Can be specified as a list or array of frame integers. If not specified, bakes all video frames.	`None`
`fps`	`float \| None`	Frames per second for the output video. If not specified, uses this video's FPS if available, otherwise defaults to 30.	`None`
`video_kwargs`	`dict[str, Any] \| None`	A dictionary of keyword arguments to provide to `sio.save_video` for video compression.	`None`

Returns:

Type	Description
`Video`	A new `Video` pointing to the baked file, with `source_video` set to the uncropped original (or this video) and `grayscale` carried from this video.

Raises:

Type	Description
`ValueError`	If this video has no virtual crop to apply (i.e., :meth:`_crop_tuple` returns `None`). Use :meth:`save` to re-encode an uncropped video.

Source code in sleap_io/model/video.py

def apply_crop(
    self,
    path: str | Path,
    *,
    frame_inds: list[int] | np.ndarray | None = None,
    fps: float | None = None,
    video_kwargs: dict[str, Any] | None = None,
) -> "Video":
    """Bake this video's virtual crop into a new physical video file.

    Materializes the cropped frames (``self[i]``, already cropped by the
    virtual :class:`~sleap_io.io.video_reading.CropVideoBackend`) to ``path``
    via :class:`~sleap_io.io.video_writing.VideoWriter`. The crop becomes
    physical: the returned video has no ``CropVideoBackend`` / ``/video_crops``
    entry. ``baked.shape`` equals this video's cropped shape when the cropped
    width and height are multiples of 16; otherwise the H.264 encoder pads the
    bottom/right edges up to the next multiple of 16 (the macro-block size),
    so ``baked.shape`` may exceed the cropped shape on those edges. The
    top-left content is preserved, so coordinates stay aligned regardless.

    This operation is coordinate-neutral. A virtual crop already presents
    cropped-frame coordinates, so baking the cropped pixels does not change
    any point coordinates (unlike ``sio transform --crop``, which applies a
    new crop and adjusts coordinates).

    Provenance is preserved: the returned video's ``source_video`` is the
    uncropped original — ``self.source_video`` (the parent a virtual crop is
    created against), or, for a manually-built crop with no parent, an
    uncropped view reconstructed from the crop backend's inner. So
    ``baked.source_video.shape`` is the uncropped shape while ``baked.shape``
    is the cropped shape, and ``baked.grayscale`` is carried from this video.

    Args:
        path: Path to the new video file. Should end in MP4.
        frame_inds: Frame indices to bake. Can be specified as a list or array
            of frame integers. If not specified, bakes all video frames.
        fps: Frames per second for the output video. If not specified, uses
            this video's FPS if available, otherwise defaults to 30.
        video_kwargs: A dictionary of keyword arguments to provide to
            ``sio.save_video`` for video compression.

    Returns:
        A new ``Video`` pointing to the baked file, with ``source_video`` set
        to the uncropped original (or this video) and ``grayscale`` carried
        from this video.

    Raises:
        ValueError: If this video has no virtual crop to apply (i.e.,
            :meth:`_crop_tuple` returns ``None``). Use :meth:`save` to
            re-encode an uncropped video.
    """
    if self._crop_tuple() is None:
        raise ValueError(
            "apply_crop requires a cropped video (a virtual crop created via "
            "Video.crop / Video.from_crop), but this video has no crop to "
            "apply. Use Video.save to re-encode an uncropped video."
        )

    video_kwargs = {} if video_kwargs is None else video_kwargs.copy()
    if frame_inds is None:
        # A crop over a SPARSELY embedded video (frame_map keys are not the dense
        # range 0..N-1, e.g. {5, 9}) cannot be baked by default: writing the frames
        # compacts them to 0..k-1, so any labeled frame referencing a source index
        # (5, 9) would dangle. Refuse with a clear error rather than crash or
        # silently misalign. An explicit frame_inds bypasses this for advanced use.
        inner = getattr(self.backend, "inner", None)
        frame_map = getattr(inner, "frame_map", None)
        if frame_map:
            keys = sorted(frame_map.keys())
            if keys != list(range(len(keys))):
                raise ValueError(
                    "Cannot bake a virtual crop over a video with sparsely "
                    f"embedded frames (frame_map keys {keys}): baking would "
                    "compact frames to a contiguous range and break frame_idx "
                    "references. Pass explicit frame_inds to override, or "
                    "materialize from the original source video."
                )
        frame_inds = np.arange(len(self))

    # Use this video's FPS if not explicitly specified.
    if fps is None:
        fps = self.fps
    if fps is not None and "fps" not in video_kwargs:
        video_kwargs["fps"] = fps

    with VideoWriter(path, **video_kwargs) as vw:
        for frame_ind in frame_inds:
            vw(self[frame_ind])

    baked = Video.from_filename(path, grayscale=self.grayscale)
    # Provenance: the uncropped original. Walk past any still-virtual crop
    # ancestors (a flattened crop-of-crop's source_video may itself be a crop)
    # to the first uncropped ancestor. For a manually-built crop with no parent,
    # reconstruct an uncropped view from the crop backend's inner, so
    # source_video is never a cropped video.
    source = self.source_video
    while source is not None and source._crop_tuple() is not None:
        source = source.source_video
    if source is None:
        inner = getattr(self.backend, "inner", None)
        source = (
            Video(filename=inner.filename, backend=inner)
            if inner is not None
            else self
        )
    baked.source_video = source
    return baked

`close()` ¶

Close the video backend.

Source code in sleap_io/model/video.py

def close(self):
    """Close the video backend."""
    if self.backend is not None:
        # Try to remember values from previous backend if available and not
        # specified.
        try:
            self.backend_metadata["dataset"] = getattr(
                self.backend, "dataset", None
            )
            self.backend_metadata["grayscale"] = getattr(
                self.backend, "grayscale", None
            )
            self.backend_metadata["shape"] = getattr(self.backend, "shape", None)
            self.backend_metadata["fps"] = getattr(self.backend, "fps", None)
            # Persist the crop so a Video cropped in-memory (never loaded
            # from disk) survives a close()->open() and deepcopy: open()
            # re-wraps from these keys (the closed-path shape above is
            # already the cropped shape).
            from sleap_io.io.video_reading import CropVideoBackend

            if isinstance(self.backend, CropVideoBackend):
                self.backend_metadata["crop"] = list(self.backend.crop)
                self.backend_metadata["crop_fill"] = self.backend.fill
        except Exception:
            pass

        # Deterministically release the backend's open handles (the cached
        # reader and, for a remote HDF5Video, the fsspec URL file-like)
        # rather than relying on garbage collection.
        try:
            self.backend.close()
        except Exception:
            pass

        del self.backend
        self.backend = None

`crop(crop=None, *, bbox=None, roi=None, center=None, size=None, margin=0, fill=0, share_decode=True)` ¶

Return a virtual, on-read cropped view of this video.

Exactly one region spec must be given: crop (explicit (x1, y1, x2, y2) rect), bbox, roi (its axis-aligned bounds + margin), or (center, size) for a fixed-size centered/ centroid-following window. The returned Video shares no pixels with this one; frames are decoded on read and cropped (byte-identical to :func:sleap_io.transform.frame.crop_frame). Out-of-bounds regions are pad-filled with fill (never clamped), so the output shape is always exactly (y2 - y1, x2 - x1).

The crop composes (FLATTENS when fills agree and the region is in-bounds) with any existing crop on this video via :meth:CropVideoBackend.wrap. source_video is set to this video for provenance. When share_decode (the default), the new crop reuses this video's backend instance as the shared inner so a mosaic of tiles over one file decodes each source frame once; in that case the new tile does NOT own the shared decoder (this video does).

Parameters:

Name	Type	Description	Default
`crop`	`tuple[int, int, int, int] \| None`	Explicit crop region `(x1, y1, x2, y2)`, `x2`/`y2` exclusive.	`None`
`bbox`	`tuple[float, float, float, float] \| None`	A bounding box `(x1, y1, x2, y2)`; bounds may be float.	`None`
`roi`	`object \| None`	Any object exposing axis-aligned `.bounds` as `(minx, miny, maxx, maxy)` (e.g. a shapely geometry).	`None`
`center`	`tuple[float, float] \| None`	Window center `(cx, cy)` (used with `size`).	`None`
`size`	`tuple[int, int] \| None`	Fixed output `(width, height)` (used with `center`).	`None`
`margin`	`int`	Pixels added around the `roi` bounds on every side.	`0`
`fill`	`int \| tuple[int, ...]`	Fill value for out-of-bounds regions.	`0`
`share_decode`	`bool`	If `True` (the default), reuse this video's backend as the shared inner so tiles decode each frame once; the new tile does not own the shared decoder.	`True`

Returns:

Type	Description
`Video`	A new `Video` exposing the cropped view.

Source code in sleap_io/model/video.py

def crop(
    self,
    crop: tuple[int, int, int, int] | None = None,
    *,
    bbox: tuple[float, float, float, float] | None = None,
    roi: object | None = None,
    center: tuple[float, float] | None = None,
    size: tuple[int, int] | None = None,
    margin: int = 0,
    fill: int | tuple[int, ...] = 0,
    share_decode: bool = True,
) -> "Video":
    """Return a virtual, on-read cropped view of this video.

    Exactly one region spec must be given: ``crop`` (explicit
    ``(x1, y1, x2, y2)`` rect), ``bbox``, ``roi`` (its axis-aligned bounds +
    ``margin``), or (``center``, ``size``) for a fixed-size centered/
    centroid-following window. The returned ``Video`` shares no pixels with
    this one; frames are decoded on read and cropped (byte-identical to
    :func:`sleap_io.transform.frame.crop_frame`). Out-of-bounds regions are
    pad-filled with ``fill`` (never clamped), so the output shape is always
    exactly ``(y2 - y1, x2 - x1)``.

    The crop composes (FLATTENS when fills agree and the region is in-bounds)
    with any existing crop on this video via
    :meth:`CropVideoBackend.wrap`. ``source_video`` is set to this video for
    provenance. When ``share_decode`` (the default), the new crop reuses this
    video's backend instance as the shared inner so a mosaic of tiles over
    one file decodes each source frame once; in that case the new tile does
    NOT own the shared decoder (this video does).

    Args:
        crop: Explicit crop region ``(x1, y1, x2, y2)``, ``x2``/``y2``
            exclusive.
        bbox: A bounding box ``(x1, y1, x2, y2)``; bounds may be float.
        roi: Any object exposing axis-aligned ``.bounds`` as
            ``(minx, miny, maxx, maxy)`` (e.g. a shapely geometry).
        center: Window center ``(cx, cy)`` (used with ``size``).
        size: Fixed output ``(width, height)`` (used with ``center``).
        margin: Pixels added around the ``roi`` bounds on every side.
        fill: Fill value for out-of-bounds regions.
        share_decode: If ``True`` (the default), reuse this video's backend
            as the shared inner so tiles decode each frame once; the new tile
            does not own the shared decoder.

    Returns:
        A new ``Video`` exposing the cropped view.
    """
    from sleap_io.io.video_reading import CropVideoBackend

    rect = _resolve_crop_rect(crop, bbox, roi, center, size, margin)
    if self.backend is None and self.open_backend:
        self.open()
    if self.backend is None:
        raise ValueError(
            "Cannot crop a video with no open backend. Open it first (set "
            "open_backend=True or call .open()) before cropping."
        )
    inner = self.backend
    cropped_backend = CropVideoBackend.wrap(
        inner=inner, crop=rect, fill=fill, owns_inner=not share_decode
    )

    cropped = Video(
        filename=self.filename,
        backend=cropped_backend,
        source_video=self,
        open_backend=self.open_backend,
    )

    x1, y1, x2, y2 = cropped_backend.crop
    src_shape = self.shape
    cropped.backend_metadata = {
        **self.backend_metadata,
        "shape": (src_shape[0], y2 - y1, x2 - x1, src_shape[3])
        if src_shape is not None
        else None,
        # The uncropped source shape, so a closed re-serialize keeps videos_json
        # describing the full frame even without a live source_video (D-120/DI-2).
        "source_shape": list(src_shape) if src_shape is not None else None,
        # COMPOSED source rect from wrap (D-120): keeps open/closed crop keys
        # identical and root-canonical, and survives close()->open().
        "crop": list(cropped_backend.crop),
        "crop_fill": cropped_backend.fill,
    }
    return cropped

`deduplicate_with(other)` ¶

Create a new video with duplicate images removed.

This method is specifically for ImageVideo backends (image sequences).

Parameters:

Name	Type	Description	Default
`other`	`Video`	Another video to deduplicate against. Must also be ImageVideo.	required

Returns:

Type	Description
`Video`	A new Video object with duplicate images removed from this video, or None if all images were duplicates.

Raises:

Type	Description
`ValueError`	If either video is not an ImageVideo backend.

Notes

Only works with ImageVideo backends where filename is a list. Images are considered duplicates if they have the same basename. The returned video contains only images from this video that are not present in the other video.

Source code in sleap_io/model/video.py

def deduplicate_with(self, other: "Video") -> "Video":
    """Create a new video with duplicate images removed.

    This method is specifically for ImageVideo backends (image sequences).

    Args:
        other: Another video to deduplicate against. Must also be ImageVideo.

    Returns:
        A new Video object with duplicate images removed from this video,
        or None if all images were duplicates.

    Raises:
        ValueError: If either video is not an ImageVideo backend.

    Notes:
        Only works with ImageVideo backends where filename is a list.
        Images are considered duplicates if they have the same basename.
        The returned video contains only images from this video that are
        not present in the other video.
    """
    if not isinstance(self.filename, list):
        raise ValueError("deduplicate_with only works with ImageVideo backends")
    if not isinstance(other.filename, list):
        raise ValueError("Other video must also be ImageVideo backend")

    # Get basenames from other video
    other_basenames = set(Path(f).name for f in other.filename)

    # Keep only non-duplicate images
    deduplicated_paths = [
        f for f in self.filename if Path(f).name not in other_basenames
    ]

    if not deduplicated_paths:
        # All images were duplicates
        return None

    # Create new video with deduplicated images
    return Video.from_filename(deduplicated_paths, grayscale=self.grayscale)

`exists(check_all=False, dataset=None)` ¶

Check if the video file exists and is accessible.

Parameters:

Name	Type	Description	Default
`check_all`	`bool`	If `True`, check that all filenames in a list exist. If `False` (the default), check that the first filename exists.	`False`
`dataset`	`str \| None`	Name of dataset in HDF5 file. If specified, this will function will return `False` if the dataset does not exist.	`None`

Returns:

Type	Description
`bool`	`True` if the file exists and is accessible, `False` otherwise.

Source code in sleap_io/model/video.py

def exists(self, check_all: bool = False, dataset: str | None = None) -> bool:
    """Check if the video file exists and is accessible.

    Args:
        check_all: If `True`, check that all filenames in a list exist. If `False`
            (the default), check that the first filename exists.
        dataset: Name of dataset in HDF5 file. If specified, this will function will
            return `False` if the dataset does not exist.

    Returns:
        `True` if the file exists and is accessible, `False` otherwise.
    """
    if isinstance(self.filename, list):
        if check_all:
            for f in self.filename:
                if not is_file_accessible(f):
                    return False
            return True
        else:
            return is_file_accessible(self.filename[0])

    # URL fast path: must run BEFORE `is_file_accessible`, which treats the
    # filename as a local path and would spuriously return False for a URL.
    from sleap_io.io._remote import _is_url

    if _is_url(self.filename):
        return self._url_exists(dataset)

    file_is_accessible = is_file_accessible(self.filename)
    if not file_is_accessible:
        # Check if it's a directory (ImageVideo source)
        if Path(self.filename).is_dir():
            return True
        return False

    if dataset is None or dataset == "":
        dataset = self.backend_metadata.get("dataset", None)

    if dataset is not None and dataset != "":
        has_dataset = False
        if (
            self.backend is not None
            and type(self.backend) is HDF5Video
            and self.backend._open_reader is not None
        ):
            has_dataset = dataset in self.backend._open_reader
        else:
            with h5py.File(self.filename, "r") as f:
                has_dataset = dataset in f
        return has_dataset

    return True

`frame_to_seconds(frame_idx)` ¶

Convert a frame index to timestamp in seconds.

Parameters:

Name	Type	Description	Default
`frame_idx`	`int`	Zero-indexed frame number.	required

Returns:

Type	Description
`float \| None`	Time in seconds, or None if FPS is unknown.

Notes

This assumes constant frame rate. For variable frame rate videos, the returned timestamp may be approximate.

Source code in sleap_io/model/video.py

def frame_to_seconds(self, frame_idx: int) -> float | None:
    """Convert a frame index to timestamp in seconds.

    Args:
        frame_idx: Zero-indexed frame number.

    Returns:
        Time in seconds, or None if FPS is unknown.

    Notes:
        This assumes constant frame rate. For variable frame rate videos,
        the returned timestamp may be approximate.
    """
    if self.fps is None or self.fps <= 0:
        return None
    return frame_idx / self.fps

`from_crop(video, crop=None, *, bbox=None, roi=None, center=None, size=None, margin=0, fill=0, share_decode=True, **kwargs)` `classmethod` ¶

Open video (path or Video) and return a virtual crop.

Accepts the same region specs as :meth:crop (crop/bbox/roi/ center+size); extra keyword arguments are forwarded to :meth:from_filename when video is a path (ignored when it is already a Video).

Parameters:

Name	Type	Description	Default
`video`	`str \| Path \| Video`	A path/filename to open, or an existing `Video` to crop.	required
`crop`	`tuple[int, int, int, int] \| None`	Explicit crop region `(x1, y1, x2, y2)`, `x2`/`y2` exclusive.	`None`
`bbox`	`tuple[float, float, float, float] \| None`	A bounding box `(x1, y1, x2, y2)`; bounds may be float.	`None`
`roi`	`object \| None`	An object exposing axis-aligned `.bounds` (e.g. a shapely geometry); `margin` is applied around it.	`None`
`center`	`tuple[float, float] \| None`	Window center `(cx, cy)` (with `size`).	`None`
`size`	`tuple[int, int] \| None`	Fixed output `(width, height)` (with `center`).	`None`
`margin`	`int`	Pixels added around the `roi` bounds on every side.	`0`
`fill`	`int \| tuple[int, ...]`	Fill value for out-of-bounds regions.	`0`
`share_decode`	`bool`	If `True` (default), reuse the source decoder.	`True`
`**kwargs`		Forwarded to :meth:`from_filename` for a path input.	required

Returns:

Type	Description
`Video`	A new `Video` exposing the cropped view.

Source code in sleap_io/model/video.py

@classmethod
def from_crop(
    cls,
    video: "str | Path | Video",
    crop: tuple[int, int, int, int] | None = None,
    *,
    bbox: tuple[float, float, float, float] | None = None,
    roi: object | None = None,
    center: tuple[float, float] | None = None,
    size: tuple[int, int] | None = None,
    margin: int = 0,
    fill: int | tuple[int, ...] = 0,
    share_decode: bool = True,
    **kwargs,
) -> "Video":
    """Open ``video`` (path or ``Video``) and return a virtual crop.

    Accepts the same region specs as :meth:`crop` (``crop``/``bbox``/``roi``/
    ``center``+``size``); extra keyword arguments are forwarded to
    :meth:`from_filename` when ``video`` is a path (ignored when it is already
    a ``Video``).

    Args:
        video: A path/filename to open, or an existing ``Video`` to crop.
        crop: Explicit crop region ``(x1, y1, x2, y2)``, ``x2``/``y2`` exclusive.
        bbox: A bounding box ``(x1, y1, x2, y2)``; bounds may be float.
        roi: An object exposing axis-aligned ``.bounds`` (e.g. a shapely
            geometry); ``margin`` is applied around it.
        center: Window center ``(cx, cy)`` (with ``size``).
        size: Fixed output ``(width, height)`` (with ``center``).
        margin: Pixels added around the ``roi`` bounds on every side.
        fill: Fill value for out-of-bounds regions.
        share_decode: If ``True`` (default), reuse the source decoder.
        **kwargs: Forwarded to :meth:`from_filename` for a path input.

    Returns:
        A new ``Video`` exposing the cropped view.
    """
    if isinstance(video, (str, Path)):
        video = cls.from_filename(video, **kwargs)
    return video.crop(
        crop,
        bbox=bbox,
        roi=roi,
        center=center,
        size=size,
        margin=margin,
        fill=fill,
        share_decode=share_decode,
    )

`from_filename(filename, dataset=None, grayscale=None, keep_open=True, source_video=None, **kwargs)` `classmethod` ¶

Create a Video from a filename.

Parameters:

Name	Type	Description	Default
`filename`	`str \| list[str]`	The filename(s) of the video. Supported extensions: "mp4", "avi", "mov", "mj2", "mkv", "h5", "hdf5", "slp", "png", "jpg", "jpeg", "tif", "tiff", "bmp". If the filename is a list, a list of image filenames are expected. If filename is a folder, it will be searched for images.	required
`dataset`	`str \| None`	Name of dataset in HDF5 file.	`None`
`grayscale`	`bool \| None`	Whether to force grayscale. If None, autodetect on first frame load.	`None`
`keep_open`	`bool`	Whether to keep the video reader open between calls to read frames. If False, will close the reader after each call. If True (the default), it will keep the reader open and cache it for subsequent calls which may enhance the performance of reading multiple frames.	`True`
`source_video`	`Video \| None`	The source video object if this is a proxy video. This is present when the video contains an embedded subset of frames from another video.	`None`
`**kwargs`		Additional backend-specific arguments passed to VideoBackend.from_filename. See VideoBackend.from_filename for supported arguments.	required

Returns:

Type	Description
`VideoBackend`	Video instance with the appropriate backend instantiated.

Source code in sleap_io/model/video.py

@classmethod
def from_filename(
    cls,
    filename: str | list[str],
    dataset: str | None = None,
    grayscale: bool | None = None,
    keep_open: bool = True,
    source_video: "Video | None" = None,
    **kwargs,
) -> VideoBackend:
    """Create a Video from a filename.

    Args:
        filename: The filename(s) of the video. Supported extensions: "mp4", "avi",
            "mov", "mj2", "mkv", "h5", "hdf5", "slp", "png", "jpg", "jpeg", "tif",
            "tiff", "bmp". If the filename is a list, a list of image filenames are
            expected. If filename is a folder, it will be searched for images.
        dataset: Name of dataset in HDF5 file.
        grayscale: Whether to force grayscale. If None, autodetect on first frame
            load.
        keep_open: Whether to keep the video reader open between calls to read
            frames. If False, will close the reader after each call. If True (the
            default), it will keep the reader open and cache it for subsequent calls
            which may enhance the performance of reading multiple frames.
        source_video: The source video object if this is a proxy video. This is
            present when the video contains an embedded subset of frames from
            another video.
        **kwargs: Additional backend-specific arguments passed to
            VideoBackend.from_filename. See VideoBackend.from_filename for supported
            arguments.

    Returns:
        Video instance with the appropriate backend instantiated.
    """
    backend = VideoBackend.from_filename(
        filename,
        dataset=dataset,
        grayscale=grayscale,
        keep_open=keep_open,
        **kwargs,
    )
    # If filename is a directory, VideoBackend.from_filename will expand it
    # to a list of paths to images contained within the directory. In this
    # case we want to use the expanded list as filename
    return cls(
        filename=backend.filename,
        backend=backend,
        source_video=source_video,
    )

`has_overlapping_images(other)` ¶

Check if this video has overlapping images with another video.

This method is specifically for ImageVideo backends (image sequences).

Parameters:

Name	Type	Description	Default
`other`	`Video`	Another video to compare with.	required

Returns:

Type	Description
`bool`	True if both are ImageVideo instances with overlapping image files. False if either video is not an ImageVideo or no overlap exists.

Notes

Only works with ImageVideo backends where filename is a list. Compares individual image filenames (basenames only).

Source code in sleap_io/model/video.py

def has_overlapping_images(self, other: "Video") -> bool:
    """Check if this video has overlapping images with another video.

    This method is specifically for ImageVideo backends (image sequences).

    Args:
        other: Another video to compare with.

    Returns:
        True if both are ImageVideo instances with overlapping image files.
        False if either video is not an ImageVideo or no overlap exists.

    Notes:
        Only works with ImageVideo backends where filename is a list.
        Compares individual image filenames (basenames only).
    """
    # Both must be image sequences
    if not (isinstance(self.filename, list) and isinstance(other.filename, list)):
        return False

    # Get basenames for comparison
    self_basenames = set(Path(f).name for f in self.filename)
    other_basenames = set(Path(f).name for f in other.filename)

    # Check if there's any overlap
    return len(self_basenames & other_basenames) > 0

`matches_content(other)` ¶

Check if this video has the same content as another video.

Parameters:

Name	Type	Description	Default
`other`	`Video`	Another video to compare with.	required

Returns:

Type	Description
`bool`	True if the videos have the same shape and backend type.

Notes

This compares metadata like shape and backend type, not actual frame data.

Source code in sleap_io/model/video.py

def matches_content(self, other: "Video") -> bool:
    """Check if this video has the same content as another video.

    Args:
        other: Another video to compare with.

    Returns:
        True if the videos have the same shape and backend type.

    Notes:
        This compares metadata like shape and backend type, not actual frame data.
    """
    # Compare shapes
    self_shape = self.shape
    other_shape = other.shape

    if self_shape != other_shape:
        return False

    # Compare backend types
    if self.backend is None and other.backend is None:
        return True
    elif self.backend is None or other.backend is None:
        return False

    return type(self.backend).__name__ == type(other.backend).__name__

`matches_path(other, strict=False)` ¶

Check if this video has the same path as another video.

Parameters:

Name	Type	Description	Default
`other`	`Video`	Another video to compare with.	required
`strict`	`bool`	If True, require exact path match. If False, consider videos with the same filename (basename) as matching.	`False`

Returns:

Type	Description
`bool`	True if the videos have matching paths, False otherwise.

Notes

For HDF5 video backends (e.g., embedded videos in .pkg.slp files), matching prioritizes the source_filename attribute since multiple videos can share the same HDF5 file path but reference different source videos. Falls back to dataset name matching if source_filename is not available.

Source code in sleap_io/model/video.py

def matches_path(self, other: "Video", strict: bool = False) -> bool:
    """Check if this video has the same path as another video.

    Args:
        other: Another video to compare with.
        strict: If True, require exact path match. If False, consider videos
            with the same filename (basename) as matching.

    Returns:
        True if the videos have matching paths, False otherwise.

    Notes:
        For HDF5 video backends (e.g., embedded videos in .pkg.slp files),
        matching prioritizes the source_filename attribute since multiple
        videos can share the same HDF5 file path but reference different
        source videos. Falls back to dataset name matching if source_filename
        is not available.
    """
    # Handle HDF5 backends specially - prioritize source_filename matching
    self_is_hdf5 = isinstance(self.backend, HDF5Video)
    other_is_hdf5 = isinstance(other.backend, HDF5Video)

    if self_is_hdf5 and other_is_hdf5:
        # Both are HDF5 videos - must match by BOTH source_filename AND dataset
        # to distinguish different videos embedded in the same pkg.slp file
        self_source = self.backend.source_filename
        other_source = other.backend.source_filename
        self_dataset = self.backend.dataset
        other_dataset = other.backend.dataset

        # If both have datasets, they must match
        if self_dataset is not None and other_dataset is not None:
            if self_dataset != other_dataset:
                return False  # Different datasets = different videos

        # If both have source_filenames, compare them
        if self_source is not None and other_source is not None:
            if strict:
                # For HDF5 videos, just compare normalized path strings
                # (avoid slow resolve() on network paths)
                return Path(self_source).as_posix() == Path(other_source).as_posix()
            else:
                return Path(self_source).name == Path(other_source).name

        # If only datasets available (no source_filename), they must match
        if self_dataset is not None and other_dataset is not None:
            return self_dataset == other_dataset

        # If neither source_filename nor dataset available, cannot match
        return False

    if isinstance(self.filename, list) and isinstance(other.filename, list):
        # Both are image sequences
        if strict:
            return self.filename == other.filename
        else:
            # Compare basenames
            self_basenames = [Path(f).name for f in self.filename]
            other_basenames = [Path(f).name for f in other.filename]
            return self_basenames == other_basenames
    elif isinstance(self.filename, list) or isinstance(other.filename, list):
        # One is image sequence, other is single file
        return False
    else:
        # Both are single files - use resolve() for symlink handling
        if strict:
            p1, p2 = Path(self.filename), Path(other.filename)
            # Fast string comparison first
            if p1.as_posix() == p2.as_posix():
                return True
            # Only resolve if both exist locally (avoid slow network timeouts)
            try:
                if p1.exists() and p2.exists():
                    return p1.resolve() == p2.resolve()
            except OSError:
                pass
            return False
        else:
            return Path(self.filename).name == Path(other.filename).name

`matches_shape(other)` ¶

Check if this video has the same shape as another video.

Parameters:

Name	Type	Description	Default
`other`	`Video`	Another video to compare with.	required

Returns:

Type	Description
`bool`	True if the videos have the same height, width, and channels.

Notes

This only compares spatial dimensions, not the number of frames.

Source code in sleap_io/model/video.py

def matches_shape(self, other: "Video") -> bool:
    """Check if this video has the same shape as another video.

    Args:
        other: Another video to compare with.

    Returns:
        True if the videos have the same height, width, and channels.

    Notes:
        This only compares spatial dimensions, not the number of frames.
    """
    # Try to get shape from backend metadata first if shape is not available
    if self.backend is None and "shape" in self.backend_metadata:
        self_shape = self.backend_metadata["shape"]
    else:
        self_shape = self.shape

    if other.backend is None and "shape" in other.backend_metadata:
        other_shape = other.backend_metadata["shape"]
    else:
        other_shape = other.shape

    # Handle None shapes
    if self_shape is None or other_shape is None:
        return False

    # Compare only height, width, channels (not frames)
    return self_shape[1:] == other_shape[1:]

`merge_with(other)` ¶

Merge another video's images into this one.

This method is specifically for ImageVideo backends (image sequences).

Parameters:

Name	Type	Description	Default
`other`	`Video`	Another video to merge with. Must also be ImageVideo.	required

Returns:

Type	Description
`Video`	A new Video object with unique images from both videos.

Raises:

Type	Description
`ValueError`	If either video is not an ImageVideo backend.

Notes

Only works with ImageVideo backends where filename is a list. The merged video contains all unique images from both videos, with automatic deduplication based on image basename.

Source code in sleap_io/model/video.py

def merge_with(self, other: "Video") -> "Video":
    """Merge another video's images into this one.

    This method is specifically for ImageVideo backends (image sequences).

    Args:
        other: Another video to merge with. Must also be ImageVideo.

    Returns:
        A new Video object with unique images from both videos.

    Raises:
        ValueError: If either video is not an ImageVideo backend.

    Notes:
        Only works with ImageVideo backends where filename is a list.
        The merged video contains all unique images from both videos,
        with automatic deduplication based on image basename.
    """
    if not isinstance(self.filename, list):
        raise ValueError("merge_with only works with ImageVideo backends")
    if not isinstance(other.filename, list):
        raise ValueError("Other video must also be ImageVideo backend")

    # Get all unique images (by basename) preserving order
    seen_basenames = set()
    merged_paths = []

    for path in self.filename:
        basename = Path(path).name
        if basename not in seen_basenames:
            merged_paths.append(path)
            seen_basenames.add(basename)

    for path in other.filename:
        basename = Path(path).name
        if basename not in seen_basenames:
            merged_paths.append(path)
            seen_basenames.add(basename)

    # Create new video with merged images
    return Video.from_filename(merged_paths, grayscale=self.grayscale)

`open(filename=None, dataset=None, grayscale=None, keep_open=True, plugin=None)` ¶

Open the video backend for reading.

Parameters:

Name	Type	Description	Default
`filename`	`str \| None`	Filename to open. If not specified, will use the filename set on the video object.	`None`
`dataset`	`str \| None`	Name of dataset in HDF5 file.	`None`
`grayscale`	`str \| None`	Whether to force grayscale. If None, autodetect on first frame load.	`None`
`keep_open`	`bool`	Whether to keep the video reader open between calls to read frames. If False, will close the reader after each call. If True (the default), it will keep the reader open and cache it for subsequent calls which may enhance the performance of reading multiple frames.	`True`
`plugin`	`str \| None`	Video plugin to use for MediaVideo files. One of "opencv", "FFMPEG", or "pyav". Also accepts aliases (case-insensitive). If not specified, uses the backend metadata, global default, or auto-detection in that order.	`None`

Notes

This is useful for opening the video backend to read frames and then closing it after reading all the necessary frames.

If the backend was already open, it will be closed before opening a new one. Values for the HDF5 dataset and grayscale will be remembered if not specified.

Source code in sleap_io/model/video.py

def open(
    self,
    filename: str | None = None,
    dataset: str | None = None,
    grayscale: str | None = None,
    keep_open: bool = True,
    plugin: str | None = None,
):
    """Open the video backend for reading.

    Args:
        filename: Filename to open. If not specified, will use the filename set on
            the video object.
        dataset: Name of dataset in HDF5 file.
        grayscale: Whether to force grayscale. If None, autodetect on first frame
            load.
        keep_open: Whether to keep the video reader open between calls to read
            frames. If False, will close the reader after each call. If True (the
            default), it will keep the reader open and cache it for subsequent calls
            which may enhance the performance of reading multiple frames.
        plugin: Video plugin to use for MediaVideo files. One of "opencv",
            "FFMPEG", or "pyav". Also accepts aliases (case-insensitive).
            If not specified, uses the backend metadata, global default,
            or auto-detection in that order.

    Notes:
        This is useful for opening the video backend to read frames and then closing
        it after reading all the necessary frames.

        If the backend was already open, it will be closed before opening a new one.
        Values for the HDF5 dataset and grayscale will be remembered if not
        specified.
    """
    if filename is not None:
        self.replace_filename(filename, open=False)

    # Try to remember values from previous backend if available and not specified.
    if self.backend is not None:
        if dataset is None:
            dataset = getattr(self.backend, "dataset", None)
        if grayscale is None:
            grayscale = getattr(self.backend, "grayscale", None)

    else:
        if dataset is None and "dataset" in self.backend_metadata:
            dataset = self.backend_metadata["dataset"]
        if grayscale is None:
            if "grayscale" in self.backend_metadata:
                grayscale = self.backend_metadata["grayscale"]
            elif "shape" in self.backend_metadata:
                grayscale = self.backend_metadata["shape"][-1] == 1

    if not self.exists(dataset=dataset):
        from sleap_io.io._remote import _is_url, _redact_url

        # Redact credential-bearing URLs (e.g. presigned ``?token=`` links)
        # so they never surface in tracebacks/logs. Local paths are shown
        # verbatim.
        name = (
            _redact_url(self.filename)
            if isinstance(self.filename, str) and _is_url(self.filename)
            else self.filename
        )
        msg = f"Video does not exist or cannot be opened for reading: {name}"
        if dataset is not None:
            msg += f" (dataset: {dataset})"
        raise FileNotFoundError(msg)

    # Close previous backend if open.
    self.close()

    # Handle plugin parameter
    backend_kwargs = {}
    if plugin is not None:
        from sleap_io.io.video_reading import normalize_plugin_name

        plugin = normalize_plugin_name(plugin)
        self.backend_metadata["plugin"] = plugin

    if "plugin" in self.backend_metadata:
        backend_kwargs["plugin"] = self.backend_metadata["plugin"]

    # Create new backend. Forward the URL auth context so a reopened remote
    # HDF5Video stays authenticated (the previous backend, and its headers,
    # were dropped by self.close() above).
    self.backend = VideoBackend.from_filename(
        self.filename,
        dataset=dataset,
        grayscale=grayscale,
        keep_open=keep_open,
        url_headers=self._url_headers,
        url_stream_mode=self._url_stream_mode,
        **backend_kwargs,
    )

    # Re-wrap as a crop view if this video records a crop in its metadata.
    # The rebuilt backend above is always a plain backend, so this wraps
    # exactly once (idempotent across close()->open() and deepcopy).
    if "crop" in self.backend_metadata:
        from sleap_io.io.video_reading import CropVideoBackend

        self.backend = CropVideoBackend.wrap(
            inner=self.backend,
            crop=tuple(self.backend_metadata["crop"]),
            fill=self.backend_metadata.get("crop_fill", 0),
        )

`replace_filename(new_filename, open=True)` ¶

Update the filename of the video, optionally opening the backend.

Parameters:

Name	Type	Description	Default
`new_filename`	`str \| Path \| list[str] \| list[Path]`	New filename to set for the video.	required
`open`	`bool`	If `True` (the default), open the backend with the new filename. If the new filename does not exist, no error is raised.	`True`

Source code in sleap_io/model/video.py

def replace_filename(
    self, new_filename: str | Path | list[str] | list[Path], open: bool = True
):
    """Update the filename of the video, optionally opening the backend.

    Args:
        new_filename: New filename to set for the video.
        open: If `True` (the default), open the backend with the new filename. If
            the new filename does not exist, no error is raised.
    """
    if isinstance(new_filename, Path):
        new_filename = new_filename.as_posix()

    if isinstance(new_filename, list):
        new_filename = [
            p.as_posix() if isinstance(p, Path) else p for p in new_filename
        ]

    # A relink to a different file makes the recorded shape/grayscale/fps in
    # ``backend_metadata`` stale: they describe the OLD file but the new file
    # may have a different resolution/channels/frame rate. They must not be
    # serialized under the new filename (regression from #483, where
    # ``save_slp(prefer_metadata=True)`` prefers these recorded values), so
    # invalidate them on a real relink and let them be recomputed from the new
    # backend. The no-relink path leaves metadata untouched so golden
    # byte-identical saves stay byte-identical.
    filename_changed = new_filename != self.filename

    self.filename = new_filename
    self.backend_metadata["filename"] = new_filename
    # Invalidate any cached URL existence results for the previous filename.
    self._exists_cache.clear()

    if open:
        if self.exists():
            self.open()
        else:
            self.close()

    # Drop stale metadata AFTER (re)opening: ``open()`` internally calls
    # ``close()``, which would otherwise re-stamp the OLD backend's
    # shape/grayscale/fps back into ``backend_metadata``.
    if filename_changed:
        for key in ("shape", "grayscale", "fps"):
            self.backend_metadata.pop(key, None)

`save(save_path, frame_inds=None, fps=None, video_kwargs=None)` ¶

Save video frames to a new video file.

Parameters:

Name	Type	Description	Default
`save_path`	`str \| Path`	Path to the new video file. Should end in MP4.	required
`frame_inds`	`list[int] \| ndarray \| None`	Frame indices to save. Can be specified as a list or array of frame integers. If not specified, saves all video frames.	`None`
`fps`	`float \| None`	Frames per second for the output video. If not specified, uses the source video's FPS if available, otherwise defaults to 30.	`None`
`video_kwargs`	`dict[str, Any] \| None`	A dictionary of keyword arguments to provide to `sio.save_video` for video compression.	`None`

Returns:

Type	Description
`Video`	A new `Video` object pointing to the new video file.

Source code in sleap_io/model/video.py

def save(
    self,
    save_path: str | Path,
    frame_inds: list[int] | np.ndarray | None = None,
    fps: float | None = None,
    video_kwargs: dict[str, Any] | None = None,
) -> "Video":
    """Save video frames to a new video file.

    Args:
        save_path: Path to the new video file. Should end in MP4.
        frame_inds: Frame indices to save. Can be specified as a list or array of
            frame integers. If not specified, saves all video frames.
        fps: Frames per second for the output video. If not specified, uses the
            source video's FPS if available, otherwise defaults to 30.
        video_kwargs: A dictionary of keyword arguments to provide to
            `sio.save_video` for video compression.

    Returns:
        A new `Video` object pointing to the new video file.
    """
    video_kwargs = {} if video_kwargs is None else video_kwargs.copy()
    frame_inds = np.arange(len(self)) if frame_inds is None else frame_inds

    # Use source video FPS if not explicitly specified
    if fps is None:
        fps = self.fps
    if fps is not None and "fps" not in video_kwargs:
        video_kwargs["fps"] = fps

    with VideoWriter(save_path, **video_kwargs) as vw:
        for frame_ind in frame_inds:
            vw(self[frame_ind])

    new_video = Video.from_filename(save_path, grayscale=self.grayscale)
    return new_video

`seconds_to_frame(seconds)` ¶

Convert a timestamp in seconds to frame index.

Parameters:

Name	Type	Description	Default
`seconds`	`float`	Time in seconds from video start.	required

Returns:

Type	Description
`int \| None`	Zero-indexed frame number (rounded down), or None if FPS unknown.

Source code in sleap_io/model/video.py

def seconds_to_frame(self, seconds: float) -> int | None:
    """Convert a timestamp in seconds to frame index.

    Args:
        seconds: Time in seconds from video start.

    Returns:
        Zero-indexed frame number (rounded down), or None if FPS unknown.
    """
    if self.fps is None or self.fps <= 0:
        return None
    return int(seconds * self.fps)

`set_video_plugin(plugin)` ¶

Set the video plugin and reopen the video.

Parameters:

Name	Type	Description	Default
`plugin`	`str`	Video plugin to use. One of "opencv", "FFMPEG", or "pyav". Also accepts aliases (case-insensitive).	required

Raises:

Type	Description
`ValueError`	If the video is not a MediaVideo type.

Examples:

>>> video.set_video_plugin("opencv")
>>> video.set_video_plugin("CV2")  # Same as "opencv"

Source code in sleap_io/model/video.py

def set_video_plugin(self, plugin: str) -> None:
    """Set the video plugin and reopen the video.

    Args:
        plugin: Video plugin to use. One of "opencv", "FFMPEG", or "pyav".
            Also accepts aliases (case-insensitive).

    Raises:
        ValueError: If the video is not a MediaVideo type.

    Examples:
        >>> video.set_video_plugin("opencv")
        >>> video.set_video_plugin("CV2")  # Same as "opencv"
    """
    from sleap_io.io.video_reading import MediaVideo, normalize_plugin_name

    if not self.filename.endswith(MediaVideo.EXTS):
        raise ValueError(f"Cannot set plugin for non-media video: {self.filename}")

    plugin = normalize_plugin_name(plugin)

    # Close current backend if open
    was_open = self.is_open
    if was_open:
        self.close()

    # Update backend metadata
    self.backend_metadata["plugin"] = plugin

    # Reopen with new plugin if it was open
    if was_open:
        self.open()

`to_crop_coords(points)` ¶

Map source-frame (x, y) into this video's cropped frame.

Parameters:

Name	Type	Description	Default
`points`	`ndarray`	Coordinate array of shape `(..., 2)`. NaN values are preserved.	required

Returns:

Type	Description
`ndarray`	Coordinates translated into the cropped frame. If this video is not cropped, a copy of `points` is returned unchanged.

Source code in sleap_io/model/video.py

def to_crop_coords(self, points: np.ndarray) -> np.ndarray:
    """Map source-frame ``(x, y)`` into this video's cropped frame.

    Args:
        points: Coordinate array of shape ``(..., 2)``. NaN values are
            preserved.

    Returns:
        Coordinates translated into the cropped frame. If this video is not
        cropped, a copy of ``points`` is returned unchanged.
    """
    crop = self._crop_tuple()
    return points.copy() if crop is None else crop_points(points, crop)

`to_source_coords(points)` ¶

Map cropped-frame (x, y) back to source-frame coordinates.

Inverse of :meth:to_crop_coords.

Parameters:

Name	Type	Description	Default
`points`	`ndarray`	Coordinate array of shape `(..., 2)`. NaN values are preserved.	required

Returns:

Type	Description
`ndarray`	Coordinates translated back to source coordinates. If this video is not cropped, a copy of `points` is returned unchanged.

Source code in sleap_io/model/video.py

def to_source_coords(self, points: np.ndarray) -> np.ndarray:
    """Map cropped-frame ``(x, y)`` back to source-frame coordinates.

    Inverse of :meth:`to_crop_coords`.

    Args:
        points: Coordinate array of shape ``(..., 2)``. NaN values are
            preserved.

    Returns:
        Coordinates translated back to source coordinates. If this video is
        not cropped, a copy of ``points`` is returned unchanged.
    """
    crop = self._crop_tuple()
    return points.copy() if crop is None else uncrop_points(points, crop)

`VideoMatchMethod` ¶

Bases: builtins.str, enum.Enum

Methods for matching videos.

Attributes:

Name	Type	Description
`PATH`		Match by exact file path (strict or lenient based on VideoMatcher.strict setting).
`BASENAME`		Match by filename only, ignoring directory paths.
`CONTENT`		Match by video shape (frames, height, width, channels) and backend type.
`AUTO`		Automatic matching - tries BASENAME first, then falls back to CONTENT.
`IMAGE_DEDUP`		(ImageVideo only) Match ImageVideo instances with overlapping image files. Used to deduplicate individual images when merging datasets where videos are image sequences.
`SHAPE`		Match videos by shape only (height, width, channels), ignoring filenames and frame count. Commonly used with ImageVideo to merge same-shaped image sequences.

Source code in sleap_io/model/matching.py

class VideoMatchMethod(str, Enum):
    """Methods for matching videos.

    Attributes:
        PATH: Match by exact file path (strict or lenient based on
            VideoMatcher.strict setting).
        BASENAME: Match by filename only, ignoring directory paths.
        CONTENT: Match by video shape (frames, height, width, channels) and
            backend type.
        AUTO: Automatic matching - tries BASENAME first, then falls back to CONTENT.
        IMAGE_DEDUP: (ImageVideo only) Match ImageVideo instances with overlapping
            image files. Used to deduplicate individual images when merging datasets
            where videos are image sequences.
        SHAPE: Match videos by shape only (height, width, channels), ignoring
            filenames and frame count. Commonly used with ImageVideo to merge
            same-shaped image sequences.
    """

    PATH = "path"
    BASENAME = "basename"
    CONTENT = "content"
    AUTO = "auto"
    IMAGE_DEDUP = "image_dedup"
    SHAPE = "shape"

`AUTO = <VideoMatchMethod.AUTO: 'auto'>` `class-attribute` ¶

Methods for matching videos.

Attributes:

Name	Type	Description
`PATH`		Match by exact file path (strict or lenient based on VideoMatcher.strict setting).
`BASENAME`		Match by filename only, ignoring directory paths.
`CONTENT`		Match by video shape (frames, height, width, channels) and backend type.
`AUTO`		Automatic matching - tries BASENAME first, then falls back to CONTENT.
`IMAGE_DEDUP`		(ImageVideo only) Match ImageVideo instances with overlapping image files. Used to deduplicate individual images when merging datasets where videos are image sequences.
`SHAPE`		Match videos by shape only (height, width, channels), ignoring filenames and frame count. Commonly used with ImageVideo to merge same-shaped image sequences.

`BASENAME = <VideoMatchMethod.BASENAME: 'basename'>` `class-attribute` ¶

Methods for matching videos.

Attributes:

Name	Type	Description
`PATH`		Match by exact file path (strict or lenient based on VideoMatcher.strict setting).
`BASENAME`		Match by filename only, ignoring directory paths.
`CONTENT`		Match by video shape (frames, height, width, channels) and backend type.
`AUTO`		Automatic matching - tries BASENAME first, then falls back to CONTENT.
`IMAGE_DEDUP`		(ImageVideo only) Match ImageVideo instances with overlapping image files. Used to deduplicate individual images when merging datasets where videos are image sequences.
`SHAPE`		Match videos by shape only (height, width, channels), ignoring filenames and frame count. Commonly used with ImageVideo to merge same-shaped image sequences.

`CONTENT = <VideoMatchMethod.CONTENT: 'content'>` `class-attribute` ¶

Methods for matching videos.

Attributes:

Name	Type	Description
`PATH`		Match by exact file path (strict or lenient based on VideoMatcher.strict setting).
`BASENAME`		Match by filename only, ignoring directory paths.
`CONTENT`		Match by video shape (frames, height, width, channels) and backend type.
`AUTO`		Automatic matching - tries BASENAME first, then falls back to CONTENT.
`IMAGE_DEDUP`		(ImageVideo only) Match ImageVideo instances with overlapping image files. Used to deduplicate individual images when merging datasets where videos are image sequences.
`SHAPE`		Match videos by shape only (height, width, channels), ignoring filenames and frame count. Commonly used with ImageVideo to merge same-shaped image sequences.

`IMAGE_DEDUP = <VideoMatchMethod.IMAGE_DEDUP: 'image_dedup'>` `class-attribute` ¶

Methods for matching videos.

Attributes:

Name	Type	Description
`PATH`		Match by exact file path (strict or lenient based on VideoMatcher.strict setting).
`BASENAME`		Match by filename only, ignoring directory paths.
`CONTENT`		Match by video shape (frames, height, width, channels) and backend type.
`AUTO`		Automatic matching - tries BASENAME first, then falls back to CONTENT.
`IMAGE_DEDUP`		(ImageVideo only) Match ImageVideo instances with overlapping image files. Used to deduplicate individual images when merging datasets where videos are image sequences.
`SHAPE`		Match videos by shape only (height, width, channels), ignoring filenames and frame count. Commonly used with ImageVideo to merge same-shaped image sequences.

`PATH = <VideoMatchMethod.PATH: 'path'>` `class-attribute` ¶

Methods for matching videos.

Attributes:

Name	Type	Description
`PATH`		Match by exact file path (strict or lenient based on VideoMatcher.strict setting).
`BASENAME`		Match by filename only, ignoring directory paths.
`CONTENT`		Match by video shape (frames, height, width, channels) and backend type.
`AUTO`		Automatic matching - tries BASENAME first, then falls back to CONTENT.
`IMAGE_DEDUP`		(ImageVideo only) Match ImageVideo instances with overlapping image files. Used to deduplicate individual images when merging datasets where videos are image sequences.
`SHAPE`		Match videos by shape only (height, width, channels), ignoring filenames and frame count. Commonly used with ImageVideo to merge same-shaped image sequences.

`SHAPE = <VideoMatchMethod.SHAPE: 'shape'>` `class-attribute` ¶

Methods for matching videos.

Attributes:

Name	Type	Description
`PATH`		Match by exact file path (strict or lenient based on VideoMatcher.strict setting).
`BASENAME`		Match by filename only, ignoring directory paths.
`CONTENT`		Match by video shape (frames, height, width, channels) and backend type.
`AUTO`		Automatic matching - tries BASENAME first, then falls back to CONTENT.
`IMAGE_DEDUP`		(ImageVideo only) Match ImageVideo instances with overlapping image files. Used to deduplicate individual images when merging datasets where videos are image sequences.
`SHAPE`		Match videos by shape only (height, width, channels), ignoring filenames and frame count. Commonly used with ImageVideo to merge same-shaped image sequences.

doc = 'Methods for matching videos.\n\nAttributes:\n PATH: Match by exact file path (strict or lenient based on\n VideoMatcher.strict setting).\n BASENAME: Match by filename only, ignoring directory paths.\n CONTENT: Match by video shape (frames, height, width, channels) and\n backend type.\n AUTO: Automatic matching - tries BASENAME first, then falls back to CONTENT.\n IMAGE_DEDUP: (ImageVideo only) Match ImageVideo instances with overlapping\n image files. Used to deduplicate individual images when merging datasets\n where videos are image sequences.\n SHAPE: Match videos by shape only (height, width, channels), ignoring\n filenames and frame count. Commonly used with ImageVideo to merge\n same-shaped image sequences.\n' `class-attribute` ¶

str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.str() (if defined) or repr(object). encoding defaults to 'utf-8'. errors defaults to 'strict'.

`module = 'sleap_io.model.matching'` `class-attribute` ¶

str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.str() (if defined) or repr(object). encoding defaults to 'utf-8'. errors defaults to 'strict'.

`VideoMatcher` ¶

Matcher for comparing and matching videos.

Attributes:

Name	Type	Description
`method`		The matching method to use. Can be a VideoMatchMethod enum value or a string that will be converted to the enum. Default is AUTO.
`strict`		Whether to use strict path matching for the PATH method. When True, paths must be exactly identical. When False, paths are normalized before comparison. Only used when method is PATH. Default is False.
`content_frames`		Minimum number of matching frames required for pose/image matching to confirm a match. If fewer common frames exist, requires all of them to match. Default 3.
`compare_predictions`		Whether to include predicted instances in pose matching. "auto" (default): Include only if video has 100% predictions (no user instances). True: Always include predictions. False: Never include predictions (user instances only).
`compare_images`		Whether to compare frame images via pixel similarity. Expensive operation requiring frame decoding. Default False.
`image_similarity_threshold`		Maximum mean pixel difference (0-1 scale, normalized by 255) for images to be considered matching. Only used when compare_images=True. Default 0.05 (~13/255 pixels).

Notes

For AUTO method, use find_match() when matching against a list of candidates. The match() method for AUTO uses a simplified pairwise check that doesn't include the full leaf-uniqueness algorithm.

Methods:

Name	Description
`__eq__`	Method generated by attrs for class VideoMatcher.
`__init__`	Method generated by attrs for class VideoMatcher.
`__repr__`	Method generated by attrs for class VideoMatcher.
`__setattr__`	Method generated by attrs for class VideoMatcher.
`find_match`	Find a matching video from candidates using the configured method.
`match`	Check if two videos match according to the configured method.

Source code in sleap_io/model/matching.py

@attrs.define
class VideoMatcher:
    """Matcher for comparing and matching videos.

    Attributes:
        method: The matching method to use. Can be a VideoMatchMethod enum value
            or a string that will be converted to the enum. Default is AUTO.
        strict: Whether to use strict path matching for the PATH method.
            When True, paths must be exactly identical. When False, paths
            are normalized before comparison. Only used when method is PATH.
            Default is False.
        content_frames: Minimum number of matching frames required for pose/image
            matching to confirm a match. If fewer common frames exist, requires
            all of them to match. Default 3.
        compare_predictions: Whether to include predicted instances in pose matching.
            "auto" (default): Include only if video has 100% predictions (no user
            instances). True: Always include predictions. False: Never include
            predictions (user instances only).
        compare_images: Whether to compare frame images via pixel similarity.
            Expensive operation requiring frame decoding. Default False.
        image_similarity_threshold: Maximum mean pixel difference (0-1 scale,
            normalized by 255) for images to be considered matching.
            Only used when compare_images=True. Default 0.05 (~13/255 pixels).

    Notes:
        For AUTO method, use find_match() when matching against a list of
        candidates. The match() method for AUTO uses a simplified pairwise
        check that doesn't include the full leaf-uniqueness algorithm.
    """

    method: VideoMatchMethod | str = attrs.field(
        default=VideoMatchMethod.AUTO,
        converter=lambda x: VideoMatchMethod(x) if isinstance(x, str) else x,
    )
    strict: bool = False
    content_frames: int = 3
    compare_predictions: str | bool = "auto"
    compare_images: bool = False
    image_similarity_threshold: float = 0.05
    _frame_cache: dict = attrs.field(factory=dict, init=False, repr=False)

    def _get_cached_frame_instances(
        self,
        labels: "Labels",
        video: "Video",
        include_predictions: bool,
    ) -> dict[int, list["Instance"]]:
        """Get frame instances with caching for performance.

        Caches the result to avoid recomputing for the same video multiple times
        during merge operations.
        """
        cache_key = (id(labels), id(video), include_predictions)
        if cache_key not in self._frame_cache:
            self._frame_cache[cache_key] = _get_frame_instances(
                labels, video, include_predictions
            )
        return self._frame_cache[cache_key]

    def match(self, video1: Video, video2: Video) -> bool:
        """Check if two videos match according to the configured method.

        For AUTO method, this performs pairwise checks (file identity, path match).
        For full AUTO matching with leaf-uniqueness, use find_match() instead.
        """
        if self.method == VideoMatchMethod.AUTO:
            # Pairwise AUTO: rejection checks + definitive identity + path match
            # (Leaf-uniqueness requires full candidate list - use find_match())

            # Rejection: incompatible shapes
            if shapes_compatible(video1, video2) is False:
                return False

            # Rejection: conflicting provenance
            if original_videos_conflict(video1, video2):
                return False

            # Definitive: same source file but different crop (mosaic tiles).
            # Must run before any path rung, which would otherwise re-match the
            # shared root file. For non-crop videos this is always False.
            if _same_file_different_crop(video1, video2):
                return False

            # Definitive: same file identity (crop-aware)
            if is_same_file(video1, video2):
                return True

            # String: strict path match
            if video1.matches_path(video2, strict=True):
                return True

            # String: basename match (for pairwise, this is the fallback)
            if video1.matches_path(video2, strict=False):
                return True

            return False

        elif self.method == VideoMatchMethod.PATH:
            return video1.matches_path(video2, strict=self.strict)
        elif self.method == VideoMatchMethod.BASENAME:
            return video1.matches_path(video2, strict=False)
        elif self.method == VideoMatchMethod.CONTENT:
            return video1.matches_content(video2)
        elif self.method == VideoMatchMethod.IMAGE_DEDUP:
            # Match ImageVideo instances with overlapping images (ImageVideo only)
            return video1.has_overlapping_images(video2)
        elif self.method == VideoMatchMethod.SHAPE:
            # Match videos by shape only (height, width, channels)
            return video1.matches_shape(video2)
        else:
            raise ValueError(f"Unknown video match method: {self.method}")

    def find_match(
        self,
        incoming: Video,
        candidates: list[Video],
        labels_incoming: "Labels | None" = None,
        labels_base: "Labels | None" = None,
    ) -> Video | None:
        """Find a matching video from candidates using the configured method.

        This is the preferred method for AUTO matching as it implements the
        full safe matching cascade including leaf-uniqueness disambiguation.

        Args:
            incoming: The video to find a match for.
            candidates: List of existing videos to search for matches.
            labels_incoming: Labels object containing the incoming video's
                annotations. Used for pose-based matching in AUTO mode.
            labels_base: Labels object containing the candidates' annotations.
                Used for pose-based matching in AUTO mode.

        Returns:
            The matched video, or None if no match found.

        Notes:
            For AUTO method, implements the safe matching cascade:
            1. Shape rejection (filter candidates)
            2. original_video conflict rejection (filter candidates)
            3. Definitive file identity (is_same_file)
            4. Strict path match
            5. Leaf uniqueness matching at increasing depths
            6. Pose-based matching (if labels provided)
            7. Image-based matching (if compare_images=True)

            Shape is for REJECTION only - compatible shapes don't imply a match.
        """
        from pathlib import Path

        from sleap_io.io.utils import sanitize_filename

        if self.method == VideoMatchMethod.AUTO:
            # Build list of viable candidates (not rejected by shape/provenance)
            viable = []
            for candidate in candidates:
                # REJECTION CHECK 1: Shape compatibility
                shape_compat = shapes_compatible(candidate, incoming)
                if shape_compat is False:
                    # Definitely incompatible shapes - skip
                    continue

                # REJECTION CHECK 2: original_video conflict
                if original_videos_conflict(candidate, incoming):
                    # Both have provenance pointing to different files - skip
                    continue

                # REJECTION CHECK 3: same source file, different crop.
                # Distinct crops (mosaic tiles) of one physical file share a
                # root file, so dropping them here prevents the file-identity,
                # strict-path, and leaf-uniqueness rungs from collapsing them.
                # For non-crop candidates this is always False.
                if _same_file_different_crop(candidate, incoming):
                    continue

                viable.append(candidate)

            # DEFINITIVE CHECK: File identity (handles source_video chains)
            for candidate in viable:
                if is_same_file(candidate, incoming):
                    return candidate

            # STRING CHECK: Full path match
            for candidate in viable:
                if candidate.matches_path(incoming, strict=True):
                    return candidate

            # STRING CHECK: Leaf path uniqueness
            # Match paths by comparing suffixes at increasing depths
            if viable:

                def get_path_parts(video: Video) -> tuple[str, ...]:
                    """Get path parts for comparison, using root video for embedded."""
                    root = _get_root_video(video)
                    fn = root.filename
                    if isinstance(fn, list):
                        fn = fn[0]  # Use first for ImageVideo
                    return Path(sanitize_filename(fn)).parts

                incoming_parts = get_path_parts(incoming)
                candidate_parts = [(v, get_path_parts(v)) for v in viable]

                # Also need all existing videos for uniqueness check
                all_existing_parts = [(v, get_path_parts(v)) for v in candidates]

                # Compare at increasing depths until we find a unique match
                max_depth = max(
                    len(incoming_parts),
                    max((len(p) for _, p in all_existing_parts), default=0),
                )

                for depth in range(1, max_depth + 1):
                    if len(incoming_parts) < depth:
                        continue
                    incoming_leaf = "/".join(incoming_parts[-depth:])

                    # Find all viable candidates that match at this depth
                    matches_at_depth = []
                    for candidate, parts in candidate_parts:
                        if len(parts) < depth:
                            continue
                        candidate_leaf = "/".join(parts[-depth:])
                        if candidate_leaf == incoming_leaf:
                            matches_at_depth.append(candidate)

                    # If exactly one match at this depth, use it
                    if len(matches_at_depth) == 1:
                        return matches_at_depth[0]
                    # If no matches, try deeper
                    # If multiple matches, continue deeper to disambiguate

            # POSE MATCHING: Compare pose annotations (default in AUTO)
            if labels_incoming is not None and labels_base is not None:
                match = self._match_by_poses(
                    incoming, viable, labels_incoming, labels_base
                )
                if match is not None:
                    return match

            # IMAGE MATCHING: Compare frame images (opt-in)
            if self.compare_images:
                match = self._match_by_images(incoming, viable)
                if match is not None:
                    return match

            # No match found
            return None

        else:
            # Non-AUTO methods: use pairwise match()
            for candidate in candidates:
                if self.match(candidate, incoming):
                    return candidate
            return None

    def _match_by_poses(
        self,
        incoming: "Video",
        candidates: list["Video"],
        labels_incoming: "Labels",
        labels_base: "Labels",
    ) -> "Video | None":
        """Try to match video by comparing pose annotations.

        Returns matched video if poses match on enough common frames.
        """
        # Resolve whether to include predictions for incoming video
        include_preds = _resolve_compare_predictions(
            self.compare_predictions, labels_incoming, incoming
        )

        # Get incoming video's frame -> instances map (cached)
        incoming_frames = self._get_cached_frame_instances(
            labels_incoming, incoming, include_preds
        )
        if not incoming_frames:
            return None  # No annotations to compare

        for candidate in candidates:
            # Get candidate's frame -> instances map (cached for performance)
            # Use same prediction setting resolved for candidate
            include_preds_cand = _resolve_compare_predictions(
                self.compare_predictions, labels_base, candidate
            )
            candidate_frames = self._get_cached_frame_instances(
                labels_base, candidate, include_preds_cand
            )
            if not candidate_frames:
                continue

            # Find common frame indices
            common_indices = set(incoming_frames.keys()) & set(candidate_frames.keys())
            if not common_indices:
                continue

            # Determine required matches
            required_matches = min(self.content_frames, len(common_indices))

            # Sample frames if too many (performance)
            sample_indices = _sample_frame_indices(
                common_indices, max_samples=self.content_frames * 2
            )

            # Count matching frames
            matching_frames = 0
            for frame_idx in sample_indices:
                if _frame_has_matching_pose(
                    incoming_frames[frame_idx], candidate_frames[frame_idx]
                ):
                    matching_frames += 1
                    if matching_frames >= required_matches:
                        return candidate  # Found match!

        return None

    def _match_by_images(
        self,
        incoming: "Video",
        candidates: list["Video"],
    ) -> "Video | None":
        """Try to match video by comparing image content.

        Only used when compare_images=True. Expensive operation.
        Returns matched video if images match on enough common frames.
        """
        for candidate in candidates:
            # Get common embedded frame indices
            common_indices = _get_common_embedded_indices(incoming, candidate)
            if not common_indices:
                continue

            required_matches = min(self.content_frames, len(common_indices))

            # Sample frames
            sample_indices = _sample_frame_indices(
                common_indices, max_samples=self.content_frames * 2
            )

            # Count matching frames
            matching_frames = 0
            for frame_idx in sample_indices:
                if _frames_similar_by_image(
                    incoming, candidate, frame_idx, self.image_similarity_threshold
                ):
                    matching_frames += 1
                    if matching_frames >= required_matches:
                        return candidate

        return None

`annotations = {'method': 'VideoMatchMethod | str', 'strict': 'bool', 'content_frames': 'int', 'compare_predictions': 'str | bool', 'compare_images': 'bool', 'image_similarity_threshold': 'float', '_frame_cache': 'dict'}` `class-attribute` ¶

dict() -> new empty dictionary dict(mapping) -> new dictionary initialized from a mapping object's (key, value) pairs dict(iterable) -> new dictionary initialized as if via: d = {} for k, v in iterable: d[k] = v dict(**kwargs) -> new dictionary initialized with the name=value pairs in the keyword argument list. For example: dict(one=1, two=2)

`__attrs_own_setattr__ = True` `class-attribute` ¶

Returns True when the argument is true, False otherwise. The builtins True and False are the only two instances of the class bool. The class bool is a subclass of the class int, and cannot be subclassed.

`__attrs_props__ = ClassProps(is_exception=False, is_slotted=True, has_weakref_slot=True, is_frozen=False, kw_only=<KeywordOnly.NO: 'no'>, collected_fields_by_mro=True, added_init=True, added_repr=True, added_eq=True, added_ordering=False, hashability=<Hashability.UNHASHABLE: 'unhashable'>, added_match_args=True, added_str=False, added_pickling=True, on_setattr_hook=<function pipe.<locals>.wrapped_pipe at 0x7f08471ce840>, field_transformer=None)` `class-attribute` ¶

Effective class properties as derived from parameters to attr.s() or define() decorators.

This is the same data structure that attrs uses internally to decide how to construct the final class.

Warning:

This feature is currently **experimental** and is not covered by our
strict backwards-compatibility guarantees.

Attributes:

Name	Type	Description
`is_exception`	`bool`	Whether the class is treated as an exception class.
`is_slotted`	`bool`	Whether the class is `slotted <slotted classes>`.
`has_weakref_slot`	`bool`	Whether the class has a slot for weak references.
`is_frozen`	`bool`	Whether the class is frozen.
`kw_only`	`KeywordOnly`	Whether / how the class enforces keyword-only arguments on the `__init__` method.
`collected_fields_by_mro`	`bool`	Whether the class fields were collected by method resolution order. That is, correctly but unlike `dataclasses`.
`added_init`	`bool`	Whether the class has an attrs-generated `__init__` method.
`added_repr`	`bool`	Whether the class has an attrs-generated `__repr__` method.
`added_eq`	`bool`	Whether the class has attrs-generated equality methods.
`added_ordering`	`bool`	Whether the class has attrs-generated ordering methods.
`hashability`	`Hashability`	How `hashable <hashing>` the class is.
`added_match_args`	`bool`	Whether the class supports positional `match <match>` over its fields.
`added_str`	`bool`	Whether the class has an attrs-generated `__str__` method.
`added_pickling`	`bool`	Whether the class has attrs-generated `__getstate__` and `__setstate__` methods for `pickle`.
`on_setattr_hook`	`Callable[[Any, Attribute[Any], Any], Any] \| None`	The class's `__setattr__` hook.
`field_transformer`	`Callable[[Attribute[Any]], Attribute[Any]] \| None`	The class's `field transformers <transform-fields>`.

.. versionadded:: 25.4.0

doc = 'Matcher for comparing and matching videos.\n\nAttributes:\n method: The matching method to use. Can be a VideoMatchMethod enum value\n or a string that will be converted to the enum. Default is AUTO.\n strict: Whether to use strict path matching for the PATH method.\n When True, paths must be exactly identical. When False, paths\n are normalized before comparison. Only used when method is PATH.\n Default is False.\n content_frames: Minimum number of matching frames required for pose/image\n matching to confirm a match. If fewer common frames exist, requires\n all of them to match. Default 3.\n compare_predictions: Whether to include predicted instances in pose matching.\n "auto" (default): Include only if video has 100% predictions (no user\n instances). True: Always include predictions. False: Never include\n predictions (user instances only).\n compare_images: Whether to compare frame images via pixel similarity.\n Expensive operation requiring frame decoding. Default False.\n image_similarity_threshold: Maximum mean pixel difference (0-1 scale,\n normalized by 255) for images to be considered matching.\n Only used when compare_images=True. Default 0.05 (~13/255 pixels).\n\nNotes:\n For AUTO method, use find_match() when matching against a list of\n candidates. The match() method for AUTO uses a simplified pairwise\n check that doesn\'t include the full leaf-uniqueness algorithm.\n' `class-attribute` ¶

str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.str() (if defined) or repr(object). encoding defaults to 'utf-8'. errors defaults to 'strict'.

`firstlineno = 946` `class-attribute` ¶

int([x]) -> integer int(x, base=10) -> integer

Convert a number or string to an integer, or return 0 if no arguments are given. If x is a number, return x.int(). For floating-point numbers, this truncates towards zero.

If x is not a number or if base is given, then x must be a string, bytes, or bytearray instance representing an integer literal in the given base. The literal can be preceded by '+' or '-' and be surrounded by whitespace. The base defaults to 10. Valid bases are 0 and 2-36. Base 0 means to interpret the base from the string as an integer iteral.

`__match_args__ = ('method', 'strict', 'content_frames', 'compare_predictions', 'compare_images', 'image_similarity_threshold')` `class-attribute` ¶

Built-in immutable sequence.

If no argument is given, the constructor returns an empty tuple. If iterable is specified the tuple is initialized from iterable's items.

If the argument is a tuple, the return value is the same object.

`module = 'sleap_io.model.matching'` `class-attribute` ¶

str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.str() (if defined) or repr(object). encoding defaults to 'utf-8'. errors defaults to 'strict'.

`slots = ('method', 'strict', 'content_frames', 'compare_predictions', 'compare_images', 'image_similarity_threshold', '_frame_cache', 'weakref')` `class-attribute` ¶

Built-in immutable sequence.

If no argument is given, the constructor returns an empty tuple. If iterable is specified the tuple is initialized from iterable's items.

If the argument is a tuple, the return value is the same object.

`__static_attributes__ = ()` `class-attribute` ¶

Built-in immutable sequence.

If no argument is given, the constructor returns an empty tuple. If iterable is specified the tuple is initialized from iterable's items.

If the argument is a tuple, the return value is the same object.

`weakref` `property` ¶

list of weak references to the object

`eq(other)` ¶

Method generated by attrs for class VideoMatcher.

Source code in sleap_io/model/matching.py

automatic strategies.
"""

from __future__ import annotations

from enum import Enum
from typing import TYPE_CHECKING, Any

import attrs
import numpy as np

from sleap_io.model.category import Category

`init(method=<VideoMatchMethod.AUTO: 'auto'>, strict=False, content_frames=3, compare_predictions='auto', compare_images=False, image_similarity_threshold=0.05)` ¶

Method generated by attrs for class VideoMatcher.

Source code in sleap_io/model/matching.py

from sleap_io.model.identity import Identity
from sleap_io.model.instance import Instance, Track
from sleap_io.model.labeled_frame import LabeledFrame
from sleap_io.model.skeleton import Skeleton
from sleap_io.model.video import Video

if TYPE_CHECKING:
    from sleap_io.model.labels import Labels

`repr()` ¶

Method generated by attrs for class VideoMatcher.

Source code in sleap_io/model/matching.py

"""Unified matcher system for comparing and matching data structures during merging.

This module provides configurable matchers for comparing skeletons, instances, tracks,
and videos during merge operations. The matchers use various strategies to determine
when data structures should be considered equivalent during merging.

Key features:
- Skeleton matching: exact, structure-based, overlap, and subset matching
- Instance matching: spatial proximity, track identity, and bounding box IoU
- Track matching: by name or object identity
- Identity matching: by name or object identity
- Category matching: by name or object identity
- Video matching: path, basename, content, and auto matching

Video matching supports path-based, filename-based, content-based, and

`setattr(name, val)` ¶

Method generated by attrs for class VideoMatcher.

Source code in sleap_io/model/matching.py

        return match

# IMAGE MATCHING: Compare frame images (opt-in)
if self.compare_images:
    match = self._match_by_images(incoming, viable)
    if match is not None:
        return match

# No match found

`find_match(incoming, candidates, labels_incoming=None, labels_base=None)` ¶

Find a matching video from candidates using the configured method.

This is the preferred method for AUTO matching as it implements the full safe matching cascade including leaf-uniqueness disambiguation.

Parameters:

Name	Type	Description	Default
`incoming`	`Video`	The video to find a match for.	required
`candidates`	`list[Video]`	List of existing videos to search for matches.	required
`labels_incoming`	`Labels \| None`	Labels object containing the incoming video's annotations. Used for pose-based matching in AUTO mode.	`None`
`labels_base`	`Labels \| None`	Labels object containing the candidates' annotations. Used for pose-based matching in AUTO mode.	`None`

Returns:

Type	Description
`Video \| None`	The matched video, or None if no match found.

Notes

For AUTO method, implements the safe matching cascade: 1. Shape rejection (filter candidates) 2. original_video conflict rejection (filter candidates) 3. Definitive file identity (is_same_file) 4. Strict path match 5. Leaf uniqueness matching at increasing depths 6. Pose-based matching (if labels provided) 7. Image-based matching (if compare_images=True)

Shape is for REJECTION only - compatible shapes don't imply a match.

Source code in sleap_io/model/matching.py

def find_match(
    self,
    incoming: Video,
    candidates: list[Video],
    labels_incoming: "Labels | None" = None,
    labels_base: "Labels | None" = None,
) -> Video | None:
    """Find a matching video from candidates using the configured method.

    This is the preferred method for AUTO matching as it implements the
    full safe matching cascade including leaf-uniqueness disambiguation.

    Args:
        incoming: The video to find a match for.
        candidates: List of existing videos to search for matches.
        labels_incoming: Labels object containing the incoming video's
            annotations. Used for pose-based matching in AUTO mode.
        labels_base: Labels object containing the candidates' annotations.
            Used for pose-based matching in AUTO mode.

    Returns:
        The matched video, or None if no match found.

    Notes:
        For AUTO method, implements the safe matching cascade:
        1. Shape rejection (filter candidates)
        2. original_video conflict rejection (filter candidates)
        3. Definitive file identity (is_same_file)
        4. Strict path match
        5. Leaf uniqueness matching at increasing depths
        6. Pose-based matching (if labels provided)
        7. Image-based matching (if compare_images=True)

        Shape is for REJECTION only - compatible shapes don't imply a match.
    """
    from pathlib import Path

    from sleap_io.io.utils import sanitize_filename

    if self.method == VideoMatchMethod.AUTO:
        # Build list of viable candidates (not rejected by shape/provenance)
        viable = []
        for candidate in candidates:
            # REJECTION CHECK 1: Shape compatibility
            shape_compat = shapes_compatible(candidate, incoming)
            if shape_compat is False:
                # Definitely incompatible shapes - skip
                continue

            # REJECTION CHECK 2: original_video conflict
            if original_videos_conflict(candidate, incoming):
                # Both have provenance pointing to different files - skip
                continue

            # REJECTION CHECK 3: same source file, different crop.
            # Distinct crops (mosaic tiles) of one physical file share a
            # root file, so dropping them here prevents the file-identity,
            # strict-path, and leaf-uniqueness rungs from collapsing them.
            # For non-crop candidates this is always False.
            if _same_file_different_crop(candidate, incoming):
                continue

            viable.append(candidate)

        # DEFINITIVE CHECK: File identity (handles source_video chains)
        for candidate in viable:
            if is_same_file(candidate, incoming):
                return candidate

        # STRING CHECK: Full path match
        for candidate in viable:
            if candidate.matches_path(incoming, strict=True):
                return candidate

        # STRING CHECK: Leaf path uniqueness
        # Match paths by comparing suffixes at increasing depths
        if viable:

            def get_path_parts(video: Video) -> tuple[str, ...]:
                """Get path parts for comparison, using root video for embedded."""
                root = _get_root_video(video)
                fn = root.filename
                if isinstance(fn, list):
                    fn = fn[0]  # Use first for ImageVideo
                return Path(sanitize_filename(fn)).parts

            incoming_parts = get_path_parts(incoming)
            candidate_parts = [(v, get_path_parts(v)) for v in viable]

            # Also need all existing videos for uniqueness check
            all_existing_parts = [(v, get_path_parts(v)) for v in candidates]

            # Compare at increasing depths until we find a unique match
            max_depth = max(
                len(incoming_parts),
                max((len(p) for _, p in all_existing_parts), default=0),
            )

            for depth in range(1, max_depth + 1):
                if len(incoming_parts) < depth:
                    continue
                incoming_leaf = "/".join(incoming_parts[-depth:])

                # Find all viable candidates that match at this depth
                matches_at_depth = []
                for candidate, parts in candidate_parts:
                    if len(parts) < depth:
                        continue
                    candidate_leaf = "/".join(parts[-depth:])
                    if candidate_leaf == incoming_leaf:
                        matches_at_depth.append(candidate)

                # If exactly one match at this depth, use it
                if len(matches_at_depth) == 1:
                    return matches_at_depth[0]
                # If no matches, try deeper
                # If multiple matches, continue deeper to disambiguate

        # POSE MATCHING: Compare pose annotations (default in AUTO)
        if labels_incoming is not None and labels_base is not None:
            match = self._match_by_poses(
                incoming, viable, labels_incoming, labels_base
            )
            if match is not None:
                return match

        # IMAGE MATCHING: Compare frame images (opt-in)
        if self.compare_images:
            match = self._match_by_images(incoming, viable)
            if match is not None:
                return match

        # No match found
        return None

    else:
        # Non-AUTO methods: use pairwise match()
        for candidate in candidates:
            if self.match(candidate, incoming):
                return candidate
        return None

`match(video1, video2)` ¶

Check if two videos match according to the configured method.

For AUTO method, this performs pairwise checks (file identity, path match). For full AUTO matching with leaf-uniqueness, use find_match() instead.

Source code in sleap_io/model/matching.py

def match(self, video1: Video, video2: Video) -> bool:
    """Check if two videos match according to the configured method.

    For AUTO method, this performs pairwise checks (file identity, path match).
    For full AUTO matching with leaf-uniqueness, use find_match() instead.
    """
    if self.method == VideoMatchMethod.AUTO:
        # Pairwise AUTO: rejection checks + definitive identity + path match
        # (Leaf-uniqueness requires full candidate list - use find_match())

        # Rejection: incompatible shapes
        if shapes_compatible(video1, video2) is False:
            return False

        # Rejection: conflicting provenance
        if original_videos_conflict(video1, video2):
            return False

        # Definitive: same source file but different crop (mosaic tiles).
        # Must run before any path rung, which would otherwise re-match the
        # shared root file. For non-crop videos this is always False.
        if _same_file_different_crop(video1, video2):
            return False

        # Definitive: same file identity (crop-aware)
        if is_same_file(video1, video2):
            return True

        # String: strict path match
        if video1.matches_path(video2, strict=True):
            return True

        # String: basename match (for pairwise, this is the fallback)
        if video1.matches_path(video2, strict=False):
            return True

        return False

    elif self.method == VideoMatchMethod.PATH:
        return video1.matches_path(video2, strict=self.strict)
    elif self.method == VideoMatchMethod.BASENAME:
        return video1.matches_path(video2, strict=False)
    elif self.method == VideoMatchMethod.CONTENT:
        return video1.matches_content(video2)
    elif self.method == VideoMatchMethod.IMAGE_DEDUP:
        # Match ImageVideo instances with overlapping images (ImageVideo only)
        return video1.has_overlapping_images(video2)
    elif self.method == VideoMatchMethod.SHAPE:
        # Match videos by shape only (height, width, channels)
        return video1.matches_shape(video2)
    else:
        raise ValueError(f"Unknown video match method: {self.method}")

`is_same_file(video1, video2)` ¶

Check if two videos refer to the same underlying file.

This provides definitive file identity checking by: - Traversing source_video/original_video chains to find root videos - Using os.path.samefile() when files exist (handles symlinks) - Falling back to path resolution and string comparison - Requiring matching crop rects (so two distinct crops of one source file -- e.g. mosaic tiles -- are NOT collapsed into one video)

Parameters:

Name	Type	Description	Default
`video1`	`Video`	First video to compare.	required
`video2`	`Video`	Second video to compare.	required

Returns:

Type	Description
`bool`	True if both videos refer to the same underlying file AND have the same crop identity.

Notes

This is stricter than matches_path(strict=False) - it only returns True when files are verifiably the same, not just same basename.

The crop keys are read from the ORIGINAL videos (not the resolved roots): two tiles share one uncropped source whose own crop key is None, so the disambiguation must use each video's own crop rect. For non-cropped videos both keys are None, so behavior is unchanged.

Source code in sleap_io/model/matching.py

def is_same_file(video1: Video, video2: Video) -> bool:
    """Check if two videos refer to the same underlying file.

    This provides definitive file identity checking by:
    - Traversing source_video/original_video chains to find root videos
    - Using os.path.samefile() when files exist (handles symlinks)
    - Falling back to path resolution and string comparison
    - Requiring matching crop rects (so two distinct crops of one source file
      -- e.g. mosaic tiles -- are NOT collapsed into one video)

    Args:
        video1: First video to compare.
        video2: Second video to compare.

    Returns:
        True if both videos refer to the same underlying file AND have the same
        crop identity.

    Notes:
        This is stricter than matches_path(strict=False) - it only returns True
        when files are verifiably the same, not just same basename.

        The crop keys are read from the ORIGINAL videos (not the resolved
        roots): two tiles share one uncropped source whose own crop key is
        ``None``, so the disambiguation must use each video's own crop rect.
        For non-cropped videos both keys are ``None``, so behavior is unchanged.
    """
    root1 = _get_root_video(video1)
    root2 = _get_root_video(video2)
    if not _is_same_file_direct(root1, root2):
        return False
    # Same underlying file: distinct crops of it are distinct videos.
    return _crop_key(video1) == _crop_key(video2)

`original_videos_conflict(video1, video2)` ¶

Check if two videos have conflicting original_video references.

This is used for REJECTION in video matching. If both videos have provenance info pointing to verifiably different files, they definitely don't match (even if shapes are identical).

Returns True only if both videos have provenance pointing to verifiably different files. If files don't exist and can't be verified, returns False to allow fall-through to other matching strategies (pose, image).

Parameters:

Name	Type	Description	Default
`video1`	`Video`	First video to compare.	required
`video2`	`Video`	Second video to compare.	required

Returns:

Type	Description
`bool`	True if both have provenance AND their roots point to verifiably different files. False otherwise (including if either or both have no provenance, or if files don't exist and can't be verified).

Example

Two videos with identical basenames and shapes but from different directories would conflict if both have original_video set to their respective source paths AND those files exist on disk.

Source code in sleap_io/model/matching.py

def original_videos_conflict(video1: Video, video2: Video) -> bool:
    """Check if two videos have conflicting original_video references.

    This is used for REJECTION in video matching. If both videos have
    provenance info pointing to verifiably different files, they definitely
    don't match (even if shapes are identical).

    Returns True only if both videos have provenance pointing to verifiably
    different files. If files don't exist and can't be verified, returns False
    to allow fall-through to other matching strategies (pose, image).

    Args:
        video1: First video to compare.
        video2: Second video to compare.

    Returns:
        True if both have provenance AND their roots point to verifiably
        different files. False otherwise (including if either or both have
        no provenance, or if files don't exist and can't be verified).

    Example:
        Two videos with identical basenames and shapes but from different
        directories would conflict if both have original_video set to their
        respective source paths AND those files exist on disk.
    """
    root1 = _get_root_video(video1)
    root2 = _get_root_video(video2)

    # Only conflict if BOTH have non-trivial chains (provenance info set)
    # AND the roots are different
    has_provenance1 = (
        video1.original_video is not None or video1.source_video is not None
    )
    has_provenance2 = (
        video2.original_video is not None or video2.source_video is not None
    )

    if not (has_provenance1 and has_provenance2):
        # At least one has no provenance - no conflict
        return False

    # Both have provenance - check if roots are the same file
    if _is_same_file_direct(root1, root2):
        return False  # Definitely same - no conflict

    # If neither file exists, we can't verify - don't reject
    if not _file_exists(root1.filename) and not _file_exists(root2.filename):
        return False  # Can't verify, allow fall-through to other matching

    # At least one file exists and they don't match - conflict
    return True

`shapes_compatible(video1, video2)` ¶

Check if two videos have compatible shapes.

This is used for REJECTION only in video matching - incompatible shapes mean the videos definitely don't match. Compatible shapes (or unknown) do NOT imply the videos are the same.

Parameters:

Name	Type	Description	Default
`video1`	`Video`	First video to compare.	required
`video2`	`Video`	Second video to compare.	required

Returns:

Type	Description
`bool \| None`	False if shapes are definitely incompatible (different frames, H, or W). True if shapes are compatible. None if shape cannot be determined (missing metadata).

Notes

Per algorithm design: Compare (frames, height, width) but NOT channels. Channels are excluded because grayscale detection is noisy (affected by compression) and user-configurable.

Source code in sleap_io/model/matching.py

def shapes_compatible(video1: Video, video2: Video) -> bool | None:
    """Check if two videos have compatible shapes.

    This is used for REJECTION only in video matching - incompatible shapes
    mean the videos definitely don't match. Compatible shapes (or unknown)
    do NOT imply the videos are the same.

    Args:
        video1: First video to compare.
        video2: Second video to compare.

    Returns:
        False if shapes are definitely incompatible (different frames, H, or W).
        True if shapes are compatible.
        None if shape cannot be determined (missing metadata).

    Notes:
        Per algorithm design: Compare (frames, height, width) but NOT channels.
        Channels are excluded because grayscale detection is noisy (affected
        by compression) and user-configurable.
    """
    shape1 = _get_effective_shape(video1)
    shape2 = _get_effective_shape(video2)

    # If either shape is unknown, we can't determine compatibility
    if shape1 is None or shape2 is None:
        return None

    # Compare frames, height, width (indices 0, 1, 2) - NOT channels (index 3)
    return (
        shape1[0] == shape2[0]  # frames
        and shape1[1] == shape2[1]  # height
        and shape1[2] == shape2[2]  # width
    )

Name	Description
`__attrs_post_init__`	Post init syntactic sugar.
`__deepcopy__`	Deep copy the video object.
`__getitem__`	Return the frames of the video at the given indices.
`__init__`	Method generated by attrs for class Video.
`__len__`	Return the length of the video as the number of frames.
`__repr__`	Informal string representation (for print or format).
`__str__`	Informal string representation (for print or format).
`apply_crop`	Bake this video's virtual crop into a new physical video file.
`close`	Close the video backend.
`crop`	Return a virtual, on-read cropped view of this video.
`deduplicate_with`	Create a new video with duplicate images removed.
`exists`	Check if the video file exists and is accessible.
`frame_to_seconds`	Convert a frame index to timestamp in seconds.
`from_crop`	Open `video` (path or `Video`) and return a virtual crop.
`from_filename`	Create a Video from a filename.
`has_overlapping_images`	Check if this video has overlapping images with another video.
`matches_content`	Check if this video has the same content as another video.
`matches_path`	Check if this video has the same path as another video.
`matches_shape`	Check if this video has the same shape as another video.
`merge_with`	Merge another video's images into this one.
`open`	Open the video backend for reading.
`replace_filename`	Update the filename of the video, optionally opening the backend.
`save`	Save video frames to a new video file.
`seconds_to_frame`	Convert a timestamp in seconds to frame index.
`set_video_plugin`	Set the video plugin and reopen the video.
`to_crop_coords`	Map source-frame `(x, y)` into this video's cropped frame.
`to_source_coords`	Map cropped-frame `(x, y)` back to source-frame coordinates.

matching

sleap_io.model.matching ¶

AUTO_VIDEO_MATCHER = VideoMatcher(method=<VideoMatchMethod.AUTO: 'auto'>, strict=False, content_frames=3, compare_predictions='auto', compare_images=False, image_similarity_threshold=0.05) module-attribute ¶

BASENAME_VIDEO_MATCHER = VideoMatcher(method=<VideoMatchMethod.BASENAME: 'basename'>, strict=False, content_frames=3, compare_predictions='auto', compare_images=False, image_similarity_threshold=0.05) module-attribute ¶

DUPLICATE_MATCHER = InstanceMatcher(method=<InstanceMatchMethod.SPATIAL: 'spatial'>, threshold=5.0) module-attribute ¶

IDENTITY_INSTANCE_MATCHER = InstanceMatcher(method=<InstanceMatchMethod.IDENTITY: 'identity'>, threshold=5.0) module-attribute ¶

IDENTITY_TRACK_MATCHER = TrackMatcher(method=<TrackMatchMethod.IDENTITY: 'identity'>) module-attribute ¶

IMAGE_DEDUP_VIDEO_MATCHER = VideoMatcher(method=<VideoMatchMethod.IMAGE_DEDUP: 'image_dedup'>, strict=False, content_frames=3, compare_predictions='auto', compare_images=False, image_similarity_threshold=0.05) module-attribute ¶

IOU_MATCHER = InstanceMatcher(method=<InstanceMatchMethod.IOU: 'iou'>, threshold=0.5) module-attribute ¶

NAME_CATEGORY_MATCHER = CategoryMatcher(method=<CategoryMatchMethod.NAME: 'name'>) module-attribute ¶

NAME_IDENTITY_MATCHER = IdentityMatcher(method=<IdentityMatchMethod.NAME: 'name'>) module-attribute ¶

NAME_TRACK_MATCHER = TrackMatcher(method=<TrackMatchMethod.NAME: 'name'>) module-attribute ¶

OVERLAP_SKELETON_MATCHER = SkeletonMatcher(method=<SkeletonMatchMethod.OVERLAP: 'overlap'>, require_same_order=False, min_overlap=0.7) module-attribute ¶

PATH_VIDEO_MATCHER = VideoMatcher(method=<VideoMatchMethod.PATH: 'path'>, strict=True, content_frames=3, compare_predictions='auto', compare_images=False, image_similarity_threshold=0.05) module-attribute ¶

SHAPE_VIDEO_MATCHER = VideoMatcher(method=<VideoMatchMethod.SHAPE: 'shape'>, strict=False, content_frames=3, compare_predictions='auto', compare_images=False, image_similarity_threshold=0.05) module-attribute ¶

STRUCTURE_SKELETON_MATCHER = SkeletonMatcher(method=<SkeletonMatchMethod.STRUCTURE: 'structure'>, require_same_order=False, min_overlap=0.5) module-attribute ¶

SUBSET_SKELETON_MATCHER = SkeletonMatcher(method=<SkeletonMatchMethod.SUBSET: 'subset'>, require_same_order=False, min_overlap=0.5) module-attribute ¶

TYPE_CHECKING = False module-attribute ¶

__cached__ = '/home/runner/work/sleap-io/sleap-io/sleap_io/model/__pycache__/matching.cpython-313.pyc' module-attribute ¶

__file__ = '/home/runner/work/sleap-io/sleap-io/sleap_io/model/matching.py' module-attribute ¶

__name__ = 'sleap_io.model.matching' module-attribute ¶

__package__ = 'sleap_io.model' module-attribute ¶

Category ¶

__annotations__ = {'name': 'str', 'metadata': 'dict[str, str]'} class-attribute ¶

__attrs_own_setattr__ = True class-attribute ¶

__firstlineno__ = 9 class-attribute ¶

__match_args__ = ('name', 'metadata') class-attribute ¶

__module__ = 'sleap_io.model.category' class-attribute ¶

__slots__ = ('name', 'metadata', '__weakref__') class-attribute ¶

__static_attributes__ = () class-attribute ¶

__weakref__ property ¶

__init__(name='', metadata=NOTHING) ¶

__repr__() ¶

__setattr__(name, val) ¶

matches(other, method='name') ¶

CategoryMatchMethod ¶

IDENTITY = <CategoryMatchMethod.IDENTITY: 'identity'> class-attribute ¶

NAME = <CategoryMatchMethod.NAME: 'name'> class-attribute ¶

__doc__ = 'Methods for matching categories.\n\nAttributes:\n NAME: Match categories by their `name` attribute, which survives\n serialization and cross-file merges (default).\n IDENTITY: Match categories by Python object identity (same object).\n' class-attribute ¶

__module__ = 'sleap_io.model.matching' class-attribute ¶

CategoryMatcher ¶

__annotations__ = {'method': 'CategoryMatchMethod | str'} class-attribute ¶

__attrs_own_setattr__ = True class-attribute ¶

__firstlineno__ = 925 class-attribute ¶

__match_args__ = ('method',) class-attribute ¶

__module__ = 'sleap_io.model.matching' class-attribute ¶

__slots__ = ('method', '__weakref__') class-attribute ¶

__static_attributes__ = () class-attribute ¶

__weakref__ property ¶

__eq__(other) ¶

__init__(method=<CategoryMatchMethod.NAME: 'name'>) ¶

__repr__() ¶

__setattr__(name, val) ¶

match(category1, category2) ¶

ConflictResolution ¶

__annotations__ = {'frame': 'LabeledFrame', 'conflict_type': 'str', 'original_data': 'Any', 'new_data': 'Any', 'resolution': 'str'} class-attribute ¶

__attrs_own_setattr__ = False class-attribute ¶

__firstlineno__ = 1321 class-attribute ¶

__match_args__ = ('frame', 'conflict_type', 'original_data', 'new_data', 'resolution') class-attribute ¶

__module__ = 'sleap_io.model.matching' class-attribute ¶

__slots__ = ('frame', 'conflict_type', 'original_data', 'new_data', 'resolution', '__weakref__') class-attribute ¶

__static_attributes__ = () class-attribute ¶

__weakref__ property ¶

__eq__(other) ¶

__init__(frame, conflict_type, original_data, new_data, resolution) ¶

__repr__() ¶

ErrorMode ¶

CONTINUE = <ErrorMode.CONTINUE: 'continue'> class-attribute ¶

STRICT = <ErrorMode.STRICT: 'strict'> class-attribute ¶

WARN = <ErrorMode.WARN: 'warn'> class-attribute ¶

__doc__ = 'Error handling modes for merge operations.\n\nAttributes:\n CONTINUE: Continue merging on errors, collecting them in the result.\n STRICT: Raise an exception on the first error encountered.\n WARN: Issue warnings about errors but continue merging.\n' class-attribute ¶

__module__ = 'sleap_io.model.matching' class-attribute ¶

FrameStrategy ¶

AUTO = <FrameStrategy.AUTO: 'auto'> class-attribute ¶

KEEP_BOTH = <FrameStrategy.KEEP_BOTH: 'keep_both'> class-attribute ¶

KEEP_NEW = <FrameStrategy.KEEP_NEW: 'keep_new'> class-attribute ¶

KEEP_ORIGINAL = <FrameStrategy.KEEP_ORIGINAL: 'keep_original'> class-attribute ¶

REPLACE_PREDICTIONS = <FrameStrategy.REPLACE_PREDICTIONS: 'replace_predictions'> class-attribute ¶

UPDATE_TRACKS = <FrameStrategy.UPDATE_TRACKS: 'update_tracks'> class-attribute ¶

__module__ = 'sleap_io.model.matching' class-attribute ¶

`sleap_io.model.matching` ¶

`AUTO_VIDEO_MATCHER = VideoMatcher(method=<VideoMatchMethod.AUTO: 'auto'>, strict=False, content_frames=3, compare_predictions='auto', compare_images=False, image_similarity_threshold=0.05)` `module-attribute` ¶

`BASENAME_VIDEO_MATCHER = VideoMatcher(method=<VideoMatchMethod.BASENAME: 'basename'>, strict=False, content_frames=3, compare_predictions='auto', compare_images=False, image_similarity_threshold=0.05)` `module-attribute` ¶

`DUPLICATE_MATCHER = InstanceMatcher(method=<InstanceMatchMethod.SPATIAL: 'spatial'>, threshold=5.0)` `module-attribute` ¶

`IDENTITY_INSTANCE_MATCHER = InstanceMatcher(method=<InstanceMatchMethod.IDENTITY: 'identity'>, threshold=5.0)` `module-attribute` ¶

`IDENTITY_TRACK_MATCHER = TrackMatcher(method=<TrackMatchMethod.IDENTITY: 'identity'>)` `module-attribute` ¶

`IMAGE_DEDUP_VIDEO_MATCHER = VideoMatcher(method=<VideoMatchMethod.IMAGE_DEDUP: 'image_dedup'>, strict=False, content_frames=3, compare_predictions='auto', compare_images=False, image_similarity_threshold=0.05)` `module-attribute` ¶

`IOU_MATCHER = InstanceMatcher(method=<InstanceMatchMethod.IOU: 'iou'>, threshold=0.5)` `module-attribute` ¶

`NAME_CATEGORY_MATCHER = CategoryMatcher(method=<CategoryMatchMethod.NAME: 'name'>)` `module-attribute` ¶

`NAME_IDENTITY_MATCHER = IdentityMatcher(method=<IdentityMatchMethod.NAME: 'name'>)` `module-attribute` ¶

`NAME_TRACK_MATCHER = TrackMatcher(method=<TrackMatchMethod.NAME: 'name'>)` `module-attribute` ¶

`OVERLAP_SKELETON_MATCHER = SkeletonMatcher(method=<SkeletonMatchMethod.OVERLAP: 'overlap'>, require_same_order=False, min_overlap=0.7)` `module-attribute` ¶

`PATH_VIDEO_MATCHER = VideoMatcher(method=<VideoMatchMethod.PATH: 'path'>, strict=True, content_frames=3, compare_predictions='auto', compare_images=False, image_similarity_threshold=0.05)` `module-attribute` ¶

`SHAPE_VIDEO_MATCHER = VideoMatcher(method=<VideoMatchMethod.SHAPE: 'shape'>, strict=False, content_frames=3, compare_predictions='auto', compare_images=False, image_similarity_threshold=0.05)` `module-attribute` ¶

`STRUCTURE_SKELETON_MATCHER = SkeletonMatcher(method=<SkeletonMatchMethod.STRUCTURE: 'structure'>, require_same_order=False, min_overlap=0.5)` `module-attribute` ¶

`SUBSET_SKELETON_MATCHER = SkeletonMatcher(method=<SkeletonMatchMethod.SUBSET: 'subset'>, require_same_order=False, min_overlap=0.5)` `module-attribute` ¶

`TYPE_CHECKING = False` `module-attribute` ¶

`cached = '/home/runner/work/sleap-io/sleap-io/sleap_io/model/pycache/matching.cpython-313.pyc'` `module-attribute` ¶

`file = '/home/runner/work/sleap-io/sleap-io/sleap_io/model/matching.py'` `module-attribute` ¶

`name = 'sleap_io.model.matching'` `module-attribute` ¶

`package = 'sleap_io.model'` `module-attribute` ¶

`Category` ¶

`annotations = {'name': 'str', 'metadata': 'dict[str, str]'}` `class-attribute` ¶

`__attrs_own_setattr__ = True` `class-attribute` ¶

`firstlineno = 9` `class-attribute` ¶

`__match_args__ = ('name', 'metadata')` `class-attribute` ¶

`module = 'sleap_io.model.category'` `class-attribute` ¶

`slots = ('name', 'metadata', 'weakref')` `class-attribute` ¶

`__static_attributes__ = ()` `class-attribute` ¶

`weakref` `property` ¶

`init(name='', metadata=NOTHING)` ¶

`repr()` ¶

`setattr(name, val)` ¶

`matches(other, method='name')` ¶

`CategoryMatchMethod` ¶

`IDENTITY = <CategoryMatchMethod.IDENTITY: 'identity'>` `class-attribute` ¶

`NAME = <CategoryMatchMethod.NAME: 'name'>` `class-attribute` ¶

doc = 'Methods for matching categories.\n\nAttributes:\n NAME: Match categories by their `name` attribute, which survives\n serialization and cross-file merges (default).\n IDENTITY: Match categories by Python object identity (same object).\n' `class-attribute` ¶

`module = 'sleap_io.model.matching'` `class-attribute` ¶

`CategoryMatcher` ¶

`annotations = {'method': 'CategoryMatchMethod | str'}` `class-attribute` ¶

`__attrs_own_setattr__ = True` `class-attribute` ¶

`firstlineno = 925` `class-attribute` ¶

`__match_args__ = ('method',)` `class-attribute` ¶

`module = 'sleap_io.model.matching'` `class-attribute` ¶

`slots = ('method', 'weakref')` `class-attribute` ¶

`__static_attributes__ = ()` `class-attribute` ¶

`weakref` `property` ¶

`eq(other)` ¶

`init(method=<CategoryMatchMethod.NAME: 'name'>)` ¶

`repr()` ¶

`setattr(name, val)` ¶

`match(category1, category2)` ¶

`ConflictResolution` ¶

`annotations = {'frame': 'LabeledFrame', 'conflict_type': 'str', 'original_data': 'Any', 'new_data': 'Any', 'resolution': 'str'}` `class-attribute` ¶

`__attrs_own_setattr__ = False` `class-attribute` ¶

`firstlineno = 1321` `class-attribute` ¶

`__match_args__ = ('frame', 'conflict_type', 'original_data', 'new_data', 'resolution')` `class-attribute` ¶

`module = 'sleap_io.model.matching'` `class-attribute` ¶

`slots = ('frame', 'conflict_type', 'original_data', 'new_data', 'resolution', 'weakref')` `class-attribute` ¶

`__static_attributes__ = ()` `class-attribute` ¶

`weakref` `property` ¶

`eq(other)` ¶

`init(frame, conflict_type, original_data, new_data, resolution)` ¶

`repr()` ¶

`ErrorMode` ¶

`CONTINUE = <ErrorMode.CONTINUE: 'continue'>` `class-attribute` ¶

`STRICT = <ErrorMode.STRICT: 'strict'>` `class-attribute` ¶

`WARN = <ErrorMode.WARN: 'warn'>` `class-attribute` ¶

`doc = 'Error handling modes for merge operations.\n\nAttributes:\n CONTINUE: Continue merging on errors, collecting them in the result.\n STRICT: Raise an exception on the first error encountered.\n WARN: Issue warnings about errors but continue merging.\n'` `class-attribute` ¶

`module = 'sleap_io.model.matching'` `class-attribute` ¶

`FrameStrategy` ¶

`AUTO = <FrameStrategy.AUTO: 'auto'>` `class-attribute` ¶

`KEEP_BOTH = <FrameStrategy.KEEP_BOTH: 'keep_both'>` `class-attribute` ¶

`KEEP_NEW = <FrameStrategy.KEEP_NEW: 'keep_new'>` `class-attribute` ¶

`KEEP_ORIGINAL = <FrameStrategy.KEEP_ORIGINAL: 'keep_original'>` `class-attribute` ¶

`REPLACE_PREDICTIONS = <FrameStrategy.REPLACE_PREDICTIONS: 'replace_predictions'>` `class-attribute` ¶

`UPDATE_TRACKS = <FrameStrategy.UPDATE_TRACKS: 'update_tracks'>` `class-attribute` ¶

`module = 'sleap_io.model.matching'` `class-attribute` ¶

`Identity` ¶