abstract-identity 0.1.0__tar.gz

abstract_identity-0.1.0/LICENSE

@@ -0,0 +1,59 @@
+MIT License
+
+Copyright (c) 2026 putkoff (hugpy.ai)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+THIRD-PARTY OBLIGATIONS NOTICE (not part of the MIT license above)
+
+The MIT license covers abstract_identity's own source code only (both the
+char360 and render subpackages). A DEPLOYED installation with the optional
+runtime stacks present loads third-party components whose licenses impose
+their own obligations on any combined or deployed work:
+
+char360 subpackage (the [render] extra's detection stack):
+
+  * ultralytics (YOLO) — AGPL-3.0. A deployment of char360 with ultralytics
+    installed is an AGPL-governed combined work: offering it as a network
+    service or distributing it triggers AGPL source obligations. Ultralytics
+    sells a commercial Enterprise license; permissive alternatives exist
+    (e.g. Apache-2.0 RT-DETR).
+  * insightface — the library code is MIT, but the pretrained model packs it
+    downloads (e.g. "buffalo_l") are published for non-commercial research
+    use only. No license file accompanies the packs on disk; the restriction
+    is real regardless.
+
+render subpackage (a deployed identity-render service, installed via
+install/install_identity_render_ae.sh — never pip deps):
+
+  * Hunyuan3D-2 (hy3dgen code AND weights) — Tencent Hunyuan 3D 2.0
+    Community License: does not apply in the EU/UK/South Korea (including
+    generated OUTPUTS), >1M-MAU products need a separate Tencent license,
+    hosted services must disclose the operating entity, and outputs may not
+    be used to improve other AI models.
+  * pymeshlab — GPL-3.0 (pulled in by Hunyuan3D's requirements). No
+    obligation for hosted use; distributing an environment containing it
+    triggers GPL source obligations.
+  * Blender (invoked as a subprocess; GPL) and the installer-vendored copy
+    of it — redistributing the install root includes a GPL program.
+
+Nothing in this notice modifies the MIT grant over abstract_identity's own
+code.

abstract_identity-0.1.0/PKG-INFO

@@ -0,0 +1,159 @@
+Metadata-Version: 2.4
+Name: abstract_identity
+Version: 0.1.0
+Summary: Identity pipeline for hugpy: char360 (video -> character face detection/clustering/360-view selection) + render (identity-render GPU service: Hunyuan3D-2mv mesh, Blender turntable, video_extract, video_characters_glb)
+Author: putkoff
+License: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: flask<4.0,>=3.0
+Requires-Dist: pydantic<3.0,>=2.0
+Provides-Extra: render
+Requires-Dist: scenedetect[opencv]; extra == "render"
+Requires-Dist: ultralytics; extra == "render"
+Requires-Dist: insightface; extra == "render"
+Requires-Dist: onnxruntime-gpu==1.18.1; extra == "render"
+Requires-Dist: opencv-python; extra == "render"
+Requires-Dist: numpy; extra == "render"
+Requires-Dist: scikit-learn; extra == "render"
+Dynamic: license-file
+
+# abstract_identity
+
+Identity pipeline for hugpy, merged from the former standalone `char360` and
+`identity-render` dists into one src-layout package with two subpackages:
+
+| Subpackage | What it is |
+| --- | --- |
+| `abstract_identity.char360` | Video → per-character 360° view sets: scenes → person detect+track (YOLO) → face embed+pose (insightface) → identity cluster (agglomerative) → yaw-bin (12×30°) → best-per-bin crops + `manifest.json`. Library + CLI (`char360` console script / `python -m char360`). |
+| `abstract_identity.render` | The identity-render GPU service (`identity-render` console script): reference photos → Hunyuan3D-2mv mesh (+ headless-Blender turntable), plus the char360-powered `video_extract` and `video_characters_glb` job kinds, behind a tokened Flask job API on :9750. |
+
+## Install
+
+Base (any box — coordinator, dev VM, CI):
+
+```bash
+pip install abstract_identity
+```
+
+Base is deliberately thin and wheels-only: `flask` + `pydantic`, nothing else.
+Every module still imports cleanly with no heavy deps present — heavy imports
+are lazy, inside the stage/job that needs them — so the service can boot
+anywhere and honestly report capabilities as not-ready.
+
+ae render host (GPU box): run the installer instead of pip —
+
+```bash
+bash /srv/share/projects/hugpy/dev/py/abstract_identity/install/install_identity_render_ae.sh \
+  --token <TOKEN>
+```
+
+It is idempotent (safe to re-run), refuses to run without `--token` or as
+root, and sets up: CUDA torch, the Hunyuan3D-2 checkout + weights, rembg,
+portable Blender 4.2, the char360 heavy deps, an editable install of this
+package into the venv, and the `identity-render.service` systemd **user**
+unit (`ExecStart=venv/bin/python -m abstract_identity.render.service`). See
+the script header and its `PASS:`/`FAIL:`/`NOTE:` output for details. One-time
+firewall opening on ae (verified 2026-07-14):
+
+```bash
+sudo ufw allow from 192.168.1.0/24 to any port 9750 proto tcp comment 'identity-render (hugpy central relay)'
+```
+
+## Why the heavy deps are an extra, not base
+
+`pip install abstract_identity[render]` pulls the char360 detection stack:
+`scenedetect[opencv]`, `ultralytics`, `insightface`, `onnxruntime-gpu==1.18.1`,
+`opencv-python`, `numpy`, `scikit-learn`. They are not in base because they are
+
+- **heavy/native/CUDA** — pointless on a coordinator box, and
+- **restrictively licensed** — `ultralytics` is AGPL-3.0 (a deployed
+  combination is an AGPL combined work) and the insightface pretrained packs
+  (`buffalo_l`) are non-commercial research only. See the THIRD-PARTY
+  OBLIGATIONS NOTICE in `LICENSE` before any commercial use or redistribution.
+
+**Hunyuan3D-2 is never a pip dep** at all (restrictive Tencent community
+license — excludes EU/UK/South Korea including outputs). It is installed
+out-of-band, only on the render box, by
+`install/install_identity_render_ae.sh` (git checkout + `pip install -e` +
+weight pre-download); the code only reaches `hy3dgen` lazily inside a running
+mesh job. Same for torch, trimesh, and Blender.
+
+## Compat shims
+
+The old import paths keep working — the wheel ships thin `char360` and
+`identity_render` shim packages that re-export from their new homes:
+
+```python
+import char360                      # -> abstract_identity.char360
+from char360.pipeline import run_char360
+import identity_render              # -> abstract_identity.render
+from identity_render.jobstate import STAGE_DONE
+python -m char360.cli <video> -o <outdir>
+python -m identity_render.service   # old systemd ExecStart still boots
+```
+
+New code should import `abstract_identity.char360` / `abstract_identity.render`
+directly. The log-capture contract is unchanged: service log records still
+flow through the literal `"identity_render"` logger name.
+
+## Service API (summary)
+
+Every request, `/health` included, requires `X-Identity-Render-Token: <TOKEN>`
+(401 otherwise). Jobs run one at a time (single GPU, single worker thread).
+
+| Method | Path | What |
+|---|---|---|
+| GET | `/health` | Service + honest capability report |
+| POST | `/jobs` | Queue a job (`mesh_build`, `turntable`, `mesh_and_turntable`, `video_extract`, `video_characters_glb`); returns `202 {"job_id": ...}` |
+| GET | `/jobs/<job_id>` | `{job_id, status, error?, files?}` |
+| GET | `/jobs/<job_id>/files/<name>` | Fetch an artifact's bytes |
+| DELETE | `/jobs/<job_id>` | Best-effort cleanup of a job's files |
+
+Artifacts land under `$IDENTITY_RENDER_HOME/<job_id>/`; nothing is cleaned up
+automatically. Env vars (`IDENTITY_RENDER_TOKEN/PORT/HOME`, `BLENDER_BIN`,
+`FFMPEG_BIN`, `HUNYUAN3D_*`, `HF_HOME`, ...) are written to
+`~/identity-render/env` by the installer. Background removal
+(`mesh_params.remove_background`) is ON by default; originals are never
+modified.
+
+On ae: `systemctl --user status identity-render.service`,
+`journalctl --user -u identity-render.service -f`. Code-only update: re-run
+the installer (editable install — a restart alone picks up share changes),
+then `systemctl --user restart identity-render.service`.
+
+## char360 CLI
+
+```bash
+char360 <video> -o <outdir> [--stride 8] [--yolo yolov8m.pt] \
+    [--min-h-frac 0.15] [--cluster-dist 0.55] [--min-faces 4]
+```
+
+Output: `<outdir>/manifest.json` + `char_NN/view_MM_yaw±DDD.png` crops (bin 0
+frontal, 30° bins CCW; rear bins are `yaw_source=rear_inferred` via
+track-level identity propagation). Missing heavy deps fail loud at stage-run
+time with a `pip install` hint, never at import time.
+
+## Tests
+
+```bash
+python -m pytest tests/ -q     # or: python -m unittest discover tests
+```
+
+The suite never imports cv2/torch/insightface/sklearn/scenedetect — heavy
+stages are mocked — so it runs on a base install (plus numpy for the pipeline
+test's fixtures).
+
+## Publishing
+
+```bash
+cd py/abstract_identity
+python -m build          # sdist + wheel
+twine upload dist/*      # public PyPI
+```
+
+Order matters: publish `abstract_identity` **before** publishing
+`abstract_hugpy_dev` 0.1.234, which now base-depends on
+`abstract_identity>=0.1.0`. Version is single-sourced from
+`src/abstract_identity/__init__.py:__version__` — bump it there.

abstract_identity-0.1.0/README.md

@@ -0,0 +1,138 @@
+# abstract_identity
+
+Identity pipeline for hugpy, merged from the former standalone `char360` and
+`identity-render` dists into one src-layout package with two subpackages:
+
+| Subpackage | What it is |
+| --- | --- |
+| `abstract_identity.char360` | Video → per-character 360° view sets: scenes → person detect+track (YOLO) → face embed+pose (insightface) → identity cluster (agglomerative) → yaw-bin (12×30°) → best-per-bin crops + `manifest.json`. Library + CLI (`char360` console script / `python -m char360`). |
+| `abstract_identity.render` | The identity-render GPU service (`identity-render` console script): reference photos → Hunyuan3D-2mv mesh (+ headless-Blender turntable), plus the char360-powered `video_extract` and `video_characters_glb` job kinds, behind a tokened Flask job API on :9750. |
+
+## Install
+
+Base (any box — coordinator, dev VM, CI):
+
+```bash
+pip install abstract_identity
+```
+
+Base is deliberately thin and wheels-only: `flask` + `pydantic`, nothing else.
+Every module still imports cleanly with no heavy deps present — heavy imports
+are lazy, inside the stage/job that needs them — so the service can boot
+anywhere and honestly report capabilities as not-ready.
+
+ae render host (GPU box): run the installer instead of pip —
+
+```bash
+bash /srv/share/projects/hugpy/dev/py/abstract_identity/install/install_identity_render_ae.sh \
+  --token <TOKEN>
+```
+
+It is idempotent (safe to re-run), refuses to run without `--token` or as
+root, and sets up: CUDA torch, the Hunyuan3D-2 checkout + weights, rembg,
+portable Blender 4.2, the char360 heavy deps, an editable install of this
+package into the venv, and the `identity-render.service` systemd **user**
+unit (`ExecStart=venv/bin/python -m abstract_identity.render.service`). See
+the script header and its `PASS:`/`FAIL:`/`NOTE:` output for details. One-time
+firewall opening on ae (verified 2026-07-14):
+
+```bash
+sudo ufw allow from 192.168.1.0/24 to any port 9750 proto tcp comment 'identity-render (hugpy central relay)'
+```
+
+## Why the heavy deps are an extra, not base
+
+`pip install abstract_identity[render]` pulls the char360 detection stack:
+`scenedetect[opencv]`, `ultralytics`, `insightface`, `onnxruntime-gpu==1.18.1`,
+`opencv-python`, `numpy`, `scikit-learn`. They are not in base because they are
+
+- **heavy/native/CUDA** — pointless on a coordinator box, and
+- **restrictively licensed** — `ultralytics` is AGPL-3.0 (a deployed
+  combination is an AGPL combined work) and the insightface pretrained packs
+  (`buffalo_l`) are non-commercial research only. See the THIRD-PARTY
+  OBLIGATIONS NOTICE in `LICENSE` before any commercial use or redistribution.
+
+**Hunyuan3D-2 is never a pip dep** at all (restrictive Tencent community
+license — excludes EU/UK/South Korea including outputs). It is installed
+out-of-band, only on the render box, by
+`install/install_identity_render_ae.sh` (git checkout + `pip install -e` +
+weight pre-download); the code only reaches `hy3dgen` lazily inside a running
+mesh job. Same for torch, trimesh, and Blender.
+
+## Compat shims
+
+The old import paths keep working — the wheel ships thin `char360` and
+`identity_render` shim packages that re-export from their new homes:
+
+```python
+import char360                      # -> abstract_identity.char360
+from char360.pipeline import run_char360
+import identity_render              # -> abstract_identity.render
+from identity_render.jobstate import STAGE_DONE
+python -m char360.cli <video> -o <outdir>
+python -m identity_render.service   # old systemd ExecStart still boots
+```
+
+New code should import `abstract_identity.char360` / `abstract_identity.render`
+directly. The log-capture contract is unchanged: service log records still
+flow through the literal `"identity_render"` logger name.
+
+## Service API (summary)
+
+Every request, `/health` included, requires `X-Identity-Render-Token: <TOKEN>`
+(401 otherwise). Jobs run one at a time (single GPU, single worker thread).
+
+| Method | Path | What |
+|---|---|---|
+| GET | `/health` | Service + honest capability report |
+| POST | `/jobs` | Queue a job (`mesh_build`, `turntable`, `mesh_and_turntable`, `video_extract`, `video_characters_glb`); returns `202 {"job_id": ...}` |
+| GET | `/jobs/<job_id>` | `{job_id, status, error?, files?}` |
+| GET | `/jobs/<job_id>/files/<name>` | Fetch an artifact's bytes |
+| DELETE | `/jobs/<job_id>` | Best-effort cleanup of a job's files |
+
+Artifacts land under `$IDENTITY_RENDER_HOME/<job_id>/`; nothing is cleaned up
+automatically. Env vars (`IDENTITY_RENDER_TOKEN/PORT/HOME`, `BLENDER_BIN`,
+`FFMPEG_BIN`, `HUNYUAN3D_*`, `HF_HOME`, ...) are written to
+`~/identity-render/env` by the installer. Background removal
+(`mesh_params.remove_background`) is ON by default; originals are never
+modified.
+
+On ae: `systemctl --user status identity-render.service`,
+`journalctl --user -u identity-render.service -f`. Code-only update: re-run
+the installer (editable install — a restart alone picks up share changes),
+then `systemctl --user restart identity-render.service`.
+
+## char360 CLI
+
+```bash
+char360 <video> -o <outdir> [--stride 8] [--yolo yolov8m.pt] \
+    [--min-h-frac 0.15] [--cluster-dist 0.55] [--min-faces 4]
+```
+
+Output: `<outdir>/manifest.json` + `char_NN/view_MM_yaw±DDD.png` crops (bin 0
+frontal, 30° bins CCW; rear bins are `yaw_source=rear_inferred` via
+track-level identity propagation). Missing heavy deps fail loud at stage-run
+time with a `pip install` hint, never at import time.
+
+## Tests
+
+```bash
+python -m pytest tests/ -q     # or: python -m unittest discover tests
+```
+
+The suite never imports cv2/torch/insightface/sklearn/scenedetect — heavy
+stages are mocked — so it runs on a base install (plus numpy for the pipeline
+test's fixtures).
+
+## Publishing
+
+```bash
+cd py/abstract_identity
+python -m build          # sdist + wheel
+twine upload dist/*      # public PyPI
+```
+
+Order matters: publish `abstract_identity` **before** publishing
+`abstract_hugpy_dev` 0.1.234, which now base-depends on
+`abstract_identity>=0.1.0`. Version is single-sourced from
+`src/abstract_identity/__init__.py:__version__` — bump it there.

abstract_identity-0.1.0/pyproject.toml

@@ -0,0 +1,59 @@
+# abstract_identity — identity pipeline for hugpy (char360 + identity-render),
+# merged from the former standalone `char360` and `identity-render` dists.
+# Published to public PyPI as its own dist; abstract_hugpy_dev base-depends on it.
+
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "abstract_identity"
+# Single-sourced from src/abstract_identity/__init__.py:__version__ (read
+# statically by setuptools — see [tool.setuptools.dynamic] below). Bump it THERE.
+dynamic = ["version"]
+description = "Identity pipeline for hugpy: char360 (video -> character face detection/clustering/360-view selection) + render (identity-render GPU service: Hunyuan3D-2mv mesh, Blender turntable, video_extract, video_characters_glb)"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "putkoff" }]
+
+# Base = thin, wheels-only: enough to install, import everything, and boot the
+# service in honest not-ready mode. Every heavy/native/CUDA dep is imported
+# lazily inside the stage or job that needs it and lives in the [render] extra
+# (or is installed out-of-band by install/install_identity_render_ae.sh —
+# torch, hy3dgen/Hunyuan3D-2, trimesh, Blender are NEVER pip deps of this dist).
+dependencies = [
+    "flask>=3.0,<4.0",
+    "pydantic>=2.0,<3.0",
+]
+
+[project.optional-dependencies]
+# The char360 detection/clustering stack (GPU box). NOTE the licenses:
+# ultralytics is AGPL-3.0 and insightface's pretrained packs are
+# non-commercial — see LICENSE's THIRD-PARTY OBLIGATIONS NOTICE.
+# onnxruntime-gpu pin matches the cu12 torch builds the installer sets up;
+# on a cu11 box use 1.17.x, or plain onnxruntime for CPU-only.
+render = [
+    "scenedetect[opencv]",
+    "ultralytics",
+    "insightface",
+    "onnxruntime-gpu==1.18.1",
+    "opencv-python",
+    "numpy",
+    "scikit-learn",
+]
+
+[project.scripts]
+char360 = "abstract_identity.char360.cli:main"
+identity-render = "abstract_identity.render.service:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+# char360* and identity_render* are thin compat shims so old import paths
+# (`import char360`, `python -m identity_render.service`) keep working.
+include = ["abstract_identity*", "char360*", "identity_render*"]
+
+[tool.setuptools.dynamic]
+# Read statically (AST) out of __init__.py — the package is NOT imported at
+# build time, so this stays cheap and cannot fail on missing build-env deps.
+version = { attr = "abstract_identity.__version__" }

abstract_identity-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

abstract_identity-0.1.0/src/abstract_identity/__init__.py

@@ -0,0 +1,17 @@
+"""abstract_identity: identity pipeline for hugpy.
+
+Two subpackages, merged from the former standalone `char360` and
+`identity-render` dists:
+
+- :mod:`abstract_identity.char360` — video → per-character face
+  detection, identity clustering, and 360-degree view selection.
+- :mod:`abstract_identity.render` — the identity-render HTTP service
+  (tokened Flask job API): mesh (Hunyuan3D-2mv), turntable (headless
+  Blender), video_extract, and video_characters_glb job kinds.
+
+Heavy deps stay lazy: importing this package (and every submodule)
+needs only the base install; GPU/native stacks are imported inside the
+stage or job that uses them.
+"""
+
+__version__ = "0.1.0"

abstract_identity-0.1.0/src/abstract_identity/char360/__init__.py

@@ -0,0 +1,51 @@
+"""char360: extract per-character 360-degree view sets from a video.
+
+Pipeline: scenes -> person detect+track (YOLO/ultralytics) -> face
+embed+pose (insightface) -> identity cluster (sklearn agglomerative) ->
+yaw-bin (12x30 degrees) -> best-per-bin selection -> crops + manifest.json.
+
+Ported from the standalone ``char360_extract.py`` script into this
+modular package (S1 of the char360 feature plan). The algorithm — scoring,
+yaw-binning, and especially the track-level identity-propagation that
+harvests rear/back-of-head views — is unchanged; only the structure is
+new: each stage is its own module with an explicit typed input/output
+(:mod:`char360.stage_scenes`, :mod:`char360.stage_detect`,
+:mod:`char360.stage_faces`, :mod:`char360.stage_cluster`,
+:mod:`char360.stage_select`), and :func:`char360.pipeline.run_char360` is
+the one-shot orchestrator that runs them all with the script's original
+defaults.
+
+None of scenedetect/ultralytics/insightface/onnxruntime/scikit-learn/cv2
+are imported at package-import time -- every module here (including this
+one) is safe to import on a box with none of those installed. They are
+only imported inside the specific stage function that needs them (see
+each stage module's docstring), same discipline as
+``identity_render_service/identity_render`` and
+``abstract_hugpy_dev.phone_brick``: pure helpers stay dependency-light and
+unit-testable; heavy deps are paid for only by the box that actually runs
+an extraction, and only at the moment a stage runs, not at import time.
+
+This package is a library + CLI only -- no job-bus wrapper, no service
+plumbing. A later slice decides how it's consumed (worker-side runner vs.
+a standalone service in the vein of ``identity_render_service``); it does
+not decide that here.
+"""
+from .schemas import (
+    CharacterResult,
+    Char360Result,
+    Char360Spec,
+    Det,
+    FaceObs,
+    Pick,
+)
+
+__all__ = [
+    "CharacterResult",
+    "Char360Result",
+    "Char360Spec",
+    "Det",
+    "FaceObs",
+    "Pick",
+]
+
+__version__ = "0.1.0"

abstract_identity-0.1.0/src/abstract_identity/char360/cli.py

@@ -0,0 +1,58 @@
+"""``char360`` CLI — the original script's argparse UX, unchanged.
+
+Every flag, default, and help string here matches
+``char360_extract.py``'s ``main()`` exactly: ``video`` positional,
+``-o/--outdir`` required, ``--stride`` (default 8), ``--yolo`` (default
+"yolov8m.pt"), ``--min-h-frac`` (default 0.15), ``--cluster-dist``
+(default 0.55), ``--min-faces`` (default 4). Only the body changed: it now
+builds a :class:`char360.schemas.Char360Spec` and calls
+:func:`char360.pipeline.run_char360` instead of inlining the stage calls.
+
+This module imports only :mod:`char360.pipeline` (which itself defers all
+heavy deps), so ``python -m char360.cli --help`` works with none of
+scenedetect/ultralytics/insightface/sklearn/cv2/numpy installed — only
+actually running an extraction requires them.
+"""
+from __future__ import annotations
+
+import argparse
+
+from .pipeline import run_char360
+from .schemas import Char360Spec
+
+_DESCRIPTION = "extract per-character 360-degree view sets from a video."
+
+
+def build_parser() -> argparse.ArgumentParser:
+    ap = argparse.ArgumentParser(prog="char360", description=_DESCRIPTION)
+    ap.add_argument("video")
+    ap.add_argument("-o", "--outdir", required=True)
+    ap.add_argument("--stride", type=int, default=8, help="sample every Nth frame (default 8)")
+    ap.add_argument("--yolo", default="yolov8m.pt")
+    ap.add_argument("--min-h-frac", type=float, default=0.15,
+                     help="ignore persons shorter than this fraction of frame height")
+    ap.add_argument("--cluster-dist", type=float, default=0.55)
+    ap.add_argument("--min-faces", type=int, default=4,
+                     help="min face obs for a cluster to count as a character")
+    return ap
+
+
+def main(argv=None) -> int:
+    ap = build_parser()
+    args = ap.parse_args(argv)
+
+    spec = Char360Spec(
+        video=args.video,
+        outdir=args.outdir,
+        stride=args.stride,
+        yolo_model=args.yolo,
+        min_h_frac=args.min_h_frac,
+        cluster_dist=args.cluster_dist,
+        min_faces=args.min_faces,
+    )
+    run_char360(spec)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

abstract_identity-0.1.0/src/abstract_identity/char360/geometry.py

@@ -0,0 +1,66 @@
+"""Pure geometry/scoring helpers — no heavy deps at import time.
+
+``N_BINS``, ``BIN_DEG``, ``REAR_BINS``, ``yaw_to_bin``, and ``iou`` are
+stdlib-only (no numpy, no cv2) so they unit-test on any box, including one
+with none of char360's runtime deps installed. This is the module that S1's
+acceptance criterion — "import char360 cleanly with no heavy deps present"
+— hinges on most directly, so nothing here may gain a module-level
+``import numpy`` / ``import cv2``.
+
+``sharpness`` is the one exception: computing a Laplacian variance is
+inherently a cv2 operation on real pixel data, so it lazily imports cv2
+inside the function body (never at module scope) per the same discipline
+``phone_brick`` uses (see that package's ``analyze.py``/``detector.py``
+docstrings) — this module still *imports* cleanly without cv2 installed;
+only *calling* ``sharpness`` requires it.
+
+Ported verbatim from ``char360_extract.py``'s top-level constants and
+``iou``/``yaw_to_bin``/``sharpness`` functions — logic unchanged.
+"""
+from __future__ import annotations
+
+# ---------------------------------------------------------------------------
+# Bin geometry (parameterizable: change these two constants, nothing else,
+# to retune bin granularity — do not hardcode 12/30 elsewhere).
+# ---------------------------------------------------------------------------
+N_BINS = 12
+BIN_DEG = 360 // N_BINS          # 30
+REAR_BINS = (5, 6, 7)             # yaw ~ [135..225): back-left, back, back-right
+PERSON_CLS = 0                    # COCO person
+
+
+def yaw_to_bin(yaw: float) -> int:
+    """yaw in degrees, 0 = facing camera, positive = subject's left turn.
+
+    Bin 0 centered on 0; bins increase CCW. Pure arithmetic — verbatim from
+    the original script.
+    """
+    a = (yaw + BIN_DEG / 2) % 360
+    return int(a // BIN_DEG)
+
+
+def iou(a, b) -> float:
+    """Intersection-over-union of two ``(x1, y1, x2, y2)`` boxes.
+
+    Pure arithmetic — verbatim from the original script.
+    """
+    ix1, iy1 = max(a[0], b[0]), max(a[1], b[1])
+    ix2, iy2 = min(a[2], b[2]), min(a[3], b[3])
+    iw, ih = max(0, ix2 - ix1), max(0, iy2 - iy1)
+    inter = iw * ih
+    ua = (a[2] - a[0]) * (a[3] - a[1]) + (b[2] - b[0]) * (b[3] - b[1]) - inter
+    return inter / ua if ua > 0 else 0.0
+
+
+def sharpness(img) -> float:
+    """Laplacian-variance sharpness of an image (higher = sharper).
+
+    Lazily imports cv2 — this is the one geometry helper that cannot be
+    made pure (it operates on decoded pixel data), so it keeps the cv2 call
+    but defers the import to call time so *importing* this module never
+    requires cv2. Verbatim from the original script.
+    """
+    import cv2
+
+    g = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY)
+    return float(cv2.Laplacian(g, cv2.CV_64F).var())