argus-puppet 0.2.0__tar.gz → 0.3.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (80) hide show
  1. {argus_puppet-0.2.0 → argus_puppet-0.3.0}/CLAUDE.md +2 -0
  2. {argus_puppet-0.2.0 → argus_puppet-0.3.0}/PKG-INFO +6 -3
  3. {argus_puppet-0.2.0 → argus_puppet-0.3.0}/README.md +5 -2
  4. {argus_puppet-0.2.0 → argus_puppet-0.3.0}/docs/conditioning.md +2 -1
  5. {argus_puppet-0.2.0 → argus_puppet-0.3.0}/docs/deploy.md +1 -1
  6. {argus_puppet-0.2.0 → argus_puppet-0.3.0}/docs/metrics.md +45 -3
  7. {argus_puppet-0.2.0 → argus_puppet-0.3.0}/docs/pose-vector.md +8 -5
  8. {argus_puppet-0.2.0 → argus_puppet-0.3.0}/docs/server.md +20 -7
  9. {argus_puppet-0.2.0 → argus_puppet-0.3.0}/schema/puppet-wire.schema.json +105 -6
  10. {argus_puppet-0.2.0 → argus_puppet-0.3.0}/src/argus_puppet/_version.py +2 -2
  11. {argus_puppet-0.2.0 → argus_puppet-0.3.0}/src/argus_puppet/cli.py +19 -0
  12. {argus_puppet-0.2.0 → argus_puppet-0.3.0}/src/argus_puppet/compare.py +4 -2
  13. {argus_puppet-0.2.0 → argus_puppet-0.3.0}/src/argus_puppet/embedding.py +72 -20
  14. {argus_puppet-0.2.0 → argus_puppet-0.3.0}/src/argus_puppet/library.py +14 -6
  15. {argus_puppet-0.2.0 → argus_puppet-0.3.0}/src/argus_puppet/metrics.py +25 -3
  16. {argus_puppet-0.2.0 → argus_puppet-0.3.0}/src/argus_puppet/models.py +62 -1
  17. {argus_puppet-0.2.0 → argus_puppet-0.3.0}/tests/test_cli.py +33 -0
  18. {argus_puppet-0.2.0 → argus_puppet-0.3.0}/tests/test_compare.py +20 -0
  19. {argus_puppet-0.2.0 → argus_puppet-0.3.0}/tests/test_embedding.py +53 -0
  20. {argus_puppet-0.2.0 → argus_puppet-0.3.0}/tests/test_library.py +1 -0
  21. {argus_puppet-0.2.0 → argus_puppet-0.3.0}/tests/test_metrics.py +91 -1
  22. {argus_puppet-0.2.0 → argus_puppet-0.3.0}/tests/test_models.py +14 -1
  23. argus_puppet-0.3.0/tests/test_real_model.py +128 -0
  24. argus_puppet-0.2.0/tests/test_real_model.py +0 -63
  25. {argus_puppet-0.2.0 → argus_puppet-0.3.0}/.copier-answers.yml +0 -0
  26. {argus_puppet-0.2.0 → argus_puppet-0.3.0}/.dockerignore +0 -0
  27. {argus_puppet-0.2.0 → argus_puppet-0.3.0}/.github/workflows/ci.yml +0 -0
  28. {argus_puppet-0.2.0 → argus_puppet-0.3.0}/.github/workflows/docs.yml +0 -0
  29. {argus_puppet-0.2.0 → argus_puppet-0.3.0}/.github/workflows/release.yml +0 -0
  30. {argus_puppet-0.2.0 → argus_puppet-0.3.0}/.github/workflows/suite.yml +0 -0
  31. {argus_puppet-0.2.0 → argus_puppet-0.3.0}/.gitignore +0 -0
  32. {argus_puppet-0.2.0 → argus_puppet-0.3.0}/.suite-rules-baseline.json +0 -0
  33. {argus_puppet-0.2.0 → argus_puppet-0.3.0}/Dockerfile +0 -0
  34. {argus_puppet-0.2.0 → argus_puppet-0.3.0}/LICENSE +0 -0
  35. {argus_puppet-0.2.0 → argus_puppet-0.3.0}/Makefile +0 -0
  36. {argus_puppet-0.2.0 → argus_puppet-0.3.0}/compose.yaml +0 -0
  37. {argus_puppet-0.2.0 → argus_puppet-0.3.0}/docs/cli.md +0 -0
  38. {argus_puppet-0.2.0 → argus_puppet-0.3.0}/docs/index.md +0 -0
  39. {argus_puppet-0.2.0 → argus_puppet-0.3.0}/docs/models.md +0 -0
  40. {argus_puppet-0.2.0 → argus_puppet-0.3.0}/gpu-tenant.yaml +0 -0
  41. {argus_puppet-0.2.0 → argus_puppet-0.3.0}/pyproject.toml +0 -0
  42. {argus_puppet-0.2.0 → argus_puppet-0.3.0}/src/argus_puppet/__init__.py +0 -0
  43. {argus_puppet-0.2.0 → argus_puppet-0.3.0}/src/argus_puppet/age.py +0 -0
  44. {argus_puppet-0.2.0 → argus_puppet-0.3.0}/src/argus_puppet/config.py +0 -0
  45. {argus_puppet-0.2.0 → argus_puppet-0.3.0}/src/argus_puppet/estimator.py +0 -0
  46. {argus_puppet-0.2.0 → argus_puppet-0.3.0}/src/argus_puppet/extract.py +0 -0
  47. {argus_puppet-0.2.0 → argus_puppet-0.3.0}/src/argus_puppet/gpu.py +0 -0
  48. {argus_puppet-0.2.0 → argus_puppet-0.3.0}/src/argus_puppet/labels.py +0 -0
  49. {argus_puppet-0.2.0 → argus_puppet-0.3.0}/src/argus_puppet/primary.py +0 -0
  50. {argus_puppet-0.2.0 → argus_puppet-0.3.0}/src/argus_puppet/py.typed +0 -0
  51. {argus_puppet-0.2.0 → argus_puppet-0.3.0}/src/argus_puppet/registry.py +0 -0
  52. {argus_puppet-0.2.0 → argus_puppet-0.3.0}/src/argus_puppet/render.py +0 -0
  53. {argus_puppet-0.2.0 → argus_puppet-0.3.0}/src/argus_puppet/runtime.py +0 -0
  54. {argus_puppet-0.2.0 → argus_puppet-0.3.0}/src/argus_puppet/sampling.py +0 -0
  55. {argus_puppet-0.2.0 → argus_puppet-0.3.0}/src/argus_puppet/server/__init__.py +0 -0
  56. {argus_puppet-0.2.0 → argus_puppet-0.3.0}/src/argus_puppet/server/app.py +0 -0
  57. {argus_puppet-0.2.0 → argus_puppet-0.3.0}/src/argus_puppet/sidecars.py +0 -0
  58. {argus_puppet-0.2.0 → argus_puppet-0.3.0}/src/argus_puppet/skeleton.py +0 -0
  59. {argus_puppet-0.2.0 → argus_puppet-0.3.0}/src/argus_puppet/weights.py +0 -0
  60. {argus_puppet-0.2.0 → argus_puppet-0.3.0}/tests/conftest.py +0 -0
  61. {argus_puppet-0.2.0 → argus_puppet-0.3.0}/tests/posegen.py +0 -0
  62. {argus_puppet-0.2.0 → argus_puppet-0.3.0}/tests/synthetic_poses.py +0 -0
  63. {argus_puppet-0.2.0 → argus_puppet-0.3.0}/tests/test_age.py +0 -0
  64. {argus_puppet-0.2.0 → argus_puppet-0.3.0}/tests/test_config.py +0 -0
  65. {argus_puppet-0.2.0 → argus_puppet-0.3.0}/tests/test_estimator.py +0 -0
  66. {argus_puppet-0.2.0 → argus_puppet-0.3.0}/tests/test_extract.py +0 -0
  67. {argus_puppet-0.2.0 → argus_puppet-0.3.0}/tests/test_gpu.py +0 -0
  68. {argus_puppet-0.2.0 → argus_puppet-0.3.0}/tests/test_gpu_tenant.py +0 -0
  69. {argus_puppet-0.2.0 → argus_puppet-0.3.0}/tests/test_labels.py +0 -0
  70. {argus_puppet-0.2.0 → argus_puppet-0.3.0}/tests/test_must_never.py +0 -0
  71. {argus_puppet-0.2.0 → argus_puppet-0.3.0}/tests/test_primary.py +0 -0
  72. {argus_puppet-0.2.0 → argus_puppet-0.3.0}/tests/test_registry.py +0 -0
  73. {argus_puppet-0.2.0 → argus_puppet-0.3.0}/tests/test_render.py +0 -0
  74. {argus_puppet-0.2.0 → argus_puppet-0.3.0}/tests/test_runtime.py +0 -0
  75. {argus_puppet-0.2.0 → argus_puppet-0.3.0}/tests/test_sampling.py +0 -0
  76. {argus_puppet-0.2.0 → argus_puppet-0.3.0}/tests/test_server.py +0 -0
  77. {argus_puppet-0.2.0 → argus_puppet-0.3.0}/tests/test_server_sets.py +0 -0
  78. {argus_puppet-0.2.0 → argus_puppet-0.3.0}/tests/test_skeleton.py +0 -0
  79. {argus_puppet-0.2.0 → argus_puppet-0.3.0}/tests/test_smoke.py +0 -0
  80. {argus_puppet-0.2.0 → argus_puppet-0.3.0}/tests/test_weights.py +0 -0
