ByteNoteByteNote
字

字节笔记本

2026年2月18日

macos-vision-ocr：基于 Apple Vision 的 macOS 命令行 OCR 工具

#开源工具
API中转
¥120
每日科技简报 · 每天一篇,快速了解科技圈大事

本文介绍 macos-vision-ocr ， 一款基于 Apple Vision 框架开发的强大命令行 OCR 工具，支持单图和批量处理，输出详细的文字位置信息，专为 macOS 用户打造。

项目简介

macos-vision-ocr 是一个开源的命令行 OCR（光学字符识别）工具，由 bytefer 开发。它充分利用 Apple 原生的 Vision 框架，为 macOS 用户提供高效、准确的文字识别能力。该工具支持识别多种语言，能够输出文字位置坐标，非常适合需要批量处理图片文字提取的场景。

GitHub 数据：

  • Stars: 249+
  • Forks: 37+
  • 语言: Swift
  • 许可证: MIT

核心特性

  • 基于 Apple Vision 框架：利用 Apple 原生 API，识别准确率高
  • 单图和批量处理：支持单张图片或整个目录批量识别
  • 多语言支持：支持简体中文、繁体中文、英文等多种语言
  • 详细位置信息：输出每个文字块的精确坐标位置
  • 调试模式：可视化文字检测框，便于调试
  • JSON 输出：结构化输出结果，易于集成

系统要求

  • macOS: 10.15+ (Catalina 或更高版本)
  • 架构: 支持 Apple Silicon (arm64) 和 Intel (x86_64)
  • 开发环境: Xcode 12.0+ (如需从源码构建)

安装指南

从源码构建

  1. 克隆仓库

    bash
    git clone https://github.com/bytefer/macos-vision-ocr.git
cd macos-vision-ocr

  2. 构建项目

    Apple Silicon (M1/M2/M3):

    bash
    swift build -c release --arch arm64

    Intel Mac:

    bash
    swift build -c release --arch x86_64

  3. 使用构建产物

    构建完成后，可执行文件位于 .build/release/macos-vision-ocr

使用方法

单图处理

处理单张图片并输出到控制台：

bash
./macos-vision-ocr --img ./images/handwriting.webp

指定输出目录：

bash
./macos-vision-ocr --img ./images/handwriting.webp --output ./images

批量处理

处理目录中的所有图片：

bash
./macos-vision-ocr --img-dir ./images --output-dir ./output

合并所有结果为单个文件：

bash
./macos-vision-ocr --img-dir ./images --output-dir ./output --merge

设置识别语言

指定识别语言（支持多语言）：

bash
./macos-vision-ocr --img ./images/handwriting.webp --rec-langs "zh-Hans, zh-Hant, en-US"

调试模式

启用调试模式，在图片上绘制检测框：

bash
./macos-vision-ocr --img ./images/handwriting.webp --debug

命令行选项

选项说明
--img <path>单张图片路径
--output <path>单图模式输出目录
--img-dir <path>批量处理图片目录
--output-dir <path>批量模式输出目录
--merge合并所有输出为单个文件
--debug调试模式：在图片上绘制检测框
--lang显示支持的语言列表
--help显示帮助信息

输出格式

工具输出 JSON 格式的识别结果：

json
{
  "texts": "识别的完整文本内容...",
  "info": {
    "filepath": "./images/handwriting.webp",
    "filename": "handwriting.webp",
    "width": 1600,
    "height": 720
  },
  "observations": [
    {
      "text": "单行文字内容",
      "confidence": 0.5,
      "quad": {
        "topLeft": { "x": 0.09, "y": 0.28 },
        "topRight": { "x": 0.88, "y": 0.28 },
        "bottomLeft": { "x": 0.09, "y": 0.35 },
        "bottomRight": { "x": 0.88, "y": 0.35 }
      }
    }
  ]
}

字段说明

字段说明
texts识别出的完整文本
info图片基本信息
observations每个文字块的详细信息
confidence识别置信度 (0-1)
quad文字块的四边形坐标

支持的语言

  • zh-Hans - 简体中文
  • zh-Hant - 繁体中文
  • en-US - 英文（美国）
  • ja-JP - 日语
  • ko-KR - 韩语
  • fr-FR - 法语
  • de-DE - 德语
  • es-ES - 西班牙语
  • 更多语言...

Node.js 集成示例

javascript
const { exec } = require("child_process");
const util = require("util");
const execPromise = util.promisify(exec);

async function performOCR(imagePath, outputDir = null) {
  try {
    // 构建命令
    let command = `./macos-vision-ocr --img "${imagePath}"`;
    if (outputDir) {
      command += ` --output "${outputDir}"`;
    }

    // 执行 OCR 命令
    const { stdout, stderr } = await execPromise(command);

    if (stderr) {
      console.error("Error:", stderr);
      return null;
    }

    // 解析 JSON 输出
    const result = JSON.parse(stdout);
    return result;
  } catch (error) {
    console.error("OCR processing failed:", error);
    return null;
  }
}

// 使用示例
async function example() {
  const result = await performOCR("./images/handwriting.webp");
  if (result) {
    console.log("Extracted text:", result.texts);
    console.log("Text positions:", result.observations);
  }
}

example();

使用场景

场景应用方式
文档数字化批量扫描文档转可编辑文本
图片文字提取从截图、照片中提取文字
手写识别识别手写笔记内容
自动化工作流集成到 shell 脚本或 CI/CD
数据分析提取图片中的结构化数据

常见问题

1. 构建失败

问题: swift build 报错

解决:

  • 确保 Xcode 命令行工具已安装：xcode-select --install
  • 检查 Swift 版本：swift --version

2. 权限问题

问题: 无法执行二进制文件

解决:

bash
chmod +x ./macos-vision-ocr

3. 识别准确率低

建议:

  • 确保图片清晰，文字对比度高
  • 使用 --debug 模式检查检测框
  • 尝试调整识别语言参数

与其他 OCR 工具对比

特性macos-vision-ocrTesseractOCRmyPDF
平台macOS only跨平台跨平台
引擎Apple VisionTesseractTesseract
速度快（原生优化）中等中等
准确度高中等中等
位置信息✅❌❌
批量处理✅✅✅

技术栈

  • Swift - 主要编程语言
  • Apple Vision Framework - OCR 核心引擎
  • Swift Argument Parser - 命令行参数解析

项目链接

总结

macos-vision-ocr 是 macOS 用户的理想 OCR 工具，它充分利用 Apple Vision 框架的强大能力，提供快速、准确的文字识别服务。无论是个人使用还是集成到自动化工作流，这个工具都能满足需求。对于需要在 macOS 上进行批量 OCR 处理的用户来说，这是一个值得尝试的开源方案。

开源工具
上一篇

Hairstyle AI：免费 AI 发型试戴工具，10 秒预览 100+ 发型

下一篇

macos-vision-ocr：基于 Apple Vision 的 macOS 命令行 OCR 工具

分享: