Repository navigation
docs android ocr live framing
AlexandreZanata edited this page Nov 21, 2026
·
1 revision
This is the step left open by p37-ocr-auto-framing ("No framing or zoom before the photo"); the post-photo framing, readings and reconciliation there are unchanged.
No preview frame, token or label is stored, logged or committed (B-BR-OM08).
-
Need: live framing needs the camera preview frames and a zoom control
inside the app. The system camera (
ActivityResultContracts.TakePicture) returns only the final file, so neither is possible without an in-app camera. Camera2 alone would mean writing session, rotation, focus and resolution handling by hand; CameraX is the Jetpack camera library. -
Artifacts:
androidx.camera:camera-core,camera-camera2,camera-lifecycle,camera-view, all pinned at1.4.2(stable, released 2025;1.5.xwas not taken because it is not needed and asks for newer build tooling than AGP 8.7.3 / compileSdk 35). No dynamic versions. Transitives resolved from Google Maven:camera-video1.4.2 (pulled bycamera-view),androidx.appcompat1.1.0 runtime floor,concurrent-futures, Guavalistenablefuture,auto-value-annotations,exifinterface(already pinned at 1.3.7),tracing,lifecycle-livedata. -
License: CameraX is Apache-2.0 (POM
licenses).camera-corealso declares BSD-3-Clause for the bundled libyuv native code (libimage_processing_util_jni.so). Both are listed inTHIRD_PARTY_NOTICES.md. -
Security review: AndroidX, published by Google on Google Maven and
fetched over HTTPS. No new permission:
CAMERAwas already declared and requested before capture. No network access, analytics or upload in the library. The native library is limited by the existingabiFilters; the release artifact check (scripts/android/artifact.py) still requires the map engine in every shipped ABI. -
Build: the artifacts were not in the Gradle offline cache, so the first
build after this change needs one online dependency download; later builds
can run
--offlineagain.
-
In-app camera first. After the capture receipt is granted and
beginCamerasucceeds, the app opens its own full-screen camera instead of the system camera. It is its own full-screen window above the app's bottom bar. The photo (the camera's largest 4:3 size) is written to the same private file created byPrivateCaptureFilesand goes through the sameacceptCameraPhotocheck, review screen and post-photo OCR. When CameraX cannot bind (no back camera, camera in use, library failure), the same file is handed to the system camera as before. The in-app camera writes no location into the photo file. -
Live analysis finds the board. Preview frames (about 1280 x 960) are
read on device by the same ML Kit recognizer and
FuelBoardFraming.locaterule as the post-photo path. Only the latest frame is analysed; a slow reading drops frames instead of queueing them. A frame is held in memory only while it is read; nothing from the analysis is uploaded, stored, logged or persisted in saved state. -
Zoom decision (
LiveBoardZoom, pure). With the board's rectangle as fractions of the analysed frame and the zoom ratio of that frame:- target ratio = current ratio x
TARGET_FILL(0.8) / the board's larger side fraction, so the board fills most of the frame; - the zoom crops around the centre, so the ratio is also limited until the board's farthest edge from the centre stays inside the frame with a 5% margin: an off-centre board is never zoomed out of view;
- the ratio is bounded by the device's zoom range and by
MAX_RATIO(5x, the review screen's zoom limit), and never goes below the wide ratio (1x, or the device minimum when that is higher); - hysteresis: the ratio changes only after the board was found in two analyses in a row and only when the new ratio differs from the current one by more than 15% (a board that already fills 70% to 94% of the frame keeps the zoom still), or when it reaches a bound of the range;
- no board: the zoom is held for six analyses without a board, then returns to the wide ratio so the contributor can find the board again;
- a frame read while the zoom was still changing is not used.
- target ratio = current ratio x
- Manual control wins. If the contributor pinches to zoom, the automatic zoom stops for the rest of that camera session; the frame overlay and hint keep working. Tap to focus is the library's default.
-
Overlay and hint. While a board is found, a rounded frame in the accent
color is drawn around it and a pill says the board was found; otherwise a
neutral pill asks to point at the board. The current zoom is shown as, for
example,
2.4x. -
Never captures by itself. Only the shutter button takes the photo.
The capture receipt window (
beginCamera/acceptCameraPhoto) is checked exactly as before: a photo taken after the receipt's camera window closed is refused and its file deleted. Closing the camera (close button or back) deletes the pending file and behaves as a cancelled system camera. - Unchanged. The 24-hour private file handling, the review screen, the post-photo framing and OCR, the 15-second recognition timeout, human review before sending and the evidence photo (never cropped automatically).
- Unit:
LiveBoardZoomTest(9 cases: target ratio, device and product bounds, wide floor, centre limit, hysteresis, bound reach, confirmation, no board, invalid rectangle);CaptureOcrViewModelTest(a photo arriving after the receipt's camera window closed is refused, whatever camera produced it). Totals::domain935,:application532,:data731 (4 skipped),:app740. - Build:
:app:assembleDebug,:app:assembleDebugAndroidTest,:data:assembleDebugAndroidTest;:app:lintDebugreports no new error (the one remaining error,home_open_mapmissing translations, predates this change). - Device, generated pixels only (
am instrumenton the POCO 2311DRK48G, API 36):LiveBoardLocatorDeviceTestfeeds real YUV_420_888Images through anImageReader: the board is located in an upright frame and in a sensor-rotated frame (rotation 90), an empty scene gives no board and a closed session gives none. WithOcrFormatMatrixDeviceTest,OcrFramingDeviceTestand the syntheticRealImageOcrDeviceTestcase:OK (10 tests), far-board and dark-board results unchanged. - Phone, real flow (Comunidade → contribute → station → photograph): the
in-app camera opens full screen over the bottom bar with the 4:3 preview,
1,0x, the corner guides and the "point at the board" hint; the close button and the back key both show "capture cancelled" and delete the pending file; the shutter writes a 2448 x 3264 upright JPEG (the largest 4:3 size CameraX offers on this phone) without GPS tags, and the review opens with the photo attached and the post-photo OCR result. Nothing was sent. - Not verified on the phone: the automatic zoom and the board frame on a real price board (the phone lay facing the ceiling; nobody aimed it at a board), the pinch override, the system-camera fallback, and recovery after process death with the camera open.
- No accuracy measurement of the live path: the private evaluation sets are still photos, so they cannot exercise preview frames. The post-photo numbers in p37-ocr-auto-framing remain the only measurement.
- No flash/torch control, no lens switching beyond what the zoom ratio selects on a logical multi-camera, no front camera.
- Home
- Roadmap
- docs-README
- docs-android-build
- docs-android-design-system
- docs-android-forum
- docs-android-games
- docs-android-map-engine
- docs-android-navigation
- docs-android-ocr-image
- docs-android-ocr-live-framing
- docs-android-premium-area
- docs-android-premium-integration
- docs-android-release
- docs-android-ui-containers
- docs-architecture-android-stack
- docs-architecture-android
- docs-architecture-backend
- docs-architecture-data-sources
- docs-architecture-overview
- docs-architecture-sources-ev-research
- docs-architecture-sources-national-limits
- docs-architecture-sources-national-stations
- docs-architecture-sources-register
- docs-assets-app-tutorial-CAPTURE_CONTRACT
- docs-assets-app-tutorial-FABLE_LANDING_POLISH_PROMPT
- docs-assets-app-tutorial-README
- docs-assets-attribution
- docs-assets-brand-README
- docs-assets-flags-ATTRIBUTION
- docs-assets-fuel-icons-README
- docs-assets-games-fuel-v1-README
- docs-assets-home-icons-README
- docs-assets-landing-fleet-android-20261012-BRIEF
- docs-assets-landing-hero-20261011-BRIEF
- docs-assets-landing-illustrated-20261012-BRIEF
- docs-assets-landing-illustrated-20261012-README
- docs-assets-landing-minimal-20261012-BRIEF
- docs-assets-landing-open-data-20261026-BRIEF
- docs-assets-landing-redesign-20261011-PREPARATION_EVIDENCE
- docs-assets-landing-redesign-20261011-README
- docs-assets-landing-redesign-20261011-REFERENCE_BRIEF
- docs-assets-landing-sync-20261012-BRIEF
- docs-assets-map-icons-README
- docs-backend-anp-ingestion
- docs-backend-api
- docs-backend-community-pricing
- docs-backend-data-model
- docs-backend-domain-model
- docs-backend-driver-private-data
- docs-backend-forum-architecture
- docs-backend-forum-bulletins
- docs-backend-forum-sources
- docs-backend-payments-provider-admission
- docs-backend-payments-provider-register
- docs-backend-photos-capture
- docs-backend-photos-subset-submission
- docs-backend-premium-api
- docs-backend-premium-cloud-protocol
- docs-backend-testing
- docs-backend-toolchain
- docs-brand-app-icons
- docs-brand-identity
- docs-decisions-001-kotlin-compose-stack
- docs-decisions-002-price-import-immutability
- docs-decisions-003-nominatim-reverse-geocode
- docs-decisions-005-modular-monolith-and-postgresql
- docs-decisions-006-official-catalog-and-exact-contracts
- docs-decisions-007-anonymous-proof-of-possession
- docs-decisions-008-privacy-and-retention
- docs-decisions-009-community-consensus-and-projections
- docs-decisions-010-private-object-evidence
- docs-decisions-012-licensing-and-hosted-business
- docs-decisions-015-kotlin-multiplatform-shared-domain
- docs-decisions-016-android-commercial-community-ios-deferred
- docs-decisions-017-station-profile-and-verified-representation
- docs-decisions-021-community-first-contribution
- docs-decisions-022-comaps-derived-native-map-engine
- docs-decisions-023-admin-suite-granted-tiers-contributors
- docs-decisions-025-private-abastevo-empresas-organization-boundary
- docs-decisions-026-multilingual-public-site
- docs-decisions-README
- docs-enterprise-README
- docs-enterprise-architecture
- docs-enterprise-backlog-INDEX
- docs-enterprise-backlog-ep00-governance
- docs-enterprise-backlog-ep01-platform
- docs-enterprise-backlog-ep02-organizations
- docs-enterprise-backlog-ep03-identity-access
- docs-enterprise-backlog-ep04-sync
- docs-enterprise-backlog-ep05-fleet-meters
- docs-enterprise-backlog-ep06-trips
- docs-enterprise-backlog-ep07-gps-navigation
- docs-enterprise-backlog-ep08-fuelings
- docs-enterprise-backlog-ep09-documents
- docs-enterprise-backlog-ep10-expenses-finance
- docs-enterprise-backlog-ep11-maintenance
- docs-enterprise-backlog-ep12-fuel-stock
- docs-enterprise-backlog-ep13-intelligence
- docs-enterprise-backlog-ep14-station-claims
- docs-enterprise-backlog-ep15-station-commerce
- docs-enterprise-backlog-ep16-subscriptions
- docs-enterprise-backlog-ep17-data
- docs-enterprise-backlog-ep18-imports-notifications-integrations
- docs-enterprise-backlog-ep19-back-office
- docs-enterprise-backlog-ep20-release
- docs-enterprise-business-rules
- docs-enterprise-contract
- docs-enterprise-conventions
- docs-enterprise-data-offering
- docs-enterprise-decisions
- docs-enterprise-domain-model
- docs-enterprise-glossary
- docs-enterprise-journeys
- docs-enterprise-modules-back-office
- docs-enterprise-modules-data
- docs-enterprise-modules-documents
- docs-enterprise-modules-expenses-finance
- docs-enterprise-modules-fleet
- docs-enterprise-modules-fuel-stock
- docs-enterprise-modules-fuelings
- docs-enterprise-modules-gps-navigation
- docs-enterprise-modules-identity
- docs-enterprise-modules-imports-notifications-integrations
- docs-enterprise-modules-intelligence
- docs-enterprise-modules-maintenance
- docs-enterprise-modules-organizations
- docs-enterprise-modules-station-claims
- docs-enterprise-modules-station-commerce
- docs-enterprise-modules-subscriptions
- docs-enterprise-modules-trips
- docs-enterprise-offline-sync
- docs-enterprise-permissions
- docs-enterprise-portal-routes
- docs-enterprise-privacy-security
- docs-enterprise-product-vision
- docs-enterprise-source-admission
- docs-enterprise-state-model
- docs-enterprise-testing
- docs-enterprise-ux-app
- docs-enterprise-ux-web
- docs-operations-README
- docs-operations-backup
- docs-operations-deploy-agent
- docs-operations-dou-editions
- docs-operations-edge-cache
- docs-operations-enterprise-activation
- docs-operations-map-static-overlay
- docs-operations-moderation-feedback
- docs-operations-moderation-profiles
- docs-operations-monitoring
- docs-operations-operator-access
- docs-operations-payments
- docs-operations-premium-billing
- docs-operations-recovery
- docs-operations-registry-daily-sync
- docs-operations-registry-runs
- docs-product-README
- docs-product-admin-tiers
- docs-product-community-community-first
- docs-product-community-experience
- docs-product-community-metrics
- docs-product-community-moderation
- docs-product-community-safety
- docs-product-community-terms-pt-br
- docs-product-driver-suite-README
- docs-product-driver-suite-android-state
- docs-product-driver-suite-cloud-sync
- docs-product-driver-suite-cost-profiles-and-maintenance
- docs-product-driver-suite-driver-model-and-earnings
- docs-product-driver-suite-foundation-decisions
- docs-product-driver-suite-gps-lifecycle
- docs-product-driver-suite-mobile-hub
- docs-product-driver-suite-odometer-review
- docs-product-driver-suite-outbox-wire
- docs-product-driver-suite-quick-refuel
- docs-product-driver-suite-reports
- docs-product-driver-suite-shifts-and-distance
- docs-product-driver-suite-signed-commands
- docs-product-ev-README
- docs-product-ev-charging-stop-planner
- docs-product-ev-energy-model
- docs-product-ev-financial-method
- docs-product-ev-journey-ui
- docs-product-ev-preparation
- docs-product-ev-typed-data
- docs-product-exploration
- docs-product-forum-contract
- docs-product-forum-policies
- docs-product-glossary
- docs-product-landing-content
- docs-product-landing-guides
- docs-product-landing-organic-growth-i18n-plan
- docs-product-licensing
- docs-product-map-discovery
- docs-product-map-favorites-and-trips
- docs-product-map-reports-routing-guidance
- docs-product-notification-content
- docs-product-official-prices
- docs-product-open-source-business
- docs-product-overview
- docs-product-payments-README
- docs-product-payments-offer-policy
- docs-product-premium-README
- docs-product-premium-financial-method
- docs-product-premium-source-policy
- docs-product-stations-catalog
- docs-product-stations-fuel-feedback
- docs-product-stations-fuel-quality
- docs-product-stations-identity-and-ev-catalog
- docs-product-stations-profile-contract
- docs-product-stations-profile-representation
- docs-product-stations-registry-sources
- docs-product-vehicle-registration
- docs-product-vehicles-and-occurrences
- docs-security-android-terms-acceptance
- docs-security-free-account-access
- docs-security-identity-profile
- docs-security-media-location-policy
- docs-security-privacy-notice
- docs-security-privacy-policy
- docs-security-retention
- docs-security-risks
- docs-security-security-privacy
- docs-store-README
- docs-store-play-readiness
- docs-store-play-store-listing
- docs-store-ugc-safety
Source: AlexandreZanata/Abastevo @ e4a67580fc368a59bc1c0f1e0466fc011313f330