# zeyi-lin/hivisionidphotos architecture

> Architecture diagram of the GitHub repository zeyi-lin/hivisionidphotos, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/zeyi-lin/hivisionidphotos
- Repository: https://github.com/zeyi-lin/hivisionidphotos

## Overview

HivisionIDPhoto turns an uploaded portrait into standardized ID photos, with optional background replacement, beauty adjustments, print layouts, watermarks, and template photos. The main UI flow is Gradio → processor → ID-photo creator → downloadable outputs; a CLI and API provide additional entry points. Face detection and matting are selectable, including an optional online Face++ detector. The creator’s orchestration and API implementation were not sampled, so those links reflect the documented product flow; unsampled subsystem details are kept at their supported paths.

Main entry points: [`demo/processor.py`](https://github.com/zeyi-lin/hivisionidphotos/blob/master/demo/processor.py) (Demo processor), [`hivision/__init__.py`](https://github.com/zeyi-lin/hivisionidphotos/blob/master/hivision/__init__.py) (ID photo creator), [`inference.py`](https://github.com/zeyi-lin/hivisionidphotos/blob/master/inference.py) (Inference CLI), [`hivision/creator/choose_handler.py`](https://github.com/zeyi-lin/hivisionidphotos/blob/master/hivision/creator/choose_handler.py) (Model selection)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User interfaces"]
  node_gradio["Gradio demo<br/>[app.py]"]
  node_demo_ui["Demo controls<br/>[ui.py]"]
  node_processor["Demo processor<br/>[processor.py]"]
  node_cli["Inference CLI<br/>[inference.py]"]
end

subgraph group_creation["Photo creation"]
  node_creator["ID photo creator<br/>[__init__.py]"]
  node_context["Processing context<br/>[context.py]"]
  node_photo_adjust["Photo adjustment<br/>[photo_adjuster.py]"]
end

subgraph group_enhance["Enhancement and layout"]
  node_layout_calc["Print layout"]
  node_beauty["Beauty filters<br/>[handler.py]"]
  node_watermark["Watermarking<br/>[watermark.py]"]
  node_template["Template photos"]
end

subgraph group_models["Vision models"]
  node_handler_select["Model selection<br/>[choose_handler.py]"]
  node_matting["Portrait matting<br/>[human_matting.py]"]
  node_face_detect["Face detection<br/>[face_detector.py]"]
  node_retinaface["RetinaFace inference<br/>[inference.py]"]
end

subgraph group_services["API service"]
  node_api["API service<br/>[deploy_api.py]"]
end

node_user(("Photo user"))
node_facepp{{"Face++ API"}}
node_outputs["Photo files"]

node_user -->|"uploads photo"| node_gradio
node_gradio -->|"builds interface"| node_demo_ui
node_demo_ui -->|"dispatches inputs"| node_processor
node_processor -->|"creates photo"| node_creator
node_user -->|"provides image"| node_cli
node_cli -->|"creates photo"| node_creator
node_user -->|"sends request"| node_api
node_api -->|"requests processing"| node_creator
node_processor -->|"selects models"| node_handler_select
node_cli -->|"selects models"| node_handler_select
node_handler_select -->|"selects handler"| node_matting
node_handler_select -->|"selects handler"| node_face_detect
node_face_detect -->|"runs inference"| node_retinaface
node_face_detect -.->|"calls online detector"| node_facepp
node_creator -->|"maintains state"| node_context
node_creator -->|"extracts portrait"| node_matting
node_creator -->|"detects face"| node_face_detect
node_creator -->|"adjusts portrait"| node_photo_adjust
node_processor -->|"applies filters"| node_beauty
node_processor -->|"builds print layout"| node_layout_calc
node_processor -->|"adds watermark"| node_watermark
node_processor -->|"generates template"| node_template
node_processor -->|"saves results"| node_outputs
node_cli -->|"builds print layout"| node_layout_calc
node_cli -->|"saves results"| node_outputs

click node_gradio "https://github.com/zeyi-lin/hivisionidphotos/blob/master/app.py"
click node_demo_ui "https://github.com/zeyi-lin/hivisionidphotos/blob/master/demo/ui.py"
click node_processor "https://github.com/zeyi-lin/hivisionidphotos/blob/master/demo/processor.py"
click node_cli "https://github.com/zeyi-lin/hivisionidphotos/blob/master/inference.py"
click node_api "https://github.com/zeyi-lin/hivisionidphotos/blob/master/deploy_api.py"
click node_creator "https://github.com/zeyi-lin/hivisionidphotos/blob/master/hivision/__init__.py"
click node_context "https://github.com/zeyi-lin/hivisionidphotos/blob/master/hivision/creator/context.py"
click node_handler_select "https://github.com/zeyi-lin/hivisionidphotos/blob/master/hivision/creator/choose_handler.py"
click node_matting "https://github.com/zeyi-lin/hivisionidphotos/blob/master/hivision/creator/human_matting.py"
click node_face_detect "https://github.com/zeyi-lin/hivisionidphotos/blob/master/hivision/creator/face_detector.py"
click node_retinaface "https://github.com/zeyi-lin/hivisionidphotos/blob/master/hivision/creator/retinaface/inference.py"
click node_photo_adjust "https://github.com/zeyi-lin/hivisionidphotos/blob/master/hivision/creator/photo_adjuster.py"
click node_layout_calc "https://github.com/zeyi-lin/hivisionidphotos/blob/master/hivision/creator/layout_calculator.py"
click node_beauty "https://github.com/zeyi-lin/hivisionidphotos/blob/master/hivision/plugin/beauty/handler.py"
click node_watermark "https://github.com/zeyi-lin/hivisionidphotos/blob/master/hivision/plugin/watermark.py"
click node_template "https://github.com/zeyi-lin/hivisionidphotos/blob/master/hivision/plugin/template/template_calculator.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_gradio,node_demo_ui,node_processor,node_cli,node_user toneBlue
class node_creator,node_context,node_photo_adjust toneAmber
class node_layout_calc,node_beauty,node_watermark,node_template,node_facepp toneMint
class node_handler_select,node_matting,node_face_detect,node_retinaface toneRose
class node_api,node_outputs toneIndigo
```

## Components

### User interfaces

- [Gradio demo](https://github.com/zeyi-lin/hivisionidphotos/blob/master/app.py): `app.py`
- [Demo controls](https://github.com/zeyi-lin/hivisionidphotos/blob/master/demo/ui.py): `demo/ui.py`
- [Demo processor](https://github.com/zeyi-lin/hivisionidphotos/blob/master/demo/processor.py): `demo/processor.py`
- [Inference CLI](https://github.com/zeyi-lin/hivisionidphotos/blob/master/inference.py): `inference.py`

### Photo creation

- [ID photo creator](https://github.com/zeyi-lin/hivisionidphotos/blob/master/hivision/__init__.py): `hivision/__init__.py`
- [Processing context](https://github.com/zeyi-lin/hivisionidphotos/blob/master/hivision/creator/context.py): `hivision/creator/context.py`
- [Photo adjustment](https://github.com/zeyi-lin/hivisionidphotos/blob/master/hivision/creator/photo_adjuster.py): `hivision/creator/photo_adjuster.py`

### Enhancement and layout

- [Print layout](https://github.com/zeyi-lin/hivisionidphotos/blob/master/hivision/creator/layout_calculator.py): `hivision/creator/layout_calculator.py`
- [Beauty filters](https://github.com/zeyi-lin/hivisionidphotos/blob/master/hivision/plugin/beauty/handler.py): `hivision/plugin/beauty/handler.py`
- [Watermarking](https://github.com/zeyi-lin/hivisionidphotos/blob/master/hivision/plugin/watermark.py): `hivision/plugin/watermark.py`
- [Template photos](https://github.com/zeyi-lin/hivisionidphotos/blob/master/hivision/plugin/template/template_calculator.py): `hivision/plugin/template/template_calculator.py`

### Vision models

- [Model selection](https://github.com/zeyi-lin/hivisionidphotos/blob/master/hivision/creator/choose_handler.py): `hivision/creator/choose_handler.py`
- [Portrait matting](https://github.com/zeyi-lin/hivisionidphotos/blob/master/hivision/creator/human_matting.py): `hivision/creator/human_matting.py`
- [Face detection](https://github.com/zeyi-lin/hivisionidphotos/blob/master/hivision/creator/face_detector.py): `hivision/creator/face_detector.py`
- [RetinaFace inference](https://github.com/zeyi-lin/hivisionidphotos/blob/master/hivision/creator/retinaface/inference.py): `hivision/creator/retinaface/inference.py`

### API service

- [API service](https://github.com/zeyi-lin/hivisionidphotos/blob/master/deploy_api.py): `deploy_api.py`

### Other components

- **Photo user**
- **Face++ API**
- **Photo files**

## Connections

- Photo user → Gradio demo: uploads photo
- Gradio demo → Demo controls: builds interface
- Demo controls → Demo processor: dispatches inputs
- Demo processor → ID photo creator: creates photo
- Photo user → Inference CLI: provides image
- Inference CLI → ID photo creator: creates photo
- Photo user → API service: sends request
- API service → ID photo creator: requests processing
- Demo processor → Model selection: selects models
- Inference CLI → Model selection: selects models
- Model selection → Portrait matting: selects handler
- Model selection → Face detection: selects handler
- Face detection → RetinaFace inference: runs inference
- Face detection → Face++ API: calls online detector
- ID photo creator → Processing context: maintains state
- ID photo creator → Portrait matting: extracts portrait
- ID photo creator → Face detection: detects face
- ID photo creator → Photo adjustment: adjusts portrait
- Demo processor → Beauty filters: applies filters
- Demo processor → Print layout: builds print layout
- Demo processor → Watermarking: adds watermark
- Demo processor → Template photos: generates template
- Demo processor → Photo files: saves results
- Inference CLI → Print layout: builds print layout
- Inference CLI → Photo files: saves results