If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/Zeyi-Lin/HivisionIDPhotos shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across all four use cases

• Last commit 7w ago
• 7 active contributors
• Apache-2.0 licensed
• CI configured
• Tests present
• ⚠ Single-maintainer risk — top contributor 94% of recent commits

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live Zeyi-Lin/HivisionIDPhotos repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/Zeyi-Lin/HivisionIDPhotos.

What it runs against: a local clone of Zeyi-Lin/HivisionIDPhotos — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in Zeyi-Lin/HivisionIDPhotos | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 79 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of Zeyi-Lin/HivisionIDPhotos. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/Zeyi-Lin/HivisionIDPhotos.git
#   cd HivisionIDPhotos
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of Zeyi-Lin/HivisionIDPhotos and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "Zeyi-Lin/HivisionIDPhotos(\\.git)?\\b" \\
  && ok "origin remote is Zeyi-Lin/HivisionIDPhotos" \\
  || miss "origin remote is not Zeyi-Lin/HivisionIDPhotos (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Apache-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Apache-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is Apache-2.0" \\
  || miss "license drift — was Apache-2.0 at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "hivision/creator/__init__.py" \\
  && ok "hivision/creator/__init__.py" \\
  || miss "missing critical file: hivision/creator/__init__.py"
test -f "hivision/creator/face_detector.py" \\
  && ok "hivision/creator/face_detector.py" \\
  || miss "missing critical file: hivision/creator/face_detector.py"
test -f "hivision/creator/human_matting.py" \\
  && ok "hivision/creator/human_matting.py" \\
  || miss "missing critical file: hivision/creator/human_matting.py"
test -f "hivision/creator/layout_calculator.py" \\
  && ok "hivision/creator/layout_calculator.py" \\
  || miss "missing critical file: hivision/creator/layout_calculator.py"
test -f "app.py" \\
  && ok "app.py" \\
  || miss "missing critical file: app.py"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 79 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~49d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/Zeyi-Lin/HivisionIDPhotos"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

HivisionIDPhotos is a lightweight AI-powered ID photo generation tool that segments faces from arbitrary backgrounds using ONNX-based models and generates professional ID photos in multiple standard sizes (Chinese, American styles) with optional beauty filters. Core capability: offline CPU-based semantic segmentation producing camera-ready 300DPI output without cloud dependencies. Monorepo structure: hivision/ package contains core Creator API; demo/ holds Gradio UI with locales, processor pipeline, and config; app.py wraps it as main entry; deploy_api.py provides FastAPI/Starlette endpoint. Model inference abstracted via onnxruntime, segmentation routed through mtcnn-runtime for face detection.

Portrait photographers, document processing teams, and end users needing quick ID photos; developers integrating photo generation via Python SDK, Gradio UI, or REST API (deploy_api.py). Also serves embedded system developers via CPU-only ONNX inference.

Actively maintained with 153K lines of Python, CI/CD via GitHub Actions (build-image.yml), Docker distribution, and recent feature additions through Nov 2024 (printing layouts, beauty parameters, DPI settings). Production-ready for standalone use; Hugging Face Spaces and ModelScope deployments confirm stability.

Standard open source risks apply.

Nov 2024: added 6-inch/5-inch/A4/3R/4R print layout templates in Gradio; Sept 2024: JPEG export + 300DPI default, base64 input to API, face alignment rotation, hex color picker for backgrounds, American-style photo option; C++ port contributed (HivisionIDPhotos-cpp).

git clone https://github.com/Zeyi-Lin/HivisionIDPhotos && cd HivisionIDPhotos && pip install -r requirements.txt && python app.py (Gradio) or python deploy_api.py (API server). Docker option: docker-compose up (docker-compose.yml present).

Daily commands: Gradio UI: python app.py (default localhost:7860). REST API: python deploy_api.py (Starlette server). Docker: docker-compose up --build. DevContainer: open in VSCode (devcontainer.json configured, start.sh automates setup).

