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.
- {argus_puppet-0.2.0 → argus_puppet-0.3.0}/CLAUDE.md +2 -0
- {argus_puppet-0.2.0 → argus_puppet-0.3.0}/PKG-INFO +6 -3
- {argus_puppet-0.2.0 → argus_puppet-0.3.0}/README.md +5 -2
- {argus_puppet-0.2.0 → argus_puppet-0.3.0}/docs/conditioning.md +2 -1
- {argus_puppet-0.2.0 → argus_puppet-0.3.0}/docs/deploy.md +1 -1
- {argus_puppet-0.2.0 → argus_puppet-0.3.0}/docs/metrics.md +45 -3
- {argus_puppet-0.2.0 → argus_puppet-0.3.0}/docs/pose-vector.md +8 -5
- {argus_puppet-0.2.0 → argus_puppet-0.3.0}/docs/server.md +20 -7
- {argus_puppet-0.2.0 → argus_puppet-0.3.0}/schema/puppet-wire.schema.json +105 -6
- {argus_puppet-0.2.0 → argus_puppet-0.3.0}/src/argus_puppet/_version.py +2 -2
- {argus_puppet-0.2.0 → argus_puppet-0.3.0}/src/argus_puppet/cli.py +19 -0
- {argus_puppet-0.2.0 → argus_puppet-0.3.0}/src/argus_puppet/compare.py +4 -2
- {argus_puppet-0.2.0 → argus_puppet-0.3.0}/src/argus_puppet/embedding.py +72 -20
- {argus_puppet-0.2.0 → argus_puppet-0.3.0}/src/argus_puppet/library.py +14 -6
- {argus_puppet-0.2.0 → argus_puppet-0.3.0}/src/argus_puppet/metrics.py +25 -3
- {argus_puppet-0.2.0 → argus_puppet-0.3.0}/src/argus_puppet/models.py +62 -1
- {argus_puppet-0.2.0 → argus_puppet-0.3.0}/tests/test_cli.py +33 -0
- {argus_puppet-0.2.0 → argus_puppet-0.3.0}/tests/test_compare.py +20 -0
- {argus_puppet-0.2.0 → argus_puppet-0.3.0}/tests/test_embedding.py +53 -0
- {argus_puppet-0.2.0 → argus_puppet-0.3.0}/tests/test_library.py +1 -0
- {argus_puppet-0.2.0 → argus_puppet-0.3.0}/tests/test_metrics.py +91 -1
- {argus_puppet-0.2.0 → argus_puppet-0.3.0}/tests/test_models.py +14 -1
- argus_puppet-0.3.0/tests/test_real_model.py +128 -0
- argus_puppet-0.2.0/tests/test_real_model.py +0 -63
- {argus_puppet-0.2.0 → argus_puppet-0.3.0}/.copier-answers.yml +0 -0
- {argus_puppet-0.2.0 → argus_puppet-0.3.0}/.dockerignore +0 -0
- {argus_puppet-0.2.0 → argus_puppet-0.3.0}/.github/workflows/ci.yml +0 -0
- {argus_puppet-0.2.0 → argus_puppet-0.3.0}/.github/workflows/docs.yml +0 -0
- {argus_puppet-0.2.0 → argus_puppet-0.3.0}/.github/workflows/release.yml +0 -0
- {argus_puppet-0.2.0 → argus_puppet-0.3.0}/.github/workflows/suite.yml +0 -0
- {argus_puppet-0.2.0 → argus_puppet-0.3.0}/.gitignore +0 -0
- {argus_puppet-0.2.0 → argus_puppet-0.3.0}/.suite-rules-baseline.json +0 -0
- {argus_puppet-0.2.0 → argus_puppet-0.3.0}/Dockerfile +0 -0
- {argus_puppet-0.2.0 → argus_puppet-0.3.0}/LICENSE +0 -0
- {argus_puppet-0.2.0 → argus_puppet-0.3.0}/Makefile +0 -0
- {argus_puppet-0.2.0 → argus_puppet-0.3.0}/compose.yaml +0 -0
- {argus_puppet-0.2.0 → argus_puppet-0.3.0}/docs/cli.md +0 -0
- {argus_puppet-0.2.0 → argus_puppet-0.3.0}/docs/index.md +0 -0
- {argus_puppet-0.2.0 → argus_puppet-0.3.0}/docs/models.md +0 -0
- {argus_puppet-0.2.0 → argus_puppet-0.3.0}/gpu-tenant.yaml +0 -0
- {argus_puppet-0.2.0 → argus_puppet-0.3.0}/pyproject.toml +0 -0
- {argus_puppet-0.2.0 → argus_puppet-0.3.0}/src/argus_puppet/__init__.py +0 -0
- {argus_puppet-0.2.0 → argus_puppet-0.3.0}/src/argus_puppet/age.py +0 -0
- {argus_puppet-0.2.0 → argus_puppet-0.3.0}/src/argus_puppet/config.py +0 -0
- {argus_puppet-0.2.0 → argus_puppet-0.3.0}/src/argus_puppet/estimator.py +0 -0
- {argus_puppet-0.2.0 → argus_puppet-0.3.0}/src/argus_puppet/extract.py +0 -0
- {argus_puppet-0.2.0 → argus_puppet-0.3.0}/src/argus_puppet/gpu.py +0 -0
- {argus_puppet-0.2.0 → argus_puppet-0.3.0}/src/argus_puppet/labels.py +0 -0
- {argus_puppet-0.2.0 → argus_puppet-0.3.0}/src/argus_puppet/primary.py +0 -0
- {argus_puppet-0.2.0 → argus_puppet-0.3.0}/src/argus_puppet/py.typed +0 -0
- {argus_puppet-0.2.0 → argus_puppet-0.3.0}/src/argus_puppet/registry.py +0 -0
- {argus_puppet-0.2.0 → argus_puppet-0.3.0}/src/argus_puppet/render.py +0 -0
- {argus_puppet-0.2.0 → argus_puppet-0.3.0}/src/argus_puppet/runtime.py +0 -0
- {argus_puppet-0.2.0 → argus_puppet-0.3.0}/src/argus_puppet/sampling.py +0 -0
- {argus_puppet-0.2.0 → argus_puppet-0.3.0}/src/argus_puppet/server/__init__.py +0 -0
- {argus_puppet-0.2.0 → argus_puppet-0.3.0}/src/argus_puppet/server/app.py +0 -0
- {argus_puppet-0.2.0 → argus_puppet-0.3.0}/src/argus_puppet/sidecars.py +0 -0
- {argus_puppet-0.2.0 → argus_puppet-0.3.0}/src/argus_puppet/skeleton.py +0 -0
- {argus_puppet-0.2.0 → argus_puppet-0.3.0}/src/argus_puppet/weights.py +0 -0
- {argus_puppet-0.2.0 → argus_puppet-0.3.0}/tests/conftest.py +0 -0
- {argus_puppet-0.2.0 → argus_puppet-0.3.0}/tests/posegen.py +0 -0
- {argus_puppet-0.2.0 → argus_puppet-0.3.0}/tests/synthetic_poses.py +0 -0
- {argus_puppet-0.2.0 → argus_puppet-0.3.0}/tests/test_age.py +0 -0
- {argus_puppet-0.2.0 → argus_puppet-0.3.0}/tests/test_config.py +0 -0
- {argus_puppet-0.2.0 → argus_puppet-0.3.0}/tests/test_estimator.py +0 -0
- {argus_puppet-0.2.0 → argus_puppet-0.3.0}/tests/test_extract.py +0 -0
- {argus_puppet-0.2.0 → argus_puppet-0.3.0}/tests/test_gpu.py +0 -0
- {argus_puppet-0.2.0 → argus_puppet-0.3.0}/tests/test_gpu_tenant.py +0 -0
- {argus_puppet-0.2.0 → argus_puppet-0.3.0}/tests/test_labels.py +0 -0
- {argus_puppet-0.2.0 → argus_puppet-0.3.0}/tests/test_must_never.py +0 -0
- {argus_puppet-0.2.0 → argus_puppet-0.3.0}/tests/test_primary.py +0 -0
- {argus_puppet-0.2.0 → argus_puppet-0.3.0}/tests/test_registry.py +0 -0
- {argus_puppet-0.2.0 → argus_puppet-0.3.0}/tests/test_render.py +0 -0
- {argus_puppet-0.2.0 → argus_puppet-0.3.0}/tests/test_runtime.py +0 -0
- {argus_puppet-0.2.0 → argus_puppet-0.3.0}/tests/test_sampling.py +0 -0
- {argus_puppet-0.2.0 → argus_puppet-0.3.0}/tests/test_server.py +0 -0
- {argus_puppet-0.2.0 → argus_puppet-0.3.0}/tests/test_server_sets.py +0 -0
- {argus_puppet-0.2.0 → argus_puppet-0.3.0}/tests/test_skeleton.py +0 -0
- {argus_puppet-0.2.0 → argus_puppet-0.3.0}/tests/test_smoke.py +0 -0
- {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.
|
|
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)).
|
|
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.
|
|
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)).
|
|
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.
|
|
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`
|
|
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.
|
|
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
|
|
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
|
|
83
|
-
hips in frame (head 5 + shoulders 2 + hips 2 = 9 before any limb) and refuses a head-and-shoulders
|
|
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.
|
|
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.
|
|
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`, `
|
|
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`,
|
|
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.
|
|
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.
|
|
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.
|
|
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.
|
|
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.
|
|
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.
|
|
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.
|
|
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.
|
|
22
|
-
__version_tuple__ = version_tuple = (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,
|