poseorbit 0.1.1__py3-none-any.whl

poseorbit/__init__.py

@@ -0,0 +1,107 @@
+"""poseorbit: find the people in a picture, pick one (or everyone), turn the
+pose in 3D, and draw the skeleton a pose-conditioned image model follows.
+
+    from poseorbit import Detector, Camera, pose
+
+    detector = Detector()
+    result = pose(detector, picture, size=(832, 1216), person=0,
+                  camera=Camera(yaw=45), style="openpose")
+    result.skeleton.save("skeleton.png")
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import numpy as np
+from PIL import Image
+
+from .detect import KEYPOINT_THRESHOLD, Detector, NoPersonError, Person, most_confident
+from .draw import STYLES, Style, letterbox, render
+from .geometry import MAX_PITCH, MAX_YAW, MAX_ZOOM, MIN_ZOOM, Camera, Framing, fit, frame, scene_centre, view
+
+__version__ = "0.1.1"
+
+# Person index meaning "everyone detected", for a group pose.
+ALL_PEOPLE = -1
+
+__all__ = [
+    "ALL_PEOPLE",
+    "Camera",
+    "Detector",
+    "Framing",
+    "KEYPOINT_THRESHOLD",
+    "MAX_PITCH",
+    "MAX_YAW",
+    "MAX_ZOOM",
+    "MIN_ZOOM",
+    "NoPersonError",
+    "Person",
+    "PoseResult",
+    "STYLES",
+    "Style",
+    "letterbox",
+    "pose",
+    "render",
+]
+
+
+@dataclass
+class PoseResult:
+    skeleton: Image.Image
+    # Everyone detected, left to right, and which of them was drawn (ALL_PEOPLE for all).
+    people: list[Person]
+    person: int
+    # The camera and framing actually used, after clamping.
+    camera: Camera
+    framing: Framing
+    # The drawn people's body joints (of 17 each) that are seen and inside the
+    # canvas, for the one with the most: few left (a close-up) means a
+    # body-only skeleton has little to follow.
+    joints_in_frame: int
+
+
+def chosen(people: list[Person], person: int | None) -> tuple[int, list[Person]]:
+    """`person` resolved (None = the most confident) and the people it means."""
+    if person is None:
+        person = most_confident(people)
+    if person == ALL_PEOPLE:
+        return person, people
+    if 0 <= person < len(people):
+        return person, [people[person]]
+    raise ValueError(f"No person {person}: {len(people)} found.")
+
+
+def pose(
+    detector: Detector,
+    image: Image.Image,
+    size: tuple[int, int],
+    person: int | None = None,
+    camera: Camera | None = None,
+    style: Style = "dwpose",
+    depth: bool = False,
+    framing: Framing | None = None,
+) -> PoseResult:
+    """Detect, choose, turn and draw in one call.
+
+    `person` is an index into the left-to-right order, ALL_PEOPLE for
+    everyone, None for the most confident. A `camera` other than the front
+    view needs depth, so it is detected then whatever `depth` says. The
+    skeleton is drawn at `size` (the output's width, height), letterboxed,
+    then `framing` zooms and moves it on that canvas.
+    """
+    camera = (camera or Camera()).clamped()
+    framing = (framing or Framing()).clamped()
+    people = detector.detect(image, depth=depth or not camera.is_front)
+    person, drawn = chosen(people, person)
+    points = np.stack([p.points_3d for p in drawn])
+    if camera.is_front:
+        flat = points[..., :2]
+    else:
+        # Everyone turns around one shared centre, so a group keeps its layout.
+        flat = view(points, scene_centre(points), camera)
+    keypoints = frame(fit(flat, (image.width, image.height), size), size, framing)
+    scores = np.stack([p.scores for p in drawn])
+    inside = (keypoints >= 0).all(axis=-1) & (keypoints < np.array(size)).all(axis=-1)
+    joints = int(((scores[:, :17] >= KEYPOINT_THRESHOLD) & inside[:, :17]).sum(axis=1).max())
+    return PoseResult(render(keypoints, scores, size, style), people, person, camera, framing, joints)

poseorbit/__main__.py

@@ -0,0 +1,60 @@
+"""python -m poseorbit serve [--host 127.0.0.1] [--port 7870] [--weights-dir DIR]
+python -m poseorbit draw PICTURE OUT.png [--size 832x1216] [--person N] [--yaw D] [--pitch D]
+                         [--zoom Z --centre X,Y] [--style S]"""
+
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(prog="poseorbit")
+    commands = parser.add_subparsers(dest="command", required=True)
+
+    serve = commands.add_parser("serve", help="answer /api/pose over HTTP")
+    serve.add_argument("--host", default="127.0.0.1")
+    serve.add_argument("--port", type=int, default=7870)
+    serve.add_argument("--weights-dir", type=Path, default=None)
+
+    draw = commands.add_parser("draw", help="draw one picture's skeleton to a PNG")
+    draw.add_argument("picture", type=Path)
+    draw.add_argument("out", type=Path)
+    draw.add_argument("--size", default=None, help="WIDTHxHEIGHT (default: the picture's)")
+    draw.add_argument("--person", type=int, default=None, help="index, or -1 for everyone")
+    draw.add_argument("--yaw", type=float, default=0.0)
+    draw.add_argument("--pitch", type=float, default=0.0)
+    draw.add_argument("--zoom", type=float, default=1.0)
+    draw.add_argument("--centre", default="0.5,0.5", help="the canvas point to centre, as fractions X,Y")
+    draw.add_argument("--style", default="dwpose", choices=["dwpose", "openpose"])
+    draw.add_argument("--weights-dir", type=Path, default=None)
+
+    args = parser.parse_args()
+    if args.command == "serve":
+        import uvicorn
+
+        from .server import create_app
+
+        uvicorn.run(create_app(args.weights_dir), host=args.host, port=args.port, log_level="warning")
+        return
+
+    from PIL import Image
+
+    from . import Camera, Detector, Framing, pose
+
+    picture = Image.open(args.picture)
+    size = tuple(int(part) for part in args.size.lower().split("x")) if args.size else picture.size
+    x, y = (float(part) for part in args.centre.split(","))
+    result = pose(
+        Detector(args.weights_dir), picture, size, args.person, Camera(args.yaw, args.pitch), args.style,
+        framing=Framing(args.zoom, x, y),
+    )
+    result.skeleton.save(args.out)
+    print(
+        f"{len(result.people)} found; drew person {result.person} at yaw {result.camera.yaw}, pitch {result.camera.pitch}, "
+        f"zoom {result.framing.zoom}; {result.joints_in_frame} body joints in frame"
+    )
+
+
+if __name__ == "__main__":
+    main()

poseorbit/api.py

@@ -0,0 +1,132 @@
+"""The `/api/pose` request and answer, independent of any web framework, so
+poseorbit's own server and a generation server that embeds poseorbit speak
+exactly the same JSON.
+
+Request:
+    { "image_base64": "...", "width": 832, "height": 1216,
+      "person": 0,                          # optional; -1 = everyone, absent = most confident
+      "want_3d": true,                      # optional; answer with each person's 3D points
+      "camera": { "yaw": 30, "pitch": 10,   # optional; degrees, see geometry.py
+                  "framing": { "zoom": 3, "x": 0.5, "y": 0.2 } },  # optional; the canvas point to centre, and zoom
+      "style": "openpose" }                 # optional; "dwpose" (default) or "openpose"
+
+Answer:
+    { "skeleton_base64": "...png...", "width": 832, "height": 1216, "person": 0,
+      "camera": { "yaw": 30, "pitch": 10, "framing": { "zoom": 3, "x": 0.5, "y": 0.2 } },
+      "style": "openpose",
+      "limits": { "yaw": 90, "pitch": 45, "zoom": [0.5, 6] },
+      "joints_in_frame": 9,                 # body joints (of 17) seen inside the canvas, best drawn person
+      "people": [ { "bbox": [x0, y0, x1, y1],                # fractions of the picture
+                    "points_3d": [[x, y, z], ...],          # with want_3d: 133 points, fractions of the picture's width
+                    "scores": [...] } ] }                   # with want_3d: 133 scores
+"""
+
+from __future__ import annotations
+
+import base64
+import io
+import math
+from typing import Any
+
+from PIL import Image
+
+from . import ALL_PEOPLE, MAX_PITCH, MAX_YAW, MAX_ZOOM, MIN_ZOOM, STYLES, Camera, Detector, Framing, pose
+from .draw import Style
+
+
+class BadRequest(ValueError):
+    """The request is wrong; answer 400 with the message."""
+
+
+def decode_image(data: str) -> Image.Image:
+    if data.startswith("data:"):
+        data = data.split(",", 1)[1]
+    try:
+        image = Image.open(io.BytesIO(base64.b64decode(data)))
+        image.load()
+    except Exception as error:  # noqa: BLE001 - any decode failure is the caller's input
+        raise BadRequest("The picture could not be read.") from error
+    return image
+
+
+def encode_png(image: Image.Image) -> str:
+    buffer = io.BytesIO()
+    image.save(buffer, format="PNG")
+    return base64.b64encode(buffer.getvalue()).decode("ascii")
+
+
+def _number(value: Any, name: str) -> float:
+    if isinstance(value, bool) or not isinstance(value, (int, float)) or not math.isfinite(value):
+        raise BadRequest(f"{name} must be a number")
+    return float(value)
+
+
+def parse_camera(value: Any) -> tuple[Camera | None, Framing | None]:
+    if value is None:
+        return None, None
+    if not isinstance(value, dict):
+        raise BadRequest("camera must be an object { yaw, pitch, framing }")
+    camera = Camera(
+        yaw=_number(value.get("yaw", 0), "camera.yaw"),
+        pitch=_number(value.get("pitch", 0), "camera.pitch"),
+    ).clamped()
+    framing = value.get("framing")
+    if framing is None:
+        return camera, None
+    if not isinstance(framing, dict):
+        raise BadRequest("camera.framing must be an object { zoom, x, y }")
+    return camera, Framing(
+        zoom=_number(framing.get("zoom", 1), "camera.framing.zoom"),
+        x=_number(framing.get("x", 0.5), "camera.framing.x"),
+        y=_number(framing.get("y", 0.5), "camera.framing.y"),
+    ).clamped()
+
+
+def handle(detector: Detector, body: dict[str, Any], default_style: Style = "dwpose") -> dict[str, Any]:
+    """Answers one request. Raises BadRequest (and NoPersonError, a ValueError) for a 400."""
+    data = body.get("image_base64")
+    if not isinstance(data, str) or not data:
+        raise BadRequest("image_base64 is required")
+    image = decode_image(data)
+    width = int(_number(body.get("width", image.width), "width"))
+    height = int(_number(body.get("height", image.height), "height"))
+    if not (64 <= width <= 4096 and 64 <= height <= 4096):
+        raise BadRequest("width and height must be 64-4096")
+    person = body.get("person")
+    if person is not None and (isinstance(person, bool) or not isinstance(person, int) or person < ALL_PEOPLE):
+        raise BadRequest("person must be an index, or -1 for everyone")
+    style = body.get("style") or default_style
+    if style not in STYLES:
+        raise BadRequest(f"style must be one of {', '.join(STYLES)}")
+    want_3d = body.get("want_3d") is True
+
+    camera, framing = parse_camera(body.get("camera"))
+    result = pose(detector, image, (width, height), person, camera, style, depth=want_3d, framing=framing)
+    people = []
+    for found in result.people:
+        x0, y0, x1, y1 = found.bbox
+        # Keypoints can be guessed past the edge (feet below the frame); the
+        # box is for drawing over the picture, so it stays inside it.
+        box = [x0 / image.width, y0 / image.height, x1 / image.width, y1 / image.height]
+        entry: dict[str, Any] = {"bbox": [round(min(1.0, max(0.0, edge)), 5) for edge in box]}
+        if want_3d:
+            # One unit for all three axes (the picture's width), so a viewer
+            # can draw them without knowing the picture's size or aspect.
+            entry["points_3d"] = (found.points_3d / image.width).round(5).tolist()
+            entry["scores"] = found.scores.round(3).tolist()
+        people.append(entry)
+    return {
+        "skeleton_base64": encode_png(result.skeleton),
+        "width": width,
+        "height": height,
+        "person": result.person,
+        "camera": {
+            "yaw": result.camera.yaw,
+            "pitch": result.camera.pitch,
+            "framing": {"zoom": result.framing.zoom, "x": result.framing.x, "y": result.framing.y},
+        },
+        "style": style,
+        "limits": {"yaw": MAX_YAW, "pitch": MAX_PITCH, "zoom": [MIN_ZOOM, MAX_ZOOM]},
+        "joints_in_frame": result.joints_in_frame,
+        "people": people,
+    }

poseorbit/detect.py

@@ -0,0 +1,205 @@
+"""Finding people in a picture: their 133 whole-body keypoints and, on request,
+how far each keypoint sits in front of or behind the figure.
+
+One YOLOX person detector feeds two keypoint models on the same boxes:
+
+- RTMW-DW-x-l (DWPose, COCO-WholeBody 133 points) for x and y. Skeleton-
+  conditioned models are commonly trained on skeletons from this detector,
+  so one drawn from it looks like their training data.
+- RTMW3D-x for depth only, when asked. Its own x and y are close to DWPose's
+  (median 17 px apart on an 832x1216 picture) but not equal; taking x and y
+  from DWPose keeps a front view of the 3D pose identical to the 2D one.
+
+Both run on the CPU with onnxruntime through rtmlib: about 0.7 s for one
+person at 832x1216, all three models together.
+"""
+
+from __future__ import annotations
+
+import threading
+from dataclasses import dataclass
+from pathlib import Path
+
+import numpy as np
+from PIL import Image
+
+# A keypoint counts as seen at this score: rtmlib's default drawing cut-off.
+KEYPOINT_THRESHOLD = 0.3
+# Of the 17 body keypoints, how many must be seen for a detection to be a person.
+MIN_BODY_KEYPOINTS = 8
+
+# The ONNX files: (Hugging Face repository, path in it, local name). All are
+# OpenMMLab models under Apache-2.0. The first two come zipped from rtmlib's
+# own mirror of OpenMMLab's downloads (download.openmmlab.com has been
+# unreliable); the onnx inside is kept, renamed.
+DETECTOR_FILE = ("Tau-J/RTMPose", "rtmposev1/onnx_sdk/yolox_m_8xb8-300e_humanart-c2c7a14a.zip", "yolox_m_8xb8-300e_humanart-c2c7a14a.onnx")
+POSE_2D_FILE = ("Tau-J/RTMPose", "rtmw/onnx_sdk/rtmw-dw-x-l_simcc-cocktail14_270e-256x192_20231122.zip", "rtmw-dw-x-l_simcc-cocktail14_270e-256x192_20231122.onnx")
+POSE_3D_FILE = ("Soykaf/RTMW3D-x", "onnx/rtmw3d-x_8xb64_cocktail14-384x288-b0a0eab7_20240626.onnx", "rtmw3d-x_8xb64_cocktail14-384x288-b0a0eab7_20240626.onnx")
+# Where the files go when the caller names no folder.
+DEFAULT_WEIGHTS_DIR = Path.home() / ".cache" / "poseorbit"
+
+# RTMW3D's depth: 288 bins (its input width) spanning +-Z_RANGE metres around
+# the hips, as its SimCC3D codec was trained. rtmlib's own conversion divides
+# by the input height instead, so the bins are read here directly.
+DEPTH_BINS = 288
+Z_RANGE = 2.1744869
+# Shoulders-to-hips length used to turn metres into the picture's pixels.
+# Adult figures measure about this; the result only sets how deep a turned
+# pose looks, so being off by a little shows as a slightly flatter or deeper
+# figure, not a broken one.
+TORSO_METRES = 0.5
+
+
+class NoPersonError(ValueError):
+    """The picture has nobody in it that is seen well enough to follow."""
+
+
+@dataclass
+class Person:
+    """One detected figure, in the picture's pixels."""
+
+    keypoints: np.ndarray  # (133, 2) x, y
+    scores: np.ndarray  # (133,)
+    # Each keypoint's distance behind the hips' plane, in the same pixels as x
+    # and y (positive = away from the viewer); None unless depth was asked for.
+    depth: np.ndarray | None = None
+
+    @property
+    def visible(self) -> int:
+        """How many of the 17 body keypoints are seen: how sure this is a person."""
+        return int((self.scores[:17] >= KEYPOINT_THRESHOLD).sum())
+
+    @property
+    def bbox(self) -> tuple[float, float, float, float]:
+        """(x0, y0, x1, y1) around the keypoints that would be drawn."""
+        shown = self.keypoints[self.scores >= KEYPOINT_THRESHOLD]
+        x0, y0 = shown.min(axis=0)
+        x1, y1 = shown.max(axis=0)
+        return float(x0), float(y0), float(x1), float(y1)
+
+    @property
+    def points_3d(self) -> np.ndarray:
+        """(133, 3): x, y and depth, all in pixels. Flat (depth 0) without depth."""
+        depth = self.depth if self.depth is not None else np.zeros(len(self.keypoints))
+        return np.column_stack([self.keypoints, depth])
+
+
+def model_file(spec: tuple[str, str, str], weights_dir: Path | None) -> str:
+    """A local path to one of the ONNX files, downloading it the first time.
+
+    Kept as `<weights_dir>/<local name>` (default ~/.cache/poseorbit).
+    """
+    import shutil
+    import zipfile
+
+    from huggingface_hub import hf_hub_download
+
+    repo, filename, name = spec
+    folder = weights_dir or DEFAULT_WEIGHTS_DIR
+    local = folder / name
+    if local.is_file() and local.stat().st_size > 1_000_000:
+        return str(local)
+    folder.mkdir(parents=True, exist_ok=True)
+    downloaded = hf_hub_download(repo, filename)
+    partial = local.with_suffix(".part")
+    if filename.endswith(".zip"):
+        with zipfile.ZipFile(downloaded) as archive:
+            member = next(item for item in archive.namelist() if item.endswith(".onnx"))
+            with archive.open(member) as source, open(partial, "wb") as target:
+                shutil.copyfileobj(source, target)
+    else:
+        shutil.copyfile(downloaded, partial)
+    partial.replace(local)
+    return str(local)
+
+
+def depth_in_pixels(depth_bins: np.ndarray, keypoints: np.ndarray, scores: np.ndarray) -> np.ndarray:
+    """RTMW3D's depth bins for one person as pixels of the picture, relative to the hips.
+
+    The model gives depth in metres; the picture is in pixels. The scale comes
+    from the torso: its length on screen is the true length foreshortened by
+    how far the shoulders lean toward or away from the viewer, which the depth
+    itself says, so a figure bending over is not mistaken for a small one.
+    """
+    metres = (depth_bins / (DEPTH_BINS / 2) - 1) * Z_RANGE
+    shoulders = keypoints[[5, 6]].mean(axis=0)
+    hips = keypoints[[11, 12]].mean(axis=0)
+    seen = scores[[5, 6, 11, 12]].min() >= KEYPOINT_THRESHOLD
+    hips_depth = metres[[11, 12]].mean()
+    if not seen:
+        # No torso to measure: fall back to the figure's height as ~1.6 m.
+        shown = keypoints[scores >= KEYPOINT_THRESHOLD]
+        height = float(np.ptp(shown[:, 1])) if len(shown) else 1.0
+        return (metres - hips_depth) * max(height, 1.0) / 1.6
+    lean = metres[[5, 6]].mean() - hips_depth
+    on_screen = float(np.hypot(*(shoulders - hips)))
+    # Never let the lean eat more than 70% of the torso: past that the
+    # estimate is noise, and dividing by almost nothing would explode.
+    along = max(TORSO_METRES**2 - lean**2, (0.3 * TORSO_METRES) ** 2) ** 0.5
+    pixels_per_metre = max(on_screen, 1.0) / along
+    return (metres - hips_depth) * pixels_per_metre
+
+
+class Detector:
+    """Loads its models on first use and is safe to share between threads."""
+
+    def __init__(self, weights_dir: Path | None = None, device: str = "cpu"):
+        self.weights_dir = weights_dir
+        self.device = device
+        self._lock = threading.Lock()
+        self._boxes = None
+        self._pose_2d = None
+        self._pose_3d = None
+
+    def _models(self, depth: bool):
+        import onnxruntime
+        from rtmlib import RTMPose, RTMPose3d, YOLOX
+
+        # RTMW3D's file carries unused initialisers, and onnxruntime warns
+        # about each one on every load; errors still show.
+        onnxruntime.set_default_logger_severity(3)
+        options = {"backend": "onnxruntime", "device": self.device}
+        if self._boxes is None:
+            self._boxes = YOLOX(model_file(DETECTOR_FILE, self.weights_dir), model_input_size=(640, 640), **options)
+            self._pose_2d = RTMPose(model_file(POSE_2D_FILE, self.weights_dir), model_input_size=(192, 256), **options)
+        if depth and self._pose_3d is None:
+            self._pose_3d = RTMPose3d(model_file(POSE_3D_FILE, self.weights_dir), model_input_size=(288, 384), **options)
+        return self._boxes, self._pose_2d, self._pose_3d
+
+    def detect(self, image: Image.Image, depth: bool = False) -> list[Person]:
+        """Everyone in `image`, ordered left to right by the centre of the figure,
+        so the same picture always numbers its people the same way.
+
+        Raises NoPersonError when nobody is seen well enough.
+        """
+        import cv2
+
+        bgr = cv2.cvtColor(np.asarray(image.convert("RGB")), cv2.COLOR_RGB2BGR)
+        with self._lock:
+            boxes_model, pose_2d, pose_3d = self._models(depth)
+            boxes = boxes_model(bgr)
+            if len(boxes) == 0:
+                raise NoPersonError("Nobody was found in the picture.")
+            keypoints, scores = pose_2d(bgr, bboxes=boxes)
+            depth_bins = pose_3d(bgr, bboxes=boxes)[2][..., 2] if depth else None
+        # rtmlib returns a "person" even for a blank picture, just with every
+        # score low: measured, a white canvas gave 2 of 17 body keypoints over
+        # the threshold and noise 0, against 17 for real figures. Half the body
+        # is the bar, so a skeleton made of guesses is refused, not followed --
+        # per person, so a crowd's half-hidden extras don't become pickable ghosts.
+        people = []
+        for index in range(len(keypoints)):
+            person = Person(np.asarray(keypoints[index], float), np.asarray(scores[index], float))
+            if person.visible < MIN_BODY_KEYPOINTS:
+                continue
+            if depth_bins is not None:
+                person.depth = depth_in_pixels(np.asarray(depth_bins[index], float), person.keypoints, person.scores)
+            people.append(person)
+        if not people:
+            raise NoPersonError("Nobody was found in the picture.")
+        people.sort(key=lambda person: (person.bbox[0] + person.bbox[2]) / 2)
+        return people
+
+
+def most_confident(people: list[Person]) -> int:
+    return max(range(len(people)), key=lambda index: people[index].visible)

poseorbit/draw.py

@@ -0,0 +1,97 @@
+"""Drawing skeletons the way pose-conditioned models were trained to read them.
+
+- "dwpose": rtmlib's COCO-WholeBody drawing (thin coloured lines and dots),
+  the usual input of DWPose-trained models such as Anima-Control-Pose.
+- "openpose": the 18 OpenPose body points with thick limbs that grow with
+  the canvas, as xinsir/controlnet-openpose-sdxl-1.0 was trained. Body only:
+  hands and face were not in its training skeletons.
+  `_draw_openpose_body` follows the draw_bodypose function on that model's
+  card (Apache-2.0), itself a modification of controlnet_aux's (Apache-2.0);
+  see NOTICE.
+
+Both on black, at the output's own size.
+"""
+
+from __future__ import annotations
+
+import math
+from typing import Literal
+
+import numpy as np
+from PIL import Image
+
+from .detect import KEYPOINT_THRESHOLD
+
+Style = Literal["dwpose", "openpose"]
+STYLES: tuple[Style, ...] = ("dwpose", "openpose")
+
+# OpenPose's 18-point limbs (1-based, as published) and its colours (RGB).
+_OPENPOSE_LIMBS = [
+    (2, 3), (2, 6), (3, 4), (4, 5), (6, 7), (7, 8), (2, 9), (9, 10), (10, 11),
+    (2, 12), (12, 13), (13, 14), (2, 1), (1, 15), (15, 17), (1, 16), (16, 18),
+]
+_OPENPOSE_COLOURS = [
+    (255, 0, 0), (255, 85, 0), (255, 170, 0), (255, 255, 0), (170, 255, 0), (85, 255, 0),
+    (0, 255, 0), (0, 255, 85), (0, 255, 170), (0, 255, 255), (0, 170, 255), (0, 85, 255),
+    (0, 0, 255), (85, 0, 255), (170, 0, 255), (255, 0, 255), (255, 0, 170), (255, 0, 85),
+]
+
+
+def render(keypoints: np.ndarray, scores: np.ndarray, size: tuple[int, int], style: Style = "dwpose") -> Image.Image:
+    """`keypoints` (N, 133, 2) in the canvas's pixels with `scores` (N, 133), on a `size` canvas."""
+    if style not in STYLES:
+        raise ValueError(f"Unknown skeleton style {style!r}; one of {', '.join(STYLES)}")
+    width, height = size
+    canvas = np.zeros((height, width, 3), np.uint8)
+    if style == "openpose":
+        from rtmlib.tools.pose_estimation.post_processings import convert_coco_to_openpose
+
+        body, body_scores = convert_coco_to_openpose(keypoints, scores)
+        for person, person_scores in zip(body[:, :18], body_scores[:, :18]):
+            _draw_openpose_body(canvas, person, person_scores)
+        return Image.fromarray(canvas)
+
+    import cv2
+    from rtmlib import draw_skeleton
+
+    canvas = draw_skeleton(canvas, keypoints, scores, openpose_skeleton=False, kpt_thr=KEYPOINT_THRESHOLD)
+    return Image.fromarray(cv2.cvtColor(canvas, cv2.COLOR_BGR2RGB))
+
+
+def _draw_openpose_body(canvas: np.ndarray, points: np.ndarray, scores: np.ndarray) -> None:
+    """One person's 18 points onto an RGB canvas, in place."""
+    import cv2
+
+    height, width = canvas.shape[:2]
+    longest = max(width, height)
+    # The card's steps: 1x under 500 px, then one more per 1000 px.
+    ratio = 1.0 if longest < 500 else 2.0 if longest < 1000 else min(7.0, 3.0 + (longest - 1000) // 1000)
+    seen = scores >= KEYPOINT_THRESHOLD
+    for (first, second), colour in zip(_OPENPOSE_LIMBS, _OPENPOSE_COLOURS):
+        a, b = first - 1, second - 1
+        if not (seen[a] and seen[b]):
+            continue
+        (x0, y0), (x1, y1) = points[a], points[b]
+        length = math.hypot(x1 - x0, y1 - y0)
+        angle = math.degrees(math.atan2(y0 - y1, x0 - x1))
+        polygon = cv2.ellipse2Poly(
+            (int((x0 + x1) / 2), int((y0 + y1) / 2)), (int(length / 2), int(4 * ratio)), int(angle), 0, 360, 1
+        )
+        cv2.fillConvexPoly(canvas, polygon, [int(c * 0.6) for c in colour])
+    for point, colour, shown in zip(points, _OPENPOSE_COLOURS, seen):
+        if shown:
+            cv2.circle(canvas, (int(point[0]), int(point[1])), int(4 * ratio), colour, thickness=-1)
+
+
+def letterbox(skeleton: Image.Image, size: tuple[int, int]) -> Image.Image:
+    """A skeleton drawn for another size, scaled uniformly and centred on a black
+    `size` canvas, so it lines up with the output however it was drawn."""
+    if skeleton.size == size:
+        return skeleton.convert("RGB")
+    scale = min(size[0] / skeleton.width, size[1] / skeleton.height)
+    resized = skeleton.convert("RGB").resize(
+        (max(1, round(skeleton.width * scale)), max(1, round(skeleton.height * scale))), Image.Resampling.BILINEAR
+    )
+    canvas = Image.new("RGB", size, (0, 0, 0))
+    canvas.paste(resized, ((size[0] - resized.width) // 2, (size[1] - resized.height) // 2))
+    return canvas