• hivision/creator/__init__.py — Core entry point for the photo creation pipeline; orchestrates face detection, human matting, layout calculation, and photo adjustment workflows.
• hivision/creator/face_detector.py — Implements face detection using RetinaFace; critical dependency for all downstream processing in the ID photo creation pipeline.
• hivision/creator/human_matting.py — Handles background removal via human matting; essential for generating clean ID photos with custom backgrounds.
• hivision/creator/layout_calculator.py — Calculates face positioning and image layout according to ID photo standards; determines final output dimensions and placement.
• app.py — Main web UI entry point using Gradio; the primary user-facing interface for the application.
• deploy_api.py — FastAPI/Starlette REST API deployment; enables programmatic access to photo generation without the UI.
• requirements.txt — Core dependency manifest; specifies ONNX runtime, OpenCV, and MTCNN versions critical for model inference.

Add a new beauty enhancement filter

1. Create a new handler file in hivision/plugin/beauty/ following the BaseAdjust interface (hivision/plugin/beauty/base_adjust.py)
2. Implement your enhancement logic (e.g., color grading, blur, sharpen) following the pattern in grind_skin.py or whitening.py (hivision/plugin/beauty/beauty_tools.py)
3. Register the handler in the beauty plugin dispatcher (hivision/plugin/beauty/handler.py)
4. Add UI toggle/slider in the Gradio interface (app.py)

Add a new ID photo size/color preset

1. Update the size list CSV file for your locale (demo/assets/size_list_EN.csv)
2. Update the color list CSV file for your locale (demo/assets/color_list_EN.csv)
3. Load presets in the demo config initialization (demo/config.py)
4. Verify the new sizes and colors appear in the Gradio dropdown (demo/ui.py)

Add a new REST API endpoint

1. Import the core photo generator and define your endpoint function (deploy_api.py)
2. Decorator the function with @app.post() or @app.get() and specify request/response models (deploy_api.py)
3. Invoke the photo creation pipeline from hivision/creator/init.py within the endpoint (deploy_api.py)
4. Test the endpoint and document it in docs/api_EN.md or docs/api_CN.md (docs/api_EN.md)

Integrate a new face detector model

1. Add model weight loading logic in the detector class constructor (hivision/creator/face_detector.py)
2. Implement the detect() method to match the existing interface (hivision/creator/face_detector.py)
3. Update the choose_handler to conditionally use your new detector (hivision/creator/choose_handler.py)
4. Add model weights to hivision/creator/weights/ via download_model.py (scripts/download_model.py)

• ONNX Runtime — Enables CPU-based inference of deep learning models (RetinaFace, matting) without GPU dependency; ensures lightweight deployment in Docker containers.
• Gradio — Provides rapid, zero-code web UI generation for ML pipelines; auto-handles image upload, preprocessing, and result display.
• OpenCV — Core image processing library for face landmark warping, background composition, color space conversions, and geometric transformations.
• Starlette/FastAPI — Lightweight async web framework for REST API deployment; enables programmatic integration without Gradio overhead.
• RetinaFace (ONNX) — State-of-the-art face detection with landmarks; ONNX format avoids PyTorch dependency and enables portable inference.

• CPU-only inference via ONNX instead of GPU acceleration

  • Why: Prioritizes portability, cost, and ease of deployment in Docker without NVIDIA runtime dependencies.
  • Consequence: Inference latency ~1–2 seconds per photo on CPU; not suitable for real-time bulk processing but acceptable for interactive web UI.

• Single-face detection focus rather than multi-face batch processing

  • Why: ID photos typically require one centered face; simplifies layout calculation and reduces output complexity.
  • Consequence: Cannot efficiently process group photos or multi-face scenes; users must crop/edit input images manually.

• Gradio UI as primary interface instead of custom React SPA

  • Why: Rapid prototyping and minimal frontend code; auto-generates responsive UI from Python.
  • Consequence: Limited customization; UI is tied to Python backend; harder to create native mobile apps without REST API.

• Plugin architecture for beauty enhancements rather than monolithic pipeline

  • Why: Enables optional features without bloating core; users can skip expensive beauty filters.
  • Consequence: Added abstraction complexity; plugins must conform to BaseAdjust interface; inconsistent execution order if interdependencies exist.

