poseorbit 0.1.2__tar.gz → 0.2.0__tar.gz

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

@@ -1,5 +1,18 @@
 # Changelog
 
+## 0.2.0 (2026-10-11)
+
+- **Choose some of the people**: `pose(..., person=[0, 2])` draws just those
+  (turned together around their shared centre), and `/api/pose` takes
+  `"person": [0, 2]` (up to 64 indices). The list comes back sorted and
+  without repeats; an empty list or an index past the end is refused.
+  `python -m poseorbit draw --person 0,2` does the same.
+- `/api/pose` answers `"person_subsets": true`, so a client knows it may
+  send a list.
+- **Changed:** `PoseResult.person` (and the answer's `person`) is a list when
+  a list was asked for; code that only passes an int or `ALL_PEOPLE` still
+  gets an int.
+
 ## 0.1.2 (2026-10-11)
 
 - **Pinned model downloads**: the three ONNX files come from a fixed commit

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: poseorbit
-Version: 0.1.2
+Version: 0.2.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/
@@ -122,9 +122,9 @@ Turning a pose in 3D for ControlNet is not new (see
   person boxes. Hands and face turn with the body instead of staying flat or
   being dropped, and the front view is pixel-identical to plain 2D detection.
 - **Choose a person in a group.** Everyone found comes back left to right
-  with a box, so index 1 is the same person on every call. Draw one of them
-  or all of them, turned together around a shared centre so the group keeps
-  its layout.
+  with a box, so index 1 is the same person on every call. Draw one of them,
+  any few of them (`person=[0, 2]`) or all of them, turned together around a
+  shared centre so the group keeps its layout.
 - **Drawn for the model that will read it.** `dwpose` is rtmlib's
   COCO-WholeBody drawing (thin lines, hands and face), the usual input of
   DWPose-trained adapters. `openpose` is the thick, body-only drawing
@@ -251,7 +251,7 @@ curl -s localhost:7870/api/pose -H 'Content-Type: application/json' -d '{
 ```
 
 ```json
-{ "skeleton_base64": "…png…", "width": 832, "height": 1216, "person": 0,
+{ "skeleton_base64": "…png…", "width": 832, "height": 1216, "person": 0, "person_subsets": true,
   "camera": { "yaw": 30, "pitch": 10, "framing": { "zoom": 2, "x": 0.5, "y": 0.35 } },
   "style": "openpose", "limits": { "yaw": 90, "pitch": 45, "zoom": [0.5, 6] },
   "joints_in_frame": 13,
@@ -260,8 +260,10 @@ curl -s localhost:7870/api/pose -H 'Content-Type: application/json' -d '{
 ```
 
 Everything but `image_base64` is optional. `person` is an index into
-`people` (left to right), `-1` for everyone, or absent for the most
-confident. `want_3d` adds each person's 133 points as `[x, y, z]` in units of
+`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
 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.

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

@@ -85,9 +85,9 @@ Turning a pose in 3D for ControlNet is not new (see
   person boxes. Hands and face turn with the body instead of staying flat or
   being dropped, and the front view is pixel-identical to plain 2D detection.
 - **Choose a person in a group.** Everyone found comes back left to right
-  with a box, so index 1 is the same person on every call. Draw one of them
-  or all of them, turned together around a shared centre so the group keeps
-  its layout.
+  with a box, so index 1 is the same person on every call. Draw one of them,
+  any few of them (`person=[0, 2]`) or all of them, turned together around a
+  shared centre so the group keeps its layout.
 - **Drawn for the model that will read it.** `dwpose` is rtmlib's
   COCO-WholeBody drawing (thin lines, hands and face), the usual input of
   DWPose-trained adapters. `openpose` is the thick, body-only drawing
@@ -214,7 +214,7 @@ curl -s localhost:7870/api/pose -H 'Content-Type: application/json' -d '{
 ```
 
 ```json
-{ "skeleton_base64": "…png…", "width": 832, "height": 1216, "person": 0,
+{ "skeleton_base64": "…png…", "width": 832, "height": 1216, "person": 0, "person_subsets": true,
   "camera": { "yaw": 30, "pitch": 10, "framing": { "zoom": 2, "x": 0.5, "y": 0.35 } },
   "style": "openpose", "limits": { "yaw": 90, "pitch": 45, "zoom": [0.5, 6] },
   "joints_in_frame": 13,
@@ -223,8 +223,10 @@ curl -s localhost:7870/api/pose -H 'Content-Type: application/json' -d '{
 ```
 
 Everything but `image_base64` is optional. `person` is an index into
-`people` (left to right), `-1` for everyone, or absent for the most
-confident. `want_3d` adds each person's 133 points as `[x, y, z]` in units of
+`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
 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.

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

@@ -11,6 +11,7 @@ pose in 3D, and draw the skeleton a pose-conditioned image model follows.
 
 from __future__ import annotations
 
+from collections.abc import Sequence
 from dataclasses import dataclass
 
 import numpy as np
@@ -20,7 +21,7 @@ from .detect import KEYPOINT_THRESHOLD, Detector, NoPersonError, Person, most_co
 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.2"
+__version__ = "0.2.0"
 
 # Person index meaning "everyone detected", for a group pose.
 ALL_PEOPLE = -1
@@ -53,7 +54,8 @@ class PoseResult:
     Attributes:
         skeleton: The skeleton on black, at the requested size.
         people: Everyone detected, left to right.
-        person: Who was drawn: an index into `people`, or `ALL_PEOPLE`.
+        person: Who was drawn: an index into `people`, `ALL_PEOPLE`, or the
+            sorted indices when several were chosen by a list.
         camera: The camera actually used, after clamping.
         framing: The framing actually used, after clamping.
         joints_in_frame: Body joints (of 17) seen and inside the canvas, for
@@ -62,9 +64,10 @@ class PoseResult:
     """
 
     skeleton: Image.Image
-    # Everyone detected, left to right, and which of them was drawn (ALL_PEOPLE for all).
+    # Everyone detected, left to right, and which of them was drawn: an index,
+    # ALL_PEOPLE for all, or the sorted indices of the ones chosen.
     people: list[Person]
-    person: int
+    person: int | list[int]
     # The camera and framing actually used, after clamping.
     camera: Camera
     framing: Framing
@@ -74,26 +77,38 @@ class PoseResult:
     joints_in_frame: int
 
 
-def chosen(people: list[Person], person: int | None) -> tuple[int, list[Person]]:
+def chosen(people: list[Person], person: int | Sequence[int] | None) -> tuple[int | list[int], list[Person]]:
     """`person` resolved (None = the most confident) and the people it means.
 
+    A sequence chooses any of them: the indices come back sorted, without
+    repeats, and the people in that (left-to-right) order.
+
     Raises:
-        ValueError: `person` is past the end of `people`.
+        ValueError: `person` (or one of a sequence) is past the end of
+            `people`, or the sequence is empty.
     """
     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.")
+    if isinstance(person, int):
+        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.")
+    indices = sorted(set(person))
+    if not indices:
+        raise ValueError("Choose at least one person.")
+    for index in indices:
+        if not 0 <= index < len(people):
+            raise ValueError(f"No person {index}: {len(people)} found.")
+    return indices, [people[index] for index in indices]
 
 
 def pose(
     detector: Detector,
     image: Image.Image,
     size: tuple[int, int],
-    person: int | None = None,
+    person: int | Sequence[int] | None = None,
     camera: Camera | None = None,
     style: Style = "dwpose",
     depth: bool = False,
@@ -110,7 +125,9 @@ def pose(
         size: The output's (width, height). The skeleton is drawn at it, the
             picture letterboxed onto it.
         person: An index into the left-to-right order, `ALL_PEOPLE` (-1) for
-            everyone, or None for the most confident.
+            everyone, a sequence of indices for some of them (drawn together
+            and turned around their shared centre), or None for the most
+            confident.
         camera: Where the camera stands; None for the front view.
         style: `"dwpose"` or `"openpose"`; see [render][poseorbit.render].
         depth: Detect depth even for the front view (to read
@@ -122,7 +139,8 @@ def pose(
 
     Raises:
         NoPersonError: Nobody in the picture is seen well enough.
-        ValueError: `person` is past the end of the people found.
+        ValueError: `person` (or one of a sequence) is past the end of the
+            people found, or the sequence is empty.
     """
     camera = (camera or Camera()).clamped()
     framing = (framing or Framing()).clamped()

{poseorbit-0.1.2 → poseorbit-0.2.0}/poseorbit/__main__.py

@@ -1,5 +1,5 @@
 """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]
+python -m poseorbit draw PICTURE OUT.png [--size 832x1216] [--person N|N,M,...] [--yaw D] [--pitch D]
                          [--zoom Z --centre X,Y] [--style S]"""
 
 from __future__ import annotations
@@ -8,6 +8,13 @@ import argparse
 from pathlib import Path
 
 
+def _person(text: str) -> int | list[int]:
+    """`--person`: one index (-1 for everyone), or several as "0,2"."""
+    if "," in text:
+        return [int(part) for part in text.split(",") if part.strip()]
+    return int(text)
+
+
 def main() -> None:
     """The `poseorbit` command (`python -m poseorbit`)."""
     parser = argparse.ArgumentParser(prog="poseorbit")
@@ -22,7 +29,7 @@ def main() -> None:
     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("--person", type=_person, default=None, help="index, several as 0,2, 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)

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

@@ -4,14 +4,15 @@ exactly the same JSON.
 
 Request:
     { "image_base64": "...", "width": 832, "height": 1216,
-      "person": 0,                          # optional; -1 = everyone, absent = most confident
+      "person": 0,                          # optional; -1 = everyone, [0, 2] = those, 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,
+    { "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
       "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] },
@@ -33,6 +34,10 @@ 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
 
+# 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
+
 
 class BadRequest(ValueError):
     """The request is wrong; answer 400 with the message."""
@@ -119,8 +124,12 @@ def handle(detector: Detector, body: dict[str, Any], default_style: Style = "dwp
     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")
+    if isinstance(person, list):
+        # Bounded before anything is detected; past the people found is a ValueError later.
+        if not 1 <= len(person) <= MAX_CHOSEN or any(isinstance(index, bool) or not isinstance(index, int) or index < 0 for index in person):
+            raise BadRequest(f"person as a list must hold 1-{MAX_CHOSEN} indices")
+    elif person is not None and (isinstance(person, bool) or not isinstance(person, int) or person < ALL_PEOPLE):
+        raise BadRequest("person must be an index, a list of indices, 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)}")
@@ -146,6 +155,7 @@ def handle(detector: Detector, body: dict[str, Any], default_style: Style = "dwp
         "width": width,
         "height": height,
         "person": result.person,
+        "person_subsets": True,
         "camera": {
             "yaw": result.camera.yaw,
             "pitch": result.camera.pitch,

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

@@ -1,6 +1,6 @@
 [project]
 name = "poseorbit"
-version = "0.1.2"
+version = "0.2.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.1.2 → poseorbit-0.2.0}/tests/test_api.py

@@ -44,6 +44,7 @@ def test_an_answer_has_everything_a_client_needs():
     answer = handle(StubDetector([_person(100), _person(300)]), {"image_base64": _picture(), "width": 832, "height": 1216})
     assert answer["width"] == 832 and answer["height"] == 1216
     assert answer["person"] in (0, 1)
+    assert answer["person_subsets"] is True
     assert answer["camera"] == {"yaw": 0.0, "pitch": 0.0, "framing": {"zoom": 1.0, "x": 0.5, "y": 0.5}}
     assert answer["limits"] == {"yaw": 90.0, "pitch": 45.0, "zoom": [0.5, 6.0]}
     assert answer["style"] == "dwpose"
@@ -93,6 +94,11 @@ def test_zooming_in_leaves_fewer_joints_in_frame():
         {"image_base64": "PIC", "width": 10},
         {"image_base64": "PIC", "person": -2},
         {"image_base64": "PIC", "person": True},
+        {"image_base64": "PIC", "person": []},
+        {"image_base64": "PIC", "person": [0, -1]},
+        {"image_base64": "PIC", "person": [0, True]},
+        {"image_base64": "PIC", "person": ["0"]},
+        {"image_base64": "PIC", "person": list(range(65))},
         {"image_base64": "PIC", "style": "sketch"},
         {"image_base64": "PIC", "camera": 5},
         {"image_base64": "PIC", "camera": {"yaw": "left"}},
@@ -111,3 +117,20 @@ def test_nobody_and_a_person_past_the_end_are_refused():
         handle(StubDetector([]), {"image_base64": _picture()})
     with pytest.raises(ValueError):
         handle(StubDetector([_person(200)]), {"image_base64": _picture(), "person": 3})
+    with pytest.raises(ValueError):
+        handle(StubDetector([_person(200)]), {"image_base64": _picture(), "person": [0, 3]})
+
+
+def test_some_people_are_drawn_together():
+    people = [_person(80), _person(200), _person(320)]
+    body = {"image_base64": _picture(), "width": 400, "height": 600}
+    some = handle(StubDetector(people), {**body, "person": [2, 0]})
+    assert some["person"] == [0, 2]
+    assert len(some["people"]) == 3
+    # Two figures draw differently from one, and from all three.
+    one = handle(StubDetector(people), {**body, "person": 0})
+    everyone = handle(StubDetector(people), {**body, "person": -1})
+    assert len({some["skeleton_base64"], one["skeleton_base64"], everyone["skeleton_base64"]}) == 3
+    # 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

{poseorbit-0.1.2 → poseorbit-0.2.0}/tests/test_geometry.py

@@ -82,6 +82,17 @@ def test_choosing_people():
         chosen(people, 2)
 
 
+def test_choosing_some_people_by_a_list():
+    people = [_person(10), _person(20), _person(30)]
+    # Sorted, without repeats, in left-to-right order.
+    assert chosen(people, [2, 0, 2]) == ([0, 2], [people[0], people[2]])
+    assert chosen(people, (1,)) == ([1], [people[1]])
+    with pytest.raises(ValueError):
+        chosen(people, [])
+    with pytest.raises(ValueError):
+        chosen(people, [0, 3])
+
+
 def test_whole_framing_changes_nothing():
     points = np.array([[10.0, 20.0], [300.0, 400.0]])
     assert np.allclose(frame(points, (832, 1216), Framing()), points)