3D¶

sleap-io supports multi-camera setups for 3D pose reconstruction. A RecordingSession ties together camera calibrations, synchronized videos, and cross-camera instance matching, making it straightforward to work with multi-view data in a single unified data model.

How the types fit together¶

Camera stores calibration data for a single viewpoint: intrinsic matrix, distortion coefficients, and extrinsic pose (rotation + translation).
CameraGroup groups the cameras that are used together in a multi-view rig.
RecordingSession links each camera to its video and holds frame groups for cross-view annotations.
FrameGroup matches the labeled frames from each camera at the same time point.
InstanceGroup matches instances of the same animal across cameras for 3D triangulation.

The main relationships are: RecordingSession → CameraGroup → Camera for calibration, and RecordingSession → FrameGroup → InstanceGroup for cross-view correspondences. Sessions are stored on Labels.sessions so that multi-view data travels alongside the rest of the annotations.

Camera¶

A Camera stores everything needed to map between 3D world coordinates and 2D pixel coordinates for a single viewpoint:

Intrinsic parameters: the 3x3 camera matrix encoding focal length and principal point, plus radial-tangential distortion coefficients.
Extrinsic parameters: the camera's position and orientation in world coordinates, stored as a rotation vector (rvec, axis-angle representation) and translation vector (tvec). An extrinsic 4x4 matrix is derived automatically and stays in sync when either vector is updated.

>>> import sleap_io as sio
>>> import numpy as np
>>> cam = sio.Camera(
...     matrix=np.array([[500, 0, 320], [0, 500, 240], [0, 0, 1]], dtype="float64"),
...     dist=np.zeros(5),
...     size=(640, 480),
...     rvec=np.zeros(3),
...     tvec=np.array([0, 0, 1], dtype="float64"),
...     name="cam_top",
... )
>>> print(cam.name)
cam_top
>>> print(cam.size)
(640, 480)
>>> print(cam.matrix)
[[500.   0. 320.]
 [  0. 500. 240.]
 [  0.   0.   1.]]

The matrix field follows the standard pinhole camera model:

\[ K = \begin{bmatrix} f_x & 0 & c_x \\ 0 & f_y & c_y \\ 0 & 0 & 1 \end{bmatrix} \]

where \(f_x, f_y\) are focal lengths in pixels and \((c_x, c_y)\) is the principal point.

The five distortion coefficients follow OpenCV ordering: \([k_1, k_2, p_1, p_2, k_3]\).

Camera group¶

A CameraGroup collects the set of cameras that were used together in a multi-view rig. This is primarily an organizational container: it holds a list of Camera objects and optional metadata.

>>> import sleap_io as sio
>>> import numpy as np
>>> cam = sio.Camera(
...     matrix=np.array([[500, 0, 320], [0, 500, 240], [0, 0, 1]], dtype="float64"),
...     dist=np.zeros(5),
...     size=(640, 480),
...     rvec=np.zeros(3),
...     tvec=np.array([0, 0, 1], dtype="float64"),
...     name="cam_top",
... )
>>> cam2 = sio.Camera(
...     matrix=np.eye(3) * 500,
...     dist=np.zeros(5),
...     size=(640, 480),
...     rvec=np.array([0, 0.5, 0]),
...     tvec=np.array([1, 0, 1], dtype="float64"),
...     name="cam_side",
... )
>>> cg = sio.CameraGroup(cameras=[cam, cam2])
>>> print(len(cg.cameras))
2

Recording session¶

A RecordingSession represents a synchronized multi-camera recording. It links each Camera in a CameraGroup to the Video captured from that viewpoint, and it stores FrameGroups that contain the cross-view annotations.

>>> import sleap_io as sio
>>> import numpy as np
>>> cam = sio.Camera(
...     matrix=np.array([[500, 0, 320], [0, 500, 240], [0, 0, 1]], dtype="float64"),
...     dist=np.zeros(5), size=(640, 480), rvec=np.zeros(3),
...     tvec=np.array([0, 0, 1], dtype="float64"), name="cam_top",
... )
>>> cam2 = sio.Camera(
...     matrix=np.eye(3) * 500, dist=np.zeros(5), size=(640, 480),
...     rvec=np.array([0, 0.5, 0]),
...     tvec=np.array([1, 0, 1], dtype="float64"), name="cam_side",
... )
>>> cg = sio.CameraGroup(cameras=[cam, cam2])
>>> vid_top = sio.Video("top_view.mp4", open_backend=False)
>>> vid_side = sio.Video("side_view.mp4", open_backend=False)
>>> session = sio.RecordingSession(
...     camera_group=cg,
...     video_by_camera={cam: vid_top, cam2: vid_side},
...     camera_by_video={vid_top: cam, vid_side: cam2},
... )
>>> print(session.cameras)
[Camera(matrix=non-identity, dist=zero, size=(640, 480), rvec=zero, tvec=[0. 0. 1.], name=cam_top), Camera(matrix=non-identity, dist=zero, size=(640, 480), rvec=[0.  0.5 0. ], tvec=[1. 0. 1.], name=cam_side)]
>>> print(session.videos)
[Video(filename="top_view.mp4", shape=None, backend=NoneType), Video(filename="side_view.mp4", shape=None, backend=NoneType)]
>>> print(session.get_camera(vid_top).name)
cam_top

You can also add or remove video-camera mappings after construction:

# Adding a new camera to an existing session
cam3 = sio.Camera(name="cam_rear")
cg.cameras.append(cam3)
vid_rear = sio.Video("rear_view.mp4", open_backend=False)
session.add_video(vid_rear, cam3)
len(session.videos)  # 3

Frame group¶

A FrameGroup represents a single time point across all camera views. It groups the LabeledFrames from each camera at the same frame index and contains one or more InstanceGroups that define cross-camera correspondences.

Key properties:

frame_idx — the synchronized frame index shared across views.
labeled_frames — the per-camera LabeledFrame objects at this time point.
instance_groups — cross-camera matches for individual animals (see below).
get_frame(camera) — look up the LabeledFrame for a specific camera.

Instance group¶

An InstanceGroup links together 2D Instance annotations of the same animal as seen from different cameras at the same frame. This cross-camera correspondence is the key input for 3D triangulation.

Key properties:

instance_by_camera — dictionary mapping each Camera to the corresponding Instance.
instances — flat list of all matched Instance objects.
cameras — list of cameras that have a matched instance.
instance_3d — optional Instance3D with triangulated 3D keypoints.
points — convenience accessor for instance_3d.points (backwards compatible).
score — optional confidence score for the match.
identity — optional Identity for this group (which animal).

>>> import numpy as np
>>> import sleap_io as sio
>>> skel = sio.Skeleton(nodes=["head", "tail"], edges=[("head", "tail")])
>>> cam1, cam2 = sio.Camera(name="cam1"), sio.Camera(name="cam2")
>>> inst_2d_cam1 = sio.Instance.from_numpy(np.array([[10, 20], [30, 40]]), skeleton=skel)
>>> inst_2d_cam2 = sio.Instance.from_numpy(np.array([[12, 22], [32, 42]]), skeleton=skel)
>>> inst_3d = sio.Instance3D(points=np.array([[1.0, 2.0, 3.0], [4.0, 5.0, 6.0]]), skeleton=skel)
>>> mouse_a = sio.Identity(name="mouse_A")
>>> group = sio.InstanceGroup(
...     instance_by_camera={cam1: inst_2d_cam1, cam2: inst_2d_cam2},
...     instance_3d=inst_3d,
...     identity=mouse_a,
... )
>>> print(len(group.instances), "matched instances")
2 matched instances
>>> print(group.identity.name)
mouse_A

Identity¶

An Identity represents a ground-truth animal that can be recognized across videos, sessions, and experiments. Unlike Track (an ephemeral, video-local temporal trajectory), Identity is the global re-identification key, persistent across recordings, sessions, and multi-view setups.

Key properties:

