wholebodypose 2.0.2__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (50) hide show
  1. wholebodypose/__init__.py +43 -0
  2. wholebodypose/api.py +192 -0
  3. wholebodypose/cli.py +149 -0
  4. wholebodypose/datasets/__init__.py +33 -0
  5. wholebodypose/datasets/build.py +467 -0
  6. wholebodypose/datasets/hdf5.py +201 -0
  7. wholebodypose/datasets/sources.py +362 -0
  8. wholebodypose/enhancing/__init__.py +0 -0
  9. wholebodypose/enhancing/brightness.py +37 -0
  10. wholebodypose/filters/__init__.py +0 -0
  11. wholebodypose/filters/filtering_mean.py +25 -0
  12. wholebodypose/filters/filtering_nlms.py +130 -0
  13. wholebodypose/filters/sequence.py +187 -0
  14. wholebodypose/io.py +61 -0
  15. wholebodypose/models/__init__.py +0 -0
  16. wholebodypose/models/base.py +49 -0
  17. wholebodypose/models/mediapipe/__init__.py +0 -0
  18. wholebodypose/models/mediapipe/map_mp2coco.py +217 -0
  19. wholebodypose/models/mediapipe/meta_data.json +148 -0
  20. wholebodypose/models/mediapipe/model.py +320 -0
  21. wholebodypose/models/onnx_session.py +56 -0
  22. wholebodypose/models/rtmpose/__init__.py +0 -0
  23. wholebodypose/models/rtmpose/_onnx/__init__.py +9 -0
  24. wholebodypose/models/rtmpose/_onnx/rtmw.py +225 -0
  25. wholebodypose/models/rtmpose/_onnx/wholebody.py +92 -0
  26. wholebodypose/models/rtmpose/_onnx/yolox.py +220 -0
  27. wholebodypose/models/rtmpose/model.py +129 -0
  28. wholebodypose/models/vitpose/__init__.py +0 -0
  29. wholebodypose/models/vitpose/model.py +112 -0
  30. wholebodypose/models/vitpose/onnx_runtime.py +109 -0
  31. wholebodypose/tracking.py +93 -0
  32. wholebodypose/utils/__init__.py +0 -0
  33. wholebodypose/utils/coco133.py +212 -0
  34. wholebodypose/utils/files.py +47 -0
  35. wholebodypose/utils/keypoint_subsets.py +49 -0
  36. wholebodypose/utils/vision.py +256 -0
  37. wholebodypose/video/__init__.py +0 -0
  38. wholebodypose/video/converters.py +126 -0
  39. wholebodypose/video/video2pose.py +377 -0
  40. wholebodypose/weights.py +220 -0
  41. wholebodypose-2.0.2.dist-info/METADATA +182 -0
  42. wholebodypose-2.0.2.dist-info/RECORD +50 -0
  43. wholebodypose-2.0.2.dist-info/WHEEL +5 -0
  44. wholebodypose-2.0.2.dist-info/entry_points.txt +3 -0
  45. wholebodypose-2.0.2.dist-info/licenses/LICENSE +201 -0
  46. wholebodypose-2.0.2.dist-info/licenses/LICENSES/Apache-2.0.txt +201 -0
  47. wholebodypose-2.0.2.dist-info/licenses/LICENSES/MIT.txt +22 -0
  48. wholebodypose-2.0.2.dist-info/licenses/NOTICE +10 -0
  49. wholebodypose-2.0.2.dist-info/licenses/THIRD_PARTY.md +47 -0
  50. wholebodypose-2.0.2.dist-info/top_level.txt +1 -0
