poseorbit 0.1.1__tar.gz

poseorbit-0.1.1/.gitattributes

@@ -0,0 +1,3 @@
+* text=auto eol=lf
+*.png binary
+*.jpg binary

poseorbit-0.1.1/.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+*.egg-info/
+.pytest_cache/
+.venv/
+dist/
+build/
+weights/

poseorbit-0.1.1/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+## 0.1.1 (2026-10-06)
+
+- Published on PyPI: `pip install poseorbit`. Releases are uploaded from
+  GitHub Actions with Trusted Publishing and signed attestations.
+- The README's pictures and links are absolute, so they show on PyPI too.
+
+## 0.1.0 (2026-10-05)
+
+First release.
+
+- Find people with YOLOX and DWPose (133 whole-body keypoints), left to
+  right; choose one, or everyone.
+- Depth for every keypoint from RTMW3D-x on the same boxes; turn the pose
+  with an orthographic camera (yaw ±90°, pitch ±45°).
+- Frame the output canvas: zoom ×0.5 to ×6 around any point.
+- Draw `dwpose` (rtmlib's COCO-WholeBody) or `openpose` (thick, body-only, as
+  xinsir's SDXL ControlNet was trained) skeletons, letterboxed onto the
+  output's size.
+- Library, `python -m poseorbit draw`, and `python -m poseorbit serve`
+  (`POST /api/pose`, optional Bearer token).

poseorbit-0.1.1/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

poseorbit-0.1.1/NOTICE

@@ -0,0 +1,28 @@
+poseorbit
+Copyright 2026 33rd-kk
+
+This product is licensed under the Apache License, Version 2.0 (see LICENSE).
+
+It includes or is derived from the following third-party work:
+
+- rtmlib (https://github.com/Tau-J/rtmlib), Apache License 2.0.
+  poseorbit calls rtmlib to run the detectors and to draw "dwpose" skeletons,
+  and uses its COCO-to-OpenPose keypoint conversion.
+
+- The "openpose" drawing in poseorbit/draw.py (_draw_openpose_body) follows
+  the draw_bodypose function published on the model card of
+  xinsir/controlnet-openpose-sdxl-1.0
+  (https://huggingface.co/xinsir/controlnet-openpose-sdxl-1.0), Apache License
+  2.0, itself a modification of controlnet_aux's OpenPose drawing
+  (https://github.com/huggingface/controlnet_aux), Apache License 2.0.
+  The 18-point limb order and colours are OpenPose's conventions as used there.
+
+Model files (downloaded at run time, not distributed with poseorbit):
+
+- YOLOX-m (HumanArt) person detector and RTMW-DW-x-l whole-body pose model,
+  OpenMMLab (https://github.com/open-mmlab/mmpose), Apache License 2.0,
+  fetched from rtmlib's mirror https://huggingface.co/Tau-J/RTMPose.
+- RTMW3D-x, OpenMMLab, Apache License 2.0, fetched from
+  https://huggingface.co/Soykaf/RTMW3D-x.
+  Paper: Jiang et al., "RTMW: Real-Time Multi-Person 2D and 3D Whole-body
+  Pose Estimation", arXiv:2407.08634.

poseorbit-0.1.1/PKG-INFO

@@ -0,0 +1,351 @@
+Metadata-Version: 2.5
+Name: poseorbit
+Version: 0.1.1
+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: Issues, https://github.com/33rd-kk/poseorbit/issues
+Project-URL: Changelog, https://github.com/33rd-kk/poseorbit/blob/main/CHANGELOG.md
+Author: 33rd-kk
+License-Expression: Apache-2.0
+License-File: LICENSE
+License-File: NOTICE
+Keywords: 3d,controlnet,dwpose,openpose,pose,rtmlib,skeleton,stable-diffusion
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Multimedia :: Graphics
+Classifier: Topic :: Scientific/Engineering :: Image Recognition
+Requires-Python: >=3.10
+Requires-Dist: huggingface-hub>=0.30
+Requires-Dist: numpy>=1.26
+Requires-Dist: onnxruntime>=1.18
+Requires-Dist: pillow>=10
+Requires-Dist: rtmlib>=0.0.16
+Provides-Extra: server
+Requires-Dist: fastapi>=0.115; extra == 'server'
+Requires-Dist: uvicorn>=0.30; extra == 'server'
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == 'test'
+Description-Content-Type: text/markdown
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/33rd-kk/poseorbit/main/docs/assets/banner-dark.png">
+  <img alt="poseorbit: a picture, the skeleton turned 30 degrees and the picture generated from it, then a zoomed skeleton and the close-up generated from it" src="https://raw.githubusercontent.com/33rd-kk/poseorbit/main/docs/assets/banner-light.png">
+</picture>
+
+# poseorbit
+
+[![PyPI](https://img.shields.io/pypi/v/poseorbit.svg)](https://pypi.org/project/poseorbit/)
+[![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](https://github.com/33rd-kk/poseorbit/blob/main/LICENSE)
+![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)
+![CPU only](https://img.shields.io/badge/runs%20on-CPU-555.svg)
+[![Tests](https://github.com/33rd-kk/poseorbit/actions/workflows/test.yml/badge.svg)](https://github.com/33rd-kk/poseorbit/actions/workflows/test.yml)
+
+**Take the pose from a picture, pick whose, look at it from another angle or
+closer in, and get the skeleton your image model follows.**
+
+poseorbit finds every person in a picture, lets you choose one (or everyone),
+turns the whole-body pose (hands and face included) in 3D, frames it (from a
+face close-up to room around the figure), and draws the skeleton in the style
+a pose-conditioned model was trained on. It is a small Python package: CPU
+only, no torch, usable as a library, a command, or an HTTP server.
+
+```python
+from PIL import Image
+from poseorbit import Camera, Detector, Framing, pose
+
+result = pose(Detector(), Image.open("group.png"), size=(832, 1216),
+              person=1, camera=Camera(yaw=40, pitch=10),
+              framing=Framing(zoom=2, x=0.5, y=0.35), style="openpose")
+result.skeleton.save("skeleton.png")   # feed this to your ControlNet or pose adapter
+```
+
+## Examples
+
+One reference, two skeletons, two pictures generated from them:
+
+| Reference | Turned: `Camera(yaw=-30)` | Generated | Close-up: `Framing(zoom=5)` on the face | Generated |
+|---|---|---|---|---|
+| <img src="https://raw.githubusercontent.com/33rd-kk/poseorbit/main/docs/assets/examples/reference.jpg" width="150" alt="reference picture: a girl in a grey hoodie waving, legs crossed"> | <img src="https://raw.githubusercontent.com/33rd-kk/poseorbit/main/docs/assets/examples/turn-skeleton.png" width="150" alt="the reference's skeleton turned 30 degrees"> | <img src="https://raw.githubusercontent.com/33rd-kk/poseorbit/main/docs/assets/examples/turn-result.jpg" width="150" alt="picture generated from the turned skeleton"> | <img src="https://raw.githubusercontent.com/33rd-kk/poseorbit/main/docs/assets/examples/closeup-skeleton.png" width="150" alt="the reference's skeleton zoomed five times on the face"> | <img src="https://raw.githubusercontent.com/33rd-kk/poseorbit/main/docs/assets/examples/closeup-result.jpg" width="150" alt="close-up generated from the zoomed skeleton"> |
+
+All pictures were generated for this README. The reference: Illustrious XL
+2.0, "1girl, solo, full body, standing, waving, one hand raised, head tilt,
+grey hoodie, black pants, white sneakers, simple background", seed 13. The
+other two: Anima Base 1.0 with Anima-Control-Pose (`dwpose` style), 832×1216,
+30 steps, CFG 5, "1girl, solo, short black hair, blue oversized hoodie, loose
+jeans, sneakers, front view, looking at viewer, smile, simple background"
+plus "full body" or "portrait, face focus, close-up", seed 43 each (picked
+from four and three). The skeleton sets the figure, the prompt everything
+else. Note that Anima and Anima-Control-Pose are under CircleStone Labs'
+non-commercial licence (pictures made with them are not restricted);
+poseorbit itself does not use or include them.
+
+## How it works
+
+```mermaid
+flowchart LR
+  A[picture] --> B["find people<br/>YOLOX"]
+  B --> C["133 keypoints<br/>DWPose"]
+  B --> D["depth<br/>RTMW3D"]
+  C --> E[choose a person<br/>or everyone]
+  D --> E
+  E --> F["turn<br/>yaw / pitch"]
+  F --> G["fit onto the<br/>output canvas"]
+  G --> H["frame<br/>zoom / centre"]
+  H --> I["draw<br/>dwpose / openpose"]
+```
+
+One person detector feeds two keypoint models on the same boxes: DWPose gives
+x and y, RTMW3D (only when a turn is asked for) gives depth. The camera is
+orthographic and orbits the middle of the drawn people's hips. The turned
+pose is letterboxed onto the output's canvas, framed like a cropped photo,
+and drawn on black.
+
+## What sets it apart
+
+Turning a pose in 3D for ControlNet is not new (see
+[related projects](#related-projects)). poseorbit's choices are different:
+
+- **Depth for all 133 whole-body points, from one picture.** x and y come
+  from DWPose (RTMW-DW-x-l) and depth from RTMW3D-x, run on the *same*
+  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.
+- **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
+  xinsir's OpenPose ControlNet for SDXL was trained on, line width growing
+  with the canvas as its model card specifies.
+- **Framing, not just turning.** Zoom from ×0.5 to ×6 around any point of
+  the output canvas: a face or upper-body close-up from a full-body
+  reference, or a smaller figure with room around it. The answer says how
+  many body joints are left in the frame, so a client can warn when a
+  body-only skeleton has little to follow.
+- **What you preview is what is followed.** The whole mapping (turn,
+  letterbox, framing) is specified [below](#coordinates), so a browser
+  viewer can show exactly what will be drawn. Latentry's three.js view is
+  tested against it to within 0.05 px.
+- **No framework attached.** No ComfyUI or web UI required, no torch, no
+  GPU: a library, `python -m poseorbit draw`, or `python -m poseorbit serve`
+  answering `POST /api/pose`. A generation server can embed the same handler
+  (`poseorbit.api.handle`) so both speak one API.
+- **Guard rails from measurement.** Turning is held to ±90° yaw and ±45°
+  pitch, where single-picture depth is still mostly right. Detections with
+  fewer than 8 of 17 body joints seen are not offered as people (a blank
+  canvas otherwise "finds" one).
+
+## Measured
+
+Generated with and without the skeleton, same seed, 832×1216. The score is
+PCK@0.1 of the re-detected output against the skeleton: 1.0 means every
+point landed within 10% of the diagonal of where the skeleton put it.
+
+| Model | Pose | Without | With |
+|---|---|---|---|
+| Illustrious XL 2.0 + xinsir OpenPose ControlNet (`openpose`) | walking, front | 0.76 | **0.94** |
+| same | standing, front | 0.47 | **0.76** |
+| same | walking, turned yaw 45° / yaw −60° pitch 15° | — | **0.94 / 0.88** |
+| Anima Base 1.0 + Anima-Control-Pose (`dwpose`) | walking, front | 0.06 | **0.71** |
+| same | walking, turned yaw 45° | — | **0.94** |
+
+Framed, scored on the body and face points left in the frame (the prompt
+says "upper body" or "portrait, close-up" in both runs):
+
+| Model | Framing | Without | With |
+|---|---|---|---|
+| Illustrious XL 2.0 + xinsir ControlNet | upper body, ×2 | 0.02 | **1.00** |
+| same | face, ×5 (7 body joints left) | 0.48 | **0.99** |
+| Anima Base 1.0 + Anima-Control-Pose | upper body ×2 / face ×5 | 0.93 / 0.97 | 0.93 / 0.99 |
+
+Anima already centres a close-up by itself, so its score barely moves; with
+the skeleton the head's tilt and turn follow the reference. Detection takes
+about 0.7 s for one person on a desktop CPU, all three models together.
+
+## Install
+
+Python 3.10 or newer.
+
+```sh
+pip install poseorbit
+pip install "poseorbit[server]"     # with the HTTP server
+```
+
+The latest `main`, before it is released:
+`pip install "poseorbit @ git+https://github.com/33rd-kk/poseorbit"`.
+
+The model files (about 700 MB, all Apache-2.0) download from Hugging Face on
+first use into `~/.cache/poseorbit`, or the `weights_dir` you give `Detector`.
+
+## Use
+
+### From Python
+
+```python
+from pathlib import Path
+from PIL import Image
+from poseorbit import ALL_PEOPLE, Camera, Detector, Framing, pose
+
+detector = Detector(weights_dir=Path("weights"))   # load once, reuse; thread-safe
+picture = Image.open("reference.png")
+
+people = detector.detect(picture)                  # everyone, left to right
+print([p.bbox for p in people])                    # boxes in the picture's pixels
+
+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
+```
+
+### With diffusers
+
+```python
+import torch
+from diffusers import ControlNetModel, StableDiffusionXLControlNetPipeline
+
+controlnet = ControlNetModel.from_pretrained("xinsir/controlnet-openpose-sdxl-1.0", torch_dtype=torch.float16)
+pipe = StableDiffusionXLControlNetPipeline.from_pretrained(
+    "stabilityai/stable-diffusion-xl-base-1.0", controlnet=controlnet, torch_dtype=torch.float16
+).to("cuda")
+
+skeleton = pose(detector, picture, size=(832, 1216), camera=Camera(yaw=45), style="openpose").skeleton
+image = pipe("1girl, full body", image=skeleton, width=832, height=1216).images[0]
+```
+
+### From the command line
+
+```sh
+python -m poseorbit draw ref.png skeleton.png --size 832x1216 --person -1 --yaw 40 --style openpose
+python -m poseorbit draw ref.png face.png --size 832x1216 --zoom 5 --centre 0.62,0.2
+```
+
+### Over HTTP
+
+```sh
+python -m poseorbit serve --port 7870      # set POSEORBIT_TOKEN to require a Bearer token
+```
+
+```sh
+curl -s localhost:7870/api/pose -H 'Content-Type: application/json' -d '{
+  "image_base64": "<base64 PNG or JPEG>", "width": 832, "height": 1216,
+  "person": 0, "want_3d": true,
+  "camera": { "yaw": 30, "pitch": 10, "framing": { "zoom": 2, "x": 0.5, "y": 0.35 } },
+  "style": "openpose" }'
+```
+
+```json
+{ "skeleton_base64": "…png…", "width": 832, "height": 1216, "person": 0,
+  "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,
+  "people": [ { "bbox": [0.31, 0.2, 0.8, 1.0],
+                "points_3d": [[0.61, 0.24, -0.03], "…"], "scores": [0.92, "…"] } ] }
+```
+
+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
+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.
+
+## Reference
+
+| 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. |
+| `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`. |
+| `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. |
+
+### Skeleton styles
+
+| Style | Drawing | For |
+|---|---|---|
+| `dwpose` | rtmlib's COCO-WholeBody: thin coloured lines, body, feet, hands and face | DWPose-trained adapters, such as Anima-Control-Pose |
+| `openpose` | 18 OpenPose body points, thick translucent limbs scaled with the canvas | OpenPose ControlNets, such as xinsir/controlnet-openpose-sdxl-1.0 |
+
+## Coordinates
+
+x right, y down, depth away from the viewer, all in the picture's pixels
+(the API scales them by the picture's width). The camera at (`yaw`, `pitch`)
+stands at `(sin yaw · cos pitch, −sin pitch, −cos yaw · cos pitch)` from the
+centre (the middle of the drawn people's hips). In a y-up, z-toward-viewer
+frame such as three.js that is `(sin yaw · cos pitch, sin pitch, cos yaw ·
+cos pitch)`.
+
+The turned picture is letterboxed onto the output canvas, then framed:
+canvas point `(x, y)` (fractions) goes to the middle and everything scales
+by `zoom` around it. Framing never moves the point the camera orbits.
+
+## Limits
+
+- Depth is estimated from a single picture: past a side view, which limb is
+  in front gets unreliable. That is why the camera is limited.
+- Chosen from a group, a person is drawn where they stand in the picture,
+  letterboxed onto the output. A small figure gives a small skeleton, which
+  models follow loosely; zoom in on them.
+- Some models do not tell front from back by the skeleton alone. Anima, for
+  one, often draws a strongly turned figure from behind. What helps: turn
+  away from the side the figure already shows (look at `Person.depth`: the
+  nearer shoulder is the smaller value), keep the turn moderate, and put
+  "front view" in the prompt and "from behind" in the negative.
+- Animals and non-human figures are not detected.
+
+## Related projects
+
+Other ways to get a turned or posed skeleton, each with its own strengths:
+
+- [3D Openpose Editor](https://github.com/ZhUyU1997/open-pose-editor): a
+  browser 3D mannequin editor for Stable Diffusion web UI, with hand editing
+  and depth, normal and canny maps.
+- [ComfyUI-Magos-Nodes](https://github.com/MagosDigitalStudio/ComfyUI-Magos-Nodes):
+  a DWPose skeleton editor for ComfyUI with NLF-based 3D, an orbit view and
+  animated cameras for video.
+- [ComfyUI-Fisher-Pose](https://github.com/Work-Fisher/ComfyUI-Fisher-Pose):
+  a posable MakeHuman mannequin and camera moves for Qwen-Image editing.
+- [RTMW / RTMW3D](https://arxiv.org/abs/2407.08634) and
+  [rtmlib](https://github.com/Tau-J/rtmlib): the models and the runtime
+  poseorbit is built on.
+
+## Used by
+
+Latentry, a local web UI for diffusion backends, uses poseorbit for its pose
+slot and its 3D pose view.
+
+## Development
+
+```sh
+pip install -e ".[test,server]"
+pytest                             # geometry and API checks; no model download
+python scripts/make_banner.py      # redraws docs/assets/banner-*.png
+```
+
+## Security
+
+Report vulnerabilities privately through
+[GitHub's reporting](https://github.com/33rd-kk/poseorbit/security/advisories/new);
+see [SECURITY.md](https://github.com/33rd-kk/poseorbit/blob/main/SECURITY.md).
+
+## License
+
+Apache-2.0. See [LICENSE](https://github.com/33rd-kk/poseorbit/blob/main/LICENSE), and [NOTICE](https://github.com/33rd-kk/poseorbit/blob/main/NOTICE) for the third-party
+work poseorbit builds on (rtmlib; the OpenPose drawing from xinsir's model
+card and controlnet_aux). The model files (OpenMMLab's YOLOX, RTMW and
+RTMW3D, Apache-2.0) are downloaded, not shipped. Models you condition with
+the skeletons keep their own licences. The example pictures in
+`docs/assets` were generated by the author for this README.