poseorbit 0.2.0__tar.gz → 0.3.0__tar.gz

{poseorbit-0.2.0 → poseorbit-0.3.0}/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 0.3.0 (2026-10-25)
+
+- **Move a joint**: `pose(..., edits=[Edit(person, joint, to)])` turns a
+  joint about its parent to point at `to`, carrying everything hanging from
+  it, so no bone changes length. The head, arms, legs and feet move
+  (`MOVABLE`); a hand moves with its wrist and the face with the head; the
+  hips stay put. Edits apply in order. `bend` and `apply_edits` do the same
+  for points of your own, and `poseorbit.body` holds the keypoint names and
+  their tree.
+- `/api/pose` takes `"edits": [{ "person", "joint", "to": [x, y, z] }]`
+  (up to 256, `to` in picture widths like `points_3d`) and answers
+  `"movable"`, the joints it may move, so a client knows it may send them.
+  `points_3d` stays as detected.
+- A request with edits detects depth even for the front view.
+- The command line does not take edits yet.
+
 ## 0.2.0 (2026-10-11)
 
 - **Choose some of the people**: `pose(..., person=[0, 2])` draws just those

{poseorbit-0.2.0 → poseorbit-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: poseorbit
-Version: 0.2.0
+Version: 0.3.0
 Summary: Find the people in a picture, turn their pose in 3D, and draw the skeleton a pose-conditioned image model follows.
 Project-URL: Homepage, https://github.com/33rd-kk/poseorbit
 Project-URL: Documentation, https://33rd-kk.github.io/poseorbit/
@@ -200,7 +200,7 @@ is used; nothing is left behind in Hugging Face's own cache.
 ```python
 from pathlib import Path
 from PIL import Image
-from poseorbit import ALL_PEOPLE, Camera, Detector, Framing, pose
+from poseorbit import ALL_PEOPLE, Camera, Detector, Edit, Framing, pose
 
 detector = Detector(weights_dir=Path("weights"))   # load once, reuse; thread-safe
 picture = Image.open("reference.png")
@@ -212,6 +212,10 @@ result = pose(detector, picture, size=(832, 1216), person=ALL_PEOPLE,
               camera=Camera(yaw=-30), style="dwpose")
 result.skeleton            # PIL image, 832x1216, on black
 result.joints_in_frame     # body joints left inside the canvas
+
+# Raise the first person's left wrist; the hand comes with it, the arm keeps its length.
+x, y, z = detector.detect(picture, depth=True)[0].points_3d[9]
+raised = pose(detector, picture, size=(832, 1216), person=0, edits=[Edit(0, 9, (x, y - 200, z))])
 ```
 
 ### With diffusers
@@ -263,7 +267,10 @@ Everything but `image_base64` is optional. `person` is an index into
 `people` (left to right), a list of indices for some of them (`[0, 2]`, up to
 64; answered sorted), `-1` for everyone, or absent for the most confident.
 `person_subsets: true` in the answer tells a client it may send a list (0.2.0
-and later). `want_3d` adds each person's 133 points as `[x, y, z]` in units of
+and later). `edits` (0.3.0 and later) moves joints, in order:
+`[{ "person": 0, "joint": 9, "to": [x, y, z] }]`, up to 256, `to` in units of
+the picture's width; `movable` in the answer lists the joints it may move.
+`want_3d` adds each person's 133 points as `[x, y, z]` in units of
 the picture's width, for a 3D viewer. Out-of-range angles and zoom are
 clamped; a picture with nobody in it, or a person index past the end, gets a
 400 with a `detail` message. Server and API are 127.0.0.1-only by default.
@@ -273,11 +280,12 @@ clamped; a picture with nobody in it, or a person index past the end, gets a
 | Name | What it is |
 |---|---|
 | `Detector(weights_dir=None, device="cpu")` | Loads the models on first use. `detect(image, depth=False) -> list[Person]`, left to right; raises `NoPersonError`. |
