Feature: Document Edge Detection
Relevant source files
The following files were used as context for generating this wiki page:- app/src/main/java/com/musagenius/ocrapp/data/camera/DocumentEdgeDetector.kt
- app/src/main/java/com/musagenius/ocrapp/presentation/ui/camera/DocumentOverlay.kt
- TODO.md
- ROADMAP.md
- app/src/main/AndroidManifest.xml
- app/src/main/java/com/musagenius/ocrapp/data/ocr/ImagePreprocessor.kt
- app/src/main/java/com/musagenius/ocrapp/MainActivity.kt
The Document Edge Detection feature is designed to analyze frames from the live camera preview to identify the boundaries of a rectangular document. Its primary purpose is to provide real-time visual feedback to the user, guiding them to position their camera correctly for a clear and well-aligned capture. This enhances the user experience and improves the quality of the image sent for OCR processing.
This feature is part of the CameraX integration and consists of two main components: a detector that processes camera frames and a UI overlay that renders the detected edges. The project's TODO.md and ROADMAP.md files list "Document edge detection preview overlay" as a key feature for the camera screen, indicating its importance in the application's design.
Sources: TODO.md:65, ROADMAP.md:158, app/src/main/java/com/musagenius/ocrapp/data/camera/DocumentEdgeDetector.kt:12-13
Architecture Overview
The feature follows a clean separation of concerns, with the detection logic in the data layer and the rendering in the presentation layer.
- CameraX Frame Provider: The camera provides frames as
ImageProxyobjects. DocumentEdgeDetector(Data Layer): A singleton service that takes anImageProxy, processes it, and attempts to find the four corners of a document.DocumentCorners(Data Model): A simple data class that holds the coordinates of the detected corners and a confidence score.DocumentOverlay(Presentation Layer): A Jetpack Compose composable that receivesDocumentCornersand draws a visual overlay on top of the camera preview.
This flow is illustrated in the diagram below.
This diagram shows the data flow from the camera frame to the final UI overlay.
Sources: app/src/main/java/com/musagenius/ocrapp/data/camera/DocumentEdgeDetector.kt:80, app/src/main/java/com/musagenius/ocrapp/presentation/ui/camera/DocumentOverlay.kt:17
Core Logic: DocumentEdgeDetector
The DocumentEdgeDetector class is the brain of the feature. It's a Hilt @Singleton responsible for processing image frames to find document boundaries.
Sources: app/src/main/java/com/musagenius/ocrapp/data/camera/DocumentEdgeDetector.kt:16-17
Detection Pipeline
The detection process is executed within the detectEdges suspend function, which runs on the Dispatchers.Default coroutine dispatcher for performance.
- Image Conversion: The input
ImageProxyis converted to aBitmap. This is done by extracting the Y (luminance) plane from theYUV_420_888format, which effectively creates a grayscale image. - Downsampling: The bitmap is scaled down by a factor of 4 to improve processing speed.
- Edge Detection: A simple contrast-based edge detection algorithm (
detectEdgesSimple) is run on the scaled-down bitmap to identify pixels with a high brightness gradient. - Region Finding: The algorithm finds "bright regions" which are assumed to be part of the document.
- Bounding Box Calculation: An axis-aligned bounding box (
findAxisAlignedBoundingBox) is calculated around the detected edge points. - Filtering: The detected area is filtered based on its ratio to the total image area to discard invalid detections. It must be between 10% and 90% of the image area.
- Confidence Score: A confidence score is calculated based on the density of detected edge points and the area ratio.
- Scaling Up: The final corner coordinates are scaled back up to match the original image dimensions before being returned as a
DocumentCornersobject.
The following diagram illustrates this internal pipeline.
This diagram outlines the steps inside the DocumentEdgeDetector to process an image frame.
Sources: app/src/main/java/com/musagenius/ocrapp/data/camera/DocumentEdgeDetector.kt:80-97, app/src/main/java/com/musagenius/ocrapp/data/camera/DocumentEdgeDetector.kt:127-133, app/src/main/java/com/musagenius/ocrapp/data/camera/DocumentEdgeDetector.kt:216-219
Key Data Structures
The feature relies on a few key data classes.
This class diagram shows the relationship between the main detector class and its data models.
Sources: app/src/main/java/com/musagenius/ocrapp/data/camera/DocumentEdgeDetector.kt:29, app/src/main/java/com/musagenius/ocrapp/data/camera/DocumentEdgeDetector.kt:73
DocumentCorners Data Class
This data class encapsulates the result of a detection operation.
| Field | Type | Description |
|---|---|---|
topLeft | Point | The top-left corner of the detected document. |
topRight | Point | The top-right corner of the detected document. |
bottomRight | Point | The bottom-right corner of the detected document. |
bottomLeft | Point | The bottom-left corner of the detected document. |
confidence | Float | A score from 0.0 to 1.0 indicating the reliability of the detection. |
isReliable() | Boolean | A helper function that returns true if the confidence is greater than 0.5. |
Sources: app/src/main/java/com/musagenius/ocrapp/data/camera/DocumentEdgeDetector.kt:29-40
Detection Parameters
The detection algorithm is configured with several internal constants.
| Constant | Value | Description |
|---|---|---|
MIN_CONTOUR_AREA_RATIO | 0.1f | The minimum area a detected document can occupy relative to the image. |
MAX_CONTOUR_AREA_RATIO | 0.9f | The maximum area a detected document can occupy relative to the image. |
EDGE_THRESHOLD | 50 | The brightness gradient threshold for a pixel to be considered an edge. |
Sources: app/src/main/java/com/musagenius/ocrapp/data/camera/DocumentEdgeDetector.kt:21-23
UI Rendering: DocumentOverlay
The DocumentOverlay is a @Composable function that visually represents the detected document corners on top of the camera preview.
Sources: app/src/main/java/com/musagenius/ocrapp/presentation/ui/camera/DocumentOverlay.kt:16
Drawing Logic
The overlay is drawn on a Canvas and updates whenever new DocumentCorners are provided.
- Scaling: It first calculates the scale factors required to map the corner coordinates from the camera's resolution to the view's dimensions.
- Outline: It draws a path connecting the four scaled corner points. The path is filled with a semi-transparent color and stroked with a dashed line.
- Corner Markers: It draws small, L-shaped markers at each of the four corners to make them more prominent.
Sources: app/src/main/java/com/musagenius/ocrapp/presentation/ui/camera/DocumentOverlay.kt:40-44, app/src/main/java/com/musagenius/ocrapp/presentation/ui/camera/DocumentOverlay.kt:70-85, app/src/main/java/com/musagenius/ocrapp/presentation/ui/camera/DocumentOverlay.kt:100-119
Visual States
The overlay provides clear visual feedback based on the quality of the detection.
| State | Visual Cue | Trigger |
|---|---|---|
| Reliable | Green, pulsing outline and fill. | corners.isReliable() returns true. |
| Uncertain | Amber (yellow-orange) outline and fill with a fixed, low alpha. | corners.isReliable() returns false. |
| No Detection | The overlay is not drawn. | corners object is null. |
An InfiniteTransition is used to create a gentle pulsing animation for the alpha value of the overlay when the detection is reliable, drawing the user's attention.
Sources: app/src/main/java/com/musagenius/ocrapp/presentation/ui/camera/DocumentOverlay.kt:22-30, app/src/main/java/com/musagenius/ocrapp/presentation/ui/camera/DocumentOverlay.kt:78-82
Integration and Permissions
The feature requires camera access to function.
Permissions
The application manifest requests the necessary camera permissions.
<!-- Camera permissions for CameraX -->
<uses-feature
android:name="android.hardware.camera"
android:required="false" />
<uses-permission android:name="android.permission.CAMERA" />
Sources: app/src/main/AndroidManifest.xml:5-9, app/src/main/AndroidManifest.xml:13
UI Integration
The DocumentEdgeDetector and DocumentOverlay are intended to be used within the CameraScreen. The MainActivity sets up navigation to the CameraScreen, which is the entry point for this feature. While the full integration is not shown in the provided files, the CameraScreen would be responsible for instantiating an ImageAnalysis use case from CameraX, passing each frame to DocumentEdgeDetector, and feeding the resulting DocumentCorners to the DocumentOverlay composable.
Sources: app/src/main/java/com/musagenius/ocrapp/MainActivity.kt:43-53, TODO.md:65
Conclusion
The Document Edge Detection feature is a well-architected system for providing real-time guidance during document capture. It effectively separates the complex image processing logic in DocumentEdgeDetector from the UI rendering in DocumentOverlay. By using a confidence score and providing clear visual feedback (color changes and animations), it creates an intuitive user experience that helps improve the quality of images captured for OCR, thereby increasing the overall accuracy and reliability of the application.