@@ -85,6 +85,8 @@ it **UNENFORCED** until something checks it. When a rule bites, add a check rath
85
85
  `image_for_sidecar` (the image a sidecar sits beside).
86
86
  - `embedding.py` — the pose vector (body-17, hip-centred, robust torso scale, masked joints) and the mirror-invariant
87
87
  distance (`pose_distance`, chunked `pairwise_distances`/`cross_distances`). Pure numpy. See `docs/pose-vector.md`.
88
+ `embed_or_reason`/`torso_frame_or_reason` are the single source of `UnusableReason` (the wire's
89
+ `unusable_reason`); `embed`/`torso_frame` wrap them. Never re-derive a reason elsewhere.
88
90
  - `labels.py` — `pose_labels(kp)`: stance / arms / facing from geometry rules (named threshold constants). The one
89
91
  source of labels: metrics, compare and library always recompute from keypoints and never read a stored
90
92
  `PersonPose.labels` (`tests/test_metrics.py::test_stored_person_labels_never_change_stats_compare_or_library`).
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: argus-puppet
3
- Version: 0.2.0
3
+ Version: 0.3.0
4
4
  Summary: Body pose for the Argus suite: whole-body keypoints, pose embeddings, diversity and coverage metrics, and ControlNet pose conditioning (:8220)
5
5
  Project-URL: Repository, https://github.com/smk762/argus-puppet
6
6
  Author: smk762
