Getting Started

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• ROADMAP.md
• app/src/main/AndroidManifest.xml
• app/src/main/java/com/musagenius/ocrapp/MainActivity.kt
• app/src/main/java/com/musagenius/ocrapp/data/ocr/OCRServiceImpl.kt
• app/src/main/assets/tessdata/README.md
• app/src/main/java/com/musagenius/ocrapp/presentation/viewmodel/OCRViewModel.kt
• app/src/main/java/com/musagenius/ocrapp/domain/model/OCRConfig.kt

This document provides a technical overview for developers to get started with the Material Expressive Android OCR App. The project is an offline-first Android application for extracting text from images using the Tesseract OCR engine. It is built with a modern tech stack, including Jetpack Compose for the UI, and follows Clean Architecture principles for maintainability and testability.

The core value propositions are its offline capability, modern Material Design 3 interface, multi-language support, and a privacy-first approach where all processing occurs on the device. The target audience includes students, professionals, and any user needing on-the-go text extraction, especially in areas with limited internet.

Sources: README.md:1-12, ROADMAP.md:5-18

Architecture

The application is built using MVVM (Model-View-ViewModel) combined with Clean Architecture principles. This separates concerns into distinct layers, making the codebase decoupled, easier to maintain, and highly testable.

Sources: README.md:43-55

This diagram illustrates the separation of concerns into Presentation, Domain, and Data layers, with dependencies flowing inwards towards the Domain layer.

Sources: README.md:103-115, ROADMAP.md:49-56

Layer Descriptions

• Presentation Layer: Contains the UI built with Jetpack Compose and ViewModels that manage UI state and handle user events.
  • Sources: app/src/main/java/com/musagenius/ocrapp/MainActivity.kt, app/src/main/java/com/musagenius/ocrapp/presentation/viewmodel/OCRViewModel.kt
• Domain Layer: The core of the application, containing business logic. It includes Use Cases (e.g., ProcessImageUseCase), domain models (e.g., ScanResult), and repository interfaces. This layer is independent of any framework.
  • Sources: README.md:48-49, app/src/main/java/com/musagenius/ocrapp/presentation/viewmodel/OCRViewModel.kt:19
• Data Layer: Responsible for data operations. It includes repository implementations that fetch data from local sources (Room database) or external services (Tesseract OCR engine). It also handles data mapping between domain models and data entities.
  • Sources: README.md:50-51, app/src/main/java/com/musagenius/ocrapp/data/ocr/OCRServiceImpl.kt

Core Technologies

The project utilizes a modern Android technology stack to ensure robustness, performance, and maintainability.

Technology	Description	Source File(s) -
Jetpack Compose	The UI is built entirely with Jetpack Compose and Material 3 components for a modern, declarative UI.	README.md:15-23 -
Tesseract (tess-two)	The core OCR engine, used via the tess-two library. It enables offline text recognition.	README.md:25-36 -
CameraX	The modern Jetpack library for camera integration, used for capturing images to be processed by OCR.	README.md:57-67 -
Room	The recommended persistence library for local data storage, used to save and manage OCR scan history.	README.md:73-85 -
Hilt	Jetpack's recommended dependency injection library, used to manage dependencies throughout the application.	README.md:87-99 -
Kotlin Coroutines	Used for managing background threads for I/O-intensive tasks like OCR processing and database access.	README.md:101-111 -

Sources: README.md:13-111

Setup and Configuration

Android Permissions

The application requires several permissions to function correctly. These are declared in the AndroidManifest.xml file.

| Permission | Max SDK | Description - | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| android.permission.CAMERA | - | Essential for using CameraX to capture images for OCR. - |
| android.permission.READ_EXTERNAL_STORAGE | 32 | Required to read images from the gallery on older Android versions. - |
| android.permission.WRITE_EXTERNAL_STORAGE| 28 | Required for saving files on older Android versions. Marked with tools:ignore="ScopedStorage". - |
| android.permission.READ_MEDIA_IMAGES | - | Required to read images from media storage on Android 13 (API 33) and higher. - |

Sources: app/src/main/AndroidManifest.xml:13-20

Tesseract tessdata Setup

A critical step for this application to work is providing the Tesseract trained data files (.traineddata). These files are not included in the repository due to their size and must be added manually.

1. Download Language Files: Download the required .traineddata files from one of the official Tesseract repositories:
   • Best (Recommended): `https://github.com/tesseract-ocr/tessdata_best%60
   • Fast: `https://github.com/tesseract-ocr/tessdata_fast%60
2. Place Files: Place the downloaded files into the app/src/main/assets/tessdata/ directory.
3. Automatic Copy: The application is configured to automatically copy these files from the assets folder to the app's storage directory on first use. The OCRServiceImpl handles this logic.

The OCRServiceImpl checks for the existence of the language file in the app's data path. If not found, it attempts to copy it from the assets/tessdata folder.

Sources: app/src/main/assets/tessdata/README.md, app/src/main/java/com/musagenius/ocrapp/data/ocr/OCRServiceImpl.kt:60-66, 203-224

Application Flow

Navigation

The application uses Jetpack Navigation Compose for its navigation graph. The entry point is the CameraScreen. The flow is defined in MainActivity.kt.

This diagram shows the primary navigation paths between the Camera, Image Editor, and OCR Result screens.

Sources: app/src/main/java/com/musagenius/ocrapp/MainActivity.kt:41-110

Core OCR Processing Workflow

The main workflow involves capturing an image, processing it via the OCRViewModel, and displaying the results.

The diagram below shows the sequence of interactions between the key components during OCR processing.

Workflow Steps:

1. The OCRResultScreen is loaded with an image URI and triggers the ProcessImage event in the OCRViewModel.
2. The OCRViewModel cancels any existing OCR job and calls the ProcessImageUseCase.
3. The ProcessImageUseCase interacts with the OCRServiceImpl to perform the text recognition.
4. OCRServiceImpl ensures Tesseract is initialized for the correct language, preprocesses the image, and uses the TessBaseAPI to extract text.
5. The result, containing the extracted text and confidence score, is passed back up through the layers as a Flow.
6. The OCRViewModel updates the OCRUiState, which the OCRResultScreen observes to display the outcome.
7. If the user chooses to save, the SaveToHistory event is triggered, and the OCRViewModel uses the ScanRepository to persist the ScanResult in the Room database.

Sources: app/src/main/java/com/musagenius/ocrapp/presentation/viewmodel/OCRViewModel.kt:61-118, 148-191, app/src/main/java/com/musagenius/ocrapp/data/ocr/OCRServiceImpl.kt:96-146

OCR Configuration

OCR processing can be customized using the OCRConfig data class. This allows for adjustments to language, image preprocessing, and Tesseract's internal modes.

| Parameter | Type | Default Value | Description - |
| language | String | "eng" | The language code for OCR (e.g., "eng", "fra"). Determines which .traineddata file to use. - |
| pageSegmentationMode | PageSegMode | AUTO | Tesseract's Page Segmentation Mode (PSM). AUTO (3) is the default. - |
| engineMode | EngineMode | DEFAULT | Tesseract's OCR Engine Mode (OEM). DEFAULT (3) uses the best available engine. - |
| preprocessImage | Boolean | true | If true, the image will be preprocessed (e.g., grayscale, scaling) before OCR. - |
| maxImageDimension | Int | 2000 | The maximum width or height in pixels to which an image is scaled during preprocessing.