Metadata-Version: 2.5
Name: trial-dlc
Version: 0.1.0
Summary: Totally Reliable & Inevitable Animal Labeler -- a GUI for reviewing and correcting DeepLabCut keypoints
Project-URL: Homepage, https://github.com/knowblesse/TRIAL
Project-URL: Repository, https://github.com/knowblesse/TRIAL
Project-URL: Issues, https://github.com/knowblesse/TRIAL/issues
Author-email: Ji Hoon Jeong <knowblesse@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: annotation,behavior,deeplabcut,dlc,neuroscience,pose-estimation,video
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: X11 Applications :: Qt
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Multimedia :: Video
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Requires-Python: >=3.9
Requires-Dist: av>=15.0
Requires-Dist: numpy>=1.24
Requires-Dist: opencv-python>=4.8
Requires-Dist: pandas>=2.0
Requires-Dist: pyside6>=6.9
Requires-Dist: ruamel-yaml>=0.18
Requires-Dist: tables>=3.8
Description-Content-Type: text/markdown

# TRIAL
Totally Reliable & Inevitable Animal Labeler

## Install

```
pip install trial-dlc
```

The MATLAB version of TRIAL lives in `bin/` in this repo and is not part of
the Python package.

## Running it

```
trial-dlc path/to/catalog.yaml
```

`python -m trial` does the same thing. The distribution is named `trial-dlc`,
but the import package it installs is plain `trial`.

With no argument it looks for `relabel_videos.yaml` in the current folder, and
falls back to an Open Video dialog. See `relabel_videos.example.yaml` for the
catalog format.

## Cropping — read this if you cropped in DLC

If DLC was told to crop before tracking, every coordinate in its csv is
measured from the crop rectangle's origin, while the video itself is
full-size. The tool has to add that offset back to draw points, and subtract
it again to save a correction. **If it doesn't know about the crop, a
correction you make is written in full-frame coordinates into a csv whose
other rows are crop-relative** — two coordinate systems in one file, with
nothing to warn you.

So the crop is never guessed. For each video it is resolved in this order:

1. That video's own `crop:` in the catalog — `[x1, x2, y1, y2]` (DLC's
   ordering), or `null` meaning this one is not cropped.
2. The catalog's top-level `crop:`, applying to every video that doesn't
   override it. `null` there means the whole list is uncropped, and no
   meta.pickle is read at all.
3. DLC's `meta.pickle` for that video, located by the scorer name recorded
   inside the csv, so the right analysis run is used even when several exist.
   What it says is written back into the catalog.
4. Nothing found — an error. **If you cropped, you must provide either the
   meta.pickle or a `crop:` entry.**

Opening a lone video through the file dialog skips steps 1–2, since there's
no catalog to declare anything in: it needs a meta.pickle next to the video
or its csv. Use a catalog otherwise.

The catalog is rewritten only when a crop is learned, and comments,
indentation, and blank lines are preserved. Quote any path containing `: `
or ` #`.

# Patch Note
## v1.0
- Initial Release

## v1.1
- Interpolation method changed. Patching method to whole data interpolation.

## v1.2
- Cross head size changed
- Progress bar added
- Message notification after successful save operation

## v1.3
- Progress bar error fixed.
