ar_location_view 3.3.0
ar_location_view: ^3.3.0 copied to clipboard
Location-based augmented reality: shows labels for geolocated points of interest over the camera preview, stacked so that every POI stays visible.
3.3.0 #
Bug fixes
ArViewno longer replaces a location error (e.g. location services disabled) by an endless loading indicator: the error used to be cleared by the next compass sample, which carries no location. It is now kept until a location arrives. A permission error is still cleared by any sample, since the sensors only start once the permission is granted.ArViewadopts a newsensorSourcewhen its parent passes another one (it kept listening to the first one), and reads the device field of view whencameraFieldOfViewgoes back to null.- Annotations sharing a
uidno longer break the overlay ("Duplicate keys found"): only the first one is laid out, and debug builds print a warning. AttitudeFilterandHeadingFilterignore a NaN or infinite sample instead of returning NaN until the nextreset();ArSensorManagerdrops such compass events.- The radar is really centered at
RadarPosition.topCenter/bottomCenter(it was 8 px off), and its default size is half of the short side of the view instead of half of its width, which did not fit a landscape view. Nothing changes in portrait or withradarWidth. - POIs at exactly the same distance are ordered by
uid, so their rows cannot swap from one frame to the next. - iOS:
ArSensor.compassAccuracygoes back to-1when the heading becomes invalid instead of keeping the last valid value. - iOS: when true north is not available to Core Motion, the attitude falls back to magnetic north instead of the compass stream staying silent.
Rendering
- While the device moves,
ArViewno longer rebuilds, lays out nor repaints the labels: each one is recorded once in its own layer (RepaintBoundary) and moved by aFlowwith a transform, at paint time. The widget tree is only rebuilt when the labels shown, their distance or their groups change. With 100 POIs, about 95% fewer label repaints and 76% fewer widget rebuilds than before. Positions, row animations and taps are unchanged. AttitudeFilterandHeadingFilterare now One-Euro filters: the smoothing relaxes with the rotation speed instead of the gap between the output and the sample. Labels trailed about 4° behind the camera image when turning at 30°/s (≈ 55 px on a phone); they now trail about 1.4°, with slightly less jitter while the device is still.timeConstantkeeps its meaning (smoothing while still) but defaults to 0.5 s instead of 0.25 s, and the newbetasets how fast the smoothing relaxes when turning.fastRotationDegreesis unchanged.
New
onSensorErroronArViewandArLocationWidget: called with every sensor error, including the ones not shown because a location is already known (e.g. location services turned off while the view is running).rowAnimationDurationonArLocationWidget, forwarded toArView.LocationFilter(adaptToSpeed:), on by default: the filter uses the speed reported with a fix when it is higher thanprocessNoise. On a bike or in a vehicle the smoothed location used to trail behind the user (about 40 m at 50 km/h with 10 m fixes, now about 5 m). Nothing changes at walking pace; passadaptToSpeed: falsefor the previous behaviour.- Android:
ArSensor.compassAccuracyuses the heading accuracy estimated by the rotation vector sensor when the device provides it, instead of only three levels (15°, 30°, 45°). ArCamera.onCameraErrorreceives the underlying exception in its message (Camera initialization failed: …) instead of a fixed text.onCameraErrorandonCameraSuccessare now typedvoid Function(String)andVoidCallback.
Android
- The plugin no longer applies the Kotlin Gradle plugin: it is written in Java only.
- Remove the
HIGH_SAMPLING_RATE_SENSORSpermission, which the plugin does not need (it samples at 50 Hz). Declare it in your own manifest if your app reads sensors faster than 200 Hz.
Other
- Remove the unused
plugin_platform_interfacedependency. - The podspec version follows the package version again.
3.2.2 #
- Version bump only.
3.2.1 #
Bug fixes
- Fix the camera preview being squeezed when the app is locked in one orientation while the device is held in the other (e.g. locked in portrait, held in landscape):
CameraPreviewshapes itself after the physical orientation of the device, while the image stays upright for the UI. The preview is now shaped after the UI and covers the view (BoxFit.cover, centered, as the AR projection expects). ArCamera.onPreviewAspectRatioalways reports long side / short side, whichever way the platform reports the preview size.
3.2.0 #
Breaking changes (custom ArSensorSource implementations and code reading ArSensor.orientation)
- Remove the
native_device_orientationdependency: the orientation is now computed by the plugin's native side and sent with the compass events (CompassEvent.orientation).ArSensor.orientationandArMath.calculatePitchuse Flutter'sDeviceOrientation(package:flutter/services.dart) instead ofNativeDeviceOrientation: replaceNativeDeviceOrientation.xbyDeviceOrientation.x. ArSensor.orientationis now the orientation of the UI, whichArSensor.rotationMatrixis relative to, instead of the physical orientation of the device: it staysportraitUpwhen the app is locked in portrait.- Remove
ArSensorBackend.orientation.
3.1.0 #
Performance & battery
ArViewno longer callsannotationViewBuilderfor every annotation on every frame: a label is rebuilt only when itsdistanceFromUseror its grouped annotations change, whenArViewis rebuilt by its parent, or when an inherited widget it depends on changes. If your builder reads state that changes without rebuildingArView, rebuild it (e.g.setStatein its parent).- The
ArSensorManagercreated byArViewis paused while the app is in background (GPS, compass and accelerometer used to keep running). NewArSensorManager.pause()/resume()for managers you provide yourself. - The radar is drawn on its own layer (
RepaintBoundary).
Android
- The compass and gyroscope
<uses-feature>declared by the plugin are nowandroid:required="false", andandroid.hardware.camera.level.fullis removed. They are merged into the app and used to hide it on the Play Store from every device lacking them, notably all devices whose camera is not at the Camera2 FULL level. - Remove the unneeded
INTERNETpermission and the deprecated manifestpackageattribute.
iOS
- Add a privacy manifest (
PrivacyInfo.xcprivacy), raise the minimum to iOS 13 and fill in the podspec metadata.
Camera & permissions
ArCamerashows a loading indicator while the camera permission is requested, instead of "Need camera authorization".- When the camera or location permission was denied and is granted from the system settings, the view starts when the app returns to the foreground. A camera that failed to start is retried on resume.
- New
cameraErrorBuilderonArLocationWidget(errorBuilderonArCamera) to customize the camera error, withArCameraErrorType.
New
- The radar cone matches the camera's horizontal field of view (
RadarPainter.fieldOfView) instead of a fixed ~51°. ArSensorManager(locationSettings:)configures the position stream.ArSensorManager(backend:)/ArSensorBackendreplace the platform streams and permission calls, to test without hardware.
Deprecations
ArView.frameandArLocationWidget.frame, which were unused.- The
ArMathhelpers unused by the package (normalizeDegree,normalizeDegree2,deltaAngle,exponentialFilter,bearing*).ArMath.normalizeDegreeis also fixed: it computed360 % degreeinstead ofdegree % 360.
Other
- Require Dart 3.9 / Flutter 3.35, as the dependencies already did.
- Allow
permission_handler13, which requires the app to compile against Android SDK 37 (compileSdk 37);permission_handler12 is still supported. - Example: latest dependencies, AGP 8.13 / Kotlin 2.3.20, iOS plugins integrated with CocoaPods only (Swift Package Manager disabled).
- Rewritten README, documented parameters, CI (format, analyze, tests, pana, example builds), tests for
ArSensorManager,ArCamera,CompassEventandRadarPainter.
3.0.0 #
Breaking changes
ArAnnotation.arPosition.dxis now the label's left edge in screen coordinates (it used to be an offset in pixels relative to the heading, which rendered annotations shifted by half a screen).- Remove the public
ArSensorManager.pitchHistoryfield. ArViewno longer disposes anArSensorSourcepassed throughsensorSource: its owner is now responsible for callingdispose().ArSensorManager.arSensoris now a broadcast stream and reports failures asArSensorExceptionstream errors.- On Android, the heading is now relative to true north (magnetic declination applied), like on iOS. Where the declination is large, POIs move by that many degrees.
ArSensor.compassAccuracyis now an error in degrees on both platforms, or-1when unknown (Android used to report the raw sensor status, 0–3).ArSensorManagerno longer uses the user accelerometer, and the pitch smoothing is now time-based (~0.5 s time constant instead of ~2 s).ArAnnotation.arPositionis now the label's top-left corner in screen coordinates, the label being centered on the POI (dyused to be a pitch offset added to half the screen height, placing the label's top edge on the horizon).- POIs are now positioned with a 3D projection:
ArSensor.heading/pitchare derived from the device attitude on both platforms and the compass event channel payload now carries a rotation matrix.
Positioning
- Project POIs with the full device attitude (new
ArSensor.rotationMatrix, provided natively on Android and iOS) and a pinhole camera model (ArProjection), instead of a linear degrees-to-pixels mapping on heading and pitch. This accounts for the device roll, removes the heading jump when tilting the device past ±45° on Android, and hides POIs behind the camera. - Use the real camera field of view, read from the device (
ArCameraInfo.backCameraFieldOfView()), instead of a hard-coded 58°. It can be overridden withcameraFieldOfViewonArView/ArLocationWidget. The preview aspect ratio is taken into account to match the cropped preview. - Use the UI orientation as the single screen reference on both platforms (the pitch and field of view used the physical device orientation while the Android heading used the display rotation).
- Center labels vertically on the POI, and only keep POIs whose label intersects the screen vertically too.
- Add opt-in
useAltitudeto place POIs above/below the horizon from their altitude difference with the user. - Fix
ArAnnotation.isVisiblestayingtruefor annotations moved out of range. - Custom
ArSensorSources without a rotation matrix keep working: the attitude is rebuilt fromheadingandpitch(no roll).
Stability
- Smooth the device attitude with an adaptive, time-based filter (
AttitudeFilter): compass jitter is damped while the device is still, fast rotations are followed without lag. Without a rotation matrix, the heading is smoothed the same way, across north (HeadingFilter). - Smooth GPS fixes with a Kalman filter weighted by their accuracy (
LocationFilter), so nearby POIs no longer swing with GPS noise.onLocationChangeand the reported accuracy use the filtered position. - Both filters are configurable, or can be disabled, through the new
ArSensorManagerconstructor parameters. - Keep labels on the same overlap row across frames (
previousRows/AnnotationLayoutResult.rows, withAnnotationLayoutConfig.rowHysteresisof clearance required to move back down), and animate row changes (rowAnimationDurationonArView). - Add opt-in
hideWithinLocationAccuracyto hide POIs closer than the location accuracy. - Labels scaled with
scaleWithDistancenow shrink linearly from 1 down to a configurableminScale(default 0.5) atmaxVisibleDistance, instead of the hard-coded1 - d / (maxVisibleDistance + 280), which went down to ~0.16 and made far labels unreadable. UseminScale: 0.16to get the previous look back. The scale is computed by the layout and exposed asArAnnotation.arScale. - Overlaps are detected on each label's displayed (scaled) width, with a configurable
horizontalSpacingbetween labels: small far labels are no longer pushed onto extra rows by their unscaled size. - Cache each annotation's bearing and distance (
AnnotationGeoCache) instead of recomputing them for every annotation on every frame: they are only recomputed when the user or the annotation moves. ArViewnow projects onto its own size (LayoutBuilder) instead of the screen size, so annotations stay aligned with the camera preview when the view does not fill the screen.- Stop stacking overlapping labels above the top of the screen, and add an optional
maxRowslimit. Annotations that do not fit are grouped into the overlapping visible label whose center is closest (AnnotationLayoutResult.groups), which shows a "+N" badge (customizable withgroupBadgeBuilderonArView/ArLocationWidget). The closest POIs stay visible, the farthest ones are grouped.
Bug fixes
- Fix pitch being underestimated by ~40% (and close to 0 at startup): the exponential filter did not have unit gain. It is replaced by a recursive
LowPassFilter. - Fix annotations being drawn half a screen to the left: a POI straight ahead is now centered, and only POIs inside the displayed horizontal field of view are kept.
- Fix sharing one
ArSensorSourcebetween several views (Stream has already been listened to, and the first view closing the source used by the others).ArSensorManager.init()is now idempotent. - Fix
ArSensorManagerstarting the sensors, and adding events to a closed stream, when disposed while the location permission prompt was open. - Fix
ArCameracallingsetState()afterdispose()when the widget was removed during the permission request or camera initialization. - Fix the camera preview being frozen or broken after the app returns from background: the camera is now released and restarted with the app lifecycle.
- Fix
ArViewshowing a spinner forever when the location permission is denied or location services are disabled. - Fix the camera preview scale, which depended on the screen pixel density: the preview now covers the view (like
BoxFit.cover). - Use the back camera explicitly (instead of the first camera listed) and
ResolutionPreset.highinstead ofmax. - Fix radar markers beyond
maxVisibleDistancebeing drawn outside the radar disc. - Fix a jerky pitch: the accelerometer now runs at 50 Hz instead of 5 Hz, and only accelerometer samples update the pitch filter (it used to be driven by compass and GPS events with stale values).
- Fix the heading freezing while the compass was uncalibrated (events without accuracy were dropped).
- Android: fix heading range (now
[0, 360)instead of[-180, 180]),headingForCameraModealways being 0, heading accuracy being overwritten by the accelerometer's, accelerometer/magnetometer staying on alongside the rotation vector sensor, a listener leaking when the stream was listened to again, and the stream handler not being released on engine detach. - iOS: fall back to the magnetic heading when the true heading is unavailable, set
headingOrientationfrom the device orientation (heading was off by ±90° in landscape), and only run CoreMotion while the compass stream is listened to.
New
- Add
ArSensorException/ArSensorErrorType, and asensorErrorBuilderonArViewandArLocationWidgetto customize the error shown when location is unavailable.
2.1.0 #
- Remove unused
ACCESS_BACKGROUND_LOCATIONpermission from the Android manifest. - Upgrade Android toolchain (AGP, Kotlin, Gradle, compileSdk, Java 17) for compatibility with recent Flutter/Android Studio versions.
- Update example iOS project (deployment target, Podfile) for compatibility with current Xcode/CocoaPods tooling.
- Add
ArSensorSourceinterface so sensors can be injected intoArView/ArLocationWidgetinstead of relying on a hardcoded singleton. - Extract annotation positioning/collision logic into a standalone
AnnotationLayoutEngine, unit tested independently of Flutter widgets. - Fix
ArViewperforming side effects (position updates,onLocationChange) duringbuild(). - Fix potential incorrect widget reconciliation by keying annotation views with
ValueKey(annotation.uid). - Improve performance of annotation overlap resolution (O(n²) to O(n log n) in the common case).
20.16 #
- Upgrade sensor
2.0.15 #
- Update gradle
2.0.12 #
- Solve scale camera
2.0.11 #
- Update dependencies
- add permission HIGH_SAMPLING_RATE_SENSORS for android 12
2.0.5 #
- Solve ArPluginsNotFound for Android
2.0.0 #
- Add radar.
1.0.0 #
- Add documentation.
0.0.5 #
- Resolve bug.
0.0.4 #
- Filter pitch.
0.0.3 #
- Update example with fake annotation.
- Resolve offset for overlap annotation sort annotation for distance user
0.0.2 #
- Update example.
0.0.1 #
- Describe initial release.