Feature: Image Preprocessing & Quality Validation

Relevant source files

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

• app/src/main/java/com/musagenius/ocrapp/data/ocr/ImagePreprocessor.kt
• app/src/main/java/com/musagenius/ocrapp/domain/usecase/ValidateImageQualityUseCase.kt
• app/src/main/java/com/musagenius/ocrapp/domain/model/OCRResult.kt
• app/src/test/java/com/musagenius/ocrapp/domain/model/ImageQualityTest.kt
• app/src/main/java/com/musagenius/ocrapp/data/ocr/OCRServiceImpl.kt
• app/src/main/java/com/musagenius/ocrapp/domain/model/OCRConfig.kt
• ROADMAP.md

The Image Preprocessing and Quality Validation feature is a critical component of the OCR application, designed to maximize text recognition accuracy. It consists of two main functions: assessing the quality of an input image to provide user feedback, and applying a series of transformations to standardize and enhance the image before it is fed into the Tesseract OCR engine. This ensures that images are in an optimal state for processing, handling common issues like poor lighting, low contrast, excessive size, and blurriness.

This system is primarily implemented in the ImagePreprocessor class, which is invoked by the OCRServiceImpl during the text recognition flow. A dedicated use case, ValidateImageQualityUseCase, exposes the quality assessment logic to the domain layer, allowing the UI to check image quality proactively.

Sources: ROADMAP.md, app/src/main/java/com/musagenius/ocrapp/data/ocr/ImagePreprocessor.kt, app/src/main/java/com/musagenius/ocrapp/domain/usecase/ValidateImageQualityUseCase.kt

Architecture and Components

The feature is composed of several key classes that interact to provide preprocessing and validation services. The ImagePreprocessor is the core component in the data layer, containing all the logic for image manipulation and analysis. The ValidateImageQualityUseCase acts as a bridge to the domain layer, and the ImageQuality data class models the assessment results.

This diagram illustrates the primary components and their relationships.

Image Quality Assessment

Before processing, an image can be analyzed to determine if its quality is sufficient for accurate OCR. This is handled by the assessImageQuality method in ImagePreprocessor and exposed through the ValidateImageQualityUseCase.

Sources: app/src/main/java/com/musagenius/ocrapp/data/ocr/ImagePreprocessor.kt:133-156, app/src/main/java/com/musagenius/ocrapp/domain/usecase/ValidateImageQualityUseCase.kt:15-24

Quality Metrics

The assessment is based on three key metrics:

1. Sharpness (Blur Score): Calculated using a Laplacian filter on a 100x100 pixel sample from the center of the image. The variance of the Laplacian is normalized to a score between 0.0 (blurry) and 1.0 (sharp).
2. Brightness Score: The average grayscale value of the image, sampled every 10th pixel for performance. The result is normalized to a score between 0.0 (dark) and 1.0 (bright).
3. Resolution: The total number of pixels (width * height).

Sources: app/src/main/java/com/musagenius/ocrapp/data/ocr/ImagePreprocessor.kt:134-136, app/src/main/java/com/musagenius/ocrapp/data/ocr/ImagePreprocessor.kt:162-187, app/src/main/java/com/musagenius/ocrapp/data/ocr/ImagePreprocessor.kt:193-206

Assessment Logic

The calculated metrics are compared against predefined thresholds to generate warnings and determine if the image is of acceptable quality.

Metric	Condition	Warning Message	isAcceptable Impact
blurScore	< 0.3f	"Image is very blurry"	false
blurScore	< 0.6f	"Image may be slightly blurry"	No
brightnessScore	< 0.3f	"Image is too dark"	false (if < 0.2f)
brightnessScore	> 0.9f	"Image may be overexposed"	false (if > 0.95f)
resolution	< 500,000	"Image resolution is low"	No

The isAcceptable flag is ultimately set to true only if blurScore >= 0.3f and brightnessScore is within the range 0.2f..0.95f.

Sources: app/src/main/java/com/musagenius/ocrapp/data/ocr/ImagePreprocessor.kt:140-154

The ImageQuality Model

