Metadata-Version: 2.4
Name: procvision_algorithm_sdk
Version: 0.0.4
Summary: ProcVision algorithm SDK
Author: ProcVision Team
License: MIT
Project-URL: Homepage, https://example.com/procvision
Project-URL: Repository, https://example.com/procvision/algorithm-sdk
Project-URL: Issues, https://example.com/procvision/algorithm-sdk/issues
Keywords: vision,sdk,procvision,algorithm,industrial
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Scientific/Engineering :: Image Processing
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: numpy>=1.21
Requires-Dist: pillow>=10.0.0

# ProcVision Algorithm SDK

## 概述

- 提供 `BaseAlgorithm` 抽象与最小配套能力：`Session` 状态共享、结构化日志、诊断数据与共享内存读图接口。
- 算法方通过实现 `get_info`、`pre_execute`、`execute` 与生命周期钩子，按 `spec.md` 与平台解耦集成。

## 安装

- 从源码构建后安装：`pip install dist/procvision_algorithm_sdk-<version>-py3-none-any.whl`
- 或直接安装：`pip install procvision_algorithm_sdk`

## 接口要点（v1.0.0 对齐规范 v0.2.1）

- `BaseAlgorithm.__init__()` 不绑定 PID；每次调用通过参数传入 `pid`
- `pre_execute(step_index, pid, session, user_params, shared_mem_id, image_meta)`
- `execute(step_index, pid, session, user_params, shared_mem_id, image_meta)`
- 日志时间戳字段统一为 `timestamp_ms`
- 共享内存传图 JPEG-only，`image_meta` 最小集合：`width/height/timestamp_ms/camera_id`
- `pre_execute` 不返回真实检测结果；`execute` 的业务判定在 `data.result_status`（`OK/NG`）

## 快速开始

- 最小目录：
  - `your_algo/main.py`
  - `manifest.json`
  - `requirements.txt`
- 代码示例：

```
from typing import Any, Dict
from procvision_algorithm_sdk import BaseAlgorithm, Session, read_image_from_shared_memory

class MyAlgo(BaseAlgorithm):
    def __init__(self) -> None:
        super().__init__()
        self._supported_pids = ["p001", "p002"]

    def get_info(self) -> Dict[str, Any]:
        return {
            "name": "my_algo",
            "version": "1.0",
            "supported_pids": self._supported_pids,
            "steps": [{"index": 0, "name": "示例", "params": [{"key": "threshold", "type": "float", "default": 0.5, "min": 0.0, "max": 1.0}]}],
        }

    def pre_execute(self, step_index: int, pid: str, session: Session, user_params: Dict[str, Any], shared_mem_id: str, image_meta: Dict[str, Any]) -> Dict[str, Any]:
        if pid not in self._supported_pids:
            return {"status": "ERROR", "message": f"不支持的产品型号: {pid}", "error_code": "1001"}
        img = read_image_from_shared_memory(shared_mem_id, image_meta)
        if img is None:
            return {"status": "ERROR", "message": "图像数据为空", "error_code": "1002"}
        return {"status": "OK", "message": "准备就绪", "debug": {"latency_ms": 0.0}}

    def execute(self, step_index: int, pid: str, session: Session, user_params: Dict[str, Any], shared_mem_id: str, image_meta: Dict[str, Any]) -> Dict[str, Any]:
        img = read_image_from_shared_memory(shared_mem_id, image_meta)
        if img is None:
            return {"status": "ERROR", "message": "图像数据为空", "error_code": "1002"}
        return {"status": "OK", "data": {"result_status": "OK", "defect_rects": [], "debug": {"latency_ms": 0.0}}}
```

## CLI（Dev Runner）

- 程序名：`procvision-cli`
- 校验算法包：
  - `procvision-cli validate --project ./your_algo_project`
- 本地模拟运行：
  - `procvision-cli run ./your_algo_project --pid p001 --image ./test.jpg --json`

## 离线交付

- 生成 `requirements.txt`：`pip freeze > requirements.txt`
- 下载 wheels：

```
pip download -r requirements.txt -d wheels/ --platform win_amd64 --python-version 3.10 --implementation cp --abi cp310
```

- 打包 zip：包含源码目录、`manifest.json`、`requirements.txt`、`wheels/` 与可选 `assets/`

## 本地打包与发布（pip 包）

- 安装构建与发布工具：
  - `pip install -U build twine`
- 构建 wheel 与源码包（基于 `pyproject.toml`）：
  - `python -m build`
  - 产物输出在 `dist/`（如：`procvision_algorithm_sdk-<version>-py3-none-any.whl` 与 `procvision_algorithm_sdk-<version>.tar.gz`）
- 本地安装验证：
  - `pip install dist/procvision_algorithm_sdk-<version>-py3-none-any.whl`
- 发布到内部 PyPI（示例，仅供参考）：
  - `twine upload --repository-url <your-internal-pypi-url> dist/*`
  - 建议在环境变量或凭据管理中配置用户与令牌，避免将敏感信息写入命令行
- 版本号更新：
  - 编辑 `pyproject.toml` 的 `version` 字段（当前：`pyproject.toml:7`）并重新构建
  - 建议在 CI 中基于标签或提交自动生成版本并构建

## GitHub CI/CD

- 工作流文件：`.github/workflows/sdk-build-and-publish.yml`
- 关键步骤：安装依赖、运行测试、`python -m build` 构建产物、按标签发布到包仓库

## 目录与文件

- 包路径：`procvision_algorithm_sdk`
- 打包配置：`pyproject.toml`
- 单元测试：`tests/`

## 版本与兼容

- 要求 Python `>=3.10`
- 依赖：`numpy>=1.21`

## 参考

- `spec.md` 与 `spec_runner.md` 提供接口契约、通信协议与交付流程
