abstract_identity

Identity pipeline for hugpy, merged from the former standalone char360 and identity-render dists into one src-layout package with two subpackages:

Install

Base (any box — coordinator, dev VM, CI):

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.

Optional render dependencies can be installed with:

python -m pip install 'abstract_identity[render]'

Model weights and GPU/native runtimes need their own compatible installation. The optional extra alone does not establish renderer readiness. See the third-party notices in LICENSE and the package's installer scripts before redistributing model assets or native components.

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.

Import paths and commands

Use abstract_identity.char360 and abstract_identity.render directly:

from abstract_identity.char360.pipeline import run_char360
from abstract_identity.render.jobstate import STAGE_DONE

python -m abstract_identity.char360.cli <video> -o <outdir>
python -m abstract_identity.render.service

The char360 and identity-render console scripts remain available. Service log records flow through the "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).

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

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

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).

Source organization

abstract_identity/imports owns the shared boundary, following hugpy-discovery:

• init_imports.py declares standard-library, external, and internal package imports. Symbols resolve on request; optional GPU imports stay inside the jobs that use them.
• constants.py owns fixed pipeline/service constants and environment defaults.
• functions/ owns general file utilities and service configuration reading.

Section modules import dependencies through that boundary. Geometry/scoring, character extraction stages, rendering, and job state remain in their respective sections. Queues, locks, backend instances, and active job state remain with their owning service modules. Service settings are read at boot rather than when the boundary is imported.

Blender executes its scripts by file path in a separate Python environment. Their small sys/pathlib bootstrap exposes the source package before resolving all remaining imports through the boundary.