From ac89a16b1ebb4984ea7f2f4f0071a4a56c5822aa Mon Sep 17 00:00:00 2001 From: Cyril Achard Date: Wed, 15 Apr 2026 15:41:25 +0200 Subject: [PATCH 01/53] Add docs and notebooks audit export tool Add tools/docs_and_notebooks_audit.py: a CLI tool that scans Markdown and Jupyter notebooks for a deeplabcut metadata namespace, validates selected fields (visibility, status, recommendation, last_verified) against enums via pydantic, and exports a CSV audit register. Features include YAML frontmatter and notebook metadata parsing, alias support for recommendation, preservation of human-authored CSV columns across re-runs, configurable include/exclude scan patterns, target filtering (files, dirs, globs), and basic reporting of parse/validation issues. --- tools/docs_and_notebooks_audit.py | 547 ++++++++++++++++++++++++++++++ 1 file changed, 547 insertions(+) create mode 100644 tools/docs_and_notebooks_audit.py diff --git a/tools/docs_and_notebooks_audit.py b/tools/docs_and_notebooks_audit.py new file mode 100644 index 0000000000..52ee600772 --- /dev/null +++ b/tools/docs_and_notebooks_audit.py @@ -0,0 +1,547 @@ +#!/usr/bin/env python3 +""" +DeepLabCut docs audit export tool (validated / extensible). + +Purpose +------- +Read audit metadata from the `deeplabcut` namespace in Markdown frontmatter and +notebook-level metadata, validate selected fields against enums/schema, and +export a CSV register that humans can annotate with notes. + +Design goals +------------ +- read-only and safe in CI +- lightweight, but with strong validation for key lifecycle fields +- preserve human-authored CSV columns across re-runs +- generic/extensible field extraction (add a field spec once; reuse everywhere) +- minimal duplication between Markdown and notebook handling + +Supported metadata fields +------------------------- +From `deeplabcut:` this tool currently validates and exports: +- visibility +- status +- recommendation (with fallback alias: review_decision) +- last_verified (pass-through) + +Example metadata +---------------- +Markdown frontmatter: + +--- +deeplabcut: + visibility: online + status: viable + recommendation: keep + last_verified: 2026-04-15 +--- + +Notebook metadata: +{ + "metadata": { + "deeplabcut": { + "visibility": "online", + "status": "viable", + "recommendation": "keep", + "last_verified": "2026-04-15" + } + } +} + +Usage +----- +python tools/docs_audit_export.py \ + --config tools/docs_and_notebooks_report_config.yml \ + --out docs/_meta/docs_audit_register.csv + +python tools/docs_audit_export.py \ + --targets docs/gui/ docs/recipes/*.md examples/COLAB/*.ipynb +""" + +from __future__ import annotations + +import argparse +import csv +import fnmatch +import os +import re +import subprocess +from collections.abc import Callable, Iterable, Sequence +from enum import Enum +from pathlib import Path +from typing import Any, Literal, TypedDict + +import nbformat +import yaml +from pydantic import BaseModel, ConfigDict, ValidationError + +# ----------------------------------------------------------------------------- +# Constants / defaults +# ----------------------------------------------------------------------------- +DLC_NAMESPACE = "deeplabcut" +DEFAULT_CONFIG = Path("tools/docs_and_notebooks_report_config.yml") +DEFAULT_OUTPUT = Path("docs/_meta/docs_audit_register.csv") +GLOB_CHARS = set("*?[") +FRONTMATTER_RE = re.compile(r"^---\s*$") + +# Generated columns owned by this tool. Any additional columns present in an +# existing CSV are preserved as human columns. +GENERATED_COLUMNS = [ + "path", + "kind", + "metadata_present", + "visibility", + "status", + "recommendation", + "last_verified", + "parse_error", + "validation_error", + "notes", +] + +DEFAULT_INCLUDE = [ + "docs/**/*.md", + "docs/**/*.markdown", + "docs/**/*.ipynb", + "examples/**/*.ipynb", + "README.md", + "CONTRIBUTING.md", +] +DEFAULT_EXCLUDE = [ + ".git/**", + ".github/**", + "**/.ipynb_checkpoints/**", + "**/node_modules/**", + "**/.venv/**", +] + +FileKind = Literal["md", "ipynb", "other"] +TargetKind = Literal["invalid", "file", "dir", "glob"] + + +# ----------------------------------------------------------------------------- +# Enums / schema +# ----------------------------------------------------------------------------- +class Visibility(str, Enum): + """How discoverable the page is in the documentation surface.""" + + ONLINE = "online" # current docs surface / discoverable + UNLISTED = "unlisted" # intentionally available but not surfaced in nav + ARCHIVED = "archived" # only discoverable via archive/historical area + ORPHANED = "orphaned" # not listed and no supported inbound links + + +class Status(str, Enum): + """Current health / lifecycle state of the page.""" + + VIABLE = "viable" # current and acceptable + REVIEW_NEEDED = "review_needed" # needs human review before decision + OUTDATED = "outdated" # content exists but is stale / drifted + DEPRECATED = "deprecated" # not preferred; replacement exists/coming + ARCHIVED = "archived" # kept for historical or niche reference + REMOVED = "removed" # removed from active docs surface + + +class Recommendation(str, Enum): + """Recommended next action for the page.""" + + KEEP = "keep" + VERIFY = "verify" + UPDATE = "update" + MERGE = "merge" + ARCHIVE = "archive" + REMOVE = "remove" + + +class AuditMetadata(BaseModel): + """ + Strictly validate only the fields this exporter owns. + + Keep extra metadata allowed so the deeplabcut namespace can still contain + other fields used by the main checks tool or future workflows. + """ + + model_config = ConfigDict(extra="allow") + + visibility: Visibility | None = None + status: Status | None = None + recommendation: Recommendation | None = None + last_verified: str | None = None + + +class TargetSpec(TypedDict): + raw: str + normalized: str + kind: TargetKind + + +class FieldSpec(BaseModel): + """Describes how a CSV column maps from deeplabcut metadata.""" + + model_config = ConfigDict(arbitrary_types_allowed=True) + + column: str + source_keys: list[str] + extractor: Callable[[AuditMetadata, dict[str, Any]], str] | None = None + + +FIELD_SPECS: list[FieldSpec] = [ + FieldSpec(column="visibility", source_keys=["visibility"]), + FieldSpec(column="status", source_keys=["status"]), + # Support both recommendation and the older/alternate review_decision name. + FieldSpec(column="recommendation", source_keys=["recommendation", "review_decision"]), + FieldSpec(column="last_verified", source_keys=["last_verified"]), +] + + +# ----------------------------------------------------------------------------- +# Path / target helpers +# ----------------------------------------------------------------------------- +def normalize_target_spec(spec: str, repo_root: Path) -> str: + s = spec.strip() + if not s: + return s + s = s.replace("\\", "/") + while s.startswith("./"): + s = s[2:] + p = Path(s) + if p.is_absolute(): + try: + s = str(p.resolve().relative_to(repo_root)).replace(os.sep, "/") + except ValueError: + s = str(p).replace(os.sep, "/") + s = re.sub(r"/+", "/", s) + if len(s) > 1: + s = s.rstrip("/") + return s + + +def compile_target_specs(targets: list[str] | None, repo_root: Path) -> list[TargetSpec] | None: + if not targets: + return None + specs: list[TargetSpec] = [] + for raw in targets: + normalized = normalize_target_spec(raw, repo_root) + if not normalized: + specs.append({"raw": raw, "normalized": "", "kind": "invalid"}) + continue + if any(ch in normalized for ch in GLOB_CHARS): + specs.append({"raw": raw, "normalized": normalized, "kind": "glob"}) + continue + if raw.endswith(("/", "\\")): + specs.append({"raw": raw, "normalized": normalized, "kind": "dir"}) + continue + candidate = repo_root / normalized + specs.append( + { + "raw": raw, + "normalized": normalized, + "kind": "dir" if candidate.exists() and candidate.is_dir() else "file", + } + ) + return specs + + +def target_spec_matches_path(rel_path: str, spec: TargetSpec) -> bool: + rel_path = rel_path.replace("\\", "/") + kind = spec["kind"] + normalized = spec["normalized"] + if kind == "invalid": + return False + if kind == "file": + return rel_path == normalized + if kind == "dir": + return rel_path == normalized or rel_path.startswith(normalized + "/") + if kind == "glob": + return fnmatch.fnmatchcase(rel_path, normalized) + return False + + +def target_matches(rel_path: str, specs: list[TargetSpec] | None) -> bool: + return True if specs is None else any(target_spec_matches_path(rel_path, spec) for spec in specs) + + +def find_repo_root(start: Path) -> Path: + cur = start.resolve() + for _ in range(50): + if (cur / ".git").exists(): + return cur + if cur.parent == cur: + break + cur = cur.parent + proc = subprocess.run(["git", "rev-parse", "--show-toplevel"], cwd=str(start), capture_output=True, text=True) + if proc.returncode == 0 and proc.stdout.strip(): + return Path(proc.stdout.strip()).resolve() + raise RuntimeError("Could not locate repository root") + + +def file_kind(path: Path) -> FileKind: + suffix = path.suffix.lower() + if suffix in {".md", ".markdown"}: + return "md" + if suffix == ".ipynb": + return "ipynb" + return "other" + + +# ----------------------------------------------------------------------------- +# Config / discovery +# ----------------------------------------------------------------------------- +def load_scan_patterns(config_path: Path | None) -> tuple[list[str], list[str]]: + if not config_path or not config_path.exists(): + return DEFAULT_INCLUDE, DEFAULT_EXCLUDE + + raw = yaml.safe_load(config_path.read_text(encoding="utf-8")) or {} + scan = raw.get("scan") or {} + include = scan.get("include") or DEFAULT_INCLUDE + exclude = scan.get("exclude") or DEFAULT_EXCLUDE + return include, exclude + + +def is_excluded(rel_path: str, exclude_patterns: list[str]) -> bool: + return any(fnmatch.fnmatch(rel_path, pat) for pat in exclude_patterns) + + +def iter_candidate_paths( + repo_root: Path, + include_patterns: list[str], + exclude_patterns: list[str], + targets: list[str] | None = None, +) -> list[Path]: + specs = compile_target_specs(targets, repo_root) + matches: dict[str, Path] = {} + for pattern in include_patterns: + for path in repo_root.glob(pattern): + if not path.is_file(): + continue + rel = str(path.resolve().relative_to(repo_root)).replace(os.sep, "/") + if is_excluded(rel, exclude_patterns): + continue + if not target_matches(rel, specs): + continue + matches[rel] = path.resolve() + return [matches[k] for k in sorted(matches)] + + +# ----------------------------------------------------------------------------- +# Metadata readers (minimal duplication via namespace dispatch) +# ----------------------------------------------------------------------------- +def read_md_frontmatter(text: str) -> tuple[dict | None, str | None]: + lines = text.splitlines(keepends=True) + if not lines or not FRONTMATTER_RE.match(lines[0]): + return None, None + + end_idx = None + for i in range(1, min(len(lines), 5000)): + if FRONTMATTER_RE.match(lines[i]): + end_idx = i + break + if end_idx is None: + return None, "unterminated_markdown_frontmatter" + + fm_text = "".join(lines[1:end_idx]) + try: + fm = yaml.safe_load(fm_text) if fm_text.strip() else {} + except Exception as exc: + return None, f"markdown_frontmatter_yaml_error: {exc}" + if not isinstance(fm, dict): + return None, "markdown_frontmatter_not_mapping" + return fm, None + + +def read_container(path: Path) -> tuple[dict | None, str | None]: + """ + Return the top-level metadata container for a file. + - Markdown: YAML frontmatter mapping + - Notebook: notebook.metadata mapping + """ + kind = file_kind(path) + + if kind == "md": + try: + text = path.read_text(encoding="utf-8") + except Exception as exc: + return None, f"read_failed: {exc}" + return read_md_frontmatter(text) + + if kind == "ipynb": + try: + nb = nbformat.read(str(path), as_version=4) + meta = getattr(nb, "metadata", {}) or {} + except Exception as exc: + return None, f"notebook_read_failed: {exc}" + if not isinstance(meta, dict): + return None, "notebook_metadata_not_mapping" + return meta, None + + return None, None + + +def read_dlc_namespace(path: Path) -> tuple[dict | None, str | None]: + container, error = read_container(path) + if error: + return None, error + if container is None: + return None, None + raw = container.get(DLC_NAMESPACE) + if raw is None: + return None, None + if not isinstance(raw, dict): + return None, "deeplabcut_namespace_not_mapping" + return raw, None + + +# ----------------------------------------------------------------------------- +# Validation / normalization +# ----------------------------------------------------------------------------- +def build_validation_input(raw_meta: dict[str, Any]) -> dict[str, Any]: + """ + Map raw deeplabcut metadata into the schema-owned keys. + This is where aliases are resolved to canonical names. + """ + payload: dict[str, Any] = {} + for spec in FIELD_SPECS: + for key in spec.source_keys: + if key in raw_meta and raw_meta.get(key) not in {None, ""}: + payload[spec.column] = raw_meta.get(key) + break + return payload + + +def validate_metadata(raw_meta: dict[str, Any] | None) -> tuple[AuditMetadata | None, str | None]: + if raw_meta is None: + return None, None + try: + validated = AuditMetadata.model_validate(build_validation_input(raw_meta)) + return validated, None + except ValidationError as exc: + messages = [] + for err in exc.errors(): + loc = ".".join(str(x) for x in err.get("loc", [])) + msg = err.get("msg", "invalid value") + messages.append(f"{loc}: {msg}" if loc else msg) + return None, "; ".join(messages) + + +def extract_field_value(spec: FieldSpec, validated: AuditMetadata | None, raw_meta: dict[str, Any]) -> str: + if spec.extractor is not None: + return spec.extractor(validated, raw_meta) + if validated is not None: + value = getattr(validated, spec.column, None) + if isinstance(value, Enum): + return value.value + return "" if value is None else str(value) + # If validation failed, still emit raw/aliased value when present for easier triage. + for key in spec.source_keys: + if key in raw_meta and raw_meta.get(key) is not None: + return str(raw_meta.get(key)) + return "" + + +# ----------------------------------------------------------------------------- +# CSV merge / preserve human annotations +# ----------------------------------------------------------------------------- +def load_existing_rows(csv_path: Path) -> tuple[dict[str, dict[str, str]], list[str]]: + if not csv_path.exists(): + return {}, [] + with csv_path.open("r", newline="", encoding="utf-8") as fh: + reader = csv.DictReader(fh) + rows = {row.get("path", ""): row for row in reader if row.get("path")} + existing_columns = reader.fieldnames or [] + extra_columns = [c for c in existing_columns if c not in GENERATED_COLUMNS] + return rows, extra_columns + + +def merged_row(base: dict[str, Any], previous: dict[str, str] | None, extra_columns: Iterable[str]) -> dict[str, Any]: + row = dict(base) + if previous and previous.get("notes") is not None: + row["notes"] = previous.get("notes", "") + for col in extra_columns: + row[col] = previous.get(col, "") if previous else "" + return row + + +# ----------------------------------------------------------------------------- +# Row building / export +# ----------------------------------------------------------------------------- +def build_row(repo_root: Path, path: Path) -> dict[str, Any]: + rel = str(path.resolve().relative_to(repo_root)).replace(os.sep, "/") + kind = file_kind(path) + raw_meta, parse_error = read_dlc_namespace(path) + raw_meta = raw_meta or {} + metadata_present = bool(raw_meta) + validated, validation_error = validate_metadata(raw_meta if metadata_present else None) + + row: dict[str, Any] = { + "path": rel, + "kind": kind, + "metadata_present": "true" if metadata_present else "false", + "parse_error": parse_error or "", + "validation_error": validation_error or "", + "notes": "", + } + + for spec in FIELD_SPECS: + row[spec.column] = extract_field_value(spec, validated, raw_meta) + return row + + +def export_csv( + repo_root: Path, include: list[str], exclude: list[str], out_path: Path, targets: list[str] | None +) -> int: + candidates = iter_candidate_paths(repo_root, include, exclude, targets=targets) + existing_rows, extra_columns = load_existing_rows(out_path) + + rows = [] + for path in candidates: + base = build_row(repo_root, path) + previous = existing_rows.get(base["path"]) + rows.append(merged_row(base, previous, extra_columns)) + + fieldnames = list(GENERATED_COLUMNS) + [c for c in extra_columns if c not in GENERATED_COLUMNS] + + out_path.parent.mkdir(parents=True, exist_ok=True) + with out_path.open("w", newline="", encoding="utf-8") as fh: + writer = csv.DictWriter(fh, fieldnames=fieldnames) + writer.writeheader() + for row in rows: + writer.writerow(row) + + print(f"Wrote {len(rows)} records to {out_path}") + invalid = sum(1 for row in rows if row.get("validation_error")) + parse_fail = sum(1 for row in rows if row.get("parse_error")) + if invalid or parse_fail: + print(f"Validation issues: {invalid}; parse issues: {parse_fail}") + return 0 + + +# ----------------------------------------------------------------------------- +# CLI +# ----------------------------------------------------------------------------- +def main(argv: Sequence[str] | None = None) -> int: + parser = argparse.ArgumentParser(description="Export DeepLabCut audit metadata to CSV") + parser.add_argument("--config", default=str(DEFAULT_CONFIG), help="Optional path to scan config YAML") + parser.add_argument("--root", default=".", help="Repository root or path inside the repository") + parser.add_argument("--out", default=str(DEFAULT_OUTPUT), help="CSV output path") + parser.add_argument( + "--targets", + nargs="*", + help=( + "Optional repo-relative targets to limit the export. Supports exact files, " + "directories, and glob patterns (e.g. docs/page.md, docs/gui/, 'docs/**/*.md')." + ), + ) + args = parser.parse_args(list(argv) if argv is not None else None) + + repo_root = find_repo_root(Path(args.root)) + config_path = Path(args.config) + include, exclude = load_scan_patterns(config_path) + out_path = Path(args.out) + if not out_path.is_absolute(): + out_path = repo_root / out_path + + return export_csv(repo_root, include, exclude, out_path, targets=args.targets) + + +if __name__ == "__main__": + raise SystemExit(main()) From e192c9db5afefa066e95f02fdb7c6fa5f98d9155 Mon Sep 17 00:00:00 2001 From: Cyril Achard Date: Wed, 15 Apr 2026 16:21:07 +0200 Subject: [PATCH 02/53] Ignore tools/docs_audits in docs scan Add tools/docs_audits/** to the scan exclude list in tools/docs_and_notebooks_report_config.yml so the docs & notebooks report skips files in that directory (e.g., generated audit artifacts or temporary outputs). --- tools/docs_and_notebooks_report_config.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/tools/docs_and_notebooks_report_config.yml b/tools/docs_and_notebooks_report_config.yml index 60dfcb21f8..f630800088 100644 --- a/tools/docs_and_notebooks_report_config.yml +++ b/tools/docs_and_notebooks_report_config.yml @@ -10,6 +10,7 @@ scan: - "**/.ipynb_checkpoints/**" - "**/_build/**" - "**/build/**" + - "tools/docs_audits/**" policy: warn_if_content_older_than_days: 365 From 09ec1e8e720d10e5623780b70eea9db5f902e108 Mon Sep 17 00:00:00 2001 From: Cyril Achard Date: Wed, 15 Apr 2026 16:28:40 +0200 Subject: [PATCH 03/53] Ignore docs_audits; include tools MD files Add an exclude pattern (^tools/docs_audits/) to the docs/notebooks pre-commit hook so files under tools/docs_audits/ are skipped. Also add tools/**/*.md to the scan list in tools/docs_and_notebooks_report_config.yml so Markdown files in the tools directory are included in the docs/notebooks report. --- .pre-commit-config.yaml | 1 + tools/docs_and_notebooks_report_config.yml | 1 + 2 files changed, 2 insertions(+) diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 315fabee9f..dadf4fbccc 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -91,6 +91,7 @@ repos: language: python pass_filenames: true files: ^(docs/|examples/(JUPYTER|COLAB)/|tools/).*(\.md|\.ipynb)$ + exclude: ^tools/docs_audits/ args: - --config - tools/docs_and_notebooks_report_config.yml diff --git a/tools/docs_and_notebooks_report_config.yml b/tools/docs_and_notebooks_report_config.yml index f630800088..ee7995b742 100644 --- a/tools/docs_and_notebooks_report_config.yml +++ b/tools/docs_and_notebooks_report_config.yml @@ -6,6 +6,7 @@ scan: - "examples/JUPYTER/**/*.ipynb" - "docs/**/*.md" - "docs/**/*.ipynb" # if notebooks get added to docs (Jupyter Book supports this) + - "tools/**/*.md" exclude: - "**/.ipynb_checkpoints/**" - "**/_build/**" From 57369acdcbe3d16c7f51bd9b8cdcb233e978c68b Mon Sep 17 00:00:00 2001 From: Cyril Achard Date: Tue, 21 Apr 2026 13:53:23 +0200 Subject: [PATCH 04/53] Introduce markdown-myst pre-commit hook ## Summary Adds `mdformat` v1.0 as a pre commit hook with the myst plugin. This helps automate formatting of documentation and catch any mistakes in structure or syntax, making docs maintenance easier. ## Scope As a hook with write permissions, it is meant to run locally, not in CI. --- .pre-commit-config.yaml | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index dadf4fbccc..771192d27e 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -82,6 +82,15 @@ repos: args: [--check, --diff] stages: [manual] + - repo: https://github.com/hukkin/mdformat + rev: 1.0.0 + hooks: + - id: mdformat + additional_dependencies: + - mdformat-myst + files: ^docs/.*\.md$ + stages: [pre-commit] + # check only, no modifications - repo: local hooks: From 759956e11f64185ac0d1a1e69b38a218d017c180 Mon Sep 17 00:00:00 2001 From: Cyril Achard Date: Mon, 27 Apr 2026 15:49:51 +0200 Subject: [PATCH 05/53] Add notes field and 'move' recommendation Add support for human-editable notes and a new Recommendation.MOVE enum. AuditMetadata now includes a notes field and FIELD_SPECS registers notes so notes are read from CSV. merged_row now preserves existing human notes, warns on conflicts between scanned and previous notes, and prefers previous notes when present. build_row no longer unconditionally writes an empty notes value (to avoid clobbering preserved notes). Also removed the file shebang line. --- tools/docs_and_notebooks_audit.py | 22 +++++++++++++++++----- 1 file changed, 17 insertions(+), 5 deletions(-) diff --git a/tools/docs_and_notebooks_audit.py b/tools/docs_and_notebooks_audit.py index 52ee600772..76c7359e47 100644 --- a/tools/docs_and_notebooks_audit.py +++ b/tools/docs_and_notebooks_audit.py @@ -1,4 +1,3 @@ -#!/usr/bin/env python3 """ DeepLabCut docs audit export tool (validated / extensible). @@ -148,6 +147,7 @@ class Recommendation(str, Enum): KEEP = "keep" VERIFY = "verify" UPDATE = "update" + MOVE = "move" MERGE = "merge" ARCHIVE = "archive" REMOVE = "remove" @@ -167,6 +167,7 @@ class AuditMetadata(BaseModel): status: Status | None = None recommendation: Recommendation | None = None last_verified: str | None = None + notes: str | None = None class TargetSpec(TypedDict): @@ -188,9 +189,9 @@ class FieldSpec(BaseModel): FIELD_SPECS: list[FieldSpec] = [ FieldSpec(column="visibility", source_keys=["visibility"]), FieldSpec(column="status", source_keys=["status"]), - # Support both recommendation and the older/alternate review_decision name. FieldSpec(column="recommendation", source_keys=["recommendation", "review_decision"]), FieldSpec(column="last_verified", source_keys=["last_verified"]), + FieldSpec(column="notes", source_keys=["notes"]), ] @@ -454,10 +455,21 @@ def load_existing_rows(csv_path: Path) -> tuple[dict[str, dict[str, str]], list[ def merged_row(base: dict[str, Any], previous: dict[str, str] | None, extra_columns: Iterable[str]) -> dict[str, Any]: row = dict(base) - if previous and previous.get("notes") is not None: - row["notes"] = previous.get("notes", "") + + if previous: + prev_notes = (previous.get("notes") or "").strip() + scanned_notes = (row.get("notes") or "").strip() + if prev_notes and scanned_notes and prev_notes != scanned_notes: + print(f"WARNING: Notes conflict for {row['path']}:") + print(f"- Previous: {prev_notes}") + print(f"- Scanned: {scanned_notes}") + print("Preserving previous notes and ignoring scanned notes.") + # Preserve human notes if present, otherwise keep scanned notes + row["notes"] = prev_notes if prev_notes else scanned_notes + for col in extra_columns: row[col] = previous.get(col, "") if previous else "" + return row @@ -478,7 +490,7 @@ def build_row(repo_root: Path, path: Path) -> dict[str, Any]: "metadata_present": "true" if metadata_present else "false", "parse_error": parse_error or "", "validation_error": validation_error or "", - "notes": "", + # "notes": "", } for spec in FIELD_SPECS: From ced7cc6dfbf2fd30523f1ddb80ffda5f7c273831 Mon Sep 17 00:00:00 2001 From: Cyril Achard Date: Tue, 28 Apr 2026 09:38:54 +0200 Subject: [PATCH 06/53] Document Recommendation enum values Add brief inline comments to each member of the Recommendation enum in tools/docs_and_notebooks_audit.py to clarify what each action means for auditors (keep, verify, update, move, merge, archive, remove). This is a documentation-only change and does not alter runtime behavior. --- tools/docs_and_notebooks_audit.py | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/tools/docs_and_notebooks_audit.py b/tools/docs_and_notebooks_audit.py index 76c7359e47..59f4411c9d 100644 --- a/tools/docs_and_notebooks_audit.py +++ b/tools/docs_and_notebooks_audit.py @@ -144,13 +144,13 @@ class Status(str, Enum): class Recommendation(str, Enum): """Recommended next action for the page.""" - KEEP = "keep" - VERIFY = "verify" - UPDATE = "update" - MOVE = "move" - MERGE = "merge" - ARCHIVE = "archive" - REMOVE = "remove" + KEEP = "keep" # content is fine as-is; no action needed + VERIFY = "verify" # content and/or formatting could use verification + UPDATE = "update" # requires content update to be considered viable + MOVE = "move" # move to a more appropriate location + MERGE = "merge" # merge into another page + ARCHIVE = "archive" # if deprecated, archive before removal + REMOVE = "remove" # remove from repository (can be resurrected from git history if needed) class AuditMetadata(BaseModel): From d8b3a15f1d4dce0e8de1a079667e1a43749c3986 Mon Sep 17 00:00:00 2001 From: Cyril Achard Date: Tue, 21 Apr 2026 13:40:23 +0200 Subject: [PATCH 07/53] chore(metadata): update docs/notebooks metadata Installation page --- docs/installation.md | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/docs/installation.md b/docs/installation.md index 333a1e72bc..dd9d0e743c 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -1,10 +1,16 @@ --- deeplabcut: last_content_updated: '2026-02-23' - last_metadata_updated: '2026-03-06' + last_metadata_updated: '2026-04-21' ignore: false + visibility: online + status: outdated + recommendation: update + notes: Could be moved to a core/installation folder for clarity. + last_verified: '2026-04-21' + verified_for: 3.0.0rc14 --- -(how-to-install)= +(file:how-to-install)= # How To Install DeepLabCut - **DeepLabCut can be run on Windows, Linux, or MacOS as long as you have Python 3.10 installed** From fbc7bad22f370f85d9ac255f2b25a30f9ebf4cb8 Mon Sep 17 00:00:00 2001 From: Cyril Achard Date: Tue, 21 Apr 2026 14:03:54 +0200 Subject: [PATCH 08/53] chore(metadata): update docs/notebooks metadata --- docs/course.md | 3 +++ .../publishing_notebooks_into_the_DLC_main_cookbook.md | 4 ++++ 2 files changed, 7 insertions(+) diff --git a/docs/course.md b/docs/course.md index 58c9d153c0..a47610c787 100644 --- a/docs/course.md +++ b/docs/course.md @@ -3,6 +3,9 @@ deeplabcut: last_content_updated: '2025-06-30' last_metadata_updated: '2026-03-06' ignore: false + visibility: online + status: outdated + recommendation: archive --- # DeepLabCut Self-paced Course diff --git a/docs/recipes/publishing_notebooks_into_the_DLC_main_cookbook.md b/docs/recipes/publishing_notebooks_into_the_DLC_main_cookbook.md index 99d754c731..2efd55b858 100644 --- a/docs/recipes/publishing_notebooks_into_the_DLC_main_cookbook.md +++ b/docs/recipes/publishing_notebooks_into_the_DLC_main_cookbook.md @@ -3,6 +3,10 @@ deeplabcut: last_content_updated: '2025-06-30' last_metadata_updated: '2026-03-06' ignore: false + visibility: online + status: review_needed + recommendation: verify + notes: Sligthly redundant with CONTRIBUTING.md, style may need adjusted based on the rest of the repo. --- # Publishing Notebooks into the Main DLC Cookbook ### Your Recipe Guide to Contributing to the DLC Cookbook From 7c9b3fd1cea4ae542dcc29bee30196513b814d88 Mon Sep 17 00:00:00 2001 From: Cyril Achard Date: Mon, 27 Apr 2026 15:39:37 +0200 Subject: [PATCH 09/53] chore(metadata): update docs/notebooks metadata --- docs/recipes/installTips.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/docs/recipes/installTips.md b/docs/recipes/installTips.md index 1ddefa0ca7..ebadbbb7ae 100644 --- a/docs/recipes/installTips.md +++ b/docs/recipes/installTips.md @@ -1,8 +1,13 @@ --- deeplabcut: last_content_updated: '2025-02-28' - last_metadata_updated: '2026-03-06' + last_metadata_updated: '2026-04-27' ignore: false + visibility: online + status: outdated + recommendation: archive + last_verified: '2026-04-27' + verified_for: 3.0.0rc14 --- (installation-tips)= # Installation Tips From fb18c009b6889e1073ebdf23dde06e60a701dca2 Mon Sep 17 00:00:00 2001 From: Cyril Achard Date: Tue, 28 Apr 2026 09:41:02 +0200 Subject: [PATCH 10/53] chore(metadata): update docs/notebooks metadata --- docs/HelperFunctions.md | 4 ++++ docs/Overviewof3D.md | 4 ++++ docs/docker.md | 3 +++ docs/gui/PROJECT_GUI.md | 4 ++++ docs/gui/napari_GUI.md | 4 ++++ docs/maDLC_UserGuide.md | 4 ++++ docs/standardDeepLabCut_UserGuide.md | 4 ++++ 7 files changed, 27 insertions(+) diff --git a/docs/HelperFunctions.md b/docs/HelperFunctions.md index aa90f91975..e651f45b02 100644 --- a/docs/HelperFunctions.md +++ b/docs/HelperFunctions.md @@ -3,6 +3,10 @@ deeplabcut: last_content_updated: '2025-06-30' last_metadata_updated: '2026-03-06' ignore: false + visibility: online + status: outdated + recommendation: archive + notes: I would suggest using API docs over pages like this to avoid drift. The advice below promises updates that are not being made, and the content is already quite outdated. Automating API docs generation and putting usage info for obtaining commands info in ipython in a basic 'evergreen' page would be more sustainable than trying to maintain this page. --- (helper-functions)= # Helper & Advanced Optional Function Documentation diff --git a/docs/Overviewof3D.md b/docs/Overviewof3D.md index 07c9384a90..afb844db38 100644 --- a/docs/Overviewof3D.md +++ b/docs/Overviewof3D.md @@ -3,6 +3,10 @@ deeplabcut: last_content_updated: '2025-10-14' last_metadata_updated: '2026-03-06' ignore: false + visibility: online + status: review_needed + recommendation: update + notes: Contents seem up-to-date as the codebase has not evolved drastically for 3D, but formatting and organization could be improved. Separate basic/advanced sections could help, as well as more admonitions/dropdowns to streamline. --- (3D-overview)= # 3D DeepLabCut diff --git a/docs/docker.md b/docs/docker.md index dbca607353..7e4e440937 100644 --- a/docs/docker.md +++ b/docs/docker.md @@ -3,6 +3,9 @@ deeplabcut: last_content_updated: '2025-04-15' last_metadata_updated: '2026-03-06' ignore: false + visibility: online + status: review_needed + recommendation: verify --- (docker-containers)= # DeepLabCut Docker containers diff --git a/docs/gui/PROJECT_GUI.md b/docs/gui/PROJECT_GUI.md index 362479a4b9..8e0bffee7b 100644 --- a/docs/gui/PROJECT_GUI.md +++ b/docs/gui/PROJECT_GUI.md @@ -3,6 +3,10 @@ deeplabcut: last_content_updated: '2025-02-28' last_metadata_updated: '2026-03-06' ignore: false + visibility: online + status: review_needed + recommendation: update + notes: While the content is generally accurate, repeating installation instructions is not ideal. I would suggest linking to the installation guide instead. Also, the GUI is likely sed by the majority of users, so I would even consider making this a full section in the TOC, and maybe even having one file per GUI tab, which would make tracking code/docs sync easier. --- (project-manager-gui)= # Interactive Project Manager GUI diff --git a/docs/gui/napari_GUI.md b/docs/gui/napari_GUI.md index 9acc9ddaea..3c97d1f419 100644 --- a/docs/gui/napari_GUI.md +++ b/docs/gui/napari_GUI.md @@ -3,6 +3,10 @@ deeplabcut: last_content_updated: '2026-02-10' last_metadata_updated: '2026-03-06' ignore: false + visibility: online + status: outdated + recommendation: archive + notes: Being updated in a separate PR (#3280) --- (napari-gui)= # napari labeling GUI diff --git a/docs/maDLC_UserGuide.md b/docs/maDLC_UserGuide.md index d4ec6d215c..a5e873cdf2 100644 --- a/docs/maDLC_UserGuide.md +++ b/docs/maDLC_UserGuide.md @@ -3,6 +3,10 @@ deeplabcut: last_content_updated: '2026-02-10' last_metadata_updated: '2026-03-06' ignore: false + visibility: online + status: review_needed + recommendation: verify + notes: Could use a small formatting pass. Contents are 4-5y old in some places, recommend to review for accuracy. --- (multi-animal-userguide)= # DeepLabCut for Multi-Animal Projects diff --git a/docs/standardDeepLabCut_UserGuide.md b/docs/standardDeepLabCut_UserGuide.md index 5100d3d867..a29130de36 100644 --- a/docs/standardDeepLabCut_UserGuide.md +++ b/docs/standardDeepLabCut_UserGuide.md @@ -3,6 +3,10 @@ deeplabcut: last_content_updated: '2025-06-30' last_metadata_updated: '2026-03-06' ignore: false + visibility: online + status: review_needed + recommendation: update + notes: This is a crucial piece of the doc, but it is rather long and verbose. Recommend breaking it up into smaller sections, and adding more visuals (e.g. screenshots of the GUI, etc.) to make it more engaging and easier to read. Also, consider adding a table of contents at the beginning for easier navigation. --- (single-animal-userguide)= # DeepLabCut User Guide (for single animal projects) From 619bddaa1891d54dd4828c2b5728a42bb410b19b Mon Sep 17 00:00:00 2001 From: Cyril Achard Date: Tue, 28 Apr 2026 10:30:01 +0200 Subject: [PATCH 11/53] chore(metadata): update docs/notebooks metadata --- docs/beginner-guides/Training-Evaluation.md | 4 ++++ docs/beginner-guides/beginners-guide.md | 4 ++++ docs/beginner-guides/labeling.md | 4 ++++ docs/beginner-guides/manage-project.md | 4 ++++ docs/beginner-guides/video-analysis.md | 4 ++++ docs/gui/PROJECT_GUI.md | 2 +- docs/pytorch/Benchmarking_shuffle_guide.md | 4 ++++ docs/pytorch/architectures.md | 3 +++ docs/pytorch/pytorch_config.md | 4 ++++ docs/pytorch_dlc.md | 4 ++++ docs/quick-start/single_animal_quick_guide.md | 4 ++++ docs/quick-start/tutorial_maDLC.md | 3 +++ docs/recipes/installTips.md | 3 +-- 13 files changed, 44 insertions(+), 3 deletions(-) diff --git a/docs/beginner-guides/Training-Evaluation.md b/docs/beginner-guides/Training-Evaluation.md index 802a22aec5..ae22ab403c 100644 --- a/docs/beginner-guides/Training-Evaluation.md +++ b/docs/beginner-guides/Training-Evaluation.md @@ -3,6 +3,10 @@ deeplabcut: last_content_updated: '2025-02-28' last_metadata_updated: '2026-03-06' ignore: false + visibility: online + status: viable + recommendation: move + notes: "As mentioned on oher beginner-guides/ docs, this should be part of the GUI section." --- # Neural Network training and evaluation in the GUI DLC LIVE! diff --git a/docs/beginner-guides/beginners-guide.md b/docs/beginner-guides/beginners-guide.md index 784e522c65..a4df28db50 100644 --- a/docs/beginner-guides/beginners-guide.md +++ b/docs/beginner-guides/beginners-guide.md @@ -3,6 +3,10 @@ deeplabcut: last_content_updated: '2026-03-03' last_metadata_updated: '2026-03-06' ignore: false + visibility: online + status: outdated + recommendation: update + notes: "While it could seem like a useful page for beginners, duplicating installation instructions is not ideal for maintenance. This is also mixing installation/setup with a GUI guide, which should be in its own section/page. This puts into question the reason of existence of this page, as it would end up being two links to different sections. I would rather have well-made, accurate installation and GUI guides, and if there are beginner-relevant information that really cannot fit into those, then we can have a 'beginner's guide' that links to those and has the extra info. I would suggest reviewing whether this style of docs should remain at all, but if we want to keep them revising the approach may be needed." --- (beginners-guide)= # Using DeepLabCut diff --git a/docs/beginner-guides/labeling.md b/docs/beginner-guides/labeling.md index f3c6d5aa8e..592845edc1 100644 --- a/docs/beginner-guides/labeling.md +++ b/docs/beginner-guides/labeling.md @@ -3,6 +3,10 @@ deeplabcut: last_content_updated: '2025-06-30' last_metadata_updated: '2026-03-06' ignore: false + visibility: online + status: viable + recommendation: update + notes: "Useful content, a note is that this should be better integrated with the napari plugin docs, making the workflow transition from DLC GUI -> napari viewer -> back to DLC GUI more seamless so as to confuse users less. This will need a bit of restructuring, as napari-DLC docs are also standalone from the main GUI. Finding a good linking strategy would help. Perhaps breaking napari-DLC docs into install/setup, basic usage, *labeling workflow* (new) and advanced usage would allow to do this cleanly, as it would separate the standalone plugin operation from the DLC-GUI integrated workflow, yet retaining a single source for napari-DLC labeling workflow." --- (labeling)= # Labeling GUI diff --git a/docs/beginner-guides/manage-project.md b/docs/beginner-guides/manage-project.md index ee0e0f339e..4159ba99b9 100644 --- a/docs/beginner-guides/manage-project.md +++ b/docs/beginner-guides/manage-project.md @@ -3,6 +3,10 @@ deeplabcut: last_content_updated: '2025-06-30' last_metadata_updated: '2026-03-06' ignore: false + visibility: online + status: viable + recommendation: move + notes: "It seems the beginner guide section is more of a GUI step-by-step. As such, it should be moved to the GUI section, and merged/integrated with the contents there. The content is useful, but making it clear that this is for the GUI would reduce the confusion of a beginner guide being in fact rather central GUI use instructions." --- # Setting up what keypoints to track DLC LIVE! diff --git a/docs/beginner-guides/video-analysis.md b/docs/beginner-guides/video-analysis.md index 8c48d3209c..5ed5892530 100644 --- a/docs/beginner-guides/video-analysis.md +++ b/docs/beginner-guides/video-analysis.md @@ -3,6 +3,10 @@ deeplabcut: last_content_updated: '2025-06-30' last_metadata_updated: '2026-03-06' ignore: false + visibility: online + status: viable + recommendation: move + notes: "As mentioned on oher beginner-guides/ docs, this should be part of the GUI section." --- # Video Analysis with DeepLabCut DLC LIVE! diff --git a/docs/gui/PROJECT_GUI.md b/docs/gui/PROJECT_GUI.md index 8e0bffee7b..139d200e08 100644 --- a/docs/gui/PROJECT_GUI.md +++ b/docs/gui/PROJECT_GUI.md @@ -6,7 +6,7 @@ deeplabcut: visibility: online status: review_needed recommendation: update - notes: While the content is generally accurate, repeating installation instructions is not ideal. I would suggest linking to the installation guide instead. Also, the GUI is likely sed by the majority of users, so I would even consider making this a full section in the TOC, and maybe even having one file per GUI tab, which would make tracking code/docs sync easier. + notes: "While the content is generally accurate, repeating installation instructions is not ideal. I would suggest linking to the installation guide instead of re-suggesting commmands but then still saying to read the install page... Also, the GUI is likely used by the majority of users, so I would even consider making this a full section in the TOC, and maybe even having one file per GUI tab, which would make tracking code/docs sync easier. Addendum: it seems the beginner guide section is more of a GUI step-by-step, as mentioned earlier in this comment. I would suggest merging/moving and adding links in the present doc, which would make it less of a video list and more of a proper GUI guide." --- (project-manager-gui)= # Interactive Project Manager GUI diff --git a/docs/pytorch/Benchmarking_shuffle_guide.md b/docs/pytorch/Benchmarking_shuffle_guide.md index ba54ceca9f..81802cf164 100644 --- a/docs/pytorch/Benchmarking_shuffle_guide.md +++ b/docs/pytorch/Benchmarking_shuffle_guide.md @@ -3,6 +3,10 @@ deeplabcut: last_content_updated: '2025-06-30' last_metadata_updated: '2026-03-06' ignore: false + visibility: online + status: viable + recommendation: move + notes: "Useful and well-written, but it could be better groped with other tutorials/guides rather than being a PyTorch docs only page, as its contents are somewhat inbetween the two backends." --- # DeepLabCut Benchmarking - User Guide diff --git a/docs/pytorch/architectures.md b/docs/pytorch/architectures.md index 755a967a77..a6cefbe586 100644 --- a/docs/pytorch/architectures.md +++ b/docs/pytorch/architectures.md @@ -3,6 +3,9 @@ deeplabcut: last_content_updated: '2025-06-30' last_metadata_updated: '2026-03-06' ignore: false + visibility: online + status: viable + recommendation: keep --- (dlc3-architectures)= # DeepLabCut 3.0 - PyTorch Model Architectures diff --git a/docs/pytorch/pytorch_config.md b/docs/pytorch/pytorch_config.md index cbd435c46a..0019433993 100644 --- a/docs/pytorch/pytorch_config.md +++ b/docs/pytorch/pytorch_config.md @@ -3,6 +3,10 @@ deeplabcut: last_content_updated: '2025-10-02' last_metadata_updated: '2026-03-06' ignore: false + visibility: online + status: review_needed + recommendation: verify + notes: "Check for accuracy and completeness of content, and update as needed. Formatting is fairly consistent and does not need an urgent update." --- (dlc3-pytorch-config)= # The PyTorch Configuration file diff --git a/docs/pytorch_dlc.md b/docs/pytorch_dlc.md index 6d2ddca45b..50890c3440 100644 --- a/docs/pytorch_dlc.md +++ b/docs/pytorch_dlc.md @@ -3,6 +3,10 @@ deeplabcut: last_content_updated: '2024-01-17' last_metadata_updated: '2026-03-06' ignore: false + visibility: orphaned + status: viable + recommendation: move + notes: "Unclear why this is unlisted in TOC; recommend updating and moving to PyTorch section." --- # DeepLabCut: PyTorch API diff --git a/docs/quick-start/single_animal_quick_guide.md b/docs/quick-start/single_animal_quick_guide.md index 99362ea9d0..5f88c9b126 100644 --- a/docs/quick-start/single_animal_quick_guide.md +++ b/docs/quick-start/single_animal_quick_guide.md @@ -3,6 +3,10 @@ deeplabcut: last_content_updated: '2025-06-30' last_metadata_updated: '2026-03-06' ignore: false + visibility: online + status: viable + recommendation: archive + notes: "This is a bit stuck between minimal guide and quick start, as the lack of explanations makes it more into a catalogue of commands (which is an API docs responsibility), and a proper quick start guide that gives users a proper sense of the workflow. This should either be expanded greatly or simply archived. For simplicity, I recommend archiving." --- # QUICK GUIDE to single Animal Training: **The main steps to take you from project creation to analyzed videos:** diff --git a/docs/quick-start/tutorial_maDLC.md b/docs/quick-start/tutorial_maDLC.md index 111ed996f5..adf8dda979 100644 --- a/docs/quick-start/tutorial_maDLC.md +++ b/docs/quick-start/tutorial_maDLC.md @@ -3,6 +3,9 @@ deeplabcut: last_content_updated: '2025-02-28' last_metadata_updated: '2026-03-06' ignore: false + visibility: online + status: viable + recommendation: keep --- # Multi-animal pose estimation with DeepLabCut: A 5-minute tutorial diff --git a/docs/recipes/installTips.md b/docs/recipes/installTips.md index ebadbbb7ae..a76b7ace45 100644 --- a/docs/recipes/installTips.md +++ b/docs/recipes/installTips.md @@ -6,8 +6,7 @@ deeplabcut: visibility: online status: outdated recommendation: archive - last_verified: '2026-04-27' - verified_for: 3.0.0rc14 + notes: "Should be removed in favor of the main installation guide." --- (installation-tips)= # Installation Tips From 1bd19dee298158f1bc3f158d798f9aa002e04045 Mon Sep 17 00:00:00 2001 From: Cyril Achard Date: Tue, 28 Apr 2026 10:37:32 +0200 Subject: [PATCH 12/53] Update audit files --- .../docs_audits/april-2026/audit_metadata.csv | 78 +++++++++++++++++++ 1 file changed, 78 insertions(+) create mode 100644 tools/docs_audits/april-2026/audit_metadata.csv diff --git a/tools/docs_audits/april-2026/audit_metadata.csv b/tools/docs_audits/april-2026/audit_metadata.csv new file mode 100644 index 0000000000..2a89a1285a --- /dev/null +++ b/tools/docs_audits/april-2026/audit_metadata.csv @@ -0,0 +1,78 @@ +path,kind,metadata_present,visibility,status,recommendation,last_verified,parse_error,validation_error,notes,review_decision,review_priority +docs/Governance.md,md,true,,,,,,,,, +docs/HelperFunctions.md,md,true,online,outdated,archive,,,,"I would suggest using API docs over pages like this to avoid drift. The advice below promises updates that are not being made, and the content is already quite outdated. Automating API docs generation and putting usage info for obtaining commands info in ipython in a basic 'evergreen' page would be more sustainable than trying to maintain this page.",, +docs/MISSION_AND_VALUES.md,md,true,,,,,,,,, +docs/ModelZoo.md,md,true,,,,,,,,, +docs/Overviewof3D.md,md,true,online,review_needed,update,,,,"Contents seem up-to-date as the codebase has not evolved drastically for 3D, but formatting and organization could be improved. Separate basic/advanced sections could help, as well as more admonitions/dropdowns to streamline.",, +docs/README.md,md,true,,,,,,,,, +docs/UseOverviewGuide.md,md,true,online,viable,keep,2026-04-27,,,,, +docs/beginner-guides/Training-Evaluation.md,md,true,online,viable,move,,,,"As mentioned on oher beginner-guides/ docs, this should be part of the GUI section.",, +docs/beginner-guides/beginners-guide.md,md,true,online,outdated,update,,,,"While it could seem like a useful page for beginners, duplicating installation instructions is not ideal for maintenance. This is also mixing installation/setup with a GUI guide, which should be in its own section/page. This puts into question the reason of existence of this page, as it would end up being two links to different sections. I would rather have well-made, accurate installation and GUI guides, and if there are beginner-relevant information that really cannot fit into those, then we can have a 'beginner's guide' that links to those and has the extra info. I would suggest reviewing whether this style of docs should remain at all, but if we want to keep them revising the approach may be needed.",, +docs/beginner-guides/labeling.md,md,true,online,viable,update,,,,"Useful content, a note is that this should be better integrated with the napari plugin docs, making the workflow transition from DLC GUI -> napari viewer -> back to DLC GUI more seamless so as to confuse users less. This will need a bit of restructuring, as napari-DLC docs are also standalone from the main GUI. Finding a good linking strategy would help. Perhaps breaking napari-DLC docs into install/setup, basic usage, *labeling workflow* (new) and advanced usage would allow to do this cleanly, as it would separate the standalone plugin operation from the DLC-GUI integrated workflow, yet retaining a single source for napari-DLC labeling workflow.",, +docs/beginner-guides/manage-project.md,md,true,online,viable,move,,,,"It seems the beginner guide section is more of a GUI step-by-step. As such, it should be moved to the GUI section, and merged/integrated with the contents there. The content is useful, but making it clear that this is for the GUI would reduce the confusion of a beginner guide being in fact rather central GUI use instructions.",, +docs/beginner-guides/video-analysis.md,md,true,online,viable,move,,,,"As mentioned on oher beginner-guides/ docs, this should be part of the GUI section.",, +docs/benchmark.md,md,true,,,,,,,,, +docs/citation.md,md,true,,,,,,,,, +docs/convert_maDLC.md,md,true,,,,,,,,, +docs/course.md,md,true,online,outdated,archive,,,,,, +docs/dlc-live/deeplabcutlive.md,md,true,,,,,,,,, +docs/dlc-live/dlc-live-gui/index.md,md,true,,,,,,,,, +docs/dlc-live/dlc-live-gui/quickstart/install.md,md,true,,,,,,,,, +docs/dlc-live/dlc-live-gui/user_guide/cameras_backends/aravis_backend.md,md,true,,,,,,,,, +docs/dlc-live/dlc-live-gui/user_guide/cameras_backends/basler_backend.md,md,true,,,,,,,,, +docs/dlc-live/dlc-live-gui/user_guide/cameras_backends/camera_support.md,md,true,,,,,,,,, +docs/dlc-live/dlc-live-gui/user_guide/cameras_backends/gentl_backend.md,md,true,,,,,,,,, +docs/dlc-live/dlc-live-gui/user_guide/cameras_backends/opencv_backend.md,md,true,,,,,,,,, +docs/dlc-live/dlc-live-gui/user_guide/misc/misc_landing.md,md,true,,,,,,,,, +docs/dlc-live/dlc-live-gui/user_guide/misc/modelzoo_downloads.md,md,true,,,,,,,,, +docs/dlc-live/dlc-live-gui/user_guide/misc/timestamp_format.md,md,true,,,,,,,,, +docs/dlc-live/dlc-live-gui/user_guide/overview.md,md,true,,,,,,,,, +docs/docker.md,md,true,online,review_needed,verify,,,,,, +docs/gui/PROJECT_GUI.md,md,true,online,review_needed,update,,,,"While the content is generally accurate, repeating installation instructions is not ideal. I would suggest linking to the installation guide instead of re-suggesting commmands but then still saying to read the install page... Also, the GUI is likely used by the majority of users, so I would even consider making this a full section in the TOC, and maybe even having one file per GUI tab, which would make tracking code/docs sync easier. Addendum: it seems the beginner guide section is more of a GUI step-by-step, as mentioned earlier in this comment. I would suggest merging/moving and adding links in the present doc, which would make it less of a video list and more of a proper GUI guide.",, +docs/gui/napari_GUI.md,md,true,online,outdated,archive,,,,Being updated in a separate PR (#3280),, +docs/installation.md,md,true,online,outdated,update,2026-04-21,,,Could be moved to a core/installation folder for clarity.,, +docs/intro.md,md,true,,,,,,,,, +docs/maDLC_UserGuide.md,md,true,online,review_needed,verify,,,,"Could use a small formatting pass. Contents are 4-5y old in some places, recommend to review for accuracy.",, +docs/pytorch/Benchmarking_shuffle_guide.md,md,true,online,viable,move,,,,"Useful and well-written, but it could be better groped with other tutorials/guides rather than being a PyTorch docs only page, as its contents are somewhat inbetween the two backends.",, +docs/pytorch/architectures.md,md,true,online,viable,keep,,,,,, +docs/pytorch/pytorch_config.md,md,true,online,review_needed,verify,,,,"Check for accuracy and completeness of content, and update as needed. Formatting is fairly consistent and does not need an urgent update.",, +docs/pytorch/user_guide.md,md,true,,,,,,,,, +docs/pytorch_dlc.md,md,true,orphaned,viable,move,,,,Unclear why this is unlisted in TOC; recommend updating and moving to PyTorch section.,, +docs/quick-start/single_animal_quick_guide.md,md,true,online,viable,archive,,,,"This is a bit stuck between minimal guide and quick start, as the lack of explanations makes it more into a catalogue of commands (which is an API docs responsibility), and a proper quick start guide that gives users a proper sense of the workflow. This should either be expanded greatly or simply archived. For simplicity, I recommend archiving.",, +docs/quick-start/tutorial_maDLC.md,md,true,online,viable,keep,,,,,, +docs/recipes/BatchProcessing.md,md,true,,,,,,,,, +docs/recipes/ClusteringNapari.md,md,true,,,,,,,,, +docs/recipes/DLCMethods.md,md,true,,,,,,,,, +docs/recipes/MegaDetectorDLCLive.md,md,true,orphaned,outdated,archive,,,,,, +docs/recipes/OpenVINO.md,md,true,,,,,,,,, +docs/recipes/OtherData.md,md,true,,,,,,,,, +docs/recipes/TechHardware.md,md,true,,,,,,,,, +docs/recipes/UsingModelZooPupil.md,md,true,,,,,,,,, +docs/recipes/flip_and_rotate.ipynb,ipynb,true,,,,,,,,, +docs/recipes/installTips.md,md,true,online,outdated,archive,,,,Should be removed in favor of the main installation guide.,, +docs/recipes/io.md,md,true,,,,,,,,, +docs/recipes/nn.md,md,true,,,,,,,,, +docs/recipes/pose_cfg_file_breakdown.md,md,true,,,,,,,,, +docs/recipes/post.md,md,true,,,,,,,,, +docs/recipes/publishing_notebooks_into_the_DLC_main_cookbook.md,md,true,online,review_needed,verify,,,,"Sligthly redundant with CONTRIBUTING.md, style may need adjusted based on the rest of the repo.",, +docs/roadmap.md,md,true,,,,,,,,, +docs/standardDeepLabCut_UserGuide.md,md,true,online,review_needed,update,,,,"This is a crucial piece of the doc, but it is rather long and verbose. Recommend breaking it up into smaller sections, and adding more visuals (e.g. screenshots of the GUI, etc.) to make it more engaging and easier to read. Also, consider adding a table of contents at the beginning for easier navigation.",, +examples/COLAB/COLAB_3miceDemo.ipynb,ipynb,true,,,,,,,,, +examples/COLAB/COLAB_BUCTD_and_CTD_tracking.ipynb,ipynb,true,,,,,,,,, +examples/COLAB/COLAB_DEMO_SuperAnimal.ipynb,ipynb,true,,,,,,,,, +examples/COLAB/COLAB_DEMO_mouse_openfield.ipynb,ipynb,true,,,,,,,,, +examples/COLAB/COLAB_DLC_ModelZoo.ipynb,ipynb,true,,,,,,,,, +examples/COLAB/COLAB_HumanPose_with_RTMPose.ipynb,ipynb,false,,,,,,,,, +examples/COLAB/COLAB_YOURDATA_SuperAnimal.ipynb,ipynb,true,,,,,,,,, +examples/COLAB/COLAB_YOURDATA_TrainNetwork_VideoAnalysis.ipynb,ipynb,true,,,,,,,,, +examples/COLAB/COLAB_YOURDATA_maDLC_TrainNetwork_VideoAnalysis.ipynb,ipynb,true,,,,,,,,, +examples/COLAB/COLAB_transformer_reID.ipynb,ipynb,false,,,,,,,,, +examples/JUPYTER/Demo_3D_DeepLabCut.ipynb,ipynb,true,,,,,,,,, +examples/JUPYTER/Demo_labeledexample_MouseReaching.ipynb,ipynb,true,,,,,,,,, +examples/JUPYTER/Demo_labeledexample_Openfield.ipynb,ipynb,true,,,,,,,,, +examples/JUPYTER/Demo_napari.ipynb,ipynb,true,,,,,,,,, +examples/JUPYTER/Demo_yourowndata.ipynb,ipynb,true,,,,,,,,, +examples/JUPYTER/Docker_TrainNetwork_VideoAnalysis.ipynb,ipynb,true,,,,,,,,, +tools/README.md,md,false,,,,,,,,, +tools/docs_and_notebooks_tool_README.md,md,false,,,,,,,,, +tools/ruff_cleanup_helpers.md,md,false,,,,,,,,, From c9bd740b9df8e59cb852e971bd62470c2d6d0337 Mon Sep 17 00:00:00 2001 From: Cyril Achard Date: Tue, 28 Apr 2026 10:49:46 +0200 Subject: [PATCH 13/53] chore(metadata): update docs/notebooks metadata --- docs/recipes/MegaDetectorDLCLive.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/recipes/MegaDetectorDLCLive.md b/docs/recipes/MegaDetectorDLCLive.md index 416a23125c..3f216e5ba3 100644 --- a/docs/recipes/MegaDetectorDLCLive.md +++ b/docs/recipes/MegaDetectorDLCLive.md @@ -3,6 +3,9 @@ deeplabcut: last_content_updated: '2026-02-10' last_metadata_updated: '2026-03-06' ignore: false + visibility: orphaned + status: outdated + recommendation: archive --- # 💚 MegaDetector+DeepLabCut 💜 From 0f48d90a30b2f98f96b3e740e55daedfdda93c80 Mon Sep 17 00:00:00 2001 From: Cyril Achard Date: Tue, 21 Apr 2026 13:37:56 +0200 Subject: [PATCH 14/53] Polish README content and docs metadata Clean up and reorganize README.md: adjust headings and phrasing, remove extraneous blank lines, clarify installation and TensorFlow deprecation wording, add/rename sections (Pretrained Models, Development and Applications, Ecosystem, Code contributors, Funding), comment out outdated course/residency/roadmap links, update community badges and links, and improve news/release notes. Also add brief HTML comments to docs/README.md indicating the root README is used for main documentation and noting frontmatter metadata behavior. --- README.md | 96 +++++++++++++++++++++++++++++--------------------- docs/README.md | 2 ++ 2 files changed, 58 insertions(+), 40 deletions(-) diff --git a/README.md b/README.md index 5c177728ad..d761906c58 100644 --- a/README.md +++ b/README.md @@ -16,12 +16,6 @@ - - - - - - [📚Documentation](https://deeplabcut.github.io/DeepLabCut/README.html) | [🛠️ Installation](https://deeplabcut.github.io/DeepLabCut/docs/installation.html) | [🌎 Home Page](https://www.deeplabcut.org) | @@ -57,7 +51,7 @@ **DeepLabCut™️** is a toolbox for state-of-the-art markerless pose estimation of animals performing various behaviors. As long as you can see (label) what you want to track, you can use this toolbox, as it is animal and object agnostic. [Read a short development and application summary below](https://github.com/DeepLabCut/DeepLabCut#why-use-deeplabcut). -# [Installation: how to install DeepLabCut](https://deeplabcut.github.io/DeepLabCut/docs/installation.html) +# [Installation](https://deeplabcut.github.io/DeepLabCut/docs/installation.html) Please click the link above for all the information you need to get started! Please note that currently we support only Python 3.10+ (see conda files for guidance). @@ -83,34 +77,44 @@ version with PyTorch)! To use the TensorFlow (TF) engine (requires Python 3.10; TF up to v2.10 supported on Windows, up to v2.12 on other platforms): you'll need to run `pip install "deeplabcut[gui,tf]"` (which includes all functions plus GUIs) or `pip install "deeplabcut[tf]"` (headless -version with PyTorch and TensorFlow). We aim to depreciate the TF part in 2027. +version with PyTorch and TensorFlow). +We aim to deprecate the TF part in 2027. We recommend using our conda file, see [here](https://github.com/DeepLabCut/DeepLabCut/blob/main/conda-environments/README.md) or the [`deeplabcut-docker` package](https://github.com/DeepLabCut/DeepLabCut/tree/main/docker). -# [Documentation: The DeepLabCut Process](https://deeplabcut.github.io/DeepLabCut/README.html) + +# Documentation: The DeepLabCut Process Our docs walk you through using DeepLabCut, and key API points. For an overview of the toolbox and workflow for project management, see our step-by-step at [Nature Protocols paper](https://doi.org/10.1038/s41596-019-0176-0). -For a deeper understanding and more resources for you to get started with Python and DeepLabCut, please check out our free online course! https://deeplabcut.github.io/DeepLabCut/docs/course.html + +

-# [DEMO the code](examples/README.md) +# [Code demo](examples/README.md) -🐭 pose tracking of single animals demo [![Open in Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/DeepLabCut/DeepLabCut/blob/master/examples/COLAB/COLAB_DEMO_mouse_openfield.ipynb) +🐭 Pose tracking of single animals demo [![Open in Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/DeepLabCut/DeepLabCut/blob/master/examples/COLAB/COLAB_DEMO_mouse_openfield.ipynb) -See [more demos here](https://github.com/DeepLabCut/DeepLabCut/blob/main/examples/README.md). We provide data and several Jupyter Notebooks: one that walks you through a demo dataset to test your installation, and another Notebook to run DeepLabCut from the beginning on your own data. We also show you how to use the code in Docker, and on Google Colab. +See [more demos here](https://github.com/DeepLabCut/DeepLabCut/blob/main/examples/README.md). +We provide data and several Jupyter Notebooks, walking you through a demo dataset to test your installation, and another to run DeepLabCut from the start on your own data. +We also show how to use the code in Docker, and on Google Colab. # Why use DeepLabCut? -DeepLabCut continues to be actively maintained and we strive to provide a user-friendly `GUI` and `API` for computer vision researchers and life scientists alike. This means we integrate state-of-the-art models and frameworks, while providing our "best-guess" defaults for life scientists. We highly encourage you to read our papers to get a better understanding of what to use and how to modify the models for your setting. +DeepLabCut continues to be actively maintained and we strive to provide a user-friendly `GUI` and `API` for computer vision researchers and life scientists alike. This means we integrate state-of-the-art models and frameworks, while providing our "best-guess" defaults for life scientists. +We highly encourage you to read our papers to get a better understanding of what to use and how to modify the models for your setting. ## Performance 🔥 In general, we provide all the tooling for you to train and use custom models with various high-performance backbones. -We also provide two foundation pretrained animal models: `SuperAnimal-Quadruped`, `SuperAnimal-TopViewMouse`. To gauge their *out-of-distribution* performance, we provide the following tables. + +## Pretrained Models + +We also provide two foundation pretrained animal models: `SuperAnimal-Quadruped` & `SuperAnimal-TopViewMouse`. +To gauge their *out-of-distribution* performance, we provide the following tables. These models are trained on the [SuperAnimal-Quadruped with AP-10K held out for out-of-domain testing]([https://cocodataset.org/](https://www.nature.com/articles/s41467-024-48792-2)) and the [SuperAnimal-TopViewMouse with DLC-openfield held out for out-of-distribution testing](https://www.nature.com/articles/s41467-024-48792-2). We provide models that include AP-10K in the API (and GUI). Note, there are many different models to select from in DeepLabCut 3.0. We strongly recommend you check [this Guide](https://deeplabcut.github.io/DeepLabCut/docs/pytorch/architectures.html) for more details. @@ -132,8 +136,13 @@ This [link provides the model weights](https://huggingface.co/mwmathis/DeepLabCu ## The History -In 2018, we demonstrated the capabilities for [trail tracking](https://vnmurthylab.org/), [reaching in mice](http://www.mousemotorlab.org/) and various Drosophila behaviors during egg-laying (see [Mathis et al.](https://www.nature.com/articles/s41593-018-0209-y) for details). There is, however, nothing specific that makes the toolbox only applicable to these tasks and/or species. The toolbox has already been successfully applied (by us and others) to [rats](http://www.mousemotorlab.org/deeplabcut), humans, various fish species, bacteria, leeches, various robots, cheetahs, [mouse whiskers](http://www.mousemotorlab.org/deeplabcut) and [race horses](http://www.mousemotorlab.org/deeplabcut). DeepLabCut utilized the feature detectors (ResNets + readout layers) of one of the state-of-the-art algorithms for human pose estimation by Insafutdinov et al., called DeeperCut, which inspired the name for our toolbox (see references below). Since this time, the package has changed substantially. The code has been re-tooled and re-factored since 2.1+: We have added faster and higher performance variants with MobileNetV2s, EfficientNets, and our own DLCRNet backbones (see [Pretraining boosts out-of-domain robustness for pose estimation](https://arxiv.org/abs/1909.11229) and [Lauer et al 2022](https://www.nature.com/articles/s41592-022-01443-0)). Additionally, we have improved the inference speed and provided both additional and novel augmentation methods, added real-time, and multi-animal support. -In v3.0+ we have changed the backend to support PyTorch. This brings not only an easier installation process for users, but performance gains, developer flexibility, and a lot of new tools! Importantly, the high-level API stays the same, so it will be a seamless transition for users 💜! +### Development and Applications + +In 2018, we demonstrated the capabilities for [trail tracking](https://vnmurthylab.org/), [reaching in mice](http://www.mousemotorlab.org/) and various Drosophila behaviors during egg-laying (see [Mathis et al.](https://www.nature.com/articles/s41593-018-0209-y) for details). There is, however, nothing specific that makes the toolbox only applicable to these tasks and/or species. +The toolbox has already been successfully applied (by us and others) to [rats](http://www.mousemotorlab.org/deeplabcut), humans, various fish species, bacteria, leeches, various robots, cheetahs, [mouse whiskers](http://www.mousemotorlab.org/deeplabcut) and [race horses](http://www.mousemotorlab.org/deeplabcut). +DeepLabCut utilized the feature detectors (ResNets + readout layers) of one of the state-of-the-art algorithms for human pose estimation by Insafutdinov et al., called DeeperCut, which inspired the name for our toolbox (see references below). Since this time, the package has changed substantially. +The code has been re-tooled and re-factored since 2.1+: We have added faster and higher performance variants with MobileNetV2s, EfficientNets, and our own DLCRNet backbones (see [Pretraining boosts out-of-domain robustness for pose estimation](https://arxiv.org/abs/1909.11229) and [Lauer et al 2022](https://www.nature.com/articles/s41592-022-01443-0)). Additionally, we have improved the inference speed and provided both additional and novel augmentation methods, added real-time, and multi-animal support. +In v3.0+ we have updated the backend to support PyTorch. This brings not only an easier installation process for users, but performance gains, developer flexibility, and a lot of new tools! Importantly, the high-level API stays the same, so it will be a seamless transition for users 💜! We currently provide state-of-the-art performance for animal pose estimation and the labs (M. Mathis Lab and A. Mathis Group) have both top journal and computer vision conference papers.

@@ -145,49 +154,51 @@ We currently provide state-of-the-art performance for animal pose estimation and **Left:** Due to transfer learning it requires **little training data** for multiple, challenging behaviors (see [Mathis et al. 2018](https://www.nature.com/articles/s41593-018-0209-y) for details). **Mid Left:** The feature detectors are robust to video compression (see [Mathis/Warren](https://www.biorxiv.org/content/early/2018/10/30/457242) for details). **Mid Right:** It allows 3D pose estimation with a single network and camera (see [Mathis/Warren](https://www.biorxiv.org/content/early/2018/10/30/457242)). **Right:** It allows 3D pose estimation with a single network trained on data from multiple cameras together with standard triangulation methods (see [Nath* and Mathis* et al. 2019](https://doi.org/10.1038/s41596-019-0176-0)). -**DeepLabCut** is embedding in a larger open-source eco-system, providing behavioral tracking for neuroscience, ecology, medical, and technical applications. Moreover, many new tools are being actively developed. See [DLC-Utils](https://github.com/DeepLabCut/DLCutils) for some helper code. +### Ecosystem + +**DeepLabCut** is part of a larger open-source eco-system, providing behavioral tracking for neuroscience, ecology, medical, and technical applications. +Moreover, many new tools are being actively developed. See [DLC-Utils](https://github.com/DeepLabCut/DLCutils) for some helper code.

-## Code contributors: +### Code contributors -DLC code was originally developed by [Alexander Mathis](https://github.com/AlexEMG) & [Mackenzie Mathis](https://github.com/MMathisLab), and was extended in 2.0 with the core dev team consisting of [Tanmay Nath](https://github.com/meet10may) (2.0-2.1), [Jessy Lauer](https://github.com/jeylau) (2.1-2.4), and [Niels Poulsen](https://github.com/n-poulsen) (2.3-3.0). -DeepLabCut is an open-source tool and has benefited from suggestions and edits by many individuals including early contributors: Mert Yuksekgonul, Tom Biasi, Richard Warren, Ronny Eichler, Hao Wu, Federico Claudi, Gary Kane and Jonny Saunders as well as the [100+ contributors](https://github.com/DeepLabCut/DeepLabCut/graphs/contributors). Please see [AUTHORS](https://github.com/DeepLabCut/DeepLabCut/blob/master/AUTHORS) for more details! +DeepLabCut was originally developed by [Alexander Mathis](https://github.com/AlexEMG) & [Mackenzie Mathis](https://github.com/MMathisLab), and was extended in 2.0 with the core dev team consisting of [Tanmay Nath](https://github.com/meet10may) (2.0-2.1), [Jessy Lauer](https://github.com/jeylau) (2.1-2.4), and [Niels Poulsen](https://github.com/n-poulsen) (2.3-3.0). +DeepLabCut is an open-source tool and has benefited from suggestions and edits by many individuals including early contributors: Mert Yuksekgonul, Tom Biasi, Richard Warren, Ronny Eichler, Hao Wu, Federico Claudi, Gary Kane and Jonny Saunders as well as the [100+ contributors](https://github.com/DeepLabCut/DeepLabCut/graphs/contributors). +Please see [AUTHORS](https://github.com/DeepLabCut/DeepLabCut/blob/master/AUTHORS) for more details! 🤩 This is an actively developed package and we welcome community development and involvement: [![Contributors](https://contrib.rocks/image?repo=DeepLabCut/DeepLabCut)](https://github.com/DeepLabCut/DeepLabCut/graphs/contributors) - - -# Get Assistance & be part of the DLC Community✨: +# Get Assistance & be part of the DLC Community✨ | 🚉 Platform | 🎯 Goal | ⏱️ Estimated Response Time | 📢 Support Squad | |------------------------------------------------------------|-----------------------------------------------------------------------------|---------------------------|----------------------------------------| -| GitHub DeepLabCut/[Issues](https://github.com/DeepLabCut/DeepLabCut/issues) | To report bugs and code issues🐛 (we encourage you to search issues first) | 2-5 days | DLC Core Dev Team | -| GitHub DeepLabCut/[Contributing](https://github.com/DeepLabCut/DeepLabCut/blob/master/CONTRIBUTING.md) | To contribute your expertise and experience🙏💯 | 2-5 days | DLC Core Dev Team | -| 🚧 GitHub DeepLabCut/[Roadmap](https://github.com/DeepLabCut/DeepLabCut/blob/master/docs/roadmap.md) | To learn more about our journey✈️ | N/A | N/A +| GitHub - [Issues](https://github.com/DeepLabCut/DeepLabCut/issues) | To report bugs and code issues🐛 (we encourage you to search issues first) | 2-5 days | DLC Core Dev Team | +| GitHub - [Contributing](https://github.com/DeepLabCut/DeepLabCut/blob/master/CONTRIBUTING.md) | To contribute your expertise and experience🙏💯 | 2-5 days | DLC Core Dev Team | | [![Image.sc forum](https://img.shields.io/badge/dynamic/json.svg?label=forum&url=https%3A%2F%2Fforum.image.sc%2Ftag%2Fdeeplabcut.json&query=%24.topic_list.tags.0.topic_count&colorB=brightgreen&&suffix=%20topics&logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAA4AAAAOCAYAAAAfSC3RAAABPklEQVR42m3SyyqFURTA8Y2BER0TDyExZ+aSPIKUlPIITFzKeQWXwhBlQrmFgUzMMFLKZeguBu5y+//17dP3nc5vuPdee6299gohUYYaDGOyyACq4JmQVoFujOMR77hNfOAGM+hBOQqB9TjHD36xhAa04RCuuXeKOvwHVWIKL9jCK2bRiV284QgL8MwEjAneeo9VNOEaBhzALGtoRy02cIcWhE34jj5YxgW+E5Z4iTPkMYpPLCNY3hdOYEfNbKYdmNngZ1jyEzw7h7AIb3fRTQ95OAZ6yQpGYHMMtOTgouktYwxuXsHgWLLl+4x++Kx1FJrjLTagA77bTPvYgw1rRqY56e+w7GNYsqX6JfPwi7aR+Y5SA+BXtKIRfkfJAYgj14tpOF6+I46c4/cAM3UhM3JxyKsxiOIhH0IO6SH/A1Kb1WBeUjbkAAAAAElFTkSuQmCC)](https://forum.image.sc/tag/deeplabcut)
🐭Tag: DeepLabCut | To ask help and support questions 👋 | Promptly🔥 | The DLC Community | |[![Gitter](https://badges.gitter.im/DeepLabCut/community.svg)](https://gitter.im/DeepLabCut/community?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge) | To discuss with other users, share ideas and collaborate💡 | 2-5 days | The DLC Community | -| [BluSky🦋](https://bsky.app/profile/deeplabcut.bsky.social) | To keep up with our latest news and updates 📢 | 2-5 days | DLC Team | +| [![BlueSky](https://img.shields.io/badge/BlueSky-%40deeplabcut-blue?logo=bluesky)](https://bsky.app/profile/deeplabcut.bsky.social) | To keep up with our latest news and updates 📢 | 2-5 days | DLC Team | | [![Twitter Follow](https://img.shields.io/twitter/follow/DeepLabCut.svg?label=DeepLabCut&style=social)](https://x.com/DeepLabCut) | To keep up with our latest news and updates 📢 | 2-5 days | DLC Team | -| The DeepLabCut [AI Residency Program](https://www.deeplabcutairesidency.org/) | To come and work with us next summer👏 | Annually | DLC Team | + + -## References \& Citations: +## References \& Citations Please see our [dedicated page](https://deeplabcut.github.io/DeepLabCut/docs/citation.html) on how to **cite DeepLabCut** 🙏 and our suggestions for your Methods section! -## License: +## License This project is primarily licensed under the GNU Lesser General Public License v3.0. Note that the software is provided "as is", without warranty of any kind, express or implied. If you use the code or data, please cite us! Note, artwork (DeepLabCut logo) and images are copyrighted; please do not take or use these images without written permission. SuperAnimal models are provided for research use only (non-commercial use). -## Major Versions: +## Major Versions **For all versions, please see [here](https://github.com/DeepLabCut/DeepLabCut/releases).** @@ -202,18 +213,21 @@ This package includes graphical user interfaces to label your data, and take you VERSION 1.0: The initial, Nature Neuroscience version of [DeepLabCut](https://www.nature.com/articles/s41593-018-0209-y) can be found in the history of git, or here: https://github.com/DeepLabCut/DeepLabCut/releases/tag/1.11 -# News (and in the news): +# News + +## Major releases -:purple_heart: We released a major update, moving from 2.x --> 3.x with the backend change to PyTorch +💜 We released a major update, moving from 2.x --> 3.x with the backend change to PyTorch -:purple_heart: The DeepLabCut Model Zoo launches SuperAnimals, see more [here](https://deeplabcut.github.io/DeepLabCut/docs/ModelZoo.html). +💜 The DeepLabCut Model Zoo launches SuperAnimals, see more [here](https://deeplabcut.github.io/DeepLabCut/docs/ModelZoo.html). -:purple_heart: **DeepLabCut supports multi-animal pose estimation!** maDLC is out of beta/rc mode and beta is deprecated, thanks to the testers out there for feedback! Your labeled data will be backwards compatible, but not all other steps. Please see the [new `2.2+` releases](https://github.com/DeepLabCut/DeepLabCut/releases) for what's new & how to install it, please see our new [paper, Lauer et al 2022](https://www.nature.com/articles/s41592-022-01443-0), and the [new docs]( https://deeplabcut.github.io/DeepLabCut) on how to use it! +💜 **DeepLabCut supports multi-animal pose estimation!** maDLC is out of beta/rc mode and beta is deprecated, thanks to the testers out there for feedback! Your labeled data will be backwards compatible, but not all other steps. Please see the [new `2.2+` releases](https://github.com/DeepLabCut/DeepLabCut/releases) for what's new & how to install it, please see our new [paper, Lauer et al 2022](https://www.nature.com/articles/s41592-022-01443-0), and the [new docs]( https://deeplabcut.github.io/DeepLabCut) on how to use it! -:purple_heart: We support multi-animal re-identification, see [Lauer et al 2022](https://www.nature.com/articles/s41592-022-01443-0). +💜 We support multi-animal re-identification, see [Lauer et al 2022](https://www.nature.com/articles/s41592-022-01443-0). -:purple_heart: We have a **real-time** package available! http://DLClive.deeplabcut.org +💜 We have a **real-time** package available! [DLC-live on GitHub](https://github.com/DeepLabCut/DeepLabCut-live) and [DLC-live-GUI](https://github.com/DeepLabCut/DeepLabCut-live-GUI) +## In the news - June 2024: Our second DLC paper ['Using DeepLabCut for 3D markerless pose estimation across species and behaviors'](https://www.nature.com/articles/s41596-019-0176-0) in Nature Protocols has surpassed 1,000 Google Scholar citations! - May 2024: DeepLabCut was featured in Nature: ['DeepLabCut: the motion-tracking tool that went viral'](https://www.nature.com/articles/d41586-024-01474-x) @@ -251,6 +265,8 @@ importing a project into the new data format for DLC 2.0 - July 2018: Ed Yong covered DeepLabCut and interviewed several users for the [Atlantic](https://www.theatlantic.com/science/archive/2018/07/deeplabcut-tracking-animal-movements/564338). - April 2018: first DeepLabCut preprint on [arXiv.org](https://arxiv.org/abs/1804.03142) - ## Funding + # Funding - We are grateful for the follow support over the years! This software project was supported in part by the Essential Open Source Software for Science (EOSS) program at Chan Zuckerberg Initiative (cycles 1, 3, 3-DEI, 4), and jointly with the Kavli Foundation for EOSS Cycle 6! We also thank the Rowland Institute at Harvard for funding from 2017-2020, and EPFL from 2020-present. + We are grateful for the follow support over the years! + This software project was supported in part by the **Essential Open Source Software for Science (EOSS)** program at **Chan Zuckerberg Initiative** (cycles 1, 3, 3-DEI, 4), and jointly with the **Kavli Foundation** for **EOSS Cycle 6**! + We also thank the **Rowland Institute** at **Harvard** for funding from 2017-2020, and **EPFL** from 2020-present. diff --git a/docs/README.md b/docs/README.md index 2812d8f001..59de51578f 100644 --- a/docs/README.md +++ b/docs/README.md @@ -4,6 +4,8 @@ deeplabcut: last_metadata_updated: '2026-03-06' ignore: false --- + + Please see https://deeplabcut.github.io/DeepLabCut for documentation on how to use this software. This directory contains the source code for the docs. From 430f5a1634fcb1967a5fffc9287ecbbcf83480fe Mon Sep 17 00:00:00 2001 From: Cyril Achard Date: Tue, 21 Apr 2026 13:39:44 +0200 Subject: [PATCH 15/53] Revise installation docs and update instructions MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Refactor docs/installation.md: update frontmatter metadata and restructure the installation guide. Broaden supported Python versions (3.10–3.12), clarify conda vs miniconda usage, add `uv` developer install instructions and editable `pip install -e` guidance, and reorganize sections for Conda, pip, Docker, GPU support, troubleshooting, and system/hardware considerations. Update TensorFlow deprecation timeline and GPU/CUDA guidance, improve admonitions/notes formatting, fix anchors/section refs, and add various wording and usability improvements. --- docs/installation.md | 285 ++++++++++++++++++++++++------------------- 1 file changed, 158 insertions(+), 127 deletions(-) diff --git a/docs/installation.md b/docs/installation.md index dd9d0e743c..5fcd2b7c73 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -13,20 +13,22 @@ deeplabcut: (file:how-to-install)= # How To Install DeepLabCut -- **DeepLabCut can be run on Windows, Linux, or MacOS as long as you have Python 3.10 installed** - - (see also [technical considerations](tech-considerations-during-install) and if you run into issues also check out the [Installation Tips](https://deeplabcut.github.io/DeepLabCut/docs/recipes/installTips.html) page). -- 🚧 Please note, there are several modes of installation: - - please decide to either use a [**conda environment**](https://deeplabcut.github.io/DeepLabCut/docs/installation.html#conda-the-installation-process-is-as-easy-as-this-figure) based installation (**recommended**), - - or the supplied [**Docker container**](docker-containers) (recommended for Ubuntu advanced users). -- 🚀 Please note, you will get the best performance with using a **GPU**! - - Please see the section on [GPU support](https://deeplabcut.github.io/DeepLabCut/docs/installation.html#gpu-support) to install your GPU driver and CUDA. - -```{Hint} Familiar with python packages and conda? Quick Install Guide: +- **DeepLabCut can be run on Windows, Linux, or MacOS as long as you have Python 3.10-3.12 installed** + - See also [technical considerations](sec:hardware-considerations-during-install) and if you run into issues also check out the [installation tips](https://deeplabcut.github.io/DeepLabCut/docs/recipes/installTips.html). +- 🚧 Please note, there are **several equally valid modes of installation**: + - Install in a [**conda environment**](https://deeplabcut.github.io/DeepLabCut/docs/installation.html#conda-the-installation-process-is-as-easy-as-this-figure) (**recommended**) + - Install with [**uv**](sec:uv-install) (recommended for developers) + - In the supplied [**Docker container**](docker-containers) (recommended for Ubuntu advanced users). +- 🚀 Please note, you will get the best performance when using a **GPU**! + - Please see the section on [GPU support](sec:install-gpu-support) to install your GPU driver and CUDA. + +````{hint} +Familiar with python packages and conda? This assumes you have `conda`/`mamba` installed and this will install DeepLabCut in a fresh -environment. If you have an NVIDIA GPU, install PyTorch according to [their instructions -](https://pytorch.org/get-started/locally/) (with your desired CUDA version) - you just -need your GPU drivers installed. +environment. +If you have an NVIDIA GPU, install PyTorch according to [their instructions +](https://pytorch.org/get-started/locally/) (with your desired CUDA version) - you just need your GPU drivers installed. ```bash conda create -n DEEPLABCUT python=3.12 @@ -47,97 +49,93 @@ pip install --pre deeplabcut[gui] # should print `True` python -c "import torch; print(torch.cuda.is_available())" ``` +```` - If you're familiar with the command line and want TensorFlow support, look [below]( deeplabcut-with-tf-install) for a fresh installation that has worked for us (on Linux) and makes it possible to use the GPU with both PyTorch and TensorFlow. -## CONDA: The installation process is as easy as this figure! --> +## Using Conda DLC -### 🚨 Before you start with our conda file, do you have a GPU? +**The installation process is as easy as the figure below!** + +### 🚨 Before you start... + +Do you have a GPU? If yes, see the [GPU support section](sec:install-gpu-support) below for installation instructions. + +If not, you can still install DeepLabCut and use it on your CPU, but it will be much slower for training and evaluation (but not for labeling or project management). + ````{admonition} 🚨 Click here for more information! :class: dropdown - We recommend having a GPU if possible! -- You **need to decide if you want to use a CPU or GPU for your models**: (Note, you can also use the CPU-only for project management and labeling the data! Then, for example, use Google Colaboratory GPUs for free (read more [here](https://github.com/DeepLabCut/DeepLabCut/tree/master/examples#demo-4-deeplabcut-training-and-analysis-on-google-colaboratory-with-googles-gpus) and there are a lot of helper videos on [our YouTube channel!](https://www.youtube.com/playlist?list=PLjpMSEOb9vRFwwgIkLLN1NmJxFprkO_zi)). +- You **need to decide if you want to use a CPU or GPU for your models** - **CPU?** Great, jump to the next section below! - - **NVIDIA GPU?** If you want to use your own GPU (i.e., a GPU is in your workstation), then you need to be sure you have a CUDA compatible GPU, CUDA, and cuDNN installed. Please note, which CUDA you install depends on what version of PyTorch you want to use. So, please check "GPU Support" below carefully. **Note, DeepLabCut is up to date with the latest CUDA and PyTorch!** + - **NVIDIA GPU?** If you want to use your own GPU (i.e., a GPU is in your workstation), then you need to be sure you have a CUDA compatible GPU, CUDA, and cuDNN installed. + Please note, which CUDA you install depends on what version of PyTorch you want to use. So, please check [](sec:install-gpu-support) below carefully. **Note, DeepLabCut is up to date with the latest CUDA and PyTorch!** - - **Apple M-chip GPU?** Be sure to install miniconda3, and your GPU will be used by default. -```` + - **Apple M-chip GPU?** Be sure to install miniconda, and your GPU will be used by default. -### Step 1: Install Python via Anaconda +- Note, you can also use the CPU-only install for project management and labeling the data! +Then, for example, use Google Colaboratory GPUs for free (read more [here](https://github.com/DeepLabCut/DeepLabCut/tree/master/examples#demo-4-deeplabcut-training-and-analysis-on-google-colaboratory-with-googles-gpus) and there are a lot of helper videos on [our YouTube channel!](https://www.youtube.com/playlist?list=PLjpMSEOb9vRFwwgIkLLN1NmJxFprkO_zi)). +```` -### Install [anaconda](https://docs.conda.io/projects/conda/en/latest/user-guide/install/index.html#), or use miniconda3 for MacOS users (see below) +### Step 1: Install miniconda -- Anaconda is an easy way to install Python and additional packages across various operating systems. With Anaconda you create all the dependencies in an [environment](https://conda.io/docs/user-guide/tasks/manage-environments.html) on your machine. +- Anaconda is an easy way to install Python and additional packages across various operating systems +- With Anaconda you create all the dependencies in an [environment](https://conda.io/docs/user-guide/tasks/manage-environments.html) on your machine +- Miniconda is a lightweight version of Anaconda that includes only conda and its dependencies, which allows you to create your own environments and install only the packages you need. This is the recommended way to install DeepLabCut, as it allows for more flexibility and less disk space usage compared to the full Anaconda distribution. -```{Hint} -Download anaconda for your operating system: [anaconda.com/download/ -](https://www.anaconda.com/download/) +```{hint} +Download [miniconda](https://www.anaconda.com/docs/getting-started/miniconda/main) for your operating system ``` -- IF you use a M1 or M2 chip in your MacBook with v12.5+ (typically 2020 or newer machines), we recommend **miniconda3,** which operates with the same principles as anaconda. This is straight forward and explained in detail here: https://docs.conda.io/projects/conda/en/latest/user-guide/install/macos.html. But in short, open the program "terminal" and copy/paste and run the code that is supplied below. - -### 💡 miniconda for Mac -````{admonition} Click the button to see code for miniconda for Mac -:class: dropdown -wget https://repo.anaconda.com/miniconda/Miniconda3-py310_4.12.0-MacOSX-arm64.sh -O ~/miniconda.sh -bash ~/miniconda.sh -b -p $HOME/miniconda -source ~/miniconda/bin/activate -conda init zsh -```` - -### Step 2: Build an Env using our Conda file! +### Step 2: Build a conda environment using our environment file -You simply need to have this `.yaml` file anywhere locally on your computer. So, let's download it! +You simply need to have this `.yaml` file locally on your computer. So, let's download it! -```{Hint} -Windows users: Be sure you have `git` installed along with anaconda: https://gitforwindows.org/ +```{hint} +Windows users: Be sure you have `git` installed along with anaconda: [Git for Windows](https://gitforwindows.org/) ``` -- TO DIRECTLY DOWNLOAD THE CONDA FILE conda: - - - click ➡️ for [CONDA FILE](https://github.com/DeepLabCut/DeepLabCut/blob/main/conda-environments/DEEPLABCUT.yaml#:~:text=Raw%20file%20content-,Download,-%E2%8C%98) and then click the "..." and select Download +- Follow the link ➡️ for the [Conda file](https://github.com/DeepLabCut/DeepLabCut/blob/main/conda-environments/DEEPLABCUT.yaml#:~:text=Raw%20file%20content-,Download,-%E2%8C%98) and then click "..." and select Download Screen Shot 2023-09-13 at 10 33 32 PM - **Now, in Terminal (or Anaconda Command Prompt for Windows users)**, if you clicked to download, go to your downloads folder. -```{Hint} +```{hint} Windows users: Be sure to open the program terminal/cmd/anaconda prompt with a RIGHT-click, "open as admin" ``` -```{Hint} -:class: dropdown -If you cloned the repo onto your Desktop, the command may look like: -``cd C:\Users\YourUserName\Desktop\DeepLabCut\conda-environments`` -You can (on Windows) hold SHIFT and right-click > Copy as path, or (on Mac) right-click and while in the menu press the OPTION key to reveal Copy as Pathname. -``` Be sure you are in the folder that has the `.yaml` file, then run: ``conda env create -f DEEPLABCUT.yaml`` -- You can now use this environment from anywhere on your computer (i.e., no need to go back into the conda- folder). Just enter your environment by running: - - Ubuntu/MacOS: ``source/conda activate nameoftheenv`` (i.e. on your Mac: ``conda activate DEEPLABCUT``) - - Windows: ``activate nameoftheenv`` (i.e. ``activate DEEPLABCUT``) +- You can now use this environment from anywhere on your computer. Just enter your environment by running: ``conda activate DEEPLABCUT`` -Now you should see (`nameofenv`) on the left of your terminal screen, i.e. ``(DEEPLABCUT) YourName-MacBook...`` -NOTE: no need to run pip install deeplabcut, as it is already installed!!! :) + +Now you should see (`DEEPLABCUT`) on the left of your terminal screen, i.e. ``(DEEPLABCUT) YourName-MacBook...`` + +```{note} +No need to run `pip install deeplabcut`, it's already in the conda file! +``` (deeplabcut-with-tf-install)= -### 💡 Notice: PyTorch and TensorFlow Support within DeepLabCut +#### 💡 PyTorch and TensorFlow Support within DeepLabCut ````{admonition} DeepLabCut TensorFlow Support :class: dropdown -As of June 2024 we have a PyTorch Engine backend and we will be depreciating the -TensorFlow backend by the end of 2024. Currently, if you want to use TensorFlow, you +As of June 2024 we have a PyTorch Engine backend and we will be deprecating the +TensorFlow backend by 2027. +Currently, if you want to use TensorFlow, you need to run `pip install deeplabcut[tf]` in order to install the correct version of -TensorFlow in your conda env. Please note, we will be providing bug fixes, but we will +TensorFlow in your conda env. +Please note, we will be providing bug fixes, but we will not be supporting new TensorFlow versions beyond 2.10 (Windows), and 2.12 for other OS. Installing TensorFlow and getting it to have access to the GPU can be a bit tricky. @@ -170,50 +168,68 @@ pip install --pre deeplabcut ``` ```` -**Great, that's it! DeepLabCut is installed!** 🎉💜 -### Step 3: Really, that's it! Let's run DeepLabCut +### Step 3: Let's run DeepLabCut! + +**DeepLabCut is installed!** 🎉💜 Head over to the [User Guide Overview](https://deeplabcut.github.io/DeepLabCut/docs/UseOverviewGuide.html) for information. -🎉 Launch DeepLabCut in your new env by running `python -m deeplabcut` +🎉 Launch the DeepLabCut GUI in your new conda env by running `python -m deeplabcut` ## Other ways to install DeepLabCut and additional tips -### Alternatively, you can git clone this repo and install from source! -i.e., if the download did not work or you just want to have the source code handy! +### git clone + +Recommended for users who want to modify the code, or want to be up-to-date with the latest code on GitHub. - **Windows/Linux/MacBooks:** git clone this repo (in the terminal/cmd program, while **in a folder** you wish to place DeepLabCut -To git clone type: ``git clone https://github.com/DeepLabCut/DeepLabCut.git``). Note, this can be anywhere, even downloads is fine.) -- Then follow the same steps as in Step 2 above, adjusting for the file now being in the downloaded folder. +To git clone type: ``git clone https://github.com/DeepLabCut/DeepLabCut.git``) +- Then follow the same steps as in Step 2 above, adjusting for the `DEEPLABCUT.yaml` env file now being in the folder where you git cloned the repo. -### PIP: +(sec:uv-install)= +### `uv` (recommended for developers) + +- Install `uv` following [instructions here](https://docs.astral.sh/uv/getting-started/installation/) +- Run in the cloned repo: +```bash + uv venv -p 3.12 + uv pip install -e .[gui,modelzoo,tf] # Change optional install as needed + source .venv/bin/activate # or & .venv\Scripts\activate.ps1 on Windows +``` + +### `pip` - Everything you need to build custom models within DeepLabCut (i.e., use our source code and our dependencies) can be installed with `pip install 'deeplabcut[gui]'` (for GUI support w/PyTorch) or without the gui: `pip install 'deeplabcut'`. +- If you **cloned the repo** and want to make edits to the code locally, navigate to the cloned repo folder and run `pip install -e .[gui,modelzoo,tf]` to install the package in "editable" mode, which allows you to make changes to the code and have those changes reflected when you import the package. - If you want to use the SuperAnimal models, then please use `pip install 'deeplabcut[gui,modelzoo]'`. -## DOCKER: + +### Docker - We also have docker containers. Docker is the most reproducible way to use and deploy code. Please see our dedicated docker package and page [here](https://deeplabcut.github.io/DeepLabCut/docs/docker.html). -## Pro Tips: +## Tips -More [installation ProTips](installation-tips) are also available. +More [installation tips](installation-tips) are also available. -If you ever want to update your DLC, just run `pip install --upgrade deeplabcut` once -you are inside your env. If you want to use a specific release, then you need to specify -the version you want, such as `pip install deeplabcut==3.0`. Once installed, you can -check the version by running `import deeplabcut` `deeplabcut.__version__`. Don't be -afraid to update, DLC is backwards compatible with your 2.0+ projects and performance -continues to get better and new features are added nearly monthly. +### Updating your installation + +If you ever want to update your DLC, just run `pip install --upgrade deeplabcut` inside your env. +If you want to use a specific release, then specify the version you want, such as `pip install deeplabcut==3.0`. +Once installed, you can +check the version by running `import deeplabcut` `deeplabcut.__version__`. Don't be afraid to update, DLC is backwards compatible with your 2.0+ projects and performance continues to get better and new features are added often. **All of the data you labelled in version 2.X is also compatible with version 3+ and the -PyTorch engine**! There is no change in the workflow or the way labels are handled: the +PyTorch engine**! +There is no change in the workflow or the way labels are handled: the big changes happen under-the-hood! If you've been working with DeepLabCut 2.X and want -to learn more about moving to the PyTorch engine, checkout our docs on [moving from +to learn more about moving to the PyTorch engine, check out our docs on [moving from TensorFlow to PyTorch](dlc3-user-guide) +### Conda environment management tips + Here are some conda environment management tips: [kapeli.com: Conda Cheat Sheet]( https://kapeli.com/cheat_sheets/Conda.docset/Contents/Resources/Documents/index) @@ -225,11 +241,11 @@ https://www.youtube.com/watch?v=IOWtKn3l33s. ## Creating your own customized conda env (recommended route for Linux: Ubuntu, CentOS, Mint, etc.) -*Note in a fresh ubuntu install, you will often have to run: ``sudo apt-get install gcc python3-dev`` to install the GNU Compiler Collection and the python developing environment. - -Some users might want to create their own customize env. - Here is an example. +```{tip} +In a fresh ubuntu install, you will often have to run: ``sudo apt-get install gcc python3-dev`` to install the GNU Compiler Collection and the python developing environment. +``` -In the terminal type: +Create a new conda environment with Python 3.10 (or 3.11, 3.12) by running: `conda create -n DLC python=3.10` @@ -237,37 +253,42 @@ In the terminal type: `pip install deeplabcut`) or `pip install 'deeplabcut[gui]'` which has a napari based GUI. +(sec:install-gpu-support)= +## GPU Support + +### General GPU support -## **GPU Support:** +Please ensure you have an NVIDIA GPU and the matching NVIDIA driver installed. -The ONLY thing you need to do **first** if you have an NVIDIA GPU and the matching NVIDIA CUDA+driver installed. -- CUDA: https://developer.nvidia.com/cuda-downloads (just follow the prompts here!) -- DRIVERS: https://www.nvidia.com/Download/index.aspx +```{warning} +If you have a GPU, you should first **install an appropriate driver for +your specific GPU**, then you can use the supplied conda file. +``` -### The most common "new user" hurdle is installing and using your GPU, so don't get discouraged! +- Drivers: see [NVIDIA Drivers](https://www.nvidia.com/Download/index.aspx) +- CUDA: download [here](https://developer.nvidia.com/cuda-downloads) if needed. Installing the drivers usually allows you to skip installing CUDA; instead obtaining via the PyTorch installation process. -**CRITICAL:** If you have a GPU, you should FIRST **install an appropriate driver for -your specific GPU**, then you can use the supplied conda file. You'll need an NVIDIA GPU -which is compatible with CUDA. To see a list of CUDA-enabled NVIDIA GPUs, please [see -their website](https://developer.nvidia.com/cuda-gpus). +### Installing CUDA and cuDNN for TensorFlow GPU support -- Here we provide notes on how to install and check your GPU use with TensorFlow (which -is used by DeepLabCut and already installed with the Anaconda files above). Thus, you do -not need to independently install tensorflow. +You will need an NVIDIA GPU that is compatible with CUDA. -**FIRST**, install a driver for your GPU. Find DRIVER HERE: -https://www.nvidia.com/download/index.aspx +To see a list of CUDA-enabled NVIDIA GPUs, please [see +their website](https://developer.nvidia.com/cuda-gpus). -- Check which driver is installed by typing this into the terminal: ``nvidia-smi``. +Here we provide notes on how to install and check your GPU use with TensorFlow , which is used by DeepLabCut and will be installed with the Anaconda files above. +Thus, you do not need to independently install tensorflow. -**SECOND**, install CUDA: https://developer.nvidia.com/ (Note that cuDNN, https://developer.nvidia.com/cudnn, is supplied inside the anaconda environment files, so you don't need to install it again). +1. Install a driver for your GPU, using the NVIDIA Drivers link above. + - Check which driver is installed by typing this into the terminal: ``nvidia-smi``. -**THIRD:** Follow the steps above to get the `DEEPLABCUT` conda file and install it! +2. Install CUDA: https://developer.nvidia.com/ (Note that cuDNN, https://developer.nvidia.com/cudnn, is supplied inside the anaconda environment files, so you don't need to install it again). -### Notes: +3. Follow the steps above to get the `DEEPLABCUT` conda file and install it! + +### Notes - **As of version 3.0+ we moved to PyTorch. The Last supported version of TensorFlow is -2.10 (window users) and 2.12 for others (we have not tested beyond this).** +2.10 (window users) and 2.12 for others** (We will not be testing beyond this) - Please be mindful different versions of TensorFlow require different CUDA versions. - As the combination of TensorFlow and CUDA matters, we strongly encourage you to **check your driver/cuDNN/CUDA/TensorFlow versions** [on this StackOverflow post]( @@ -281,18 +302,16 @@ https://stackoverflow.com/questions/30820513/what-is-version-of-cuda-for-nvidia- (or `testscript_tensorflow_single_animal.py` for the TensorFlow engine); this is inside the examples folder you acquired when you git cloned the repo. Here is more information/a short [video on running the testscript](https://www.youtube.com/watch?v=IOWtKn3l33s). -- Additionally, if you want to use the bleeding edge, with your git clone you also get -the latest code. While inside the main DeepLabCut folder, you can run `./reinstall.sh` -to be sure it's installed (more [here](installation-tips)) -- You can test that your GPU is being properly engaged with these additional [tips]( +- You can test that your GPU is being properly used with these additional [tips]( https://www.tensorflow.org/programmers_guide/using_gpu). - Ubuntu users might find this [installation guide]( https://deeplabcut.github.io/DeepLabCut/docs/recipes/installTips.html#installation-on-ubuntu-20-04-lts -) for a fresh ubuntu install useful as well. +) for a fresh DLC install on Ubuntu useful as well. + +## Troubleshooting -## Troubleshooting: +### TensorFlow -TensorFlow: Here are some additional resources users have found helpful (posted without endorsement): - https://stackoverflow.com/questions/30820513/what-is-the-correct-version-of-cuda-for-my-nvidia-driver/30820690 @@ -308,37 +327,49 @@ Here are some additional resources users have found helpful (posted without endo - https://developer.nvidia.com/cuda-toolkit-archive -FFMPEG: +### FFMPEG - A few Windows users report needing to install re-install ffmpeg (after windows updates) as described here: https://video.stackexchange.com/questions/20495/how-do-i-set-up-and-use-ffmpeg-in-windows (A potential error could occur when making new videos). On Ubuntu, the command is: `sudo apt install ffmpeg` -DEEPLABCUT: +### DEEPLABCUT -- if you git clone or download this folder, and are inside of it then ``import deeplabcut`` will import the package from there rather than from the latest on PyPi! +- If you git clone or download this folder, and are inside of it then ``import deeplabcut`` will import the package from the local folder rather than from the latest on PyPi! -(system-wide-considerations-during-install)= +(sec:system-wide-considerations-during-install)= ## System-wide considerations: -If you perform the system-wide installation, and the computer has other Python packages or TensorFlow versions installed that conflict, this will overwrite them. If you have a dedicated machine for DeepLabCut, this is fine. If there are other applications that require different versions of libraries, then one would potentially break those applications. The solution to this problem is to create a virtual environment, a self-contained directory that contains a Python installation for a particular version of Python, plus additional packages. One way to manage virtual environments is to use conda environments (for which you need Anaconda installed). +```{note} +**What is a system-wide installation?** + +A system-wide installation, or a base environment installation, is when you install using the default Python environment/interpreter on your computer, instead of a compartimentalized, separate environment (e.g., a conda environment). + +This is often a source of conflicts between packages, user confusion and progressive "dependency hell" (where you have to keep installing and uninstalling packages to get the right versions for different applications). +``` + + +If you perform a system-wide installation, and the computer has other Python packages or TensorFlow versions installed that conflict, this will overwrite them. +If you have a dedicated machine for DeepLabCut, this is fine. If there are other applications that require different versions of libraries, then one would potentially break those applications. +The solution to this problem is to create a virtual environment (e.g. via conda or uv), a self-contained directory that contains a Python installation for a particular version of Python, plus additional packages. +One way to manage virtual environments is to use conda environments (for which you need Anaconda installed). -(tech-considerations-during-install)= -## Technical Considerations: +(sec:hardware-considerations-during-install)= +## Hardware considerations -- Computer: +- **Computer**: - For reference, we use e.g. Dell workstations (79xx series) with **Ubuntu 16.04 LTS, 18.04 LTS, 20.04 LTS, 22.04 LTS** and for versions prior to 2.2, we run a Docker container that has TensorFlow, etc. installed (https://github.com/DeepLabCut/Docker4DeepLabCut2.0). Now we use the new Docker containers supplied on this repo (linux support only), also available through [DockerHub](https://hub.docker.com/r/deeplabcut/deeplabcut) or the [`deeplabcut-docker`](https://pypi.org/project/deeplabcut-docker/) helper script. -- Computer Hardware: - - Ideally, you will use a strong NVIDIA GPU with *at least* 8GB memory. A GPU is not necessary, but on a CPU the (training and evaluation) code is considerably slower (10x) for ResNets, but MobileNets are faster (see WIKI). You might also consider using cloud computing services like [Google cloud/amazon web services](https://github.com/DeepLabCut/DeepLabCut/issues/47) or Google Colaboratory. +- **Computing Hardware**: + - An NVIDIA GPU with *at least* 8GB VRAM (memory) is ideal. + - A GPU is not strictly necessary, but on a CPU the (training and evaluation) code is considerably slower (10x) for ResNets, but MobileNets are faster. You might also consider using cloud computing services like [Google cloud/amazon web services](https://github.com/DeepLabCut/DeepLabCut/issues/47) or Google Colaboratory. -- Camera Hardware: - - The software is very robust to track data from any camera (cell phone cameras, grayscale, color; captured under infrared light, different manufacturers, etc.). See demos on our [website](https://www.mousemotorlab.org/deeplabcut/). +- **Camera Hardware**: + - The software is very robust to variations stemming from various cameras (cell phone cameras, grayscale, color; captured under infrared light, different manufacturers, etc.). See demos on our [website](https://www.mousemotorlab.org/deeplabcut/). + - Note that a model trained on certain data/camera may not generalize to data from a different camera however, so we recommend using the same camera for training and inference. -- Software: - - Operating System: Linux (Ubuntu), MacOS* (Mojave), or Windows 10. However, the authors strongly recommend Ubuntu! *MacOS does not support NVIDIA GPUs (easily), so we only suggest this option for CPU use or a case where the user wants to label data, refine data, etc and then push the project to a cloud resource for GPU computing steps, or use MobileNets. - - Anaconda/Python3: Anaconda: a free and open source distribution of the Python programming language (download from https://www.anaconda.com/). DeepLabCut is written in Python 3 (https://www.python.org/) and not compatible with Python 2. - - `pip install deeplabcut` - - TensorFlow - - If you want to use a pre3.0 version, you will need [TensorFlow](https://www.tensorflow.org/) (we used version 1.0 in the Nature Neuroscience paper, later versions also work with the provided code (we tested **TensorFlow versions 1.0 to 1.15, and 2.0 to 2.10**; we recommend TF2.10 now) for Python 3.8, 3.9, 3.10 with GPU support. - - To note, is it possible to run DeepLabCut on your CPU, but it will be VERY slow (see: [Mathis & Warren](https://www.biorxiv.org/content/early/2018/10/30/457242)). However, this is the preferred path if you want to test DeepLabCut on your own computer/data before purchasing a GPU, with the added benefit of a straightforward installation! Otherwise, use our COLAB notebooks for GPU access for testing. - - Docker: We highly recommend advanced users use the supplied [Docker container](docker-containers) +- **Software**: + - Operating System: Linux (Ubuntu), MacOS* (Mojave), or Windows 10. However, we the authors strongly recommend Ubuntu! *MacOS does not support NVIDIA GPUs (easily), so we only suggest this option for CPU use or a case where the user wants to label data, refine data, etc and then push the project to a cloud resource for GPU computing steps, or use MobileNets. + - DeepLabCut is written in Python 3 (https://www.python.org/) and not compatible with Python 2. + From f2873c3f6b1a5749eea8fbcfd575e7483826d791 Mon Sep 17 00:00:00 2001 From: Cyril Achard Date: Tue, 21 Apr 2026 15:44:16 +0200 Subject: [PATCH 16/53] docs: clarify and reformat installation guide Large cleanup and reorganization of docs/installation.md: rename heading, fix Markdown/admonition syntax, and normalize code fences. Clarified differences between Miniconda/Anaconda/conda, added a dedicated 'Build a conda environment' step, Windows-specific warnings, and tips for activating and managing environments. Added guidance for launching the GUI, created a simple conda env example, improved GPU/CUDA notes and troubleshooting links, and reformatted numerous paragraphs and images for readability. --- docs/installation.md | 218 ++++++++++++++++++++++++------------------- 1 file changed, 122 insertions(+), 96 deletions(-) diff --git a/docs/installation.md b/docs/installation.md index 5fcd2b7c73..753b7fb8ac 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -11,7 +11,8 @@ deeplabcut: verified_for: 3.0.0rc14 --- (file:how-to-install)= -# How To Install DeepLabCut + +# Installing DeepLabCut - **DeepLabCut can be run on Windows, Linux, or MacOS as long as you have Python 3.10-3.12 installed** - See also [technical considerations](sec:hardware-considerations-during-install) and if you run into issues also check out the [installation tips](https://deeplabcut.github.io/DeepLabCut/docs/recipes/installTips.html). @@ -51,14 +52,12 @@ python -c "import torch; print(torch.cuda.is_available())" ``` ```` -- If you're familiar with the command line and want TensorFlow support, look [below]( -deeplabcut-with-tf-install) for a fresh installation that has worked for us (on Linux) -and makes it possible to use the GPU with both PyTorch and TensorFlow. - +- If you're familiar with the command line and want TensorFlow support, look [below](deeplabcut-with-tf-install) for a fresh installation that has worked for us (on Linux) + and makes it possible to use the GPU with both PyTorch and TensorFlow. ## Using Conda - DLC +DLC **The installation process is as easy as the figure below!** @@ -68,8 +67,10 @@ Do you have a GPU? If yes, see the [GPU support section](sec:install-gpu-support If not, you can still install DeepLabCut and use it on your CPU, but it will be much slower for training and evaluation (but not for labeling or project management). -````{admonition} 🚨 Click here for more information! -:class: dropdown +```{admonition} 🚨 Click here for more information! +--- +class: dropdown +--- - We recommend having a GPU if possible! - You **need to decide if you want to use a CPU or GPU for your models** @@ -82,54 +83,71 @@ If not, you can still install DeepLabCut and use it on your CPU, but it will be - Note, you can also use the CPU-only install for project management and labeling the data! Then, for example, use Google Colaboratory GPUs for free (read more [here](https://github.com/DeepLabCut/DeepLabCut/tree/master/examples#demo-4-deeplabcut-training-and-analysis-on-google-colaboratory-with-googles-gpus) and there are a lot of helper videos on [our YouTube channel!](https://www.youtube.com/playlist?list=PLjpMSEOb9vRFwwgIkLLN1NmJxFprkO_zi)). -```` +``` ### Step 1: Install miniconda -- Anaconda is an easy way to install Python and additional packages across various operating systems -- With Anaconda you create all the dependencies in an [environment](https://conda.io/docs/user-guide/tasks/manage-environments.html) on your machine -- Miniconda is a lightweight version of Anaconda that includes only conda and its dependencies, which allows you to create your own environments and install only the packages you need. This is the recommended way to install DeepLabCut, as it allows for more flexibility and less disk space usage compared to the full Anaconda distribution. - -```{hint} +```{important} Download [miniconda](https://www.anaconda.com/docs/getting-started/miniconda/main) for your operating system ``` -### Step 2: Build a conda environment using our environment file +- miniconda is an easy way to install Python and additional packages across various operating systems +- With miniconda, you can install all the dependencies in an [environment](https://conda.io/docs/user-guide/tasks/manage-environments.html) on your machine +- Miniconda is a lightweight version of Anaconda that includes only conda and its dependencies. -You simply need to have this `.yaml` file locally on your computer. So, let's download it! +```{admonition} Wait, why are we mixing Anaconda, miniconda and conda? +--- +class: dropdown tip +--- +`conda` is the terminal-based environment management system that is included in both Anaconda and Miniconda. This is the actual workhorse that allows you to create and manage environments, and install packages. -```{hint} -Windows users: Be sure you have `git` installed along with anaconda: [Git for Windows](https://gitforwindows.org/) +**Anaconda** is a full-featured distribution that includes conda, Python, and a large number of scientific packages and their dependencies, plus some graphical user interfaces (GUIs) for managing environments and packages. It is a larger download and takes up more disk space. + +**Miniconda** is a minimal distribution that includes only conda and its dependencies, along with Python. It does not include any additional packages or GUIs. We recommend it as most GUIs and base packages provided by the full Anaconda distribution are not necessary for DeepLabCut. ``` -- Follow the link ➡️ for the [Conda file](https://github.com/DeepLabCut/DeepLabCut/blob/main/conda-environments/DEEPLABCUT.yaml#:~:text=Raw%20file%20content-,Download,-%E2%8C%98) and then click "..." and select Download - Screen Shot 2023-09-13 at 10 33 32 PM +(sec:conda-build-env)= + +### Step 2: Build a conda environment -- **Now, in Terminal (or Anaconda Command Prompt for Windows users)**, if you clicked to download, go to your downloads folder. +Use the `DEEPLABCUT.yaml` file to build a conda environment with all the dependencies for DeepLabCut. -```{hint} -Windows users: Be sure to open the program terminal/cmd/anaconda prompt with a RIGHT-click, "open as admin" +You simply need to have this `.yaml` file locally on your computer. + +```{warning} +On **Windows**, make sure you have `git` installed: [Git for Windows](https://gitforwindows.org/) ``` -Be sure you are in the folder that has the `.yaml` file, then run: +- Follow the link ➡️ for the [conda file](https://github.com/DeepLabCut/DeepLabCut/blob/main/conda-environments/DEEPLABCUT.yaml#:~:text=Raw%20file%20content-,Download,-%E2%8C%98) and then click "..." and select Download + Screen Shot 2023-09-13 at 10 33 32 PM -``conda env create -f DEEPLABCUT.yaml`` +- **Now, in Terminal (or Anaconda Command Prompt for Windows users)**: + - If you clicked to download, go to your downloads folder. + - Be sure you are in the folder that has the `.yaml` file, then run: + `conda env create -f DEEPLABCUT.yaml` -- You can now use this environment from anywhere on your computer. Just enter your environment by running: ``conda activate DEEPLABCUT`` +- You can now use this environment from anywhere on your computer. + Just activate your environment by running: `conda activate DEEPLABCUT` +Now you should see (`DEEPLABCUT`) on the left of your terminal screen: -Now you should see (`DEEPLABCUT`) on the left of your terminal screen, i.e. ``(DEEPLABCUT) YourName-MacBook...`` +``` +(DEEPLABCUT) YourName-MacBook... +``` ```{note} No need to run `pip install deeplabcut`, it's already in the conda file! ``` (deeplabcut-with-tf-install)= -#### 💡 PyTorch and TensorFlow Support within DeepLabCut ````{admonition} DeepLabCut TensorFlow Support -:class: dropdown +--- +class: dropdown +--- +💡 **PyTorch and TensorFlow Support within DeepLabCut** + As of June 2024 we have a PyTorch Engine backend and we will be deprecating the TensorFlow backend by 2027. Currently, if you want to use TensorFlow, you @@ -168,31 +186,45 @@ pip install --pre deeplabcut ``` ```` - - ### Step 3: Let's run DeepLabCut! **DeepLabCut is installed!** 🎉💜 +Launch the DeepLabCut GUI in your new conda env by running `python -m deeplabcut` + Head over to the [User Guide Overview](https://deeplabcut.github.io/DeepLabCut/docs/UseOverviewGuide.html) for information. -🎉 Launch the DeepLabCut GUI in your new conda env by running `python -m deeplabcut` +```{warning} +On **Windows**: Open the terminal/cmd/anaconda prompt as **Administrator** (right click and select "Run as administrator") to avoid permission issues when downloading models, and for symlink support when videos are not copied into the project folder. +``` + +### Conda environment management tips + +Here are some conda environment management tips: [kapeli.com: Conda Cheat Sheet](https://kapeli.com/cheat_sheets/Conda.docset/Contents/Resources/Documents/index) -## Other ways to install DeepLabCut and additional tips +**Pro Tip:** If you want to modify code and then test it, you can use our provided +test scripts. This would mean you need to be up-to-date with the latest GitHub-based code +though! Please see [here](installation-tips) on how to get the latest GitHub code, and +how to test your installation by following [this video](https://www.youtube.com/watch?v=IOWtKn3l33s). + +## Other ways to install DeepLabCut ### git clone Recommended for users who want to modify the code, or want to be up-to-date with the latest code on GitHub. - **Windows/Linux/MacBooks:** git clone this repo (in the terminal/cmd program, while **in a folder** you wish to place DeepLabCut -To git clone type: ``git clone https://github.com/DeepLabCut/DeepLabCut.git``) +- To git clone run: `git clone https://github.com/DeepLabCut/DeepLabCut.git`) - Then follow the same steps as in Step 2 above, adjusting for the `DEEPLABCUT.yaml` env file now being in the folder where you git cloned the repo. +- Or use pip/uv to install from the cloned repo (see below). (sec:uv-install)= + ### `uv` (recommended for developers) - Install `uv` following [instructions here](https://docs.astral.sh/uv/getting-started/installation/) - Run in the cloned repo: + ```bash uv venv -p 3.12 uv pip install -e .[gui,modelzoo,tf] # Change optional install as needed @@ -201,45 +233,20 @@ To git clone type: ``git clone https://github.com/DeepLabCut/DeepLabCut.git``) ### `pip` -- Everything you need to build custom models within DeepLabCut (i.e., use our source code and our dependencies) can be installed with `pip install 'deeplabcut[gui]'` (for GUI support w/PyTorch) or without the gui: `pip install 'deeplabcut'`. +If you already have a local environment, everything you need to use the project manager GI, train and/or build custom models within DeepLabCut (i.e., use our source code and our dependencies) can be installed with `pip install 'deeplabcut[gui]'` (for GUI support w/PyTorch) or without the gui: `pip install 'deeplabcut'`. + - If you **cloned the repo** and want to make edits to the code locally, navigate to the cloned repo folder and run `pip install -e .[gui,modelzoo,tf]` to install the package in "editable" mode, which allows you to make changes to the code and have those changes reflected when you import the package. - If you want to use the SuperAnimal models, then please use `pip install 'deeplabcut[gui,modelzoo]'`. - ### Docker - We also have docker containers. Docker is the most reproducible way to use and deploy code. Please see our dedicated docker package and page [here](https://deeplabcut.github.io/DeepLabCut/docs/docker.html). -## Tips +### Creating your own conda environment -More [installation tips](installation-tips) are also available. + -### Updating your installation - -If you ever want to update your DLC, just run `pip install --upgrade deeplabcut` inside your env. -If you want to use a specific release, then specify the version you want, such as `pip install deeplabcut==3.0`. -Once installed, you can -check the version by running `import deeplabcut` `deeplabcut.__version__`. Don't be afraid to update, DLC is backwards compatible with your 2.0+ projects and performance continues to get better and new features are added often. - -**All of the data you labelled in version 2.X is also compatible with version 3+ and the -PyTorch engine**! -There is no change in the workflow or the way labels are handled: the -big changes happen under-the-hood! If you've been working with DeepLabCut 2.X and want -to learn more about moving to the PyTorch engine, check out our docs on [moving from -TensorFlow to PyTorch](dlc3-user-guide) - -### Conda environment management tips - -Here are some conda environment management tips: [kapeli.com: Conda Cheat Sheet]( -https://kapeli.com/cheat_sheets/Conda.docset/Contents/Resources/Documents/index) - -**Pro Tip:** If you want to modify code and then test it, you can use our provided -testscripts. This would mean you need to be up-to-date with the latest GitHub-based code -though! Please see [here](installation-tips) on how to get the latest GitHub code, and -how to test your installation by following this video: -https://www.youtube.com/watch?v=IOWtKn3l33s. - -## Creating your own customized conda env (recommended route for Linux: Ubuntu, CentOS, Mint, etc.) + ```{tip} In a fresh ubuntu install, you will often have to run: ``sudo apt-get install gcc python3-dev`` to install the GNU Compiler Collection and the python developing environment. @@ -253,7 +260,22 @@ Create a new conda environment with Python 3.10 (or 3.11, 3.12) by running: `pip install deeplabcut`) or `pip install 'deeplabcut[gui]'` which has a napari based GUI. +## Updating your installation + +If you ever want to update your DLC, just run `pip install --upgrade deeplabcut` inside your env. +If you want to use a specific release, then specify the version you want, such as `pip install deeplabcut==3.0`. +Once installed, you can +check the version by running `import deeplabcut` `deeplabcut.__version__`. Don't be afraid to update, DLC is backwards compatible with your 2.0+ projects and performance continues to get better and new features are added often. + +**All of the data you labelled in version 2.X is also compatible with version 3+ and the +PyTorch engine**! +There is no change in the workflow or the way labels are handled: the +big changes happen under-the-hood! If you've been working with DeepLabCut 2.X and want +to learn more about moving to the PyTorch engine, check out our docs on [moving from +TensorFlow to PyTorch](dlc3-user-guide) + (sec:install-gpu-support)= + ## GPU Support ### General GPU support @@ -279,34 +301,27 @@ Here we provide notes on how to install and check your GPU use with TensorFlow , Thus, you do not need to independently install tensorflow. 1. Install a driver for your GPU, using the NVIDIA Drivers link above. - - Check which driver is installed by typing this into the terminal: ``nvidia-smi``. - -2. Install CUDA: https://developer.nvidia.com/ (Note that cuDNN, https://developer.nvidia.com/cudnn, is supplied inside the anaconda environment files, so you don't need to install it again). - -3. Follow the steps above to get the `DEEPLABCUT` conda file and install it! + - Check which driver is installed by typing this into the terminal: `nvidia-smi`. +1. Install [CUDA](https://developer.nvidia.com/). Note that [cuDNN](https://developer.nvidia.com/cudnn) is supplied inside the anaconda environment files, so you don't need to install it again. +1. Follow the steps above to get the `DEEPLABCUT` conda file and install it! ### Notes - **As of version 3.0+ we moved to PyTorch. The Last supported version of TensorFlow is -2.10 (window users) and 2.12 for others** (We will not be testing beyond this) + 2.10 (window users) and 2.12 for others** (We will not be testing beyond this) - Please be mindful different versions of TensorFlow require different CUDA versions. - As the combination of TensorFlow and CUDA matters, we strongly encourage you to -**check your driver/cuDNN/CUDA/TensorFlow versions** [on this StackOverflow post]( -https://stackoverflow.com/questions/30820513/what-is-version-of-cuda-for-nvidia-304-125/30820690#30820690 -). + **check your driver/cuDNN/CUDA/TensorFlow versions** [on this StackOverflow post](https://stackoverflow.com/questions/30820513/what-is-version-of-cuda-for-nvidia-304-125/30820690#30820690). - To check your GPU is working, in the terminal, run: `nvcc -V` to check your installed version(s). - The best practice is to then run the supplied `testscript_pytorch_single_animal.py` -(or `testscript_tensorflow_single_animal.py` for the TensorFlow engine); this is inside the examples folder you -acquired when you git cloned the repo. Here is more information/a short -[video on running the testscript](https://www.youtube.com/watch?v=IOWtKn3l33s). -- You can test that your GPU is being properly used with these additional [tips]( -https://www.tensorflow.org/programmers_guide/using_gpu). -- Ubuntu users might find this [installation guide]( -https://deeplabcut.github.io/DeepLabCut/docs/recipes/installTips.html#installation-on-ubuntu-20-04-lts -) for a fresh DLC install on Ubuntu useful as well. + (or `testscript_tensorflow_single_animal.py` for the TensorFlow engine); this is inside the examples folder you + acquired when you git cloned the repo. Here is more information/a short + [video on running the test scripts](https://www.youtube.com/watch?v=IOWtKn3l33s). +- You can test that your GPU is being properly used with these additional [tips](https://www.tensorflow.org/programmers_guide/using_gpu). +- Ubuntu users might find this [installation guide](https://deeplabcut.github.io/DeepLabCut/docs/recipes/installTips.html#installation-on-ubuntu-20-04-lts) for a fresh DLC install on Ubuntu useful as well. ## Troubleshooting @@ -326,16 +341,16 @@ Here are some additional resources users have found helpful (posted without endo - https://developer.nvidia.com/cuda-toolkit-archive - ### FFMPEG - A few Windows users report needing to install re-install ffmpeg (after windows updates) as described here: https://video.stackexchange.com/questions/20495/how-do-i-set-up-and-use-ffmpeg-in-windows (A potential error could occur when making new videos). On Ubuntu, the command is: `sudo apt install ffmpeg` ### DEEPLABCUT -- If you git clone or download this folder, and are inside of it then ``import deeplabcut`` will import the package from the local folder rather than from the latest on PyPi! +- If you git clone or download this folder, and are inside of it then `import deeplabcut` will import the package from the local folder rather than from the latest on PyPi! (sec:system-wide-considerations-during-install)= + ## System-wide considerations: ```{note} @@ -344,32 +359,43 @@ Here are some additional resources users have found helpful (posted without endo A system-wide installation, or a base environment installation, is when you install using the default Python environment/interpreter on your computer, instead of a compartimentalized, separate environment (e.g., a conda environment). This is often a source of conflicts between packages, user confusion and progressive "dependency hell" (where you have to keep installing and uninstalling packages to get the right versions for different applications). -``` +To avoid this, we recommend using a virtual environment (e.g., conda or uv managed environments) to keep your DeepLabCut installation separate from other Python packages and applications on your system. +``` -If you perform a system-wide installation, and the computer has other Python packages or TensorFlow versions installed that conflict, this will overwrite them. -If you have a dedicated machine for DeepLabCut, this is fine. If there are other applications that require different versions of libraries, then one would potentially break those applications. -The solution to this problem is to create a virtual environment (e.g. via conda or uv), a self-contained directory that contains a Python installation for a particular version of Python, plus additional packages. -One way to manage virtual environments is to use conda environments (for which you need Anaconda installed). +If you perform a system-wide/base environment installation, and the computer has other Python packages or TensorFlow versions installed that conflict, this will overwrite them. +If you have a dedicated machine for DeepLabCut, this may be temporarily fine, but will degrade over time as you try to install or update other packages. +Indeed, if there are other applications that require different versions of libraries, then one would potentially break those applications. +One way to manage virtual environments is to use conda environments (for which you need Anaconda/miniconda installed). +An environment is a self-contained directory that contains a Python installation for a particular version of Python, plus additional packages, without any cross-talk with other environments (NVIDIA drivers being a notable exception, as they are system-wide by nature). (sec:hardware-considerations-during-install)= + ## Hardware considerations - **Computer**: - - For reference, we use e.g. Dell workstations (79xx series) with **Ubuntu 16.04 LTS, 18.04 LTS, 20.04 LTS, 22.04 LTS** and for versions prior to 2.2, we run a Docker container that has TensorFlow, etc. installed (https://github.com/DeepLabCut/Docker4DeepLabCut2.0). Now we use the new Docker containers supplied on this repo (linux support only), also available through [DockerHub](https://hub.docker.com/r/deeplabcut/deeplabcut) or the [`deeplabcut-docker`](https://pypi.org/project/deeplabcut-docker/) helper script. + - For reference, we use e.g. Dell workstations (79xx series) with **Ubuntu 16.04 LTS, 18.04 LTS, 20.04 LTS, 22.04 LTS** and for versions prior to 2.2, we run a Docker container that has TensorFlow, etc. installed (https://github.com/DeepLabCut/Docker4DeepLabCut2.0). Now we use the new Docker containers supplied on this repo (linux support only), also available through [DockerHub](https://hub.docker.com/r/deeplabcut/deeplabcut) or the [`deeplabcut-docker`](https://pypi.org/project/deeplabcut-docker/) helper script. - **Computing Hardware**: - - An NVIDIA GPU with *at least* 8GB VRAM (memory) is ideal. - - A GPU is not strictly necessary, but on a CPU the (training and evaluation) code is considerably slower (10x) for ResNets, but MobileNets are faster. You might also consider using cloud computing services like [Google cloud/amazon web services](https://github.com/DeepLabCut/DeepLabCut/issues/47) or Google Colaboratory. + + - An NVIDIA GPU with *at least* 8GB VRAM (memory) is ideal. + - A GPU is not strictly necessary, but on a CPU the (training and evaluation) code is considerably slower (10x) for ResNets, but MobileNets are faster. You might also consider using cloud computing services like [Google cloud/amazon web services](https://github.com/DeepLabCut/DeepLabCut/issues/47) or Google Colaboratory. - **Camera Hardware**: - - The software is very robust to variations stemming from various cameras (cell phone cameras, grayscale, color; captured under infrared light, different manufacturers, etc.). See demos on our [website](https://www.mousemotorlab.org/deeplabcut/). - - Note that a model trained on certain data/camera may not generalize to data from a different camera however, so we recommend using the same camera for training and inference. + + - The software is very robust to variations stemming from various cameras (cell phone cameras, grayscale, color; captured under infrared light, different manufacturers, etc.). See demos on our [website](https://www.mousemotorlab.org/deeplabcut/). + - Note that a model trained on certain data/camera may not generalize to data from a different camera however, so we recommend using the same camera for training and inference. - **Software**: - - Operating System: Linux (Ubuntu), MacOS* (Mojave), or Windows 10. However, we the authors strongly recommend Ubuntu! *MacOS does not support NVIDIA GPUs (easily), so we only suggest this option for CPU use or a case where the user wants to label data, refine data, etc and then push the project to a cloud resource for GPU computing steps, or use MobileNets. - - DeepLabCut is written in Python 3 (https://www.python.org/) and not compatible with Python 2. - + +## Additional tips + +More [installation tips](installation-tips) are also available. From 7a8917b20f64a8f3bf7c6b0a32f0ee4601adbfed Mon Sep 17 00:00:00 2001 From: Cyril Achard Date: Tue, 21 Apr 2026 15:44:58 +0200 Subject: [PATCH 17/53] Revise UseOverviewGuide content and layout MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Restructure and update the UseOverviewGuide page: fix markup (e.g. hint directive), add an Introduction and Workflow overview, embed/adjust images, and reorganize sections (What we support → Main modes; Additional learning resources; Usage advice & project types). Clarify installation reference, start/requirements guidance, and what you don't need. Add tips/warnings (recommend single-animal first, Windows admin warning), improve option headings for demos/GUI/terminal, and add brief terminal usage steps and useful links. Remove or comment out outdated/broken link references and tidy copy for clarity. --- docs/UseOverviewGuide.md | 165 +++++++++++++++++++++++++-------------- 1 file changed, 108 insertions(+), 57 deletions(-) diff --git a/docs/UseOverviewGuide.md b/docs/UseOverviewGuide.md index 77cf3eda53..35f2758c45 100644 --- a/docs/UseOverviewGuide.md +++ b/docs/UseOverviewGuide.md @@ -4,79 +4,90 @@ deeplabcut: last_metadata_updated: '2026-03-06' ignore: false --- + (overview)= + # 🥳 Get started with DeepLabCut: our key recommendations Below we will first outline what you need to get started, the different ways you can use DeepLabCut, and then the full workflow. Note, we highly recommend you also read and follow our [Nature Protocols paper](https://www.nature.com/articles/s41596-019-0176-0), which is (still) fully relevant to standard DeepLabCut. -```{Hint} +```{hint} 💡📚 If you are new to Python and DeepLabCut, you might consider checking our [beginner guide](https://deeplabcut.github.io/DeepLabCut/docs/beginner-guides/beginners-guide.html) once you are ready to jump into using the DeepLabCut App! ``` +## Introduction -## [How to install DeepLabCut](how-to-install) +**DeepLabCut** is a software package for markerless pose estimation of animals performing various tasks. The software can manage multiple projects for various tasks. Each project is identified by the name of the project (e.g. TheBehavior), name of the experimenter (e.g. YourName), as well as the date at creation. This project folder holds a `config.yaml` (a text document) file containing various (project) parameters as well as links the data of the project. + +

+ +

+ +

+ +

+ +## {ref}`Installing DeepLabCut` We don't cover installation in depth on this page, so click on the link above if that is what you are looking for. See below for details on getting started with DeepLabCut! -## What we support: +## What we support We are primarily a package that enables deep learning-based pose estimation. We have a lot of models and options, but don't get overwhelmed -- the developer team has tried our best to "set the best defaults we possibly can"! -- Decide on your needs: there are **two main modes, standard DeepLabCut or multi-animal DeepLabCut**. We highly recommend carefully considering which one is best for your needs. For example, a white mouse + black mouse would call for standard, while two black mice would use multi-animal. **[Important Information on how to use DLC in different scenarios (single vs multi animal)](important-info-regd-usage)** Then pick a user guide: +### Main modes of DeepLabCut + +- Decide on your needs: there are **two main modes, standard DeepLabCut or multi-animal DeepLabCut**. + - We highly recommend carefully considering which one is best for your needs. + - For example, a white mouse + black mouse would call for standard, while two black mice would use multi-animal. **[Important Information on how to use DLC in different scenarios (single vs multi animal)](important-info-regd-usage)** Then pick a user guide: - (1) [How to use standard DeepLabCut](single-animal-userguide) - (2) [How to use multi-animal DeepLabCut](multi-animal-userguide) -- To note, as of DLC3+ the single and multi-animal code bases are more integrated and we support **top-down**, **bottom-up**, and a new "hybrid" approach that is state-of-the-art, called **BUCTD** (bottom-up conditional top down), models. +- To note, as of DLC3+ the single and multi-animal code bases are more integrated and we support **top-down**, **bottom-up**, and a new "hybrid" approach that is state-of-the-art, called **BUCTD** (bottom-up conditional top down) + - If these terms are new to you, check out our [Primer on Motion Capture with Deep Learning!](https://www.sciencedirect.com/science/article/pii/S0896627320307170). In brief, both work for single or multiple animals and each method can be better or worse on your data.

- - Here is more information on BUCTD: +- Here is more information on BUCTD: +

- **Additional Learning Resources:** +### Additional learning resources - - [TUTORIALS:](https://www.youtube.com/channel/UC2HEbWpC_1v6i9RnDMy-dfA?view_as=subscriber) video tutorials that demonstrate various aspects of using the code base. - - [HOW-TO-GUIDES:](overview) step-by-step user guidelines for using DeepLabCut on your own datasets (see below) - - [EXPLANATIONS:](https://github.com/DeepLabCut/DeepLabCut-Workshop-Materials) resources on understanding how DeepLabCut works - - [REFERENCES:](https://github.com/DeepLabCut/DeepLabCut#references) read the science behind DeepLabCut - - [BEGINNER GUIDE TO THE GUI](https://deeplabcut.github.io/DeepLabCut/docs/beginner-guides/beginners-guide.html) +- [Video tutorials:](https://www.youtube.com/channel/UC2HEbWpC_1v6i9RnDMy-dfA?view_as=subscriber) video tutorials that demonstrate various aspects of using the code base. -Getting Started: [a video tutorial on navigating the documentation!](https://www.youtube.com/watch?v=A9qZidI7tL8) + + -### What you need to get started: +- [Explanations:](https://github.com/DeepLabCut/DeepLabCut-Workshop-Materials) resources on understanding how DeepLabCut works +- [References:](https://github.com/DeepLabCut/DeepLabCut#references) read the science behind DeepLabCut +- [Beginner Guide to the GUI](https://deeplabcut.github.io/DeepLabCut/docs/beginner-guides/beginners-guide.html) - - **a set of videos that span the types of behaviors you want to track.** Having 10 videos that include different backgrounds, different individuals, and different postures is MUCH better than 1 or 2 videos of 1 or 2 different individuals (i.e. 10-20 frames from each of 10 videos is **much better** than 50-100 frames from 2 videos). + - - **minimally, a computer w/a CPU.** If you want to use DeepLabCut on your own computer for many experiments, then you should get an NVIDIA GPU. See technical specs [here](https://github.com/DeepLabCut/DeepLabCut/wiki/FAQ). You can also use cloud computing resources, including COLAB ([see how](https://github.com/DeepLabCut/DeepLabCut/blob/master/examples/README.md)). + +### What you need to get started -### What you DON'T need to get started: +- **A set of videos that span the types of behaviors you want to track.** Having 10 videos that include different backgrounds, different individuals, and different postures is MUCH better than 1 or 2 videos of 1 or 2 different individuals (i.e. 10-20 frames from each of 10 videos is **much better** than 50-100 frames from 2 videos). - - no specific cameras/videos are required; color, monochrome, etc., is all fine. If you can see what you want to measure, then this will work for you (given enough labeled data). +- **Ideally, a computer with a GPU.** If you want to use DeepLabCut on your own computer for training and/or for many experiments, then you should get an NVIDIA GPU. See technical specs [here](https://github.com/DeepLabCut/DeepLabCut/wiki/FAQ). You can also use cloud computing resources, including COLAB ([see how](https://github.com/DeepLabCut/DeepLabCut/blob/master/examples/README.md)). - - no specific computer is required (but see recommendations above), our software works on Linux, Windows, and MacOS. +### What you DON'T need to get started +- No specific cameras/videos are required; color, monochrome, etc., is all fine. If you can see what you want to measure, then this will work for you (given enough labeled data). -### Overview: -**DeepLabCut** is a software package for markerless pose estimation of animals performing various tasks. The software can manage multiple projects for various tasks. Each project is identified by the name of the project (e.g. TheBehavior), name of the experimenter (e.g. YourName), as well as the date at creation. This project folder holds a ``config.yaml`` (a text document) file containing various (project) parameters as well as links the data of the project. +- No specific computer is required (but see recommendations above), our software works on Linux, Windows, and MacOS. +## Workflow overview -

- -

- -

- -

- -### Overview of the workflow: This page contains a list of the essential functions of DeepLabCut as well as demos. There are many optional parameters with each described function. For detailed function documentation, please refer to the main user guides or API documentation. For additional assistance, you can use the [help](UseOverviewGuide.md#help) function to better understand what each function does.

@@ -87,42 +98,44 @@ This page contains a list of the essential functions of DeepLabCut as well as de

-You can have as many projects on your computer as you wish. You can have DeepLabCut installed in an [environment](../conda-environments/README.md) and always exit and return to this environment to run the code. You just need to point to the correct ``config.yaml`` file to [jump back in](/docs/UseOverviewGuide.md#tips-for-daily-use)! The documentation below will take you through the individual steps. +You can have as many projects on your computer as you wish. +You can have DeepLabCut installed in a {ref}`conda environment`; once you are finished, exit your terminal, and later re-activate your environment. + +When working on a given project, you just need to point to the correct `config.yaml` file to [jump back in](/docs/UseOverviewGuide.md#tips-for-daily-use)! The documentation below will take you through the individual steps.

- (important-info-regd-usage)= -# Specific Advice for Using DeepLabCut: +## Usage advice & project types -## Important information on using DeepLabCut: - -We recommend first using **DeepLabCut for a single animal scenario** to understand the workflow - even if it's just our demo data. Multi-animal tracking is more complex - i.e. it has several decisions the user needs to make. Then, when you are ready you can jump into multi-animals... - -### Additional information for getting started with maDeepLabCut: +```{tip} +We recommend first using **DeepLabCut for a single animal scenario** to understand the workflow - even if it's just our demo data. Multi-animal tracking is more complex - i.e. it has several decisions the user needs to make. Then, when you are ready you can jump into multi-animal mode. +``` -We highly recommend using it first in the Project Manager GUI ([Option 3](docs/functionDetails.md#deeplabcut-project-manager-gui)). This will allow you to get used to the additional steps by being walked through the process. Then, you can always use all the functions in your favorite IDE, notebooks, etc. +### First project: single or multi-animal? -### *What scenario do you have?* +*What scenario do you have?* - **I have single animal videos:** - - quick start: when you `create_new_project` (and leave the default flag to False in `multianimal=False`). This is the typical work path for many of you. + + - quick start: when you `create_new_project` (and leave the default flag to False in `multianimal=False`). This is the typical work path for many of you. - **I have single animal videos, but I want to use the updated network capabilities introduced for multi-animal projects:** - - quick start: when you `create_new_project` just set the flag `multianimal=True`. This enables you to use maDLC features even though you have only one animal. To note, this is rarely required for single animal projects, and not the recommended path. Some tips for when you might want to use this: this is good for say, a hand or a mouse if you feel the "skeleton" during training would increase performance. DON'T do this for things that could be identified an individual objects. i.e., don't do whisker 1, whisker 2, whisker 3 as 3 individuals. Each whisker always has a specific spatial location, and by calling them individuals you will do WORSE than in single animal mode. + + - quick start: when you `create_new_project` just set the flag `multianimal=True`. This enables you to use maDLC features even though you have only one animal. To note, this is rarely required for single animal projects, and not the recommended path. Some tips for when you might want to use this: this is good for say, a hand or a mouse if you feel the "skeleton" during training would increase performance. DON'T do this for things that could be identified an individual objects. i.e., don't do whisker 1, whisker 2, whisker 3 as 3 individuals. Each whisker always has a specific spatial location, and by calling them individuals you will do WORSE than in single animal mode. [VIDEO TUTORIAL AVAILABLE!](https://youtu.be/JDsa8R5J0nQ) - **I have multiple *identical-looking animals* in my videos:** - - quick start: when you `create_new_project` set the flag `multianimal=True`. If you can't tell them apart, you can assign the "individual" ID to any animal in each frame. See this [labeling w/2.2 demo video](https://www.youtube.com/watch?v=_qbEqNKApsI) + - quick start: when you `create_new_project` set the flag `multianimal=True`. If you can't tell them apart, you can assign the "individual" ID to any animal in each frame. See this [labeling w/2.2 demo video](https://www.youtube.com/watch?v=_qbEqNKApsI) [VIDEO TUTORIAL AVAILABLE!](https://youtu.be/Kp-stcTm77g) - **I have multiple animals, *but I can tell them apart,* in my videos and want to use DLC2.2:** - - quick start: when you `create_new_project` set the flag `multianimal=True`. And always label the "individual" ID name the same; i.e. if you have mouse1 and mouse2 but mouse2 always has a miniscope, in every frame label mouse2 consistently. See this [labeling w/2.2 demo video](https://www.youtube.com/watch?v=_qbEqNKApsI). Then, you MUST put the following in the config.yaml file: `identity: true` + - quick start: when you `create_new_project` set the flag `multianimal=True`. And always label the "individual" ID name the same; i.e. if you have mouse1 and mouse2 but mouse2 always has a miniscope, in every frame label mouse2 consistently. See this [labeling w/2.2 demo video](https://www.youtube.com/watch?v=_qbEqNKApsI). Then, you MUST put the following in the config.yaml file: `identity: true` [VIDEO TUTORIAL AVAILABLE!](https://youtu.be/Kp-stcTm77g) - ALSO, if you can tell them apart, label animals them consistently! @@ -130,42 +143,76 @@ We highly recommend using it first in the Project Manager GUI ([Option 3](docs/f Please read [this convert 2 maDLC guide](convert-maDLC) -# The options for using DeepLabCut: +### Getting started with multi-animal (ma) DeepLabCut + +We highly recommend using it first in the Project Manager GUI ([Option 3](docs/functionDetails.md#deeplabcut-project-manager-gui)). +This will allow you to get used to the additional steps by being walked through the process. Then, you can always use all the functions in your favorite IDE, notebooks, etc. + +## How to run DeepLabCut -Great - now that you get the overall workflow let's jump in! Here, you have several options. +There are several options to use DeepLabCut, and we recommend you pick the one that best suits your needs and experience level. You can always switch between them, so don't worry about picking the "wrong" one. -[**Option 1**](using-demo-notebooks) DEMOs: for a quick introduction to DLC on our data. +- **Option 1**: [Demo notebooks](using-demo-notebooks): for a quick introduction to DLC on our data. -[**Option 2**](using-project-manager-gui) Standalone GUI: is the perfect place for -beginners who want to start using DeepLabCut on your own data. +- **Option 2**: [Standalone GUI](using-project-manager-gui): is the perfect place for + beginners who want to start using DeepLabCut on your own data. -[**Option 3**](using-the-terminal) In the terminal: is best for more advanced users, as -with the terminal interface you get the most versatility and options. +- **Option 3**: [In the terminal](using-the-terminal): is best for more advanced users, as + with the terminal interface you get the most versatility and options. (using-demo-notebooks)= -## Option 1: Demo Notebooks: + +### Option 1: Demo Jupyter notebooks + [VIDEO TUTORIAL AVAILABLE!](https://www.youtube.com/watch?v=DRT-Cq2vdWs) We provide Jupyter and COLAB notebooks for using DeepLabCut on both a pre-labeled dataset, and on the end user's -own dataset. See all the demo's [here!](../examples/README.md) Please note that GUIs are not easily supported in Jupyter in MacOS, as you need a framework build of python. While it's possible to launch them with a few tweaks, we recommend using the Project Manager GUI or terminal, so please follow the instructions below. +own dataset. See all the demo's [here!](../examples/README.md) +Please note that GUIs are not easily supported in Jupyter in MacOS, as you need a framework build of python. While it's possible to launch them with a few tweaks, we recommend using the Project Manager GUI or terminal, so please follow the instructions below. (using-project-manager-gui)= -## Option 2: using the Project Manager GUI: + +### Option 2: using the Project Manager GUI + [VIDEO TUTORIAL!](https://www.youtube.com/watch?v=KcXogR-p5Ak) [VIDEO TUTORIAL#2!](https://youtu.be/Kp-stcTm77g) -Start Python by typing ``ipython`` or ``python`` in the terminal (note: using pythonw for Mac users was depreciated in 2022). -If you are using DeepLabCut on the cloud, you cannot use the GUIs. If you use Windows, please always open the terminal with administrator privileges. Please read more in our Nature Protocols paper [here](https://www.nature.com/articles/s41596-019-0176-0). And, see our [troubleshooting wiki](https://github.com/DeepLabCut/DeepLabCut/wiki/Troubleshooting-Tips). + + + + +If you are using DeepLabCut on the cloud, you cannot use the GUIs. + +```{warning} +On **Windows**: Open the terminal/cmd/anaconda prompt as **Administrator** (right click and select "Run as administrator") to avoid permission issues when downloading models, and for symlink support when videos are not copied into the project folder. +``` Simply open the terminal and type: + ```python python -m deeplabcut ``` + That's it! Follow the GUI for details (using-the-terminal)= -## Option 3: using the program terminal, Start iPython*: + +### Option 3: using the terminal + +1. Start iPython: + +```bash +ipython +``` + +2. Import DeepLabCut: + +```python +import deeplabcut +``` + +3. Follow the instructions in the user guides for either standard or multi-animal DeepLabCut (see below). [VIDEO TUTORIAL AVAILABLE!](https://www.youtube.com/watch?v=7xwOhUcIGio) @@ -173,3 +220,7 @@ Please decide with mode you want to use DeepLabCut, and follow one of the follow - (1) [How to use standard DeepLabCut](single-animal-userguide) - (2) [How to use multi-animal DeepLabCut](multi-animal-userguide) + +## Useful links + +Please read more in our Nature Protocols paper [here](https://www.nature.com/articles/s41596-019-0176-0). And, see our [troubleshooting wiki](https://github.com/DeepLabCut/DeepLabCut/wiki/Troubleshooting-Tips). From aed72a9b8270a5b28457ab8800b652efe9f06d54 Mon Sep 17 00:00:00 2001 From: Cyril Achard Date: Tue, 21 Apr 2026 16:24:11 +0200 Subject: [PATCH 18/53] Update installation docs: GPU/OS guidance Rewrite and clarify installation guidance in docs/installation.md. Rephrase installation bullets (conda recommended, Docker note, GPU performance), fix image HTML closing and caption, and replace a single admonition with a tab-set providing CPU, NVIDIA GPU, and Apple M-chip GPU tabs (including CUDA/cuDNN guidance). Minor wording and link adjustments for clarity and reproducibility. --- docs/installation.md | 35 ++++++++++++++++++++--------------- 1 file changed, 20 insertions(+), 15 deletions(-) diff --git a/docs/installation.md b/docs/installation.md index 753b7fb8ac..8e244d19b9 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -16,11 +16,11 @@ deeplabcut: - **DeepLabCut can be run on Windows, Linux, or MacOS as long as you have Python 3.10-3.12 installed** - See also [technical considerations](sec:hardware-considerations-during-install) and if you run into issues also check out the [installation tips](https://deeplabcut.github.io/DeepLabCut/docs/recipes/installTips.html). -- 🚧 Please note, there are **several equally valid modes of installation**: - - Install in a [**conda environment**](https://deeplabcut.github.io/DeepLabCut/docs/installation.html#conda-the-installation-process-is-as-easy-as-this-figure) (**recommended**) +- 🚧 Please note, there are several possibilities for installation: + - **Recommended for most users**: Install in a [**conda environment**](https://deeplabcut.github.io/DeepLabCut/docs/installation.html#conda-the-installation-process-is-as-easy-as-this-figure) - Install with [**uv**](sec:uv-install) (recommended for developers) - - In the supplied [**Docker container**](docker-containers) (recommended for Ubuntu advanced users). -- 🚀 Please note, you will get the best performance when using a **GPU**! + - In the supplied [**Docker container**](docker-containers) (recommended for Ubuntu advanced users and reproducibility). +- 🚀 You will get the best performance when using a **GPU**! - Please see the section on [GPU support](sec:install-gpu-support) to install your GPU driver and CUDA. ````{hint} @@ -52,14 +52,13 @@ python -c "import torch; print(torch.cuda.is_available())" ``` ```` -- If you're familiar with the command line and want TensorFlow support, look [below](deeplabcut-with-tf-install) for a fresh installation that has worked for us (on Linux) - and makes it possible to use the GPU with both PyTorch and TensorFlow. +- If you're familiar with the command line and want TensorFlow support, look [below](deeplabcut-with-tf-install) for a fresh installation on Linux and makes it possible to use the GPU with both PyTorch and TensorFlow. ## Using Conda -DLC +DLC -**The installation process is as easy as the figure below!** +**The installation process is as easy as the figure on the right!↘️** ### 🚨 Before you start... @@ -67,23 +66,29 @@ Do you have a GPU? If yes, see the [GPU support section](sec:install-gpu-support If not, you can still install DeepLabCut and use it on your CPU, but it will be much slower for training and evaluation (but not for labeling or project management). -```{admonition} 🚨 Click here for more information! +`````{admonition} 🚨 Hardware information! --- class: dropdown --- - We recommend having a GPU if possible! - You **need to decide if you want to use a CPU or GPU for your models** - - **CPU?** Great, jump to the next section below! - - - **NVIDIA GPU?** If you want to use your own GPU (i.e., a GPU is in your workstation), then you need to be sure you have a CUDA compatible GPU, CUDA, and cuDNN installed. + ````{tab-set} + ```{tab-item} CPU + Great, jump to the next section below! + ``` + ```{tab-item} NVIDIA GPU + If you want to use your own GPU (i.e., a GPU is in your workstation), then you need to be sure you have a CUDA compatible GPU, CUDA, and cuDNN installed. Please note, which CUDA you install depends on what version of PyTorch you want to use. So, please check [](sec:install-gpu-support) below carefully. **Note, DeepLabCut is up to date with the latest CUDA and PyTorch!** - - - **Apple M-chip GPU?** Be sure to install miniconda, and your GPU will be used by default. + ``` + ```{tab-item} Apple M-chip GPU + Be sure to install miniconda, and your GPU will be used by default. + ``` + ```` - Note, you can also use the CPU-only install for project management and labeling the data! Then, for example, use Google Colaboratory GPUs for free (read more [here](https://github.com/DeepLabCut/DeepLabCut/tree/master/examples#demo-4-deeplabcut-training-and-analysis-on-google-colaboratory-with-googles-gpus) and there are a lot of helper videos on [our YouTube channel!](https://www.youtube.com/playlist?list=PLjpMSEOb9vRFwwgIkLLN1NmJxFprkO_zi)). -``` +````` ### Step 1: Install miniconda From 10a585636655c0eff37cc2deec28ff3328f9c1ad Mon Sep 17 00:00:00 2001 From: Cyril Achard Date: Tue, 21 Apr 2026 16:26:44 +0200 Subject: [PATCH 19/53] Clarify and reformat UseOverviewGuide Refines wording and layout in the UseOverviewGuide: changes "What scenario" to "Which scenario", normalizes "Quick start" capitalization, and restructures multi-animal guidance into clearer bullet points. Expands guidance about using multianimal mode for single-animal projects (when a skeleton helps) and warns against treating fixed-position parts (e.g., whiskers) as separate individuals. Consolidates and repositions tutorial links, adds an important note to label identifiable animals consistently, updates the conversion link phrasing, and clarifies the Windows note to state admin is required for certain usage tasks (downloading models/symlinks) but not for installation. --- docs/UseOverviewGuide.md | 35 ++++++++++++++++++++++++----------- 1 file changed, 24 insertions(+), 11 deletions(-) diff --git a/docs/UseOverviewGuide.md b/docs/UseOverviewGuide.md index 35f2758c45..7d967ae285 100644 --- a/docs/UseOverviewGuide.md +++ b/docs/UseOverviewGuide.md @@ -117,31 +117,43 @@ We recommend first using **DeepLabCut for a single animal scenario** to understa ### First project: single or multi-animal? -*What scenario do you have?* +*Which scenario do you have?* - **I have single animal videos:** - - quick start: when you `create_new_project` (and leave the default flag to False in `multianimal=False`). This is the typical work path for many of you. + - Quick start: when you `create_new_project` (and leave the default flag to False in `multianimal=False`). This is the typical work path for a single animal project. - **I have single animal videos, but I want to use the updated network capabilities introduced for multi-animal projects:** - - quick start: when you `create_new_project` just set the flag `multianimal=True`. This enables you to use maDLC features even though you have only one animal. To note, this is rarely required for single animal projects, and not the recommended path. Some tips for when you might want to use this: this is good for say, a hand or a mouse if you feel the "skeleton" during training would increase performance. DON'T do this for things that could be identified an individual objects. i.e., don't do whisker 1, whisker 2, whisker 3 as 3 individuals. Each whisker always has a specific spatial location, and by calling them individuals you will do WORSE than in single animal mode. + - Quick start: when you `create_new_project` just set the flag `multianimal=True`. -[VIDEO TUTORIAL AVAILABLE!](https://youtu.be/JDsa8R5J0nQ) + - This enables you to use maDLC features even though you have only one animal. To note, this is rarely required for single animal projects, and not the recommended path. + - Some tips for when you might want to use this: + - This is good for e.g. a hand or a mouse if you feel the "skeleton" during training would increase performance. + - Do not do this for things that could be identified as an individual objects. i.e., don't do whisker 1, whisker 2, whisker 3 as 3 individuals. + Each whisker always has a specific spatial location, and by calling them individuals the network will perform worse than in single animal mode. + + - [VIDEO TUTORIAL AVAILABLE!](https://youtu.be/JDsa8R5J0nQ) - **I have multiple *identical-looking animals* in my videos:** - - quick start: when you `create_new_project` set the flag `multianimal=True`. If you can't tell them apart, you can assign the "individual" ID to any animal in each frame. See this [labeling w/2.2 demo video](https://www.youtube.com/watch?v=_qbEqNKApsI) -[VIDEO TUTORIAL AVAILABLE!](https://youtu.be/Kp-stcTm77g) + - Quick start: when you `create_new_project` set the flag `multianimal=True`. + - If you can't tell them apart, you can assign the "individual" ID to any animal in each frame. See this [labeling w/2.2 demo video](https://www.youtube.com/watch?v=_qbEqNKApsI) + - [VIDEO TUTORIAL AVAILABLE!](https://youtu.be/Kp-stcTm77g) - **I have multiple animals, *but I can tell them apart,* in my videos and want to use DLC2.2:** - - quick start: when you `create_new_project` set the flag `multianimal=True`. And always label the "individual" ID name the same; i.e. if you have mouse1 and mouse2 but mouse2 always has a miniscope, in every frame label mouse2 consistently. See this [labeling w/2.2 demo video](https://www.youtube.com/watch?v=_qbEqNKApsI). Then, you MUST put the following in the config.yaml file: `identity: true` -[VIDEO TUTORIAL AVAILABLE!](https://youtu.be/Kp-stcTm77g) - ALSO, if you can tell them apart, label animals them consistently! + - Quick start: when you `create_new_project` set the flag `multianimal=True`. + - Always label the "individual" ID name the same; i.e. if you have mouse1 and mouse2 but mouse2 always has a miniscope, in every frame label mouse2 consistently. See this [labeling w/2.2 demo video](https://www.youtube.com/watch?v=_qbEqNKApsI). + - Then, you MUST put the following in the config.yaml file: `identity: true` + - [VIDEO TUTORIAL AVAILABLE!](https://youtu.be/Kp-stcTm77g) -- **I have a pre-2.2 single animal project, but I want to use 2.2:** +```{important} +If you can tell them apart, label your animals consistently! +``` -Please read [this convert 2 maDLC guide](convert-maDLC) +- **I have a pre-2.2 single animal project, but I want to use 2.2:** + - Please read [the conversion to maDLC guide](convert-maDLC) ### Getting started with multi-animal (ma) DeepLabCut @@ -185,7 +197,8 @@ Please note that GUIs are not easily supported in Jupyter in MacOS, as you need If you are using DeepLabCut on the cloud, you cannot use the GUIs. ```{warning} -On **Windows**: Open the terminal/cmd/anaconda prompt as **Administrator** (right click and select "Run as administrator") to avoid permission issues when downloading models, and for symlink support when videos are not copied into the project folder. +On **Windows**: Open the terminal/cmd/anaconda prompt as **Administrator** (right click and select "Run as administrator") to avoid permission issues during usage when downloading models, and for symlink support when videos are not copied into the project folder. +Admin mode is not required for installation. ``` Simply open the terminal and type: From d1d65359bd994e66bf3f82cea2a1de5bdd6d8f77 Mon Sep 17 00:00:00 2001 From: Cyril Achard Date: Tue, 21 Apr 2026 16:41:17 +0200 Subject: [PATCH 20/53] Convert links to Sphinx refs and tidy docs Replace Markdown inline links with Sphinx {ref} cross-references, standardize admonition/class syntax, and clean up spacing and punctuation throughout docs/installation.md. Also normalize casing for the DeepLabCut heading, adjust image/code block indentation, add a MacOS GPU support footnote, and make minor clarity edits to GPU/PyTorch/TensorFlow installation notes and examples. --- docs/installation.md | 55 +++++++++++++++++++++++++------------------- 1 file changed, 31 insertions(+), 24 deletions(-) diff --git a/docs/installation.md b/docs/installation.md index 8e244d19b9..4026e194ac 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -15,21 +15,20 @@ deeplabcut: # Installing DeepLabCut - **DeepLabCut can be run on Windows, Linux, or MacOS as long as you have Python 3.10-3.12 installed** - - See also [technical considerations](sec:hardware-considerations-during-install) and if you run into issues also check out the [installation tips](https://deeplabcut.github.io/DeepLabCut/docs/recipes/installTips.html). + - See also {ref}`technical considerations ` and if you run into issues also check out the [installation tips](https://deeplabcut.github.io/DeepLabCut/docs/recipes/installTips.html). - 🚧 Please note, there are several possibilities for installation: - **Recommended for most users**: Install in a [**conda environment**](https://deeplabcut.github.io/DeepLabCut/docs/installation.html#conda-the-installation-process-is-as-easy-as-this-figure) - - Install with [**uv**](sec:uv-install) (recommended for developers) - - In the supplied [**Docker container**](docker-containers) (recommended for Ubuntu advanced users and reproducibility). + - Install with **{ref}`uv `** (recommended for developers) + - In the supplied **{ref}`Docker container `** (recommended for Ubuntu advanced users and reproducibility). - 🚀 You will get the best performance when using a **GPU**! - - Please see the section on [GPU support](sec:install-gpu-support) to install your GPU driver and CUDA. + - Please see the section on {ref}`GPU support ` to install your GPU driver and CUDA. ````{hint} Familiar with python packages and conda? This assumes you have `conda`/`mamba` installed and this will install DeepLabCut in a fresh environment. -If you have an NVIDIA GPU, install PyTorch according to [their instructions -](https://pytorch.org/get-started/locally/) (with your desired CUDA version) - you just need your GPU drivers installed. +If you have an NVIDIA GPU, install PyTorch according to [their instructions](https://pytorch.org/get-started/locally/) (with your desired CUDA version) - you just need your GPU drivers installed. ```bash conda create -n DEEPLABCUT python=3.12 @@ -40,7 +39,6 @@ conda activate DEEPLABCUT # GPU version of pytorch for CUDA 11.3 conda install pytorch cudatoolkit=11.3 -c pytorch - # install the latest version of DeepLabCut pip install --pre deeplabcut # or if you want to use the GUI @@ -52,7 +50,7 @@ python -c "import torch; print(torch.cuda.is_available())" ``` ```` -- If you're familiar with the command line and want TensorFlow support, look [below](deeplabcut-with-tf-install) for a fresh installation on Linux and makes it possible to use the GPU with both PyTorch and TensorFlow. +- If you're familiar with the command line and want TensorFlow support, look {ref}`below ` for a fresh installation on Linux and makes it possible to use the GPU with both PyTorch and TensorFlow. ## Using Conda @@ -62,7 +60,7 @@ python -c "import torch; print(torch.cuda.is_available())" ### 🚨 Before you start... -Do you have a GPU? If yes, see the [GPU support section](sec:install-gpu-support) below for installation instructions. +Do you have a GPU? If yes, see the {ref}`GPU support section ` below for installation instructions. If not, you can still install DeepLabCut and use it on your CPU, but it will be much slower for training and evaluation (but not for labeling or project management). @@ -79,7 +77,7 @@ class: dropdown ``` ```{tab-item} NVIDIA GPU If you want to use your own GPU (i.e., a GPU is in your workstation), then you need to be sure you have a CUDA compatible GPU, CUDA, and cuDNN installed. - Please note, which CUDA you install depends on what version of PyTorch you want to use. So, please check [](sec:install-gpu-support) below carefully. **Note, DeepLabCut is up to date with the latest CUDA and PyTorch!** + Please note, which CUDA you install depends on what version of PyTorch you want to use. So, please check {ref}`sec:install-gpu-support` below carefully. **Note, DeepLabCut is up to date with the latest CUDA and PyTorch!** ``` ```{tab-item} Apple M-chip GPU Be sure to install miniconda, and your GPU will be used by default. @@ -87,7 +85,7 @@ class: dropdown ```` - Note, you can also use the CPU-only install for project management and labeling the data! -Then, for example, use Google Colaboratory GPUs for free (read more [here](https://github.com/DeepLabCut/DeepLabCut/tree/master/examples#demo-4-deeplabcut-training-and-analysis-on-google-colaboratory-with-googles-gpus) and there are a lot of helper videos on [our YouTube channel!](https://www.youtube.com/playlist?list=PLjpMSEOb9vRFwwgIkLLN1NmJxFprkO_zi)). + Then, for example, use Google Colaboratory GPUs for free (read more [here](https://github.com/DeepLabCut/DeepLabCut/tree/master/examples#demo-4-deeplabcut-training-and-analysis-on-google-colaboratory-with-googles-gpus) and there are a lot of helper videos on [our YouTube channel!](https://www.youtube.com/playlist?list=PLjpMSEOb9vRFwwgIkLLN1NmJxFprkO_zi)). ````` ### Step 1: Install miniconda @@ -124,12 +122,15 @@ On **Windows**, make sure you have `git` installed: [Git for Windows](https://gi ``` - Follow the link ➡️ for the [conda file](https://github.com/DeepLabCut/DeepLabCut/blob/main/conda-environments/DEEPLABCUT.yaml#:~:text=Raw%20file%20content-,Download,-%E2%8C%98) and then click "..." and select Download + Screen Shot 2023-09-13 at 10 33 32 PM - **Now, in Terminal (or Anaconda Command Prompt for Windows users)**: - If you clicked to download, go to your downloads folder. + - Be sure you are in the folder that has the `.yaml` file, then run: + `conda env create -f DEEPLABCUT.yaml` - You can now use this environment from anywhere on your computer. @@ -209,7 +210,7 @@ Here are some conda environment management tips: [kapeli.com: Conda Cheat Sheet] **Pro Tip:** If you want to modify code and then test it, you can use our provided test scripts. This would mean you need to be up-to-date with the latest GitHub-based code -though! Please see [here](installation-tips) on how to get the latest GitHub code, and +though! Please see {ref}`here ` on how to get the latest GitHub code, and how to test your installation by following [this video](https://www.youtube.com/watch?v=IOWtKn3l33s). ## Other ways to install DeepLabCut @@ -231,9 +232,9 @@ Recommended for users who want to modify the code, or want to be up-to-date with - Run in the cloned repo: ```bash - uv venv -p 3.12 - uv pip install -e .[gui,modelzoo,tf] # Change optional install as needed - source .venv/bin/activate # or & .venv\Scripts\activate.ps1 on Windows +uv venv -p 3.12 +uv pip install -e .[gui,modelzoo,tf] # Change optional install as needed +source .venv/bin/activate # or & .venv\Scriptsctivate.ps1 on Windows ``` ### `pip` @@ -254,7 +255,7 @@ If you already have a local environment, everything you need to use the project ```{tip} -In a fresh ubuntu install, you will often have to run: ``sudo apt-get install gcc python3-dev`` to install the GNU Compiler Collection and the python developing environment. +In a fresh ubuntu install, you will often have to run: `sudo apt-get install gcc python3-dev` to install the GNU Compiler Collection and the python developing environment. ``` Create a new conda environment with Python 3.10 (or 3.11, 3.12) by running: @@ -299,10 +300,9 @@ your specific GPU**, then you can use the supplied conda file. You will need an NVIDIA GPU that is compatible with CUDA. -To see a list of CUDA-enabled NVIDIA GPUs, please [see -their website](https://developer.nvidia.com/cuda-gpus). +To see a list of CUDA-enabled NVIDIA GPUs, please [see their website](https://developer.nvidia.com/cuda-gpus). -Here we provide notes on how to install and check your GPU use with TensorFlow , which is used by DeepLabCut and will be installed with the Anaconda files above. +Here we provide notes on how to install and check your GPU use with TensorFlow, which is used by DeepLabCut and will be installed with the Anaconda files above. Thus, you do not need to independently install tensorflow. 1. Install a driver for your GPU, using the NVIDIA Drivers link above. @@ -314,18 +314,23 @@ Thus, you do not need to independently install tensorflow. - **As of version 3.0+ we moved to PyTorch. The Last supported version of TensorFlow is 2.10 (window users) and 2.12 for others** (We will not be testing beyond this) + - Please be mindful different versions of TensorFlow require different CUDA versions. + - As the combination of TensorFlow and CUDA matters, we strongly encourage you to **check your driver/cuDNN/CUDA/TensorFlow versions** [on this StackOverflow post](https://stackoverflow.com/questions/30820513/what-is-version-of-cuda-for-nvidia-304-125/30820690#30820690). + - To check your GPU is working, in the terminal, run: -`nvcc -V` to check your installed version(s). + `nvcc -V` to check your installed version(s). - The best practice is to then run the supplied `testscript_pytorch_single_animal.py` (or `testscript_tensorflow_single_animal.py` for the TensorFlow engine); this is inside the examples folder you acquired when you git cloned the repo. Here is more information/a short [video on running the test scripts](https://www.youtube.com/watch?v=IOWtKn3l33s). + - You can test that your GPU is being properly used with these additional [tips](https://www.tensorflow.org/programmers_guide/using_gpu). + - Ubuntu users might find this [installation guide](https://deeplabcut.github.io/DeepLabCut/docs/recipes/installTips.html#installation-on-ubuntu-20-04-lts) for a fresh DLC install on Ubuntu useful as well. ## Troubleshooting @@ -337,7 +342,7 @@ Here are some additional resources users have found helpful (posted without endo - https://stackoverflow.com/questions/30820513/what-is-the-correct-version-of-cuda-for-my-nvidia-driver/30820690

- +

- https://www.tensorflow.org/install/source#gpu @@ -350,7 +355,7 @@ Here are some additional resources users have found helpful (posted without endo - A few Windows users report needing to install re-install ffmpeg (after windows updates) as described here: https://video.stackexchange.com/questions/20495/how-do-i-set-up-and-use-ffmpeg-in-windows (A potential error could occur when making new videos). On Ubuntu, the command is: `sudo apt install ffmpeg` -### DEEPLABCUT +### DeepLabCut - If you git clone or download this folder, and are inside of it then `import deeplabcut` will import the package from the local folder rather than from the latest on PyPi! @@ -394,7 +399,7 @@ An environment is a self-contained directory that contains a Python installation - **Software**: - - Operating System: Linux (Ubuntu), MacOS\* (Mojave), or Windows 10. However, we the authors strongly recommend Ubuntu! \*MacOS does not support NVIDIA GPUs (easily), so we only suggest this option for CPU use or a case where the user wants to label data, refine data, etc and then push the project to a cloud resource for GPU computing steps, or use MobileNets. + - Operating System: Linux (Ubuntu), MacOS[^1] (Mojave), or Windows 10. However, we the authors strongly recommend Ubuntu! - DeepLabCut is written in Python 3 (https://www.python.org/) and not compatible with Python 2. ## Additional tips From 1cb8a68b867547721c3589eab48a24d831657a9b Mon Sep 17 00:00:00 2001 From: Cyril Achard Date: Mon, 27 Apr 2026 15:29:33 +0200 Subject: [PATCH 22/53] Fix markdown code blocks and list numbering Adjust formatting in docs/UseOverviewGuide.md: indent fenced code blocks for proper rendering and normalize the ordered list numbering (use '1.' for sequential steps) for consistency in the instructions. --- docs/UseOverviewGuide.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/UseOverviewGuide.md b/docs/UseOverviewGuide.md index 7d967ae285..8f69092330 100644 --- a/docs/UseOverviewGuide.md +++ b/docs/UseOverviewGuide.md @@ -215,17 +215,17 @@ That's it! Follow the GUI for details 1. Start iPython: -```bash -ipython -``` + ```bash + ipython + ``` -2. Import DeepLabCut: +1. Import DeepLabCut: -```python -import deeplabcut -``` + ```python + import deeplabcut + ``` -3. Follow the instructions in the user guides for either standard or multi-animal DeepLabCut (see below). +1. Follow the instructions in the user guides for either standard or multi-animal DeepLabCut (see below). [VIDEO TUTORIAL AVAILABLE!](https://www.youtube.com/watch?v=7xwOhUcIGio) From 9038a0b01cb347a26f62d50f3e825ca416c191c6 Mon Sep 17 00:00:00 2001 From: Cyril Achard Date: Mon, 27 Apr 2026 15:40:07 +0200 Subject: [PATCH 23/53] Remove outdated installation tips links Disable references to the outdated 'installation tips' page in docs/installation.md. Replaced direct links and related guidance with HTML comments, added a note that the git-clone section is the place for editable installs, adjusted the pro-tip wording to point users to the test video, and commented out the 'Additional tips' block. Original content is preserved in comments for review. --- docs/installation.md | 22 ++++++++++++++++------ 1 file changed, 16 insertions(+), 6 deletions(-) diff --git a/docs/installation.md b/docs/installation.md index 0ad89f53b2..65f647ae91 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -15,7 +15,12 @@ deeplabcut: # Installing DeepLabCut - **DeepLabCut can be run on Windows, Linux, or MacOS as long as you have Python 3.10-3.12 installed** - - See also {ref}`technical considerations ` and if you run into issues also check out the [installation tips](https://deeplabcut.github.io/DeepLabCut/docs/recipes/installTips.html). + - See also {ref}`technical considerations `. + + + + + - 🚧 Please note, there are several possibilities for installation: - **Recommended for most users**: Install in a [**conda environment**](https://deeplabcut.github.io/DeepLabCut/docs/installation.html#conda-the-installation-process-is-as-easy-as-this-figure) - Install with **{ref}`uv `** (recommended for developers) @@ -208,10 +213,15 @@ On **Windows**: Open the terminal/cmd/anaconda prompt as **Administrator** (righ Here are some conda environment management tips: [kapeli.com: Conda Cheat Sheet](https://kapeli.com/cheat_sheets/Conda.docset/Contents/Resources/Documents/index) -**Pro Tip:** If you want to modify code and then test it, you can use our provided + + + + +Please see how to test your installation by following [this video](https://www.youtube.com/watch?v=IOWtKn3l33s). + + ## Other ways to install DeepLabCut @@ -413,8 +423,8 @@ An environment is a self-contained directory that contains a Python installation - As noted, is it possible to run DeepLabCut on your CPU, but it will be very slow (see: [Mathis & Warren](https://www.biorxiv.org/content/early/2018/10/30/457242)). However, this is the preferred path if you want to test DeepLabCut on your own computer/data before purchasing a GPU, with the added benefit of a straightforward installation! Otherwise, use our COLAB notebooks for GPU access for testing. - Docker: We highly recommend advanced users use the supplied [Docker container](docker-containers) --> -## Additional tips + [^1]: MacOS does not support NVIDIA GPUs (easily), so we only suggest this option for CPU use or a case where the user wants to label data, refine data, etc, and then push the project to a cloud resource for GPU computing steps, or use MobileNets From 4e27d0462742da5ccb4ab11090b3610c1506ae44 Mon Sep 17 00:00:00 2001 From: Cyril Achard Date: Tue, 5 May 2026 14:04:21 +0200 Subject: [PATCH 24/53] Update PROJECT_GUI.md --- docs/gui/PROJECT_GUI.md | 23 +++++++++++------------ 1 file changed, 11 insertions(+), 12 deletions(-) diff --git a/docs/gui/PROJECT_GUI.md b/docs/gui/PROJECT_GUI.md index 139d200e08..f94378ba23 100644 --- a/docs/gui/PROJECT_GUI.md +++ b/docs/gui/PROJECT_GUI.md @@ -6,25 +6,21 @@ deeplabcut: visibility: online status: review_needed recommendation: update - notes: "While the content is generally accurate, repeating installation instructions is not ideal. I would suggest linking to the installation guide instead of re-suggesting commmands but then still saying to read the install page... Also, the GUI is likely used by the majority of users, so I would even consider making this a full section in the TOC, and maybe even having one file per GUI tab, which would make tracking code/docs sync easier. Addendum: it seems the beginner guide section is more of a GUI step-by-step, as mentioned earlier in this comment. I would suggest merging/moving and adding links in the present doc, which would make it less of a video list and more of a proper GUI guide." + notes: 'While the content is generally accurate, repeating installation instructions is not ideal. I would suggest linking to the installation guide instead of re-suggesting commmands but then still saying to read the install page... Also, the GUI is likely used by the majority of users, so I would even consider making this a full section in the TOC, and maybe even having one file per GUI tab, which would make tracking code/docs sync easier. Addendum: it seems the beginner guide section is more of a GUI step-by-step, as mentioned earlier in this comment. I would suggest merging/moving and adding links in the present doc, which would make it less of a video list and more of a proper GUI guide.' --- + (project-manager-gui)= + # Interactive Project Manager GUI -As some users may be more comfortable working with an interactive interface, we wanted to provide an easy-entry point to the software. All the main functionality is available in an easy-to-deploy GUI interface. Thus, while the many advanced features are not fully available in this Project GUI, we hope this gets more users up-and-running quickly. +As some users may be more comfortable working with an interactive interface, we wanted to provide an easy-entry point to the software. All the main functionality is available in an easy-to-deploy GUI interface. Thus, while the many advanced features are not fully available in this Project GUI, we hope this gets more users up-and-running quickly. **Release notes:** As of DeepLabCut 2.1+ now provide a full front-end user experience for DeepLabCut, and as of 2.3+ we changed the GUI from wxPython to PySide6 with napari support. ## Get Started: -(1) Install DeepLabCut using the simple-install with Anaconda found [here!](how-to-install)*. -Now you have DeepLabCut installed, but if you want to update it, either follow the prompt in the GUI which will ask you to upgrade when a new version is available, or just go into your env (activate DEEPLABCUT) then run: - -` pip install 'deeplabcut[gui,modelzoo]'` *but please see [full install guide](how-to-install)! - - -(2) Open the terminal and run: `python -m deeplabcut` - +1. Install DeepLabCut following the instructions in the {ref}`installation page`. +1. Open the terminal and run: `python -m deeplabcut`

@@ -35,12 +31,15 @@ We recommend to keep the terminal visible (as well as the GUI) so you can see th - For specific napari-based labeling features, see the ["napari gui" docs](napari-gui-usage). - To change from dark to light mode, set appearance at the top: +

-## Video Demos: How to launch and run the Project Manager GUI: +## Video Demo + +### How to launch and run the Project Manager GUI **Click on the images!** @@ -60,6 +59,6 @@ Note that currently the video demo is the wxPython version, but the logic is the [Read more here](important-info-regd-usage) -## VIDEO DEMO: How to benchmark your data with the new networks and data augmentation pipelines: +### How to benchmark your data with the new networks and data augmentation pipelines: [Watch the video](https://youtu.be/WXCVr6xAcCA) From c9cf9f2941e7357e6c66e33f1452b03093103b94 Mon Sep 17 00:00:00 2001 From: Cyril Achard Date: Tue, 5 May 2026 16:56:33 +0200 Subject: [PATCH 25/53] Clarify Project GUI wording in docs Make minor copy edits to docs/gui/PROJECT_GUI.md for clarity: change "easy-entry point" to "easy entry point", replace "easy-to-deploy GUI interface" with "easy-to-use GUI interface", and rephrase the following sentence to more clearly state that several advanced features are not available in the Project GUI. --- docs/gui/PROJECT_GUI.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/gui/PROJECT_GUI.md b/docs/gui/PROJECT_GUI.md index f94378ba23..99659b07f9 100644 --- a/docs/gui/PROJECT_GUI.md +++ b/docs/gui/PROJECT_GUI.md @@ -13,7 +13,8 @@ deeplabcut: # Interactive Project Manager GUI -As some users may be more comfortable working with an interactive interface, we wanted to provide an easy-entry point to the software. All the main functionality is available in an easy-to-deploy GUI interface. Thus, while the many advanced features are not fully available in this Project GUI, we hope this gets more users up-and-running quickly. +As some users may be more comfortable working with an interactive interface, we wanted to provide an easy entry point to the software. All the main functionality is available in an easy-to-use GUI interface. +While several advanced features are not fully available in this Project GUI, we hope this gets more users up-and-running quickly. **Release notes:** As of DeepLabCut 2.1+ now provide a full front-end user experience for DeepLabCut, and as of 2.3+ we changed the GUI from wxPython to PySide6 with napari support. From f2b7df2de216c68c1659e4137cadd90a64a5f3e8 Mon Sep 17 00:00:00 2001 From: Cyril Achard Date: Tue, 5 May 2026 17:02:27 +0200 Subject: [PATCH 26/53] Update beginner guide ref --- docs/UseOverviewGuide.md | 4 +- docs/beginner-guides/beginners-guide.md | 45 +++++++++---- docs/course.md | 88 ++++++++++++------------- 3 files changed, 79 insertions(+), 58 deletions(-) diff --git a/docs/UseOverviewGuide.md b/docs/UseOverviewGuide.md index 8f69092330..b6879d49aa 100644 --- a/docs/UseOverviewGuide.md +++ b/docs/UseOverviewGuide.md @@ -12,7 +12,7 @@ deeplabcut: Below we will first outline what you need to get started, the different ways you can use DeepLabCut, and then the full workflow. Note, we highly recommend you also read and follow our [Nature Protocols paper](https://www.nature.com/articles/s41596-019-0176-0), which is (still) fully relevant to standard DeepLabCut. ```{hint} -💡📚 If you are new to Python and DeepLabCut, you might consider checking our [beginner guide](https://deeplabcut.github.io/DeepLabCut/docs/beginner-guides/beginners-guide.html) once you are ready to jump into using the DeepLabCut App! +💡📚 If you are new to Python and DeepLabCut, you might consider checking our [beginner guide](file:beginners-guide) once you are ready to jump into using the DeepLabCut App! ``` ## Introduction @@ -68,7 +68,7 @@ We are primarily a package that enables deep learning-based pose estimation. We - [Explanations:](https://github.com/DeepLabCut/DeepLabCut-Workshop-Materials) resources on understanding how DeepLabCut works - [References:](https://github.com/DeepLabCut/DeepLabCut#references) read the science behind DeepLabCut -- [Beginner Guide to the GUI](https://deeplabcut.github.io/DeepLabCut/docs/beginner-guides/beginners-guide.html) +- \[Beginner Guide to the GUI\](file:beginners-guide) diff --git a/docs/beginner-guides/beginners-guide.md b/docs/beginner-guides/beginners-guide.md index a4df28db50..041a0b090e 100644 --- a/docs/beginner-guides/beginners-guide.md +++ b/docs/beginner-guides/beginners-guide.md @@ -6,10 +6,13 @@ deeplabcut: visibility: online status: outdated recommendation: update - notes: "While it could seem like a useful page for beginners, duplicating installation instructions is not ideal for maintenance. This is also mixing installation/setup with a GUI guide, which should be in its own section/page. This puts into question the reason of existence of this page, as it would end up being two links to different sections. I would rather have well-made, accurate installation and GUI guides, and if there are beginner-relevant information that really cannot fit into those, then we can have a 'beginner's guide' that links to those and has the extra info. I would suggest reviewing whether this style of docs should remain at all, but if we want to keep them revising the approach may be needed." + notes: While it could seem like a useful page for beginners, duplicating installation instructions is not ideal for maintenance. This is also mixing installation/setup with a GUI guide, which should be in its own section/page. This puts into question the reason of existence of this page, as it would end up being two links to different sections. I would rather have well-made, accurate installation and GUI guides, and if there are beginner-relevant information that really cannot fit into those, then we can have a 'beginner's guide' that links to those and has the extra info. I would suggest reviewing whether this style of docs should remain at all, but if we want to keep them revising the approach may be needed. --- -(beginners-guide)= + +(file:beginners-guide)= + # Using DeepLabCut + DLC LIVE! This guide, and related pages, are meant as a very-new-to-python beginner guide to DeepLabCut. After you are comfortable with this material we recommend then jumping into the more detailed User Guides! @@ -23,6 +26,7 @@ Before you begin, make sure that DeepLabCut is installed on your system. - **ProTip:** For detailed installation instructions, geared towards a bit more advanced users, refer to the [Full Installation Guide](https://deeplabcut.github.io/DeepLabCut/docs/installation.html). ## Beginner User Guide + If you are new to Python, the best way to get Python installed onto your computer is with Anaconda. [Head over here and download the version that is best for your computer](https://www.anaconda.com/download). - "Conda", as it's often called, it a very nice way to create "environments (env)" on your computer. While there can be some cross-talk, in general, it allows you to separate the different tools you need to use to get your science done 💪. @@ -38,11 +42,13 @@ In the terminal, type: ``` conda create -n deeplabcut python=3.10 ``` + You will be prompted (y/n) to install, and then wait for the magic to happen. At the end, check the terminal, it should prompt you to then type: ``` conda activate deeplabcut ``` + Now, we are going to install the core dependencies. The way this works is that there are "package managers" such as `conda` itself and python's `pip`. We are going to deploy a mix based on what we know works across ooperating systems. **(1) Install PyTorch** @@ -50,10 +56,13 @@ Now, we are going to install the core dependencies. The way this works is that t `PyTorch` is the backend deep-learning language we wrote DLC3 in. To select the right version, head to the ["Install PyTorch"](https://pytorch.org/get-started/locally/) instructions in the official PyTorch Docs. Select your desired PyTorch build, operating system, select conda as your package manager and Python as the language. Select your compute platform (either a CUDA version or CPU only). Then, use the command to install the PyTorch package. Below are a few possible examples: - **GPU version of pytorch for CUDA 12.4** + ``` pip install torch torchvision --index-url https://download.pytorch.org/whl/cu124 ``` + - **CPU only version of pytorch, using the latest version** + ``` pip install torch torchvision --index-url https://download.pytorch.org/whl/cpu ``` @@ -63,12 +72,15 @@ pip install torch torchvision --index-url https://download.pytorch.org/whl/cpu Alright! Next, we will install all the `deeplabcut` source code 🔥. Please decide which version you want (stable or alpha), then type: - For the **Stable release:** + ``` pip install "deeplabcut[gui,modelzoo,wandb]" ``` + - This gives you DeepLabCut, the DLC GUI (gui), our latest neural networks (modelzoo) and a cool data logger (wandb) if you choose to use it later on! - OR for the **Alpha release (from GitHub bleeding edge of the code):** + ``` pip install "git+https://github.com/DeepLabCut/DeepLabCut.git@pytorch_dlc#egg=deeplabcut[gui,modelzoo,wandb]" ``` @@ -76,9 +88,11 @@ pip install "git+https://github.com/DeepLabCut/DeepLabCut.git@pytorch_dlc#egg=de ## Starting DeepLabCut In the terminal, enter: + ```bash python -m deeplabcut ``` + This will open the DeepLabCut App (note, the default is dark mode, but you can click "appearance" to change: ![DeepLabCut GUI Screenshot](https://images.squarespace-cdn.com/content/v1/57f6d51c9f74566f55ecf271/1717779625875-5UHPC367I293CBSP8CT6/GUI-screenshot.png?format=500w) @@ -92,8 +106,8 @@ This will open the DeepLabCut App (note, the default is dark mode, but you can c When you first launch the GUI, you'll find three primary main options: 1. **Create New Project:** Geared towards new initiatives. A good choice if you're here to start something new. -2. **Load Project:** Use this to resume your on-hold or past work. -3. **Model Zoo:** Best suited for those who want to explore Model Zoo. +1. **Load Project:** Use this to resume your on-hold or past work. +1. **Model Zoo:** Best suited for those who want to explore Model Zoo. ### Commencing Your Work: @@ -105,38 +119,47 @@ When you first launch the GUI, you'll find three primary main options: - When you start a new project, you'll be presented with an empty project window. In DLC3+ you will see a new option "Engine". - We recommend using the PyTorch Engine: - ![DeepLabCut Engine](https://images.squarespace-cdn.com/content/v1/57f6d51c9f74566f55ecf271/1717780414978-17LOVBUJ8JR102QVSFDY/Screen+Shot+2024-06-07+at+7.13.14+PM.png?format=1500w)) +![DeepLabCut Engine](https://images.squarespace-cdn.com/content/v1/57f6d51c9f74566f55ecf271/1717780414978-17LOVBUJ8JR102QVSFDY/Screen+Shot+2024-06-07+at+7.13.14+PM.png?format=1500w)) 2. **Filling in Project Details:** + - **Naming Your Project:** + - Give a specific, well-defined name to your project. - > **💡 Tip:** Avoid empty spaces in your project name. + > **💡 Tip:** Avoid empty spaces in your project name. - **Naming the Experimenter:** + - Fill in the name of the experimenter. This part of the data remains immutable. -3. **Determine Project Location:** +1. **Determine Project Location:** + - By default, your project will be located on the **Desktop**. - To pick a different home, modify the path as needed. -4. **Multi-Animal or Single-Animal Project:** +1. **Multi-Animal or Single-Animal Project:** + - Tick the 'Multi-Animal' option in the menu, but only if that's the mode of the project. - Choose the 'Number of Cameras' as per your experiment. -5. **Adding Videos:** +1. **Adding Videos:** + - First, click on **`Browse Videos`** button on the right side of the window, to search for the video contents. + - Once the media selection tool opens, navigate and select the folder with your videos. > **💡 Tip:** DeepLabCut supports **`.mp4`**, **`.avi`**, **`.mkv`** and **`.mov`** files. + - A list will be created with all the videos inside this folder. + - Unselect the videos you wish to remove from the project. -6. **Create your project:** +1. **Create your project:** + - Click on **`Create`** button on the bottom, right side of the main window. - A new folder named after your project's name will be created in the location you chose above. - ### 📽 Video Tutorial: Setting Up Your Project in DeepLabCut ![DeepLabCut Create Project GIF](https://images.squarespace-cdn.com/content/v1/57f6d51c9f74566f55ecf271/1717779616437-30U5RFYV0OY6ACGDG7F4/create-project.gif?format=500w) diff --git a/docs/course.md b/docs/course.md index a47610c787..94d4c24d0f 100644 --- a/docs/course.md +++ b/docs/course.md @@ -7,16 +7,17 @@ deeplabcut: status: outdated recommendation: archive --- + # DeepLabCut Self-paced Course -::::{warning} +::::\{warning} This course was designed for DLC 2. An updated version for DLC 3 is in the works. :::: Do you have video of animal behaviors? Step 1: Get Poses ... - DLC LIVE! +DLC LIVE! This document is an outline of resources for a course for those wanting to learn to use `Python` and `DeepLabCut`. We expect it to take *roughly* 1-2 weeks to get through if you do it rigorously. To get the basics, it should take 1-2 days. @@ -27,14 +28,13 @@ We expect it to take *roughly* 1-2 weeks to get through if you do it rigorously.

- ## Installation: You need Python and DeepLabCut installed! -- [See these "beginner docs" for help!](beginners-guide) -- **WATCH:** overview of conda: [Python Tutorial: Anaconda - Installation and Using Conda](https://www.youtube.com/watch?v=YJC6ldI3hWk) +- \[See these "beginner docs" for help!\](file:beginners-guide) +- **WATCH:** overview of conda: [Python Tutorial: Anaconda - Installation and Using Conda](https://www.youtube.com/watch?v=YJC6ldI3hWk) ## Outline: @@ -47,93 +47,91 @@ You need Python and DeepLabCut installed! - **Learning:** learning and teaching signal processing, and overview from Prof. Demba Ba [talk at JupyterCon](https://www.youtube.com/watch?v=ywz-LLYwkQQ) - **DEMO:** Can I DEMO DEEPLABCUT (DLC) quickly? - - Yes: [you can click through this DEMO notebook](https://github.com/DeepLabCut/DeepLabCut/blob/main/examples/COLAB/COLAB_DEMO_mouse_openfield.ipynb) - - AND follow along with me: [Video Tutorial!](https://www.youtube.com/watch?v=DRT-Cq2vdWs) + - Yes: [you can click through this DEMO notebook](https://github.com/DeepLabCut/DeepLabCut/blob/main/examples/COLAB/COLAB_DEMO_mouse_openfield.ipynb) + - AND follow along with me: [Video Tutorial!](https://www.youtube.com/watch?v=DRT-Cq2vdWs) - **WATCH:** How do you know DLC is installed properly? (i.e. how to use our test script!) [Video Tutorial!](https://youtu.be/IOWtKn3l33s) - review! - **REVIEW PAPER:** The state of animal pose estimation w/ deep learning i.e. "Deep learning tools for the measurement of animal behavior in neuroscience" [arXiv](https://arxiv.org/abs/1909.13868) & [published version](https://www.sciencedirect.com/science/article/pii/S0959438819301151) - **REVIEW PAPER:** [A Primer on Motion Capture with Deep Learning: Principles, Pitfalls and Perspectives](https://www.sciencedirect.com/science/article/pii/S0896627320307170) - - **WATCH:** There are a lot of docs... where to begin: [Video Tutorial!](https://www.youtube.com/watch?v=A9qZidI7tL8) ### **Module 1: getting started on data** **What you need:** any videos where you can see the animals/objects, etc. You can use our demo videos, grab some from the internet, or use whatever older data you have. Any camera, color/monochrome, etc will work. Find diverse videos, and label what you want to track well :) -- IF YOU ARE PART OF THE COURSE: you will be contributing to the DLC Model Zoo 😊 - - **Slides:** [Overview of starting new projects](https://github.com/DeepLabCut/DeepLabCut-Workshop-Materials/blob/main/part1-labeling.pdf) - - **READ ME PLEASE:** [DeepLabCut, the science](https://rdcu.be/4Rep) - - **READ ME PLEASE:** [DeepLabCut, the user guide](https://rdcu.be/bHpHN) - - **WATCH:** Video tutorial 1: [using the Project Manager GUI](https://www.youtube.com/watch?v=KcXogR-p5Ak) - - Please go from project creation (use >1 video!) to labeling your data, and then check the labels! - - **WATCH:** Video tutorial 2: [using the Project Manager GUI for multi-animal pose estimation](https://www.youtube.com/watch?v=Kp-stcTm77g) - - Please go from project creation (use >1 video!) to labeling your data, and then check the labels! - - **WATCH:** Video tutorial 3: [using ipython/pythonw (more functions!)](https://www.youtube.com/watch?v=7xwOhUcIGio) - - multi-animal DLC: [labeling](https://www.youtube.com/watch?v=Kp-stcTm77g) - - Please go from project creation (use >1 video!) to labeling your data, and then check the labels! +- IF YOU ARE PART OF THE COURSE: you will be contributing to the DLC Model Zoo 😊 + - **Slides:** [Overview of starting new projects](https://github.com/DeepLabCut/DeepLabCut-Workshop-Materials/blob/main/part1-labeling.pdf) + - **READ ME PLEASE:** [DeepLabCut, the science](https://rdcu.be/4Rep) + - **READ ME PLEASE:** [DeepLabCut, the user guide](https://rdcu.be/bHpHN) + - **WATCH:** Video tutorial 1: [using the Project Manager GUI](https://www.youtube.com/watch?v=KcXogR-p5Ak) + - Please go from project creation (use >1 video!) to labeling your data, and then check the labels! + - **WATCH:** Video tutorial 2: [using the Project Manager GUI for multi-animal pose estimation](https://www.youtube.com/watch?v=Kp-stcTm77g) + - Please go from project creation (use >1 video!) to labeling your data, and then check the labels! + - **WATCH:** Video tutorial 3: [using ipython/pythonw (more functions!)](https://www.youtube.com/watch?v=7xwOhUcIGio) + - multi-animal DLC: [labeling](https://www.youtube.com/watch?v=Kp-stcTm77g) + - Please go from project creation (use >1 video!) to labeling your data, and then check the labels! ### **Module 2: Neural Networks** - - **Slides:** [Overview of creating training and test data, and training networks](https://github.com/DeepLabCut/DeepLabCut-Workshop-Materials/blob/main/part2-network.pdf) - - **READ ME PLEASE:** [What are convolutional neural networks?](https://towardsdatascience.com/a-comprehensive-guide-to-convolutional-neural-networks-the-eli5-way-3bd2b1164a53) +- **Slides:** [Overview of creating training and test data, and training networks](https://github.com/DeepLabCut/DeepLabCut-Workshop-Materials/blob/main/part2-network.pdf) + +- **READ ME PLEASE:** [What are convolutional neural networks?](https://towardsdatascience.com/a-comprehensive-guide-to-convolutional-neural-networks-the-eli5-way-3bd2b1164a53) - - **READ ME PLEASE:** Here is a new paper from us describing challenges in robust pose estimation, why PRE-TRAINING really matters - which was our major scientific contribution to low-data input pose-estimation - and it describes new networks that are available to you. [Pretraining boosts out-of-domain robustness for pose estimation](https://paperswithcode.com/paper/pretraining-boosts-out-of-domain-robustness) +- **READ ME PLEASE:** Here is a new paper from us describing challenges in robust pose estimation, why PRE-TRAINING really matters - which was our major scientific contribution to low-data input pose-estimation - and it describes new networks that are available to you. [Pretraining boosts out-of-domain robustness for pose estimation](https://paperswithcode.com/paper/pretraining-boosts-out-of-domain-robustness) - - **MORE DETAILS:** ImageNet: check out the original paper and dataset: http://www.image-net.org/ + - **MORE DETAILS:** ImageNet: check out the original paper and dataset: http://www.image-net.org/ - - **REVIEW PAPER:** [A Primer on Motion Capture with Deep Learning: Principles, Pitfalls and Perspectives](https://www.sciencedirect.com/science/article/pii/S0896627320307170) +- **REVIEW PAPER:** [A Primer on Motion Capture with Deep Learning: Principles, Pitfalls and Perspectives](https://www.sciencedirect.com/science/article/pii/S0896627320307170) +review! - review! +Before you create a training/test set, please read/watch: - Before you create a training/test set, please read/watch: - - **More information:** [Which types neural networks are available, and what should I use?](https://github.com/DeepLabCut/DeepLabCut/wiki/What-neural-network-should-I-use%3F-(Trade-offs,-speed-performance,-and-considerations)) - - **WATCH:** Video tutorial 1: [How to test different networks in a controlled way](https://www.youtube.com/watch?v=WXCVr6xAcCA) - - Now, decide what model(s) you want to test. - - IF you want to train on your CPU, then run the step `create_training_dataset`, in the GUI etc. on your own computer. - - IF you want to use GPUs on google colab, [**(1)** watch this FIRST/follow along here!](https://www.youtube.com/watch?v=qJGs8nxx80A) **(2)** move your whole project folder to Google Drive, and then [**use this notebook**](https://github.com/DeepLabCut/DeepLabCut/blob/main/examples/COLAB/COLAB_YOURDATA_TrainNetwork_VideoAnalysis.ipynb) +- **More information:** [Which types neural networks are available, and what should I use?]() +- **WATCH:** Video tutorial 1: [How to test different networks in a controlled way](https://www.youtube.com/watch?v=WXCVr6xAcCA) + - Now, decide what model(s) you want to test. - **MODULE 2 webinar**: https://youtu.be/ILsuC4icBU0 + - IF you want to train on your CPU, then run the step `create_training_dataset`, in the GUI etc. on your own computer. + - IF you want to use GPUs on google colab, [**(1)** watch this FIRST/follow along here!](https://www.youtube.com/watch?v=qJGs8nxx80A) **(2)** move your whole project folder to Google Drive, and then [**use this notebook**](https://github.com/DeepLabCut/DeepLabCut/blob/main/examples/COLAB/COLAB_YOURDATA_TrainNetwork_VideoAnalysis.ipynb) + **MODULE 2 webinar**: https://youtu.be/ILsuC4icBU0 ### **Module 3: Evaluation of network performance** - - **Slides** [Evaluate your network](https://github.com/DeepLabCut/DeepLabCut-Workshop-Materials/blob/master/part3-analysis.pdf) - - **WATCH:** [Evaluate the network in ipython](https://www.youtube.com/watch?v=bgfnz1wtlpo) - - why evaluation matters; how to benchmark; analyzing a video and using scoremaps, conf. readouts, etc. +- **Slides** [Evaluate your network](https://github.com/DeepLabCut/DeepLabCut-Workshop-Materials/blob/master/part3-analysis.pdf) +- **WATCH:** [Evaluate the network in ipython](https://www.youtube.com/watch?v=bgfnz1wtlpo) + - why evaluation matters; how to benchmark; analyzing a video and using scoremaps, conf. readouts, etc. ### **Module 4: Scaling your analysis to many new videos** Once you have good networks, you can deploy them. You can create "cron jobs" to run a timed analysis script, for example. We run this daily on new videos collected in the lab. Check out a simple script to get started, and read more below: - - [Analyzing videos in batches, over many folders, setting up automated data processing](https://github.com/DeepLabCut/DLCutils/tree/master/SCALE_YOUR_ANALYSIS) +- [Analyzing videos in batches, over many folders, setting up automated data processing](https://github.com/DeepLabCut/DLCutils/tree/master/SCALE_YOUR_ANALYSIS) - - How to automate your analysis in the lab: [datajoint.io](https://datajoint.io), Cron Jobs: [schedule your code runs](https://www.ostechnix.com/a-beginners-guide-to-cron-jobs/) +- How to automate your analysis in the lab: [datajoint.io](https://datajoint.io), Cron Jobs: [schedule your code runs](https://www.ostechnix.com/a-beginners-guide-to-cron-jobs/) ### **Module 5: Got Poses? Now what ...** Pose estimation took away the painful part of digitizing your data, but now what? There is a rich set of tools out there to help you create your own custom analysis, or use others (and edit them to your needs). Check out more below: - - [Helper code and packages for use on DLC outputs](https://github.com/DeepLabCut/DLCutils) +- [Helper code and packages for use on DLC outputs](https://github.com/DeepLabCut/DLCutils) - - Create your own machine learning classifiers: https://scikit-learn.org/stable/ +- Create your own machine learning classifiers: https://scikit-learn.org/stable/ - - **REVIEW PAPER:** [Toward a Science of Computational Ethology](https://www.sciencedirect.com/science/article/pii/S0896627314007934) +- **REVIEW PAPER:** [Toward a Science of Computational Ethology](https://www.sciencedirect.com/science/article/pii/S0896627314007934) - - **REVIEW PAPER:** The state of animal pose estimation w/ deep learning i.e. "Deep learning tools for the measurement of animal behavior in neuroscience" [arXiv](https://arxiv.org/abs/1909.13868) & [published version](https://www.sciencedirect.com/science/article/pii/S0959438819301151) - - - **REVIEW PAPER:** [Big behavior: challenges and opportunities in a new era of deep behavior profiling](https://www.nature.com/articles/s41386-020-0751-7) +- **REVIEW PAPER:** The state of animal pose estimation w/ deep learning i.e. "Deep learning tools for the measurement of animal behavior in neuroscience" [arXiv](https://arxiv.org/abs/1909.13868) & [published version](https://www.sciencedirect.com/science/article/pii/S0959438819301151) - - **READ**: [Automated measurement of mouse social behaviors using depth sensing, video tracking, and machine learning](https://www.pnas.org/content/112/38/E5351) +- **REVIEW PAPER:** [Big behavior: challenges and opportunities in a new era of deep behavior profiling](https://www.nature.com/articles/s41386-020-0751-7) +- **READ**: [Automated measurement of mouse social behaviors using depth sensing, video tracking, and machine learning](https://www.pnas.org/content/112/38/E5351) *compiled and edited by Mackenzie Mathis* From 8132c692b98d27de095b8b74f98972e082ded9b4 Mon Sep 17 00:00:00 2001 From: Cyril Achard Date: Tue, 5 May 2026 17:59:01 +0200 Subject: [PATCH 27/53] Revise Beginner Guide to focus on GUI Refactor beginners-guide.md to center the guide on the DeepLabCut GUI. Updated the main heading and clarified startup wording (python -m deeplabcut) and project-creation workflow. Removed/replaced redundant installation text with a reference to the installation page and commented out an outdated course link. Added notes recommending the PyTorch engine, improved tips for video selection/copying, added guidance for defining bodyparts and multiple individuals, included a video tutorial GIF, and updated the next-steps reference to the GUI-specific manage-project page. Miscellaneous wording and screenshot tweaks for clarity. --- docs/beginner-guides/beginners-guide.md | 89 ++++++++++++++++--------- 1 file changed, 59 insertions(+), 30 deletions(-) diff --git a/docs/beginner-guides/beginners-guide.md b/docs/beginner-guides/beginners-guide.md index 041a0b090e..1a9798be72 100644 --- a/docs/beginner-guides/beginners-guide.md +++ b/docs/beginner-guides/beginners-guide.md @@ -11,20 +11,25 @@ deeplabcut: (file:beginners-guide)= -# Using DeepLabCut +# Using the DeepLabCut GUI DLC LIVE! This guide, and related pages, are meant as a very-new-to-python beginner guide to DeepLabCut. After you are comfortable with this material we recommend then jumping into the more detailed User Guides! -- **ProTip:** For even more 'in-depth' understanding, head over to check out the [DeepLabCut Course](https://deeplabcut.github.io/DeepLabCut/docs/course.html), which provides a deeper dive into the science behind DeepLabCut. + + + ## Installation Before you begin, make sure that DeepLabCut is installed on your system. -- **ProTip:** For detailed installation instructions, geared towards a bit more advanced users, refer to the [Full Installation Guide](https://deeplabcut.github.io/DeepLabCut/docs/installation.html). +Please see the {ref}`installation page` for detailed instructions on how to install DeepLabCut on your computer. + + + -## Starting DeepLabCut +## Starting the DeepLabCut GUI -In the terminal, enter: +In the terminal, type: ```bash python -m deeplabcut ``` -This will open the DeepLabCut App (note, the default is dark mode, but you can click "appearance" to change: +This will open DeepLabCut. + + ![DeepLabCut GUI Screenshot](https://images.squarespace-cdn.com/content/v1/57f6d51c9f74566f55ecf271/1717779625875-5UHPC367I293CBSP8CT6/GUI-screenshot.png?format=500w) > 💡 **Note:** For a visual guide on navigating through the DeepLabCut GUI, check out our [YouTube tutorial](https://www.youtube.com/watch?v=tr3npnXWoD4). -## Starting a New Project +## Starting a new project -### Navigating the GUI on Initial Launch +### Navigating the GUI on initial Launch When you first launch the GUI, you'll find three primary main options: @@ -109,59 +116,81 @@ When you first launch the GUI, you'll find three primary main options: 1. **Load Project:** Use this to resume your on-hold or past work. 1. **Model Zoo:** Best suited for those who want to explore Model Zoo. -### Commencing Your Work: + -- For a first-time or new user, please click on **`Start New Project`**. + -## 🐾 Steps to Start a New Project +### 🐾 New project step-by-step 1. **Launch New Project:** - When you start a new project, you'll be presented with an empty project window. In DLC3+ you will see a new option "Engine". - - We recommend using the PyTorch Engine: -![DeepLabCut Engine](https://images.squarespace-cdn.com/content/v1/57f6d51c9f74566f55ecf271/1717780414978-17LOVBUJ8JR102QVSFDY/Screen+Shot+2024-06-07+at+7.13.14+PM.png?format=1500w)) +![DeepLabCut Engine](https://images.squarespace-cdn.com/content/v1/57f6d51c9f74566f55ecf271/1717780414978-17LOVBUJ8JR102QVSFDY/Screen+Shot+2024-06-07+at+7.13.14+PM.png?format=1500w) -2. **Filling in Project Details:** +```{note} +For most users, the engine will be PyTorch. See {ref}`sec:deeplabcut-with-tf-install` for TensorFlow support. +``` - - **Naming Your Project:** +1. **Filling in Project Details:** - - Give a specific, well-defined name to your project. + - **Naming Your Project:** - > **💡 Tip:** Avoid empty spaces in your project name. + - Give a specific, easy-to-track name to your project. - - **Naming the Experimenter:** + ```{tip} + Avoid empty spaces in your project name. + ``` - - Fill in the name of the experimenter. This part of the data remains immutable. + - Fill in the name of the experimenter. This will be the permanent name associated with the project. 1. **Determine Project Location:** - By default, your project will be located on the **Desktop**. - - To pick a different home, modify the path as needed. + - To pick a different location, browse as needed. 1. **Multi-Animal or Single-Animal Project:** - - Tick the 'Multi-Animal' option in the menu, but only if that's the mode of the project. + - Tick the 'Multi-Animal' option in the menuif relevant to your experiment. - Choose the 'Number of Cameras' as per your experiment. 1. **Adding Videos:** - First, click on **`Browse Videos`** button on the right side of the window, to search for the video contents. - - Once the media selection tool opens, navigate and select the folder with your videos. - - > **💡 Tip:** DeepLabCut supports **`.mp4`**, **`.avi`**, **`.mkv`** and **`.mov`** files. - + ```{tip} + DeepLabCut supports **`.mp4`**, **`.avi`**, **`.mkv`** and **`.mov`** files. + ``` - A list will be created with all the videos inside this folder. - - Unselect the videos you wish to remove from the project. + - Videos can be automatically copied to the project folder by selecting the "Copy videos to project folder" option. This is recommended for data management and to avoid issues with moving files later on, but depends on your storage system and needs. + - ```{tip} + By default, the GUI will look for **folders of videos**. Use the "Select individual files" + checkbox if you want to select individual videos instead of a whole folder. + ``` + +1. **Define bodyparts and individuals:** + + - Enter all the name, numbers or IDs of bodyparts you wish to track. + - Example: "head", "tail", "left paw", "right paw", etc. + - Less recommened: "L1", "L2", "L3", etc. + - **If you have multiple animals**: + - Enter the name, numbers or IDs of the individuals in your experiment. + - Example: "mouse1", "mouse2", "mouse3", etc. + - **Unique bodyparts**: If you wish to track "landmark" locations, such as the edges of a maze, or a specific object, you can add these as "unique bodyparts". These are not considered part of an individual, but are still tracked as part of the project. + - Example: "maze_left_edge", "maze_right_edge", "reward_port", etc. + - **Identity labeling**: if and only if you can tell individuals apart by their appearance (not their location), set this to Yes and consistently label your individuals in the same way across videos. This will allow DeepLabCut to learn to tell them apart, and assign consistent identities across frames and videos. 1. **Create your project:** - - Click on **`Create`** button on the bottom, right side of the main window. - - A new folder named after your project's name will be created in the location you chose above. + - Click on the **`Create`** button on the bottom, right side of the main window. + - A new folder will be created in the location you chose above. + +## Video tutorial ### 📽 Video Tutorial: Setting Up Your Project in DeepLabCut ![DeepLabCut Create Project GIF](https://images.squarespace-cdn.com/content/v1/57f6d51c9f74566f55ecf271/1717779616437-30U5RFYV0OY6ACGDG7F4/create-project.gif?format=500w) -## Next, head over to the beginner guide for [Setting up what keypoints to track](https://deeplabcut.github.io/DeepLabCut/docs/beginner-guides/manage-project.html) +## Next steps + +Next, head over to the beginner guide for {ref}`Setting up what keypoints to track `, which will show you how to edit the configuration file to edit your bodyparts and skeleton structure. From 40dba920d3be4b7a773701e36d6f7721362e83d4 Mon Sep 17 00:00:00 2001 From: Cyril Achard Date: Tue, 5 May 2026 17:59:17 +0200 Subject: [PATCH 28/53] Update install link ref --- docs/installation.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/docs/installation.md b/docs/installation.md index 65f647ae91..d0403bd36a 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -10,6 +10,7 @@ deeplabcut: last_verified: '2026-04-21' verified_for: 3.0.0rc14 --- + (file:how-to-install)= # Installing DeepLabCut @@ -55,7 +56,7 @@ python -c "import torch; print(torch.cuda.is_available())" ``` ```` -- If you're familiar with the command line and want TensorFlow support, look {ref}`below ` for a fresh installation on Linux and makes it possible to use the GPU with both PyTorch and TensorFlow. +- If you're familiar with the command line and want TensorFlow support, look {ref}`below ` for a fresh installation on Linux and makes it possible to use the GPU with both PyTorch and TensorFlow. ## Using Conda @@ -151,7 +152,9 @@ Now you should see (`DEEPLABCUT`) on the left of your terminal screen: No need to run `pip install deeplabcut`, it's already in the conda file! ``` -(deeplabcut-with-tf-install)= +(sec:deeplabcut-with-tf-install)= + +#### TensorFlow support ````{admonition} DeepLabCut TensorFlow Support --- From cd6512932c18435355c7ea0577e1fdf41cb873fb Mon Sep 17 00:00:00 2001 From: Cyril Achard Date: Tue, 5 May 2026 18:01:09 +0200 Subject: [PATCH 29/53] Refactor labeling guide and napari workflow Restructure and clarify the labeling documentation: reorganized headings and sections, consolidated frame selection guidance (automatic vs manual), and added an example workflow, important/tip admonitions, and a "Next steps" pointer to training/evaluation. Updated phrasing for clarity, fixed formatting (headings, links, and image reference), and replaced a quoted YAML note with unquoted text. These changes improve readability and better integrate the napari-DLC labeling workflow with the rest of the docs. --- docs/beginner-guides/labeling.md | 84 ++++++++++++++++---------------- 1 file changed, 43 insertions(+), 41 deletions(-) diff --git a/docs/beginner-guides/labeling.md b/docs/beginner-guides/labeling.md index 8e3173cbe2..8a4e69fd91 100644 --- a/docs/beginner-guides/labeling.md +++ b/docs/beginner-guides/labeling.md @@ -6,74 +6,76 @@ deeplabcut: visibility: online status: viable recommendation: update - notes: "Useful content, a note is that this should be better integrated with the napari plugin docs, making the workflow transition from DLC GUI -> napari viewer -> back to DLC GUI more seamless so as to confuse users less. This will need a bit of restructuring, as napari-DLC docs are also standalone from the main GUI. Finding a good linking strategy would help. Perhaps breaking napari-DLC docs into install/setup, basic usage, *labeling workflow* (new) and advanced usage would allow to do this cleanly, as it would separate the standalone plugin operation from the DLC-GUI integrated workflow, yet retaining a single source for napari-DLC labeling workflow." + notes: Useful content, a note is that this should be better integrated with the napari plugin docs, making the workflow transition from DLC GUI -> napari viewer -> back to DLC GUI more seamless so as to confuse users less. This will need a bit of restructuring, as napari-DLC docs are also standalone from the main GUI. Finding a good linking strategy would help. Perhaps breaking napari-DLC docs into install/setup, basic usage, *labeling workflow* (new) and advanced usage would allow to do this cleanly, as it would separate the standalone plugin operation from the DLC-GUI integrated workflow, yet retaining a single source for napari-DLC labeling workflow. --- -(labeling)= -# Labeling GUI - -## Selecting Frames to Label - -In DeepLabCut, choosing the right frames for labeling is a key step. The trick is always to select the MOST DIVERSE data you can that your model will see. That means good lighting, bad lighting, anything you want to throw at it. So, first, pick a range of diverse videos! Then, we will help you pick frames. You've got two easy ways to do this: -1. **Let DeepLabCut Choose:** DeepLabCut can extract frames automatically for you. It's got two neat ways to do that: - - **Uniform:** This is like taking a snapshot at regular time intervals. - - **K-means clustering:** This one applies k-means and picks images from different clusters. This is typically better, as it gives you a variety of actions and poses. Note, as it is a clustering tool, it will miss rare events, so ideally run this step, then perhaps consider running the manual GUI to get some rare frames! You can do both within DLC. +(file:labeling-gui)= -2. **Pick Frames Yourself:** Just like flipping through a photo album, you can go through your video and pick the frames that catch your eye - this is great for finding rare frames. Choose the **`manual`** extraction method. +# Labeling GUI -### Here's how to get started: +## Selecting frames to label -- **Step 1:** Click on **`automatic`** in the frame selection area. -- **Step 2:** Choose **`k-means`** for some variety. -- **Step 3:** Hit the **`Extract Frames`** button, usually found at the bottom right corner. +In DeepLabCut, choosing the right frames for labeling is a key step. -By default, DeepLabCut will grab 20 frames from each of your videos and put them into sub-folders, per video, under **labeled-data** in your project. Now, you're all set to start labeling! +```{important} +Always aim to select the MOST DIVERSE data you can for your model to be trained on. This implies picking a variety of good lighting, bad lighting, partial occlusions, and different poses. +If relevant, label data across several experimental sessions, animals, and conditions. +``` -## Labeling Your First Set of Frames in DeepLabCut +To help you select "different" frames, DeepLabCut provides two main options: -Alright, you've got your extracted frames ready. Now comes the labeling! +1. **Automated frame extraction** DeepLabCut can extract frames automatically for you. -### Entering the Label Frames Area + - **Uniform:** Samples at regular time intervals. Does not guarantee diversity, but is simple and fast. + - **K-means clustering:** This one runs a k-means algorithm and picks images from different clusters. This is typically more robust in extracting a variety of actions and poses. Note, as it is a clustering tool, it will miss rare events, so after running this step, consider using the manual GUI to get some rare frames! You can do both within DLC. -- **Click on `Label Frames`:** This takes you straight to where your frames are, sorted in the **labeled-data** folder, each video in its own sub-folder. -- **Open a Folder:** Click on the first one to start, and then click **`open`**. +1. **Manual frame extraction** Pick frames yourself using the GUI. This is the most time-consuming, but allows you to have full control over the frames you pick, and can be useful to get rare events that automated tools might miss. You can also use this after running automated frame extraction to get some of those "rare" frames. -### The napari DeepLabCut Labeler +### Example workflow -- **Plugin Window Opens:** As soon as you click **`open`**, the napari DeepLabCut plugin window appears, your main stage for labeling. -- **Tutorial Popup:** A quick tutorial window shows up. It's a brief guide, so give it a look to understand the basics. +1. Click on **`automatic`** in the frame selection area. +1. Choose **`k-means`** as a good default option for frame extraction, and set the number of frames you want to extract. +1. Hit the **`Extract Frames`** button. -![Labeling Frames in DeepLabCut using Napari Interface](https://images.squarespace-cdn.com/content/v1/57f6d51c9f74566f55ecf271/1717779602092-LVR2TI6OADSHEYRCGS6F/labeling-napari.png?format=500w)) +By default, DeepLabCut will grab 20 frames from each of your videos and put them into sub-folders, per video, under **labeled-data** in your project. +With this, you are all set to start labeling! -### Labeling Setup +## Frame labeling workflow -- **Frames on Display:** Your frames are lined up in the middle, with a slider below to shuffle through them. -- **Tools and Keypoints:** To the bottom right, you find a list of bodyparts from your configuration. On the top left, all your labeling tools are ready. +Alright, you've got your extracted frames ready. Now comes the labeling! -### The Labeling Process +### Launching the labeling GUI -- **Start with `Add points`:** Click this to begin placing keypoints on your first frame. If you can't see a bodypart, just move to the next one. -- **Navigate Through Frames:** Use the slider to go from one frame to the next after you're done labeling. -- **Save Progress:** Remember to save your work as you go with **`Command and S`** (or **`Ctrl and S`** on Windows). +- **Click on `Label Frames`:** This takes you straight to where your frames are, sorted in the **labeled-data** folder, each video in its own sub-folder. +- **Open a Folder:** Click on the first unlabeled folder to start, and then click **`Open`**. -> 💡 **Note:** For a detailed walkthrough on using the Napari labeling GUI, have a look at the -[DeepLabCut Napari Guide](file:napari-gui-landing). Additionally, you can watch our instructional -[YouTube video](https://www.youtube.com/watch?v=hsA9IB5r73E) for more insights and tips. +### napari-deeplabcut +Please refer to the {ref}`file:napari-dlc-basic-usage` section for a detailed walkthrough of how to use the napari-DLC plugin for labeling your frames. -### Completing the Set +### Completing the labeling -Work through all the frames in the first folder. Then, proceed to the next, continuing this way until each folder in your **labeled-data** directory is done. +Work through all the frames in the first folder and save them. -## Checking Your Labels +```{tip} +After saving, you can close napari and click **`Label Frames`* again to open the next folder +**OR** +Remove all layers in napari and drag-and-drop the next folder in the same napari session to keep going without needing to close and reopen napari. +``` -After you've labeled all your frames, it's important to ensure they're accurate. +## Checking labels -### How to Check Your Labels +After you've labeled all your frames, you may want to review their accuracy before moving on to training your model. This is a crucial step, as the quality of your labels will directly impact the performance of your model. - **Return to the Main Window:** Once you're done with labeling, head back to DeepLabCut's main window, and click on **`Check Labels`**. - **Review the Labeled Folders:** The system will have created new folders for each labeled set inside your labeled-data folder. These folders contain your original frames overlaid with the keypoints you've added. ![Checking Labels in DeepLabCut](https://images.squarespace-cdn.com/content/v1/57f6d51c9f74566f55ecf271/1717779615252-6BNW661XB2ULH85RTAD3/evaluation-example.png?format=500w) -Take the time to go through each folder. Accurate labels are key. If there are mistakes, the model might learn incorrectly and mislabel your videos later on. It's all about setting the right foundation for accurate analysis. +Take the time to go through each folder. Accurate labels are key. +If there are mistakes, the model might learn incorrectly and mislabel your videos later on. +A clean foundation is essential for accurate analysis. + +## Next steps + +Head on to {ref}`file:training-evaluation-gui` to learn about training and evaluating your neural network with the labeled data you created! From f6fb6079fd7599fe3b42fca0ddbc1217d29a6aea Mon Sep 17 00:00:00 2001 From: Cyril Achard Date: Tue, 5 May 2026 18:01:27 +0200 Subject: [PATCH 30/53] Clarify GUI config editing in manage-project Revise the manage-project beginner guide to focus on editing the GUI configuration file. Renamed the section, added a file anchor, and reworded the intro to explain config.yaml as the central project record. Introduced a dedicated "Editing the configuration" and a step-by-step walkthrough that consolidates bodyparts and skeleton guidance (including details on entries/IDs), improved bullets and examples, and added a tip and an HTML comment. Updated the link to the labeling guide (file:labeling-gui) and made minor YAML/frontmatter and formatting fixes. --- docs/beginner-guides/manage-project.md | 50 ++++++++++++++++---------- 1 file changed, 31 insertions(+), 19 deletions(-) diff --git a/docs/beginner-guides/manage-project.md b/docs/beginner-guides/manage-project.md index 4159ba99b9..6c771f803c 100644 --- a/docs/beginner-guides/manage-project.md +++ b/docs/beginner-guides/manage-project.md @@ -6,49 +6,61 @@ deeplabcut: visibility: online status: viable recommendation: move - notes: "It seems the beginner guide section is more of a GUI step-by-step. As such, it should be moved to the GUI section, and merged/integrated with the contents there. The content is useful, but making it clear that this is for the GUI would reduce the confusion of a beginner guide being in fact rather central GUI use instructions." + notes: It seems the beginner guide section is more of a GUI step-by-step. As such, it should be moved to the GUI section, and merged/integrated with the contents there. The content is useful, but making it clear that this is for the GUI would reduce the confusion of a beginner guide being in fact rather central GUI use instructions. --- -# Setting up what keypoints to track + +(file:manage-project-gui)= + +# Editing and working with the configuration file + DLC LIVE! -**Edit the Configuration File** +The configuration file (`config.yaml`) is the central record of files in your project, as well as the settings for your models. +As a YAML file, it can be edited manually, but the GUI provides an easy way to edit it without needing to know the YAML format. In this guide, we will show you how to edit the configuration file using the GUI. -After creating your DeepLabCut project, you'll go to the main GUI window, where you'll start managing your project from the Project Management Tab. +## Editing the configuration -**Accessing the Configuration File** +After creating your DeepLabCut project, you'll be shown the main GUI window, where you can manage your project from the Project Management Tab. - **Locate the Configuration File:** At the top of the main window, you'll find the file path to the configuration file. -- **Edit the File:** Click on **`Edit config.yaml`**. This action allows you to: - - Define the bodyparts you wish to track. - - Outline the skeleton structure (optional!). +- **Edit the File:** Click on **`Edit config.yaml`**. + - A **`Configuration Editor`** window will open, displaying all the configuration details. + - You will need to modify some of these settings to align with your experiment. + - For example: + - Update or define the bodyparts you wish to track. + - *Optional:* Outline the skeleton structure. -A **`Configuration Editor`** window will open, displaying all the configuration details. You'll need to modify some of these settings to align with your research requirements. +## Step-by-step configuration walkthrough -## Steps to Edit the Configuration - -### 1. Defining Bodyparts +### Defining & updating bodyparts - **Locate the Bodyparts Section:** In the Configuration Editor, find the **`bodyparts`** category. - **Modify the List:** Click on the arrow next to **`bodyparts`** to expand the list. Here, you can: - Update the list with the names of the bodyparts relevant to your study. - Add more entries by right-clicking on a row number and selecting **`Insert`**. - ![Editing Bodyparts in DeepLabCut's Config File](https://images.squarespace-cdn.com/content/v1/57f6d51c9f74566f55ecf271/1717779624617-CIVZCM23U69NYK9BO3GY/bodyparts.png?format=500w) + -### 2. Defining the Skeleton +### Defining the skeleton - **Navigate to the Skeleton Section:** Scroll down to the **`skeleton`** category. -- **Adjust the Skeleton List:** Click on the arrow to expand this section. You can then: - - Update the pairs of bodyparts to define the skeleton structure of your model. +- **Adjust the Skeleton List:** Click on the arrow to expand this section. + - You can then update the pairs of bodyparts to define the skeleton structure of your model. + - Each entry has an ID, starting from 0 (key) + - Each entry (value) under a key must then consist in a pair of bodyparts, which will be connected in the skeleton. ![Defining the Skeleton Structure in Config File](https://images.squarespace-cdn.com/content/v1/57f6d51c9f74566f55ecf271/1717779598505-HQNECHIKSQ6XL033JX8M/skeleton.png?format=500w) -> 💡 **Tip:** If you're new to DeepLabCut, spend some time visualizing how the chosen bodyparts can be connected effectively to form a coherent skeleton. +```{tip} +Spend some time visualizing how the chosen bodyparts can be connected effectively to form a coherent, visually helpful skeleton. +``` -### Saving Your Changes +### Saving changes - **Save the Configuration:** Once you're satisfied with the modifications, click **`Save`**. This will store your changes and return you to the main GUI window. -## Next, head over the beginner guide for [Labeling your data](labeling) +## Next steps + +Head over the beginner guide for \[Labeling your data\](file:labeling-gui), which will show you how to label your data using the napari-based labeling GUI, and how to integrate that with the main DLC GUI workflow. From 6ddfa52edbf567a0a1f4b8086b0d1210a5d6ceb2 Mon Sep 17 00:00:00 2001 From: Cyril Achard Date: Tue, 5 May 2026 18:02:08 +0200 Subject: [PATCH 31/53] Update GUI training/evaluation guide MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Revise docs/beginner-guides/Training-Evaluation.md: add RST anchor and restructure headings (Network training, Creating a training set, Starting the training process, Network evaluation, Next steps). Clarify wording (e.g. defaults described as “good” to start), convert tip to RST directive, adjust evaluation section formatting and images, and add reference to the video-analysis GUI section. Also change YAML notes value formatting. --- docs/beginner-guides/Training-Evaluation.md | 44 +++++++++++++-------- 1 file changed, 28 insertions(+), 16 deletions(-) diff --git a/docs/beginner-guides/Training-Evaluation.md b/docs/beginner-guides/Training-Evaluation.md index ae22ab403c..1776e8f748 100644 --- a/docs/beginner-guides/Training-Evaluation.md +++ b/docs/beginner-guides/Training-Evaluation.md @@ -6,19 +6,28 @@ deeplabcut: visibility: online status: viable recommendation: move - notes: "As mentioned on oher beginner-guides/ docs, this should be part of the GUI section." + notes: As mentioned on oher beginner-guides/ docs, this should be part of the GUI section. --- -# Neural Network training and evaluation in the GUI + +(file:training-evaluation-gui)= + +# Neural network training and evaluation in the GUI + DLC LIVE! +## Network training + +### Creating a training set Before training your model, the first step is to assemble your training dataset. -**Create Training Dataset:** Move to the corresponding tab and click **`Create Training Dataset`**. For starters, the default settings will do just fine. While there are more powerful models and data augmentations you might want to consider, you can trust that for most projects the defaults are an ideal place to start. +**Create Training Dataset:** Move to the corresponding tab and click **`Create Training Dataset`**. For starters, the default settings will do just fine. While there are more powerful models and data augmentations you might want to consider, you can trust that for most projects the defaults are a good place to start. -> 💡 **Note:** This guide assumes you have a GPU on your local machine. If you're CPU-bound and finding training challenging, consider using Google Colab. Our [Colab Guide](https://colab.research.google.com/github/DeepLabCut/DeepLabCut/blob/master/examples/COLAB/COLAB_YOURDATA_TrainNetwork_VideoAnalysis.ipynb) can help you get started! +```{note} +This guide assumes you have a GPU on your local machine. If you're CPU-bound and training is not feasible, consider using Google Colab. Our [Colab Guide](https://colab.research.google.com/github/DeepLabCut/DeepLabCut/blob/master/examples/COLAB/COLAB_YOURDATA_TrainNetwork_VideoAnalysis.ipynb) can help you get started! +``` -## Kickstarting the Training Process +### Starting the training process With your training dataset ready, it's time to train your model. @@ -33,31 +42,34 @@ You can keep an eye on the training progress via your terminal window. This will ![DeepLabCut Training in Terminal with TF](https://images.squarespace-cdn.com/content/v1/57f6d51c9f74566f55ecf271/1717779598041-DC8UJA2NXJXG65ZWJH1O/training-terminal.png?format=500w) -## Evaluate the Network +## Network evaluation After training, it's time to see how well your model performs. -### Steps to Evaluate the Network +### Step-by-step 1. Find and click on the **`Evaluate Network`** tab. -2. **Choose Evaluation Options:** +1. **Choose Evaluation Options:** - **Plot Predictions:** Select this to visualize the model's predictions, similar to standard DeepLabCut (DLC) evaluations. - **Compare Bodyparts:** Opt to compare all the bodyparts for a comprehensive evaluation. -3. Click the **`Evaluate Network`** button, located on the right side of the main window. - ->💡 Tip: If you wish to evaluate all saved snapshots, go to the configuration file and change the `snapshotindex` parameter to `all`. +1. Click the **`Evaluate Network`** button, located on the right side of the main window. +```{tip} +If you wish to evaluate all saved snapshots, go to the configuration file and change the `snapshotindex` parameter to `all`. +``` -### Understanding the Evaluation Results +### Interpreting the results - **Performance Metrics:** DLC will assess the latest snapshot of your model, generating a `.CSV` file with performance -metrics. This file is stored in the **`evaluation-results`** (for TensorFlow models) or the -**`evaluation-results-pytorch`** (for PyTorch models) folder within your project. + metrics. This file is stored in the **`evaluation-results`** (for TensorFlow models) or the + **`evaluation-results-pytorch`** (for PyTorch models) folder within your project. +![Combined Evaluation Results in DeepLabCut](https://images.squarespace-cdn.com/content/v1/57f6d51c9f74566f55ecf271/1717779617667-0RLTM9DVRALN9YIKSHJZ/combined-evaluation-results.png?format=750w) -![Combined Evaluation Results in DeepLabCut](https://images.squarespace-cdn.com/content/v1/57f6d51c9f74566f55ecf271/1717779617667-0RLTM9DVRALN9YIKSHJZ/combined-evaluation-results.png?format=750w)) - **Visual Feedback:** Additionally, DLC creates subfolders containing your frames overlaid with both the labeled bodyparts and the model's predictions, allowing you to visually gauge the network's performance. ![Evaluation Example in DeepLabCut](https://images.squarespace-cdn.com/content/v1/57f6d51c9f74566f55ecf271/1717779623162-BFDAW37B9TO94EGME2O5/check-labels.png?format=500w)) -## Next, head over the beginner guide for [using your new neural network for video analysis](video-analysis) +## Next steps + +Head over the {ref}`file:video-analysis-gui` section to learn about applying your trained model to videos, and creating labeled videos with the results of your analysis! From 784ddef347a49977515411c5b856da2c591068f9 Mon Sep 17 00:00:00 2001 From: Cyril Achard Date: Tue, 5 May 2026 18:02:29 +0200 Subject: [PATCH 32/53] Refactor video analysis guide for GUI Rework the beginner video-analysis doc to focus on the GUI workflow: add a file anchor, rename and restructure headings (Analyzing videos with your trained model, Generating labeled videos, Next steps), reorganize and clarify step-by-step instructions, and update copy. Also remove quoting from the frontmatter notes and add a TODO link comment for future cross-references. --- docs/beginner-guides/video-analysis.md | 42 +++++++++++++++++--------- 1 file changed, 27 insertions(+), 15 deletions(-) diff --git a/docs/beginner-guides/video-analysis.md b/docs/beginner-guides/video-analysis.md index 5ed5892530..ac667881b4 100644 --- a/docs/beginner-guides/video-analysis.md +++ b/docs/beginner-guides/video-analysis.md @@ -6,23 +6,30 @@ deeplabcut: visibility: online status: viable recommendation: move - notes: "As mentioned on oher beginner-guides/ docs, this should be part of the GUI section." + notes: As mentioned on oher beginner-guides/ docs, this should be part of the GUI section. --- -# Video Analysis with DeepLabCut -DLC LIVE! +(file:video-analysis-gui)= + +# Video analysis in the GUI + +DLC LIVE! After training and evaluating your model, the next step is to apply it to your videos. -**How to Analyze Videos** +## Analyzing videos with your trained model + +### Step-by-step 1. **Navigate to the 'Analyze Videos' Tab:** Begin applying your trained model to video data here. -2. **Select Your Video Format and Files:** - - **Choose Video Format:** Pick the format of your video (`.mp4`, `.avi`, `.mkv`, or `.mov`). - - **Select Videos:** Click **`Select Videos`** to find and open your video file. +1. **Select Your Video Format and Files:** + +- **Choose Video Format:** Pick the format of your video (`.mp4`, `.avi`, `.mkv`, or `.mov`). +- **Select Videos:** Click **`Select Videos`** to find and open your video file. + 3. **Start Analysis:** Click **`Analyze`**. The analysis time depends on video length and resolution. Track progress in the terminal or Anaconda prompt. -## Reviewing Analysis Results +### Reviewing analysis results - **Find Results in Your Project Folder:** After analysis, go to your project's video folder. - **Analysis Files:** Look also for a `.metapickle`, an `.h5`, and possibly a `.csv` file for detailed analysis data. @@ -30,16 +37,21 @@ After training and evaluating your model, the next step is to apply it to your v ![Plot poses](https://images.squarespace-cdn.com/content/v1/57f6d51c9f74566f55ecf271/1717779600836-YOWM5T2MBY0JN1LB537B/plot-poses.png?format=500w) -## Creating a Labeled Video +## Generating labeled videos + +### Create a labeled video 1. **Go to 'Create Labeled Video' Tab:** The previously analyzed video should be selected. -2. If not already selected, choose your video. -3. Click **`Create Videos`**. +1. If not already selected, choose your video. +1. Click **`Create Videos`**. -## Viewing the Labeled Video +### View the labeled video - Your labeled video will be in your video folder, named after the original video plus model details and 'labeled'. -- Watch the video to assess the model's labeling accuracy. +- Use it in your results, or perform downstream analyses with it! + +## Next steps + + -## Happy DeepLabCutting! -- Check out the more advanced user guides for even more options! +Check our more advanced guides, and consider reading more about models, augmentations and other parameters to further optimize your model and analysis! From 5564ef7b7ad19a262fe2d5f3b50114b99e71808e Mon Sep 17 00:00:00 2001 From: Cyril Achard Date: Wed, 6 May 2026 09:54:02 +0200 Subject: [PATCH 33/53] Refine beginner guides and napari usage docs Update several docs to improve formatting, clarity, and links. Convert inline notes to admonition blocks, fix spacing/indentation around images and note blocks, and bold example items for readability (docs/beginner-guides/beginners-guide.md). Clarify labeling guidance and emphasize labeling across multiple videos; update front-matter note to link to napari plugin docs (docs/beginner-guides/labeling.md). Adjust manage-project wording and next-step link to the labeling guide (docs/beginner-guides/manage-project.md). Add a brief napari usage recommendation with a link to the official napari docs (docs/gui/napari/basic_usage.md). These changes aim to make the GUI/napari workflow and labeling guidance clearer for beginners. --- docs/beginner-guides/beginners-guide.md | 20 +++++++++++--------- docs/beginner-guides/labeling.md | 5 +++-- docs/beginner-guides/manage-project.md | 4 ++-- docs/gui/napari/basic_usage.md | 7 +++++++ 4 files changed, 23 insertions(+), 13 deletions(-) diff --git a/docs/beginner-guides/beginners-guide.md b/docs/beginner-guides/beginners-guide.md index 1a9798be72..8c9bd358ed 100644 --- a/docs/beginner-guides/beginners-guide.md +++ b/docs/beginner-guides/beginners-guide.md @@ -104,7 +104,8 @@ This will open DeepLabCut. ![DeepLabCut GUI Screenshot](https://images.squarespace-cdn.com/content/v1/57f6d51c9f74566f55ecf271/1717779625875-5UHPC367I293CBSP8CT6/GUI-screenshot.png?format=500w) -> 💡 **Note:** For a visual guide on navigating through the DeepLabCut GUI, check out our [YouTube tutorial](https://www.youtube.com/watch?v=tr3npnXWoD4). +```{note} For a visual guide on navigating through the DeepLabCut GUI, check out our [YouTube tutorial](https://www.youtube.com/watch?v=tr3npnXWoD4). +``` ## Starting a new project @@ -123,13 +124,14 @@ When you first launch the GUI, you'll find three primary main options: ### 🐾 New project step-by-step 1. **Launch New Project:** + - When you start a new project, you'll be presented with an empty project window. In DLC3+ you will see a new option "Engine". -![DeepLabCut Engine](https://images.squarespace-cdn.com/content/v1/57f6d51c9f74566f55ecf271/1717780414978-17LOVBUJ8JR102QVSFDY/Screen+Shot+2024-06-07+at+7.13.14+PM.png?format=1500w) + ![DeepLabCut Engine](https://images.squarespace-cdn.com/content/v1/57f6d51c9f74566f55ecf271/1717780414978-17LOVBUJ8JR102QVSFDY/Screen+Shot+2024-06-07+at+7.13.14+PM.png?format=1500w) -```{note} -For most users, the engine will be PyTorch. See {ref}`sec:deeplabcut-with-tf-install` for TensorFlow support. -``` + ```{note} + For most users, the engine will be PyTorch. See {ref}`sec:deeplabcut-with-tf-install` for TensorFlow support. + ``` 1. **Filling in Project Details:** @@ -171,13 +173,13 @@ For most users, the engine will be PyTorch. See {ref}`sec:deeplabcut-with-tf-ins 1. **Define bodyparts and individuals:** - Enter all the name, numbers or IDs of bodyparts you wish to track. - - Example: "head", "tail", "left paw", "right paw", etc. + - **Example:** "head", "tail", "left paw", "right paw", etc. - Less recommened: "L1", "L2", "L3", etc. - **If you have multiple animals**: - Enter the name, numbers or IDs of the individuals in your experiment. - - Example: "mouse1", "mouse2", "mouse3", etc. + - **Example:** "mouse1", "mouse2", "mouse3", etc. - **Unique bodyparts**: If you wish to track "landmark" locations, such as the edges of a maze, or a specific object, you can add these as "unique bodyparts". These are not considered part of an individual, but are still tracked as part of the project. - - Example: "maze_left_edge", "maze_right_edge", "reward_port", etc. + - **Example**: "maze_left_edge", "maze_right_edge", "reward_port", etc. - **Identity labeling**: if and only if you can tell individuals apart by their appearance (not their location), set this to Yes and consistently label your individuals in the same way across videos. This will allow DeepLabCut to learn to tell them apart, and assign consistent identities across frames and videos. 1. **Create your project:** @@ -193,4 +195,4 @@ For most users, the engine will be PyTorch. See {ref}`sec:deeplabcut-with-tf-ins ## Next steps -Next, head over to the beginner guide for {ref}`Setting up what keypoints to track `, which will show you how to edit the configuration file to edit your bodyparts and skeleton structure. +Next, head over to the beginner guide for {ref}`editing the configuration and managing the project `, which will show you how to edit the configuration file to edit your bodyparts and skeleton structure. diff --git a/docs/beginner-guides/labeling.md b/docs/beginner-guides/labeling.md index 8a4e69fd91..a71090178e 100644 --- a/docs/beginner-guides/labeling.md +++ b/docs/beginner-guides/labeling.md @@ -6,7 +6,7 @@ deeplabcut: visibility: online status: viable recommendation: update - notes: Useful content, a note is that this should be better integrated with the napari plugin docs, making the workflow transition from DLC GUI -> napari viewer -> back to DLC GUI more seamless so as to confuse users less. This will need a bit of restructuring, as napari-DLC docs are also standalone from the main GUI. Finding a good linking strategy would help. Perhaps breaking napari-DLC docs into install/setup, basic usage, *labeling workflow* (new) and advanced usage would allow to do this cleanly, as it would separate the standalone plugin operation from the DLC-GUI integrated workflow, yet retaining a single source for napari-DLC labeling workflow. + notes: Updated to link directly to the napari plugin docs. Making the link specific to the workflow section of the napari docs could help. --- (file:labeling-gui)= @@ -18,8 +18,9 @@ deeplabcut: In DeepLabCut, choosing the right frames for labeling is a key step. ```{important} -Always aim to select the MOST DIVERSE data you can for your model to be trained on. This implies picking a variety of good lighting, bad lighting, partial occlusions, and different poses. +Always aim to select the **most diverse data** you can for your model to be trained on. This implies picking a variety of good lighting, bad lighting, partial occlusions, and different poses. If relevant, label data across several experimental sessions, animals, and conditions. +**Labeling 10 frames from several different videos is typically more effective than labeling 100 frames from a single video.** ``` To help you select "different" frames, DeepLabCut provides two main options: diff --git a/docs/beginner-guides/manage-project.md b/docs/beginner-guides/manage-project.md index 6c771f803c..3bc0bb2f71 100644 --- a/docs/beginner-guides/manage-project.md +++ b/docs/beginner-guides/manage-project.md @@ -6,7 +6,7 @@ deeplabcut: visibility: online status: viable recommendation: move - notes: It seems the beginner guide section is more of a GUI step-by-step. As such, it should be moved to the GUI section, and merged/integrated with the contents there. The content is useful, but making it clear that this is for the GUI would reduce the confusion of a beginner guide being in fact rather central GUI use instructions. + notes: Making the config edit tool slightly easier to work with and updating the docs below to include additional fields would be helpful. --- (file:manage-project-gui)= @@ -63,4 +63,4 @@ Spend some time visualizing how the chosen bodyparts can be connected effectivel ## Next steps -Head over the beginner guide for \[Labeling your data\](file:labeling-gui), which will show you how to label your data using the napari-based labeling GUI, and how to integrate that with the main DLC GUI workflow. +Head over the guide for the {ref}`file:labeling-gui`, which will show you how to label your data using the napari-based labeling GUI. diff --git a/docs/gui/napari/basic_usage.md b/docs/gui/napari/basic_usage.md index b6f2cb6f3f..b10880e4a0 100644 --- a/docs/gui/napari/basic_usage.md +++ b/docs/gui/napari/basic_usage.md @@ -8,6 +8,7 @@ deeplabcut: --- (file:napari-dlc-basic-usage)= + # napari-DLC - Basic usage `napari-deeplabcut` is a napari plugin for keypoint annotation and label refinement. It can be used either as part of the DeepLabCut GUI or as a standalone annotation tool. @@ -56,6 +57,12 @@ You can load files either by: If you drag and drop a compatible labeled-data folder, the widget opens automatically. ``` +## Using napari + +```{important} +To familiarize yourself with napari, we recommend checking out the [official napari documentation and tutorials](https://napari.org/stable/usage.html). +``` + ## Recommended basic labeling workflow The simplest way to **start labeling** is: From 24d39fd3b493d730603ac11629f16f81ba2f6e08 Mon Sep 17 00:00:00 2001 From: Cyril Achard Date: Wed, 6 May 2026 10:03:28 +0200 Subject: [PATCH 34/53] Tidy beginner-guides Minor cleanup and reorganization prep for beginner guides: remove an extra closing parenthesis from an image link in Training-Evaluation.md; update frontmatter recommendation from "update" to "move" and simplify notes to indicate moving content to a dedicated GUI section in beginners-guide.md, labeling.md, and manage-project.md; and change "Click on" to "Select" in the labeling workflow example. These edits prepare the docs for consolidation under a GUI section. --- docs/beginner-guides/Training-Evaluation.md | 2 +- docs/beginner-guides/beginners-guide.md | 4 ++-- docs/beginner-guides/labeling.md | 6 +++--- docs/beginner-guides/manage-project.md | 2 +- 4 files changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/beginner-guides/Training-Evaluation.md b/docs/beginner-guides/Training-Evaluation.md index 1776e8f748..c7885abdfc 100644 --- a/docs/beginner-guides/Training-Evaluation.md +++ b/docs/beginner-guides/Training-Evaluation.md @@ -68,7 +68,7 @@ If you wish to evaluate all saved snapshots, go to the configuration file and ch - **Visual Feedback:** Additionally, DLC creates subfolders containing your frames overlaid with both the labeled bodyparts and the model's predictions, allowing you to visually gauge the network's performance. -![Evaluation Example in DeepLabCut](https://images.squarespace-cdn.com/content/v1/57f6d51c9f74566f55ecf271/1717779623162-BFDAW37B9TO94EGME2O5/check-labels.png?format=500w)) +![Evaluation Example in DeepLabCut](https://images.squarespace-cdn.com/content/v1/57f6d51c9f74566f55ecf271/1717779623162-BFDAW37B9TO94EGME2O5/check-labels.png?format=500w) ## Next steps diff --git a/docs/beginner-guides/beginners-guide.md b/docs/beginner-guides/beginners-guide.md index 8c9bd358ed..1daf747e74 100644 --- a/docs/beginner-guides/beginners-guide.md +++ b/docs/beginner-guides/beginners-guide.md @@ -5,8 +5,8 @@ deeplabcut: ignore: false visibility: online status: outdated - recommendation: update - notes: While it could seem like a useful page for beginners, duplicating installation instructions is not ideal for maintenance. This is also mixing installation/setup with a GUI guide, which should be in its own section/page. This puts into question the reason of existence of this page, as it would end up being two links to different sections. I would rather have well-made, accurate installation and GUI guides, and if there are beginner-relevant information that really cannot fit into those, then we can have a 'beginner's guide' that links to those and has the extra info. I would suggest reviewing whether this style of docs should remain at all, but if we want to keep them revising the approach may be needed. + recommendation: move + notes: Move to GUI section. --- (file:beginners-guide)= diff --git a/docs/beginner-guides/labeling.md b/docs/beginner-guides/labeling.md index a71090178e..d5ce8cbb9c 100644 --- a/docs/beginner-guides/labeling.md +++ b/docs/beginner-guides/labeling.md @@ -5,8 +5,8 @@ deeplabcut: ignore: false visibility: online status: viable - recommendation: update - notes: Updated to link directly to the napari plugin docs. Making the link specific to the workflow section of the napari docs could help. + recommendation: move + notes: Move to GUI section. Updated to link directly to the napari plugin docs. Making the link specific to the workflow section of the napari docs could help. --- (file:labeling-gui)= @@ -34,7 +34,7 @@ To help you select "different" frames, DeepLabCut provides two main options: ### Example workflow -1. Click on **`automatic`** in the frame selection area. +1. Select **`automatic`** in the frame selection area. 1. Choose **`k-means`** as a good default option for frame extraction, and set the number of frames you want to extract. 1. Hit the **`Extract Frames`** button. diff --git a/docs/beginner-guides/manage-project.md b/docs/beginner-guides/manage-project.md index 3bc0bb2f71..ce8ddcfee3 100644 --- a/docs/beginner-guides/manage-project.md +++ b/docs/beginner-guides/manage-project.md @@ -6,7 +6,7 @@ deeplabcut: visibility: online status: viable recommendation: move - notes: Making the config edit tool slightly easier to work with and updating the docs below to include additional fields would be helpful. + notes: Move to a dedicated GUI section. Making the config edit tool slightly easier to work with and updating the docs below to include additional fields would be helpful. --- (file:manage-project-gui)= From c6e00877b7d34c52544c5e796eac568f372dcc84 Mon Sep 17 00:00:00 2001 From: Cyril Achard Date: Wed, 6 May 2026 10:25:58 +0200 Subject: [PATCH 35/53] Refine PROJECT_GUI docs layout and links MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Polish docs/gui/PROJECT_GUI.md: rename headings for clarity ("Interactive Project Manager GUI" → "Project Manager GUI", "Get Started:" → "Getting started", "Video Demo" → "User guide" / "Video demos"); replace inline markdown links with Sphinx {ref} cross-references (napari and beginners guide); add an important note linking to the beginners guide and a tip to "Click on the images!". These changes improve consistency with the docs style and surface the step-by-step GUI guide. --- docs/gui/PROJECT_GUI.md | 22 +++++++++++++++------- 1 file changed, 15 insertions(+), 7 deletions(-) diff --git a/docs/gui/PROJECT_GUI.md b/docs/gui/PROJECT_GUI.md index 9d269bf471..fc450bd648 100644 --- a/docs/gui/PROJECT_GUI.md +++ b/docs/gui/PROJECT_GUI.md @@ -11,14 +11,14 @@ deeplabcut: (project-manager-gui)= -# Interactive Project Manager GUI +# Project Manager GUI As some users may be more comfortable working with an interactive interface, we wanted to provide an easy entry point to the software. All the main functionality is available in an easy-to-use GUI interface. While several advanced features are not fully available in this Project GUI, we hope this gets more users up-and-running quickly. **Release notes:** As of DeepLabCut 2.1+ now provide a full front-end user experience for DeepLabCut, and as of 2.3+ we changed the GUI from wxPython to PySide6 with napari support. -## Get Started: +## Getting started 1. Install DeepLabCut following the instructions in the {ref}`installation page`. 1. Open the terminal and run: `python -m deeplabcut` @@ -30,7 +30,7 @@ While several advanced features are not fully available in this Project GUI, we Start at the Project Management Tab and work your way through the tabs to built your customized model and deploy it on new data. We recommend to keep the terminal visible (as well as the GUI) so you can see the ongoing processes as you step through your project, or any errors that might arise. -- For specific napari-based labeling features, see the ["napari gui" docs](file:napari-gui-landing). +- For specific napari-based labeling features, see the {ref}`napari gui` section. - To change from dark to light mode, set appearance at the top:

@@ -38,28 +38,36 @@ We recommend to keep the terminal visible (as well as the GUI) so you can see th " width="30%">

-## Video Demo +## User guide + +```{important} +See the dedicated {ref}`file:beginners-guide` section for a step-by-step walkthrough of the GUI. +``` + +## Video demos ### How to launch and run the Project Manager GUI +```{tip} **Click on the images!** +``` Note that currently the video demo is the wxPython version, but the logic is the same! [![Watch the video](https://images.squarespace-cdn.com/content/v1/57f6d51c9f74566f55ecf271/1572824438905-QY9XQKZ8LAJZG6BLPWOQ/ke17ZwdGBToddI8pDm48kIIa76w436aRzIF_cdFnEbEUqsxRUqqbr1mOJYKfIPR7LoDQ9mXPOjoJoqy81S2I8N_N4V1vUb5AoIIIbLZhVYxCRW4BPu10St3TBAUQYVKcLthF_aOEGVRewCT7qiippiAuU5PSJ9SSYal26FEts0MmqyMIhpMOn8vJAUvOV4MI/guilaunch.jpg?format=1000w)](https://youtu.be/KcXogR-p5Ak) -### Using the Project Manager GUI with the latest DLC code (single animals, plus objects): ⬇️ +### Using the Project Manager GUI with the latest DLC code (single animals, plus objects) [![Watch the video](https://images.squarespace-cdn.com/content/v1/57f6d51c9f74566f55ecf271/1589046800303-OV1CCNZINWDMF1PZWCWE/ke17ZwdGBToddI8pDm48kB4PVlRPKDmSlQNbUD3wvXgUqsxRUqqbr1mOJYKfIPR7LoDQ9mXPOjoJoqy81S2I8N_N4V1vUb5AoIIIbLZhVYxCRW4BPu10St3TBAUQYVKcaja1QZ1SznGf7WzFOi-J6zLusnaF2VdeZcKivwxvFiDfGDqVYuwbAlftad9hfoui/dlc_gui_22.png?format=1000w)](https://www.youtube.com/watch?v=JDsa8R5J0nQ) [Read more here](important-info-regd-usage) -### Using the Project Manager GUI with the latest DLC code (multiple identical-looking animals, plus objects): +### Using the Project Manager GUI with the latest DLC code (multiple identical-looking animals, plus objects) [![Watch the video](https://images.squarespace-cdn.com/content/v1/57f6d51c9f74566f55ecf271/1589047147498-G1KTFA5BXR4PVHOOR7OG/ke17ZwdGBToddI8pDm48kJDij24pM2COisBTLIGjR1pZw-zPPgdn4jUwVcJE1ZvWQUxwkmyExglNqGp0IvTJZamWLI2zvYWH8K3-s_4yszcp2ryTI0HqTOaaUohrI8PIel60EThn7SDFlTiSprUhmjQQHn9bhdY9dnQSKs8bCCo/Untitled.png?format=1000w)](https://www.youtube.com/watch?v=Kp-stcTm77g) [Read more here](important-info-regd-usage) -### How to benchmark your data with the new networks and data augmentation pipelines: +### How to benchmark your data with the new networks and data augmentation pipelines [Watch the video](https://youtu.be/WXCVr6xAcCA) From 86c3a4855a3b4d3c6587082a4decd51e77f06714 Mon Sep 17 00:00:00 2001 From: Cyril Achard Date: Wed, 6 May 2026 10:29:47 +0200 Subject: [PATCH 36/53] Fix link in getting started --- docs/UseOverviewGuide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/UseOverviewGuide.md b/docs/UseOverviewGuide.md index b6879d49aa..c88ae4e045 100644 --- a/docs/UseOverviewGuide.md +++ b/docs/UseOverviewGuide.md @@ -12,7 +12,7 @@ deeplabcut: Below we will first outline what you need to get started, the different ways you can use DeepLabCut, and then the full workflow. Note, we highly recommend you also read and follow our [Nature Protocols paper](https://www.nature.com/articles/s41596-019-0176-0), which is (still) fully relevant to standard DeepLabCut. ```{hint} -💡📚 If you are new to Python and DeepLabCut, you might consider checking our [beginner guide](file:beginners-guide) once you are ready to jump into using the DeepLabCut App! +💡📚 If you are new to Python and DeepLabCut, you might consider checking our {ref}`beginner guide ` once you are ready to jump into using the DeepLabCut App! ``` ## Introduction From 030239c9872cb35cf24bf4fc02286fb5ceeb3169 Mon Sep 17 00:00:00 2001 From: Cyril Achard Date: Wed, 6 May 2026 10:42:29 +0200 Subject: [PATCH 37/53] docs: update Docker docs formatting and notes Refactor docs/docker.md to improve formatting and clarify guidance. Renamed the section heading, convert several inline notes into MyST admonitions (important/note), wrap the napari-deeplabcut install guidance into an important block, and adjust the GPU reminder into an admonition. Minor rework of the mount/example instructions and commented out a redundant labelling note to reduce duplication and improve readability. --- docs/docker.md | 77 +++++++++++++++++++++++++++----------------------- 1 file changed, 42 insertions(+), 35 deletions(-) diff --git a/docs/docker.md b/docs/docker.md index 7e4e440937..eb95439e6a 100644 --- a/docs/docker.md +++ b/docs/docker.md @@ -7,26 +7,26 @@ deeplabcut: status: review_needed recommendation: verify --- + (docker-containers)= -# DeepLabCut Docker containers -For DeepLabCut 2.2.0.2 and onwards, we provide container containers on [DockerHub]( -https://hub.docker.com/r/deeplabcut/deeplabcut). Using Docker is an alternative approach -to using DeepLabCut, which only requires the user to install [Docker]( -https://www.docker.com/) on your machine, vs. following the step-by-step installation +# DeepLabCut in Docker + +For DeepLabCut 2.2.0.2 and onwards, we provide container containers on [DockerHub](https://hub.docker.com/r/deeplabcut/deeplabcut). Using Docker is an alternative approach +to using DeepLabCut, which only requires the user to install [Docker](https://www.docker.com/) on your machine, vs. following the step-by-step installation guide for a Anaconda setup. All dependencies needed to run DeepLabCut in the terminal or running Jupyter notebooks with DeepLabCut pre-installed are shipped with the provided Docker images. -The [`napari-deeplabcut` labelling GUI]( -https://deeplabcut.github.io/DeepLabCut/docs/gui/napari_GUI.html) can be used to label +```{important} +The {ref}`napari-deeplabcut plugin ` can be used to label your data, but it cannot be run in a Docker container: it should be installed as -documented in the link above: `pip install napari-deeplabcut` (checkout the [workflow]( -https://deeplabcut.github.io/DeepLabCut/docs/gui/napari_GUI.html#workflow) as well!). +documented in the link above: `pip install napari-deeplabcut` +``` Advanced users can directly head to [DockerHub](https://hub.docker.com/r/deeplabcut/deeplabcut) and use the provided images there. To get started with using the images, we however also provide a helper tool, `deeplabcut-docker`, which makes the transition to docker images particularly convenient; to install the tool, run -``` bash +```bash $ pip install deeplabcut-docker ``` @@ -37,36 +37,36 @@ Note that this will *not* disprupt or install Tensorflow, or any other DeepLabCu With `deeplabcut-docker`, you can use the images in two modes. -- *Note 1: When running any of the following commands first, it can take some time to complete (a few minutes, depending on your internet connection), since it downloads the Docker image in the background. If you do not see any errors in your terminal, assume that everything is working fine! Subsequent runs of the command will be faster.* -- *Note 2: The labelling GUI cannot be used through the Docker images. However, you can install [`napari-deeplabcut`](https://github.com/DeepLabCut/napari-deeplabcut/tree/main?tab=readme-ov-file#napari-deeplabcut-keypoint-annotation-for-pose-estimation) in a conda environment to do the labelling!* -- *Note 3: For any mode below, you might want to set which directory is the base, namely, so you can have read/write (or read-only access). Here is how to do so: -If you want to mount the whole directory could e.g., pass* - -`deeplabcut-docker bash -v /home/mackenzie/DEEPLABCUT:/home/mackenzie/DEEPLABCUT` - -(which will mount the full directory into the container in read/write mode) - -If read-only access is enough, `deeplabcut-docker bash -v /home/mackenzie/DEEPLABCUT:/home/mackenzie/DEEPLABCUT:ro` - +```{note} +1. When running any of the following commands first, it can take some time to complete (a few minutes, depending on your internet connection), since it downloads the Docker image in the background. If you do not see any errors in your terminal, assume that everything is working fine! Subsequent runs of the command will be faster.* + +1. For any mode below, you might want to set which directory is the base, namely, so you can have read/write (or read-only access). Here is how to do so: + If you want to mount the whole directory could e.g., pass* + `deeplabcut-docker bash -v /home/mackenzie/DEEPLABCUT:/home/mackenzie/DEEPLABCUT` + (which will mount the full directory into the container in read/write mode) + If read-only access is enough, `deeplabcut-docker bash -v /home/mackenzie/DEEPLABCUT:/home/mackenzie/DEEPLABCUT:ro` +``` ### Terminal mode You can run the light version of DeepLabCut and open a terminal by running -``` bash +```bash $ deeplabcut-docker bash ``` -**Important:** if have GPUs on your machine and want to use them to train models, you +````{important} +If you have GPUs on your machine and want to use them to train models, you need to pass the `--gpus all` argument to `deeplabcut-docker`: ``` bash $ deeplabcut-docker bash --gpus all ``` +```` Inside the terminal, you can confirm that DeepLabCut is correctly installed by running and noting which version installs. -``` bash +```bash $ ipython >>> import deeplabcut ``` @@ -75,7 +75,7 @@ $ ipython You can run DeepLabCut by starting a jupyter notebook server. The corresponding image can be pulled and started by running -``` bash +```bash $ deeplabcut-docker notebook ``` @@ -92,28 +92,35 @@ Advanced users and developers can visit the [`/docker` subdirectory](https://git **(1)** Install Docker. See https://docs.docker.com/install/ & for Ubuntu: https://docs.docker.com/install/linux/docker-ce/ubuntu/ Test docker: - $ sudo docker run hello-world - - The output should be: ``Hello from Docker! This message shows that your installation appears to be working correctly.`` +``` +$ sudo docker run hello-world +``` -*if you get the error ``docker: Error response from daemon: Unknown runtime specified nvidia.`` just simply restart docker: +The output should be: `Hello from Docker! This message shows that your installation appears to be working correctly.` - $ sudo systemctl daemon-reload - $ sudo systemctl restart docker +\*if you get the error `docker: Error response from daemon: Unknown runtime specified nvidia.` just simply restart docker: +``` + $ sudo systemctl daemon-reload + $ sudo systemctl restart docker +``` **(2)** Add your user to the docker group (https://docs.docker.com/install/linux/linux-postinstall/#manage-docker-as-a-non-root-user) -Quick guide to create the docker group and add your user: +Quick guide to create the docker group and add your user: Create the docker group. - $ sudo groupadd docker +``` +$ sudo groupadd docker +``` + Add your user to the docker group. - $ sudo usermod -aG docker $USER +``` +$ sudo usermod -aG docker $USER +``` (perhaps restart your computer (best) or (at min) open a new terminal to make sure that you are added from now on) - ## Notes and troubleshooting We dropped GUI support in 2.3.5+ due to too many numerous issues supporting them. Also please note these are tested on unix systems. From 31ae0de95c4ce136a9826085bc5250f673c3ae16 Mon Sep 17 00:00:00 2001 From: Cyril Achard Date: Tue, 12 May 2026 11:55:54 +0200 Subject: [PATCH 38/53] Apply suggestions from code review Credita to @deruyter92 Co-authored-by: Jaap de Ruyter van Steveninck <32810691+deruyter92@users.noreply.github.com> --- docs/beginner-guides/Training-Evaluation.md | 4 ++-- docs/beginner-guides/beginners-guide.md | 10 +++++----- docs/beginner-guides/labeling.md | 4 ++-- docs/beginner-guides/manage-project.md | 7 ++++--- docs/gui/napari/advanced_usage.md | 4 ++-- docs/gui/napari/basic_usage.md | 8 ++++---- 6 files changed, 19 insertions(+), 18 deletions(-) diff --git a/docs/beginner-guides/Training-Evaluation.md b/docs/beginner-guides/Training-Evaluation.md index c7885abdfc..a49d70820b 100644 --- a/docs/beginner-guides/Training-Evaluation.md +++ b/docs/beginner-guides/Training-Evaluation.md @@ -17,14 +17,14 @@ deeplabcut: ## Network training -### Creating a training set +### Creating a training dataset Before training your model, the first step is to assemble your training dataset. **Create Training Dataset:** Move to the corresponding tab and click **`Create Training Dataset`**. For starters, the default settings will do just fine. While there are more powerful models and data augmentations you might want to consider, you can trust that for most projects the defaults are a good place to start. ```{note} -This guide assumes you have a GPU on your local machine. If you're CPU-bound and training is not feasible, consider using Google Colab. Our [Colab Guide](https://colab.research.google.com/github/DeepLabCut/DeepLabCut/blob/master/examples/COLAB/COLAB_YOURDATA_TrainNetwork_VideoAnalysis.ipynb) can help you get started! +This guide assumes you have a (CUDA-enabled) GPU on your local machine. If you're CPU-bound and training is not feasible, consider using Google Colab. Our [Colab Guide](https://colab.research.google.com/github/DeepLabCut/DeepLabCut/blob/master/examples/COLAB/COLAB_YOURDATA_TrainNetwork_VideoAnalysis.ipynb) can help you get started! ``` ### Starting the training process diff --git a/docs/beginner-guides/beginners-guide.md b/docs/beginner-guides/beginners-guide.md index 1daf747e74..43bce7f1c1 100644 --- a/docs/beginner-guides/beginners-guide.md +++ b/docs/beginner-guides/beginners-guide.md @@ -143,7 +143,7 @@ When you first launch the GUI, you'll find three primary main options: Avoid empty spaces in your project name. ``` - - Fill in the name of the experimenter. This will be the permanent name associated with the project. + - Fill in the name of the experimenter. This name is used in data headers and directory names and it remains permanently associated with the project. 1. **Determine Project Location:** @@ -152,7 +152,7 @@ When you first launch the GUI, you'll find three primary main options: 1. **Multi-Animal or Single-Animal Project:** - - Tick the 'Multi-Animal' option in the menuif relevant to your experiment. + - Tick the 'Multi-Animal' option in the menu if relevant to your experiment. - Choose the 'Number of Cameras' as per your experiment. 1. **Adding Videos:** @@ -164,9 +164,9 @@ When you first launch the GUI, you'll find three primary main options: ``` - A list will be created with all the videos inside this folder. - Unselect the videos you wish to remove from the project. - - Videos can be automatically copied to the project folder by selecting the "Copy videos to project folder" option. This is recommended for data management and to avoid issues with moving files later on, but depends on your storage system and needs. + - Videos outside the project directory can be automatically copied into to the project folder by selecting the "Copy videos to project folder" option. This is the recommended strategy for data management. External videos that are not copied are instead referenced via symbolic links. While using symbolic links avoids duplicating files and reduces storage usage, it is also more prone to issues, for example if the original files are moved or deleted. - ```{tip} - By default, the GUI will look for **folders of videos**. Use the "Select individual files" + By default, the GUI will look for a **directory** containing videos. Use the "Select individual files" checkbox if you want to select individual videos instead of a whole folder. ``` @@ -174,7 +174,7 @@ When you first launch the GUI, you'll find three primary main options: - Enter all the name, numbers or IDs of bodyparts you wish to track. - **Example:** "head", "tail", "left paw", "right paw", etc. - - Less recommened: "L1", "L2", "L3", etc. + - Less recommended: "L1", "L2", "L3", etc. - **If you have multiple animals**: - Enter the name, numbers or IDs of the individuals in your experiment. - **Example:** "mouse1", "mouse2", "mouse3", etc. diff --git a/docs/beginner-guides/labeling.md b/docs/beginner-guides/labeling.md index d5ce8cbb9c..8692c0256c 100644 --- a/docs/beginner-guides/labeling.md +++ b/docs/beginner-guides/labeling.md @@ -59,7 +59,7 @@ Please refer to the {ref}`file:napari-dlc-basic-usage` section for a detailed wa Work through all the frames in the first folder and save them. ```{tip} -After saving, you can close napari and click **`Label Frames`* again to open the next folder +After saving, you can close napari and click **`Label Frames`** again to open the next folder **OR** Remove all layers in napari and drag-and-drop the next folder in the same napari session to keep going without needing to close and reopen napari. ``` @@ -68,7 +68,7 @@ Remove all layers in napari and drag-and-drop the next folder in the same napari After you've labeled all your frames, you may want to review their accuracy before moving on to training your model. This is a crucial step, as the quality of your labels will directly impact the performance of your model. -- **Return to the Main Window:** Once you're done with labeling, head back to DeepLabCut's main window, and click on **`Check Labels`**. +- **Return to the DeepLabCut GUI:** Once you're done with labeling, head back to DeepLabCut's main window, and click on **`Check Labels`**. - **Review the Labeled Folders:** The system will have created new folders for each labeled set inside your labeled-data folder. These folders contain your original frames overlaid with the keypoints you've added. ![Checking Labels in DeepLabCut](https://images.squarespace-cdn.com/content/v1/57f6d51c9f74566f55ecf271/1717779615252-6BNW661XB2ULH85RTAD3/evaluation-example.png?format=500w) diff --git a/docs/beginner-guides/manage-project.md b/docs/beginner-guides/manage-project.md index ce8ddcfee3..0faf7f3c52 100644 --- a/docs/beginner-guides/manage-project.md +++ b/docs/beginner-guides/manage-project.md @@ -47,9 +47,10 @@ After creating your DeepLabCut project, you'll be shown the main GUI window, whe - **Navigate to the Skeleton Section:** Scroll down to the **`skeleton`** category. - **Adjust the Skeleton List:** Click on the arrow to expand this section. - - You can then update the pairs of bodyparts to define the skeleton structure of your model. - - Each entry has an ID, starting from 0 (key) - - Each entry (value) under a key must then consist in a pair of bodyparts, which will be connected in the skeleton. + - You can then update the list of bodypart pairs: i.e. the connections that define the skeleton structure of your model. + - In the list of bodypart pairs, each pair has an index. (ranging from 0 to the total number of pairs in the skeleton). + - Each item of the pair (also indexed; 0 or 1) has a value: the name of the bodypart. + - Each pair of two bodyparts represents a connection, where all connections together make the skeleton. ![Defining the Skeleton Structure in Config File](https://images.squarespace-cdn.com/content/v1/57f6d51c9f74566f55ecf271/1717779598505-HQNECHIKSQ6XL033JX8M/skeleton.png?format=500w) diff --git a/docs/gui/napari/advanced_usage.md b/docs/gui/napari/advanced_usage.md index 20aaafd254..5b5f5aca29 100644 --- a/docs/gui/napari/advanced_usage.md +++ b/docs/gui/napari/advanced_usage.md @@ -25,7 +25,7 @@ This is the folder where annotations will be saved when using **File -> Save Sel ### Labeling progress -When a labeled data folder is loaded, the widget shows a percentage of labeled frames, based on the theoretical maximum number of keypoints (i.e. number of body parts x number of individuals x number of frames) that could be labeled. +When a labeled data folder is loaded, the widget shows a percentage of labeled frames, based on the theoretical maximum number of keypoints (i.e. number of bodyparts x number of individuals x number of frames) that could be labeled. ```{note} This can be a useful reference to track labeling progress.
@@ -46,7 +46,7 @@ To copy-paste keypoints from one frame to another: ## Color scheme display features -The plugin shows a list of body parts and their corresponding colors in the dock widget. You can toggle the visibility of this color scheme using the **Show color scheme** button. +The plugin shows a list of bodyparts and their corresponding colors in the dock widget. You can toggle the visibility of this color scheme using the **Show color scheme** button. ```{tip} The display only shows keypoints that are currently visible in the viewer.
diff --git a/docs/gui/napari/basic_usage.md b/docs/gui/napari/basic_usage.md index b10880e4a0..b9ba052bed 100644 --- a/docs/gui/napari/basic_usage.md +++ b/docs/gui/napari/basic_usage.md @@ -171,7 +171,7 @@ Keeping data inside the project directory is recommended for best compatibility. - napari-deeplabcut specific: - `M`: cycle through annotation modes - `E`: toggle edge coloring - - `F`: toggle between individual and body-part coloring modes + - `F`: toggle between individual and bodypart coloring modes - `V`: toggle visibility of the selected layer - `Backspace`: delete selected point(s) - `Ctrl+C` / `Ctrl+V`: copy and paste selected points @@ -182,7 +182,7 @@ Use the **View shortcuts** button in the dock widget for a quick reference of na ### More quality-of-life features -See the {ref}`Advanced features ` for useful features such as copy-pasting annotations, quick body part selection, and more. +See the {ref}`Advanced features ` for useful features such as copy-pasting annotations, quick bodypart selection, and more. ## Labeling workflows @@ -210,9 +210,9 @@ Use this when the folder already contains a `CollectedData_.h5` file - Open (or drag and drop) the folder in napari. Existing annotations and keypoint metadata will be loaded automatically from the H5 file. -In this case, loading `config.yaml` is usually **not needed** unless : +In this case, loading `config.yaml` is usually **not needed** unless: -- The project's body parts have changed or +- The project's bodyparts have changed or - You want to refresh the configured color scheme ### Refining machine labels From cc9bf79c21cd39bc82e01dbff21e856d2d75a2bb Mon Sep 17 00:00:00 2001 From: C-Achard Date: Tue, 12 May 2026 14:13:05 +0200 Subject: [PATCH 39/53] Separate GPU and cloud bullets; remove link Split the combined GPU/cloud sentence into two separate bullets for clarity. Removed the technical specs (FAQ) link from the GPU item and removed the troubleshooting wiki link at the bottom. Also cleaned up trailing newline/whitespace. --- docs/UseOverviewGuide.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/UseOverviewGuide.md b/docs/UseOverviewGuide.md index c88ae4e045..ead8471a93 100644 --- a/docs/UseOverviewGuide.md +++ b/docs/UseOverviewGuide.md @@ -78,7 +78,9 @@ We are primarily a package that enables deep learning-based pose estimation. We - **A set of videos that span the types of behaviors you want to track.** Having 10 videos that include different backgrounds, different individuals, and different postures is MUCH better than 1 or 2 videos of 1 or 2 different individuals (i.e. 10-20 frames from each of 10 videos is **much better** than 50-100 frames from 2 videos). -- **Ideally, a computer with a GPU.** If you want to use DeepLabCut on your own computer for training and/or for many experiments, then you should get an NVIDIA GPU. See technical specs [here](https://github.com/DeepLabCut/DeepLabCut/wiki/FAQ). You can also use cloud computing resources, including COLAB ([see how](https://github.com/DeepLabCut/DeepLabCut/blob/master/examples/README.md)). +- **Ideally, a computer with a GPU.** If you want to use DeepLabCut on your own computer for training and/or for many experiments, then you should get an NVIDIA GPU. + +- You can also use cloud computing resources, including COLAB ([see how](https://github.com/DeepLabCut/DeepLabCut/blob/master/examples/README.md)). ### What you DON'T need to get started @@ -236,4 +238,4 @@ Please decide with mode you want to use DeepLabCut, and follow one of the follow ## Useful links -Please read more in our Nature Protocols paper [here](https://www.nature.com/articles/s41596-019-0176-0). And, see our [troubleshooting wiki](https://github.com/DeepLabCut/DeepLabCut/wiki/Troubleshooting-Tips). +Please read more in our Nature Protocols paper [here](https://www.nature.com/articles/s41596-019-0176-0). From 983da40c446035b0b315eee4755861a22eb1badb Mon Sep 17 00:00:00 2001 From: C-Achard Date: Tue, 12 May 2026 14:13:46 +0200 Subject: [PATCH 40/53] Update README: TF backend, dataset links Simplify and update README text: streamline TensorFlow engine install instructions and add a planned deprecation target (tensorflow backend deprecated in v3.2). Replace prior dataset references with explicit Zenodo DOIs for SuperAnimal-Quadruped and SuperAnimal-TopViewMouse and add a citation to Ye et al. 2024. Clarify that models including AP-10K are available in the API/GUI, and fix minor wording in the funding acknowledgement ("following support"). --- README.md | 12 +++++------- 1 file changed, 5 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index d761906c58..365d201b99 100644 --- a/README.md +++ b/README.md @@ -74,11 +74,8 @@ pip install --pre "deeplabcut[gui]" or `pip install --pre "deeplabcut"` (headless version with PyTorch)! -To use the TensorFlow (TF) engine (requires Python 3.10; TF up to v2.10 supported on Windows, -up to v2.12 on other platforms): you'll need to run `pip install "deeplabcut[gui,tf]"` -(which includes all functions plus GUIs) or `pip install "deeplabcut[tf]"` (headless -version with PyTorch and TensorFlow). -We aim to deprecate the TF part in 2027. +To use the TensorFlow (TF) engine: you'll need to run `pip install "deeplabcut[gui,tf]"` or `pip install "deeplabcut[tf]"` (headless version with TF). +We aim to deprecate the tensorflow backend in version 3.2 (release date TBD). We recommend using our conda file, see [here](https://github.com/DeepLabCut/DeepLabCut/blob/main/conda-environments/README.md) or the [`deeplabcut-docker` package](https://github.com/DeepLabCut/DeepLabCut/tree/main/docker). @@ -116,7 +113,8 @@ In general, we provide all the tooling for you to train and use custom models wi We also provide two foundation pretrained animal models: `SuperAnimal-Quadruped` & `SuperAnimal-TopViewMouse`. To gauge their *out-of-distribution* performance, we provide the following tables. -These models are trained on the [SuperAnimal-Quadruped with AP-10K held out for out-of-domain testing]([https://cocodataset.org/](https://www.nature.com/articles/s41467-024-48792-2)) and the [SuperAnimal-TopViewMouse with DLC-openfield held out for out-of-distribution testing](https://www.nature.com/articles/s41467-024-48792-2). We provide models that include AP-10K in the API (and GUI). +These models are trained on the [SuperAnimal-Quadruped dataset](https://doi.org/10.5281/zenodo.10619172) with *AP-10K* held out for out-of-domain testing and the [SuperAnimal-TopViewMouse dataset](https://doi.org/10.5281/zenodo.13757509) with *DLC-openfield* held out for out-of-distribution testing (see [Ye et al. 2024](https://www.nature.com/articles/s41467-024-48792-2)). +We provide models that include AP-10K in the API (and GUI). Note, there are many different models to select from in DeepLabCut 3.0. We strongly recommend you check [this Guide](https://deeplabcut.github.io/DeepLabCut/docs/pytorch/architectures.html) for more details. This table, and those below, give you a sense of performance in real-world complex in-the-wild and lab mouse data, respectively. This [link provides the model weights](https://huggingface.co/mwmathis/DeepLabCutModelZoo-SuperAnimal-Quadruped) to reproduce the numbers; but please note, our `full` models are in our DLClibrary and released in the API. @@ -267,6 +265,6 @@ importing a project into the new data format for DLC 2.0 # Funding - We are grateful for the follow support over the years! + We are grateful for the following support and funding over the years! This software project was supported in part by the **Essential Open Source Software for Science (EOSS)** program at **Chan Zuckerberg Initiative** (cycles 1, 3, 3-DEI, 4), and jointly with the **Kavli Foundation** for **EOSS Cycle 6**! We also thank the **Rowland Institute** at **Harvard** for funding from 2017-2020, and **EPFL** from 2020-present. From 753ef224806a18b343e1ba1d5bbf2a11ec0068e6 Mon Sep 17 00:00:00 2001 From: C-Achard Date: Tue, 12 May 2026 14:14:59 +0200 Subject: [PATCH 41/53] Clarify Docker usage and napari limitation Update docs/docker.md to improve clarity and accuracy of Docker guidance. Reworded introduction to explain that DeepLabCut images are available on DockerHub, that Docker requires a local Docker installation, and that containers provide a reproducible, isolated environment for terminal and Jupyter use. Explicitly state the DeepLabCut GUI is not supported in containers and move/strengthen the important note that the napari-deeplabcut plugin cannot be run inside Docker and must be installed locally (e.g. via pip). Clarified that deeplabcut-docker is a lightweight helper that will not disrupt local TensorFlow/PyTorch or other dependencies, and fixed wording/formatting issues. --- docs/docker.md | 17 +++++++---------- 1 file changed, 7 insertions(+), 10 deletions(-) diff --git a/docs/docker.md b/docs/docker.md index eb95439e6a..dcfc23bf9d 100644 --- a/docs/docker.md +++ b/docs/docker.md @@ -12,16 +12,14 @@ deeplabcut: # DeepLabCut in Docker -For DeepLabCut 2.2.0.2 and onwards, we provide container containers on [DockerHub](https://hub.docker.com/r/deeplabcut/deeplabcut). Using Docker is an alternative approach -to using DeepLabCut, which only requires the user to install [Docker](https://www.docker.com/) on your machine, vs. following the step-by-step installation -guide for a Anaconda setup. All dependencies needed to run DeepLabCut in the terminal or -running Jupyter notebooks with DeepLabCut pre-installed are shipped with the provided -Docker images. +From DeepLabCut 2.2.0.2 onward, we provide container images on [DockerHub](https://hub.docker.com/r/deeplabcut/deeplabcut). +Using Docker is an alternative approach to installing DeepLabCut in a local conda or pip environment: the images bundle all dependencies needed to run DeepLabCut in a reproducible, self-contained environment. +In a Docker container, DeepLabCut can be used from the terminal, or with Jupyter notebook - the DeepLabCut GUI is not supported. +The approach requires a local installation of [Docker / Docker Desktop](https://www.docker.com/), and is meant for users who need strict reproducibility, an isolated environment, or server-based automation. ```{important} -The {ref}`napari-deeplabcut plugin ` can be used to label -your data, but it cannot be run in a Docker container: it should be installed as -documented in the link above: `pip install napari-deeplabcut` +The napari-deeplabcut plugin **cannot be run in a Docker container**. To label +your data, please {ref}`install napari-deeplabcut ` in a local, non-dockerized environment, e.g. using pip: `pip install napari-deeplabcut` . ``` Advanced users can directly head to [DockerHub](https://hub.docker.com/r/deeplabcut/deeplabcut) and use the provided images there. To get started with using the images, we however also provide a helper tool, `deeplabcut-docker`, which makes the transition to docker images particularly convenient; to install the tool, run @@ -30,8 +28,7 @@ Advanced users can directly head to [DockerHub](https://hub.docker.com/r/deeplab $ pip install deeplabcut-docker ``` -on your machine (potentially in a virtual environment, or an existing Anaconda environment). -Note that this will *not* disprupt or install Tensorflow, or any other DeepLabCut dependencies on your computer---the Docker containers are completely isolated from your existing software installation! +on your machine (in any environment). deeplabcut-docker is just a lightweight package for setting up the Docker environment and it will *not* disrupt your installation of TensorFlow, PyTorch or any other dependencies. The Docker container itself is completely isolated from your existing software installation! ## Usage modes From 7319208873ef46465290abef7ca23d59651e68ce Mon Sep 17 00:00:00 2001 From: C-Achard Date: Tue, 12 May 2026 14:16:24 +0200 Subject: [PATCH 42/53] Clarify training dataset creation steps Add brief guidance in the Training Dataset section to outline key steps (splitting labeled data and creating shuffle folders) so beginners have a clearer workflow before training. Also include a small formatting/whitespace adjustment in the GPU/Colab note. --- docs/beginner-guides/Training-Evaluation.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/docs/beginner-guides/Training-Evaluation.md b/docs/beginner-guides/Training-Evaluation.md index a49d70820b..09e1c7f2b8 100644 --- a/docs/beginner-guides/Training-Evaluation.md +++ b/docs/beginner-guides/Training-Evaluation.md @@ -17,14 +17,18 @@ deeplabcut: ## Network training -### Creating a training dataset +### Creating a training dataset Before training your model, the first step is to assemble your training dataset. +This involves: + +- Splitting labeled data into training and evaluation subsets +- Creating each shuffle folder with the model configuration ready for training. **Create Training Dataset:** Move to the corresponding tab and click **`Create Training Dataset`**. For starters, the default settings will do just fine. While there are more powerful models and data augmentations you might want to consider, you can trust that for most projects the defaults are a good place to start. ```{note} -This guide assumes you have a (CUDA-enabled) GPU on your local machine. If you're CPU-bound and training is not feasible, consider using Google Colab. Our [Colab Guide](https://colab.research.google.com/github/DeepLabCut/DeepLabCut/blob/master/examples/COLAB/COLAB_YOURDATA_TrainNetwork_VideoAnalysis.ipynb) can help you get started! +This guide assumes you have a (CUDA-enabled) GPU on your local machine. If you're CPU-bound and training is not feasible, consider using Google Colab. Our [Colab Guide](https://colab.research.google.com/github/DeepLabCut/DeepLabCut/blob/master/examples/COLAB/COLAB_YOURDATA_TrainNetwork_VideoAnalysis.ipynb) can help you get started! ``` ### Starting the training process From 94aa21361d5bf9250aeb925c37e73afb95f70ff4 Mon Sep 17 00:00:00 2001 From: C-Achard Date: Tue, 12 May 2026 14:16:45 +0200 Subject: [PATCH 43/53] Clarify labeling progress and color-scheme docs Update docs/gui/napari/advanced_usage.md to improve clarity and usability. Reword the labeling progress note to emphasize that the displayed percentage is a rough estimate and that occluded/hidden keypoints are not counted. Expand and simplify instructions for jumping to a bodypart from the color scheme by breaking into explicit steps and clarifying behavior when the bodypart is already visible. Minor wording/formatting cleanups for readability. --- docs/gui/napari/advanced_usage.md | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/docs/gui/napari/advanced_usage.md b/docs/gui/napari/advanced_usage.md index 5b5f5aca29..3ce04c4d5d 100644 --- a/docs/gui/napari/advanced_usage.md +++ b/docs/gui/napari/advanced_usage.md @@ -25,11 +25,11 @@ This is the folder where annotations will be saved when using **File -> Save Sel ### Labeling progress -When a labeled data folder is loaded, the widget shows a percentage of labeled frames, based on the theoretical maximum number of keypoints (i.e. number of bodyparts x number of individuals x number of frames) that could be labeled. +When a labeled data folder is loaded, the widget shows a percentage of labeled frames, based on the theoretical maximum number of keypoints (i.e. number of bodyparts x number of individuals x number of frames) that could be labeled. ```{note} This can be a useful reference to track labeling progress.
-Since visibility cannot be accounted for, it should be considered an estimate of relative labeling progress rather than an absolute measure of completeness. (as not all videos would need 100% labeling, i.e. every body part on every individual in every frame). +Since visibility cannot be accounted for, it should be considered only a rough estimate of relative labeling progress rather than an absolute measure of completeness: hidden/occluded keypoints are not counted, therefore projects with occlusions will not have every body part on every individual in every frame. ``` ### Point size slider @@ -46,7 +46,7 @@ To copy-paste keypoints from one frame to another: ## Color scheme display features -The plugin shows a list of bodyparts and their corresponding colors in the dock widget. You can toggle the visibility of this color scheme using the **Show color scheme** button. +The plugin shows a list of bodyparts and their corresponding colors in the dock widget. You can toggle the visibility of this color scheme using the **Show color scheme** button. ```{tip} The display only shows keypoints that are currently visible in the viewer.
@@ -63,7 +63,11 @@ In individual coloring mode, the color scheme also shows the individuals list, a ### Jump to body part in viewer -If showing all body parts in the color scheme from the config, clicking on a keypoint in the list that is not currently visible in the viewer will jump to the first instance of that body part in the viewer and select it, if applicable. +To locate a bodypart label that is currently not visible in the viewer, enable "Show all bodyparts" in the color scheme list. +Then, click on a bodypart entry in the color scheme list. +The viewer will jump to the first instance of that body part and select it (when it exists). +If the bodypart is already visible in the viewer, clicking on it in the color scheme will simply select all keypoints of that bodypart, as described above. + This helps quickly find a specific body part in the viewer. ## Trajectory plot From 483de19fba38e682778755789d60e09990f62d04 Mon Sep 17 00:00:00 2001 From: C-Achard Date: Tue, 12 May 2026 14:17:13 +0200 Subject: [PATCH 44/53] Relocate demo video link; cleanup whitespace Move the demo video link to appear before the warning block and tidy up minor whitespace/trailing-space issues in docs/gui/napari/basic_usage.md. These are formatting-only changes and do not alter substantive content. --- docs/gui/napari/basic_usage.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/docs/gui/napari/basic_usage.md b/docs/gui/napari/basic_usage.md index b9ba052bed..5e126b0727 100644 --- a/docs/gui/napari/basic_usage.md +++ b/docs/gui/napari/basic_usage.md @@ -171,7 +171,7 @@ Keeping data inside the project directory is recommended for best compatibility. - napari-deeplabcut specific: - `M`: cycle through annotation modes - `E`: toggle edge coloring - - `F`: toggle between individual and bodypart coloring modes + - `F`: toggle between individual and bodypart coloring modes - `V`: toggle visibility of the selected layer - `Backspace`: delete selected point(s) - `Ctrl+C` / `Ctrl+V`: copy and paste selected points @@ -182,7 +182,7 @@ Use the **View shortcuts** button in the dock widget for a quick reference of na ### More quality-of-life features -See the {ref}`Advanced features ` for useful features such as copy-pasting annotations, quick bodypart selection, and more. +See the {ref}`Advanced features ` for useful features such as copy-pasting annotations, quick bodypart selection, and more. ## Labeling workflows @@ -210,9 +210,9 @@ Use this when the folder already contains a `CollectedData_.h5` file - Open (or drag and drop) the folder in napari. Existing annotations and keypoint metadata will be loaded automatically from the H5 file. -In this case, loading `config.yaml` is usually **not needed** unless: +In this case, loading `config.yaml` is usually **not needed** unless: -- The project's bodyparts have changed or +- The project's bodyparts have changed or - You want to refresh the configured color scheme ### Refining machine labels @@ -277,8 +277,9 @@ This helps keep saving behavior unambiguous. A short demo video is available here: +[Link to video](https://youtu.be/hsA9IB5r73E) + ```{warning} This demo may be outdated, but the general annotation workflow remains the same. If you would like an updated video tutorial, please open a feature request issue on GitHub, and we will update it. -[Link to video](https://youtu.be/hsA9IB5r73E) ``` From c0be68908d51de0ad84e032a064dbf9d98239839 Mon Sep 17 00:00:00 2001 From: Cyril Achard Date: Thu, 21 May 2026 12:01:13 +0200 Subject: [PATCH 45/53] Update installation.md --- docs/installation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/installation.md b/docs/installation.md index d0403bd36a..137e361bb3 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -163,7 +163,7 @@ class: dropdown 💡 **PyTorch and TensorFlow Support within DeepLabCut** As of June 2024 we have a PyTorch Engine backend and we will be deprecating the -TensorFlow backend by 2027. +TensorFlow backend by version 3.2 latest (TBD). Currently, if you want to use TensorFlow, you need to run `pip install deeplabcut[tf]` in order to install the correct version of TensorFlow in your conda env. From d6e6e74c1370775dbcabc1e404291b6d57262046 Mon Sep 17 00:00:00 2001 From: Cyril Achard Date: Thu, 21 May 2026 16:19:13 +0200 Subject: [PATCH 46/53] Fix docs formatting, typos and image tags MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Clean up documentation across multiple files: add quotes to image src attributes, correct typos (e.g. "oher"→"other", "built"→"build", "compartimentalized"→"compartmentalized"), normalize admonition/code-block syntax, adjust cross-reference/link syntax, and make minor wording/grammar improvements. Affected files include docs/README.md, UseOverviewGuide.md, beginner-guides/*, course.md, docker.md, gui/PROJECT_GUI.md, and installation.md. --- docs/README.md | 3 +++ docs/UseOverviewGuide.md | 10 +++++----- docs/beginner-guides/Training-Evaluation.md | 2 +- docs/beginner-guides/beginners-guide.md | 3 ++- docs/beginner-guides/manage-project.md | 4 ++-- docs/beginner-guides/video-analysis.md | 10 ++++------ docs/course.md | 6 +++--- docs/docker.md | 11 ++++++----- docs/gui/PROJECT_GUI.md | 7 +++---- docs/installation.md | 16 +++++++--------- 10 files changed, 36 insertions(+), 36 deletions(-) diff --git a/docs/README.md b/docs/README.md index 59de51578f..00b76cff14 100644 --- a/docs/README.md +++ b/docs/README.md @@ -4,8 +4,11 @@ deeplabcut: last_metadata_updated: '2026-03-06' ignore: false --- + + + Please see https://deeplabcut.github.io/DeepLabCut for documentation on how to use this software. This directory contains the source code for the docs. diff --git a/docs/UseOverviewGuide.md b/docs/UseOverviewGuide.md index ead8471a93..7c5f9565f2 100644 --- a/docs/UseOverviewGuide.md +++ b/docs/UseOverviewGuide.md @@ -20,7 +20,7 @@ Below we will first outline what you need to get started, the different ways you **DeepLabCut** is a software package for markerless pose estimation of animals performing various tasks. The software can manage multiple projects for various tasks. Each project is identified by the name of the project (e.g. TheBehavior), name of the experimenter (e.g. YourName), as well as the date at creation. This project folder holds a `config.yaml` (a text document) file containing various (project) parameters as well as links the data of the project.

- +

@@ -49,13 +49,13 @@ We are primarily a package that enables deep learning-based pose estimation. We - If these terms are new to you, check out our [Primer on Motion Capture with Deep Learning!](https://www.sciencedirect.com/science/article/pii/S0896627320307170). In brief, both work for single or multiple animals and each method can be better or worse on your data.

- +

- Here is more information on BUCTD:

- +

### Additional learning resources @@ -68,7 +68,7 @@ We are primarily a package that enables deep learning-based pose estimation. We - [Explanations:](https://github.com/DeepLabCut/DeepLabCut-Workshop-Materials) resources on understanding how DeepLabCut works - [References:](https://github.com/DeepLabCut/DeepLabCut#references) read the science behind DeepLabCut -- \[Beginner Guide to the GUI\](file:beginners-guide) +- {ref}`Beginner's guide to the GUI`: a step-by-step walkthrough of the GUI for new users. @@ -106,7 +106,7 @@ You can have DeepLabCut installed in a {ref}`conda environment - +

(important-info-regd-usage)= diff --git a/docs/beginner-guides/Training-Evaluation.md b/docs/beginner-guides/Training-Evaluation.md index 09e1c7f2b8..c106b8982c 100644 --- a/docs/beginner-guides/Training-Evaluation.md +++ b/docs/beginner-guides/Training-Evaluation.md @@ -6,7 +6,7 @@ deeplabcut: visibility: online status: viable recommendation: move - notes: As mentioned on oher beginner-guides/ docs, this should be part of the GUI section. + notes: As mentioned on other beginner-guides/ docs, this should be part of the GUI section. --- (file:training-evaluation-gui)= diff --git a/docs/beginner-guides/beginners-guide.md b/docs/beginner-guides/beginners-guide.md index 47ad7e1d74..b73637604b 100644 --- a/docs/beginner-guides/beginners-guide.md +++ b/docs/beginner-guides/beginners-guide.md @@ -104,7 +104,8 @@ This will open DeepLabCut. ![DeepLabCut GUI Screenshot](https://images.squarespace-cdn.com/content/v1/57f6d51c9f74566f55ecf271/1717779625875-5UHPC367I293CBSP8CT6/GUI-screenshot.png?format=500w) -```{note} For a visual guide on navigating through the DeepLabCut GUI, check out our [YouTube tutorial](https://www.youtube.com/watch?v=tr3npnXWoD4). +```{note} +For a visual guide on navigating through the DeepLabCut GUI, check out our [YouTube tutorial](https://www.youtube.com/watch?v=tr3npnXWoD4). ``` ## Starting a new project diff --git a/docs/beginner-guides/manage-project.md b/docs/beginner-guides/manage-project.md index 3fc478c8b8..fd091a2c44 100644 --- a/docs/beginner-guides/manage-project.md +++ b/docs/beginner-guides/manage-project.md @@ -48,9 +48,9 @@ After creating your DeepLabCut project, you'll be shown the main GUI window, whe - **Navigate to the Skeleton Section:** Scroll down to the **`skeleton`** category. - **Adjust the Skeleton List:** Click on the arrow to expand this section. - You can then update the list of bodypart pairs: i.e. the connections that define the skeleton structure of your model. - - In the list of bodypart pairs, each pair has an index. (ranging from 0 to the total number of pairs in the skeleton). + - In the list of bodypart pairs, each pair has an index. (ranging from 0 to the total number of pairs in the skeleton). - Each item of the pair (also indexed; 0 or 1) has a value: the name of the bodypart. - - Each pair of two bodyparts represents a connection, where all connections together make the skeleton. + - Each pair of two bodyparts represents a connection, where all connections together make the skeleton. ![Defining the Skeleton Structure in Config File](https://images.squarespace-cdn.com/content/v1/57f6d51c9f74566f55ecf271/1717779598505-HQNECHIKSQ6XL033JX8M/skeleton.png?format=500w) diff --git a/docs/beginner-guides/video-analysis.md b/docs/beginner-guides/video-analysis.md index ac667881b4..842ee78506 100644 --- a/docs/beginner-guides/video-analysis.md +++ b/docs/beginner-guides/video-analysis.md @@ -6,7 +6,7 @@ deeplabcut: visibility: online status: viable recommendation: move - notes: As mentioned on oher beginner-guides/ docs, this should be part of the GUI section. + notes: As mentioned on other beginner-guides/ docs, this should be part of the GUI section. --- (file:video-analysis-gui)= @@ -23,11 +23,9 @@ After training and evaluating your model, the next step is to apply it to your v 1. **Navigate to the 'Analyze Videos' Tab:** Begin applying your trained model to video data here. 1. **Select Your Video Format and Files:** - -- **Choose Video Format:** Pick the format of your video (`.mp4`, `.avi`, `.mkv`, or `.mov`). -- **Select Videos:** Click **`Select Videos`** to find and open your video file. - -3. **Start Analysis:** Click **`Analyze`**. The analysis time depends on video length and resolution. Track progress in the terminal or Anaconda prompt. + - **Choose Video Format:** Pick the format of your video (`.mp4`, `.avi`, `.mkv`, or `.mov`). + - **Select Videos:** Click **`Select Videos`** to find and open your video file. +1. **Start Analysis:** Click **`Analyze`**. The analysis time depends on video length and resolution. Track progress in the terminal or Anaconda prompt. ### Reviewing analysis results diff --git a/docs/course.md b/docs/course.md index 94d4c24d0f..a1364ef8d9 100644 --- a/docs/course.md +++ b/docs/course.md @@ -10,10 +10,10 @@ deeplabcut: # DeepLabCut Self-paced Course -::::\{warning} +```{warning} This course was designed for DLC 2. An updated version for DLC 3 is in the works. -:::: +``` Do you have video of animal behaviors? Step 1: Get Poses ... @@ -32,7 +32,7 @@ We expect it to take *roughly* 1-2 weeks to get through if you do it rigorously. You need Python and DeepLabCut installed! -- \[See these "beginner docs" for help!\](file:beginners-guide) +- See the {ref}`beginners-guide` for help! - **WATCH:** overview of conda: [Python Tutorial: Anaconda - Installation and Using Conda](https://www.youtube.com/watch?v=YJC6ldI3hWk) diff --git a/docs/docker.md b/docs/docker.md index dcfc23bf9d..a2d539b1c0 100644 --- a/docs/docker.md +++ b/docs/docker.md @@ -14,7 +14,7 @@ deeplabcut: From DeepLabCut 2.2.0.2 onward, we provide container images on [DockerHub](https://hub.docker.com/r/deeplabcut/deeplabcut). Using Docker is an alternative approach to installing DeepLabCut in a local conda or pip environment: the images bundle all dependencies needed to run DeepLabCut in a reproducible, self-contained environment. -In a Docker container, DeepLabCut can be used from the terminal, or with Jupyter notebook - the DeepLabCut GUI is not supported. +In a Docker container, DeepLabCut can be used from the terminal, or with Jupyter notebooks; the DeepLabCut GUI is not supported. The approach requires a local installation of [Docker / Docker Desktop](https://www.docker.com/), and is meant for users who need strict reproducibility, an isolated environment, or server-based automation. ```{important} @@ -34,11 +34,12 @@ on your machine (in any environment). deeplabcut-docker is just a lightweight pa With `deeplabcut-docker`, you can use the images in two modes. -```{note} -1. When running any of the following commands first, it can take some time to complete (a few minutes, depending on your internet connection), since it downloads the Docker image in the background. If you do not see any errors in your terminal, assume that everything is working fine! Subsequent runs of the command will be faster.* -1. For any mode below, you might want to set which directory is the base, namely, so you can have read/write (or read-only access). Here is how to do so: - If you want to mount the whole directory could e.g., pass* + +```{note} +1. When running any of the following commands first, it can take some time to complete (a few minutes, depending on your internet connection), since it downloads the Docker image in the background. If you do not see any errors in your terminal, assume that everything is working fine! Subsequent runs of the command will be faster. +2. For any mode below, you might want to set which directory is the base, namely, so you can have read/write (or read-only access). Here is how to do so: + If you want to mount the whole directory could e.g., pass `deeplabcut-docker bash -v /home/mackenzie/DEEPLABCUT:/home/mackenzie/DEEPLABCUT` (which will mount the full directory into the container in read/write mode) If read-only access is enough, `deeplabcut-docker bash -v /home/mackenzie/DEEPLABCUT:/home/mackenzie/DEEPLABCUT:ro` diff --git a/docs/gui/PROJECT_GUI.md b/docs/gui/PROJECT_GUI.md index fc450bd648..a4303e193b 100644 --- a/docs/gui/PROJECT_GUI.md +++ b/docs/gui/PROJECT_GUI.md @@ -6,7 +6,7 @@ deeplabcut: visibility: online status: review_needed recommendation: update - notes: 'While the content is generally accurate, repeating installation instructions is not ideal. I would suggest linking to the installation guide instead of re-suggesting commmands but then still saying to read the install page... Also, the GUI is likely used by the majority of users, so I would even consider making this a full section in the TOC, and maybe even having one file per GUI tab, which would make tracking code/docs sync easier. Addendum: it seems the beginner guide section is more of a GUI step-by-step, as mentioned earlier in this comment. I would suggest merging/moving and adding links in the present doc, which would make it less of a video list and more of a proper GUI guide.' + notes: 'While the content is generally accurate, repeating installation instructions is not ideal. I would suggest linking to the installation guide instead of re-suggesting commands but then still saying to read the install page... Also, the GUI is likely used by the majority of users, so I would even consider making this a full section in the TOC, and maybe even having one file per GUI tab, which would make tracking code/docs sync easier. Addendum: it seems the beginner guide section is more of a GUI step-by-step, as mentioned earlier in this comment. I would suggest merging/moving and adding links in the present doc, which would make it less of a video list and more of a proper GUI guide.' --- (project-manager-gui)= @@ -27,15 +27,14 @@ While several advanced features are not fully available in this Project GUI, we

-Start at the Project Management Tab and work your way through the tabs to built your customized model and deploy it on new data. +Start at the Project Management Tab and work your way through the tabs to build your customized model and deploy it on new data. We recommend to keep the terminal visible (as well as the GUI) so you can see the ongoing processes as you step through your project, or any errors that might arise. - For specific napari-based labeling features, see the {ref}`napari gui` section. - To change from dark to light mode, set appearance at the top:

- +

## User guide diff --git a/docs/installation.md b/docs/installation.md index 137e361bb3..e2c624b6f0 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -40,9 +40,8 @@ If you have an NVIDIA GPU, install PyTorch according to [their instructions](htt conda create -n DEEPLABCUT python=3.12 conda activate DEEPLABCUT -# install PyTorch with your desired CUDA version (or for CPU only) - check [their -](https://pytorch.org/get-started/locally/) website: -# GPU version of pytorch for CUDA 11.3 +# Install PyTorch with your desired CUDA version (or CPU only) +# Example: GPU version of pytorch for CUDA 11.3 conda install pytorch cudatoolkit=11.3 -c pytorch # install the latest version of DeepLabCut @@ -232,8 +231,7 @@ Please see how to test your installation by following [this video](https://www.y Recommended for users who want to modify the code, or want to be up-to-date with the latest code on GitHub. -- **Windows/Linux/MacBooks:** git clone this repo (in the terminal/cmd program, while **in a folder** you wish to place DeepLabCut -- To git clone run: `git clone https://github.com/DeepLabCut/DeepLabCut.git`) +- To clone the repository run: `git clone https://github.com/DeepLabCut/DeepLabCut.git` - Then follow the same steps as in Step 2 above, adjusting for the `DEEPLABCUT.yaml` env file now being in the folder where you git cloned the repo. - Or use pip/uv to install from the cloned repo (see below). @@ -252,7 +250,7 @@ source .venv/bin/activate # or & .venv\Scripts\activate.ps1 on Windows ### `pip` -If you already have a local environment, everything you need to use the project manager GI, train and/or build custom models within DeepLabCut (i.e., use our source code and our dependencies) can be installed with `pip install 'deeplabcut[gui]'` (for GUI support w/PyTorch) or without the gui: `pip install 'deeplabcut'`. +If you already have a local environment, everything you need to use the project manager GUI, train and/or build custom models within DeepLabCut (i.e., use our source code and our dependencies) can be installed with `pip install 'deeplabcut[gui]'` (for GUI support w/PyTorch) or without the gui: `pip install 'deeplabcut'`. - If you **cloned the repo** and want to make edits to the code locally, navigate to the cloned repo folder and run `pip install -e .[gui,modelzoo,tf]` to install the package in "editable" mode, which allows you to make changes to the code and have those changes reflected when you import the package. - If you want to use the SuperAnimal models, then please use `pip install 'deeplabcut[gui,modelzoo]'`. @@ -329,8 +327,8 @@ Thus, you do not need to independently install tensorflow. ### Notes -- **As of version 3.0+ we moved to PyTorch. The Last supported version of TensorFlow is - 2.10 (window users) and 2.12 for others** (We will not be testing beyond this) +- **As of version 3.0+ we moved to PyTorch. The last supported version of TensorFlow is + 2.10 (for Windows users) and 2.12 for others**. Support will not be provided for future versions. - Please be mindful different versions of TensorFlow require different CUDA versions. @@ -383,7 +381,7 @@ Here are some additional resources users have found helpful (posted without endo ```{note} **What is a system-wide installation?** -A system-wide installation, or a base environment installation, is when you install using the default Python environment/interpreter on your computer, instead of a compartimentalized, separate environment (e.g., a conda environment). +A system-wide installation, or a base environment installation, is when you install using the default Python environment/interpreter on your computer, instead of a compartmentalized, separate environment (e.g., a conda environment). This is often a source of conflicts between packages, user confusion and progressive "dependency hell" (where you have to keep installing and uninstalling packages to get the right versions for different applications). From e5418a326e4cc50805782183e3cd6e4ff976791a Mon Sep 17 00:00:00 2001 From: Cyril Achard Date: Thu, 21 May 2026 17:39:01 +0200 Subject: [PATCH 47/53] Fix typo Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- docs/beginner-guides/beginners-guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/beginner-guides/beginners-guide.md b/docs/beginner-guides/beginners-guide.md index b73637604b..6b53144d53 100644 --- a/docs/beginner-guides/beginners-guide.md +++ b/docs/beginner-guides/beginners-guide.md @@ -165,7 +165,7 @@ When you first launch the GUI, you'll find three primary main options: ``` - A list will be created with all the videos inside this folder. - Unselect the videos you wish to remove from the project. - - Videos outside the project directory can be automatically copied into to the project folder by selecting the "Copy videos to project folder" option. This is the recommended strategy for data management. External videos that are not copied are instead referenced via symbolic links. While using symbolic links avoids duplicating files and reduces storage usage, it is also more prone to issues, for example if the original files are moved or deleted. + - Videos outside the project directory can be automatically copied into the project folder by selecting the "Copy videos to project folder" option. This is the recommended strategy for data management. External videos that are not copied are instead referenced via symbolic links. While using symbolic links avoids duplicating files and reduces storage usage, it is also more prone to issues, for example if the original files are moved or deleted. - ```{tip} By default, the GUI will look for a **directory** containing videos. Use the "Select individual files" checkbox if you want to select individual videos instead of a whole folder. From e02df06bc79bde486349fe898f051cf825cb11d1 Mon Sep 17 00:00:00 2001 From: C-Achard Date: Fri, 22 May 2026 10:06:12 +0200 Subject: [PATCH 48/53] Docs: add external data import recipe Add a new recipe (docs/recipes/external_data_import.md) describing how to convert externally annotated data (CSV/H5) into the DeepLabCut format and how to merge multiple datasets (uses deeplabcut.convertcsv2h5). Update docs/installation.md to use a local Sphinx cross-reference for the Conda section, add the section anchor (sec:installation-using-conda), and fix the uv pip install line to quote the extras ('.[gui,modelzoo,tf]') to avoid shell globbing. Also add a file anchor (file:hardware-requirements)= to docs/recipes/TechHardware.md for cross-references. --- docs/installation.md | 6 ++++-- docs/recipes/TechHardware.md | 11 ++++++---- docs/recipes/external_data_import.md | 31 ++++++++++++++++++++++++++++ 3 files changed, 42 insertions(+), 6 deletions(-) create mode 100644 docs/recipes/external_data_import.md diff --git a/docs/installation.md b/docs/installation.md index e2c624b6f0..4402ffeff8 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -23,7 +23,7 @@ deeplabcut: - 🚧 Please note, there are several possibilities for installation: - - **Recommended for most users**: Install in a [**conda environment**](https://deeplabcut.github.io/DeepLabCut/docs/installation.html#conda-the-installation-process-is-as-easy-as-this-figure) + - **Recommended for most users**: Install in a {ref}`conda environment ` - Install with **{ref}`uv `** (recommended for developers) - In the supplied **{ref}`Docker container `** (recommended for Ubuntu advanced users and reproducibility). - 🚀 You will get the best performance when using a **GPU**! @@ -57,6 +57,8 @@ python -c "import torch; print(torch.cuda.is_available())" - If you're familiar with the command line and want TensorFlow support, look {ref}`below ` for a fresh installation on Linux and makes it possible to use the GPU with both PyTorch and TensorFlow. +(sec:installation-using-conda)= + ## Using Conda DLC @@ -244,7 +246,7 @@ Recommended for users who want to modify the code, or want to be up-to-date with ```bash uv venv -p 3.12 -uv pip install -e .[gui,modelzoo,tf] # Change optional install as needed +uv pip install -e '.[gui,modelzoo,tf]' # Change optional install as needed source .venv/bin/activate # or & .venv\Scripts\activate.ps1 on Windows ``` diff --git a/docs/recipes/TechHardware.md b/docs/recipes/TechHardware.md index 9ab75ade22..9eac85b9fc 100644 --- a/docs/recipes/TechHardware.md +++ b/docs/recipes/TechHardware.md @@ -4,9 +4,13 @@ deeplabcut: last_metadata_updated: '2026-03-06' ignore: false --- + +(file:hardware-requirements)= + # Technical (Hardware) Considerations ## Quick summary: + [On our install page](tech-considerations-during-install) we highlight that for GPU computing through standard installation you need a NVIDIA GPU, with at least 8 GB of memory. If you have an Intel or AMD GPU, and are on windows, there is an alternative method of installation available which is shown on the [installation tips page](installation-tips) under "How to install Deeplabcut for Intel and AMD GPUs". Note, some info is repeated here, and will be updated as systems and hardware changes. @@ -17,7 +21,7 @@ For reference, we use e.g. Dell workstations (79xx series) with **Ubuntu 16.04 L ### Computer Hardware: -Ideally, you will use a strong GPU with *at least* 8GB memory such as the [NVIDIA GeForce 1080 Ti, 2080 Ti, or 3090](https://marketplace.nvidia.com/en-us/consumer/graphics-cards/). A GPU is not strictly necessary, but on a CPU the (training and evaluation) code is considerably slower (10x) for ResNets, but MobileNets and EfficientNets are slightly faster. Still, a GPU will give you a massive speed boost. You might also consider using cloud computing services like [Google cloud/amazon web services](https://github.com/DeepLabCut/DeepLabCut/issues/47) or Google Colaboratory. +Ideally, you will use a strong GPU with *at least* 8GB memory such as the [NVIDIA GeForce 1080 Ti, 2080 Ti, or 3090](https://marketplace.nvidia.com/en-us/consumer/graphics-cards/). A GPU is not strictly necessary, but on a CPU the (training and evaluation) code is considerably slower (10x) for ResNets, but MobileNets and EfficientNets are slightly faster. Still, a GPU will give you a massive speed boost. You might also consider using cloud computing services like [Google cloud/amazon web services](https://github.com/DeepLabCut/DeepLabCut/issues/47) or Google Colaboratory. ```{note} If you encounter errors during inference related to @@ -32,7 +36,7 @@ The software is very robust to track data from any camera (cell phone cameras, g ### Software: -**Operating System:** Linux (Ubuntu), MacOS* (Mojave), or Windows 10. However, the authors strongly recommend Ubuntu! *MacOS does not support NVIDIA GPUs (easily), so we only suggest this option for CPU use or a case where the user wants to label data, refine data, etc and then push the project to a cloud resource for GPU computing steps, or use MobileNets. +**Operating System:** Linux (Ubuntu), MacOS\* (Mojave), or Windows 10. However, the authors strongly recommend Ubuntu! \*MacOS does not support NVIDIA GPUs (easily), so we only suggest this option for CPU use or a case where the user wants to label data, refine data, etc and then push the project to a cloud resource for GPU computing steps, or use MobileNets. **Anaconda/Python3:** Anaconda: a free and open source distribution of the Python programming language (download from https://www.anaconda.com/). DeepLabCut is written in Python 3 (https://www.python.org/) and not compatible with Python 2. @@ -48,8 +52,7 @@ DeepLabCut on your own computer/data before purchasing a GPU, with the added ben a straightforward installation! Otherwise, use our COLAB notebooks for GPU access for testing. -Docker: We highly recommend advanced users use the supplied [Docker container]( -docker-containers). +Docker: We highly recommend advanced users use the supplied [Docker container](docker-containers). NOTE: [Currently GPU support in Docker Desktop is only available on Windows with the WSL2 backend.](https://docs.docker.com/desktop/features/gpu/) diff --git a/docs/recipes/external_data_import.md b/docs/recipes/external_data_import.md new file mode 100644 index 0000000000..739ae4971f --- /dev/null +++ b/docs/recipes/external_data_import.md @@ -0,0 +1,31 @@ +(file:recipe-importing-data)= + +# Importing annotated data from elsewhere + +## Using data labeled elsewhere + +Some users may have annotation data in different formats, yet want to use the DLC pipeline. In this case, you need to convert the data to our format. Simply, you can format your data in an excel sheet (.csv file) or pandas array (.h5 file). + +Here is a guide to do this via the ".csv" route: (the pandas array route is identical, just format the pandas array in the same way). + +1. Create a project + +1. Edit the `config.yaml` file to include the body part names, please take care that spelling, spacing, and capitalization are IDENTICAL to the "labeled data body part names". + +1. Please inspect the excel formatted sheet (.csv) from our [demo project](https://github.com/DeepLabCut/DeepLabCut/tree/main/examples/Reaching-Mackenzie-2018-08-30/labeled-data/reachingvideo1) + + - e.g. see [this file](https://github.com/DeepLabCut/DeepLabCut/blob/main/examples/Reaching-Mackenzie-2018-08-30/labeled-data/reachingvideo1/CollectedData_Mackenzie.csv) + +1. Edit the .csv file such that it contains the X, Y pixel coordinates, the body part names, the scorer name as well as the relative path to the image: e.g. /labeled-data/somefolder/img017.jpg + Then make sure the scorer name, and body parts are the same in the config.yaml file. + Also add for each folder a video to the `video_set` in the config.yaml file. + This can also be a dummy variable, but should be e.g. `C://somefolder.avi` if the folder is called `somefolder`. See demo config.yaml file for proper formatting. + +1. When you are done, run `deeplabcut.convertcsv2h5('path_to_config.yaml', scorer= 'experimenter')` + +- The scorer name must be identical to the input name for experimenter that you used when you created the project. This will automatically update "Mackenzie" to your name in the example demo notebook. + +## Merging multiple datasets + +1. Rename the CSV files to be the target name. +1. Run and pass the target name `deeplabcut.convertcsv2h5('path_to_config.yaml', scorer= 'experimenter')`. This will overwrite the H5 file so the data is all merged under the target name. From e9125612237519b6c618c1ac5273dc953cc1d2ca Mon Sep 17 00:00:00 2001 From: C-Achard Date: Fri, 22 May 2026 10:11:00 +0200 Subject: [PATCH 49/53] Refine wording and links in user guides Small editorial updates to user documentation for clarity and better Sphinx linking. In docs/UseOverviewGuide.md: use inline `help` function wording, rephrase 'jump back in' to 'resume work' for clarity, and replace the 'Option 3' Project Manager GUI link with a Sphinx {ref} cross-reference. In docs/beginner-guides/beginners-guide.md: change the tip to 'Avoid spaces' and emphasize the scorer/experimenter field. These changes improve readability and consistency. --- docs/UseOverviewGuide.md | 6 +++--- docs/beginner-guides/beginners-guide.md | 4 ++-- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/UseOverviewGuide.md b/docs/UseOverviewGuide.md index 7c5f9565f2..7cc1069b55 100644 --- a/docs/UseOverviewGuide.md +++ b/docs/UseOverviewGuide.md @@ -90,7 +90,7 @@ We are primarily a package that enables deep learning-based pose estimation. We ## Workflow overview -This page contains a list of the essential functions of DeepLabCut as well as demos. There are many optional parameters with each described function. For detailed function documentation, please refer to the main user guides or API documentation. For additional assistance, you can use the [help](UseOverviewGuide.md#help) function to better understand what each function does. +This page contains a list of the essential functions of DeepLabCut as well as demos. There are many optional parameters with each described function. For detailed function documentation, please refer to the main user guides or API documentation. For additional assistance, you can use the `help` function to better understand what each function does.

@@ -103,7 +103,7 @@ This page contains a list of the essential functions of DeepLabCut as well as de You can have as many projects on your computer as you wish. You can have DeepLabCut installed in a {ref}`conda environment`; once you are finished, exit your terminal, and later re-activate your environment. -When working on a given project, you just need to point to the correct `config.yaml` file to [jump back in](/docs/UseOverviewGuide.md#tips-for-daily-use)! The documentation below will take you through the individual steps. +When working on a given project, you just need to point to the correct `config.yaml` file to resume work; the documentation below will take you through the individual steps.

@@ -159,7 +159,7 @@ If you can tell them apart, label your animals consistently! ### Getting started with multi-animal (ma) DeepLabCut -We highly recommend using it first in the Project Manager GUI ([Option 3](docs/functionDetails.md#deeplabcut-project-manager-gui)). +We highly recommend using it first in the {ref}`Project Manager GUI `. This will allow you to get used to the additional steps by being walked through the process. Then, you can always use all the functions in your favorite IDE, notebooks, etc. ## How to run DeepLabCut diff --git a/docs/beginner-guides/beginners-guide.md b/docs/beginner-guides/beginners-guide.md index 6b53144d53..7a79a5e978 100644 --- a/docs/beginner-guides/beginners-guide.md +++ b/docs/beginner-guides/beginners-guide.md @@ -141,10 +141,10 @@ When you first launch the GUI, you'll find three primary main options: - Give a specific, easy-to-track name to your project. ```{tip} - Avoid empty spaces in your project name. + Avoid spaces in your project name. ``` - - Fill in the name of the experimenter. This name is used in data headers and directory names and it remains permanently associated with the project. + - **Fill in the name of the scorer/experimenter**. This name is used in data headers and directory names and it remains permanently associated with the project. 1. **Determine Project Location:** From 058da2e9608692bdcfdb001aca18a8013d85e931 Mon Sep 17 00:00:00 2001 From: C-Achard Date: Fri, 22 May 2026 10:40:58 +0200 Subject: [PATCH 50/53] Convert internal docs links to Sphinx refs Replace Markdown-style internal links with Sphinx/MyST cross-reference syntax and adjust anchors/formatting for proper rendering. Updated docs/UseOverviewGuide.md to use {ref}`...` and change the target anchor to sec:important-info-regd-usage, and fixed the user-guide list formatting. Updated docs/gui/PROJECT_GUI.md to use {ref}`Read more here ` in two places. --- docs/UseOverviewGuide.md | 9 +++++---- docs/gui/PROJECT_GUI.md | 4 ++-- 2 files changed, 7 insertions(+), 6 deletions(-) diff --git a/docs/UseOverviewGuide.md b/docs/UseOverviewGuide.md index 7cc1069b55..dd83a1d0d9 100644 --- a/docs/UseOverviewGuide.md +++ b/docs/UseOverviewGuide.md @@ -40,9 +40,10 @@ We are primarily a package that enables deep learning-based pose estimation. We - Decide on your needs: there are **two main modes, standard DeepLabCut or multi-animal DeepLabCut**. - We highly recommend carefully considering which one is best for your needs. - - For example, a white mouse + black mouse would call for standard, while two black mice would use multi-animal. **[Important Information on how to use DLC in different scenarios (single vs multi animal)](important-info-regd-usage)** Then pick a user guide: - - (1) [How to use standard DeepLabCut](single-animal-userguide) - - (2) [How to use multi-animal DeepLabCut](multi-animal-userguide) + - For example, a white mouse + black mouse would call for standard, while two black mice would use multi-animal. See {ref}`important-info-regd-usage`. + - Then pick a user guide: + 1. [How to use standard DeepLabCut](single-animal-userguide) + 1. [How to use multi-animal DeepLabCut](multi-animal-userguide) - To note, as of DLC3+ the single and multi-animal code bases are more integrated and we support **top-down**, **bottom-up**, and a new "hybrid" approach that is state-of-the-art, called **BUCTD** (bottom-up conditional top down) @@ -109,7 +110,7 @@ When working on a given project, you just need to point to the correct `config.y

-(important-info-regd-usage)= +(sec:important-info-regd-usage)= ## Usage advice & project types diff --git a/docs/gui/PROJECT_GUI.md b/docs/gui/PROJECT_GUI.md index a4303e193b..0cd9c0f475 100644 --- a/docs/gui/PROJECT_GUI.md +++ b/docs/gui/PROJECT_GUI.md @@ -59,13 +59,13 @@ Note that currently the video demo is the wxPython version, but the logic is the [![Watch the video](https://images.squarespace-cdn.com/content/v1/57f6d51c9f74566f55ecf271/1589046800303-OV1CCNZINWDMF1PZWCWE/ke17ZwdGBToddI8pDm48kB4PVlRPKDmSlQNbUD3wvXgUqsxRUqqbr1mOJYKfIPR7LoDQ9mXPOjoJoqy81S2I8N_N4V1vUb5AoIIIbLZhVYxCRW4BPu10St3TBAUQYVKcaja1QZ1SznGf7WzFOi-J6zLusnaF2VdeZcKivwxvFiDfGDqVYuwbAlftad9hfoui/dlc_gui_22.png?format=1000w)](https://www.youtube.com/watch?v=JDsa8R5J0nQ) -[Read more here](important-info-regd-usage) +{ref}`Read more here ` ### Using the Project Manager GUI with the latest DLC code (multiple identical-looking animals, plus objects) [![Watch the video](https://images.squarespace-cdn.com/content/v1/57f6d51c9f74566f55ecf271/1589047147498-G1KTFA5BXR4PVHOOR7OG/ke17ZwdGBToddI8pDm48kJDij24pM2COisBTLIGjR1pZw-zPPgdn4jUwVcJE1ZvWQUxwkmyExglNqGp0IvTJZamWLI2zvYWH8K3-s_4yszcp2ryTI0HqTOaaUohrI8PIel60EThn7SDFlTiSprUhmjQQHn9bhdY9dnQSKs8bCCo/Untitled.png?format=1000w)](https://www.youtube.com/watch?v=Kp-stcTm77g) -[Read more here](important-info-regd-usage) +{ref}`Read more here ` ### How to benchmark your data with the new networks and data augmentation pipelines From 81e3257d1b6bbaf4a18e89754ec95e9256b81239 Mon Sep 17 00:00:00 2001 From: C-Achard Date: Fri, 22 May 2026 10:41:50 +0200 Subject: [PATCH 51/53] chore(metadata): update docs/notebooks metadata --- docs/recipes/external_data_import.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/docs/recipes/external_data_import.md b/docs/recipes/external_data_import.md index 739ae4971f..009a04dec0 100644 --- a/docs/recipes/external_data_import.md +++ b/docs/recipes/external_data_import.md @@ -1,3 +1,11 @@ +--- +deeplabcut: + last_metadata_updated: '2026-05-22' + last_verified: '2026-05-22' + verified_for: 3.0.0rc14 + ignore: false +--- + (file:recipe-importing-data)= # Importing annotated data from elsewhere From d3659136864028fd5d71741c6902263df4fe7282 Mon Sep 17 00:00:00 2001 From: C-Achard Date: Fri, 22 May 2026 10:42:43 +0200 Subject: [PATCH 52/53] Update course.md --- docs/course.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/course.md b/docs/course.md index a1364ef8d9..30fd93f92b 100644 --- a/docs/course.md +++ b/docs/course.md @@ -32,7 +32,7 @@ We expect it to take *roughly* 1-2 weeks to get through if you do it rigorously. You need Python and DeepLabCut installed! -- See the {ref}`beginners-guide` for help! +- See the {ref}`file:beginners-guide` for help! - **WATCH:** overview of conda: [Python Tutorial: Anaconda - Installation and Using Conda](https://www.youtube.com/watch?v=YJC6ldI3hWk) From 3f8a0153518dce54986d9af5a40263bee4272c2a Mon Sep 17 00:00:00 2001 From: C-Achard Date: Fri, 22 May 2026 17:06:57 +0200 Subject: [PATCH 53/53] Docs: copyedits, formatting, and install updates Editorial and formatting updates across documentation to improve clarity and accuracy. Key changes: - README.md: minor whitespace/paragraph tweak in funding section. - docs/UseOverviewGuide.md: corrected phrasing for mode selection. - docs/beginner-guides/beginners-guide.md: reworded intro, removed stray blank line, clarified install link. - docs/course.md: removed trailing colon from heading. - docs/gui/PROJECT_GUI.md: removed outdated release-note lines. - docs/gui/napari_GUI.md: adjusted front-matter spacing and landing file anchor. - docs/installation.md: updated PyTorch install example to pip + CUDA 12.6 wheel URL, clarified pip install deeplabcut usage (mentioning --pre), updated uv editable install extras (removed tf), added recommended clone step, improved version-check example and a few other clarifications. - docs/pytorch/pytorch_config.md: multiple formatting fixes (lists, line wraps, links, code blocks), corrected table header alignment, minor text clarifications and punctuation fixes. - docs/recipes/TechHardware.md: heading and subsection title adjustments and minor wording tweaks. - docs/recipes/external_data_import.md: combined demo CSV links into one sentence and adjusted bullet formatting. - docs/standardDeepLabCut_UserGuide.md: extensive copyedits and formatting cleanups (headings, admonitions, code blocks, escaped characters, consistent naming like add_new_videos), reflowed many paragraphs and improved examples and API-admonition formatting. Overall these changes are non-functional documentation improvements to make instructions clearer and fix formatting/typography issues. --- README.md | 6 +- docs/UseOverviewGuide.md | 2 +- docs/beginner-guides/beginners-guide.md | 3 +- docs/course.md | 2 +- docs/gui/PROJECT_GUI.md | 2 - docs/gui/napari_GUI.md | 2 + docs/installation.md | 21 ++- docs/pytorch/pytorch_config.md | 74 ++++---- docs/recipes/TechHardware.md | 12 +- docs/recipes/external_data_import.md | 6 +- docs/standardDeepLabCut_UserGuide.md | 229 ++++++++++++++++-------- 11 files changed, 221 insertions(+), 138 deletions(-) diff --git a/README.md b/README.md index 365d201b99..746bdebf28 100644 --- a/README.md +++ b/README.md @@ -265,6 +265,6 @@ importing a project into the new data format for DLC 2.0 # Funding - We are grateful for the following support and funding over the years! - This software project was supported in part by the **Essential Open Source Software for Science (EOSS)** program at **Chan Zuckerberg Initiative** (cycles 1, 3, 3-DEI, 4), and jointly with the **Kavli Foundation** for **EOSS Cycle 6**! - We also thank the **Rowland Institute** at **Harvard** for funding from 2017-2020, and **EPFL** from 2020-present. +We are grateful for the following support and funding over the years! +This software project was supported in part by the **Essential Open Source Software for Science (EOSS)** program at **Chan Zuckerberg Initiative** (cycles 1, 3, 3-DEI, 4), and jointly with the **Kavli Foundation** for **EOSS Cycle 6**! +We also thank the **Rowland Institute** at **Harvard** for funding from 2017-2020, and **EPFL** from 2020-present. diff --git a/docs/UseOverviewGuide.md b/docs/UseOverviewGuide.md index dd83a1d0d9..74038ef62b 100644 --- a/docs/UseOverviewGuide.md +++ b/docs/UseOverviewGuide.md @@ -232,7 +232,7 @@ That's it! Follow the GUI for details [VIDEO TUTORIAL AVAILABLE!](https://www.youtube.com/watch?v=7xwOhUcIGio) -Please decide with mode you want to use DeepLabCut, and follow one of the following: +Please decide which mode you want to use DeepLabCut with, and follow one of: - (1) [How to use standard DeepLabCut](single-animal-userguide) - (2) [How to use multi-animal DeepLabCut](multi-animal-userguide) diff --git a/docs/beginner-guides/beginners-guide.md b/docs/beginner-guides/beginners-guide.md index 7a79a5e978..ecc1a4afd4 100644 --- a/docs/beginner-guides/beginners-guide.md +++ b/docs/beginner-guides/beginners-guide.md @@ -15,7 +15,7 @@ deeplabcut: DLC LIVE! -This guide, and related pages, are meant as a very-new-to-python beginner guide to DeepLabCut. After you are comfortable with this material we recommend then jumping into the more detailed User Guides! +This guide and the related pages are intended as a beginner-friendly introduction to DeepLabCut for users who are new to Python. After you are comfortable with this material, we recommend then jumping into the more detailed user guides! @@ -24,7 +24,6 @@ This guide, and related pages, are meant as a very-new-to-python beginner guide ## Installation Before you begin, make sure that DeepLabCut is installed on your system. - Please see the {ref}`installation page` for detailed instructions on how to install DeepLabCut on your computer. diff --git a/docs/course.md b/docs/course.md index 30fd93f92b..83d23e5848 100644 --- a/docs/course.md +++ b/docs/course.md @@ -28,7 +28,7 @@ We expect it to take *roughly* 1-2 weeks to get through if you do it rigorously.

-## Installation: +## Installation You need Python and DeepLabCut installed! diff --git a/docs/gui/PROJECT_GUI.md b/docs/gui/PROJECT_GUI.md index 0cd9c0f475..3bede5488b 100644 --- a/docs/gui/PROJECT_GUI.md +++ b/docs/gui/PROJECT_GUI.md @@ -16,8 +16,6 @@ deeplabcut: As some users may be more comfortable working with an interactive interface, we wanted to provide an easy entry point to the software. All the main functionality is available in an easy-to-use GUI interface. While several advanced features are not fully available in this Project GUI, we hope this gets more users up-and-running quickly. -**Release notes:** As of DeepLabCut 2.1+ now provide a full front-end user experience for DeepLabCut, and as of 2.3+ we changed the GUI from wxPython to PySide6 with napari support. - ## Getting started 1. Install DeepLabCut following the instructions in the {ref}`installation page`. diff --git a/docs/gui/napari_GUI.md b/docs/gui/napari_GUI.md index 79f1ee7e92..2fefc50e82 100644 --- a/docs/gui/napari_GUI.md +++ b/docs/gui/napari_GUI.md @@ -10,7 +10,9 @@ deeplabcut: last_verified: '2026-04-09' verified_for: 3.0.0rc14 --- + (file:napari-gui-landing)= + # napari GUI Welcome to the documentation for napari-DLC, the napari plugin for keypoint annotation and label refinement. This plugin can be used either as part of the DeepLabCut GUI or as a standalone annotation tool. diff --git a/docs/installation.md b/docs/installation.md index 4402ffeff8..73890d523c 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -41,13 +41,13 @@ conda create -n DEEPLABCUT python=3.12 conda activate DEEPLABCUT # Install PyTorch with your desired CUDA version (or CPU only) -# Example: GPU version of pytorch for CUDA 11.3 -conda install pytorch cudatoolkit=11.3 -c pytorch +# Example: install GPU-enabled pytorch for CUDA 12.6 +pip install torch torchvision --index-url https://download.pytorch.org/whl/cu126 # install the latest version of DeepLabCut -pip install --pre deeplabcut +pip install deeplabcut # add --pre for pre-release versions! # or if you want to use the GUI -pip install --pre deeplabcut[gui] +pip install deeplabcut[gui] # ONLY IF YOU HAVE A CUDA GPU - check that PyTorch can access your GPU; this # should print `True` @@ -241,12 +241,13 @@ Recommended for users who want to modify the code, or want to be up-to-date with ### `uv` (recommended for developers) +- Clone the [repository](https://github.com/DeepLabCut/DeepLabCut) - Install `uv` following [instructions here](https://docs.astral.sh/uv/getting-started/installation/) - Run in the cloned repo: ```bash uv venv -p 3.12 -uv pip install -e '.[gui,modelzoo,tf]' # Change optional install as needed +uv pip install -e '.[gui,modelzoo]' # Change optional install as needed source .venv/bin/activate # or & .venv\Scripts\activate.ps1 on Windows ``` @@ -284,7 +285,12 @@ GUI. If you ever want to update your DLC, just run `pip install --upgrade deeplabcut` inside your env. If you want to use a specific release, then specify the version you want, such as `pip install deeplabcut==3.0`. Once installed, you can -check the version by running `import deeplabcut` `deeplabcut.__version__`. +check the version by running: + +```python +import deeplabcut +deeplabcut.__version__ +``` Don't be afraid to update, DLC is backwards compatible with your 2.0+ projects and performance continues to get better and new features are added often. @@ -319,8 +325,7 @@ You will need an NVIDIA GPU that is compatible with CUDA. To see a list of CUDA-enabled NVIDIA GPUs, please [see their website](https://developer.nvidia.com/cuda-gpus). -Here we provide notes on how to install and check your GPU use with TensorFlow, which is used by DeepLabCut and will be installed with the Anaconda files above. -Thus, you do not need to independently install tensorflow. +Here we provide notes on how to install and check your GPU use with TensorFlow, which is used by DeepLabCut. 1. Install a driver for your GPU, using the NVIDIA Drivers link above. - Check which driver is installed by typing this into the terminal: `nvidia-smi`. diff --git a/docs/pytorch/pytorch_config.md b/docs/pytorch/pytorch_config.md index 0019433993..a4c33cd8fb 100644 --- a/docs/pytorch/pytorch_config.md +++ b/docs/pytorch/pytorch_config.md @@ -6,9 +6,11 @@ deeplabcut: visibility: online status: review_needed recommendation: verify - notes: "Check for accuracy and completeness of content, and update as needed. Formatting is fairly consistent and does not need an urgent update." + notes: Check for accuracy and completeness of content, and update as needed. Formatting is fairly consistent and does not need an urgent update. --- + (dlc3-pytorch-config)= + # The PyTorch Configuration file The `pytorch_config.yaml` file specifies the configuration for your PyTorch pose models, @@ -47,10 +49,10 @@ resume_training_from: # optional: restart the training at the specific checkpoi There are a few singleton parameters defined in the PyTorch configuration file: - `device`: The device to use for training/inference. The default is `auto`, which sets -the device to `cuda` if an NVIDIA GPU is available, and `cpu` otherwise. For users -running models on macOS with an M1/M2/M3 chip, this is set to `mps` for certain models -(not all operations are currently supported on Apple GPUs - so some models like HRNets -need to be trained on CPU, while others like ResNets can take advantage of the GPU). + the device to `cuda` if an NVIDIA GPU is available, and `cpu` otherwise. For users + running models on macOS with an M1/M2/M3 chip, this is set to `mps` for certain models + (not all operations are currently supported on Apple GPUs - so some models like HRNets + need to be trained on CPU, while others like ResNets can take advantage of the GPU). - `method`: Either `bu` for bottom-up models, or `td` for top-down models. - `net_type`: The type of pose model configured by the file (e.g. `resnet_50`). @@ -59,11 +61,10 @@ need to be trained on CPU, while others like ResNets can take advantage of the G The data section configures: - `bbox_margin`: The margin (in pixels) to add around ground truth pose when generating -bounding boxes. For more information, see [generating bounding boxes from pose]( -#bbox-from-pose). + bounding boxes. For more information, see [generating bounding boxes from pose](#bbox-from-pose). - `colormode`: in which format images are given to the model (e.g., `RGB`, `BGR`) - `inference`: which transformations should be applied to images when running evaluation -or inference + or inference - `train`: which transformations should be applied to images when training The default configuration for a pose model is: @@ -124,11 +125,9 @@ auto_padding: border_mask_value: null # str: padding value for mask if border_mode is 'constant' ``` -**Covering**: Based on Albumentations's [CoarseDropout]( -https://albumentations.ai/docs/api_reference/augmentations/dropout/coarse_dropout/#albumentations.augmentations.dropout.coarse_dropout) +**Covering**: Based on Albumentations's [CoarseDropout](https://albumentations.ai/docs/api_reference/augmentations/dropout/coarse_dropout/#albumentations.augmentations.dropout.coarse_dropout) augmentation, this "cuts" holes out of the image. As defined in -[Improved Regularization of Convolutional Neural Networks with Cutout]( -https://arxiv.org/abs/1708.04552). +[Improved Regularization of Convolutional Neural Networks with Cutout](https://arxiv.org/abs/1708.04552). ```yaml covering: true # bool: if true, applies a coarse dropout with probability 50% @@ -192,14 +191,14 @@ height and width of images in the batches. There are a few different ways to ens all images in a batch have the same size: 1. **Crop sampling**. This is the default behavior for the PyTorch engine in DeepLabCut. -A part of each image (of a fixed size) is cropped and given to the model to train. See -below for more information. -2. **A custom collate function**. Collate functions define a way that images of different -sizes can be combined into one tensor. This involves resizing and padding images to the -same size and aspect ratio. Available collate functions are defined in -`deeplabcut/pose_estimation_pytorch/data/collate.py`. -3. **Resizing all images**. All images can simply be resized to the same size. This -usually doesn't lead to the best performance. + A part of each image (of a fixed size) is cropped and given to the model to train. See + below for more information. +1. **A custom collate function**. Collate functions define a way that images of different + sizes can be combined into one tensor. This involves resizing and padding images to the + same size and aspect ratio. Available collate functions are defined in + `deeplabcut/pose_estimation_pytorch/data/collate.py`. +1. **Resizing all images**. All images can simply be resized to the same size. This + usually doesn't lead to the best performance. **Resizing - Crop Sampling**: An alternative way to ensure all images have the same size is through cropping. The `crop_sampling` crops images down to a maximum width and @@ -223,12 +222,13 @@ crop_sampling: function to use is `ResizeFromDataSizeCollate` (other collate functions are defined in `deeplabcut/pose_estimation_pytorch/data/collate.py`). For each batch to collate, this implementation: + 1. Selects the target width & height all images will be resized to by getting the size -of the first image in the batch, and multiplying it by a scale sampled uniformly at -random from `(min_scale, max_scale)`. -2. Resizes all images in the batch (while preserving their aspect ratio) such that they -are the smallest size such that the target size fits entirely in the image. -3. Crops each resulting image into the target size with a random crop. + of the first image in the batch, and multiplying it by a scale sampled uniformly at + random from `(min_scale, max_scale)`. +1. Resizes all images in the batch (while preserving their aspect ratio) such that they + are the smallest size such that the target size fits entirely in the image. +1. Crops each resulting image into the target size with a random crop. ```yaml collate: # rescales the images when putting them in a batch @@ -352,8 +352,7 @@ after every epoch, you could decide to evaluate every 5 epochs (by setting is training, it can speed up training on large datasets. **Optimizer**: Any optimizer inheriting `torch.optim.Optimizer`. More information about -optimizers can be found in [PyTorch's documentation]( -https://pytorch.org/docs/stable/optim.html). Examples: +optimizers can be found in [PyTorch's documentation](https://pytorch.org/docs/stable/optim.html). Examples: ```yaml # SGD with initial learning rate 1e-3 and momentum 0.9 @@ -372,8 +371,7 @@ https://pytorch.org/docs/stable/optim.html). Examples: lr: 1e-4 ``` -**Scheduler**: You can use [any scheduler]( -https://pytorch.org/docs/stable/optim.html#how-to-adjust-learning-rate) defined in +**Scheduler**: You can use [any scheduler](https://pytorch.org/docs/stable/optim.html#how-to-adjust-learning-rate) defined in `torch.optim.lr_scheduler`, where the arguments given are arguments of the scheduler. The default scheduler is an LRListScheduler, which changes the learning rates at each milestone to the corresponding values in `lr_list`. Examples: @@ -396,10 +394,8 @@ milestone to the corresponding values in `lr_list`. Examples: ``` You can also use schedulers that use other schedulers as parameters, such as a -[`ChainedScheduler`]( -https://pytorch.org/docs/stable/generated/torch.optim.lr_scheduler.ChainedScheduler.html) -or a [`SequentialLR`]( -https://pytorch.org/docs/stable/generated/torch.optim.lr_scheduler.SequentialLR.html). +[`ChainedScheduler`](https://pytorch.org/docs/stable/generated/torch.optim.lr_scheduler.ChainedScheduler.html) +or a [`SequentialLR`](https://pytorch.org/docs/stable/generated/torch.optim.lr_scheduler.SequentialLR.html). The `SequentialLR` can be particularly useful, such as to use a first scheduler for some warmup epochs, and a second scheduler later. An example usage would be: @@ -437,8 +433,7 @@ warmup epochs, and a second scheduler later. An example usage would be: The `train_settings` key contains parameters that are specific to training. For more information about the `dataloader_workers` and `dataloader_pin_memory` settings, see -[Single- and Multi-process Data Loading]( -https://pytorch.org/docs/stable/data.html#single-and-multi-process-data-loading) +[Single- and Multi-process Data Loading](https://pytorch.org/docs/stable/data.html#single-and-multi-process-data-loading) and [memory pinning](https://pytorch.org/docs/stable/data.html#memory-pinning). Setting `dataloader_workers: 0` uses single-process data loading, while setting it to 1 or more will use multi-process data loading. You should always keep @@ -504,11 +499,13 @@ Otherwise, the parameters for the scheduler your started training with will be l from the state dictionary, and your edits might not be kept! ### Inference + The `inference:` block in `pytorch_config.yaml` allows configuring **inference-specific behavior** for your model. It is independent of training settings and can include multiple sub-configs, currently supporting **multithreading**, **compile**, **autocast**, and **conditions**. **Example** + ```yaml inference: multithreading: @@ -526,6 +523,7 @@ inference: ``` **Sub-configs** + - `multithreading` Controls producer-consumer threading during inference for preprocessing and batching. - `enabled` (`bool`): Enable/disable multithreading. @@ -541,7 +539,7 @@ inference: - `autocast` Controls optional mixed precision during inference. - `enabled` (`bool`): Enable/disable `torch.autocast`. Default: `false`. - Note: Enabling autocast may reduce inference accuracy. It is disabled by default. + Note: Enabling autocast may reduce inference accuracy. It is disabled by default. - `conditions` Only used for **Conditional Top-Down (CTD)** models to specify which conditions should be used during inference. @@ -594,13 +592,12 @@ detector that brings enough performance. The recommended variants are the follow (from fastest to most powerful, taken from torchvision's documentation): | name | Box MAP (larger = more powerful) | Params (larger = more powerful) | GFLOPS (larger = slower) | -|-----------------------------------|---------------------------------:|--------------------------------:|-------------------------:| +| --------------------------------- | -------------------------------: | ------------------------------: | -----------------------: | | SSDLite | 21.3 | 3.4M | 0.58 | | fasterrcnn_mobilenet_v3_large_fpn | 32.8 | 19.4M | 4.49 | | fasterrcnn_resnet50_fpn | 37 | 41.8M | 134.38 | | fasterrcnn_resnet50_fpn_v2 | 46.7 | 43.7M | 280.37 | - ### Restarting Training of an Object Detector at a Specific Checkpoint If you wish to restart the training of a detector at a specific checkpoint, you can @@ -623,6 +620,7 @@ config! Otherwise, the parameters for the scheduler your started training with w loaded from the state dictionary, and your edits might not be kept! (bbox-from-pose)= + ### Generating Bounding Boxes from Pose To train object detection models (for top-down pose estimation), ground truth bounding diff --git a/docs/recipes/TechHardware.md b/docs/recipes/TechHardware.md index 9eac85b9fc..e8f7059e8c 100644 --- a/docs/recipes/TechHardware.md +++ b/docs/recipes/TechHardware.md @@ -7,19 +7,19 @@ deeplabcut: (file:hardware-requirements)= -# Technical (Hardware) Considerations +# Technical & hardware considerations -## Quick summary: +## Quick summary [On our install page](tech-considerations-during-install) we highlight that for GPU computing through standard installation you need a NVIDIA GPU, with at least 8 GB of memory. If you have an Intel or AMD GPU, and are on windows, there is an alternative method of installation available which is shown on the [installation tips page](installation-tips) under "How to install Deeplabcut for Intel and AMD GPUs". Note, some info is repeated here, and will be updated as systems and hardware changes. -### Computer: +### Computer For reference, we use e.g. Dell workstations (79xx series) with **Ubuntu 16.04 LTS, 18.04 LTS, or 20.04 LTS** and run a Docker container that has TensorFlow, etc. installed (https://github.com/DeepLabCut/Docker4DeepLabCut2.0). -### Computer Hardware: +### Computer hardware Ideally, you will use a strong GPU with *at least* 8GB memory such as the [NVIDIA GeForce 1080 Ti, 2080 Ti, or 3090](https://marketplace.nvidia.com/en-us/consumer/graphics-cards/). A GPU is not strictly necessary, but on a CPU the (training and evaluation) code is considerably slower (10x) for ResNets, but MobileNets and EfficientNets are slightly faster. Still, a GPU will give you a massive speed boost. You might also consider using cloud computing services like [Google cloud/amazon web services](https://github.com/DeepLabCut/DeepLabCut/issues/47) or Google Colaboratory. @@ -30,11 +30,11 @@ If you encounter errors during inference related to context to `torch.no_grad`, which is compatible with the DirectML execution path. ``` -### Camera Hardware: +### Camera Hardware The software is very robust to track data from any camera (cell phone cameras, grayscale, color; captured under infrared light, different manufacturers, etc.). See demos on our [website](https://www.mousemotorlab.org/deeplabcut/). -### Software: +### Software **Operating System:** Linux (Ubuntu), MacOS\* (Mojave), or Windows 10. However, the authors strongly recommend Ubuntu! \*MacOS does not support NVIDIA GPUs (easily), so we only suggest this option for CPU use or a case where the user wants to label data, refine data, etc and then push the project to a cloud resource for GPU computing steps, or use MobileNets. diff --git a/docs/recipes/external_data_import.md b/docs/recipes/external_data_import.md index 009a04dec0..21ca77ef81 100644 --- a/docs/recipes/external_data_import.md +++ b/docs/recipes/external_data_import.md @@ -20,9 +20,7 @@ Here is a guide to do this via the ".csv" route: (the pandas array route is iden 1. Edit the `config.yaml` file to include the body part names, please take care that spelling, spacing, and capitalization are IDENTICAL to the "labeled data body part names". -1. Please inspect the excel formatted sheet (.csv) from our [demo project](https://github.com/DeepLabCut/DeepLabCut/tree/main/examples/Reaching-Mackenzie-2018-08-30/labeled-data/reachingvideo1) - - - e.g. see [this file](https://github.com/DeepLabCut/DeepLabCut/blob/main/examples/Reaching-Mackenzie-2018-08-30/labeled-data/reachingvideo1/CollectedData_Mackenzie.csv) +1. Please inspect the excel formatted sheet (.csv) from our [demo project](https://github.com/DeepLabCut/DeepLabCut/tree/main/examples/Reaching-Mackenzie-2018-08-30/labeled-data/reachingvideo1). For example, see [this file](https://github.com/DeepLabCut/DeepLabCut/blob/main/examples/Reaching-Mackenzie-2018-08-30/labeled-data/reachingvideo1/CollectedData_Mackenzie.csv). 1. Edit the .csv file such that it contains the X, Y pixel coordinates, the body part names, the scorer name as well as the relative path to the image: e.g. /labeled-data/somefolder/img017.jpg Then make sure the scorer name, and body parts are the same in the config.yaml file. @@ -31,7 +29,7 @@ Here is a guide to do this via the ".csv" route: (the pandas array route is iden 1. When you are done, run `deeplabcut.convertcsv2h5('path_to_config.yaml', scorer= 'experimenter')` -- The scorer name must be identical to the input name for experimenter that you used when you created the project. This will automatically update "Mackenzie" to your name in the example demo notebook. + - The scorer name must be identical to the input name for experimenter that you used when you created the project. This will automatically update "Mackenzie" to your name in the example demo notebook. ## Merging multiple datasets diff --git a/docs/standardDeepLabCut_UserGuide.md b/docs/standardDeepLabCut_UserGuide.md index 9847b41dc9..8d6847c5f5 100644 --- a/docs/standardDeepLabCut_UserGuide.md +++ b/docs/standardDeepLabCut_UserGuide.md @@ -8,7 +8,9 @@ deeplabcut: recommendation: update notes: This is a crucial piece of the doc, but it is rather long and verbose. Recommend breaking it up into smaller sections, and adding more visuals (e.g. screenshots of the GUI, etc.) to make it more engaging and easier to read. Also, consider adding a table of contents at the beginning for easier navigation. --- + (single-animal-userguide)= + # DeepLabCut User Guide (for single animal projects) This document covers single/standard DeepLabCut use. If you have a complicated multi-animal scenario (i.e., they look @@ -18,8 +20,6 @@ To get started, you can use the GUI, or the terminal. See below. ## DeepLabCut Project Manager GUI (recommended for beginners) - - **GUI:** To begin, navigate to Anaconda Prompt Terminal and right-click to "open as admin "(Windows), or simply launch @@ -28,6 +28,7 @@ To begin, navigate to Anaconda Prompt Terminal and right-click to "open as admin simply run `python -m deeplabcut`. The below functions are available to you in an easy-to-use graphical user interface. While most functionality is available, advanced users might want the additional flexibility that command line interface offers. Read more below. + ```{Hint} 🚨 If you use Windows, please always open the terminal with administrator privileges! Right click, and "run as administrator". ``` @@ -46,6 +47,7 @@ and then please look at the following documentation and the doctrings. Thanks fo To begin, navigate to Anaconda Prompt Terminal and right-click to "open as admin "(Windows), or simply launch "Terminal" (unix/MacOS) on your computer. We assume you have DeepLabCut installed (if not, see Install docs!). Next, launch your conda env (i.e., for example `conda activate DEEPLABCUT`) and then type `ipython`. Then type: + ```python import deeplabcut ``` @@ -91,7 +93,7 @@ the path to the config.yaml file, i.e. `config_path=deeplabcut.create_new_projec This set of arguments will create a project directory with the name **++** in the **Working directory** and creates the symbolic links to videos in the **videos** directory. The project directory will have subdirectories: -**dlc-models**, **dlc-models-pytorch**, **labeled-data**, **training-datasets**, and **videos**. All the outputs +**dlc-models**, **dlc-models-pytorch**, **labeled-data**, **training-datasets**, and **videos**. All the outputs generated during the course of a project will be stored in one of these subdirectories, thus allowing each project to be curated in separation from other projects. The purpose of the subdirectories is as follows: @@ -111,13 +113,13 @@ saved checkpoint, in case the training was interrupted. are stored in separate subdirectories. Each frame has a filename related to the temporal index within the corresponding video, which allows the user to trace every frame back to its origin. -**training-datasets:** This directory will contain the training dataset used to train the network and metadata, which +**training-datasets:** This directory will contain the training dataset used to train the network and metadata, which contains information about how the training dataset was created. -**videos:** Directory of video links or videos. When **copy\_videos** is set to `False`, this directory contains +**videos:** Directory of video links or videos. When **copy_videos** is set to `False`, this directory contains symbolic links to the videos. If it is set to `True` then the videos will be copied to this directory. The default is `False`. Additionally, if the user wants to add new videos to the project at any stage, the function -**add\_new\_videos** can be used. This will update the list of videos in the project's configuration file. +**add_new_videos** can be used. This will update the list of videos in the project's configuration file. ```python deeplabcut.add_new_videos( @@ -127,7 +129,7 @@ deeplabcut.add_new_videos( ) ``` -*Please note, *Full path of the project configuration file* will be referenced as `config_path` throughout this +\*Please note, *Full path of the project configuration file* will be referenced as `config_path` throughout this protocol. The project directory also contains the main configuration file called *config.yaml*. The *config.yaml* file contains @@ -135,14 +137,17 @@ many important parameters of the project. A complete list of parameters includin Box1. The `create_new_project` step writes the following parameters to the configuration file: *Task*, *scorer*, *date*, -*project\_path* as well as a list of videos *video\_sets*. The first three parameters should **not** be changed. The +*project_path* as well as a list of videos *video_sets*. The first three parameters should **not** be changed. The list of videos can be changed by adding new videos or manually removing videos. ![Box 1 - Single Animal Project Configuration File Glossary](images/box1-single.png) ### API Docs + ````{admonition} Click the button to see API Docs -:class: dropdown +--- +class: dropdown +--- ```{eval-rst} .. include:: ./api/deeplabcut.create_new_project.rst ``` @@ -152,8 +157,8 @@ list of videos can be changed by adding new videos or manually removing videos. DLC Utils -Next, open the **config.yaml** file, which was created during **create\_new\_project**. You can edit this file in any -text editor. Familiarize yourself with the meaning of the parameters (Box 1). You can edit various parameters, in +Next, open the **config.yaml** file, which was created during **create_new_project**. You can edit this file in any +text editor. Familiarize yourself with the meaning of the parameters (Box 1). You can edit various parameters, in particular you **must add the list of *bodyparts* (or points of interest)** that you want to track. You can also set the *colormap* here that is used for all downstream steps (can also be edited at anytime), like labeling GUIs, videos, etc. Here any [matplotlib colormaps](https://matplotlib.org/tutorials/colors/colormaps.html) will do! @@ -161,8 +166,7 @@ Please DO NOT have spaces in the names of bodyparts. **bodyparts:** are the bodyparts of each individual (in the above list). - - ### (C) Select Frames to Label +### (C) Select Frames to Label **CRITICAL:** A good training dataset should consist of a sufficient number of frames that capture the breadth of the behavior. This ideally implies to select the frames from different (behavioral) sessions, different lighting and @@ -180,6 +184,7 @@ The function `extract_frames` extracts frames from all the videos in the project a training dataset. The extracted frames from all the videos are stored in a separate subdirectory named after the video file’s name under the ‘labeled-data’. This function also has various parameters that might be useful based on the user’s need. + ```python deeplabcut.extract_frames( config_path, @@ -189,6 +194,7 @@ deeplabcut.extract_frames( userfeedback=False ) ``` + **CRITICAL POINT:** It is advisable to keep the frame size small, as large frames increase the training and inference time. The cropping parameters for each video can be provided in the config.yaml file (and see below). When running the function extract_frames, if the parameter crop=True, then you will be asked to draw a box within the @@ -217,9 +223,11 @@ However, picking frames is highly dependent on the data and the behavior being s provide all purpose code that extracts frames to create a good training dataset for every behavior and animal. If the user feels specific frames are lacking, they can extract hand selected frames of interest using the interactive GUI provided along with the toolbox. This can be launched by using: + ```python deeplabcut.extract_frames(config_path, "manual") ``` + The user can use the *Load Video* button to load one of the videos in the project configuration file, use the scroll bar to navigate across the video and *Grab a Frame* (or a range of frames, as of version 2.0.5) to extract the frame(s). The user can also look at the extracted frames and e.g. delete frames (from the directory) that are too similar before @@ -230,8 +238,11 @@ reloading the set and then manually annotating them.

### API Docs + ````{admonition} Click the button to see API Docs -:class: dropdown +--- +class: dropdown +--- ```{eval-rst} .. include:: ./api/deeplabcut.extract_frames.rst ``` @@ -243,7 +254,7 @@ The toolbox provides a function **label_frames** which helps the user to easily all the extracted frames using an interactive graphical user interface (GUI). The user should have already named the bodyparts to label (points of interest) in the project’s configuration file by providing a list. The following command invokes the -napari-deeplabcut labelling GUI. Checkout the [napari-deeplabcut docs](file:napari-gui-landing) for +napari-deeplabcut labelling GUI. Checkout the \[napari-deeplabcut docs\](file:napari-gui-landing) for more information about the labelling workflow. ```python @@ -271,7 +282,7 @@ labels to the bodyparts in the config.yaml file. Thereafter, the user can call t 2.0.5+: then a box will pop up and ask the user if they wish to display all parts, or only add in the new labels. Saving the labels after all the images are labelled will append the new labels to the existing labeled dataset. -For more information, checkout the [napari-deeplabcut docs](file:napari-gui-landing) for +For more information, checkout the \[napari-deeplabcut docs\](file:napari-gui-landing) for more information about the labelling workflow. ### (E) Check Annotated Frames @@ -279,9 +290,10 @@ more information about the labelling workflow. OPTIONAL: Checking if the labels were created and stored correctly is beneficial for training, since labeling is one of the most critical parts for creating the training dataset. The DeepLabCut toolbox provides a function ‘check_labels’ to do so. It is used as follows: + ```python deeplabcut.check_labels(config_path, visualizeindividuals=True/False) - ``` +``` For each video directory in labeled-data this function creates a subdirectory with **labeled** as a suffix. Those directories contain the frames plotted with the annotated body parts. The user can double check if the body parts are @@ -289,14 +301,18 @@ labeled correctly. If they are not correct, the user can reload the frames (i.e. around, and click save again. ### API Docs + ````{admonition} Click the button to see API Docs -:class: dropdown +--- +class: dropdown +--- ```{eval-rst} .. include:: ./api/deeplabcut.check_labels.rst ``` ```` (create-training-dataset)= + ### (F) Create Training Dataset **CRITICAL POINT:** Only run this step **where** you are going to train the network. If you label on your laptop but @@ -305,10 +321,10 @@ labeled on a Windows machine but train on Linux, this is fine as of 2.0.4 onward saves file sets as both Linux and Windows for you). - If you move your project folder, you must only change the `project_path` (which is done automatically) in the main -config.yaml file - that's it - no need to change the video paths, etc! Your project is fully portable. + config.yaml file - that's it - no need to change the video paths, etc! Your project is fully portable. - Be aware you select your neural network backbone at this stage. As of DLC3+ we support PyTorch (and TensorFlow, but -this will be phased out). + this will be phased out). **OVERVIEW:** This function combines the labeled datasets from all the videos and splits them to create train and test datasets. The training data will be used to train the network, while the test data set will be used for evaluating the @@ -319,7 +335,7 @@ deeplabcut.create_training_dataset(config_path) ``` - OPTIONAL: If the user wishes to benchmark the performance of the DeepLabCut, they can create multiple training -datasets by specifying an integer value to the `num_shuffles`; see the docstring for more details. + datasets by specifying an integer value to the `num_shuffles`; see the docstring for more details. The function creates a new shuffle(s) directory in the **dlc-models-pytorch** directory (**dlc-models** if using Tensorflow), in the current "iteration" directory. @@ -337,9 +353,9 @@ additional data augmentation (beyond our defaults). You can set `net_type`, `det and `augmenter_type` when you call the function. - Networks: ImageNet pre-trained networks OR SuperAnimal pre-trained networks weights will be downloaded, as you -select. You can decide to do transfer-learning (recommended) or "fine-tune" both the backbone and the decoder head. We -suggest seeing our [dedicated documentation on models](dlc3-architectures) for more information ( -or the [this page on selecting models](what-neural-network-should-i-use) for the TensorFlow engine). + select. You can decide to do transfer-learning (recommended) or "fine-tune" both the backbone and the decoder head. We + suggest seeing our [dedicated documentation on models](dlc3-architectures) for more information ( + or the [this page on selecting models](what-neural-network-should-i-use) for the TensorFlow engine). ```{Hint} 🚨 If they do not download (you will see this downloading in the terminal), then you may not have permission to do @@ -350,21 +366,20 @@ the **[docs for more help!](tf-training-tips-and-tricks)**). **DATA AUGMENTATION:** At this stage you can also decide what type of augmentation to use. Once you've called `create_training_dataset`, you can edit the [**pytorch_config.yaml**](dlc3-pytorch-config) file that was created (or for the -TensorFlow engine, the [**pose_cfg.yaml**]( -https://github.com/DeepLabCut/DeepLabCut/blob/main/deeplabcut/pose_cfg.yaml) file). +TensorFlow engine, the [**pose_cfg.yaml**](https://github.com/DeepLabCut/DeepLabCut/blob/main/deeplabcut/pose_cfg.yaml) file). - PyTorch Engine: [Albumentations](https://albumentations.ai/docs/) is used for data -augmentation. Look at the [**pytorch_config.yaml**](dlc3-pytorch-config) for more -information about image augmentation options. + augmentation. Look at the [**pytorch_config.yaml**](dlc3-pytorch-config) for more + information about image augmentation options. - TensorFlow Engine: The default augmentation works well for most tasks (as shown on -www.deeplabcut.org), but there are many options, more data augmentation, intermediate -supervision, etc. Here are the available loaders: + www.deeplabcut.org), but there are many options, more data augmentation, intermediate + supervision, etc. Here are the available loaders: - `imgaug`: a lot of augmentation possibilities, efficient code for target map creation & batch sizes >1 supported. - You can set the parameters such as the `batch_size` in the `pose_cfg.yaml` file for the model you are training. This - is the recommended default! + You can set the parameters such as the `batch_size` in the `pose_cfg.yaml` file for the model you are training. This + is the recommended default! - `crop_scale`: our standard DLC 2.0 introduced in Nature Protocols variant (scaling, auto-crop augmentation) - `tensorpack`: a lot of augmentation possibilities, multi CPU support for fast processing, target maps are created - less efficiently than in imgaug, does not allow batch size>1 + less efficiently than in imgaug, does not allow batch size>1 - `deterministic`: only useful for testing, freezes numpy seed; otherwise like default. **MODEL COMPARISON**: You can also test several models by creating the same train/test @@ -393,21 +408,27 @@ deeplabcut.create_training_dataset_from_existing_split( ```` ````{admonition} Click the button to see API Docs for deeplabcut.create_training_dataset -:class: dropdown +--- +class: dropdown +--- ```{eval-rst} .. include:: ./api/deeplabcut.create_training_dataset.rst ``` ```` ````{admonition} Click the button to see API Docs for deeplabcut.create_training_model_comparison -:class: dropdown +--- +class: dropdown +--- ```{eval-rst} .. include:: ./api/deeplabcut.create_training_model_comparison.rst ``` ```` ````{admonition} Click the button to see API Docs for deeplabcut.create_training_dataset_from_existing_split -:class: dropdown +--- +class: dropdown +--- ```{eval-rst} .. include:: ./api/deeplabcut.create_training_dataset_from_existing_split.rst ``` @@ -416,9 +437,11 @@ deeplabcut.create_training_dataset_from_existing_split( ### (G) Train The Network The function ‘train_network’ helps the user in training the network. It is used as follows: + ```python deeplabcut.train_network(config_path) ``` + The set of arguments in the function starts training the network for the dataset created for one specific shuffle. Note that you can change training parameters in the [**pytorch_config.yaml**](dlc3-pytorch-config) file (or **pose_cfg.yaml** for TensorFlow @@ -428,8 +451,9 @@ At user specified iterations during training checkpoints are stored in the subdi *train* under the respective iteration & shuffle directory. ````{admonition} Tips on training models with the PyTorch Engine -:class: dropdown - +--- +class: dropdown +--- Example parameters that one can call: ```python @@ -471,8 +495,9 @@ and how often the weights are stored. We suggest saving every 5 to 25 epochs. ```` ````{admonition} Tips on training models with the TensorFlow Engine -:class: dropdown - +--- +class: dropdown +--- Example parameters that one can call: ```python @@ -518,7 +543,9 @@ data. The bonus, training time is much less!!! ```` ````{admonition} Click the button to see API Docs for train_network -:class: dropdown +--- +class: dropdown +--- ```{eval-rst} .. include:: ./api/deeplabcut.train_network.rst ``` @@ -549,34 +576,35 @@ Neuroscience 2018). **Optional parameters:** - `Shuffles: list, optional` - List of integers specifying the shuffle indices of the training dataset. -The default is [1] + The default is [1] - `plotting: bool, optional` - Plots the predictions on the train and test images. The default is `False`; -if provided it must be either `True` or `False` + if provided it must be either `True` or `False` - `show_errors: bool, optional` - Display train and test errors. The default is `True` - `comparisonbodyparts: list of bodyparts, Default is all` - The average error will be computed for those body parts -only (Has to be a subset of the body parts). + only (Has to be a subset of the body parts). - `gputouse: int, optional` - Natural number indicating the number of your GPU (see number in nvidia-smi). If you do not -have a GPU, put None. See: https://nvidia.custhelp.com/app/answers/detail/a_id/3751/~/useful-nvidia-smi-queries + have a GPU, put None. See: https://nvidia.custhelp.com/app/answers/detail/a_id/3751/~/useful-nvidia-smi-queries - `pcutoff: float | list[float] | dict[str, float], optional` -(Only applicable when using the PyTorch engine. For TensorFlow, set `pcutoff` in the `config.yaml` file.) -Specifies the cutoff value(s) used to compute evaluation metrics. + (Only applicable when using the PyTorch engine. For TensorFlow, set `pcutoff` in the `config.yaml` file.) + Specifies the cutoff value(s) used to compute evaluation metrics. + - If `None` (default), the cutoff will be loaded from the project configuration. - To apply a single cutoff value to all bodyparts, provide a `float`. - To specify different cutoffs per bodypart, provide either: - A `list[float]`: one value per bodypart, with an additional value for each unique bodypart if applicable. - A `dict[str, float]`: where keys are bodypart names and values are the corresponding cutoff values. -If a bodypart is not included in the provided dictionary, a default `pcutoff` of `0.6` will be used for that bodypart. + If a bodypart is not included in the provided dictionary, a default `pcutoff` of `0.6` will be used for that bodypart. The plots can be customized by editing the **config.yaml** file (i.e., the colormap, scale, marker size (dotsize), and transparency of labels (alphavalue) can be modified). By default each body part is plotted in a different color (governed by the colormap) and the plot labels indicate their source. Note that by default the human labels are plotted as plus (‘+’), DeepLabCut’s predictions either as ‘.’ (for confident predictions with likelihood > p-cutoff) and -’x’ for (likelihood <= `pcutoff`). +’x’ for (likelihood \<= `pcutoff`). The evaluation results for each shuffle of the training dataset are stored in a unique subdirectory in a newly created directory ‘evaluation-results-pytorch’ (‘evaluation-results’ for tensorflow models) in the project directory. @@ -599,11 +627,15 @@ labeled accurately ```python deeplabcut.extract_save_all_maps(config_path, shuffle=shuffle, Indices=[0, 5]) ``` + you can drop "Indices" to run this on all training/testing images (this is slow!) ### API Docs + ````{admonition} Click the button to see API Docs -:class: dropdown +--- +class: dropdown +--- ```{eval-rst} .. include:: ./api/deeplabcut.evaluate_network.rst ``` @@ -613,13 +645,16 @@ you can drop "Indices" to run this on all training/testing images (this is slow! The trained network can be used to analyze new videos. Novel/new videos **DO NOT have to be in the config file!**. You can analyze new videos anytime by simply using the following line of code: + ```python deeplabcut.analyze_videos( config_path, ["fullpath/analysis/project/videos/reachingvideo1.avi"], save_as_csv=True ) ``` + There are several other optional inputs, such as: + ```python deeplabcut.analyze_videos( config_path, @@ -633,6 +668,7 @@ deeplabcut.analyze_videos( dynamic=(True, .5, 10) ) ``` + The user can choose a checkpoint for analyzing the videos. For this, the user can enter the corresponding index of the checkpoint to the variable snapshotindex in the config.yaml file. By default, the most recent checkpoint (i.e. last) is used for analyzing the video. @@ -645,8 +681,11 @@ by default. You can also set a destination folder (`destfolder`) for the output you wish to write to. ### API Docs + ````{admonition} Click the button to see API Docs -:class: dropdown +--- +class: dropdown +--- ```{eval-rst} .. include:: ./api/deeplabcut.analyze_videos.rst ``` @@ -673,16 +712,20 @@ dynamic: triple containing (state, detectiontreshold, margin) for the next frame (this is why the margin is important and should be set large enough given the movement of the animal). ``` + ### (J) Filter Pose Data -You can also filter the predictions with a median filter (default) or with a [SARIMAX model](https://www.statsmodels.org/dev/generated/statsmodels.tsa.statespace.sarimax.SARIMAX.html), if you wish. This creates a new .h5 file with the ending *_filtered* that you can use in create_labeled_data and/or plot trajectories. +You can also filter the predictions with a median filter (default) or with a [SARIMAX model](https://www.statsmodels.org/dev/generated/statsmodels.tsa.statespace.sarimax.SARIMAX.html), if you wish. This creates a new .h5 file with the ending *\_filtered* that you can use in create_labeled_data and/or plot trajectories. + ```python deeplabcut.filterpredictions( config_path, ["fullpath/analysis/project/videos/reachingvideo1.avi"] ) ``` - An example call: + +An example call: + ```python deeplabcut.filterpredictions( config_path, @@ -693,7 +736,9 @@ deeplabcut.filterpredictions( MAdegree=2 ) ``` - Here are parameters you can modify and pass: + +Here are parameters you can modify and pass: + ```python deeplabcut.filterpredictions( config_path, @@ -707,15 +752,19 @@ deeplabcut.filterpredictions( alpha=0.01 ) ``` - Here is an example of how this can be applied to a video: -

+Here is an example of how this can be applied to a video: + +

### API Docs + ````{admonition} Click the button to see API Docs -:class: dropdown +--- +class: dropdown +--- ```{eval-rst} .. include:: ./api/deeplabcut.filterpredictions.rst ``` @@ -743,8 +792,11 @@ body part detections across frames). Here are example plot outputs on a demo vid

### API Docs + ````{admonition} Click the button to see API Docs -:class: dropdown +--- +class: dropdown +--- ```{eval-rst} .. include:: ./api/deeplabcut.plot_trajectories.rst ``` @@ -755,6 +807,7 @@ body part detections across frames). Here are example plot outputs on a demo vid Additionally, the toolbox provides a function to create labeled videos based on the extracted poses by plotting the labels on top of the frame and creating a video. There are two modes to create videos: FAST and SLOW (but higher quality!). One can use the command as follows to create multiple labeled videos: + ```python deeplabcut.create_labeled_video( config_path, @@ -763,8 +816,10 @@ deeplabcut.create_labeled_video( save_frames = True/False ) ``` - Optionally, if you want to use the filtered data for a video or directory of filtered videos pass `filtered=True`, - i.e.: + +Optionally, if you want to use the filtered data for a video or directory of filtered videos pass `filtered=True`, +i.e.: + ```python deeplabcut.create_labeled_video( config_path, @@ -773,8 +828,10 @@ deeplabcut.create_labeled_video( filtered=True ) ``` + You can also optionally add a skeleton to connect points and/or add a history of points for visualization. To set the "trailing points" you need to pass `trailpoints`: + ```python deeplabcut.create_labeled_video( config_path, @@ -783,11 +840,13 @@ deeplabcut.create_labeled_video( trailpoints=10 ) ``` + To draw a skeleton, you need to first define the pairs of connected nodes (in the `config.yaml` file) and set the skeleton color (in the `config.yaml` file). There is also a GUI to help you do this, use by calling `deeplabcut.SkeletonBuilder(configpath)`! Here is how the `config.yaml` additions/edits should look (for example, on the Openfield demo data we provide): + ```python # Plotting configuration skeleton: @@ -802,7 +861,9 @@ dotsize: 4 alphavalue: 0.5 colormap: jet ``` + Then pass `draw_skeleton=True` with the command: + ```python deeplabcut.create_labeled_video( config_path, @@ -826,7 +887,7 @@ deeplabcut.create_labeled_video( **PRO TIP:** that the **best quality videos** are created when `fastmode=False` is passed. Therefore, when `trailpoints` and `draw_skeleton` are used, we **highly** recommend you also pass `fastmode=False`! -

+

@@ -834,8 +895,11 @@ This function has various other parameters, in particular the user can set the ` `alphavalue` of the labels in **config.yaml** file. ### API Docs + ````{admonition} Click the button to see API Docs -:class: dropdown +--- +class: dropdown +--- ```{eval-rst} .. include:: ./api/deeplabcut.create_labeled_video.rst ``` @@ -844,7 +908,7 @@ This function has various other parameters, in particular the user can set the ` ### Extract "Skeleton" Features: NEW, as of 2.0.7+: You can save the "skeleton" that was applied in `create_labeled_videos` for more computations. -Namely, it extracts length and orientation of each "bone" of the skeleton as defined in the **config.yaml** file. You +Namely, it extracts length and orientation of each "bone" of the skeleton as defined in the **config.yaml** file. You can use the function by: ```python @@ -860,14 +924,18 @@ deeplabcut.analyzeskeleton( ``` ### API Docs + ````{admonition} Click the button to see API Docs -:class: dropdown +--- +class: dropdown +--- ```{eval-rst} .. include:: ./api/deeplabcut.analyzeskeleton.rst ``` ```` (active-learning)= + ### (M) Optional Active Learning -> Network Refinement: Extract Outlier Frames While DeepLabCut typically generalizes well across datasets, one might want to optimize its performance in various, @@ -892,6 +960,7 @@ the user can set: ``` outlieralgorithm: "fitting", "jump", or "uncertain" ``` + • `outlieralgorithm="uncertain"`: select frames if the likelihood of a particular or all body parts lies below `p_bound` (note this could also be due to occlusions rather than errors). @@ -901,13 +970,14 @@ pixels from the last frame. • `outlieralgorithm="fitting"`: select frames if the predicted body part location deviates from a state-space model fit to the time series of individual body parts. Specifically, this method fits an Auto Regressive Integrated Moving Average (ARIMA) model to the time series for each body part. Thereby each body part detection with a likelihood smaller than -`p_bound` is treated as missing data. Putative outlier frames are then identified as time points, where the average +`p_bound` is treated as missing data. Putative outlier frames are then identified as time points, where the average body part estimates are at least `epsilon` pixels away from the fits. The parameters of this method are `epsilon`, `p_bound`, the ARIMA parameters as well as the list of body parts to average over (can also be `all`). • `outlieralgorithm="manual"`: manually select outlier frames based on visual inspection from the user. - As an example: +As an example: + ```python deeplabcut.extract_outlier_frames(config_path, ["videofile_path"], outlieralgorithm="manual") ``` @@ -925,16 +995,19 @@ Once enough outlier frames are extracted the refinement GUI can be used to adjus (see below). ### API Docs + ````{admonition} Click the button to see API Docs -:class: dropdown +--- +class: dropdown +--- ```{eval-rst} .. include:: ./api/deeplabcut.extract_outlier_frames.rst ``` ```` - ### (N) Refine Labels: Augmentation of the Training Dataset +### (N) Refine Labels: Augmentation of the Training Dataset - Based on the performance of DeepLabCut, four scenarios are possible: +Based on the performance of DeepLabCut, four scenarios are possible: (A) Visible body part with accurate DeepLabCut prediction. These labels do not need any modifications. @@ -951,22 +1024,26 @@ and their corresponding predictions, if any. Here, the GUI will prompt the user as invalid. The labels for extracted putative outlier frames can be refined by opening the GUI: + ```python deeplabcut.refine_labels(config_path) ``` + This will launch a GUI where the user can refine the labels. -Please refer to the [napari-deeplabcut docs](file:napari-gui-landing) for more information about the labelling workflow. +Please refer to the \[napari-deeplabcut docs\](file:napari-gui-landing) for more information about the labelling workflow. After correcting the labels for all the frames in each of the subdirectories, the users should merge the data set to create a new dataset. In this step the iteration parameter in the config.yaml file is automatically updated. + ```python deeplabcut.merge_datasets(config_path) ``` + Once the dataset is merged, the user can test if the merging process was successful by plotting all the labels (Step E). Next, with this expanded training set the user can now create a novel training set and train the network as described in Steps F and G. The training dataset will be stored in the same place as before but under a different `iteration-#` -subdirectory, where the ``#`` is the new value of `iteration` variable stored in the project’s configuration file +subdirectory, where the `#` is the new value of `iteration` variable stored in the project’s configuration file (this is automatically done). Now you can run `create_training_dataset`, then `train_network`, etc. If your original labels were adjusted at all, @@ -977,16 +1054,22 @@ If after training the network generalizes well to the data, proceed to analyze n more data. ### API Docs for deeplabcut.refine_labels + ````{admonition} Click the button to see API Docs -:class: dropdown +--- +class: dropdown +--- ```{eval-rst} .. include:: ./api/deeplabcut.refine_labels.rst ``` ```` ### API Docs for deeplabcut.merge_datasets + ````{admonition} Click the button to see API Docs -:class: dropdown +--- +class: dropdown +--- ```{eval-rst} .. include:: ./api/deeplabcut.merge_datasets.rst ```