v0.3.0

Physiotrack v0.3.0

This release adds face-part parsing to the segmentation subsystem and tidies the public API
so everything is reached through clean, hierarchical entry points.

✨ Added

• Face parsing via Segmentation.Face (SegFace). Dense face-part segmentation into 19
  CelebAMask-HQ classes (skin, eyes, brows, nose, lips, hair, ears, glasses, hat, earring,
  necklace, neck, cloth, ...). It runs on face crops and, like Pose auto-detecting people,
  auto-detects faces with a YOLO face detector when no boxes are passed:

  from physiotrack import Segmentation
  result = Segmentation.Face().predict(image)   # auto-detects faces
  seg_map = result.seg_map                       # (H, W) face-part class map
  labels  = result.names                         # class id -> label
  overlay = result.plot()                        # 19-class palette overlay

  Registered as Models.Segmentation.SegFace.Face.swinb_celeba_512. Only the inference code is
  vendored (Swin-Base/CelebA model + transformer/utils), under the upstream MIT license.
• New public exports so examples and user code never reach into internal module paths:
  • physiotrack: apply_3dpcnet_transform, reverse_3dpcnet_transform.
  • physiotrack.pose: COCO_WHOLEBODY_NAMES, HUMAN26M_NAMES.
  • physiotrack.signals: motion helpers (keypoint sequences, centroids, resampling, feature
    extraction) alongside the existing filters / normalization / rPPG / plotting exports.
• Result.palette so palette-based segmentation maps (e.g. face parsing) overlay with the
  correct per-class colours.
• examples/face_parsing.py — runnable SegFace example (auto-detect and explicit-box modes).
• Demo video linked from the README.

♻️ Changed

• Cleaner, hierarchical public API. README's "The Unified API" now includes a calling-hierarchy
  diagram showing the flat entry points, the model registry, the Result family, and the public
  subsystems (signals / pose / face).
• Examples import only from public entry points. evaluate_pose.py and motion.py no longer
  reach into physiotrack.modules.* or deep file paths; they import from physiotrack,
  physiotrack.pose, and physiotrack.signals.
• README architecture diagram, feature table, model registry, and project layout updated to
  include face parsing.

⚠️ Breaking

None.

🔁 Upgrading

No code changes required for existing usage. To use the new face parser:

from physiotrack import Segmentation
result = Segmentation.Face(device=0).predict(image)

📝 Notes

• The SegFace checkpoint (segface_swinb_celeba_512.pt, slimmed to inference-only weights) is in
  the HuggingFace weights repo and must be pushed for the registry download to work.
• All released canonicalizer/face-parsing checkpoints download on first use via the Models
  registry; no weights are bundled in the package.

---

Full documentation: see the README. License: GPL-3.0.