-| `pose(detector, image, size, person=None, camera=None, style="dwpose", depth=False, framing=None) -> PoseResult` | Detect, choose, turn, frame and draw in one call. |
+| `pose(detector, image, size, person=None, camera=None, style="dwpose", depth=False, framing=None, edits=()) -> PoseResult` | Detect, choose, turn, frame and draw in one call. |
 | `Camera(yaw=0, pitch=0)` | Degrees. `+yaw` swings the camera to the viewer's right, `+pitch` raises it. Clamped to `MAX_YAW` (90) / `MAX_PITCH` (45). |
 | `Framing(zoom=1, x=0.5, y=0.5)` | The canvas point `(x, y)` (fractions) goes to the middle, scaled by `zoom` (`MIN_ZOOM` 0.5 to `MAX_ZOOM` 6). |
 | `PoseResult` | `skeleton` (PIL image), `people`, `person`, `camera` and `framing` as used, `joints_in_frame`. |
 | `Person` | `keypoints` (133×2), `scores` (133), `depth` (133 or None), `bbox`, `visible` (body joints seen), `points_3d`. |
+| `Edit(person, joint, to)` | Turn `joint` (one of `MOVABLE`) about its parent to point at `to` (pixels), carrying what hangs from it; bones keep their length. `apply_edits(points, edits)` and `bend(points, joint, to)` do it on arrays. |
 | `render(keypoints, scores, size, style)` | Draw `(N, 133, 2)` keypoints on a black `size` canvas. |
 | `letterbox(skeleton, size)` | Fit a skeleton drawn at another size onto `size`, uniformly scaled and centred. |
 | `poseorbit.api.handle(detector, body, default_style)` | The `/api/pose` handler without a web framework, to embed in another server. |

{poseorbit-0.2.0 → poseorbit-0.3.0}/README.md

@@ -163,7 +163,7 @@ is used; nothing is left behind in Hugging Face's own cache.
 ```python
 from pathlib import Path
 from PIL import Image
-from poseorbit import ALL_PEOPLE, Camera, Detector, Framing, pose
+from poseorbit import ALL_PEOPLE, Camera, Detector, Edit, Framing, pose
 
 detector = Detector(weights_dir=Path("weights"))   # load once, reuse; thread-safe
 picture = Image.open("reference.png")
@@ -175,6 +175,10 @@ result = pose(detector, picture, size=(832, 1216), person=ALL_PEOPLE,
               camera=Camera(yaw=-30), style="dwpose")
 result.skeleton            # PIL image, 832x1216, on black
 result.joints_in_frame     # body joints left inside the canvas
+
+# Raise the first person's left wrist; the hand comes with it, the arm keeps its length.
+x, y, z = detector.detect(picture, depth=True)[0].points_3d[9]
+raised = pose(detector, picture, size=(832, 1216), person=0, edits=[Edit(0, 9, (x, y - 200, z))])
 ```
 
 ### With diffusers
@@ -226,7 +230,10 @@ Everything but `image_base64` is optional. `person` is an index into
 `people` (left to right), a list of indices for some of them (`[0, 2]`, up to
 64; answered sorted), `-1` for everyone, or absent for the most confident.
 `person_subsets: true` in the answer tells a client it may send a list (0.2.0
-and later). `want_3d` adds each person's 133 points as `[x, y, z]` in units of
+and later). `edits` (0.3.0 and later) moves joints, in order:
+`[{ "person": 0, "joint": 9, "to": [x, y, z] }]`, up to 256, `to` in units of
+the picture's width; `movable` in the answer lists the joints it may move.
+`want_3d` adds each person's 133 points as `[x, y, z]` in units of
 the picture's width, for a 3D viewer. Out-of-range angles and zoom are
 clamped; a picture with nobody in it, or a person index past the end, gets a
 400 with a `detail` message. Server and API are 127.0.0.1-only by default.
@@ -236,11 +243,12 @@ clamped; a picture with nobody in it, or a person index past the end, gets a
 | Name | What it is |
 |---|---|
 | `Detector(weights_dir=None, device="cpu")` | Loads the models on first use. `detect(image, depth=False) -> list[Person]`, left to right; raises `NoPersonError`. |