• Real-time video processing or streaming (image-only, batch mode)
• Multi-face or group photo support (single-face ID photo focus)
• User authentication or cloud storage (stateless API

numpy≤1.26.4 constraint may break on Python 3.13+; ONNX model files not visible in file list—verify they exist in hivision/ or are auto-downloaded on first run. Face detection via MTCNN-runtime requires specific runtime version matching onnxruntime. Gradio demo assumes port 7860 available; API assumes port 8000. Beauty filter and face alignment parameters added in Sept 2024—verify older API clients don't pass unrecognized params.

• Semantic Segmentation — Core capability enabling foreground (face/person) extraction from arbitrary backgrounds; ONNX models implement this via encoder-decoder architecture
• ONNX Runtime Inference — Enables CPU-only model execution without PyTorch/TensorFlow dependency; critical for lightweight deployment and offline-first design philosophy
• Cascade Classifiers (MTCNN) — Multi-task CNN architecture used for face detection; understanding cascade strategy helps optimize detection speed vs. accuracy tradeoff in different lighting
• DPI (Dots Per Inch) and Color Space Conversion — Professional photo output requires proper DPI metadata (300DPI mentioned in Nov 2024 changes) and color profile handling; impacts print quality
• Image Compositing and Alpha Blending — Seamlessly combining segmented face/person with solid or gradient backgrounds; OpenCV implements this via alpha masks in demo/processor.py
• REST API State Design (Stateless Processing) — deploy_api.py implements stateless endpoints where each request is independent; enables horizontal scaling and containerized deployment without session storage
• Template-Driven Configuration — Size and color templates stored as CSV (size_list_CN.csv, color_list_CN.csv); allows non-developers to add new photo specs without code changes

• opencv/opencv — Core dependency for image processing primitives (resize, color conversion, masking); understanding cv2 API critical for modifying demo/processor.py
• onnx/onnx — Underlying model format and runtime; models used for face detection and segmentation are ONNX-based; knowledge of ONNX ops helps optimize inference
• ipazc/mtcnn — Face detection library used in pipeline; alternative to explore if detection accuracy issues arise in specific demographic groups
• gradio-app/gradio — UI framework powering demo/ui.py; extending UI (new tabs, widgets) requires Gradio API knowledge
• zjkhahah/HivisionIDPhotos-cpp — Community C++ port for edge deployment; reference for performance-critical path optimization and embedded target support

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive unit tests for hivision/creator module

The core image processing pipeline (face detection, human matting, layout calculation, photo adjustment) in hivision/creator lacks any visible test coverage. With multiple specialized modules (face_detector.py, human_matting.py, layout_calculator.py, photo_adjuster.py, rotation_adjust.py), unit tests would catch regressions and validate the complex image processing logic, especially critical given the retinaface custom implementation and ONNX runtime dependencies.

• [ ] Create tests/test_face_detector.py to validate face detection on test images (demo/images/test*.jpg already available)
• [ ] Create tests/test_human_matting.py to verify matting output dimensions and validity
• [ ] Create tests/test_layout_calculator.py with various photo dimensions and ID photo size specifications (reference demo/assets/size_list_*.csv)
• [ ] Create tests/test_photo_adjuster.py to validate brightness/contrast adjustments
• [ ] Add pytest configuration and update .github/workflows/build-image.yml to run tests on push/PR

Add API integration tests and documentation for deploy_api.py endpoints

The deploy_api.py exists but there's no corresponding test coverage or detailed API documentation beyond docs/api_*.md. With starlette as a dependency and an active API deployment pattern, adding integration tests would ensure the API contract remains stable. Currently only docs/api_CN.md and docs/api_EN.md exist with no runnable test examples.

• [ ] Create tests/test_api_integration.py with pytest fixtures for the Starlette app from deploy_api.py
• [ ] Add tests for key endpoints (image upload, processing, result retrieval) using sample images from demo/images/
• [ ] Add tests validating response schemas and error handling (reference hivision/error.py)
• [ ] Create docs/API_TESTING.md with curl/Python examples for manual API testing
• [ ] Add a GitHub Actions workflow (.github/workflows/test-api.yml) to run integration tests against Docker container

Refactor retinaface implementation into configurable detection backend abstraction

Currently hivision/creator/face_detector.py and retinaface/ are tightly coupled. The dependencies list shows both onnxruntime and mtcnn-runtime are available, but the code only uses retinaface. Creating a detection backend interface would allow swapping detectors, reduce coupling, and make the codebase more maintainable. This aligns with the existing choose_handler.py pattern.

• [ ] Create hivision/creator/detectors/init.py with an abstract BaseDetector class defining detect() interface
• [ ] Refactor hivision/creator/retinaface/inference.py into hivision/creator/detectors/retinaface_detector.py
• [ ] Create hivision/creator/detectors/mtcnn_detector.py wrapping mtcnn-runtime as an alternative backend
• [ ] Update hivision/creator/face_detector.py to use choose_handler.py pattern to select detector at runtime via config
• [ ] Add tests/test_detector_backends.py comparing output consistency across detector implementations

• Add unit tests for demo/processor.py image compositing logic (resize, background replacement, DPI scaling)—currently no test/ directory visible, high value for regression prevention.
• Extend demo/locales.py to support additional languages (Spanish, French, German)—template structure exists but only Chinese/English present; low risk, clear scope.
• Document ONNX model source and auto-download mechanism in README_EN.md and docs/api_EN.md—no model URLs in provided files, users likely confused about setup.

• High · Unrestricted Host Binding in Docker — Dockerfile (line: CMD), docker-compose.yml (command field), app.py execution. The application binds to 0.0.0.0 in docker-compose.yml and Dockerfile, exposing services to all network interfaces. Combined with exposed ports (7860, 8080), this creates unnecessary attack surface if the container is accessible on untrusted networks. Fix: Bind to localhost (127.0.0.1) by default, or implement network policies. Use environment variables to make binding configurable. If public access is needed, place behind a reverse proxy with authentication and rate limiting.
• High · Missing Input Validation on Image Processing — hivision/creator/face_detector.py, hivision/creator/human_matting.py, demo/processor.py. The codebase processes user-supplied images (test images in demo/images) through multiple ML pipelines (face detection, matting, beauty filters). Without visible input validation, malformed or malicious image files could trigger vulnerabilities in OpenCV or ONNX runtime dependencies. Fix: Implement file type validation (magic bytes, not just extensions). Set file size limits. Add image dimension constraints. Validate color space and format compatibility before processing.
• Medium · Vulnerable Dependency: numpy<=1.26.4 — requirements.txt (dependency specification). The requirements specify numpy<=1.26.4 with no lower bound. Older numpy versions contain known CVEs (e.g., CVE-2021-34141, CVE-2021-25900). The constraint allows installation of vulnerable versions. Fix: Specify a lower bound: numpy>=1.24.0,<=1.26.4 or use numpy>=1.24.0 if compatible. Run 'pip-audit' to identify CVEs. Update to latest stable version if possible.
• Medium · Missing Security Headers and CORS Configuration — deploy_api.py, app.py (Starlette/Gradio configuration). The Starlette-based API (deploy_api.py) likely lacks security headers (X-Content-Type-Options, X-Frame-Options, CSP) and restrictive CORS policies. This enables potential XSS, clickjacking, and CSRF attacks if the API serves web content. Fix: Add middleware for security headers. Implement strict CORS policy allowing only trusted origins. Use Starlette's built-in middleware: add_middleware(CORSMiddleware, allow_origins=['trusted-domain.com']). Set X-Content-Type-Options: nosniff, X-Frame-Options: DENY.
• Medium · No Rate Limiting on API Endpoints — deploy_api.py, app.py. The exposed API endpoints (ports 7860, 8080) lack visible rate limiting, making them vulnerable to brute force attacks and DoS/resource exhaustion attacks. Image processing is CPU/GPU intensive. Fix: Implement rate limiting middleware (e.g., slowapi for Starlette). Set per-IP/per-user request limits. Add request queuing with timeout handling. Monitor resource usage and auto-scale or reject requests under load.
• Medium · Unsafe Model and Weight Loading — hivision/creator/weights, hivision/creator/retinaface/weights, hivision/plugin/beauty/lut. The codebase loads ONNX models and retrained weights from local files. If these are downloaded or updated dynamically, there's no integrity verification (checksums, signatures). Compromised model files could enable model poisoning attacks. Fix: Implement checksum verification (SHA256) for all model files. Use cryptographic signatures for model distribution. Store hashes in a secure configuration. Validate before loading. Consider downloading models from HTTPS sources with certificate pinning.
• Medium · Unrestricted File Upload/Output Paths — demo/processor.py, hivision/creator/move_image.py. The demo and API components process images without visible path traversal protection. Temp files and outputs may be written to predictable locations, potentially allowing attackers to overwrite sensitive files or access intermediate outputs. Fix: Use secure temporary directories (tempfile.mkdtemp() with restrictive permissions). Validate and sanitize all file paths. Use UUID for output filenames to prevent predictability. Implement strict output directory boundaries. Clean up temp files prompt

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.