Home
Relevant source files
The following files were used as context for generating this wiki page:
- README.md
- ROADMAP.md
- TODO.md
- app/src/main/java/com/musagenius/ocrapp/MainActivity.kt
- app/src/main/java/com/musagenius/ocrapp/data/ocr/OCRServiceImpl.kt
- app/src/main/java/com/musagenius/ocrapp/presentation/viewmodel/OCRViewModel.kt
- app/src/test/java/com/musagenius/ocrapp/data/repository/ScanRepositoryImplTest.kt
- app/src/main/AndroidManifest.xml
- app/src/main/assets/tessdata/README.md
The Material Expressive Android OCR App is a modern, offline-first Android application designed for fast and accurate text extraction from images. It is built with a clean, testable architecture and leverages a modern technology stack, including Jetpack Compose for the UI, Tesseract for the OCR engine, CameraX for image capture, and Room for local data persistence. The project's vision is to provide a privacy-first, multi-language OCR tool that works anywhere without an internet connection.
The application is structured following MVVM and Clean Architecture principles to ensure maintainability and scalability. Key features include offline text recognition, a CameraX-powered scanner, local storage of scan history, and a dynamic Material Design 3 theme.
Sources: README.md:1-13, ROADMAP.md:8-20
Architecture
The application employs an MVVM (Model-View-ViewModel) pattern combined with Clean Architecture principles. This separates concerns into three distinct layers: Presentation, Domain, and Data. This structure ensures that the business logic is independent of the UI and data sources, making the codebase more testable, maintainable, and decoupled.
Sources: README.md:30-38
The following diagram illustrates the high-level architecture and the flow of data between layers.
Core Features
The application is designed with a focus on offline functionality, user experience, and privacy.
| Feature | Description | Source(s) |
|---|---|---|
| Offline OCR | Utilizes the Tesseract OCR engine via the tess-two library for on-device text recognition, requiring no internet connection. | README.md:5 |
| CameraX Integration | A modern camera interface for capturing high-quality images, with controls for flash, zoom, and focus. | README.md:7, ROADMAP.md:111-114 |
| Local Storage | Scan results, including extracted text and metadata, are saved locally using the Room database for offline access and history management. | README.md:8, TODO.md:13-23 |
| Material Design 3 UI | A modern, responsive UI built with Jetpack Compose, featuring dynamic color theming based on the user's wallpaper (on Android 12+). | README.md:6, app/src/main/java/com/musagenius/ocrapp/presentation/ui/theme/Theme.kt:66-69 |
| Multi-Language Support | Supports over 100 languages through downloadable Tesseract traineddata files. | README.md:12, app/src/main/assets/tessdata/README.md |
| Privacy-First | All image processing and text recognition happen entirely on the device, ensuring user data remains private. | ROADMAP.md:19 |
Technical Stack
The project is built using a modern set of libraries recommended for Android development.
| Component | Library/Technology | Purpose | Source(s) |
|---|---|---|---|
| UI Framework | Jetpack Compose with Material 3 | Building the native UI with a modern, declarative approach. | README.md:17-23 |
| OCR Engine | Tesseract (via tess-two:9.1.0) | Offline optical character recognition. | README.md:25-27 |
| Architecture | MVVM with Clean Architecture | Separation of concerns, testability, and maintainability. | README.md:30-32 |
| Camera | CameraX | Capturing images with lifecycle-aware components. | README.md:39-45 |
| Database | Room | Local, persistent storage of scan history in an SQLite database. | README.md:48-54 |
| Dependency Injection | Dagger Hilt | Manages dependencies and reduces boilerplate code. | README.md:57-60 |
| Asynchronous Ops | Kotlin Coroutines & Flow | Managing background tasks like OCR processing and database access. | README.md:67-70 |
System Breakdown
OCR Processing Pipeline
The core functionality of the app is its ability to process an image and extract text. This pipeline involves the UI, ViewModel, a Use Case, and the OCR service.
The following sequence diagram shows the interactions when a user captures an image to be processed.
OCRServiceImpl
This singleton class acts as a thread-safe wrapper for Tesseract's TessBaseAPI. It manages the initialization of the OCR engine, handles the loading of language data (.traineddata files), and preprocesses images before recognition. Access to the TessBaseAPI is serialized using a Mutex to prevent race conditions.
Sources: app/src/main/java/com/musagenius/ocrapp/data/ocr/OCRServiceImpl.kt:22-26
OCR Configuration
The OCR process can be customized using the OCRConfig data class.
| Parameter | Type | Default Value | Description |
|---|---|---|---|
language | String | "eng" | The language code for the OCR engine (e.g., "fra", "spa"). |
pageSegmentationMode | PageSegMode | AUTO | Tesseract's page segmentation mode. |
engineMode | EngineMode | DEFAULT | Tesseract's engine mode. |
preprocessImage | Boolean | true | Whether to apply preprocessing steps like grayscale and scaling. |
maxImageDimension | Int | 2000 | The maximum dimension (width or height) to scale the image to. |
enableAutoRotation | Boolean | false | Whether to enable automatic rotation detection. |
Sources: app/src/test/java/com/musagenius/ocrapp/domain/model/OCRConfigTest.kt:15-29
Data Persistence
The application uses the Room persistence library to store scan results for offline access in a local history.
Database Schema
A single table, scans, is planned to store all relevant information about each OCR operation.
This ER diagram shows the planned schema for the scans table.
The Data layer uses the Repository pattern, where ScanRepository provides an abstraction over the ScanDao, decoupling the domain layer from the specific data source implementation.
Sources: app/src/test/java/com/musagenius/ocrapp/data/repository/ScanRepositoryImplTest.kt:50
UI and Navigation
The UI is built with Jetpack Compose and adheres to Material Design 3 principles. The MainActivity serves as the single entry point, hosting a NavHost to manage navigation between different screens.
Sources: app/src/main/java/com/musagenius/ocrapp/MainActivity.kt:31-40
Navigation Flow
The primary user flow starts at the camera, moves to the results screen after a capture, and allows for saving to a history view.
This diagram shows the main navigation paths defined in MainActivity.kt.
Sources: app/src/main/java/com/musagenius/ocrapp/MainActivity.kt:48-89, app/src/main/res/values/strings.xml:5-7