vision-reader

给没有图像能力的 LLM 的"看图能力"工具：把图片的像素 + 坐标整理成模型可读的文本，让模型理解复杂图片（截图、文档、图表、UI 界面等）。

用法一句话：vision analyze 你的图片.png，其余全部自动。 内部自动完成 全图概览 → 自动挑选关注区域 → 编码细看 → OCR → 输出完整 Markdown 报告，不需要任何手动调度。

---

安装（约 2 分钟）

第 1 步：安装 uv（Python 包管理器，会自动带上 Python，无需手动装 Python）

Windows（任选其一）：

winget install astral-sh.uv

或

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

macOS / Linux：

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

装完重开终端，输入 uv --version 能输出版本号即成功。

第 2 步：获取项目并安装依赖

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

⏳ 首次安装需要下载 torch / easyocr 等依赖，约几百 MB，请耐心等几分钟，进度条走完即可。

第 3 步：验证安装成功

uv run vision demo

看到终端输出一份 Markdown 报告、并在 demo/output/report.md 生成文件，说明安装成功。

---

快速开始（30 秒上手）

看你自己的一张图

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

打开 report.md，就是完整的图片理解报告（整体概览 + 局部细节 + OCR 文字 + 坐标索引）。

首次运行会自动下载 OCR 模型权重（约 60 MB，一次性，存到 ~/.EasyOCR），请耐心等待。

没有图片？跑个演示

uv run vision demo

自动生成一张合成图并分析，输出到 demo/output/。

常用命令速查

想做什么	命令
一键分析图片（主用法）	uv run vision analyze <图片>
分析并保存报告	uv run vision analyze <图片> --out report.md
只看全图概览	uv run vision overview <图片>
裁剪某区域细看	uv run vision crop <图片> --region 0.1,0.1,0.5,0.5
提取某区域文字	uv run vision ocr <图片> --region 0.1,0.1,0.5,0.5
跑完整演示	uv run vision demo

所有坐标都是归一化坐标 (0~1)，0,0 是左上角，1,1 是右下角。

---

常见问题（FAQ）

Q：uv 命令找不到？ 安装 uv 后需要重开终端（让 PATH 生效）；Windows 用户也可以重启一下终端窗口。

Q：安装/下载很慢？ 首次 uv sync 要下载 torch（几百 MB），首次 analyze 要下载 OCR 模型（约 60 MB）。都是一次性的，之后秒开。网络慢可考虑配置镜像源。

Q：vision analyze 报错？ 先跑 uv run vision demo 确认环境正常；如果 demo 正常而你自己的图报错，可能是图片路径含中文/空格——用引号包起来：uv run vision analyze "我的 图片.png"。

Q：我想让 Claude / 我的 AI 直接"看图"？ 见下方 MCP Server 章节，配置一次后，AI 就能调用 vision_analyze 工具看你的图。

---

CLI 用法

一键分析（推荐，主用法）

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

参数	说明
--grid NxM	全图概览网格，默认 8x8
--top N	自动细看的区域数，默认 3
--out 路径	报告保存路径（默认仅打印）
--summary	输出 token 精简摘要（布局要点+区域要点+OCR 汇总，约省 80% token；适合大图/长上下文受限）
--no-ocr	跳过 OCR

内部自动流程：全图概览 → 按边缘密度排序挑选候选区域、膨胀并合并重叠 → 每个区域自动选编码器（颜色丰富用 color_stats，否则 ascii_art）→ 疑似文字区域自动 OCR → 汇总 Markdown 报告。

报告开头自带"给模型的导读"：说明坐标归一化、ASCII 字符含义、边缘密度解读、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. 汇总报告

crop 参数：--scale 放大倍数（默认 2.0）、--encode 编码器（ascii_art / grayscale_grid / color_stats）、--color 保留彩色、--json 输出 JSON 供 report 汇总。

---

三种编码器（模型按需自选）

名称	输出	特点
grayscale_grid	灰度数字网格（量化级数可调）	最接近原始像素读数，token 消耗大
ascii_art	字符明暗密度图	token 最省、最易读
color_stats	分块主色/亮度/边缘密度统计	适合颜色与结构判断

编码器可插拔：实现 vision_reader/encoders/base.py 的 Encoder 接口并加 @register 即可。

---

Python 库用法

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