Metadata-Version: 2.5
Name: seetapsych-lib
Version: 0.0.3rc1
Summary: A Computer Vision Toolkit for Face-based Psychological Measurement
Project-URL: Homepage, https://github.com/seetapsych/seetapsych-lib
Project-URL: Repository, https://github.com/seetapsych/seetapsych-lib
Project-URL: Issues, https://github.com/seetapsych/seetapsych-lib/issues
License: BSD 3-Clause License
        
        Copyright (c) 2026, Visual Information Processing and Learning (VIPL) group,
        Institute of Computing Technology, Chinese Academy of Sciences, Beijing, China;
        Southeast University, China;
        Beijing Seetatech Co., Ltd.
        All rights reserved.
        
        Redistribution and use in source and binary forms, with or without
        modification, are permitted provided that the following conditions are met:
        
        1. Redistributions of source code must retain the above copyright notice, this
           list of conditions and the following disclaimer.
        
        2. Redistributions in binary form must reproduce the above copyright notice,
           this list of conditions and the following disclaimer in the documentation
           and/or other materials provided with the distribution.
        
        3. Neither the name of the copyright holder nor the names of its
           contributors may be used to endorse or promote products derived from
           this software without specific prior written permission.
        
        THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
        AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
        IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
        ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
        LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
        CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
        SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
        INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
        CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
        ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
        POSSIBILITY OF SUCH DAMAGE.
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Image Processing
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: jsonschema2md>=1.7.0
Requires-Dist: nvidia-ml-py>=13.595.45
Requires-Dist: packaging>=25.0
Requires-Dist: platformdirs>=4.5.1
Requires-Dist: pydantic>=2.13.3
Requires-Dist: pyyaml>=6.0.3
Requires-Dist: tomli>=2.3.0
Requires-Dist: tqdm>=4.67.2
Provides-Extra: dev
Requires-Dist: aistudio-sdk>=0.3.8; extra == 'dev'
Requires-Dist: bandit>=1.7; extra == 'dev'
Requires-Dist: build>=1.4.4; extra == 'dev'
Requires-Dist: huggingface-hub>=1.6.0; extra == 'dev'
Requires-Dist: modelscope>=1.34.0; extra == 'dev'
Requires-Dist: mypy>=1.11; extra == 'dev'
Requires-Dist: numpy>=2.2.6; extra == 'dev'
Requires-Dist: onnxruntime-gpu<1.24; (sys_platform != 'darwin' and python_version <= '3.10') and extra == 'dev'
Requires-Dist: onnxruntime-gpu>=1.24; (sys_platform != 'darwin' and python_version > '3.10') and extra == 'dev'
Requires-Dist: onnxruntime<1.24; (sys_platform == 'darwin' and python_version <= '3.10') and extra == 'dev'
Requires-Dist: onnxruntime>=1.24; (sys_platform == 'darwin' and python_version > '3.10') and extra == 'dev'
Requires-Dist: opencv-python>=4.13.0.90; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Requires-Dist: streamlit>=1.53.0; extra == 'dev'
Requires-Dist: twine>=6.2.0; extra == 'dev'
Requires-Dist: types-pyyaml>=6.0; extra == 'dev'
Provides-Extra: webui
Requires-Dist: numpy>=2.2.6; extra == 'webui'
Requires-Dist: opencv-python>=4.13.0.90; extra == 'webui'
Requires-Dist: streamlit>=1.53.0; extra == 'webui'
Description-Content-Type: text/markdown

# SeetaPsych Lib

> A Computer Vision Toolkit for Face-based Psychological Measurement

