{"id":48976170,"url":"https://github.com/tobilg/simpleocr","last_synced_at":"2026-04-18T09:06:38.029Z","repository":{"id":343771109,"uuid":"1173724300","full_name":"tobilg/simpleocr","owner":"tobilg","description":"Swift OCR CLI for AI Pipeline Use","archived":false,"fork":false,"pushed_at":"2026-03-11T17:55:05.000Z","size":39,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-11T22:41:46.230Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Swift","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tobilg.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-05T17:21:47.000Z","updated_at":"2026-03-11T17:55:08.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/tobilg/simpleocr","commit_stats":null,"previous_names":["tobilg/simpleocr"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/tobilg/simpleocr","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tobilg%2Fsimpleocr","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tobilg%2Fsimpleocr/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tobilg%2Fsimpleocr/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tobilg%2Fsimpleocr/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tobilg","download_url":"https://codeload.github.com/tobilg/simpleocr/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tobilg%2Fsimpleocr/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31962892,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-18T00:39:45.007Z","status":"online","status_checked_at":"2026-04-18T02:00:07.018Z","response_time":103,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-04-18T09:06:37.106Z","updated_at":"2026-04-18T09:06:38.019Z","avatar_url":"https://github.com/tobilg.png","language":"Swift","funding_links":[],"categories":[],"sub_categories":[],"readme":"# simpleocr\n\n`simpleocr` is a macOS OCR CLI written in Swift for image-to-text workflows in local AI pipelines, meaning no data has to be send to the model providers.\n\nIt uses Apple's Vision framework, has no third-party dependencies, and is designed to produce output that is easy to pipe into downstream LLM or automation steps.\n\n## Features\n\n- OCR for local image files on macOS\n- Spatially aware plain-text output for LLM consumption\n- Structured JSON output with normalized bounding boxes\n- Table-focused JSON output derived from generic layout heuristics\n- Searchable PDF generation:\n  - `pdf-text`: text-only PDF\n  - `pdf-image`: original image plus invisible text layer\n- Optional PII redaction for recognized text\n- No network dependency and no cloud OCR service\n\n## Requirements\n\n- macOS 13 or newer\n\n## Install\n\n```bash\nbrew install tobilg/simpleocr/simpleocr\n```\n\n## Usage\n\n```bash\nsimpleocr \u003cimage-path\u003e [options]\nsimpleocr - [options]              # read image from stdin\n```\n\n### Arguments\n\n- `image-path`: path to the input image file (use `-` to read from stdin)\n\n### Options\n\n- `--lang \u003ccodes\u003e`: comma-separated language codes, default `de-DE,en-US`\n- `--mode \u003clevel\u003e`: `accurate` or `fast`, default `accurate`\n- `--format \u003ctype\u003e`: `plain`, `text`, `json`, `table-json`, `pdf-text`, or `pdf-image`, default `text`\n- `--output \u003cpath\u003e`: output file path for PDF formats; defaults to the input basename with `.pdf`\n- `--min-confidence \u003cval\u003e`: minimum confidence threshold between `0.0` and `1.0`, default `0.3`\n- `--pii`: redact personally identifiable information from recognized text\n- `--error-format \u003ctype\u003e`: error output format: `text` or `json`, default `text`\n- `--describe-formats`: describe available output formats and exit\n- `--version`: print version and exit\n- `--help`, `-h`: print help and exit\n\n### Supported Input Formats\n\n- `jpg`, `jpeg`\n- `png`\n- `tiff`, `tif`\n- `heic`, `heif`\n- `bmp`\n- `gif`\n\n## Examples\n\nBasic OCR (plain text, best for LLMs):\n\n```bash\nsimpleocr examples/example-bill.png --format plain\n```\n\nOCR with spatial coordinates:\n\n```bash\nsimpleocr examples/example-bill.png\n```\n\nJSON output:\n\n```bash\nsimpleocr examples/example-bill.png --format json\n```\n\nTable-focused JSON output:\n\n```bash\nsimpleocr examples/example-bill.png --format table-json\n```\n\nFast mode with German-first language hints:\n\n```bash\nsimpleocr examples/example-bill.png --lang de-DE,en-US --mode fast\n```\n\nGenerate a searchable image PDF:\n\n```bash\nsimpleocr examples/example-bill.png --format pdf-image --output bill-searchable.pdf\n```\n\nRedact PII before returning text:\n\n```bash\nsimpleocr examples/example-bill.png --pii\n```\n\nRead image from stdin:\n\n```bash\ncat screenshot.png | simpleocr - --format plain\n```\n\nJSON errors for programmatic consumption:\n\n```bash\nsimpleocr missing.png --error-format json\n# stderr: {\"error\":\"Error: File not found or unreadable: missing.png\",\"code\":1}\n```\n\nDescribe available output formats:\n\n```bash\nsimpleocr --describe-formats\n```\n\n## Output Formats\n\n### `plain`\n\nPlain text output, one line per recognized text element, sorted top-to-bottom then left-to-right. Best for feeding into LLMs or other text processing tools.\n\nExample:\n\n```text\nMuster GmbH\nIndustriestrasse 42, 80331 Munchen\n```\n\n### `text`\n\nSpatially-aware text with normalized coordinates (y,x) prepended to each line. Useful when position matters.\n\nExample:\n\n```text\n[y=0.08,x=0.06] Muster GmbH\n[y=0.11,x=0.06] Industriestrasse 42, 80331 Munchen\n```\n\n### `json`\n\nReturns document metadata, recognized observations, and inferred structured regions:\n\n```json\n{\n  \"image_size\": {\n    \"height\": 3508,\n    \"width\": 2480\n  },\n  \"language_hints\": [\n    \"de-DE\",\n    \"en-US\"\n  ],\n  \"observations\": [\n    {\n      \"bounding_box\": {\n        \"height\": 0.03,\n        \"width\": 0.22,\n        \"x\": 0.06,\n        \"y\": 0.08\n      },\n      \"confidence\": 0.98,\n      \"text\": \"Muster GmbH\"\n    }\n  ],\n  \"pii_redacted\": false,\n  \"recognition_level\": \"accurate\",\n  \"source\": \"invoice.png\"\n}\n```\n\n### `table-json`\n\nReturns only inferred table-like regions with row and cell structure derived from geometry:\n\n```json\n{\n  \"image_size\": {\n    \"height\": 1161,\n    \"width\": 796\n  },\n  \"language_hints\": [\n    \"de-DE\",\n    \"en-US\"\n  ],\n  \"pii_redacted\": false,\n  \"recognition_level\": \"accurate\",\n  \"source\": \"example-bill.png\",\n  \"tables\": [\n    {\n      \"column_anchors\": [0.1, 0.14, 0.49, 0.59, 0.74, 0.82],\n      \"row_count\": 2\n    }\n  ]\n}\n```\n\n### `pdf-text`\n\nCreates a PDF page containing rendered OCR text only.\n\n### `pdf-image`\n\nCreates a PDF containing the original image with an invisible text layer for search and copy/paste.\n\n## Claude Code Skill\n\nThis repo includes a [Claude Code](https://claude.ai/claude-code) skill that lets coding agents run OCR directly:\n\n```\n/ocr examples/example-bill.png\n/ocr screenshot.png --format json\n```\n\nThe skill is defined in `.claude/skills/ocr/SKILL.md` and is available automatically when Claude Code is used in this project.\n\nTo use the skill in other projects, install it to your personal skills directory:\n\n```bash\nmkdir -p ~/.claude/skills/ocr\ncurl -fsSL https://raw.githubusercontent.com/tobilg/simpleocr/main/.claude/skills/ocr/SKILL.md -o ~/.claude/skills/ocr/SKILL.md\n```\n\n## Development\n\n### Build from source\n\nUse the wrapper script so SwiftPM and Clang caches stay inside the repository:\n\n```bash\n./scripts/build-local.sh\n```\n\nRelease build:\n\n```bash\n./scripts/build-local.sh -c release\n```\n\n## Troubleshooting\n\n### Swift / SDK version mismatch\n\nIf you see an error like:\n\n```text\nthis SDK is not supported by the compiler\n```\n\nyour selected Swift toolchain and the active Apple SDK do not match. Fix it by:\n\n1. installing a matching Xcode version\n2. selecting the matching developer directory with `xcode-select`\n3. rerunning `./scripts/build-local.sh`\n\n### Sandbox cache warnings\n\nThe wrapper script exports local cache paths:\n\n- `SWIFTPM_MODULECACHE_OVERRIDE=.build/module-cache`\n- `CLANG_MODULE_CACHE_PATH=.build/clang-module-cache`\n\nThat avoids writing to global cache locations during local or sandboxed builds.\nIf plain `swift build` already works on your machine, you can keep using it.\n\n## Project Layout\n\n```text\nPackage.swift\nREADME.md\n.claude/skills/ocr/SKILL.md\nSources/simpleocr/main.swift\nSources/simpleocr/CLI.swift\nSources/simpleocr/Models.swift\nSources/simpleocr/ObservationLayout.swift\nSources/simpleocr/OCREngine.swift\nSources/simpleocr/OutputFormatter.swift\nSources/simpleocr/PDFGenerator.swift\nSources/simpleocr/PIIRedactor.swift\nTests/simpleocrTests/\nrequirements/ocr-cli-prd.md\nexamples/example-bill.png\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftobilg%2Fsimpleocr","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftobilg%2Fsimpleocr","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftobilg%2Fsimpleocr/lists"}