-| `pose(detector, image, size, person=None, camera=None, style="dwpose", depth=False, framing=None) -> PoseResult` | Detect, choose, turn, frame and draw in one call. |
+| `pose(detector, image, size, person=None, camera=None, style="dwpose", depth=False, framing=None, edits=()) -> PoseResult` | Detect, choose, turn, frame and draw in one call. |
 | `Camera(yaw=0, pitch=0)` | Degrees. `+yaw` swings the camera to the viewer's right, `+pitch` raises it. Clamped to `MAX_YAW` (90) / `MAX_PITCH` (45). |
 | `Framing(zoom=1, x=0.5, y=0.5)` | The canvas point `(x, y)` (fractions) goes to the middle, scaled by `zoom` (`MIN_ZOOM` 0.5 to `MAX_ZOOM` 6). |
 | `PoseResult` | `skeleton` (PIL image), `people`, `person`, `camera` and `framing` as used, `joints_in_frame`. |
 | `Person` | `keypoints` (133×2), `scores` (133), `depth` (133 or None), `bbox`, `visible` (body joints seen), `points_3d`. |
+| `Edit(person, joint, to)` | Turn `joint` (one of `MOVABLE`) about its parent to point at `to` (pixels), carrying what hangs from it; bones keep their length. `apply_edits(points, edits)` and `bend(points, joint, to)` do it on arrays. |
 | `render(keypoints, scores, size, style)` | Draw `(N, 133, 2)` keypoints on a black `size` canvas. |
 | `letterbox(skeleton, size)` | Fit a skeleton drawn at another size onto `size`, uniformly scaled and centred. |
 | `poseorbit.api.handle(detector, body, default_style)` | The `/api/pose` handler without a web framework, to embed in another server. |

{poseorbit-0.2.0 → poseorbit-0.3.0}/poseorbit/__init__.py

@@ -17,11 +17,12 @@ from dataclasses import dataclass
 import numpy as np
 from PIL import Image
 
+from .body import MOVABLE, NAMES, Edit, apply_edits, bend
 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.2.0"
+__version__ = "0.3.0"
 
 # Person index meaning "everyone detected", for a group pose.
 ALL_PEOPLE = -1
