winget install astral-sh.uv

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

curl -LsSf https://astral.sh/uv/install.sh | sh

git clone https://github.com/JoshuaLam21/vision-reader.git
cd vision-reader
uv sync --extra dev --extra mcp

uv run vision demo

uv run vision analyze 你的图片.png --out report.md

uv run vision demo

uv run vision analyze <图片> [--grid 8x8] [--top 3] [--out report.md] [--summary] [--no-ocr]

uv run vision overview <图片> --grid 8x8          # 1. 全图 chunk 概览
uv run vision crop <图片> --region 0.1,0.1,0.5,0.5 --encode ascii_art --size 64   # 2. 裁剪+编码
uv run vision ocr <图片> --region 0.02,0.42,0.6,0.58 --engine easyocr --languages ch_sim,en  # 3. OCR
uv run vision report obs1.json obs2.json --out report.md   # 4. 汇总报告

from vision_reader import image_io
from vision_reader.analyzer import analyze

img = image_io.load_image("截图.png")          # 支持路径 / base64 / bytes / ndarray
result = analyze(img, top_n=3, ocr=True)       # 一键分析（无需调度）
print(result.to_report())                      # 完整 Markdown 报告

# 需要精细控制时，可用分步 API：
from vision_reader import crop, overview
from vision_reader.encoders import encode
from vision_reader.ocr import recognize

chunks = overview.chunks(img, grid=(8, 8))     # 全图概览
cr = crop.region(img, 0.1, 0.1, 0.5, 0.5, scale=2.0)  # 裁剪放大
print(encode(cr.image, name="grayscale_grid", grid_width=32))  # 编码细看
result = recognize(cr.image, engine="easyocr", languages=("ch_sim", "en"))  # OCR

uv tool install . --extra mcp   # 全局安装 vision / vision-mcp 命令（含依赖，约几百 MB，一次性）
vision-mcp                     # 测试：启动后不退出、无报错即正常（Ctrl+C 停止）

uv sync --extra mcp        # 安装过（--extra dev --extra mcp）则跳过

uv run python -m vision_reader.mcp_server

{
  "mcpServers": {
    "vision-reader": {
      "command": "vision-mcp"
    }
  }
}

{
  "mcpServers": {
    "vision-reader": {
      "command": "uv",
      "args": ["--directory", "<项目路径>", "run", "python", "-m", "vision_reader.mcp_server"]
    }
  }
}

# 看图的工具（vision-reader）
当需要理解一张图片时：
1. `uv run vision analyze <img> --out report.md` → 一键自动分析，读 report.md 理解图片
2. 需要更细看某区域时：`uv run vision crop <img> --region x1,y1,x2,y2 --encode ascii_art`
3. 需要读文字时：`uv run vision ocr <img> --region x1,y1,x2,y2`

vision_reader/
├── image_io.py          # 图片加载（路径/base64/bytes/ndarray）
├── coordinates.py       # 归一化坐标 ↔ 像素换算、越界处理
├── crop.py              # 裁剪 + LANCZOS 放大 + 灰度化
├── overview.py          # 全图 chunk 网格摘要
├── analyzer.py          # 一键自动分析（概览→选区域→编码→OCR→报告）
├── report.py            # 多次观察汇总为 Markdown
├── cli.py               # CLI 入口（vision 命令）
├── mcp_server.py        # MCP server（FastMCP + stdio）
├── demo_runner.py       # demo 完整链路
├── encoders/            # 可插拔编码器（grayscale_grid/ascii_art/color_stats）
├── ocr/                 # 可插拔 OCR（easyocr 默认 / paddleocr 占位）
└── synthetic.py         # 合成测试图生成
tests/                   # pytest 单测（全部基于合成图）
demo/                    # demo 脚本与输出

uv run pytest -q