Repository Public License
1<div align="center">23<img src="docs/assets/logo.svg" alt="ORIX Scan logo" width="560">45<br><br>67<img src="docs/assets/icon-256.png" alt="ORIX Scan icon" width="128" height="128">89# ORIX Scan1011**Document Intelligence. Beautifully Simple.**1213A premium, privacy-first document scanning and PDF intelligence application for iPhone and iPad.<br>14Scan, enhance, recognize, organize, and export documents directly on your device.1516**Author: [Simon-Pierre Boucher](https://www.spboucher.ai)**1718192021-F59E0B?style=for-the-badge)22%20internal%20testing-22C55E?style=for-the-badge)23242526272829303132333435363738394041-22C55E?style=flat-square)4243444546474849-06B6D4?style=flat-square)50515253[](https://git.spboucher.ai/orix-scan/commits)54[](https://git.spboucher.ai/orix-scan/commits)55[](https://git.spboucher.ai/orix-scan)56[](https://git.spboucher.ai/orix-scan)5758</div>5960> Badge values are the results recorded on 2026-11-20 and listed with their evidence in [Release Status](#-release-status) and61> [`RELEASE-REPORT.md`](RELEASE-REPORT.md). Nothing was run on a physical iPhone or iPad: see [Known Limitations](#-known-limitations).6263---6465## Table of contents66671. [Overview](#-overview)682. [Product Philosophy](#-product-philosophy)693. [Application Preview](#-application-preview)704. [Core Features](#-core-features)715. [Local OCR Architecture](#-local-ocr-architecture)726. [PDF Processing](#-pdf-processing)737. [ORIX Actions](#-orix-actions)748. [Document Library](#-document-library)759. [Privacy and Security](#-privacy-and-security)7610. [Technology Stack](#-technology-stack)7711. [System Architecture](#-system-architecture)7812. [Project Structure](#-project-structure)7913. [Requirements](#-requirements)8014. [Installation](#-installation)8115. [Build Instructions](#-build-instructions)8216. [Testing](#-testing)8317. [Performance](#-performance)8418. [Accessibility](#-accessibility)8519. [Localization](#-localization)8620. [Development Workflow](#-development-workflow)8721. [Release Status](#-release-status)8822. [Roadmap](#-roadmap)8923. [Known Limitations](#-known-limitations)9024. [Contributing / Internal Development](#-contributing--internal-development)9125. [License](#-license)9226. [ORIX Ecosystem](#-orix-ecosystem)9394---9596## 📄 Overview9798ORIX Scan turns paper into clean, searchable documents. It scans with the system document camera, cleans the page, reads the99text with Apple's Vision framework, and writes PDFs that keep the scanned image and carry a selectable, searchable text layer.100101Everything happens on the device. The repository contains no networking code and no third-party dependency: the app is built102only on Apple frameworks.103104| | |105|---|---|106| **What it is** | A native iPhone and iPad app: scanner, page editor, on-device OCR, searchable-PDF builder, document library, workflow automation |107| **Who it is for** | Anyone who files paper: receipts, invoices, letters, contracts, course notes, books |108| **What makes it different** | No account, no upload, no tracking; file sizes are measured, not estimated; every claim in this README has a test or a measurement behind it |109| **Bundle ID** | `ai.spboucher.orix.scan` |110| **Version** | 1.0.0 (build 1) |111112## 🧭 Product Philosophy113114| Principle | What it means in ORIX Scan |115|---|---|116| **Instant Utility** | The first screen is *Scan Document*. No onboarding, no permission prompt at launch |117| **No Accounts** | There is nothing to sign up for and no sign-in code in the app |118| **Privacy by Design** | Capture, enhancement, recognition, PDF generation and search all run locally |119| **Professional Power** | Perspective crop, non-destructive filters, merge/split, password PDFs, batch workflows |120| **Exceptional Craftsmanship** | One design system (`ORIXDesign`), Dynamic Type, dark mode, an iPad workspace that is not a stretched phone |121| **Reliability First** | Crash-safe storage, atomic writes, staged document creation, features that could not be validated are left out |122123## 📱 Application Preview124125All images below are screenshots of the running app, captured by the UI tests in the iOS Simulator (iPhone 17 Pro and126iPad Pro 13-inch (M5), iOS 26.5 runtime). The documents on screen are sample pages generated by the debug build and processed127by the real engines.128129<table>130<tr>131<td align="center" width="25%"><img src="docs/screenshots/iphone-home.jpg" alt="Home screen" width="220"><br><sub><b>Home</b><br>Scan first, imports and recents below</sub></td>132<td align="center" width="25%"><img src="docs/screenshots/iphone-enhancement.jpg" alt="Document enhancement with before and after" width="220"><br><sub><b>Enhancement</b><br>Before / after, shadows flattened</sub></td>133<td align="center" width="25%"><img src="docs/screenshots/iphone-ocr-review.jpg" alt="OCR review with text regions" width="220"><br><sub><b>OCR</b><br>Recognized lines over the page</sub></td>134<td align="center" width="25%"><img src="docs/screenshots/iphone-searchable-pdf.jpg" alt="Search inside the exported PDF" width="220"><br><sub><b>Searchable PDF</b><br>Search inside the exported file</sub></td>135</tr>136<tr>137<td align="center"><img src="docs/screenshots/iphone-library.jpg" alt="Document library" width="220"><br><sub><b>Library</b><br>Folders, favourites, text search</sub></td>138<td align="center"><img src="docs/screenshots/iphone-actions.jpg" alt="ORIX Actions" width="220"><br><sub><b>ORIX Actions</b><br>Presets and your own workflows</sub></td>139<td align="center"><img src="docs/screenshots/iphone-export.jpg" alt="Export with measured sizes" width="220"><br><sub><b>Export</b><br>Real file size per preset</sub></td>140<td align="center"><img src="docs/screenshots/iphone-ocr-tables.jpg" alt="Extracted table" width="220"><br><sub><b>Tables</b><br>Editable preview, CSV export</sub></td>141</tr>142</table>143144<div align="center">145<img src="docs/screenshots/ipad-enhancement.jpg" alt="iPad workspace: sidebar, page rail and editor" width="820"><br>146<sub><b>iPad workspace</b> — sidebar, page rail and a large editor</sub>147</div>148149<details>150<summary><b>More screens</b> (text search, crop, action builder, run, organizer, dark mode, French, iPad)</summary>151<br>152<table>153<tr>154<td align="center"><img src="docs/screenshots/iphone-ocr-text.jpg" alt="Text search" width="200"><br><sub>Text with search</sub></td>155<td align="center"><img src="docs/screenshots/iphone-crop.jpg" alt="Crop editor" width="200"><br><sub>Crop and perspective</sub></td>156<td align="center"><img src="docs/screenshots/iphone-action-builder.jpg" alt="Action builder" width="200"><br><sub>Action builder</sub></td>157<td align="center"><img src="docs/screenshots/iphone-action-run.jpg" alt="Action run" width="200"><br><sub>Action run</sub></td>158</tr>159<tr>160<td align="center"><img src="docs/screenshots/iphone-organize.jpg" alt="Page organizer" width="200"><br><sub>Organize pages</sub></td>161<td align="center"><img src="docs/screenshots/iphone-home-dark.jpg" alt="Dark mode" width="200"><br><sub>Dark mode</sub></td>162<td align="center"><img src="docs/screenshots/iphone-home-fr.jpg" alt="French interface" width="200"><br><sub>Français (Canada)</sub></td>163<td align="center"><img src="docs/screenshots/iphone-settings.jpg" alt="Settings" width="200"><br><sub>Settings</sub></td>164</tr>165</table>166<img src="docs/screenshots/ipad-library.jpg" alt="iPad library" width="400"> <img src="docs/screenshots/ipad-ocr-review.jpg" alt="iPad OCR review" width="400">167<br>168<img src="docs/screenshots/ipad-home.jpg" alt="iPad home" width="400"> <img src="docs/screenshots/ipad-searchable-pdf.jpg" alt="iPad searchable PDF" width="400">169</details>170171> **No scanner screenshot.** The scanner is the system document camera (VisionKit) and needs a real camera. The Simulator has172> none and no physical device was available, so that screen has never been displayed or captured. On a device without a173> camera the app says so and offers imports instead (this path is tested).174175## ✨ Core Features176177### Capture178179| Feature | Notes |180|---|---|181| Document camera | `VNDocumentCameraViewController`: automatic edge detection, multi-page capture, flash, retake, perspective correction |182| Import photos | `PhotosPicker`, up to 50 at a time, no photo-library permission needed |183| Import files | Images and PDFs from Files, the share sheet, "Open in", and drag and drop on iPad |184| Protected PDFs | Asks for the password, imports an unlocked copy into the app's protected storage; the password is not stored |185| Edge detection on imports | Vision document segmentation proposes the crop for imported photos |186| Add, retake, replace | Add pages to an existing document, retake a page, replace it from Photos |187188### Enhancement (non-destructive)189190| Feature | Notes |191|---|---|192| Filters | Original, Colour, Greyscale, Black & White |193| Shadow reduction and background cleanup | Paper estimated at low resolution, page divided by it |194| Black & White that keeps faint text | Soft threshold, tested on faint ink |195| Adjustments | Brightness, contrast, sharpening, noise reduction |196| Geometry | Four-corner crop with perspective correction, 90° rotation, automatic straightening |197| Before / after | Draggable split view against the unfiltered capture |198| Originals kept | Every capture is stored untouched; edits are a recipe replayed at render time |199200### Page quality advice201202Blur, low contrast, dark or washed-out pages, low resolution, strong perspective, text touching the edge, and regions the203recognizer was unsure about. These are heuristics, presented as advice the user can dismiss or turn off.204205### Text206207| Feature | Notes |208|---|---|209| On-device recognition | Vision, Automatic / Fast / Accurate modes, progress, cancellation, continues briefly in the background |210| Languages | The list is read from Vision at run time; nothing is hard-coded |211| Search, copy, export | Search with match count and highlighting, copy all, `.txt` export |212| Review and correction | Line boxes over the page, low-confidence lines flagged, per-line editing with revert |213| Tables | Reconstructed from word positions, editable preview, CSV export, uncertain cells highlighted |214215### Platform integration216217Files, share sheet, printing, Spotlight (title and first lines of text, on-device index), four App Intents for Shortcuts and218Siri, drag and drop in and out on iPad, keyboard shortcuts (⌘N scan, ⇧⌘I import files, ⇧⌘P import photos, ⌘E export,219⌘1 / ⌘2 sections), context menus, haptics, dark mode, Dynamic Type, optional App Lock.220221## 🔎 Local OCR Architecture222223Recognition is `VNRecognizeTextRequest` running on the device. There is no remote OCR and no way to enable one: the code224base has no networking code at all.225226```mermaid227flowchart LR228 A["Stored original<br/>(never modified)"] --> B["PageRenderer<br/>crop · straighten · rotate · filter"]229 B --> C["Vision<br/>VNRecognizeTextRequest"]230 C --> D["Lines and words<br/>text · boxes · confidence"]231 D --> E["ReadingOrder<br/>recursive XY-cut"]232 E --> F["OCRPage<br/>ocr/<page>.json"]233 F --> G["Search · copy · correction"]234 F --> H["TableExtractor<br/>rows · gutters · cells"]235 F --> I["Searchable PDF<br/>text layer"]236```237238| Aspect | Implementation |239|---|---|240| Modes | **Automatic** = accurate with language detection; **Fast**; **Accurate** with the languages you choose |241| Languages | `supportedRecognitionLanguages()` per mode. On the development Mac (macOS 27.0) Vision reports 33 languages in Accurate mode and 6 in Fast mode (en-US, fr-FR, it-IT, de-DE, es-ES, pt-BR). The app shows whatever the device reports |242| Reading order | Recursive XY-cut: columns first when the vertical gutter is wide enough, then rows |243| Stale text is impossible | Each result is keyed to the page geometry; changing crop, rotation or straightening discards it |244| Black & White pages | Recognized through the greyscale render, which Vision reads better than a thresholded image |245| Handwriting | **Not offered as a feature.** Not validated on real handwriting (see [Known Limitations](#-known-limitations)) |246247Measured accuracy is in [Testing](#-testing). Details: [`docs/architecture/ocr-engine.md`](docs/architecture/ocr-engine.md).248249## 📑 PDF Processing250251```mermaid252flowchart TB253 subgraph Pass1["Pass 1 — Core Graphics"]254 J["Rendered page JPEG<br/>(embedded as is)"] --> K["PDF page<br/>A4 · Letter · own proportions"]255 L["OCRPage"] --> M["Invisible text<br/>per word, scaled to its box"]256 M --> K257 end258 subgraph Pass2["Pass 2 — PDFKit"]259 K --> N["Assemble in page order"]260 O["Imported PDF pages<br/>(copied, vector and text kept)"] --> N261 N --> P["Metadata · optional password"]262 end263 P --> Q["Atomic replace at destination"]264```265266| Feature | Notes |267|---|---|268| Searchable PDF | Image kept, invisible text placed word by word; tests read the file back with PDFKit and check that search hits sit on the recognized words |269| Create, import, view | Scans, images and PDFs can be mixed in one document |270| Merge, split, extract | Merge several documents; split after a page or every N pages; extract selected pages. Sources are never modified |271| Pages | Reorder, rotate, duplicate, delete, insert scans / images / PDFs |272| Search and copy text | In the app's text view and inside the exported PDF preview |273| Compression | Maximum Quality, Balanced, Small File Size — the app builds the PDF and shows its real size; it never promises a reduction |274| Password | PDFKit user/owner password on export; protected PDFs can be opened and imported |275| Metadata | Title, author, subject, keywords |276| Share, print, save | Share sheet, AirPrint, Save to Files |277278Imported pages that already contain text are copied untouched by every preset: rasterizing them would destroy their text.279Image-only imported pages are re-rasterized by Balanced and Small. Details:280[`docs/architecture/pdf-engine.md`](docs/architecture/pdf-engine.md).281282## ⚡ ORIX Actions283284A workflow is an input (Scan, Photos, Files or library documents) followed by ordered steps. Every step runs real engine285code; the builder edits the same model the engine executes.286287```mermaid288flowchart LR289 I["Input<br/>Scan · Photos · Files · Library"] --> S1["Step 1"] --> S2["Step 2"] --> S3["Step n"]290 S3 --> R["Result<br/>document · exported files"]291 S1 -. "progress · cancel" .-> U["Run screen"]292 S2 -. "failure stops the run,<br/>later steps skipped" .-> U293```294295**Steps:** Detect Edges · Straighten · Enhance (filter) · Recognize Text (mode) · Rename (pattern with `{title}` `{date}`296`{time}` `{pages}`) · Move to Folder · Mark as Favourite · Create PDF (quality, searchable) · Export Text · Export Tables.297298| Preset | Steps |299|---|---|300| Scan to PDF | Enhance (Colour) → Create PDF (Balanced, image only) |301| Scan to Searchable PDF | Enhance (Colour) → Recognize Text → Create PDF (Balanced, searchable) |302| Receipt Archive | Enhance (Greyscale) → Recognize Text → Rename `Receipt {date} {time}` → Move to "Receipts" |303| Document Cleanup | Detect Edges → Straighten → Enhance (Black & White) |304| Book Scanner | Straighten → Enhance (Greyscale) → Recognize Text (Accurate) → Create PDF (searchable) |305| Extract Text | Detect Edges → Recognize Text → Export Text |306| Extract Tables | Detect Edges → Straighten → Recognize Text (Accurate) → Export Tables |307| Compress PDF | Create PDF (Small File Size, searchable) |308309Presets are read-only; duplicating one makes an editable copy. Workflows can be renamed, duplicated, reordered, deleted, and310run on several library documents in one go. Details: [`docs/architecture/workflows.md`](docs/architecture/workflows.md).311312## 🗂 Document Library313314Recent documents, all documents, favourites, folders, Recently Deleted (30 days), search across titles **and recognized315text** (case- and accent-insensitive), sorting (modified, created, name, size, pages), filters (favourites, with / without316text, scans, imports), grid or list, rename, duplicate, move, batch selection with export / move / favourite / merge / delete,317thumbnails with a disk and memory cache.318319```mermaid320flowchart TB321 subgraph Disk["Application Support / ORIXScan"]322 M["Documents/<id>/manifest.json<br/>source of truth, replaced atomically"]323 P["pages/ — original captures"]324 F["pdf/ — imported PDFs"]325 O["ocr/ — recognized text per page"]326 C["cache/ — previews, safe to delete"]327 S["Staging/ — documents being created"]328 end329 X["Library.store<br/>SwiftData index"] -- "rebuilt from manifests<br/>if missing" --> M330 S -- "one directory move<br/>on commit" --> M331```332333A document only appears once it is complete: it is assembled in `Staging/` and moved into place in a single step. Leftovers of334an interrupted import are discarded at the next launch. Details:335[`docs/architecture/storage.md`](docs/architecture/storage.md).336337## 🔒 Privacy and Security338339| Rule | How it is met |340|---|---|341| No account, no registration | No sign-in code exists |342| No remote OCR, no external AI | Recognition is Apple Vision on device |343| No upload, no cloud requirement | No networking code: `grep -rnE "URLSession\|URLRequest\|NWConnection\|http://\|https://" App Packages --include='*.swift'` returns nothing |344| No analytics, no ads, no tracking | No SDK of any kind; `PrivacyInfo.xcprivacy` declares no tracking and no collected data |345| Permissions only when needed | Camera is requested when the scanner opens; the photo picker needs no permission |346| Files encrypted at rest | iOS data protection, class *complete until first user authentication*, so recognition started in the foreground can finish if the device locks |347| Optional App Lock | LocalAuthentication (Face ID, Touch ID or passcode); a cover hides content in the app switcher |348| Temporary files | Exports go to a dedicated directory, emptied at launch |349| Logs | The app writes no logs containing document content; error messages never include it |350351App Store privacy answers ("Data Not Collected") and the required-reason API declarations are in352[`docs/release/app-store.md`](docs/release/app-store.md).353354## 🧰 Technology Stack355356| Layer | Technology | Role |357|---|---|---|358| Language | Swift 6 language mode, strict concurrency | App and package |359| UI | SwiftUI (`NavigationSplitView`, `TabView`, Observation) | All screens; no web view |360| Scanner | VisionKit | System document camera |361| Recognition | Vision | Text recognition, document segmentation |362| Imaging | Core Image, Core Graphics, ImageIO | Rendering pipeline, quality analysis, encoding |363| PDF | PDFKit, Core Graphics, Core Text | Assembly, text layer, encryption, preview |364| Index | SwiftData | Library records, folders, saved workflows |365| Storage | FileManager, atomic writes | Originals, manifests, recognized text |366| Automation | App Intents | Shortcuts and Siri |367| Search | Core Spotlight | On-device index |368| Security | LocalAuthentication, iOS data protection | App Lock, encryption at rest |369| Project | XcodeGen, Swift Package Manager (local package) | Build definition |370| Third-party code | None | — |371372Core ML is not used directly: recognition goes through Vision, which is the supported interface to Apple's on-device text373models.374375## 🏗 System Architecture376377```mermaid378flowchart TB379 subgraph App["App target — SwiftUI, main actor"]380 UI["Screens<br/>Home · Library · Document · Text · Export · Actions · Settings"]381 AM["AppModel<br/>capture, edits, recognition, export"]382 RT["Router<br/>tabs on iPhone, sidebar on iPad"]383 PL["Platform<br/>Intents · Spotlight · App Lock · Share · Print"]384 end385 subgraph Kit["ORIXKit — engines, no UI"]386 DP["DocumentProcessor<br/>facade"]387 DS["DocumentStore<br/>actor, files"]388 PR["PageRenderer<br/>Core Image"]389 OC["OCREngine<br/>Vision"]390 PB["SearchablePDFBuilder<br/>PDFKit + Core Graphics"]391 WE["WorkflowEngine"]392 LI["LibraryIndex<br/>SwiftData"]393 end394 DSY["ORIXDesign<br/>tokens and components"]395 UI --> AM --> DP396 UI --> DSY397 AM --> LI398 AM --> WE --> DP399 DP --> DS400 DP --> PR401 DP --> OC402 DP --> PB403 PL --> AM404```405406```mermaid407flowchart LR408 subgraph In["Import"]409 A1["Document camera"] --> B1410 A2["Photos"] --> B1411 A3["Files · drag and drop · Open in"] --> B1412 B1["AppModel.receive"] --> C1["Draft in Staging/"]413 C1 --> D1["commit → Documents/"]414 end415 D1 --> E1["Recognize (optional, automatic)"]416 E1 --> F1["Index + Spotlight"]417 subgraph Out["Export"]418 G1["PDF"]419 G2["Text"]420 G3["CSV"]421 G4["Images"]422 end423 F1 --> G1 & G2 & G3 & G4424 G1 --> H1["Share · Print · Save to Files · Preview"]425```426427Full description: [`docs/architecture/overview.md`](docs/architecture/overview.md).428429## 📁 Project Structure430431```text432ORIXScan/433├── App/434│ ├── Sources/435│ │ ├── Core/ app entry, AppModel, Router, settings, naming, shared views, root436│ │ ├── Home/ first screen437│ │ ├── Library/ library, folders, batch actions438│ │ ├── Document/ workspace, page editor, crop, organizer, text, tables, export439│ │ ├── Capture/ document camera wrapper440│ │ ├── Actions/ ORIX Actions list, builder, run441│ │ ├── Settings/ settings and language picker442│ │ ├── Platform/ intents, Spotlight, App Lock, share, print, thumbnails443│ │ └── Debug/ sample documents and isolated store (Debug builds only)444│ └── Resources/ asset catalog, string catalogs, Info.plist, privacy manifest445├── Packages/ORIXKit/446│ ├── Sources/ORIXDesign/ design tokens, components, haptics447│ ├── Sources/ORIXKit/ Model · Imaging · OCR · PDF · Storage · Actions448│ └── Tests/ORIXKitTests/ engine, pipeline, library and benchmark tests449├── UITests/ XCUITest suite and import fixture450├── Scripts/ build, benchmark, release, localization, hygiene451├── design/icon/ icon concepts, masters and generator452├── docs/ architecture · design · development · release · screenshots · assets453├── project.yml XcodeGen definition454└── RELEASE-REPORT.md455```456457| Code | Files | Lines |458|---|---:|---:|459| App (Swift) | 22 | 4 852 |460| ORIXKit engines (Swift) | 17 | 2 923 |461| ORIXDesign (Swift) | 3 | 499 |462| Package tests | 5 | 1 233 |463| UI tests | 1 | 13 tests |464| Localized strings | 464 keys | English, French (Canada) |465466## 📋 Requirements467468| | |469|---|---|470| Run | iPhone or iPad with iOS / iPadOS 18.0 or later. Scanning needs a camera |471| Build | Xcode 27.2 (Swift 6.4 toolchain), [XcodeGen](https://github.com/yonaskolb/XcodeGen), macOS with the iOS 27.2 SDK |472| Accounts | None to run. An Apple Developer team to sign for devices |473| Dependencies | None beyond the Apple SDK |474475## 📥 Installation476477ORIX Scan is not on the App Store. Build 1.0.0 (1) is on TestFlight for the account's internal testers only. To run it478otherwise, build from source:479480```bash481git clone https://git.spboucher.ai/orix-scan.git482cd orix-scan483brew install xcodegen # once484Scripts/build.sh generate # creates ORIXScan.xcodeproj485open ORIXScan.xcodeproj # run the ORIXScan scheme on a simulator or a device486```487488To run on a device, set your own team in `project.yml` (`DEVELOPMENT_TEAM`) and bundle identifier if needed.489490## 🔨 Build Instructions491492```bash493Scripts/build.sh generate # XcodeGen494Scripts/build.sh kit # engines and design system on the Mac: all package tests495Scripts/build.sh debug # Debug build for the simulator496Scripts/build.sh release # Release build for the simulator497Scripts/build.sh uitest # UI tests on the "ORIX iPhone" simulator498ORIX_SIM="ORIX iPad" Scripts/build.sh uitest499Scripts/benchmark.sh # OCR accuracy and timings → docs/development/benchmarks/500Scripts/check.sh # author headers and secret scan501Scripts/localize.py # refresh the string catalog and merge French502```503504The dedicated simulators are created once with505`xcrun simctl create "ORIX iPhone" "iPhone 17 Pro"` and `xcrun simctl create "ORIX iPad" "iPad Pro 13-inch (M5)"`.506Debug builds accept `-ORIXUITest YES` (isolated store), `-ORIXReset YES` and `-ORIXDemo YES` (sample documents).507Setup details: [`docs/development/setup.md`](docs/development/setup.md).508509## 🧪 Testing510511Results recorded on 2026-11-20 on the final code. Full strategy and what is *not* covered:512[`docs/development/testing.md`](docs/development/testing.md).513514| Suite | Where it runs | Result |515|---|---|---|516| Package tests (engines, storage, library, workflows) | Mac host, real Vision / PDFKit / Core Image / SwiftData | **79 passed**, 0 failed (plus 2 opt-in benchmark tests, also passing) |517| UI tests | iPhone 17 Pro simulator, iOS 26.5 | **13 passed**, 0 failed |518| UI tests | iPad Pro 13-inch (M5) simulator, iOS 26.5, landscape | **13 passed**, 0 failed (one harness flake in a third run, see [testing.md](docs/development/testing.md)) |519| Physical device | — | **Not run.** No iPhone or iPad was connected |520| Code coverage | — | Not measured |521522What the tests actually prove, beyond "it compiles":523524- Generated PDFs are read back with PDFKit: text extraction, `findString`, and the **position** of each search hit against the recognized word box.525- After every compression preset the exported page is rasterized and recognized again to check it is still readable.526- A simulated crash during import leaves nothing behind; a committed document survives a relaunch.527- Corrupted, truncated and password-protected PDFs, unreadable images, an empty document and low storage each produce a specific error.528- In the UI: first launch with no prompt, camera unavailable, empty library, import → recognition → search inside the exported PDF, page editing, split, an action run end to end, deletion and restoration, persistence after relaunch, dark mode, the largest accessibility text size, French.529530### OCR benchmark531532A synthetic corpus of 17 pages with known ground truth, drawn with Core Text and degraded on purpose (skew, blur, shadow, low533resolution). **These are not photographs of paper**: they measure the pipeline, not real-world capture. Character error rate534(CER) and word error rate (WER), lower is better; measured on the development Mac with the same engine code the app ships.535536| Page | Automatic CER / WER | Accurate CER / WER | Fast CER / WER |537|---|---:|---:|---:|538| English, clean print | 0.3 % / 2.2 % | 0.3 % / 2.2 % | 0.0 % / 0.0 % |539| English, dense small text | 0.0 % / 0.0 % | 0.0 % / 0.0 % | 0.0 % / 0.0 % |540| English, serif | 0.0 % / 0.0 % | 0.0 % / 0.0 % | 0.0 % / 0.0 % |541| French, clean print | 0.0 % / 0.0 % | 0.0 % / 0.0 % | 0.3 % / 2.4 % |542| French, serif | 0.0 % / 0.0 % | 0.0 % / 0.0 % | 0.3 % / 2.4 % |543| Mixed English / French | 1.1 % / 6.8 % | 1.1 % / 6.8 % | 0.4 % / 2.3 % |544| Receipt, monospaced | 0.0 % / 0.0 % | 0.0 % / 0.0 % | 5.2 % / 61.9 % |545| Low resolution (75 dpi-equivalent) | 0.0 % / 0.0 % | 0.0 % / 0.0 % | 5.4 % / 20.0 % |546| Skewed 3° | 0.0 % / 0.0 % | 0.0 % / 0.0 % | 0.0 % / 0.0 % |547| Skewed 8° | 0.0 % / 0.0 % | 0.0 % / 0.0 % | 0.0 % / 0.0 % |548| Two columns | 0.0 % / 0.0 % | 0.0 % / 0.0 % | 0.0 % / 0.0 % |549| Strong side shadow | 0.3 % / 2.4 % | 0.3 % / 2.4 % | 0.3 % / 2.4 % |550| Dark page | 0.3 % / 2.2 % | 0.3 % / 2.2 % | 0.0 % / 0.0 % |551| Faint ink | 0.0 % / 0.0 % | 0.0 % / 0.0 % | 0.0 % / 0.0 % |552| Out of focus | 0.0 % / 0.0 % | 0.0 % / 0.0 % | 53.4 % / 77.8 % |553| Script font (Snell Roundhand) | 0.0 % / 0.0 % | 0.0 % / 0.0 % | 100 % / 100 % |554| Casual script (Bradley Hand) | 0.3 % / 2.4 % | 0.3 % / 2.4 % | 41.9 % / 90.2 % |555556Reading: Accurate mode is strong on everything in this corpus; Fast mode is unreliable on receipts, low resolution, blur and557script fonts, which is why Automatic uses the accurate recognizer. The two script rows are computer fonts, not handwriting.558Raw data: [`docs/development/benchmarks/ocr-accuracy.json`](docs/development/benchmarks/ocr-accuracy.json).559560## 🚀 Performance561562Measured, not estimated. Engine figures come from `Scripts/benchmark.sh` on the development Mac (Apple M5 Max, 18 cores,56348 GB, macOS 27.0), which was running other workloads; they are **not iPhone or iPad figures**. Launch time comes from564`XCTApplicationLaunchMetric` in the Simulator. Method and caveats:565[`docs/development/performance.md`](docs/development/performance.md).566567| Measurement | Result |568|---|---|569| Cold launch to first responsive frame, iPhone simulator | 1.13 s average of 5 (1.08–1.17 s); a later run under load: 1.41 s (1.12–1.60 s) |570| Cold launch, iPad simulator | 1.19 s average of 5 (1.14–1.23 s); a later run under load had four launches at 1.74–1.87 s and one 19 s outlier |571| OCR, one A4 page at 300 dpi, Accurate | 0.13 s and 0.23 s (median of 5, two runs) |572| OCR, one A4 page at 300 dpi, Fast | 0.09 s and 0.12 s |573| Full-resolution render of a 12-megapixel capture, including JPEG encoding | 0.03–0.09 s per filter across two runs |574| Editor preview (1 800 px) | 0.03 s and 0.06 s |575| Recognize a 25-page document (A4, 300 dpi) | 2.8 s in one run, 5.3 s in another |576| Export 25 pages as searchable PDF | Maximum 2.2–2.7 s · Balanced 1.5–2.0 s · Small 1.2–1.3 s |577| Size of that export (stored originals: 9.2 MB) | Maximum 9.0 MB · Balanced 3.1 MB · Small 1.5 MB |578| Memory across the 25-page batch | Footprint did not grow between the start and the end of the batch; peak was not sampled |579| Camera-to-preview latency | **Not measured** (needs a physical device) |580581## ♿ Accessibility582583| Area | State |584|---|---|585| Dynamic Type | All text uses Dynamic Type styles; layouts switch to vertical stacks at accessibility sizes. The largest size (AX XXL) is exercised by a UI test on Home and Document |586| VoiceOver | Controls carry labels, hints, traits and values; decorative images are hidden; the crop corners and the before/after split are adjustable elements. **Not verified with VoiceOver on a device** |587| Touch targets | 44 pt minimum on custom controls |588| Colour | State is never carried by colour alone (icons and text accompany it) |589| Motion | The scanning beam animation is disabled with Reduce Motion |590| Dark mode | Every colour token has a light and a dark value; exercised by a UI test |591592## 🌍 Localization593594| Language | State |595|---|---|596| English | Source language |597| French (Canada) | 463 strings translated, 12 with singular / plural forms; Home and Library verified by a UI test. Other French screens were not individually reviewed for truncation |598599Strings live in `App/Resources/Localizable.xcstrings` and `InfoPlist.xcstrings`. `Scripts/localize.py` re-extracts keys from the600build, merges `Scripts/translations-fr.json`, and fails if a key is untranslated. Recognition languages are independent of the601interface language.602603## 🔁 Development Workflow6046051. Change engine code in `Packages/ORIXKit` and run `Scripts/build.sh kit` (seconds, on the Mac).6062. Change the app, run `Scripts/build.sh debug`, then the UI tests on both simulators.6073. New user-facing strings: `Scripts/build.sh debug && Scripts/localize.py`, add the French to `Scripts/translations-fr.json`.6084. Before committing: `Scripts/check.sh` (author header on every source file, secret scan).6095. Commit messages follow `feat:`, `fix:`, `design:`, `test:`, `docs:`, `release:`.610611## 🚦 Release Status612613| Gate | State | Evidence |614|---|---|---|615| Compiles, Debug and Release | ✅ | 0 errors, 0 warnings |616| Package tests | ✅ 79 / 79 | `Scripts/build.sh kit` |617| UI tests, iPhone and iPad simulators | ✅ 13 / 13 each | `Scripts/build.sh uitest` |618| On-device OCR verified | ✅ in tests and Simulator | CER / WER table above |619| Searchable PDFs verified | ✅ | PDFKit read-back tests, in-app PDF search test |620| Persistence | ✅ | relaunch tests (package and UI) |621| Export | ✅ PDF, text, CSV, images | package tests, UI tests |622| Icon assets | ✅ compiled into the archive | light, dark, tinted |623| Signed Release archive | ✅ 1.0.0 (1) | Apple Distribution, App Store profile |624| App ID registered | ✅ `ai.spboucher.orix.scan` | created by automatic signing |625| Physical-device testing | ❌ not done | no device connected |626| Scanner (camera) | ❌ never exercised | Simulator has no camera |627| App Store Connect record | ✅ created 2026-11-20 | Apple ID 6837545072, name only; metadata not entered yet |628| Apple validation of the IPA | ✅ | `altool --validate-app`: no errors |629| TestFlight upload | ✅ 1.0.0 (1), authorized by the owner | processing state `VALID` |630| Internal testers | ✅ available | internal group "Test", 1 tester (invited) |631| External testers | ⏳ not submitted | needs Beta App Review and a separate decision |632| App Store | ⏳ not submitted | separate approval |633634Details and outstanding approvals: [`RELEASE-REPORT.md`](RELEASE-REPORT.md),635[`docs/release/testflight.md`](docs/release/testflight.md),636[`docs/release/release-checklist.md`](docs/release/release-checklist.md).637638## 🗺 Roadmap639640Not commitments; candidates in rough order.641642- Validation on physical iPhones and iPads with the TestFlight build643- Layered Icon Composer icon in addition to the flat three-appearance asset644- Apple Pencil annotation645- Handwriting, if it can be validated on real samples646- Optional iCloud Drive export destinations in ORIX Actions647- Moving `ORIXDesign` into a package shared by the ORIX apps648649## ⚠️ Known Limitations650651- **Never run on a physical device.** The camera scanner, Face ID / Touch ID, VoiceOver, background continuation, memory pressure and real performance are unverified on hardware.652- **OCR accuracy figures are from a synthetic corpus**, not photographs of paper.653- **Handwriting is not a feature.** Only computer script fonts were tried.654- **Isolated single characters can be missed.** In a table drawn for testing, Vision did not return cells holding a single digit (`3`, `7`) in any mode, while `12` and `25` were read. Tables with one-character cells can therefore come out with empty cells.655- **Table extraction is heuristic.** Merged cells, nested headers and wrapped cell text are not reconstructed. Corrections made in the table preview apply to the exported CSV and are not saved.656- **Edited lines lose word-level positioning** in the PDF text layer (the corrected line is laid over the line box as one run).657- **Imported pages that contain text are never recompressed.**658- **Unlocking a protected PDF redraws its pages**, which drops form fields, links and outlines of that file.659- **Quality warnings are estimates** and can be wrong in both directions.660- **French** beyond Home and Library was not screen-by-screen reviewed.661- **No Apple Pencil annotation, no iCloud sync, no widgets.**662- Folders are one level deep.663664## 🤝 Contributing / Internal Development665666This is a private, single-author project. Internal rules:667668- Apple frameworks only; a third-party dependency needs a written reason.669- No feature is shown to users unless it works and has a test or a documented manual check.670- Numbers in documents come from a command in this repository.671- Every source file starts with the author header; `Scripts/check.sh` enforces it.672- No credentials, signing material or personal documents in the repository (`.gitignore`, `Scripts/check.sh`).673674## 📜 License675676All rights reserved © 2026 Simon-Pierre Boucher. See [`LICENSE`](LICENSE).677678## 🪐 ORIX Ecosystem679680ORIX is a family of independent, premium Apple utilities that share one idea: useful the moment they are installed, no account,681private by design.682683| App | State |684|---|---|685| **ORIX Scan** | This repository |686| ORIX Audio, ORIX Calc | Separate projects under development |687| ORIX PDF, Image, Video, Measure, Dev, Files, Math, Secure | Ideas, not started |688689ORIX Scan contributes two reusable pieces: the `ORIXDesign` design system (tokens, components, the scan-beam signature, the690accent pair model) and the ORIX Actions workflow model. See691[`docs/design/design-system.md`](docs/design/design-system.md),692[`docs/design/brand-guidelines.md`](docs/design/brand-guidelines.md) and693[`docs/design/icon-design.md`](docs/design/icon-design.md).694695---696697<div align="center">698<img src="docs/assets/icon-256.png" width="64" height="64" alt=""><br>699<b>Simon-Pierre Boucher</b> — design, development<br>700<a href="https://www.spboucher.ai">www.spboucher.ai</a> · <a href="https://git.spboucher.ai">git.spboucher.ai</a> · contact@spboucher.ai701</div>702