@@ -30,17 +31,22 @@ __all__ = [
     "ALL_PEOPLE",
     "Camera",
     "Detector",
+    "Edit",
     "Framing",
     "KEYPOINT_THRESHOLD",
     "MAX_PITCH",
     "MAX_YAW",
     "MAX_ZOOM",
     "MIN_ZOOM",
+    "MOVABLE",
+    "NAMES",
     "NoPersonError",
     "Person",
     "PoseResult",
     "STYLES",
     "Style",
+    "apply_edits",
+    "bend",
     "letterbox",
     "pose",
     "render",
@@ -113,11 +119,12 @@ def pose(
     style: Style = "dwpose",
     depth: bool = False,
     framing: Framing | None = None,
+    edits: Sequence[Edit] = (),
 ) -> PoseResult:
     """Detect, choose, turn, frame and draw in one call.
 
-    A `camera` other than the front view needs depth, so it is detected then
-    whatever `depth` says.
+    A `camera` other than the front view, or any `edits`, needs depth, so it
+    is detected then whatever `depth` says.
 
     Args:
         detector: A [Detector][poseorbit.Detector]; load it once and reuse it.
@@ -133,6 +140,9 @@ def pose(
         depth: Detect depth even for the front view (to read
             `Person.depth` from the result).
         framing: Zoom and centre on the canvas; None for the whole picture.
+        edits: Joints to move before turning, in order; see
+            [apply_edits][poseorbit.apply_edits]. `PoseResult.people` stays as
+            detected.
 
     Returns:
         The skeleton, everyone found and how it was drawn.
@@ -140,13 +150,16 @@ def pose(
     Raises:
         NoPersonError: Nobody in the picture is seen well enough.
         ValueError: `person` (or one of a sequence) is past the end of the
-            people found, or the sequence is empty.
+            people found, or the sequence is empty, or an edit names a
+            person past the end or a joint that is not movable.
     """
     camera = (camera or Camera()).clamped()
     framing = (framing or Framing()).clamped()
-    people = detector.detect(image, depth=depth or not camera.is_front)
+    people = detector.detect(image, depth=depth or not camera.is_front or bool(edits))
+    bent = apply_edits([p.points_3d for p in people], edits)
     person, drawn = chosen(people, person)
-    points = np.stack([p.points_3d for p in drawn])
+    indices = range(len(people)) if person == ALL_PEOPLE else [person] if isinstance(person, int) else person
+    points = np.stack([bent[index] for index in indices])
     if camera.is_front:
         flat = points[..., :2]
     else:

{poseorbit-0.2.0 → poseorbit-0.3.0}/poseorbit/api.py

@@ -8,17 +8,20 @@ Request:
       "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"
+      "style": "openpose",                  # optional; "dwpose" (default) or "openpose"
+      "edits": [ { "person": 0, "joint": 9,  # optional; joints to move, in order (see body.py)
+                   "to": [x, y, z] } ] }     # where it points, fractions of the picture's width
 
 Answer:
     { "skeleton_base64": "...png...", "width": 832, "height": 1216, "person": 0,   # or the sorted list asked for
       "person_subsets": true,               # "person" may be a list: a client may offer picking any of them
+      "movable": [0, 5, ...],               # the joints "edits" may move
       "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
+                    "points_3d": [[x, y, z], ...],          # with want_3d: 133 points as detected (before edits), fractions of the picture's width
                     "scores": [...] } ] }                   # with want_3d: 133 scores
 """
 
@@ -31,13 +34,20 @@ 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 . import ALL_PEOPLE, MAX_PITCH, MAX_YAW, MAX_ZOOM, MIN_ZOOM, MOVABLE, STYLES, Camera, Detector, Edit, Framing, pose
 from .draw import Style
 
 # The most people one request may choose by a list: far more than a picture
 # usefully holds, and it bounds the list before anything is detected.
 MAX_CHOSEN = 64
 
+# The most edits one request may carry: hundreds of drags, and it bounds the
+# work before anything is detected.
+MAX_EDITS = 256
+
+# How far an edit may point, in picture widths: well past any figure.
+_MAX_REACH = 16
+
 
 class BadRequest(ValueError):
     """The request is wrong; answer 400 with the message."""
@@ -98,6 +108,40 @@ def parse_camera(value: Any) -> tuple[Camera | None, Framing | None]:
     ).clamped()
 
 
+def parse_edits(value: Any, width: int) -> list[Edit]:
+    """The request's `edits` as [Edit][poseorbit.Edit]s in pixels (empty when absent).
+
+    Args:
+        value: The `edits` list: `{ person, joint, to: [x, y, z] }` each, `to`
+            in fractions of the picture's width.
+        width: The picture's width in pixels.
+
+    Raises:
+        BadRequest: It is not such a list, too long, names a joint that is
+            not movable, or points too far.
+    """
+    if value is None:
+        return []
+    if not isinstance(value, list) or len(value) > MAX_EDITS:
+        raise BadRequest(f"edits must be a list of at most {MAX_EDITS}")
+    edits = []
+    for edit in value:
+        if not isinstance(edit, dict):
+            raise BadRequest("each edit must be an object { person, joint, to }")
+        person, joint, to = edit.get("person"), edit.get("joint"), edit.get("to")
+        if isinstance(person, bool) or not isinstance(person, int) or person < 0:
+            raise BadRequest("edit.person must be an index")
+        if isinstance(joint, bool) or not isinstance(joint, int) or joint not in MOVABLE:
+            raise BadRequest(f"edit.joint must be one of {sorted(MOVABLE)}")
+        if not isinstance(to, list) or len(to) != 3:
+            raise BadRequest("edit.to must be [x, y, z]")
+        point = [_number(v, "edit.to") for v in to]
+        if any(abs(v) > _MAX_REACH for v in point):
+            raise BadRequest(f"edit.to must be within {_MAX_REACH} picture widths")
+        edits.append(Edit(person, joint, (point[0] * width, point[1] * width, point[2] * width)))
+    return edits
+
+
 def handle(detector: Detector, body: dict[str, Any], default_style: Style = "dwpose") -> dict[str, Any]:
     """Answers one `/api/pose` request (the JSON above), without a web framework.
 
