diff --git a/deeplabcut/gui/tabs/label_frames.py b/deeplabcut/gui/tabs/label_frames.py index 507f61a00b..4e9e71066b 100644 --- a/deeplabcut/gui/tabs/label_frames.py +++ b/deeplabcut/gui/tabs/label_frames.py @@ -8,16 +8,92 @@ # # Licensed under GNU Lesser General Public License v3.0 # +from __future__ import annotations + import os +from pathlib import Path + from PySide6 import QtWidgets from PySide6.QtCore import Qt + from deeplabcut.generate_training_dataset import check_labels from deeplabcut.gui.components import DefaultTab from deeplabcut.gui.widgets import launch_napari -def label_frames(config_path): - _ = launch_napari(config_path) +def label_frames( + config_path: str | Path | None = None, + image_folder: str | None = None +): + """Launches the napari-deeplabcut labelling GUI. + + For more information on labelling data with napari-deeplabcut, see our docs: + https://github.com/DeepLabCut/napari-deeplabcut?tab=readme-ov-file#usage + + If no parameters are given, the napari-deeplabcut labelling GUI is simply open, + and the folder containing the images to label can be dropped into the GUI. + + If the `config_path` and the `image_folder` are given as arguments, the given + `image_folder` for the project is opened in the napari-deeplabcut GUI to be labeled. + If only the `config_path` is given, the first image folder is opened. + + Parameters + ---------- + config_path: str, Path, None + Full path of the project config.yaml file. + + image_folder: str, None + Name of the image folder to open for labelling. + + Examples + -------- + Opening the napari-deeplabcut annotation GUI without opening a specific folder of + images to label. You then need to drag-and-drop your image folder into the GUI. + See the napari-deeplabcut docs linked above for more infomation about labelling in + napari-deeplabcut. + >>> import deeplabcut + >>> deeplabcut.label_frames() + + Opening the images extracted from the "2025-01-01-experiment7" video in + napari-deeplabcut on Windows. The project's folder structure should look as follows: + reaching-task/ # project root directory + ├── config.yaml # project configuration file + └── labeled-data/ # folder containing all extracted image folders + ├── ... + ├── 2025-01-01-experiment7 # folder containing the images to label + └── ... + >>> deeplabcut.label_frames( + >>> "C:\\myproject\\reaching-task\\config.yaml", + >>> "2025-01-01-experiment7", + >>> ) + + Opening the images extracted from the first video listed in the project + configuration in napari-deeplabcut on a Unix system. + >>> deeplabcut.label_frames("/users/john/project/config.yaml") + """ + files = None + if config_path is None: + if image_folder is not None: + raise ValueError( + f"If the ``config_path`` is None, the ``image_folder`` must be None " + f"too. Found {image_folder}. To label the images in {image_folder}, " + f"give the project configuration file as `config_path`." + ) + else: + data_dir = Path(config_path).parent / "labeled-data" + if image_folder is None: + image_dirs = [path for path in data_dir.iterdir() if path.is_dir()] + if len(image_dirs) == 0: + raise ValueError( + f"Could not find any image folders in {data_dir}. Please check " + f"the config path given to `deeplabcut.label_frames(...)`" + ) + image_dir = list(sorted(image_dirs))[0] + else: + image_dir = data_dir / image_folder + + files = [str(image_dir), str(config_path)] + _ = launch_napari(files=files) refine_labels = label_frames