hifd 0.1.0__tar.gz

hifd-0.1.0/CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog
+
+All notable changes to `hifd` will be documented here. This project follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and adheres to
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] — 2026-05-23
+
+### Added
+- Initial release.
+- Per-task agreement primitives: `score_age`, `score_categorical`,
+  `score_landmark`, `score_gaze`, `score_bvp`, `score_hr`.
+- Privacy (`privacy_score`, `privacy_ensemble`) and quality (`quality_score`)
+  primitives, with batch variants for the scalar-input ones.
+- Utility levels `U1` / `U2` / `U3` and per-method aggregation.
+- Composite HiFD score (`composite`, `compose_profiles`) under three default
+  application profiles (Privacy-First, Balanced, Clinical).
+- JSON envelope IO (schema version `1.0`) with full validation.
+- High-level `run_pipeline` orchestrator producing per_sample / per_method /
+  composite CSVs plus a LaTeX-ready composite table.
+- `hifd` CLI: `validate`, `compute-agreements`, `aggregate`, `compose`,
+  `run-all`, `version`.
+- PEP 561 type information (`py.typed`).

hifd-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 InfraFace
+
+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.

hifd-0.1.0/PKG-INFO

@@ -0,0 +1,153 @@
+Metadata-Version: 2.4
+Name: hifd
+Version: 0.1.0
+Summary: HiFD: a holistic metric for face de-identification evaluation.
+Project-URL: Homepage, https://github.com/infraface/hifd
+Project-URL: Documentation, https://github.com/infraface/hifd#readme
+Project-URL: Issues, https://github.com/infraface/hifd/issues
+Project-URL: Source, https://github.com/infraface/hifd
+Author-email: Hui Wei <huiwei.truth@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2026 InfraFace
+        
+        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.
+License-File: LICENSE
+Keywords: benchmark,computer-vision,face-de-identification,metric,privacy
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Image Recognition
+Requires-Python: >=3.10
+Requires-Dist: numpy>=1.24
+Requires-Dist: pandas>=2.0
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: dev
+Requires-Dist: build>=1.0; extra == 'dev'
+Requires-Dist: mypy>=1.8; extra == 'dev'
+Requires-Dist: pytest-cov>=4.1; extra == 'dev'
+Requires-Dist: pytest>=7.4; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Requires-Dist: twine>=5.0; extra == 'dev'
+Requires-Dist: types-pyyaml>=6.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# hifd
+
+[![CI](https://github.com/infraface/hifd/actions/workflows/ci.yml/badge.svg)](https://github.com/infraface/hifd/actions/workflows/ci.yml)
+
+**HiFD** is a holistic metric for evaluating face de-identification methods.
+It combines privacy (face-recognition resistance), perceptual quality, and
+three levels of utility preservation (macro cues, fine-grained cues,
+physiological signals) into a single composite score.
+
+This package provides the **scoring core**: given JSON files of pre-computed
+estimator predictions on (a) original images and (b) de-identified outputs,
+`hifd` produces per-sample agreement scores, per-method utility levels,
+ensemble privacy, quality, and composite HiFD scores under three application
+profiles (Privacy-First, Balanced, Clinical).
+
+The package does **not** run the estimators themselves — you bring your own
+predictions in the [documented JSON schema](docs/schema.md).
+
+## Install
+
+```bash
+pip install hifd
+```
+
+Runtime requirements: Python ≥ 3.10, numpy, pandas, pyyaml.
+
+## Quickstart (CLI)
+
+```bash
+hifd run-all \
+    --methods    methods.yaml \
+    --estimators estimators.yaml \
+    --data-dir   predictions/ \
+    --out        scores/
+```
+
+Produces:
+
+```
+scores/
+├── per_sample/per_sample_agreements.csv
+├── per_method/per_method_aggregated.csv
+├── per_method/method_level.csv
+├── tables/composite.csv
+└── tables/composite.tex
+```
+
+## Quickstart (Python API)
+
+```python
+import hifd
+import numpy as np
+
+# Per-task primitives (scalar)
+hifd.score_age(35.0, 36.0)                 # 0.99
+hifd.score_gaze([0, 0, 1], [0, 0.1, 1])    # ≈ 0.937
+
+# Batch variants for scalar-input primitives
+hifd.batch_score_age(np.array([35.0]), np.array([36.0]))  # ndarray([0.99])
+# Also: batch_score_categorical, batch_score_hr, batch_privacy_score,
+# batch_quality_score, batch_U1, batch_U2, batch_U3
+# (Geometric primitives — score_landmark, score_gaze, score_bvp — have no
+# batch form because their inputs are per-sample variable-shape arrays.)
+
+# Composite under a profile
+hifd.composite(P=0.7, Q=0.8, U1=0.6, U2=0.5, U3=0.4,
+               weights=hifd.DEFAULT_PROFILES["balanced"])
+
+# Full pipeline
+r = hifd.run_pipeline(
+    methods_config="methods.yaml",
+    estimators_config="estimators.yaml",
+    data_dir="predictions/",
+    out_dir="scores/",
+)
+print(r.composite_df)
+```
+
+## Input format
+
+See [docs/schema.md](docs/schema.md) for the JSON envelope spec and one example
+per task type.
+
+## Defaults
+
+Constants and profiles ship as immutable mappings:
+
+```python
+hifd.DEFAULT_CONSTANTS["tau_HR"]            # 20.0
+hifd.DEFAULT_PROFILES["balanced"]           # {"P": 0.2, "Q": 0.2, "U1": 0.2, ...}
+```
+
+To override, build a plain dict and pass it (`run_pipeline(constants=...)`) or
+provide `--constants my.yaml` on the CLI.
+
+## Citation
+
+If you use HiFD in published work, please cite the paper [TBD].

hifd-0.1.0/README.md

@@ -0,0 +1,98 @@
+# hifd
+
+[![CI](https://github.com/infraface/hifd/actions/workflows/ci.yml/badge.svg)](https://github.com/infraface/hifd/actions/workflows/ci.yml)
+
+**HiFD** is a holistic metric for evaluating face de-identification methods.
+It combines privacy (face-recognition resistance), perceptual quality, and
+three levels of utility preservation (macro cues, fine-grained cues,
+physiological signals) into a single composite score.
+
+This package provides the **scoring core**: given JSON files of pre-computed
+estimator predictions on (a) original images and (b) de-identified outputs,
+`hifd` produces per-sample agreement scores, per-method utility levels,
+ensemble privacy, quality, and composite HiFD scores under three application
+profiles (Privacy-First, Balanced, Clinical).
+
+The package does **not** run the estimators themselves — you bring your own
+predictions in the [documented JSON schema](docs/schema.md).
+
+## Install
+
+```bash
+pip install hifd
+```
+
+Runtime requirements: Python ≥ 3.10, numpy, pandas, pyyaml.
+
+## Quickstart (CLI)
+
+```bash
+hifd run-all \
+    --methods    methods.yaml \
+    --estimators estimators.yaml \
+    --data-dir   predictions/ \
+    --out        scores/
+```
+
+Produces:
+
+```
+scores/
+├── per_sample/per_sample_agreements.csv
+├── per_method/per_method_aggregated.csv
+├── per_method/method_level.csv
+├── tables/composite.csv
+└── tables/composite.tex
+```
+
+## Quickstart (Python API)
+
+```python
+import hifd
+import numpy as np
+
+# Per-task primitives (scalar)
+hifd.score_age(35.0, 36.0)                 # 0.99
+hifd.score_gaze([0, 0, 1], [0, 0.1, 1])    # ≈ 0.937
+
+# Batch variants for scalar-input primitives
+hifd.batch_score_age(np.array([35.0]), np.array([36.0]))  # ndarray([0.99])
+# Also: batch_score_categorical, batch_score_hr, batch_privacy_score,
+# batch_quality_score, batch_U1, batch_U2, batch_U3
+# (Geometric primitives — score_landmark, score_gaze, score_bvp — have no
+# batch form because their inputs are per-sample variable-shape arrays.)
+
+# Composite under a profile
+hifd.composite(P=0.7, Q=0.8, U1=0.6, U2=0.5, U3=0.4,
+               weights=hifd.DEFAULT_PROFILES["balanced"])
+
+# Full pipeline
+r = hifd.run_pipeline(
+    methods_config="methods.yaml",
+    estimators_config="estimators.yaml",
+    data_dir="predictions/",
+    out_dir="scores/",
+)
+print(r.composite_df)
+```
+
+## Input format
+
+See [docs/schema.md](docs/schema.md) for the JSON envelope spec and one example
+per task type.
+
+## Defaults
+
+Constants and profiles ship as immutable mappings:
+
+```python
+hifd.DEFAULT_CONSTANTS["tau_HR"]            # 20.0
+hifd.DEFAULT_PROFILES["balanced"]           # {"P": 0.2, "Q": 0.2, "U1": 0.2, ...}
+```
+
+To override, build a plain dict and pass it (`run_pipeline(constants=...)`) or
+provide `--constants my.yaml` on the CLI.
+
+## Citation
+
+If you use HiFD in published work, please cite the paper [TBD].

hifd-0.1.0/docs/schema.md

@@ -0,0 +1,122 @@
+# JSON envelope (schema version 1.0)
+
+Every prediction file is a JSON object with this envelope:
+
+```json
+{
+  "task":           "age",
+  "source":         "original",
+  "estimator":      "mivolo",
+  "schema_version": "1.0",
+  "predictions":    { "<sample_id>": { ... }, ... }
+}
+```
+
+- `task` — one of: `age`, `gender`, `ethnicity`, `macro_exp`, `micro_exp`,
+  `landmark`, `gaze`, `rppg`, `face_embedding`, `niqe`.
+- `source` — `original` for the un-modified images, `deid` for the
+  de-identified outputs.
+- `estimator` — a free-form string identifying the model.
+- `schema_version` — must be exactly `"1.0"` for this release.
+- `predictions` — a dict mapping sample IDs to task-specific payloads (below).
+
+Categorical tasks also require a top-level `class_names: [...]` list whose
+order matches the per-sample `probs` arrays. rPPG files may include a top-level
+`fps` integer.
+
+## Per-task payloads
+
+### `age`
+
+```json
+{"value": 32.5}
+```
+
+### `gender` / `ethnicity` / `macro_exp` / `micro_exp`
+
+```json
+{"probs": [0.92, 0.08]}
+```
+
+`probs` must sum to ~1 (off by < 1e-4 is auto-renormalized with a warning);
+length must equal the envelope's `class_names`.
+
+### `landmark`
+
+```json
+{
+  "points": [[10.0, 20.0], [30.0, 40.0], ...],
+  "left_eye_center":  [45.0, 50.0],
+  "right_eye_center": [75.0, 50.0]
+}
+```
+
+Original and de-id must have the same number of points per sample.
+
+### `gaze`
+
+```json
+{"direction": [0.0, 0.0, 1.0]}
+```
+
+A 3-vector. Normalization is applied internally; magnitude doesn't matter.
+
+### `rppg`
+
+```json
+{"bvp": [0.1, 0.2, ...], "hr_bpm": 72.0, "fps": 30}
+```
+
+`fps` may also be set at the envelope top-level. Original and de-id must
+match `fps`; BVP lengths may differ by up to 1 second.
+
+### `face_embedding`
+
+```json
+{"embedding": [0.013, -0.241, ...]}
+```
+
+D-dimensional vector. Normalization is applied internally.
+
+### `niqe`
+
+```json
+{"niqe": 3.42}
+```
+
+NIQE is no-reference, so only the de-id file is read.
+
+## Multiple estimators per task
+
+Tasks may have several estimator JSONs (e.g. `face_embedding` typically has
+`arcface_*`, `cosface_*`, `adaface_*`). They are listed in
+`estimators.yaml`:
+
+```yaml
+tasks:
+  face_embedding:
+    estimators:
+      - name: arcface
+        orig_json: face_embedding/arcface_orig.json
+        deid_json: face_embedding/arcface_deid.json
+      - name: cosface
+        orig_json: face_embedding/cosface_orig.json
+        deid_json: face_embedding/cosface_deid.json
+```
+
+## methods.yaml
+
+```yaml
+original:
+  base_path: utilface
+methods:
+  - name: MyMethod
+    base_path: methods/MyMethod
+```
+
+Paths are relative to `--data-dir`.
+
+## Compatibility
+
+A loader that sees a `schema_version` other than `"1.0"` raises `ValueError`.
+Bumping the schema is a major-version event.

hifd-0.1.0/pyproject.toml

@@ -0,0 +1,75 @@
+[build-system]
+requires = ["hatchling>=1.21"]
+build-backend = "hatchling.build"
+
+[project]
+name = "hifd"
+version = "0.1.0"
+description = "HiFD: a holistic metric for face de-identification evaluation."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { file = "LICENSE" }
+authors = [{ name = "Hui Wei", email = "huiwei.truth@gmail.com" }]
+keywords = ["face-de-identification", "privacy", "metric", "benchmark", "computer-vision"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Image Recognition",
+]
+
+dependencies = [
+    "numpy>=1.24",
+    "pandas>=2.0",
+    "pyyaml>=6.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.4",
+    "pytest-cov>=4.1",
+    "mypy>=1.8",
+    "ruff>=0.5",
+    "types-PyYAML>=6.0",
+    "build>=1.0",
+    "twine>=5.0",
+]
+
+[project.scripts]
+hifd = "hifd.cli:main"
+
+[project.urls]
+Homepage      = "https://github.com/infraface/hifd"
+Documentation = "https://github.com/infraface/hifd#readme"
+Issues        = "https://github.com/infraface/hifd/issues"
+Source        = "https://github.com/infraface/hifd"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/hifd"]
+
+[tool.hatch.build.targets.wheel.force-include]
+"src/hifd/py.typed" = "hifd/py.typed"
+
+[tool.hatch.build.targets.sdist]
+include = ["src/hifd", "tests", "README.md", "LICENSE", "CHANGELOG.md", "docs"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-ra --strict-markers"
+
+[tool.ruff]
+target-version = "py310"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "B", "UP", "SIM", "RUF"]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+files = ["src/hifd"]

hifd-0.1.0/src/hifd/__init__.py

@@ -0,0 +1,77 @@
+"""HiFD: a holistic metric for face de-identification evaluation."""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"
+
+from .aggregation import (
+    U1,
+    U2,
+    U3,
+    aggregate_method_scores,
+    batch_U1,
+    batch_U2,
+    batch_U3,
+)
+from .composite import compose_profiles, composite, load_profiles_yaml
+from .constants import DEFAULT_CONSTANTS, DEFAULT_PROFILES, SCHEMA_VERSION
+from .io import load_pair, load_predictions, validate_pair
+from .pipeline import (
+    PipelineResult,
+    aggregate,
+    compose,
+    compute_agreements,
+    run_pipeline,
+)
+from .scores.agreement import (
+    batch_score_age,
+    batch_score_categorical,
+    batch_score_hr,
+    score_age,
+    score_bvp,
+    score_categorical,
+    score_gaze,
+    score_hr,
+    score_landmark,
+)
+from .scores.privacy import batch_privacy_score, privacy_ensemble, privacy_score
+from .scores.quality import batch_quality_score, quality_score
+
+__all__ = [
+    "DEFAULT_CONSTANTS",
+    "DEFAULT_PROFILES",
+    "SCHEMA_VERSION",
+    "U1",
+    "U2",
+    "U3",
+    "PipelineResult",
+    "__version__",
+    "aggregate",
+    "aggregate_method_scores",
+    "batch_U1",
+    "batch_U2",
+    "batch_U3",
+    "batch_privacy_score",
+    "batch_quality_score",
+    "batch_score_age",
+    "batch_score_categorical",
+    "batch_score_hr",
+    "compose",
+    "compose_profiles",
+    "composite",
+    "compute_agreements",
+    "load_pair",
+    "load_predictions",
+    "load_profiles_yaml",
+    "privacy_ensemble",
+    "privacy_score",
+    "quality_score",
+    "run_pipeline",
+    "score_age",
+    "score_bvp",
+    "score_categorical",
+    "score_gaze",
+    "score_hr",
+    "score_landmark",
+    "validate_pair",
+]

hifd-0.1.0/src/hifd/aggregation.py

@@ -0,0 +1,87 @@
+"""Utility-level aggregation: per-sample U1/U2/U3 and per-method aggregation."""
+
+from __future__ import annotations
+
+from typing import Any, cast
+
+import numpy as np
+import pandas as pd  # type: ignore[import-untyped]
+from numpy.typing import NDArray
+
+# ----- 5.1 Per-sample level scores -------------------------------------------
+
+def U1(s_age: float, s_gender: float, s_eth: float, s_macro: float, s_lmk: float) -> float:
+    return float(np.mean([s_age, s_gender, s_eth, s_macro, s_lmk]))
+
+
+def U2(s_gaze: float, s_me: float | None = None) -> float:
+    if s_me is not None:
+        return 0.5 * (s_gaze + s_me)
+    return s_gaze
+
+
+def U3(bvp_scores: list[float], hr_scores: list[float]) -> float:
+    per_est = 0.5 * (np.asarray(bvp_scores) + np.asarray(hr_scores))
+    return float(np.mean(per_est))
+
+
+# ----- Vectorized versions ---------------------------------------------------
+
+def batch_U1(
+    s_age: NDArray[np.floating[Any]],
+    s_gender: NDArray[np.floating[Any]],
+    s_eth: NDArray[np.floating[Any]],
+    s_macro: NDArray[np.floating[Any]],
+    s_lmk: NDArray[np.floating[Any]],
+) -> NDArray[np.floating[Any]]:
+    return cast(
+        NDArray[np.floating[Any]],
+        np.mean(np.stack([s_age, s_gender, s_eth, s_macro, s_lmk], axis=0), axis=0),
+    )
+
+
+def batch_U2(
+    s_gaze: NDArray[np.floating[Any]], s_me: NDArray[np.floating[Any]] | None = None
+) -> NDArray[np.floating[Any]]:
+    if s_me is not None:
+        return cast(NDArray[np.floating[Any]], 0.5 * (s_gaze + s_me))
+    return cast(NDArray[np.floating[Any]], np.copy(s_gaze))
+
+
+def batch_U3(
+    bvp_per_est: list[NDArray[np.floating[Any]]],
+    hr_per_est: list[NDArray[np.floating[Any]]],
+) -> NDArray[np.floating[Any]]:
+    combined = [0.5 * (b + h) for b, h in zip(bvp_per_est, hr_per_est, strict=False)]
+    return cast(
+        NDArray[np.floating[Any]], np.mean(np.stack(combined, axis=0), axis=0)
+    )
+
+
+# ----- 5.2 Per-method aggregation --------------------------------------------
+
+_DIMENSION_MAP = {
+    "age": "L1", "gender": "L1", "ethnicity": "L1", "macro_exp": "L1", "landmark": "L1",
+    "gaze": "L2", "micro_exp": "L2",
+    "bvp": "L3", "hr": "L3",
+    "P": "Privacy", "Q": "Quality",
+    "U1": "L1", "U2": "L2", "U3": "L3",
+}
+
+
+def aggregate_method_scores(
+    per_sample: dict[str, NDArray[np.floating[Any]]], method_name: str
+) -> pd.DataFrame:
+    """Aggregate per-sample arrays into a method-level dataframe."""
+    rows = [
+        {
+            "method": method_name,
+            "dimension": _DIMENSION_MAP.get(name, "Other"),
+            "sub_score": name,
+            "value": float(np.mean(arr)),
+            "n_samples": len(arr),
+            "std": float(np.std(arr)),
+        }
+        for name, arr in per_sample.items()
+    ]
+    return pd.DataFrame(rows)