TrackingMV

py3r.behaviour.tracking.tracking_mv.TrackingMV

TrackingMV(
    views: dict[str, Tracking],
    calibration: dict,
    handle: str,
)

multi-view tracking object for stereo or multi-camera setups can be used as a drop-in replacement for Tracking in TrackingCollection stores dict of view name -> Tracking, calibration, and handle

views instance-attribute

views = views

calibration instance-attribute

calibration = calibration

handle instance-attribute

handle = handle

from_views classmethod

from_views(
    filepaths: dict[str, str],
    handle: str,
    *,
    calibration: dict,
    tracking_loader,
    **loader_kwargs,
)

Loads a TrackingMV object from a dictionary of filepaths and a calibration dictionary.

Examples:

>>> import tempfile, shutil, json
>>> from pathlib import Path
>>> from py3r.behaviour.util.docdata import data_path
>>> from py3r.behaviour.tracking.tracking import Tracking
>>> with tempfile.TemporaryDirectory() as d:
...     d = Path(d)
...     # two views using the same packaged CSV for simplicity
...     with data_path('py3r.behaviour.tracking._data', 'dlc_single.csv') as p_csv:
...         left = d / 'left.csv'; right = d / 'right.csv'
...         _ = shutil.copy(p_csv, left); _ = shutil.copy(p_csv, right)
...     # load a packaged calibration json (must define 'view_order' incl. 'left','right')
...     with data_path('py3r.behaviour.tracking._data', 'calibration.json') as p_cal:
...         calib = json.loads(Path(p_cal).read_text())
...     mv = TrackingMV.from_views(
...         {'left': str(left), 'right': str(right)}, handle='rec1',
...         calibration=calib, tracking_loader=Tracking.from_dlc, fps=30)
>>> isinstance(mv, TrackingMV) and set(mv.views.keys()) == {'left','right'}
True

from_folder classmethod

from_folder(
    folder_path: str | Path,
    handle: str,
    *,
    tracking_loader,
    fps: float,
    aspectratio_correction: float = 1.0,
) -> TrackingMV

Build a TrackingMV from a folder containing view CSVs and calibration.json.

from_dlc classmethod

from_dlc(
    folder_path: str | Path,
    handle: str,
    *,
    fps: float,
    aspectratio_correction: float = 1.0,
)

Build a TrackingMV from a folder containing DLC view CSVs and calibration.json.

Examples:

>>> import tempfile, shutil, json
>>> from pathlib import Path
>>> from py3r.behaviour.util.docdata import data_path
>>> with tempfile.TemporaryDirectory() as d:
...     d = Path(d)
...     with data_path('py3r.behaviour.tracking._data', 'dlc_single.csv') as p_csv:
...         left = d / 'left.csv'; right = d / 'right.csv'
...         _ = shutil.copy(p_csv, left); _ = shutil.copy(p_csv, right)
...     calib = {
...         'view_order': ['left','right'],
...         'views': {'left': {'K': [[1,0,0],[0,1,0],[0,0,1]], 'dist': [0]*5},
...                  'right': {'K': [[1,0,0],[0,1,0],[0,0,1]], 'dist': [0]*5}},
...         'relative_pose': {'R': [[1,0,0],[0,1,0],[0,0,1]], 'T': [0.1,0,0]},
...     }
...     (d/'calibration.json').write_text(json.dumps(calib))
...     mv = TrackingMV.from_dlc(str(d), 'rec1', fps=30)
>>> isinstance(mv, TrackingMV)
True

from_dlcma classmethod

from_dlcma(
    folder_path: str | Path,
    handle: str,
    *,
    fps: float,
    aspectratio_correction: float = 1.0,
)

Build a TrackingMV from a folder containing DLC multi-animal view CSVs and calibration.json.

Examples:

>>> import tempfile, shutil, json
>>> from pathlib import Path
>>> from py3r.behaviour.util.docdata import data_path
>>> with tempfile.TemporaryDirectory() as d:
...     d = Path(d)
...     with data_path('py3r.behaviour.tracking._data', 'dlcma_multi.csv') as p_csv:
...         left = d / 'left.csv'; right = d / 'right.csv'
...         _ = shutil.copy(p_csv, left); _ = shutil.copy(p_csv, right)
...     calib = {
...         'view_order': ['left','right'],
...         'views': {'left': {'K': [[1,0,0],[0,1,0],[0,0,1]], 'dist': [0]*5},
...                  'right': {'K': [[1,0,0],[0,1,0],[0,0,1]], 'dist': [0]*5}},
...         'relative_pose': {'R': [[1,0,0],[0,1,0],[0,0,1]], 'T': [0.1,0,0]},
...     }
...     (d/'calibration.json').write_text(json.dumps(calib))
...     mv = TrackingMV.from_dlcma(str(d), 'rec1', fps=30)
>>> isinstance(mv, TrackingMV)
True

from_yolo3r classmethod

from_yolo3r(
    folder_path: str | Path,
    handle: str,
    *,
    fps: float,
    aspectratio_correction: float = 1.0,
)

Build a TrackingMV from a folder containing YOLO3R CSVs and calibration.json.

Examples:

>>> import tempfile, shutil, json
>>> from pathlib import Path
>>> from py3r.behaviour.util.docdata import data_path
>>> with tempfile.TemporaryDirectory() as d:
...     d = Path(d)
...     with data_path('py3r.behaviour.tracking._data', 'yolo3r.csv') as p_csv:
...         left = d / 'left.csv'; right = d / 'right.csv'
...         _ = shutil.copy(p_csv, left); _ = shutil.copy(p_csv, right)
...     calib = {
...         'view_order': ['left','right'],
...         'views': {'left': {'K': [[1,0,0],[0,1,0],[0,0,1]], 'dist': [0]*5},
...                  'right': {'K': [[1,0,0],[0,1,0],[0,0,1]], 'dist': [0]*5}},
...         'relative_pose': {'R': [[1,0,0],[0,1,0],[0,0,1]], 'T': [0.1,0,0]},
...     }
...     (d/'calibration.json').write_text(json.dumps(calib))
...     mv = TrackingMV.from_yolo3r(str(d), 'rec1', fps=30)
>>> isinstance(mv, TrackingMV)
True

stereo_triangulate

stereo_triangulate(invert_z: bool = True) -> Tracking

align_ids_by_keypoints

align_ids_by_keypoints(
    keypoints: list[str], views: list[str] | None = None
) -> TrackingMV

plot

plot(
    trajectories=None,
    static=None,
    lines=None,
    dims=("x", "y"),
    ax=None,
    title=None,
    show=True,
)