@@ -0,0 +1,43 @@
1
+ """WholeBodyPose: unified COCO-WholeBody (133 keypoints) pose estimation.
2
+
3
+ Backends (RTMPose, ViTPose, MediaPipe) are imported lazily, so ``import wholebodypose`` only
4
+ needs NumPy and OpenCV.
5
+ """
6
+
7
+ from __future__ import annotations
8
+
9
+ from importlib.metadata import PackageNotFoundError, version
10
+
11
+ try:
12
+ __version__ = version("wholebodypose")
13
+ except PackageNotFoundError: # pragma: no cover - running from a source tree
14
+ __version__ = "0.0.0+local"
15
+
16
+ _LAZY = {
17
+ "PoseEstimator": "wholebodypose.api",
18
+ "create_model": "wholebodypose.api",
19
+ "available_backends": "wholebodypose.api",
20
+ "BACKENDS": "wholebodypose.api",
21
+ "Video2Pose": "wholebodypose.video.video2pose",
22
+ "DrawerPose": "wholebodypose.utils.vision",
23
+ "save_poses": "wholebodypose.io",
24
+ "load_poses": "wholebodypose.io",
25
+ "PoseSequenceFilter": "wholebodypose.filters.sequence",
26
+ "FilteringNLMS": "wholebodypose.filters.filtering_nlms",
27
+ "get_weight": "wholebodypose.weights",
28
+ "PoseTracker": "wholebodypose.tracking",
29
+ }
30
+
31
+ __all__ = ["__version__", *_LAZY]
32
+
33
+
34
+ def __getattr__(name: str):
35
+ if name in _LAZY:
36
+ import importlib
37
+
38
+ return getattr(importlib.import_module(_LAZY[name]), name)
39
+ raise AttributeError(f"module 'wholebodypose' has no attribute {name!r}")
40
+
41
+
42
+ def __dir__():
43
+ return sorted(__all__)
wholebodypose/api.py ADDED
@@ -0,0 +1,192 @@
1
+ """High-level API: one entry point for every backend."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import importlib
6
+ from dataclasses import dataclass, field
7
+ from pathlib import Path
8
+
9
+ import numpy as np
10
+
11
+ from wholebodypose.models.base import BasePoseModel
12
+
13
+
14
+ @dataclass(frozen=True)
15
+ class Backend:
16
+ """Registry entry for a pose backend."""
17
+
18
+ name: str
19
+ target: str # "module:Class"
20
+ extra: str # pip extra that installs its dependencies ("" = core install)
21
+ description: str
22
+ defaults: dict = field(default_factory=dict) # paper settings
23
+ multiperson: bool = False # can return several people (some need an option, see description)
24
+
25
+
26
+ BACKENDS: dict[str, Backend] = {
27
+ b.name: b
28
+ for b in [
29
+ Backend(
30
+ "rtmpose",
31
+ "wholebodypose.models.rtmpose.model:RTMPoseModel",
32
+ "",
33
+ "YOLOX + RTMW (OpenMMLab), multi-person, ONNX Runtime",
34
+ {"mode": "performance", "use_thresholding": True, "filter_noise": True},
35
+ multiperson=True,
36
+ ),
37
+ Backend(
38
+ "vitpose",
39
+ "wholebodypose.models.vitpose.model:VITPoseModel",
40
+ "",
41
+ "ViTPose+ top-down, ONNX Runtime; multi-person with detector='yolox_m'",
42
+ {"model_name": "ViTPose+_huge_coco_wholebody", "use_thresholding": True, "kpt_thr": 0.5},
43
+ multiperson=True,
44
+ ),
45
+ Backend(
46
+ "mediapipe",
47
+ "wholebodypose.models.mediapipe.model:MediapipeModel",
48
+ "mediapipe",
49
+ "MediaPipe pose + hands + face, CPU friendly; multi-person with max_people>1",
50
+ {"use_thresholding": True, "kpt_thr": 0.5},
51
+ multiperson=True,
52
+ ),
53
+ ]
54
+ }
55
+
56
+
57
+ # Extra settings that turn a backend into multi-person mode.
58
+ MULTIPERSON_DEFAULTS: dict[str, dict] = {
59
+ "rtmpose": {},
60
+ "vitpose": {"detector": "yolox_m"},
61
+ "mediapipe": {"engine": "tasks", "max_people": 4},
62
+ }
63
+
64
+
65
+ def install_command(extra: str) -> str:
66
+ """``pip install`` command for a backend extra (``""`` = the core package)."""
67
+ return f"pip install 'wholebodypose[{extra}]'" if extra else "pip install wholebodypose"
68
+
69
+
70
+ def available_backends() -> list[str]:
71
+ """Names of all registered backends."""
72
+ return list(BACKENDS)
73
+
74
+
75
+ def create_model(
76
+ backend: str = "rtmpose",
77
+ device: str = "auto",
78
+ verbose: bool = True,
79
+ multiperson: bool = False,
80
+ max_people: int | None = None,
81
+ **kwargs,
82
+ ) -> BasePoseModel:
83
+ """Build a backend with the paper defaults, overridden by ``kwargs``.
84
+
85
+ ``multiperson=True`` applies ``MULTIPERSON_DEFAULTS`` (YOLOX detector for ViTPose,
86
+ ``max_people`` for MediaPipe; RTMPose is always multi-person). ``max_people`` caps the
87
+ number of people for ViTPose and MediaPipe.
88
+
89
+ Example:
90
+ >>> model = create_model("mediapipe") # doctest: +SKIP
91
+ >>> keypoints, scores = model.predict(image_rgb) # doctest: +SKIP
92
+ """
93
+ key = backend.lower()
94
+ if key not in BACKENDS:
95
+ raise ValueError(f"Unknown backend {backend!r}. Choose one of {available_backends()}.")
96
+ spec = BACKENDS[key]
97
+ module_name, cls_name = spec.target.split(":")
98
+ try:
99
+ cls = getattr(importlib.import_module(module_name), cls_name)
100
+ except ImportError as e:
101
+ raise ImportError(f"Backend '{key}' needs: {install_command(spec.extra)} ({e})") from e
102
+ params = {**spec.defaults, **(MULTIPERSON_DEFAULTS[key] if multiperson else {}), **kwargs}
103
+ if max_people is not None and key in ("vitpose", "mediapipe"):
104
+ params["max_people"] = max_people
105
+ if key != "mediapipe":
106
+ params.setdefault("device", device)
107
+ params.setdefault("verbose", verbose)
108
+ return cls(**params)
109
+
110
+
111
+ class PoseEstimator:
112
+ """Whole-body pose estimation with a single, backend-agnostic interface.
113
+
114
+ Args:
115
+ backend: ``'rtmpose'``, ``'vitpose'`` or ``'mediapipe'``.
116
+ device: ``'auto'``, ``'cuda'`` or ``'cpu'``.
117
+ mode_coco: Visualization style. ``True``: COCO-WholeBody 133 keypoints;
118
+ ``False``: adds neck and pelvis points (135, OpenPose-like).
119
+ verbose: Print loading information.
120
+ multiperson: Detect every person (see :func:`create_model`); videos then return one
121
+ array per frame plus stable ``track_ids``.
122
+ max_people: Upper bound on people for ViTPose / MediaPipe.
123
+ **kwargs: Backend-specific overrides (e.g. ``model_name='ViTPose+_base_coco_wholebody'``).
124
+
125
+ Example:
126
+ >>> from wholebodypose import PoseEstimator # doctest: +SKIP
127
+ >>> est = PoseEstimator("rtmpose") # doctest: +SKIP
128
+ >>> kpts, scores = est.predict(image_rgb) # (N, 133, 2), (N, 133)
129
+ >>> res = est.process_video("in.mp4", "out/") # res["total_keypoints"]: (T, 133, 2)
130
+ """
131
+
132
+ def __init__(
133
+ self,
134
+ backend: str = "rtmpose",
135
+ device: str = "auto",
136
+ mode_coco: bool = True,
137
+ verbose: bool = True,
138
+ multiperson: bool = False,
139
+ max_people: int | None = None,
140
+ **kwargs,
141
+ ) -> None:
142
+ self.backend = backend.lower()
143
+ self.multiperson = multiperson
144
+ self.model = create_model(
145
+ self.backend, device=device, verbose=verbose, multiperson=multiperson, max_people=max_people, **kwargs
146
+ )
147
+ self.mode_coco = mode_coco
148
+ self.verbose = verbose
149
+
150
+ def predict(self, image_rgb: np.ndarray) -> tuple[np.ndarray, np.ndarray]:
151
+ """Keypoints ``(N, 133, 2)`` and scores ``(N, 133)`` for an RGB ``uint8`` image."""
152
+ return self.model.predict(image_rgb)
153
+
154
+ __call__ = predict
155
+
156
+ def predict_image(self, path: str | Path) -> tuple[np.ndarray, np.ndarray]:
157
+ """Read an image from disk and run :meth:`predict`."""
158
+ import cv2
159
+
160
+ bgr = cv2.imread(str(path))
161
+ if bgr is None:
162
+ raise FileNotFoundError(path)
163
+ return self.predict(cv2.cvtColor(bgr, cv2.COLOR_BGR2RGB))
164
+
165
+ def draw(
166
+ self,
167
+ image: np.ndarray,
168
+ keypoints: np.ndarray,
169
+ scores: np.ndarray,
170
+ kpt_thr: float = 0.5,
171
+ radius: int = 2,
172
+ line_width: int = 2,
173
+ ) -> np.ndarray:
174
+ """Return a copy of ``image`` with the skeleton(s) drawn.
175
+
176
+ Skeleton colors are defined in BGR (OpenCV convention), so pass a BGR image to get the
177
+ documented colors (as the CLI does before ``cv2.imwrite``); RGB works but swaps red/blue.
178
+ """
179
+ from wholebodypose.utils.vision import DrawerPose
180
+
181
+ img = np.ascontiguousarray(image).copy()
182
+ if len(keypoints) == 0:
183
+ return img
184
+ return DrawerPose(mode_coco=self.mode_coco)(img, keypoints, scores, kpt_thr, radius, line_width)
185
+
186
+ def process_video(self, filepath: str, folder_results: str | None = None, **kwargs) -> dict:
187
+ """Run the video pipeline; see :meth:`wholebodypose.video.Video2Pose.predict`."""
188
+ from wholebodypose.video.video2pose import Video2Pose
189
+
190
+ kwargs.setdefault("multiperson", self.multiperson)
191
+ runner = Video2Pose(mode_coco=self.mode_coco, model=self.model, verbose=self.verbose)
192
+ return runner.predict(filepath, folder_results, **kwargs)
wholebodypose/cli.py ADDED
@@ -0,0 +1,149 @@
1
+ """Command line interface: ``wholebodypose {image,video,backends,download}``."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import argparse
6
+ import sys
7
+ from pathlib import Path
8
+
9
+ CITE_LINE = "Please cite: Lazo-Quispe et al., WholeBodyPose, ICMV 2025, Proc. SPIE 14114, doi:10.1117/12.3096312"
10
+
11
+
12
+ def _add_common(p: argparse.ArgumentParser) -> None:
13
+ p.add_argument("--backend", "-b", default="rtmpose", help="rtmpose | vitpose | mediapipe")
14
+ p.add_argument("--device", default="auto", help="auto | cuda | cpu")
15
+ p.add_argument("--style", choices=["coco133", "openpose135"], default="coco133", help="skeleton drawing style")
16
+ p.add_argument("--quiet", "-q", action="store_true")
17
+
18
+
19
+ def cmd_image(args) -> int:
20
+ import cv2
21
+
22
+ from wholebodypose import PoseEstimator, save_poses
23
+
24
+ est = PoseEstimator(args.backend, device=args.device, mode_coco=args.style == "coco133", verbose=not args.quiet)
25
+ bgr = cv2.imread(str(args.input))
26
+ if bgr is None:
27
+ print(f"cannot read {args.input}", file=sys.stderr)
28
+ return 1
29
+ rgb = cv2.cvtColor(bgr, cv2.COLOR_BGR2RGB)
30
+ kpts, scores = est.predict(rgb)
31
+ out_dir = Path(args.output)
32
+ out_dir.mkdir(parents=True, exist_ok=True)
33
+ stem = f"{Path(args.input).stem}_{args.backend}"
34
+ drawn = est.draw(bgr, kpts, scores)
35
+ cv2.imwrite(str(out_dir / f"{stem}.png"), drawn)
36
+ # one "frame" holding N people: keypoints (1, N, 133, 2)
37
+ save_poses(out_dir / f"{stem}.{args.format}", [kpts], [scores], backend=args.backend, source=str(args.input))
38
+ print(f"{len(kpts)} person(s) -> {out_dir / stem}.png, .{args.format}")
39
+ return 0
40
+
41
+
42
+ def cmd_video(args) -> int:
43
+ from wholebodypose import PoseEstimator, save_poses
44
+
45
+ est = PoseEstimator(
46
+ args.backend,
47
+ device=args.device,
48
+ mode_coco=args.style == "coco133",
49
+ verbose=not args.quiet,
50
+ multiperson=args.multiperson,
51
+ max_people=args.max_people,
52
+ )
53
+ res = est.process_video(
54
+ str(args.input),
55
+ None if args.no_render else args.output,
56
+ multiperson=args.multiperson,
57
+ video_processing_fps=args.fps,
58
+ max_frames=args.max_frames,
59
+ background_plot=args.background,
60
+ resize_width=args.resize_width or None,
61
+ )
62
+ out = Path(args.output) / f"{Path(args.input).stem}_{args.backend}.{args.format}"
63
+ meta = {"backend": args.backend, "source": str(args.input), "fps": res["processing_fps"]}
64
+ meta["frame_size"] = res["frame_size"]
65
+ if "track_ids" in res: # per-frame person IDs, aligned with the people of each frame
66
+ meta["track_ids"] = [ids.tolist() for ids in res["track_ids"]]
67
+ save_poses(out, res["total_keypoints"], res["total_scores"], **meta)
68
+ print(f"{res['n_frames']} frames -> {out}" + (f", {res['filepath_result']}" if "filepath_result" in res else ""))
69
+ return 0
70
+
71
+
72
+ def cmd_backends(args) -> int:
73
+ import importlib.util
74
+
75
+ from wholebodypose.api import BACKENDS, install_command
76
+
77
+ for b in BACKENDS.values():
78
+ print(f"{b.name:10s} {install_command(b.extra):40s} {b.description}")
79
+ try:
80
+ import onnxruntime as ort
81
+
82
+ print(f"onnxruntime {ort.__version__}: {', '.join(ort.get_available_providers())}")
83
+ except ImportError:
84
+ print("onnxruntime: not installed (pip install onnxruntime or onnxruntime-gpu)")
85
+ optional = {"mediapipe": "mediapipe", "imageio_ffmpeg": "video", "padasip": "filters", "h5py": "datasets"}
86
+ found = [extra for mod, extra in optional.items() if importlib.util.find_spec(mod) is not None]
87
+ print("extras: " + (", ".join(found) if found else "none installed"))
88
+ return 0
89
+
90
+
91
+ def cmd_download(args) -> int:
92
+ from wholebodypose.weights import WEIGHTS, get_weight
93
+
94
+ keys = args.keys or list(WEIGHTS)
95
+ for k in keys:
96
+ print(f"{k:16s} {get_weight(k, verbose=not args.quiet)}")
97
+ return 0
98
+
99
+
100
+ def build_parser() -> argparse.ArgumentParser:
101
+ from wholebodypose import __version__
102
+
103
+ parser = argparse.ArgumentParser(
104
+ prog="wholebodypose",
105
+ description="Whole-body (COCO-133) pose estimation.",
106
+ epilog=CITE_LINE,
107
+ formatter_class=argparse.RawDescriptionHelpFormatter,
108
+ )
109
+ parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}\n{CITE_LINE}")
110
+ sub = parser.add_subparsers(dest="command", required=True)
111
+
112
+ p = sub.add_parser("image", help="estimate poses on an image")
113
+ p.add_argument("input", type=Path)
114
+ p.add_argument("--output", "-o", default="outputs")
115
+ p.add_argument("--format", choices=["npz", "json"], default="json")
116
+ _add_common(p)
117
+ p.set_defaults(func=cmd_image)
118
+
119
+ p = sub.add_parser("video", help="estimate poses on a video")
120
+ p.add_argument("input", type=Path)
121
+ p.add_argument("--output", "-o", default="outputs")
122
+ p.add_argument("--format", choices=["npz", "json"], default="npz")
123
+ p.add_argument("--multiperson", action="store_true", help="keep every person, with stable track IDs")
124
+ p.add_argument("--max-people", type=int, default=None, help="cap on people (vitpose/mediapipe)")
125
+ p.add_argument("--fps", type=float, default=None, help="sub-sample input to this FPS")
126
+ p.add_argument("--max-frames", type=int, default=None)
127
+ p.add_argument("--resize-width", type=int, default=640, help="0 keeps original size")
128
+ p.add_argument("--background", default=None, help="draw on a solid color (black, white, ...)")
129
+ p.add_argument("--no-render", action="store_true", help="only save keypoints")
130
+ _add_common(p)
131
+ p.set_defaults(func=cmd_video)
132
+
133
+ p = sub.add_parser("backends", help="list backends and their install extras")
134
+ p.set_defaults(func=cmd_backends)
135
+
136
+ p = sub.add_parser("download", help="pre-download model weights")
137
+ p.add_argument("keys", nargs="*", help="weight keys (default: all)")
138
+ p.add_argument("--quiet", "-q", action="store_true")
139
+ p.set_defaults(func=cmd_download)
140
+ return parser
141
+
142
+
143
+ def main(argv: list[str] | None = None) -> int:
144
+ args = build_parser().parse_args(argv)
145
+ return args.func(args)
146
+
147
+
148
+ if __name__ == "__main__": # pragma: no cover
149
+ raise SystemExit(main())
@@ -0,0 +1,33 @@
1
+ """ISLR pose datasets: published HDF5 schema, dataset adapters and the video -> HDF5 builder.
2
+
3
+ >>> from wholebodypose.datasets import read_hdf5 # doctest: +SKIP
4
+ >>> samples = read_hdf5("ISLR/WLASL/WLASL100/WLASL100_135-Test.hdf5") # doctest: +SKIP
5
+ >>> samples[0]["data"].shape # doctest: +SKIP
6
+ (35, 2, 135)
7
+
8
+ Needs ``pip install 'wholebodypose[datasets]'`` (h5py) for the HDF5 functions.
9
+ """
10
+
11
+ from wholebodypose.datasets.hdf5 import (
12
+ add_midpoints,
13
+ compare_arrays,
14
+ iter_samples,
15
+ read_hdf5,
16
+ split_filename,
17
+ to_published_array,
18
+ write_sample,
19
+ )
20
+ from wholebodypose.datasets.sources import SPECS, Sample, load_samples
21
+
22
+ __all__ = [
23
+ "SPECS",
24
+ "Sample",
25
+ "add_midpoints",
26
+ "compare_arrays",
27
+ "iter_samples",
28
+ "load_samples",
29
+ "read_hdf5",
30
+ "split_filename",
31
+ "to_published_array",
32
+ "write_sample",
33
+ ]