The result of the assessment is encapsulated in the ImageQuality data class.

// Source: app/src/main/java/com/musagenius/ocrapp/domain/model/OCRResult.kt:56-70
data class ImageQuality(
    val isAcceptable: Boolean,
    val blurScore: Float, // 0.0 (blurry) to 1.0 (sharp)
    val brightnessScore: Float, // 0.0 (too dark) to 1.0 (good)
    val resolution: Int, // in pixels (width * height)
    val warnings: List<String> = emptyList()
)

This model also includes a helper function, needsPreprocessing(), which returns true if the brightness is below 0.5f or the blur score is below 0.6f. This can be used to decide whether to run the full preprocessing pipeline.

Sources: app/src/main/java/com/musagenius/ocrapp/domain/model/OCRResult.kt:75-77, app/src/test/java/com/musagenius/ocrapp/domain/model/ImageQualityTest.kt:13-33

Image Preprocessing Pipeline

If the preprocessImage flag is enabled in the OCRConfig, the OCRServiceImpl will invoke the preprocessImage method in ImagePreprocessor. This method applies a sequence of transformations to the image.

The following diagram shows the flow of the preprocessing pipeline.

1. Scaling

The image is first checked against a maxDimension (defaulting to 2000 pixels). If either its width or height exceeds this value, it is scaled down proportionally while maintaining its aspect ratio. This prevents performance issues and out-of-memory errors with very large images.

Sources: app/src/main/java/com/musagenius/ocrapp/data/ocr/ImagePreprocessor.kt:27, app/src/main/java/com/musagenius/ocrapp/data/ocr/ImagePreprocessor.kt:39-56, app/src/main/java/com/musagenius/ocrapp/domain/model/OCRConfig.kt:9

2. Grayscale Conversion

The scaled image is converted to grayscale. This simplifies the image data for the OCR engine, as color information is not needed for text recognition. The conversion uses a standard luminance formula: Gray = 0.299 * Red + 0.587 * Green + 0.114 * Blue.

Sources: app/src/main/java/com/musagenius/ocrapp/data/ocr/ImagePreprocessor.kt:30, app/src/main/java/com/musagenius/ocrapp/data/ocr/ImagePreprocessor.kt:61-77

3. Contrast Enhancement

Finally, the contrast of the grayscale image is enhanced using histogram stretching. The algorithm finds the minimum and maximum gray values in the image and then remaps all pixel values to span the full 0-255 range. This makes the text stand out more clearly from the background.

Sources: app/src/main/java/com/musagenius/ocrapp/data/ocr/ImagePreprocessor.kt:33, app/src/main/java/com/musagenius/ocrapp/data/ocr/ImagePreprocessor.kt:82-108

Integration with OCR Service

The ImagePreprocessor is a dependency of OCRServiceImpl and is used within the main text recognition methods. The decision to preprocess is controlled by the OCRConfig object passed to the service.

This sequence diagram shows how OCRServiceImpl utilizes the ImagePreprocessor.

Configuration

The behavior of the preprocessing pipeline can be configured via the OCRConfig data class.

Parameter	Type	Default	Description
preprocessImage	Boolean	true	If true, the full preprocessing pipeline is executed.
maxImageDimension	Int	2000	The maximum width or height for an image before it is scaled down.
enableAutoRotation	Boolean	false	A flag for enabling auto-rotation, though the implementation for its use is not detailed in the provided files beyond a rotateBitmap utility function.

Sources: app/src/main/java/com/musagenius/ocrapp/domain/model/OCRConfig.kt:5-10, app/src/main/java/com/musagenius/ocrapp/data/ocr/ImagePreprocessor.kt:221-229

Summary

The Image Preprocessing and Quality Validation system is a foundational feature for ensuring the reliability and accuracy of the OCR service. By programmatically assessing image quality, the application can provide actionable feedback to the user. The automated preprocessing pipeline—comprising scaling, grayscale conversion, and contrast enhancement—transforms images into an optimal format for Tesseract, significantly improving the chances of successful text extraction from a wide variety of source images.