[![License](https://img.shields.io/badge/license-BSD-blue.svg)](LICENSE)

SeetaPsych Lib is a Python library for face and body-based psychology analysis.
It provides a modular Pipeline/Runner runtime and an optional Streamlit WebUI.

## Requirements

- Python >= 3.10
- (Recommended) uv package manager: <https://github.com/astral-sh/uv>

## Installation

### Create Virtual Environment

It is recommended to use an isolated virtual environment before installing dependencies.

#### Using uv (recommended)

```sh
# Create a virtual environment at .venv
uv venv

# Activate (bash/zsh)
source .venv/bin/activate

# Activate (PowerShell)
.venv\Scripts\Activate.ps1

# Activate (Windows CMD)
.venv\Scripts\activate.bat
```

#### Using standard venv

```sh
python -m venv .venv

# bash/zsh
source .venv/bin/activate

# PowerShell
.venv\Scripts\Activate.ps1

# Windows CMD
.venv\Scripts\activate.bat
```

#### Using conda

```sh
conda create -n seetapsych python=3.10
conda activate seetapsych
```

### Install Dependencies

Install the required dependencies:

- seetapsych-lib
- seetapsych-attributes
- seetapsych-configs

To run the WebUI, you need to install the `seetapsych-lib[webui]` package.

#### Using uv (recommended)

```sh
uv pip install 'seetapsych-lib[webui]' seetapsych-attributes seetapsych-configs
```

#### Using pip

```sh
pip install seetapsych-lib[webui] seetapsych-attributes seetapsych-configs
```

## Install Default Configs

```sh
# download default configs
seetapsych-manager download
# install each module requirements
seetapsych-manager setup
# download each model
seetapsych-manager cache
```

The `setup` and `cache` commands can be skipped.
When you use the WebUI or call the library programmatically later, `seetapsych-lib` can install dependencies and download necessary models on demand.

## Public Resources

The default modules installed with `seetapsych-lib` are published and maintained at <https://github.com/seetapsych/seetapsych-configs>.

To update the built-in modules to their latest versions, upgrade the configs package and re-download:

```sh
uv pip compile --upgrade-package seetapsych-configs
seetapsych-manager download -f
```

Algorithm inputs and execution outputs are defined via `Attributes`.

The full Attributes specification is available at <https://github.com/seetapsych/seetapsych-attributes>.

## Quick Start

### Run WebUI (Streamlit)

```sh
seetapsych-webui --log INFO
```

or

```sh
python -m seetapsych_lib.webui --log INFO
```

A local browser window will open automatically, or you can manually navigate to: `http://localhost:8501`.

Common arguments:

- `--dirs <DIR...>`: load modules from directories
- `--files <FILE...>`: load modules from local config files
- `--urls <URL...>`: load modules from remote URLs
- `--disable-builtin`: disable builtin modules
- `--disable-default`: disable default modules
- `--cache-dir <DIR>`: model cache directory
- `--upload-dir <DIR>`: upload directory
- `--log <LEVEL>`: log level (e.g., `DEBUG`, `INFO`, `WARNING`, or an integer like `10`)

### Programmatic Usage

```python
# -*- coding: utf-8 -*-

import json
import cv2

from seetapsych_lib.runtime.factory import Factory
from seetapsych_lib.runtime.pipeline import Pipeline
from seetapsych_lib.runtime.runner import Runner
from seetapsych_lib.runtime.parallel_runner import ParallelRunner


def main():
    # All installed algorithm modules are loaded by default during initialization
    # You can use the `load_xxx_module(s)` methods to load specific algorithm modules
    factory = Factory()

    # Quickly build a workflow and declare the attribute to compute as the face feature 'face/detection'
    # You can view all available attributes of installed algorithms using the `seetapsych-manager show` command
    # Result fields for attributes can be found at https://github.com/seetapsych/seetapsych-attributes
    pipeline = Pipeline(factory, attributes=["face/detection"])

    # Check for dependencies or missing issues that need to be resolved with solve()
    print(pipeline.problem())
    # Resolve workflow dependencies, automatically add face detection and corresponding models
    pipeline.solve()

    # Check for runtime environment issues that require installation or download to fix
    print(pipeline.satisfied())
    # Install missing dependencies required for the current pipeline to run
    pipeline.install_requirements()
    # Download missing models required for the pipeline to run
    pipeline.cache_models()

    # Create a basic executor
    runner = Runner(pipeline)
    # Or create a parallel executor
    # runner = ParallelRunner(pipeline)

    # Run the algorithm
    report = runner.run(data={"default": cv2.imread("image.jpg")})

    # Print the execution results
    print(json.dumps(report, indent=2, ensure_ascii=False))


if __name__ == "__main__":
    main()
```

## Built-in Modules

SeetaPsych Lib ships with a built-in module `SelectFace` for pipelines that need to reduce multi-face detection results down to a single tracked face before running downstream single-face algorithms.

### Module Catalog

| Module Config | Packages |
| --- | --- |
| [face_selection.yml](seetapsych_lib/modules/face_selection.yml) | SelectFace |

### SelectFace

> Module: SelectFace — Select one target face from multi-face detection outputs for single-face downstream pipelines.

- **Module config**: [face_selection.yml](seetapsych_lib/modules/face_selection.yml)

| Package Name | Provides Attributes | Requires Attributes |
| --- | --- | --- |
| SelectFace | `face/selection`, `face/detection` | `face/detection` |

**Description**: Select one face from detections by max area or max-tracking with PID increments on target change. Use as a post-process between multi-face detectors (RetinaFace / MediaPipe / InsightFace) and any single-face consumer (emo / hr / dense_landmarks / arcface / gaze).

**Parameters**:

| Name | Type | Default | Description & Tuning |
| --- | --- | --- | --- |
| `selection_mode` | selection (`MAX_TRACKING`, `MAX`) | `MAX_TRACKING` | Strategy for selecting from multiple faces. `MAX_TRACKING` adds temporal stability and increments PID on target switch — recommended for video. `MAX` picks the largest face every frame — use for single static images. |

**Models**: *(none — pure post-process)*

## Configuration

### Environment Variables

The following environment variables are supported:

| Env                     | Description                                                                                |
| :---------------------- | :----------------------------------------------------------------------------------------- |
| SEETAPSYCH\_LOG\_LEVEL  | Change default log level. Could be `WARNING`, `INFO`, `DEBUG`, or an integer (e.g., `10`). |
| SEETAPSYCH\_CACHE\_DIR  | Base directory for model cache. Models are cached under `<CACHE_DIR>/models`.              |
| SEETAPSYCH\_CONFIG\_DIR | Base directory for config files. Config files are loaded from `<CONFIG_DIR>/configs`.      |