@@ -113,12 +157,13 @@ def handle(detector: Detector, body: dict[str, Any], default_style: Style = "dwp
     Raises:
         BadRequest: The request is wrong; answer 400 with its message.
         NoPersonError: Nobody in the picture; also a 400.
-        ValueError: A person index past the end; also a 400.
+        ValueError: A person index past the end, in `person` or an edit; also 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)
+    edits = parse_edits(body.get("edits"), image.width)
     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):
@@ -136,7 +181,7 @@ def handle(detector: Detector, body: dict[str, Any], default_style: Style = "dwp
     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)
+    result = pose(detector, image, (width, height), person, camera, style, depth=want_3d, framing=framing, edits=edits)
     people = []
     for found in result.people:
         x0, y0, x1, y1 = found.bbox
@@ -156,6 +201,7 @@ def handle(detector: Detector, body: dict[str, Any], default_style: Style = "dwp
         "height": height,
         "person": result.person,
         "person_subsets": True,
+        "movable": sorted(MOVABLE),
         "camera": {
             "yaw": result.camera.yaw,
             "pitch": result.camera.pitch,

poseorbit-0.3.0/poseorbit/body.py

@@ -0,0 +1,170 @@
+"""Moving a joint: the 133 COCO-WholeBody points as a tree, and bending it.
+
+A joint turns about its parent, and everything hanging from it turns with
+it: bending an elbow swings the forearm and the whole hand, and no bone
+changes length. The hips are the root and stay where they are; turning the
+whole figure is the camera's job.
+
+    from poseorbit import Edit, apply_edits
+
+    left_wrist = 9
+    moved = apply_edits([person.points_3d], [Edit(0, left_wrist, (420, 180, -40))])
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from dataclasses import dataclass
+
+import numpy as np
+
+_BODY = (
+    "nose", "left_eye", "right_eye", "left_ear", "right_ear",
+    "left_shoulder", "right_shoulder", "left_elbow", "right_elbow",
+    "left_wrist", "right_wrist", "left_hip", "right_hip",
+    "left_knee", "right_knee", "left_ankle", "right_ankle",
+)
+_FEET = ("left_big_toe", "left_small_toe", "left_heel", "right_big_toe", "right_small_toe", "right_heel")
+
+NAMES: tuple[str, ...] = (
+    _BODY
+    + _FEET
+    + tuple(f"face_{i}" for i in range(68))
+    + tuple(f"left_hand_{i}" for i in range(21))
+    + tuple(f"right_hand_{i}" for i in range(21))
+)
+"""The 133 keypoints' names, in COCO-WholeBody order."""
+
+NECK = -1
+"""`PARENT` of the nose: the middle of the shoulders, found when bending."""
+
+# Each point's parent: hips are roots, shoulders hang from the hips, the
+# head from the neck, hands from the wrists and the face from the nose.
+PARENT: tuple[int | None, ...] = (
+    (NECK, 0, 0, 1, 2, 11, 12, 5, 6, 7, 8, None, None, 11, 12, 13, 14)
+    + (15, 15, 15, 16, 16, 16)
+    + (0,) * 68
+    + (9,) * 21
+    + (10,) * 21
+)
+"""Each keypoint's parent index; None for the hips, `NECK` for the nose."""
+
+MOVABLE: frozenset[int] = frozenset({0, *range(5, 11), *range(13, 23)})
+"""The joints [bend][poseorbit.bend] moves: the head, arms, legs and feet."""
+
+_CHILDREN: dict[int, list[int]] = {}
+for _point, _parent in enumerate(PARENT):
+    if _parent is not None and _parent != NECK:
+        _CHILDREN.setdefault(_parent, []).append(_point)
+
+
+def subtree(joint: int) -> tuple[int, ...]:
+    """`joint` and every point hanging from it, in index order."""
+    found = [joint]
+    for point in found:
+        found.extend(_CHILDREN.get(point, ()))
+    return tuple(sorted(found))
+
+
+def pivot(points: np.ndarray, joint: int) -> np.ndarray:
+    """The point `joint` turns about: its parent, or the neck for the nose.
+
+    Raises:
+        ValueError: `joint` is a hip, which has no parent.
+    """
+    parent = PARENT[joint]
+    if parent is None:
+        raise ValueError(f"{NAMES[joint]} is a root and does not turn.")
+    if parent == NECK:
+        return (points[5] + points[6]) / 2
+    return points[parent]
+
+
+def _rotation(u: np.ndarray, v: np.ndarray) -> np.ndarray:
+    """The smallest rotation taking direction `u` onto `v` (both unit length)."""
+    axis = np.cross(u, v)
+    sine = float(np.linalg.norm(axis))
+    cosine = float(np.dot(u, v))
+    if sine < 1e-12:
+        if cosine > 0:
+            return np.eye(3)
+        # Straight back: half a turn about any axis square to u.
+        axis = np.cross(u, (1.0, 0.0, 0.0))
+        if np.linalg.norm(axis) < 1e-6:
+            axis = np.cross(u, (0.0, 1.0, 0.0))
+        axis = axis / np.linalg.norm(axis)
+        return 2 * np.outer(axis, axis) - np.eye(3)
+    axis = axis / sine
+    cross = np.array([[0, -axis[2], axis[1]], [axis[2], 0, -axis[0]], [-axis[1], axis[0], 0]])
+    return np.eye(3) + sine * cross + (1 - cosine) * (cross @ cross)
+
+
+def bend(points: np.ndarray, joint: int, target: Sequence[float] | np.ndarray) -> np.ndarray:
+    """Turn `joint` about its parent to point at `target`, carrying its subtree.
+
+    The joint keeps its distance from the parent, so it ends on the line from
+    the parent through `target`, not on `target` itself.
+
+    Args:
+        points: (133, 3) x, y and depth, as [Person.points_3d][poseorbit.Person].
+        joint: One of `MOVABLE`.
+        target: Where the joint should point, in the same units as `points`.
+
+    Returns:
+        A new (133, 3) array; `points` is left as it was.
+
+    Raises:
+        ValueError: `joint` is not movable.
+    """
+    if joint not in MOVABLE:
+        raise ValueError(f"Joint {joint} cannot be moved.")
+    points = np.array(points, dtype=float)
+    centre = pivot(points, joint)
+    u = points[joint] - centre
+    v = np.asarray(target, dtype=float) - centre
+    length, reach = float(np.linalg.norm(u)), float(np.linalg.norm(v))
+    if length < 1e-9 or reach < 1e-9:
+        return points
+    rotation = _rotation(u / length, v / reach)
+    moved = list(subtree(joint))
+    points[moved] = (points[moved] - centre) @ rotation.T + centre
+    return points
+
+
+@dataclass(frozen=True)
+class Edit:
+    """One joint moved on one person.
+
+    Attributes:
+        person: An index into the people detected, left to right.
+        joint: One of `MOVABLE`.
+        to: Where the joint should point: x, y and depth in the picture's pixels.
+    """
+
+    person: int
+    joint: int
+    to: tuple[float, float, float]
+
+
+def apply_edits(points: Sequence[np.ndarray], edits: Sequence[Edit]) -> list[np.ndarray]:
+    """Everyone's (133, 3) points with `edits` bent in, one after another.
+
+    Order matters: each edit bends the pose the ones before it left.
+
+    Args:
+        points: Each person's (133, 3) points, left to right.
+        edits: The joints to move.
+
+    Returns:
+        New arrays, one per person; `points` is left as it was.
+
+    Raises:
+        ValueError: An edit names a person past the end or a joint that is
+            not movable.
+    """
+    bent = [np.array(p, dtype=float) for p in points]
+    for edit in edits:
+        if not 0 <= edit.person < len(bent):
+            raise ValueError(f"No person {edit.person}: {len(bent)} found.")
+        bent[edit.person] = bend(bent[edit.person], edit.joint, edit.to)
+    return bent

{poseorbit-0.2.0 → poseorbit-0.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "poseorbit"
-version = "0.2.0"
+version = "0.3.0"
 description = "Find the people in a picture, turn their pose in 3D, and draw the skeleton a pose-conditioned image model follows."
 readme = "README.md"
 license = "Apache-2.0"

{poseorbit-0.2.0 → poseorbit-0.3.0}/tests/test_api.py

@@ -7,7 +7,7 @@ import numpy as np
 import pytest
 from PIL import Image
 
-from poseorbit import MAX_YAW, MAX_ZOOM, NoPersonError, Person
+from poseorbit import MAX_YAW, MAX_ZOOM, MOVABLE, NoPersonError, Person
 from poseorbit.api import BadRequest, handle
 
 
@@ -134,3 +134,41 @@ def test_some_people_are_drawn_together():
     # Turned, the chosen ones still turn together.
     turned = handle(StubDetector(people), {**body, "person": [0, 2], "camera": {"yaw": 30}})
     assert turned["person"] == [0, 2] and turned["camera"]["yaw"] == 30
+
+
+def test_an_edit_moves_the_drawn_skeleton_but_not_the_points():
+    body = {"image_base64": _picture(), "width": 400, "height": 600, "want_3d": True}
+    plain = handle(StubDetector([_person(200)]), body)
+    detector = StubDetector([_person(200)])
+    # The left wrist straight out to the side, front view: depth is still asked for.
+    edited = handle(detector, {**body, "want_3d": False, "edits": [{"person": 0, "joint": 9, "to": [0.9, 0.5, 0]}]})
+    assert detector.asked_depth is True
+    assert edited["skeleton_base64"] != plain["skeleton_base64"]
+    assert edited["movable"] == sorted(MOVABLE)
+    again = handle(StubDetector([_person(200)]), {**body, "edits": [{"person": 0, "joint": 9, "to": [0.9, 0.5, 0]}]})
+    assert again["people"][0]["points_3d"] == plain["people"][0]["points_3d"]
+
+
+@pytest.mark.parametrize(
+    "edits",
+    [
+        5,
+        [5],
+        [{"person": True, "joint": 9, "to": [0, 0, 0]}],
+        [{"person": -1, "joint": 9, "to": [0, 0, 0]}],
+        [{"person": 0, "joint": 11, "to": [0, 0, 0]}],
+        [{"person": 0, "joint": 133, "to": [0, 0, 0]}],
+        [{"person": 0, "joint": 9, "to": [0, 0]}],
+        [{"person": 0, "joint": 9, "to": [0, 0, float("nan")]}],
+        [{"person": 0, "joint": 9, "to": [0, 0, 17]}],
+        [{"person": 0, "joint": 9, "to": [0, 0, 0]}] * 257,
+    ],
+)
+def test_bad_edits_are_refused(edits):
+    with pytest.raises(BadRequest):
+        handle(StubDetector([_person(200)]), {"image_base64": _picture(), "edits": edits})
+
+
+def test_an_edit_for_a_person_past_the_end_is_refused():
+    with pytest.raises(ValueError):
+        handle(StubDetector([_person(200)]), {"image_base64": _picture(), "edits": [{"person": 1, "joint": 9, "to": [0, 0, 0]}]})

poseorbit-0.3.0/tests/test_body.py

@@ -0,0 +1,95 @@
+"""Bending joints: bones keep their length and what hangs from a joint goes with it."""
+
+import numpy as np
+import pytest
+
+from poseorbit import MOVABLE, NAMES, Edit, apply_edits, bend
+from poseorbit.body import PARENT, pivot, subtree
+
+
+def _figure() -> np.ndarray:
+    """A figure with every point somewhere different and some depth."""
+    rng = np.random.default_rng(7)
+    points = rng.uniform(-50, 50, (133, 3))
+    points[:17] = [
+        [0, -160, -5], [-8, -168, -3], [8, -168, -3], [-15, -164, 5], [15, -164, 5],
+        [-40, -120, 0], [40, -120, 0], [-70, -70, -10], [70, -70, 10],
+        [-90, -20, -20], [90, -20, 20], [-25, 0, 0], [25, 0, 0],
+        [-28, 80, 5], [28, 80, -5], [-30, 160, 0], [30, 160, 0],
+    ]
+    points[91:112] += points[9]
+    points[112:133] += points[10]
+    points[23:91] = points[0] + points[23:91] / 4
+    return points
+
+
+def _bones(points: np.ndarray) -> np.ndarray:
+    return np.array([
+        np.linalg.norm(points[i] - pivot(points, i)) for i, parent in enumerate(PARENT) if parent is not None
+    ])
+
+
+def _distances(points: np.ndarray) -> np.ndarray:
+    return np.linalg.norm(points[:, None] - points[None], axis=-1)
+
+
+def test_the_tree_names_every_point():
+    assert len(NAMES) == len(PARENT) == 133
+    assert NAMES[9] == "left_wrist" and NAMES[132] == "right_hand_20"
+    assert 11 not in MOVABLE and 12 not in MOVABLE
+    assert subtree(7) == (7, 9, *range(91, 112))
+    assert set(subtree(0)) == {0, 1, 2, 3, 4, *range(23, 91)}
+
+
+def test_bones_keep_their_length_and_the_joint_points_at_the_target():
+    points = _figure()
+    target = np.array([-150.0, -150.0, 40.0])
+    bent = bend(points, 7, target)
+    np.testing.assert_allclose(_bones(bent), _bones(points), atol=1e-9)
+    direction = (bent[7] - bent[5]) / np.linalg.norm(bent[7] - bent[5])
+    np.testing.assert_allclose(direction, (target - points[5]) / np.linalg.norm(target - points[5]), atol=1e-12)
+
+
+def test_the_hand_goes_with_the_wrist_and_the_face_with_the_head():
+    points = _figure()
+    hand = list(subtree(9))
+    bent = bend(points, 9, [-60, -150, 0])
+    np.testing.assert_allclose(_distances(bent[hand]), _distances(points[hand]), atol=1e-9)
+    head = list(subtree(0))
+    bent = bend(points, 0, [30, -150, -60])
+    np.testing.assert_allclose(_distances(bent[head]), _distances(points[head]), atol=1e-9)
+
+
+def test_only_the_subtree_moves():
+    points = _figure()
+    bent = bend(points, 13, [-80, 60, 30])
+    still = [i for i in range(133) if i not in subtree(13)]
+    np.testing.assert_array_equal(bent[still], points[still])
+    np.testing.assert_array_equal(points, _figure())  # the input is left alone
+
+
+def test_degenerate_targets_change_nothing_and_straight_back_turns_half_way():
+    points = _figure()
+    np.testing.assert_array_equal(bend(points, 7, points[5]), points)
+    flat = points.copy()
+    flat[7] = flat[5]
+    np.testing.assert_array_equal(bend(flat, 7, [0, 0, 0]), flat)
+    back = bend(points, 7, 2 * points[5] - points[7])
+    np.testing.assert_allclose(back[7], 2 * points[5] - points[7], atol=1e-9)
+    np.testing.assert_allclose(_bones(back), _bones(points), atol=1e-9)
+
+
+def test_edits_apply_in_order_and_the_same_edits_give_the_same_pose():
+    points = [_figure(), _figure() + [200, 0, 0]]
+    edits = [Edit(0, 7, (-150, -100, 0)), Edit(0, 5, (-60, -110, 30)), Edit(1, 16, (260, 150, 40))]
+    once = apply_edits(points, edits)
+    np.testing.assert_array_equal(once[0], apply_edits(points, edits)[0])
+    swapped = apply_edits(points, [edits[1], edits[0], edits[2]])
+    assert not np.allclose(once[0], swapped[0])
+    assert not np.allclose(once[1], points[1])
+
+
+@pytest.mark.parametrize("edit", [Edit(0, 11, (0, 0, 0)), Edit(0, 133, (0, 0, 0)), Edit(1, 9, (0, 0, 0))])
+def test_hips_unknown_joints_and_people_past_the_end_are_refused(edit):
+    with pytest.raises(ValueError):
+        apply_edits([_figure()], [edit])