name — human-readable name (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 dictionary (e.g. {"color": "#e6194b", "strain": "C57BL/6"}). A visualization color, if wanted, is just a conventional metadata["color"] entry.

Identities attach at three levels:

Per instance — Instance.identity + Instance.identity_score assign a global identity to a detection (distinct from the short-term track/tracking_score).
Per multi-view group — InstanceGroup.identity binds the triangulated detections of one animal across cameras; the many per-camera Tracks of an animal map to a single Identity.
Top-level catalog — Labels.identities holds the canonical identity objects, auto-collected from instances.

>>> import sleap_io as sio
>>> mouse_a = sio.Identity(name="mouse_A")
>>> mouse_b = sio.Identity(name="mouse_B")
>>> labels = sio.Labels(identities=[mouse_a, mouse_b])
>>> print([ident.name for ident in labels.identities])
['mouse_A', 'mouse_B']

Matching identities¶

Compare identities with matches() (default method="name"), or configure an IdentityMatcher for merges. Because Identity uses object-identity equality (like Track), two Identity objects with the same name are distinct objects but still match by name — the key that survives serialization and cross-file merges. Pass method="identity" to instead require the same Python object:

>>> import sleap_io as sio
>>> a1 = sio.Identity(name="mouse_A")
>>> a2 = sio.Identity(name="mouse_A")
>>> print(a1.matches(a2))  # same name -> same animal
True
>>> print(a1.matches(a2, method="identity"))  # distinct objects -> no match
False

SLP persistence

The identity catalog and the per-detection identity links (Instance.identity/identity_score) persist in the /identity group at format 2.5+; the appearance vectors (Instance.identity_embedding) persist in the /embeddings group, also at format 2.5+. All are additive, so older readers ignore them and older files round-trip unchanged. See Embeddings and Formats → SLP.

Instance3D¶

An Instance3D stores triangulated 3D keypoints in world coordinates. It is associated with an InstanceGroup that contains the source 2D instances used for triangulation.

Key properties:

points — (N, 3) float64 array of 3D coordinates. NaN values indicate missing keypoints.
skeleton — the Skeleton defining keypoint semantics.
score — optional instance-level confidence score.
n_visible — number of non-NaN keypoints.
is_empty — whether all keypoints are missing.

PredictedInstance3D extends Instance3D with per-keypoint confidence scores in the point_scores field.

>>> import numpy as np
>>> import sleap_io as sio
>>> skel = sio.Skeleton(nodes=["head", "tail"], edges=[("head", "tail")])
>>> pts = np.array([[1.0, 2.0, 3.0], [4.0, 5.0, 6.0]])
>>> inst_3d = sio.Instance3D(points=pts, skeleton=skel)
>>> print(inst_3d.n_visible, inst_3d.is_empty)
2 False
>>> pred_3d = sio.PredictedInstance3D(
...     points=pts, skeleton=skel, point_scores=np.array([0.9, 0.8]),
... )
>>> print(pred_3d.point_scores)
[0.9 0.8]

Both Instance3D and PredictedInstance3D serialize into SLP v1.9+.

Class relationships¶

The following diagram shows how the 3D and multi-view classes relate to each other and to the core data model.

classDiagram
    direction LR

    class CameraGroup:::threed {
        +cameras
        +dict metadata
    }
    class Camera:::threed {
        +ndarray matrix
        +ndarray dist
        +tuple size
        +str name
    }
    class RecordingSession:::threed {
        +CameraGroup camera_group
        +frame_groups
        +videos
    }
    class FrameGroup:::threed {
        +int frame_idx
        +instance_groups
        +labeled_frames
    }
    class InstanceGroup:::threed {
        +instance_by_camera
        +Instance3D instance_3d
        +Identity identity
        +float score
    }
    class Video:::core {
        +str filename
    }
    class LabeledFrame:::core {
        +Video video
        +int frame_idx
    }
    class Instance:::core {
        +PointsArray points
        +Skeleton skeleton
        +Identity identity
        +float identity_score
        +Embedding identity_embedding
    }
    class Identity:::threed {
        +str name
        +dict metadata
    }
    class Instance3D:::threed {
        +ndarray points
        +Skeleton skeleton
        +float score
    }

    CameraGroup "1" *-- "0..*" Camera
    RecordingSession --> CameraGroup : uses
    RecordingSession "1" *-- "0..*" FrameGroup
    RecordingSession --> Video : links

    FrameGroup "1" *-- "0..*" InstanceGroup
    FrameGroup --> LabeledFrame : references

    InstanceGroup --> Instance : links
    InstanceGroup --> Camera : indexed by
    InstanceGroup --> Instance3D : has
    InstanceGroup --> Identity : references

    classDef threed fill:#7b1fa2,stroke:#6a1b9a,color:#fff
    classDef core fill:#546e7a,stroke:#37474f,color:#fff

API reference¶

`sleap_io.Camera` ¶

A camera used to record in a multi-view RecordingSession.

Attributes:

Name	Type	Description
`matrix`		Intrinsic camera matrix of size (3, 3) and type float64.
`dist`		Radial-tangential distortion coefficients [k_1, k_2, p_1, p_2, k_3] of size (5,) and type float64.
`size`		Image size (width, height) of camera in pixels of size (2,) and type int.
`rvec`		Rotation vector in unnormalized axis-angle representation of size (3,) and type float64.
`tvec`		Translation vector of size (3,) and type float64.
`extrinsic_matrix`		Extrinsic matrix of camera of size (4, 4) and type float64.
`name`		Camera name.
`metadata`		Dictionary of metadata.

Methods:

Name	Description
`__attrs_post_init__`	Initialize extrinsic matrix from rotation and translation vectors.
`__init__`	Method generated by attrs for class Camera.
`__repr__`	Return a readable representation of the camera.
`__setattr__`	Method generated by attrs for class Camera.
`get_video`	Get video associated with recording session.

Source code in sleap_io/model/camera.py

@define(eq=False)  # Set eq to false to make class hashable
class Camera:
    """A camera used to record in a multi-view `RecordingSession`.

    Attributes:
        matrix: Intrinsic camera matrix of size (3, 3) and type float64.
        dist: Radial-tangential distortion coefficients [k_1, k_2, p_1, p_2, k_3] of
            size (5,) and type float64.
        size: Image size (width, height) of camera in pixels of size (2,) and type int.
        rvec: Rotation vector in unnormalized axis-angle representation of size (3,) and
            type float64.
        tvec: Translation vector of size (3,) and type float64.
        extrinsic_matrix: Extrinsic matrix of camera of size (4, 4) and type float64.
        name: Camera name.
        metadata: Dictionary of metadata.
    """

    matrix: np.ndarray = field(
        default=np.eye(3),
        converter=lambda x: np.array(x, dtype="float64"),
    )
    dist: np.ndarray = field(
        default=np.zeros(5), converter=lambda x: np.array(x, dtype="float64").ravel()
    )
    size: tuple[int, int] = field(
        default=None, converter=attrs.converters.optional(tuple)
    )
    _rvec: np.ndarray = field(
        default=np.zeros(3), converter=lambda x: np.array(x, dtype="float64").ravel()
    )
    _tvec: np.ndarray = field(
        default=np.zeros(3), converter=lambda x: np.array(x, dtype="float64").ravel()
    )
    name: str = field(default=None, converter=attrs.converters.optional(str))
    _extrinsic_matrix: np.ndarray = field(init=False)
    metadata: dict = field(factory=dict, validator=instance_of(dict))

    @matrix.validator
    @dist.validator
    @size.validator
    @_rvec.validator
    @_tvec.validator
    @_extrinsic_matrix.validator
    def _validate_shape(self, attribute: attrs.Attribute, value):
        """Validate shape of attribute based on metadata.

        Args:
            attribute: Attribute to validate.
            value: Value of attribute to validate.

        Raises:
            ValueError: If attribute shape is not as expected.
        """
        # Define metadata for each attribute
        attr_metadata = {
            "matrix": {"shape": (3, 3), "type": np.ndarray},
            "dist": {"shape": (5,), "type": np.ndarray},
            "size": {"shape": (2,), "type": tuple},
            "_rvec": {"shape": (3,), "type": np.ndarray},
            "_tvec": {"shape": (3,), "type": np.ndarray},
            "_extrinsic_matrix": {"shape": (4, 4), "type": np.ndarray},
        }
        optional_attrs = ["size"]

        # Skip validation if optional attribute is None
        if attribute.name in optional_attrs and value is None:
            return

        # Validate shape of attribute
        expected_shape = attr_metadata[attribute.name]["shape"]
        expected_type = attr_metadata[attribute.name]["type"]
        if np.shape(value) != expected_shape:
            raise ValueError(
                f"{attribute.name} must be a {expected_type} of size {expected_shape}, "
                f"but received shape: {np.shape(value)} and type: {type(value)} for "
                f"value: {value}"
            )

    def __attrs_post_init__(self):
        """Initialize extrinsic matrix from rotation and translation vectors."""
        self._extrinsic_matrix = np.eye(4, dtype="float64")
        self._extrinsic_matrix[:3, :3] = rodrigues_transformation(self._rvec)[0]
        self._extrinsic_matrix[:3, 3] = self._tvec

    @property
    def rvec(self) -> np.ndarray:
        """Get rotation vector of camera.

        Returns:
            Rotation vector of camera of size 3.
        """
        return self._rvec

    @rvec.setter
    def rvec(self, value: np.ndarray):
        """Set rotation vector and update extrinsic matrix.

        Args:
            value: Rotation vector of size 3.
        """
        self._rvec = value
        self._extrinsic_matrix[:3, :3] = rodrigues_transformation(self._rvec)[0]

    @property
    def tvec(self) -> np.ndarray:
        """Get translation vector of camera.

        Returns:
            Translation vector of camera of size 3.
        """
        return self._tvec

    @tvec.setter
    def tvec(self, value: np.ndarray):
        """Set translation vector and update extrinsic matrix.

        Args:
            value: Translation vector of size 3.
        """
        self._tvec = value

        # Update extrinsic matrix
        self._extrinsic_matrix[:3, 3] = self._tvec

    @property
    def extrinsic_matrix(self) -> np.ndarray:
        """Get extrinsic matrix of camera.

        Returns:
            Extrinsic matrix of camera of size 4 x 4.
        """
        return self._extrinsic_matrix

    @extrinsic_matrix.setter
    def extrinsic_matrix(self, value: np.ndarray):
        """Set extrinsic matrix and update rotation and translation vectors.

        Args:
            value: Extrinsic matrix of size 4 x 4.
        """
        self._extrinsic_matrix = value

        # Update rotation and translation vectors
        self._rvec = rodrigues_transformation(self._extrinsic_matrix[:3, :3])[0].ravel()
        self._tvec = self._extrinsic_matrix[:3, 3]

    def get_video(self, session: RecordingSession) -> Video | None:
        """Get video associated with recording session.

        Args:
            session: Recording session to get video for.

        Returns:
            Video associated with recording session or None if not found.
        """
        return session.get_video(camera=self)

    def __repr__(self) -> str:
        """Return a readable representation of the camera."""
        matrix_str = (
            "identity" if np.array_equal(self.matrix, np.eye(3)) else "non-identity"
        )
        dist_str = "zero" if np.array_equal(self.dist, np.zeros(5)) else "non-zero"
        size_str = "None" if self.size is None else self.size
        rvec_str = (
            "zero"
            if np.array_equal(self.rvec, np.zeros(3))
            else np.array2string(self.rvec, precision=2, suppress_small=True)
        )
        tvec_str = (
            "zero"
            if np.array_equal(self.tvec, np.zeros(3))
            else np.array2string(self.tvec, precision=2, suppress_small=True)
        )
        name_str = self.name if self.name is not None else "None"
        return (
            "Camera("
            f"matrix={matrix_str}, "
            f"dist={dist_str}, "
            f"size={size_str}, "
            f"rvec={rvec_str}, "
            f"tvec={tvec_str}, "
            f"name={name_str}"
            ")"
        )

`annotations = {'matrix': 'np.ndarray', 'dist': 'np.ndarray', 'size': 'tuple[int, int]', '_rvec': 'np.ndarray', '_tvec': 'np.ndarray', 'name': 'str', '_extrinsic_matrix': 'np.ndarray', 'metadata': '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=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 camera used to record in a multi-view `RecordingSession`.\n\nAttributes:\n matrix: Intrinsic camera matrix of size (3, 3) and type float64.\n dist: Radial-tangential distortion coefficients [k_1, k_2, p_1, p_2, k_3] of\n size (5,) and type float64.\n size: Image size (width, height) of camera in pixels of size (2,) and type int.\n rvec: Rotation vector in unnormalized axis-angle representation of size (3,) and\n type float64.\n tvec: Translation vector of size (3,) and type float64.\n extrinsic_matrix: Extrinsic matrix of camera of size (4, 4) and type float64.\n name: Camera name.\n metadata: Dictionary of metadata.\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 = 257` `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.

int('0b100', base=0) 4

`__match_args__ = ('matrix', 'dist', 'size', '_rvec', '_tvec', '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.camera'` `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 = ('matrix', 'dist', 'size', '_rvec', '_tvec', 'name', '_extrinsic_matrix', '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__ = ('_extrinsic_matrix', '_rvec', '_tvec')` `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

`extrinsic_matrix` `property` ¶

Get extrinsic matrix of camera.

Returns:

Type	Description
	Extrinsic matrix of camera of size 4 x 4.

`rvec` `property` ¶

Get rotation vector of camera.

Returns:

Type	Description
	Rotation vector of camera of size 3.

`tvec` `property` ¶

Get translation vector of camera.

Returns:

Type	Description
	Translation vector of camera of size 3.

`__attrs_post_init__()` ¶

Initialize extrinsic matrix from rotation and translation vectors.

Source code in sleap_io/model/camera.py

def __attrs_post_init__(self):
    """Initialize extrinsic matrix from rotation and translation vectors."""
    self._extrinsic_matrix = np.eye(4, dtype="float64")
    self._extrinsic_matrix[:3, :3] = rodrigues_transformation(self._rvec)[0]
    self._extrinsic_matrix[:3, 3] = self._tvec

`init(matrix=array([[1., 0., 0.],[0., 1., 0.],[0., 0., 1.]]), dist=array([0., 0., 0., 0., 0.]), size=None, rvec=array([0., 0., 0.]), tvec=array([0., 0., 0.]), name=None, metadata=NOTHING)` ¶

Method generated by attrs for class Camera.

Source code in sleap_io/model/camera.py

"""Data structure for a single camera view in a multi-camera setup."""

from __future__ import annotations

import attrs
import numpy as np
from attrs import define, field
from attrs.validators import instance_of

from sleap_io.model.category import Category
from sleap_io.model.identity import Identity
from sleap_io.model.instance import Instance, Instance3D
from sleap_io.model.labeled_frame import LabeledFrame
from sleap_io.model.video import Video


def rodrigues_transformation(input_matrix: np.ndarray) -> tuple[np.ndarray, np.ndarray]:
    """Convert between rotation vector and rotation matrix using Rodrigues' formula.

    This function implements the Rodrigues' rotation formula to convert between:

`repr()` ¶

Return a readable representation of the camera.

Source code in sleap_io/model/camera.py

def __repr__(self) -> str:
    """Return a readable representation of the camera."""
    matrix_str = (
        "identity" if np.array_equal(self.matrix, np.eye(3)) else "non-identity"
    )
    dist_str = "zero" if np.array_equal(self.dist, np.zeros(5)) else "non-zero"
    size_str = "None" if self.size is None else self.size
    rvec_str = (
        "zero"
        if np.array_equal(self.rvec, np.zeros(3))
        else np.array2string(self.rvec, precision=2, suppress_small=True)
    )
    tvec_str = (
        "zero"
        if np.array_equal(self.tvec, np.zeros(3))
        else np.array2string(self.tvec, precision=2, suppress_small=True)
    )
    name_str = self.name if self.name is not None else "None"
    return (
        "Camera("
        f"matrix={matrix_str}, "
        f"dist={dist_str}, "
        f"size={size_str}, "
        f"rvec={rvec_str}, "
        f"tvec={tvec_str}, "
        f"name={name_str}"
        ")"
    )

`setattr(name, val)` ¶

Method generated by attrs for class Camera.

`get_video(session)` ¶

Get video associated with recording session.

Parameters:

Name	Type	Description	Default
`session`	`RecordingSession`	Recording session to get video for.	required

Returns:

Type	Description
`Video \| None`	Video associated with recording session or None if not found.

Source code in sleap_io/model/camera.py

def get_video(self, session: RecordingSession) -> Video | None:
    """Get video associated with recording session.

    Args:
        session: Recording session to get video for.

    Returns:
        Video associated with recording session or None if not found.
    """
    return session.get_video(camera=self)

`sleap_io.CameraGroup` ¶

A group of cameras used to record a multi-view RecordingSession.

Attributes:

Name	Type	Description
`cameras`		List of `Camera` objects in the group.
`metadata`		Dictionary of metadata.

Methods:

Name	Description
`__eq__`	Method generated by attrs for class CameraGroup.
`__init__`	Method generated by attrs for class CameraGroup.
`__repr__`	Return a readable representation of the camera group.
`__setattr__`	Method generated by attrs for class CameraGroup.

Source code in sleap_io/model/camera.py

@define
class CameraGroup:
    """A group of cameras used to record a multi-view `RecordingSession`.

    Attributes:
        cameras: List of `Camera` objects in the group.
        metadata: Dictionary of metadata.
    """

    cameras: "list[Camera]" = field(factory=list, validator=instance_of(list))
    metadata: dict = field(factory=dict, validator=instance_of(dict))

    def __repr__(self):
        """Return a readable representation of the camera group."""
        camera_names = ", ".join([c.name or "None" for c in self.cameras])
        return f"CameraGroup(cameras={len(self.cameras)}:[{camera_names}])"

`annotations = {'cameras': "'list[Camera]'", 'metadata': '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=False, 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 = 'A group of cameras used to record a multi-view `RecordingSession`.\n\nAttributes:\n cameras: List of `Camera` objects in the group.\n metadata: Dictionary of metadata.\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 = 112` `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.

int('0b100', base=0) 4

`__match_args__ = ('cameras', '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.camera'` `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 = ('cameras', '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

`eq(other)` ¶

Method generated by attrs for class CameraGroup.

Source code in sleap_io/model/camera.py

"""Data structure for a single camera view in a multi-camera setup."""

from __future__ import annotations

import attrs
import numpy as np
from attrs import define, field

`init(cameras=NOTHING, metadata=NOTHING)` ¶

Method generated by attrs for class CameraGroup.

Source code in sleap_io/model/camera.py

from attrs.validators import instance_of

from sleap_io.model.category import Category
from sleap_io.model.identity import Identity
from sleap_io.model.instance import Instance, Instance3D
from sleap_io.model.labeled_frame import LabeledFrame
from sleap_io.model.video import Video


def rodrigues_transformation(input_matrix: np.ndarray) -> tuple[np.ndarray, np.ndarray]:
    """Convert between rotation vector and rotation matrix using Rodrigues' formula.

    This function implements the Rodrigues' rotation formula to convert between:

`repr()` ¶

Return a readable representation of the camera group.

Source code in sleap_io/model/camera.py

def __repr__(self):
    """Return a readable representation of the camera group."""
    camera_names = ", ".join([c.name or "None" for c in self.cameras])
    return f"CameraGroup(cameras={len(self.cameras)}:[{camera_names}])"

`setattr(name, val)` ¶

Method generated by attrs for class CameraGroup.

`sleap_io.RecordingSession` ¶

A recording session with multiple cameras.

Attributes:

Name	Type	Description
`camera_group`		`CameraGroup` object containing cameras in the session.
`frame_groups`		Dictionary mapping frame index to `FrameGroup`.
`videos`		List of `Video` objects linked to `Camera`s in the session.
`cameras`		List of `Camera` objects linked to `Video`s in the session.
`metadata`		Dictionary of metadata.

Methods:

Name	Description
`__init__`	Method generated by attrs for class RecordingSession.
`__repr__`	Return a readable representation of the session.
`__setattr__`	Method generated by attrs for class RecordingSession.
`add_video`	Add `video` to `RecordingSession` and mapping to `camera`.
`get_camera`	Get `Camera` associated with `video`.
`get_video`	Get `Video` associated with `camera`.
`remove_video`	Remove `video` from `RecordingSession` and mapping to `Camera`.

Source code in sleap_io/model/camera.py

@define(eq=False)  # Set eq to false to make class hashable
class RecordingSession:
    """A recording session with multiple cameras.

    Attributes:
        camera_group: `CameraGroup` object containing cameras in the session.
        frame_groups: Dictionary mapping frame index to `FrameGroup`.
        videos: List of `Video` objects linked to `Camera`s in the session.
        cameras: List of `Camera` objects linked to `Video`s in the session.
        metadata: Dictionary of metadata.
    """

    camera_group: CameraGroup = field(
        factory=CameraGroup, validator=instance_of(CameraGroup)
    )
    _video_by_camera: "dict[Camera, Video]" = field(
        factory=dict, validator=instance_of(dict)
    )
    _camera_by_video: "dict[Video, Camera]" = field(
        factory=dict, validator=instance_of(dict)
    )
    _frame_group_by_frame_idx: "dict[int, FrameGroup]" = field(
        factory=dict, validator=instance_of(dict)
    )
    metadata: dict = field(factory=dict, validator=instance_of(dict))

    @property
    def frame_groups(self) -> "dict[int, FrameGroup]":
        """Get dictionary of `FrameGroup` objects by frame index.

        Returns:
            Dictionary of `FrameGroup` objects by frame index.
        """
        return self._frame_group_by_frame_idx

    @property
    def videos(self) -> list[Video]:
        """Get list of `Video` objects in the `RecordingSession`.

        Returns:
            List of `Video` objects in `RecordingSession`.
        """
        return list(self._video_by_camera.values())

    @property
    def cameras(self) -> "list[Camera]":
        """Get list of `Camera` objects linked to `Video`s in the `RecordingSession`.

        Returns:
            List of `Camera` objects in `RecordingSession`.
        """
        return list(self._video_by_camera.keys())

    def get_camera(self, video: Video) -> "Camera | None":
        """Get `Camera` associated with `video`.

        Args:
            video: `Video` to get `Camera`

        Returns:
            `Camera` associated with `video` or None if not found
        """
        return self._camera_by_video.get(video, None)

    def get_video(self, camera: "Camera") -> Video | None:
        """Get `Video` associated with `camera`.

        Args:
            camera: `Camera` to get `Video`

        Returns:
            `Video` associated with `camera` or None if not found
        """
        return self._video_by_camera.get(camera, None)

    def add_video(self, video: Video, camera: "Camera"):
        """Add `video` to `RecordingSession` and mapping to `camera`.

        Args:
            video: `Video` object to add to `RecordingSession`.
            camera: `Camera` object to associate with `video`.

        Raises:
            ValueError: If `camera` is not in associated `CameraGroup`.
            ValueError: If `video` is not a `Video` object.
        """
        # Raise ValueError if camera is not in associated camera group
        self.camera_group.cameras.index(camera)

        # Raise ValueError if `Video` is not a `Video` object
        if not isinstance(video, Video):
            raise ValueError(
                f"Expected `Video` object, but received {type(video)} object."
            )

        # Add camera to video mapping
        self._video_by_camera[camera] = video

        # Add video to camera mapping
        self._camera_by_video[video] = camera

    def remove_video(self, video: Video):
        """Remove `video` from `RecordingSession` and mapping to `Camera`.

        Args:
            video: `Video` object to remove from `RecordingSession`.

        Raises:
            ValueError: If `video` is not in associated `RecordingSession`.
        """
        # Remove video from camera mapping
        camera = self._camera_by_video.pop(video)

        # Remove camera from video mapping
        self._video_by_camera.pop(camera)

    def __repr__(self) -> str:
        """Return a readable representation of the session."""
        return (
            "RecordingSession("
            f"camera_group={len(self.camera_group.cameras)}cameras, "
            f"videos={len(self.videos)}, "
            f"frame_groups={len(self.frame_groups)}"
            ")"
        )

`annotations = {'camera_group': 'CameraGroup', '_video_by_camera': "'dict[Camera, Video]'", '_camera_by_video': "'dict[Video, Camera]'", '_frame_group_by_frame_idx': "'dict[int, FrameGroup]'", 'metadata': '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=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 recording session with multiple cameras.\n\nAttributes:\n camera_group: `CameraGroup` object containing cameras in the session.\n frame_groups: Dictionary mapping frame index to `FrameGroup`.\n videos: List of `Video` objects linked to `Camera`s in the session.\n cameras: List of `Camera` objects linked to `Video`s in the session.\n metadata: Dictionary of metadata.\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 = 130` `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.

int('0b100', base=0) 4

`__match_args__ = ('camera_group', '_video_by_camera', '_camera_by_video', '_frame_group_by_frame_idx', '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.camera'` `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 = ('camera_group', '_video_by_camera', '_camera_by_video', '_frame_group_by_frame_idx', '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

`cameras` `property` ¶

Get list of Camera objects linked to Videos in the RecordingSession.

Returns:

Type	Description
	List of `Camera` objects in `RecordingSession`.

`frame_groups` `property` ¶

Get dictionary of FrameGroup objects by frame index.

Returns:

Type	Description
	Dictionary of `FrameGroup` objects by frame index.

`videos` `property` ¶

Get list of Video objects in the RecordingSession.

Returns:

Type	Description
	List of `Video` objects in `RecordingSession`.

`init(camera_group=NOTHING, video_by_camera=NOTHING, camera_by_video=NOTHING, frame_group_by_frame_idx=NOTHING, metadata=NOTHING)` ¶

Method generated by attrs for class RecordingSession.

Source code in sleap_io/model/camera.py

"""Data structure for a single camera view in a multi-camera setup."""

from __future__ import annotations

import attrs
import numpy as np
from attrs import define, field
from attrs.validators import instance_of

from sleap_io.model.category import Category
from sleap_io.model.identity import Identity
from sleap_io.model.instance import Instance, Instance3D
from sleap_io.model.labeled_frame import LabeledFrame
from sleap_io.model.video import Video


def rodrigues_transformation(input_matrix: np.ndarray) -> tuple[np.ndarray, np.ndarray]:
    """Convert between rotation vector and rotation matrix using Rodrigues' formula.

    This function implements the Rodrigues' rotation formula to convert between:
    1. A 3D rotation vector (axis-angle representation) to a 3x3 rotation matrix
    2. A 3x3 rotation matrix to a 3D rotation vector

    Args:
        input_matrix: A 3x3 rotation matrix or a 3x1 rotation vector.

    Returns:
        A tuple containing the converted matrix/vector and the Jacobian (None for now).

`repr()` ¶

Return a readable representation of the session.

Source code in sleap_io/model/camera.py

def __repr__(self) -> str:
    """Return a readable representation of the session."""
    return (
        "RecordingSession("
        f"camera_group={len(self.camera_group.cameras)}cameras, "
        f"videos={len(self.videos)}, "
        f"frame_groups={len(self.frame_groups)}"
        ")"
    )

`setattr(name, val)` ¶

Method generated by attrs for class RecordingSession.

`add_video(video, camera)` ¶

Add video to RecordingSession and mapping to camera.

Parameters:

Name	Type	Description	Default
`video`	`Video`	`Video` object to add to `RecordingSession`.	required
`camera`	`Camera`	`Camera` object to associate with `video`.	required

Raises:

Type	Description
`ValueError`	If `camera` is not in associated `CameraGroup`.
`ValueError`	If `video` is not a `Video` object.

Source code in sleap_io/model/camera.py

def add_video(self, video: Video, camera: "Camera"):
    """Add `video` to `RecordingSession` and mapping to `camera`.

    Args:
        video: `Video` object to add to `RecordingSession`.
        camera: `Camera` object to associate with `video`.

    Raises:
        ValueError: If `camera` is not in associated `CameraGroup`.
        ValueError: If `video` is not a `Video` object.
    """
    # Raise ValueError if camera is not in associated camera group
    self.camera_group.cameras.index(camera)

    # Raise ValueError if `Video` is not a `Video` object
    if not isinstance(video, Video):
        raise ValueError(
            f"Expected `Video` object, but received {type(video)} object."
        )

    # Add camera to video mapping
    self._video_by_camera[camera] = video

    # Add video to camera mapping
    self._camera_by_video[video] = camera

`get_camera(video)` ¶

Get Camera associated with video.

Parameters:

Name	Type	Description	Default
`video`	`Video`	`Video` to get `Camera`	required

Returns:

Type	Description
`Camera \| None`	`Camera` associated with `video` or None if not found

Source code in sleap_io/model/camera.py

def get_camera(self, video: Video) -> "Camera | None":
    """Get `Camera` associated with `video`.

    Args:
        video: `Video` to get `Camera`

    Returns:
        `Camera` associated with `video` or None if not found
    """
    return self._camera_by_video.get(video, None)

`get_video(camera)` ¶

Get Video associated with camera.

Parameters:

Name	Type	Description	Default
`camera`	`Camera`	`Camera` to get `Video`	required

Returns:

Type	Description
`Video \| None`	`Video` associated with `camera` or None if not found

Source code in sleap_io/model/camera.py

def get_video(self, camera: "Camera") -> Video | None:
    """Get `Video` associated with `camera`.

    Args:
        camera: `Camera` to get `Video`

    Returns:
        `Video` associated with `camera` or None if not found
    """
    return self._video_by_camera.get(camera, None)

`remove_video(video)` ¶

Remove video from RecordingSession and mapping to Camera.

Parameters:

Name	Type	Description	Default
`video`	`Video`	`Video` object to remove from `RecordingSession`.	required

Raises:

Type	Description
`ValueError`	If `video` is not in associated `RecordingSession`.

Source code in sleap_io/model/camera.py

def remove_video(self, video: Video):
    """Remove `video` from `RecordingSession` and mapping to `Camera`.

    Args:
        video: `Video` object to remove from `RecordingSession`.

    Raises:
        ValueError: If `video` is not in associated `RecordingSession`.
    """
    # Remove video from camera mapping
    camera = self._camera_by_video.pop(video)

    # Remove camera from video mapping
    self._video_by_camera.pop(camera)

`sleap_io.FrameGroup` ¶

Defines a group of InstanceGroups across views at the same frame index.

Attributes:

Name	Type	Description
`frame_idx`		Frame index for the `FrameGroup`.
`instance_groups`		List of `InstanceGroup`s in the `FrameGroup`.
`cameras`		List of `Camera` objects linked to `LabeledFrame`s in the `FrameGroup`.
`labeled_frames`		List of `LabeledFrame`s in the `FrameGroup`.
`metadata`		Metadata for the `FrameGroup` that is provided but not deserialized.

Methods:

Name	Description
`__init__`	Method generated by attrs for class FrameGroup.
`__repr__`	Return a readable representation of the frame group.
`__setattr__`	Method generated by attrs for class FrameGroup.
`get_frame`	Get `LabeledFrame` associated with `camera`.

Source code in sleap_io/model/camera.py

@define(eq=False)  # Set eq to false to make class hashable
class FrameGroup:
    """Defines a group of `InstanceGroups` across views at the same frame index.

    Attributes:
        frame_idx: Frame index for the `FrameGroup`.
        instance_groups: List of `InstanceGroup`s in the `FrameGroup`.
        cameras: List of `Camera` objects linked to `LabeledFrame`s in the `FrameGroup`.
        labeled_frames: List of `LabeledFrame`s in the `FrameGroup`.
        metadata: Metadata for the `FrameGroup` that is provided but not deserialized.
    """

    frame_idx: int = field(converter=int)
    _instance_groups: list[InstanceGroup] = field(
        factory=list, validator=instance_of(list)
    )
    _labeled_frame_by_camera: dict[Camera, LabeledFrame] = field(
        factory=dict, validator=instance_of(dict)
    )
    metadata: dict = field(factory=dict, validator=instance_of(dict))

    @property
    def instance_groups(self) -> list[InstanceGroup]:
        """List of `InstanceGroup`s."""
        return self._instance_groups

    @property
    def cameras(self) -> "list[Camera]":
        """List of `Camera` objects."""
        return list(self._labeled_frame_by_camera.keys())

    @property
    def labeled_frames(self) -> list[LabeledFrame]:
        """List of `LabeledFrame`s."""
        return list(self._labeled_frame_by_camera.values())

    def get_frame(self, camera: Camera) -> LabeledFrame | None:
        """Get `LabeledFrame` associated with `camera`.

        Args:
            camera: `Camera` to get `LabeledFrame`.

        Returns:
            `LabeledFrame` associated with `camera` or None if not found.
        """
        return self._labeled_frame_by_camera.get(camera, None)

    def __repr__(self) -> str:
        """Return a readable representation of the frame group."""
        cameras_str = ", ".join([c.name or "None" for c in self.cameras])
        return (
            f"FrameGroup("
            f"frame_idx={self.frame_idx},"
            f"instance_groups={len(self.instance_groups)},"
            f"cameras={len(self.cameras)}:[{cameras_str}]"
            f")"
        )

`annotations = {'frame_idx': 'int', '_instance_groups': 'list[InstanceGroup]', '_labeled_frame_by_camera': 'dict[Camera, LabeledFrame]', 'metadata': '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=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 = 'Defines a group of `InstanceGroups` across views at the same frame index.\n\nAttributes:\n frame_idx: Frame index for the `FrameGroup`.\n instance_groups: List of `InstanceGroup`s in the `FrameGroup`.\n cameras: List of `Camera` objects linked to `LabeledFrame`s in the `FrameGroup`.\n labeled_frames: List of `LabeledFrame`s in the `FrameGroup`.\n metadata: Metadata for the `FrameGroup` that is provided but not deserialized.\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 = 551` `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.

int('0b100', base=0) 4

`__match_args__ = ('frame_idx', '_instance_groups', '_labeled_frame_by_camera', '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.camera'` `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_idx', '_instance_groups', '_labeled_frame_by_camera', '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

`cameras` `property` ¶

List of Camera objects.

`instance_groups` `property` ¶

List of InstanceGroups.

`labeled_frames` `property` ¶

List of LabeledFrames.

`init(frame_idx, instance_groups=NOTHING, labeled_frame_by_camera=NOTHING, metadata=NOTHING)` ¶

Method generated by attrs for class FrameGroup.

Source code in sleap_io/model/camera.py

"""Data structure for a single camera view in a multi-camera setup."""

from __future__ import annotations

import attrs
import numpy as np
from attrs import define, field
from attrs.validators import instance_of

from sleap_io.model.category import Category
from sleap_io.model.identity import Identity
from sleap_io.model.instance import Instance, Instance3D
from sleap_io.model.labeled_frame import LabeledFrame
from sleap_io.model.video import Video


def rodrigues_transformation(input_matrix: np.ndarray) -> tuple[np.ndarray, np.ndarray]:
    """Convert between rotation vector and rotation matrix using Rodrigues' formula.

`repr()` ¶

Return a readable representation of the frame group.

Source code in sleap_io/model/camera.py

def __repr__(self) -> str:
    """Return a readable representation of the frame group."""
    cameras_str = ", ".join([c.name or "None" for c in self.cameras])
    return (
        f"FrameGroup("
        f"frame_idx={self.frame_idx},"
        f"instance_groups={len(self.instance_groups)},"
        f"cameras={len(self.cameras)}:[{cameras_str}]"
        f")"
    )

`setattr(name, val)` ¶

Method generated by attrs for class FrameGroup.

`get_frame(camera)` ¶

Get LabeledFrame associated with camera.

Parameters:

Name	Type	Description	Default
`camera`	`Camera`	`Camera` to get `LabeledFrame`.	required

Returns:

Type	Description
`LabeledFrame \| None`	`LabeledFrame` associated with `camera` or None if not found.

Source code in sleap_io/model/camera.py

def get_frame(self, camera: Camera) -> LabeledFrame | None:
    """Get `LabeledFrame` associated with `camera`.

    Args:
        camera: `Camera` to get `LabeledFrame`.

    Returns:
        `LabeledFrame` associated with `camera` or None if not found.
    """
    return self._labeled_frame_by_camera.get(camera, None)

`sleap_io.InstanceGroup` ¶

Defines a group of instances across the same frame index.

Attributes:

Name	Type	Description
`instances_by_camera`		Dictionary of `Instance` objects by `Camera`.
`instances`		List of `Instance` objects in the group.
`cameras`		List of `Camera` objects that have an `Instance` associated.
`score`		Optional score for the `InstanceGroup`. Setting the score will also update the score for all `instances` already in the `InstanceGroup`. The score for `instances` will not be updated upon initialization.
`instance_3d`		Optional `Instance3D` with triangulated 3D keypoints.
`points`		Optional 3D points for the `InstanceGroup`. Delegates to `instance_3d.points` if present.
`identity`		Optional `Identity` for this group (which animal).
`category`		Optional `Category` for this group (which class). Mirrors `identity` but groups by class rather than individual.
`metadata`		Dictionary of metadata.

Methods:

Name	Description
`__init__`	Method generated by attrs for class InstanceGroup.
`__repr__`	Return a readable representation of the instance group.
`__setattr__`	Method generated by attrs for class InstanceGroup.
`get_instance`	Get `Instance` associated with `camera`.

Source code in sleap_io/model/camera.py

@define(eq=False)  # Set eq to false to make class hashable
class InstanceGroup:
    """Defines a group of instances across the same frame index.

    Attributes:
        instances_by_camera: Dictionary of `Instance` objects by `Camera`.
        instances: List of `Instance` objects in the group.
        cameras: List of `Camera` objects that have an `Instance` associated.
        score: Optional score for the `InstanceGroup`. Setting the score will also
            update the score for all `instances` already in the `InstanceGroup`. The
            score for `instances` will not be updated upon initialization.
        instance_3d: Optional `Instance3D` with triangulated 3D keypoints.
        points: Optional 3D points for the `InstanceGroup`. Delegates to
            `instance_3d.points` if present.
        identity: Optional `Identity` for this group (which animal).
        category: Optional `Category` for this group (which class). Mirrors
            `identity` but groups by class rather than individual.
        metadata: Dictionary of metadata.
    """

    _instance_by_camera: dict[Camera, Instance] = field(
        factory=dict, validator=instance_of(dict)
    )
    _score: float | None = field(
        default=None, converter=attrs.converters.optional(float)
    )
    _instance_3d: "Instance3D | None" = field(default=None)
    identity: "Identity | None" = field(default=None)
    category: "Category | None" = field(default=None)
    metadata: dict = field(factory=dict, validator=instance_of(dict))

    @property
    def instance_by_camera(self) -> dict[Camera, Instance]:
        """Get dictionary of `Instance` objects by `Camera`."""
        return self._instance_by_camera

    @property
    def instances(self) -> list[Instance]:
        """List of `Instance` objects."""
        return list(self._instance_by_camera.values())

    @property
    def cameras(self) -> "list[Camera]":
        """List of `Camera` objects."""
        return list(self._instance_by_camera.keys())

    @property
    def score(self) -> float | None:
        """Get score for `InstanceGroup`."""
        return self._score

    @property
    def instance_3d(self) -> "Instance3D | None":
        """The 3D instance for this group."""
        return self._instance_3d

    @property
    def points(self) -> np.ndarray | None:
        """3D keypoint coordinates. Delegates to instance_3d.points."""
        if self._instance_3d is not None:
            return self._instance_3d.points
        return None

    @points.setter
    def points(self, value: np.ndarray | None):
        """Set 3D points. Creates/updates Instance3D as needed."""
        if value is None:
            self._instance_3d = None
        elif self._instance_3d is not None:
            self._instance_3d.points = np.array(value, dtype="float64")
        else:
            # Need a skeleton — get from first instance if available
            skeleton = None
            for inst in self._instance_by_camera.values():
                skeleton = inst.skeleton
                break
            if skeleton is None:
                raise ValueError(
                    "Cannot set 3D points: no skeleton available from "
                    "instance_by_camera."
                )
            self._instance_3d = Instance3D(points=value, skeleton=skeleton)

    def get_instance(self, camera: Camera) -> Instance | None:
        """Get `Instance` associated with `camera`.

        Args:
            camera: `Camera` to get `Instance`.

        Returns:
            `Instance` associated with `camera` or None if not found.
        """
        return self._instance_by_camera.get(camera, None)

    def __repr__(self) -> str:
        """Return a readable representation of the instance group."""
        n_cams = len(self._instance_by_camera)
        has_3d = self._instance_3d is not None
        parts = [f"InstanceGroup(n_cameras={n_cams}, has_3d={has_3d}"]
        if self.identity is not None:
            parts.append(f', identity="{self.identity.name}"')
        if self.category is not None:
            parts.append(f', category="{self.category.name}"')
        parts.append(")")
        return "".join(parts)

`annotations = {'_instance_by_camera': 'dict[Camera, Instance]', '_score': 'float | None', '_instance_3d': "'Instance3D | None'", 'identity': "'Identity | None'", 'category': "'Category | None'", 'metadata': '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=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 = 'Defines a group of instances across the same frame index.\n\nAttributes:\n instances_by_camera: Dictionary of `Instance` objects by `Camera`.\n instances: List of `Instance` objects in the group.\n cameras: List of `Camera` objects that have an `Instance` associated.\n score: Optional score for the `InstanceGroup`. Setting the score will also\n update the score for all `instances` already in the `InstanceGroup`. The\n score for `instances` will not be updated upon initialization.\n instance_3d: Optional `Instance3D` with triangulated 3D keypoints.\n points: Optional 3D points for the `InstanceGroup`. Delegates to\n `instance_3d.points` if present.\n identity: Optional `Identity` for this group (which animal).\n category: Optional `Category` for this group (which class). Mirrors\n `identity` but groups by class rather than individual.\n metadata: Dictionary of metadata.\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 = 444` `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.

int('0b100', base=0) 4

`__match_args__ = ('_instance_by_camera', '_score', '_instance_3d', 'identity', 'category', '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.camera'` `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 = ('_instance_by_camera', '_score', '_instance_3d', 'identity', 'category', '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__ = ('_instance_3d',)` `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

`cameras` `property` ¶

List of Camera objects.

`instance_3d` `property` ¶

The 3D instance for this group.

`instance_by_camera` `property` ¶

Get dictionary of Instance objects by Camera.

`instances` `property` ¶

List of Instance objects.

`points` `property` ¶

3D keypoint coordinates. Delegates to instance_3d.points.

`score` `property` ¶

Get score for InstanceGroup.

`init(instance_by_camera=NOTHING, score=None, instance_3d=None, identity=None, category=None, metadata=NOTHING)` ¶

Method generated by attrs for class InstanceGroup.

Source code in sleap_io/model/camera.py

"""Data structure for a single camera view in a multi-camera setup."""

from __future__ import annotations

import attrs
import numpy as np
from attrs import define, field
from attrs.validators import instance_of

from sleap_io.model.category import Category
from sleap_io.model.identity import Identity
from sleap_io.model.instance import Instance, Instance3D
from sleap_io.model.labeled_frame import LabeledFrame
from sleap_io.model.video import Video


def rodrigues_transformation(input_matrix: np.ndarray) -> tuple[np.ndarray, np.ndarray]:

`repr()` ¶

Return a readable representation of the instance group.

Source code in sleap_io/model/camera.py

def __repr__(self) -> str:
    """Return a readable representation of the instance group."""
    n_cams = len(self._instance_by_camera)
    has_3d = self._instance_3d is not None
    parts = [f"InstanceGroup(n_cameras={n_cams}, has_3d={has_3d}"]
    if self.identity is not None:
        parts.append(f', identity="{self.identity.name}"')
    if self.category is not None:
        parts.append(f', category="{self.category.name}"')
    parts.append(")")
    return "".join(parts)

`setattr(name, val)` ¶

Method generated by attrs for class InstanceGroup.

`get_instance(camera)` ¶

Get Instance associated with camera.

Parameters:

Name	Type	Description	Default
`camera`	`Camera`	`Camera` to get `Instance`.	required

Returns:

Type	Description
`Instance \| None`	`Instance` associated with `camera` or None if not found.

Source code in sleap_io/model/camera.py

def get_instance(self, camera: Camera) -> Instance | None:
    """Get `Instance` associated with `camera`.

    Args:
        camera: `Camera` to get `Instance`.

    Returns:
        `Instance` associated with `camera` or None if not found.
    """
    return self._instance_by_camera.get(camera, None)

`sleap_io.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.

int('0b100', base=0) 4

`__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}")

`sleap_io.Instance3D` ¶

A 3D pose instance with keypoints in world coordinates.

Stores triangulated (or otherwise derived) 3D keypoints. Always associated with an InstanceGroup that contains the source 2D instances.

Attributes:

Name	Type	Description
`points`		3D keypoint coordinates as (N, 3) float64 array. NaN values indicate missing/unresolved keypoints.
`skeleton`		The skeleton defining keypoint semantics.
`score`		Optional instance-level confidence score.
`metadata`		Arbitrary metadata dictionary.

Methods:

Name	Description
`__init__`	Method generated by attrs for class Instance3D.
`__repr__`	Return a readable representation of the 3D instance.
`__setattr__`	Method generated by attrs for class Instance3D.
`numpy`	Return 3D points as (N, 3) float64 array.

Source code in sleap_io/model/instance.py

@attrs.define(eq=False)
class Instance3D:
    """A 3D pose instance with keypoints in world coordinates.

    Stores triangulated (or otherwise derived) 3D keypoints. Always associated
    with an InstanceGroup that contains the source 2D instances.

    Attributes:
        points: 3D keypoint coordinates as (N, 3) float64 array.
            NaN values indicate missing/unresolved keypoints.
        skeleton: The skeleton defining keypoint semantics.
        score: Optional instance-level confidence score.
        metadata: Arbitrary metadata dictionary.
    """

    points: np.ndarray = attrs.field(
        converter=lambda x: np.array(x, dtype="float64") if x is not None else None
    )
    skeleton: Skeleton = attrs.field()
    score: float | None = attrs.field(
        default=None, converter=attrs.converters.optional(float)
    )
    metadata: dict = attrs.field(
        factory=dict, validator=attrs.validators.instance_of(dict)
    )

    def __repr__(self) -> str:
        """Return a readable representation of the 3D instance."""
        n_valid = 0
        if self.points is not None:
            n_valid = int(np.sum(~np.isnan(self.points).any(axis=1)))
        n_total = len(self.skeleton.nodes)
        return f"Instance3D(n_points={n_valid}/{n_total})"

    @property
    def n_visible(self) -> int:
        """Number of non-NaN 3D keypoints."""
        if self.points is None:
            return 0
        return int(np.sum(~np.isnan(self.points).any(axis=1)))

    @property
    def is_empty(self) -> bool:
        """Whether all keypoints are NaN or points is None."""
        return self.n_visible == 0

    def numpy(self) -> np.ndarray:
        """Return 3D points as (N, 3) float64 array."""
        if self.points is None:
            return np.full((len(self.skeleton.nodes), 3), np.nan, dtype="float64")
        return self.points.copy()

`annotations = {'points': 'np.ndarray', 'skeleton': 'Skeleton', 'score': 'float | None', 'metadata': '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=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 3D pose instance with keypoints in world coordinates.\n\nStores triangulated (or otherwise derived) 3D keypoints. Always associated\nwith an InstanceGroup that contains the source 2D instances.\n\nAttributes:\n points: 3D keypoint coordinates as (N, 3) float64 array.\n NaN values indicate missing/unresolved keypoints.\n skeleton: The skeleton defining keypoint semantics.\n score: Optional instance-level confidence score.\n metadata: Arbitrary metadata dictionary.\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 = 1497` `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.

int('0b100', base=0) 4

`__match_args__ = ('points', 'skeleton', 'score', '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.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', 'score', '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

`is_empty` `property` ¶

Whether all keypoints are NaN or points is None.

`n_visible` `property` ¶

Number of non-NaN 3D keypoints.

`init(points, skeleton, score=None, metadata=NOTHING)` ¶

Method generated by attrs for class Instance3D.

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

`repr()` ¶

Return a readable representation of the 3D instance.

Source code in sleap_io/model/instance.py

def __repr__(self) -> str:
    """Return a readable representation of the 3D instance."""
    n_valid = 0
    if self.points is not None:
        n_valid = int(np.sum(~np.isnan(self.points).any(axis=1)))
    n_total = len(self.skeleton.nodes)
    return f"Instance3D(n_points={n_valid}/{n_total})"

`setattr(name, val)` ¶

Method generated by attrs for class Instance3D.

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])

`numpy()` ¶

Return 3D points as (N, 3) float64 array.

Source code in sleap_io/model/instance.py

def numpy(self) -> np.ndarray:
    """Return 3D points as (N, 3) float64 array."""
    if self.points is None:
        return np.full((len(self.skeleton.nodes), 3), np.nan, dtype="float64")
    return self.points.copy()

`sleap_io.PredictedInstance3D` ¶

Bases: sleap_io.model.instance.Instance3D

A predicted 3D pose instance with per-keypoint confidence scores.

Extends Instance3D with per-point scores from triangulation confidence or other prediction methods.

Attributes:

Name	Type	Description
`point_scores`		Per-keypoint confidence scores as (N,) float64 array. NaN values for missing keypoints.

Methods:

Name	Description
`__init__`	Method generated by attrs for class PredictedInstance3D.
`__repr__`	Return a readable representation of the predicted 3D instance.
`__setattr__`	Method generated by attrs for class PredictedInstance3D.

Source code in sleap_io/model/instance.py

@attrs.define(eq=False)
class PredictedInstance3D(Instance3D):
    """A predicted 3D pose instance with per-keypoint confidence scores.

    Extends Instance3D with per-point scores from triangulation confidence
    or other prediction methods.

    Attributes:
        point_scores: Per-keypoint confidence scores as (N,) float64 array.
            NaN values for missing keypoints.
    """

    point_scores: np.ndarray = attrs.field(
        default=None,
        converter=lambda x: np.array(x, dtype="float64") if x is not None else None,
    )

    def __repr__(self) -> str:
        """Return a readable representation of the predicted 3D instance."""
        n_valid = 0
        if self.points is not None:
            n_valid = int(np.sum(~np.isnan(self.points).any(axis=1)))
        n_total = len(self.skeleton.nodes)
        score_str = f", score={self.score:.3f}" if self.score is not None else ""
        return f"PredictedInstance3D(n_points={n_valid}/{n_total}{score_str})"

`annotations = {'point_scores': 'np.ndarray'}` `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 predicted 3D pose instance with per-keypoint confidence scores.\n\nExtends Instance3D with per-point scores from triangulation confidence\nor other prediction methods.\n\nAttributes:\n point_scores: Per-keypoint confidence scores as (N,) float64 array.\n NaN values for missing keypoints.\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 = 1550` `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.

int('0b100', base=0) 4

`__match_args__ = ('points', 'skeleton', 'score', 'metadata', 'point_scores')` `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 = ('point_scores',)` `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.

`init(points, skeleton, score=None, metadata=NOTHING, point_scores=None)` ¶

Method generated by attrs for class PredictedInstance3D.

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

`repr()` ¶

Return a readable representation of the predicted 3D instance.

Source code in sleap_io/model/instance.py

def __repr__(self) -> str:
    """Return a readable representation of the predicted 3D instance."""
    n_valid = 0
    if self.points is not None:
        n_valid = int(np.sum(~np.isnan(self.points).any(axis=1)))
    n_total = len(self.skeleton.nodes)
    score_str = f", score={self.score:.3f}" if self.score is not None else ""
    return f"PredictedInstance3D(n_points={n_valid}/{n_total}{score_str})"

`setattr(name, val)` ¶

Method generated by attrs for class PredictedInstance3D.

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])

3D¶

How the types fit together¶

Camera¶

Camera group¶

Recording session¶

Frame group¶

Instance group¶

Identity¶

Matching identities¶

Instance3D¶

Class relationships¶

API reference¶

sleap_io.Camera ¶

__annotations__ = {'matrix': 'np.ndarray', 'dist': 'np.ndarray', 'size': 'tuple[int, int]', '_rvec': 'np.ndarray', '_tvec': 'np.ndarray', 'name': 'str', '_extrinsic_matrix': 'np.ndarray', 'metadata': 'dict'} class-attribute ¶

__attrs_own_setattr__ = True class-attribute ¶

__firstlineno__ = 257 class-attribute ¶

__match_args__ = ('matrix', 'dist', 'size', '_rvec', '_tvec', 'name', 'metadata') class-attribute ¶

__module__ = 'sleap_io.model.camera' class-attribute ¶

__slots__ = ('matrix', 'dist', 'size', '_rvec', '_tvec', 'name', '_extrinsic_matrix', 'metadata', '__weakref__') class-attribute ¶

__static_attributes__ = ('_extrinsic_matrix', '_rvec', '_tvec') class-attribute ¶

__weakref__ property ¶

extrinsic_matrix property ¶

rvec property ¶

tvec property ¶

__attrs_post_init__() ¶

__init__(matrix=array([[1., 0., 0.],[0., 1., 0.],[0., 0., 1.]]), dist=array([0., 0., 0., 0., 0.]), size=None, rvec=array([0., 0., 0.]), tvec=array([0., 0., 0.]), name=None, metadata=NOTHING) ¶

__repr__() ¶

__setattr__(name, val) ¶

get_video(session) ¶

sleap_io.CameraGroup ¶

__annotations__ = {'cameras': "'list[Camera]'", 'metadata': 'dict'} class-attribute ¶

__attrs_own_setattr__ = True class-attribute ¶

__doc__ = 'A group of cameras used to record a multi-view `RecordingSession`.\n\nAttributes:\n cameras: List of `Camera` objects in the group.\n metadata: Dictionary of metadata.\n' class-attribute ¶

__firstlineno__ = 112 class-attribute ¶

__match_args__ = ('cameras', 'metadata') class-attribute ¶

__module__ = 'sleap_io.model.camera' class-attribute ¶

__slots__ = ('cameras', 'metadata', '__weakref__') class-attribute ¶

__static_attributes__ = () class-attribute ¶

__weakref__ property ¶

__eq__(other) ¶

__init__(cameras=NOTHING, metadata=NOTHING) ¶

__repr__() ¶

__setattr__(name, val) ¶

sleap_io.RecordingSession ¶

__annotations__ = {'camera_group': 'CameraGroup', '_video_by_camera': "'dict[Camera, Video]'", '_camera_by_video': "'dict[Video, Camera]'", '_frame_group_by_frame_idx': "'dict[int, FrameGroup]'", 'metadata': 'dict'} class-attribute ¶

__attrs_own_setattr__ = True class-attribute ¶

__firstlineno__ = 130 class-attribute ¶

__match_args__ = ('camera_group', '_video_by_camera', '_camera_by_video', '_frame_group_by_frame_idx', 'metadata') class-attribute ¶

__module__ = 'sleap_io.model.camera' class-attribute ¶

__slots__ = ('camera_group', '_video_by_camera', '_camera_by_video', '_frame_group_by_frame_idx', 'metadata', '__weakref__') class-attribute ¶

__static_attributes__ = () class-attribute ¶

__weakref__ property ¶

cameras property ¶

frame_groups property ¶

videos property ¶

__init__(camera_group=NOTHING, video_by_camera=NOTHING, camera_by_video=NOTHING, frame_group_by_frame_idx=NOTHING, metadata=NOTHING) ¶

__repr__() ¶

__setattr__(name, val) ¶

add_video(video, camera) ¶

get_camera(video) ¶

get_video(camera) ¶

remove_video(video) ¶

sleap_io.FrameGroup ¶

__annotations__ = {'frame_idx': 'int', '_instance_groups': 'list[InstanceGroup]', '_labeled_frame_by_camera': 'dict[Camera, LabeledFrame]', 'metadata': 'dict'} class-attribute ¶

__attrs_own_setattr__ = True class-attribute ¶

__firstlineno__ = 551 class-attribute ¶

__match_args__ = ('frame_idx', '_instance_groups', '_labeled_frame_by_camera', 'metadata') class-attribute ¶

__module__ = 'sleap_io.model.camera' class-attribute ¶

__slots__ = ('frame_idx', '_instance_groups', '_labeled_frame_by_camera', 'metadata', '__weakref__') class-attribute ¶

__static_attributes__ = () class-attribute ¶

__weakref__ property ¶

cameras property ¶

instance_groups property ¶

labeled_frames property ¶

__init__(frame_idx, instance_groups=NOTHING, labeled_frame_by_camera=NOTHING, metadata=NOTHING) ¶

__repr__() ¶

__setattr__(name, val) ¶

get_frame(camera) ¶

sleap_io.InstanceGroup ¶

__annotations__ = {'_instance_by_camera': 'dict[Camera, Instance]', '_score': 'float | None', '_instance_3d': "'Instance3D | None'", 'identity': "'Identity | None'", 'category': "'Category | None'", 'metadata': 'dict'} class-attribute ¶

`sleap_io.Camera` ¶

`annotations = {'matrix': 'np.ndarray', 'dist': 'np.ndarray', 'size': 'tuple[int, int]', '_rvec': 'np.ndarray', '_tvec': 'np.ndarray', 'name': 'str', '_extrinsic_matrix': 'np.ndarray', 'metadata': 'dict'}` `class-attribute` ¶

`__attrs_own_setattr__ = True` `class-attribute` ¶

`firstlineno = 257` `class-attribute` ¶

`__match_args__ = ('matrix', 'dist', 'size', '_rvec', '_tvec', 'name', 'metadata')` `class-attribute` ¶

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

`slots = ('matrix', 'dist', 'size', '_rvec', '_tvec', 'name', '_extrinsic_matrix', 'metadata', 'weakref')` `class-attribute` ¶

`__static_attributes__ = ('_extrinsic_matrix', '_rvec', '_tvec')` `class-attribute` ¶

`weakref` `property` ¶

`extrinsic_matrix` `property` ¶

`rvec` `property` ¶

`tvec` `property` ¶

`__attrs_post_init__()` ¶

`init(matrix=array([[1., 0., 0.],[0., 1., 0.],[0., 0., 1.]]), dist=array([0., 0., 0., 0., 0.]), size=None, rvec=array([0., 0., 0.]), tvec=array([0., 0., 0.]), name=None, metadata=NOTHING)` ¶

`repr()` ¶

`setattr(name, val)` ¶

`get_video(session)` ¶

`sleap_io.CameraGroup` ¶

`annotations = {'cameras': "'list[Camera]'", 'metadata': 'dict'}` `class-attribute` ¶

`__attrs_own_setattr__ = True` `class-attribute` ¶

doc = 'A group of cameras used to record a multi-view `RecordingSession`.\n\nAttributes:\n cameras: List of `Camera` objects in the group.\n metadata: Dictionary of metadata.\n' `class-attribute` ¶

`firstlineno = 112` `class-attribute` ¶

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

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

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

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

`weakref` `property` ¶

`eq(other)` ¶

`init(cameras=NOTHING, metadata=NOTHING)` ¶

`repr()` ¶

`setattr(name, val)` ¶

`sleap_io.RecordingSession` ¶

`annotations = {'camera_group': 'CameraGroup', '_video_by_camera': "'dict[Camera, Video]'", '_camera_by_video': "'dict[Video, Camera]'", '_frame_group_by_frame_idx': "'dict[int, FrameGroup]'", 'metadata': 'dict'}` `class-attribute` ¶

`__attrs_own_setattr__ = True` `class-attribute` ¶

`firstlineno = 130` `class-attribute` ¶

`__match_args__ = ('camera_group', '_video_by_camera', '_camera_by_video', '_frame_group_by_frame_idx', 'metadata')` `class-attribute` ¶

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

`slots = ('camera_group', '_video_by_camera', '_camera_by_video', '_frame_group_by_frame_idx', 'metadata', 'weakref')` `class-attribute` ¶

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

`weakref` `property` ¶

`cameras` `property` ¶

`frame_groups` `property` ¶

`videos` `property` ¶

`init(camera_group=NOTHING, video_by_camera=NOTHING, camera_by_video=NOTHING, frame_group_by_frame_idx=NOTHING, metadata=NOTHING)` ¶

`repr()` ¶

`setattr(name, val)` ¶

`add_video(video, camera)` ¶

`get_camera(video)` ¶

`get_video(camera)` ¶

`remove_video(video)` ¶

`sleap_io.FrameGroup` ¶

`annotations = {'frame_idx': 'int', '_instance_groups': 'list[InstanceGroup]', '_labeled_frame_by_camera': 'dict[Camera, LabeledFrame]', 'metadata': 'dict'}` `class-attribute` ¶

`__attrs_own_setattr__ = True` `class-attribute` ¶

`firstlineno = 551` `class-attribute` ¶

`__match_args__ = ('frame_idx', '_instance_groups', '_labeled_frame_by_camera', 'metadata')` `class-attribute` ¶

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

`slots = ('frame_idx', '_instance_groups', '_labeled_frame_by_camera', 'metadata', 'weakref')` `class-attribute` ¶

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

`weakref` `property` ¶

`cameras` `property` ¶

`instance_groups` `property` ¶

`labeled_frames` `property` ¶

`init(frame_idx, instance_groups=NOTHING, labeled_frame_by_camera=NOTHING, metadata=NOTHING)` ¶

`repr()` ¶

`setattr(name, val)` ¶

`get_frame(camera)` ¶

`sleap_io.InstanceGroup` ¶

`annotations = {'_instance_by_camera': 'dict[Camera, Instance]', '_score': 'float | None', '_instance_3d': "'Instance3D | None'", 'identity': "'Identity | None'", 'category': "'Category | None'", 'metadata': 'dict'}` `class-attribute` ¶

`__attrs_own_setattr__ = True` `class-attribute` ¶

`firstlineno = 444` `class-attribute` ¶

`__match_args__ = ('_instance_by_camera', '_score', '_instance_3d', 'identity', 'category', 'metadata')` `class-attribute` ¶

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

`slots = ('_instance_by_camera', '_score', '_instance_3d', 'identity', 'category', 'metadata', 'weakref')` `class-attribute` ¶

`__static_attributes__ = ('_instance_3d',)` `class-attribute` ¶

`weakref` `property` ¶

`cameras` `property` ¶

`instance_3d` `property` ¶

`instance_by_camera` `property` ¶

`instances` `property` ¶

`points` `property` ¶