@@ -121,7 +121,10 @@ argus-puppet library sample poses.library.json -n 8 --render-dir batch --size 10
121
121
 
122
122
  Re-running `pose` skips images that already have a sidecar, so it is cheap to repeat. A set with fewer than two
123
123
  usable poses scores diversity 0; measure sets of tens of images or more, and read `usable` and `comparable_share`
124
- before trusting the score (see [docs/metrics.md](docs/metrics.md#suggested-gate-for-proof)). In `compare`, a close
124
+ before trusting the score (see [docs/metrics.md](docs/metrics.md#suggested-gate-for-proof)). Each unusable image
125
+ says why (`items[].unusable_reason`, counted in `unusable_reasons`, e.g. `{"no_confident_shoulder": 3}`): a crop
126
+ without the shoulders or hips in frame is correctly unusable, so smoke-test with full-body or at least torso-in-frame
127
+ photos ([docs/metrics.md](docs/metrics.md#what-makes-a-pose-unusable)). In `compare`, a close
125
128
  pose match means "the same pose", not "a copied frame": most same-stance poses have a near twin in a large training
126
129
  set. Read the per-output match as a pointer for an image-level check, and `close_share` against the training set's
127
130
  own `baseline_close_share` (`close_excess`) as the run-level signal
@@ -165,7 +168,7 @@ it apart from other packages' `<stem>.json` sidecars). It is a `PoseResult`, the
165
168
 
166
169
  ```jsonc
167
170
  {
168
- "puppet_version": "1.1",
171
+ "puppet_version": "1.2",
169
172
  "image": "woman_yoga.jpg",
170
173
  "image_sha256": "…",
171
174
  "width": 480, "height": 720,
@@ -69,7 +69,10 @@ argus-puppet library sample poses.library.json -n 8 --render-dir batch --size 10
69
69
 
70
70
  Re-running `pose` skips images that already have a sidecar, so it is cheap to repeat. A set with fewer than two
71
71
  usable poses scores diversity 0; measure sets of tens of images or more, and read `usable` and `comparable_share`
72
- before trusting the score (see [docs/metrics.md](docs/metrics.md#suggested-gate-for-proof)). In `compare`, a close
72
+ before trusting the score (see [docs/metrics.md](docs/metrics.md#suggested-gate-for-proof)). Each unusable image
73
+ says why (`items[].unusable_reason`, counted in `unusable_reasons`, e.g. `{"no_confident_shoulder": 3}`): a crop
74
+ without the shoulders or hips in frame is correctly unusable, so smoke-test with full-body or at least torso-in-frame
75
+ photos ([docs/metrics.md](docs/metrics.md#what-makes-a-pose-unusable)). In `compare`, a close
73
76
  pose match means "the same pose", not "a copied frame": most same-stance poses have a near twin in a large training
74
77
  set. Read the per-output match as a pointer for an image-level check, and `close_share` against the training set's
75
78
  own `baseline_close_share` (`close_excess`) as the run-level signal
@@ -113,7 +116,7 @@ it apart from other packages' `<stem>.json` sidecars). It is a `PoseResult`, the
113
116
 
114
117
  ```jsonc
115
118
  {
116
- "puppet_version": "1.1",
119
+ "puppet_version": "1.2",
117
120
  "image": "woman_yoga.jpg",
118
121
  "image_sha256": "…",
119
122
  "width": 480, "height": 720,
@@ -160,7 +160,8 @@ cluster id, and its provenance: the source image's name and SHA-256.
160
160
  confident hip and shoulder to anchor on and 8 confident body joints; see
161
161
  [pose-vector.md](pose-vector.md#unusable-poses)). A pose the vector cannot embed could never be compared,
162
162
  deduplicated or clustered, so it would sit in a cluster of its own and stratified sampling would favour it; such
163
- images are counted as `unembeddable` and skipped, as are images with nobody usable. Each entry is labelled
163
+ images are counted as `unembeddable` (split by [reason](metrics.md#why-a-pose-is-unusable) in
164
+ `unembeddable_reasons`) and skipped, as are images with nobody usable. Each entry is labelled
164
165
  (stance, arms, facing; `labels.pose_labels`). Entry ids are derived from the source image's hash and the
165
166
  keypoints, so rebuilding from the same inputs gives the same ids.
166
167
  4. **Age check** (optional, `age_gate`; on with real-person sources): see below.
@@ -83,7 +83,7 @@ VERSION=<version> .`). Without `VERSION` the image reports `0.0.0.dev0`.
83
83
  verified. It also gives the provider and device, free VRAM on a GPU, and read-only mode:
84
84
 
85
85
  ```json
86
- {"puppet_version": "1.1", "version": "0.2.0", "read_only": false,
86
+ {"puppet_version": "1.2", "version": "0.2.0", "read_only": false,
87
87
  "models": {"dwpose-l-384x288": true, "dwpose-m-256x192": true, "yolox_m": true, "yolox_nano": true},
88
88
  "pose_model": "dwpose-l-384x288", "detector_model": "yolox_m",
89
89
  "provider": "CUDAExecutionProvider", "device": "cuda", "gpu_coordinator": "none", "free_vram_mb": 22544}
@@ -34,12 +34,13 @@ comparison itself.
34
34
 
35
35
  Each image contributes its **primary person** (`PoseResult.primary`). An image is **usable** when it has one and
36
36
  `embed()` accepts it (see [pose-vector.md](pose-vector.md#unusable-poses)). Unusable images are listed in `items`
37
- with `usable: false`, keep whatever labels the rules can still decide (an upper-body shot still has arms), and are
38
- left out of every number.
37
+ with `usable: false` and an `unusable_reason` (see [why a pose is unusable](#why-a-pose-is-unusable)), keep
38
+ whatever labels the rules can still decide (an upper-body shot still has arms), and are left out of every number.
39
39
 
40
40
  | field | definition |
41
41
  |---|---|
42
42
  | `count`, `usable` | images, and images with a usable primary pose |
43
+ | `unusable_reasons` | how many images are unusable for each [reason](#why-a-pose-is-unusable), listing only reasons that occur: it sums to `count - usable` and is `{}` when everything is usable (and in documents before wire 1.2) |
43
44
  | `comparable_pairs` | pairs of usable poses whose distance is defined (enough shared joints): the denominator of `diversity` and `mean_pairwise_distance` |
44
45
  | `comparable_share` | `comparable_pairs / (usable (usable - 1) / 2)`; 0 under two usable. Low when many poses are partial (waist-up crops against full-body shots) |
45
46
  | `mean_pairwise_distance` | mean `d` over all comparable usable pairs; 0 under two |
@@ -47,7 +48,46 @@ left out of every number.
47
48
  | `clusters` | average-linkage clusters, largest first: `id`, `size`, `share = size / usable`, `medoid` |
48
49
  | `largest_cluster_share` | share of the largest cluster; 0 when nothing is usable |
49
50
  | `coverage` | per label, the number of usable poses carrying it; every label listed, zero or not |
50
- | `items` | one per image, **sorted by image name**: `usable`, `cluster`, `labels`, `xy` |
51
+ | `items` | one per image, **sorted by image name**: `usable`, `unusable_reason` (null when usable), `cluster`, `labels`, `xy` |
52
+
53
+ ### Why a pose is unusable
54
+
55
+ Every unusable image carries exactly one reason (wire 1.2), the first of these checks it fails, in this order.
56
+ `embedding.embed_or_reason` makes the decision and returns the reason from where it is made; `embed()` is the same
57
+ call without the reason, so the reason and the verdict cannot disagree.
58
+
59
+ | reason | the check | where it is decided |
60
+ |---|---|---|
61
+ | `no_person` | the image has no primary person (nobody was detected) | `metrics.embed_set` |
62
+ | `no_confident_torso` | neither a hip nor a shoulder scores `min_joint_score` (0.3) or more | `embedding._anchor_points` |
63
+ | `no_confident_hip` | a confident shoulder, but no confident hip (a waist-up crop) | `embedding._anchor_points` |
64
+ | `no_confident_shoulder` | a confident hip, but no confident shoulder (a legs crop, shoulders out of frame) | `embedding._anchor_points` |
65
+ | `scale_too_small` | the robust torso scale `S` is under 4 pixels: noise, not a person | `embedding.torso_frame_or_reason` |
66
+ | `too_few_joints` | fewer than `min_usable_joints` (8) of the 17 body joints are confident (a head-and-shoulders portrait) | `embedding.embed_or_reason` |
67
+
68
+ A doubtful hip or shoulder (score 0.1 to 0.3) still helps place a pose whose other hip or shoulder is confident
69
+ ([pose-vector.md](pose-vector.md#unusable-poses)), but never anchors one on its own, so a pose whose only hips are
70
+ doubtful reads `no_confident_hip`. The same reasons appear in `compare` (each unusable output's
71
+ `matches[].unusable_reason`, and `output_unusable_reasons` / `reference_unusable_reasons`) and in library builds
72
+ (`LibraryBuild.unembeddable_reasons`; `no_person` and a low body score are counted separately there, as `no_person`
73
+ and `low_score`). The CLI's `stats`, `compare` and `library build` print the breakdown whenever anything is unusable.
74
+
75
+ ### What makes a pose unusable
76
+
77
+ The pose vector is centred on the mid-hip and scaled by the torso, so it needs at least one hip and one shoulder in
78
+ frame and confident. A crop without the shoulders (legs and an arm) or without the hips (a head-and-shoulders or
79
+ chest-up shot) is **correctly** unusable: there is nothing to measure its pose against. A set of tight crops
80
+ therefore has a low usable share, and that is the right answer, not an estimator failure; read `unusable_reasons`
81
+ before reading anything into it. A smoke test needs full-body images, or at least the torso (both a hip and a
82
+ shoulder) in frame; guessing from the mean body score is not enough, since a legs crop can have a respectable mean
83
+ and still no shoulder.
84
+
85
+ The joint-score cut (0.3) is not calibrated by the synthetic sets below: the synthetic generators score every
86
+ joint 0.9 or 0, so any cut between the two gives the same result and they cannot test it. So far it rests on two
87
+ real photos (a full-body shot and a shoulders-out-of-frame crop, the opt-in real-model test in
88
+ `tests/test_real_model.py`), in which every visible joint scored 0.38 or more and every occluded or out-of-frame
89
+ joint 0.26 or less, and on matching the DWPose annotator's drawing threshold (0.3, as `RenderOptions.min_score`
90
+ applies it).
51
91
 
52
92
  ### Clustering
53
93
 
@@ -284,11 +324,13 @@ reference set, so the answer can be read against what "no copying" looks like fo
284
324
  | field | definition |
285
325
  |---|---|
286
326
  | `matches` | one per output image, sorted by image name: `nearest`, `distance`, `shared_joints`, `close`. An output that is unusable, or shares too few joints with every usable reference pose, has `nearest`, `distance` and `shared_joints` null and `close` false. Ties for nearest go to the alphabetically first reference image |
327
+ | `matches[].unusable_reason` | why the output is unusable ([reasons](#why-a-pose-is-unusable)); null for a usable output, matched or not |
287
328
  | `matches[].shared_joints` | of the 12 non-head joints (shoulders, elbows, wrists, hips, knees, ankles), how many are confident in both poses, in the orientation compared |
288
329
  | `matches[].close` | some reference pose sharing at least `min_close_joints` (12) of those joints is closer than `threshold`. The match then names the nearest such pose; otherwise it names the nearest comparable pose of any coverage, which is reported but never close. A waist-up output is never close to a full-body frame, however well the upper bodies agree |
289
330
  | `output_count` | every output image, usable or not (one `matches` entry each) |
290
331
  | `matched_count` | outputs with a nearest reference pose |
291
332
  | `reference_count` | usable reference poses |
333
+ | `output_unusable_reasons`, `reference_unusable_reasons` | how many images of each set are unusable for each reason, listing only reasons that occur |
292
334
  | `close_eligible` | outputs that share all 12 joints with at least one reference pose, so could be close |
293
335
  | `close_share` | close outputs / `close_eligible`; 0 when none is eligible |
294
336
  | `baseline_eligible`, `baseline_close_share` | the same statistic inside the reference set, leave-one-out: each reference pose against its nearest *other* reference pose, same rules. Null with fewer than two usable reference poses or none eligible |
@@ -74,13 +74,16 @@ not count as a wrist at the hip.
74
74
 
75
75
  ### Unusable poses
76
76
 
77
- `embed()` returns `None` (the image is not usable) when:
77
+ `embed()` returns `None` (the image is not usable) when one of these holds; `embed_or_reason()` returns the reason
78
+ instead, the first that applies, in this order (the set metrics put it on the wire, see
79
+ [metrics.md](metrics.md#why-a-pose-is-unusable)):
78
80
 
79
81
  - no hip or no shoulder is confident (there is no anchor to centre or scale on; rules 2 and 3 above only complete a
80
- pair);
81
- - the scale `S` is under 4 pixels (noise, not a person);
82
- - fewer than `min_usable_joints` (default 8) body joints are confident. Eight admits an upper-body shot with the
83
- hips in frame (head 5 + shoulders 2 + hips 2 = 9 before any limb) and refuses a head-and-shoulders portrait.
82
+ pair): `no_confident_torso` (neither), `no_confident_hip` or `no_confident_shoulder`;
83
+ - the scale `S` is under 4 pixels (noise, not a person): `scale_too_small`;
84
+ - fewer than `min_usable_joints` (default 8) body joints are confident: `too_few_joints`. Eight admits an upper-body
85
+ shot with the hips in frame (head 5 + shoulders 2 + hips 2 = 9 before any limb) and refuses a head-and-shoulders
86
+ portrait.
84
87
 
85
88
  ### Not rotation-invariant
86
89
 
@@ -7,8 +7,10 @@ publishes it on the host's loopback (see [deploy.md](deploy.md)). The app is `ar
7
7
 
8
8
  Every request and response body is a type from `src/argus_puppet/models.py`, the wire contract. Its field
9
9
  descriptions are authoritative and are rendered to `schema/puppet-wire.schema.json`. Top-level documents carry
10
- `puppet_version` (currently `"1.1"`); a 1.x reader ignores fields it does not know, and every 1.x reader accepts a
11
- 1.0 document. 1.1 added `PersonPose.labels` (see [`POST /pose`](#post-pose)).
10
+ `puppet_version` (currently `"1.2"`); a 1.x reader ignores fields it does not know, and every 1.x reader accepts a
11
+ 1.0 document. 1.1 added `PersonPose.labels` (see [`POST /pose`](#post-pose)). 1.2 added why a pose is unusable:
12
+ `unusable_reason` on `/stats` items and `/compare` matches, with counts by reason beside them (see
13
+ [`POST /stats`](#post-stats)).
12
14
 
13
15
  ## Routes
14
16
 
@@ -35,7 +37,7 @@ curl -s http://<PUPPET_HOST>:8220/health
35
37
  ```
36
38
 
37
39
  ```json
38
- {"puppet_version": "1.1", "version": "0.2.0", "read_only": false,
40
+ {"puppet_version": "1.2", "version": "0.2.0", "read_only": false,
39
41
  "models": {"dwpose-l-384x288": true, "dwpose-m-256x192": true, "yolox_m": true, "yolox_nano": true},
40
42
  "pose_model": "dwpose-l-384x288", "detector_model": "yolox_m",
41
43
  "provider": null, "device": "cpu", "gpu_coordinator": "none", "free_vram_mb": null}
@@ -191,12 +193,22 @@ curl -s -X POST -H 'content-type: application/json' \
191
193
  -d '{"path": "lora-outputs/run-12"}' http://<PUPPET_HOST>:8220/stats
192
194
  ```
193
195
 
194
- The answer is a `PoseSetStats`: `count`, `usable`, `comparable_pairs` and `comparable_share` (how many usable pairs
196
+ The answer is a `PoseSetStats`: `count`, `usable`, `unusable_reasons` (how many images are unusable for each
197
+ reason, only reasons that occur), `comparable_pairs` and `comparable_share` (how many usable pairs
195
198
  the scores could compare), `diversity` (0 to 1; argus-proof's pose-diversity gate reads this, beside
196
199
  `largest_cluster_share`), `mean_pairwise_distance`, `cluster_count`, `largest_cluster_share`, `clusters` (largest first, each with a
197
200
  `medoid` image), `coverage` (counts per stance, arms and facing label), `items` (one per image, with its cluster,
198
201
  labels and a 2D point for a scatter plot), the `params` used, and the shared `estimator` when every pose came from
199
- the same one.
202
+ the same one. An unusable item has `usable: false` and an `unusable_reason`:
203
+
204
+ ```json
205
+ {"image": "legs-crop.jpg", "usable": false, "unusable_reason": "no_confident_shoulder", "cluster": null,
206
+ "labels": {"stance": "unknown", "arms": "unknown", "facing": "unknown"}, "xy": null}
207
+ ```
208
+
209
+ The reasons are `no_person`, `no_confident_torso`, `no_confident_hip`, `no_confident_shoulder`, `scale_too_small`
210
+ and `too_few_joints` ([metrics.md](metrics.md#why-a-pose-is-unusable)); `unusable_reason` is null on a usable item
211
+ and absent from documents before 1.2. A crop without the shoulders or hips in frame is correctly unusable.
200
212
 
201
213
  ### `POST /compare`
202
214
 
@@ -219,7 +231,8 @@ curl -s -X POST -H 'content-type: application/json' \
219
231
  ```
220
232
 
221
233
  The answer is a `PoseSetComparison`: one `matches` entry per output (`nearest`, `distance`, `shared_joints`,
222
- `close`), `output_count`, `matched_count`, `reference_count`, `close_eligible` and `close_share`, the reference set's
234
+ `close`, and `unusable_reason` for an unusable output), `output_count`, `matched_count`, `reference_count`,
235
+ `output_unusable_reasons` and `reference_unusable_reasons`, `close_eligible` and `close_share`, the reference set's
223
236
  own leave-one-out `baseline_close_share` and `close_excess`, nearest-distance quantiles for both sides, the
224
237
  `coverage_divergence` between the two sets' label mixes, both coverages, the threshold and params used.
225
238
 
@@ -235,7 +248,7 @@ Each set counts against the set cap separately, so one request can carry two set
235
248
  One pose to an OpenPose-convention skeleton PNG for a pose ControlNet.
236
249
 
237
250
  ```json
238
- {"pose": {"puppet_version": "1.1", "image": "photo.jpg", "...": "a whole PoseResult"},
251
+ {"pose": {"puppet_version": "1.2", "image": "photo.jpg", "...": "a whole PoseResult"},
239
252
  "options": {"width": 1024, "height": 1024, "face": false, "stroke_scale": "auto"}}
240
253
  ```
241
254
 
@@ -342,7 +342,7 @@
342
342
  "title": "Provider"
343
343
  },
344
344
  "puppet_version": {
345
- "default": "1.1",
345
+ "default": "1.2",
346
346
  "title": "Puppet Version",
347
347
  "type": "string"
348
348
  },
@@ -790,7 +790,7 @@
790
790
  "type": "string"
791
791
  },
792
792
  "puppet_version": {
793
- "default": "1.1",
793
+ "default": "1.2",
794
794
  "title": "Puppet Version",
795
795
  "type": "string"
796
796
  }
@@ -936,6 +936,27 @@
936
936
  "default": null,
937
937
  "description": "Non-head body joints (of 12: shoulders, elbows, wrists, hips, knees, ankles) confident in both poses in the orientation compared; null exactly when nearest is null.",
938
938
  "title": "Shared Joints"
939
+ },
940
+ "unusable_reason": {
941
+ "anyOf": [
942
+ {
943
+ "enum": [
944
+ "no_person",
945
+ "no_confident_torso",
946
+ "no_confident_hip",
947
+ "no_confident_shoulder",
948
+ "scale_too_small",
949
+ "too_few_joints"
950
+ ],
951
+ "type": "string"
952
+ },
953
+ {
954
+ "type": "null"
955
+ }
956
+ ],
957
+ "default": null,
958
+ "description": "Why the output is not usable, when it is not (then nearest is null): 'no_person' (no primary person), 'no_confident_torso' (neither a hip nor a shoulder at params.min_joint_score), 'no_confident_hip' (a shoulder but no hip, e.g. a waist-up crop), 'no_confident_shoulder' (a hip but no shoulder, e.g. a legs crop), 'scale_too_small' (torso under 4 px), 'too_few_joints' (fewer than params.min_usable_joints confident body joints); the first failing check, in that order (docs/metrics.md). Null for a usable output, matched or not (and in payloads before puppet_version 1.2).",
959
+ "title": "Unusable Reason"
939
960
  }
940
961
  },
941
962
  "required": [
@@ -999,7 +1020,7 @@
999
1020
  "title": "Primary"
1000
1021
  },
1001
1022
  "puppet_version": {
1002
- "default": "1.1",
1023
+ "default": "1.2",
1003
1024
  "title": "Puppet Version",
1004
1025
  "type": "string"
1005
1026
  },
@@ -1126,11 +1147,30 @@
1126
1147
  "default": null,
1127
1148
  "description": "Quantiles, over the eligible outputs, of the distance to the nearest reference pose sharing params.min_close_joints joints; null when no output is eligible."
1128
1149
  },
1150
+ "output_unusable_reasons": {
1151
+ "additionalProperties": {
1152
+ "minimum": 0,
1153
+ "type": "integer"
1154
+ },
1155
+ "description": "How many output images are unusable for each reason (matches' unusable_reason), listing only reasons that occur; empty when every output is usable (and in payloads before puppet_version 1.2).",
1156
+ "propertyNames": {
1157
+ "enum": [
1158
+ "no_person",
1159
+ "no_confident_torso",
1160
+ "no_confident_hip",
1161
+ "no_confident_shoulder",
1162
+ "scale_too_small",
1163
+ "too_few_joints"
1164
+ ]
1165
+ },
1166
+ "title": "Output Unusable Reasons",
1167
+ "type": "object"
1168
+ },
1129
1169
  "params": {
1130
1170
  "$ref": "#/$defs/MetricParams"
1131
1171
  },
1132
1172
  "puppet_version": {
1133
- "default": "1.1",
1173
+ "default": "1.2",
1134
1174
  "title": "Puppet Version",
1135
1175
  "type": "string"
1136
1176
  },
@@ -1155,6 +1195,25 @@
1155
1195
  "default": null,
1156
1196
  "description": "Quantiles, over the eligible reference poses, of the distance to the nearest other reference pose sharing params.min_close_joints joints (leave-one-out); null when baseline_close_share is null. Outputs whose quantiles sit well below these are closer to the training frames than the frames are to each other."
1157
1197
  },
1198
+ "reference_unusable_reasons": {
1199
+ "additionalProperties": {
1200
+ "minimum": 0,
1201
+ "type": "integer"
1202
+ },
1203
+ "description": "How many reference images are unusable for each reason, listing only reasons that occur; empty when every reference image is usable (and in payloads before puppet_version 1.2).",
1204
+ "propertyNames": {
1205
+ "enum": [
1206
+ "no_person",
1207
+ "no_confident_torso",
1208
+ "no_confident_hip",
1209
+ "no_confident_shoulder",
1210
+ "scale_too_small",
1211
+ "too_few_joints"
1212
+ ]
1213
+ },
1214
+ "title": "Reference Unusable Reasons",
1215
+ "type": "object"
1216
+ },
1158
1217
  "threshold": {
1159
1218
  "description": "Pose distance below which a match can be close.",
1160
1219
  "minimum": 0.0,
@@ -1201,6 +1260,27 @@
1201
1260
  "labels": {
1202
1261
  "$ref": "#/$defs/PoseLabels"
1203
1262
  },
1263
+ "unusable_reason": {
1264
+ "anyOf": [
1265
+ {
1266
+ "enum": [
1267
+ "no_person",
1268
+ "no_confident_torso",
1269
+ "no_confident_hip",
1270
+ "no_confident_shoulder",
1271
+ "scale_too_small",
1272
+ "too_few_joints"
1273
+ ],
1274
+ "type": "string"
1275
+ },
1276
+ {
1277
+ "type": "null"
1278
+ }
1279
+ ],
1280
+ "default": null,
1281
+ "description": "Why it is not usable: 'no_person' (no primary person), 'no_confident_torso' (neither a hip nor a shoulder at params.min_joint_score), 'no_confident_hip' (a shoulder but no hip, e.g. a waist-up crop), 'no_confident_shoulder' (a hip but no shoulder, e.g. a legs crop), 'scale_too_small' (torso under 4 px), 'too_few_joints' (fewer than params.min_usable_joints confident body joints); the first failing check, in that order (docs/metrics.md). Null when usable (and in payloads before puppet_version 1.2).",
1282
+ "title": "Unusable Reason"
1283
+ },
1204
1284
  "usable": {
1205
1285
  "description": "Whether it had a primary person with enough confident joints to embed (see params).",
1206
1286
  "title": "Usable",
@@ -1360,10 +1440,29 @@
1360
1440
  "$ref": "#/$defs/MetricParams"
1361
1441
  },
1362
1442
  "puppet_version": {
1363
- "default": "1.1",
1443
+ "default": "1.2",
1364
1444
  "title": "Puppet Version",
1365
1445
  "type": "string"
1366
1446
  },
1447
+ "unusable_reasons": {
1448
+ "additionalProperties": {
1449
+ "minimum": 0,
1450
+ "type": "integer"
1451
+ },
1452
+ "description": "How many images are unusable for each reason (items' unusable_reason), listing only reasons that occur, so it sums to count - usable and is empty when every image is usable (and in payloads before puppet_version 1.2).",
1453
+ "propertyNames": {
1454
+ "enum": [
1455
+ "no_person",
1456
+ "no_confident_torso",
1457
+ "no_confident_hip",
1458
+ "no_confident_shoulder",
1459
+ "scale_too_small",
1460
+ "too_few_joints"
1461
+ ]
1462
+ },
1463
+ "title": "Unusable Reasons",
1464
+ "type": "object"
1465
+ },
1367
1466
  "usable": {
1368
1467
  "description": "Images with a usable primary pose.",
1369
1468
  "minimum": 0,
@@ -1575,7 +1674,7 @@
1575
1674
  "type": "integer"
1576
1675
  },
1577
1676
  "puppet_version": {
1578
- "default": "1.1",
1677
+ "default": "1.2",
1579
1678
  "title": "Puppet Version",
1580
1679
  "type": "string"
1581
1680
  },
@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
18
18
  commit_id: str | None
19
19
  __commit_id__: str | None
20
20
 
21
- __version__ = version = '0.2.0'
22
- __version_tuple__ = version_tuple = (0, 2, 0)
21
+ __version__ = version = '0.3.0'
22
+ __version_tuple__ = version_tuple = (0, 3, 0)
23
23
 
24
24
  __commit_id__ = commit_id = None
@@ -18,6 +18,8 @@ from argus_puppet.config import DEFAULT_PORT, DEVICES, ConfigError, Settings
18
18
  from argus_puppet.models import SCHEMA_PATH, Arms, Facing, Fit, Stance
19
19
 
20
20
  if TYPE_CHECKING:
21
+ from rich.table import Table
22
+
21
23
  from argus_puppet.models import MetricParams, PoseResult, PoseSetComparison, PoseSetStats, ScanSummary
22
24
 
23
25
  app = typer.Typer(
@@ -274,6 +276,17 @@ def stats(
274
276
  raise typer.Exit(1)
275
277
 
276
278
 
279
+ def _reason_rows(table: Table, label: str | None, reasons: dict[str, int]) -> None:
280
+ """Rows of a rich summary table: how many images are unusable (under *label*, unless it is None), then one
281
+ indented row per reason. Nothing when every image is usable."""
282
+ if not reasons:
283
+ return
284
+ if label is not None:
285
+ table.add_row(label, str(sum(reasons.values())))
286
+ for reason, n in reasons.items():
287
+ table.add_row(f" {reason.replace('_', ' ')}", str(n))
288
+
289
+
277
290
  def _print_stats(folder: Path, s: PoseSetStats, out: Path | None) -> None:
278
291
  from rich.console import Console
279
292
  from rich.markup import escape
@@ -284,6 +297,7 @@ def _print_stats(folder: Path, s: PoseSetStats, out: Path | None) -> None:
284
297
  summary = Table(show_header=False)
285
298
  summary.add_row("images", str(s.count))
286
299
  summary.add_row("usable poses", str(s.usable))
300
+ _reason_rows(summary, "unusable, by reason", s.unusable_reasons)
287
301
  summary.add_row("comparable pairs", f"{s.comparable_pairs} ({s.comparable_share:.0%} of usable pairs)")
288
302
  summary.add_row("diversity", f"{s.diversity:.3f}")
289
303
  summary.add_row("mean pairwise distance", f"{s.mean_pairwise_distance:.3f}")
@@ -358,8 +372,10 @@ def _print_comparison(c: PoseSetComparison, top: int, out: Path | None) -> None:
358
372
  console = Console()
359
373
  summary = Table(show_header=False, title="argus-puppet compare")
360
374
  summary.add_row("outputs", str(c.output_count))
375
+ _reason_rows(summary, "unusable outputs, by reason", c.output_unusable_reasons)
361
376
  summary.add_row("matched outputs", str(c.matched_count))
362
377
  summary.add_row("usable reference poses", str(c.reference_count))
378
+ _reason_rows(summary, "unusable reference images, by reason", c.reference_unusable_reasons)
363
379
  summary.add_row("close-match eligible outputs", str(c.close_eligible))
364
380
  summary.add_row("close share", f"{c.close_share:.0%} (distance < {c.threshold:g}, whole limb skeleton shared)")
365
381
  if c.baseline_close_share is None:
@@ -610,6 +626,7 @@ def library_build(
610
626
  "no_person": build.no_person,
611
627
  "low_score": build.low_score,
612
628
  "unembeddable": build.unembeddable,
629
+ "unembeddable_reasons": build.unembeddable_reasons,
613
630
  "duplicate_ids": build.duplicate_ids,
614
631
  "near_duplicates": build.near_duplicates,
615
632
  "sampled_out": build.sampled_out,
@@ -646,6 +663,8 @@ def _print_build(counts: dict) -> None:
646
663
  rows += ["age_passed", "under_age", "age_unchecked"]
647
664
  for key in rows:
648
665
  table.add_row(key.replace("_", " "), str(counts[key]))
666
+ if key == "unembeddable":
667
+ _reason_rows(table, None, counts["unembeddable_reasons"])
649
668
  console.print(table)
650
669
  for item in counts["age_excluded"]:
651
670
  console.print(f"[yellow]age check kept out[/yellow] {escape(item['image'])}: {escape(item['why'])}")
@@ -103,7 +103,7 @@ def compare_pose_sets(
103
103
 
104
104
  ``matches`` lists one entry per output image, sorted by image name. An output that is unusable, or shares too few
105
105
  joints with every usable reference pose, has ``nearest``, ``distance`` and ``shared_joints`` null and is not
106
- close. An output is close when some reference pose sharing at least ``params.min_close_joints`` of the 12
106
+ close; an unusable one also carries its ``unusable_reason`` (null for a usable but unmatched output). An output is close when some reference pose sharing at least ``params.min_close_joints`` of the 12
107
107
  non-head joints with it is closer than *threshold*; its match then names the nearest such pose, and otherwise the
108
108
  nearest comparable pose of any coverage. ``close_share`` is over the outputs that could be close
109
109
  (``close_eligible``); ``baseline_close_share`` is the same share inside the reference set, each reference pose
@@ -130,7 +130,7 @@ def compare_pose_sets(
130
130
  for i, image in enumerate(out_set.images):
131
131
  row = row_of.get(i)
132
132
  if row is None or nn.index[row] < 0:
133
- matches.append(PoseMatch(image=image, close=False))
133
+ matches.append(PoseMatch(image=image, close=False, unusable_reason=out_set.reasons[i]))
134
134
  continue
135
135
  close = bool(nn.full_index[row] >= 0 and nn.full_distance[row] < threshold)
136
136
  if close:
@@ -163,6 +163,8 @@ def compare_pose_sets(
163
163
  output_count=len(matches),
164
164
  matched_count=matched,
165
165
  reference_count=len(ref_idx),
166
+ output_unusable_reasons=out_set.reason_counts(),
167
+ reference_unusable_reasons=ref_set.reason_counts(),
166
168
  matches=matches,
167
169
  close_eligible=int(eligible.sum()),
168
170
  close_share=close_share,