ARCore SDK for Android v1.31.0

Breaking & behavioral changes

• Updated ARCore's minimum supported Android API level to 19 (from 18).
  • The upcoming Android NDK version (r24) will remove support for Android API levels v16-18.
  • For more information, see the Android NDK r23 changelog.

New APIs and capabilities

ARCore Geospatial API - new

The new ARCore Geospatial API utilizes data from Google Earth 3D models and Street View image data from Google Maps to enable your app for immersive, global-scale, location-based augmented reality experiences.

• Kotlin/Java reference

  • Earth provides localization ability in geospatial coordinates.
    • Earth.createAnchor() creates a new Anchor at the specified latitude, longitude, altitude, and orientation.
  • Earth.Earthstate describes the current state of Earth, including its TrackingState.
  • GeospatialPose describes a specific latitude, longitude, altitude, and compass heading.

• C reference

  • ArEarth provides localization ability in geospatial coordinates.
    • ArEarth_acquireNewAnchor() creates a new Anchor at the specified latitude, longitude, altitude, and orientation.
    • ArEarthState describes the current state of ArEarth, including its ArTrackingState.
  • ArGeospatialPose describes a specific latitude, longitude, altitude, and compass heading.

ARCore Depth API improvements

The maximum range of Depth measurements has increased from 8191mm to 65535mm when building with ARCore SDK 1.31 and later. The Depth API now uses all 16-bits to represent depth, where previously only 13 bits were used for depth values.

To reflect this change in behavior, some Depth API functions have new names and behavior changes. The old versions of these functions will have no change in behavior, though it is recommended to make use of the longer depth range. For more information, see ARCore Depth changes in ARCore 1.31.

• Kotlin/Java
  • The Depth API function calls have changed:
    • Frame.acquireDepthImage() has been deprecated in favor of Frame.acquireDepthImage16Bits().
    • Frame.acquireRawDepthImage() has been deprecated in favor of Frame.acquireRawDepthImage16Bits().
    • The output image formats for both calls have changed from
      android.graphics.ImageFormat.DEPTH16 to
      android.hardware.HardwareBuffer.D_16.
    • Depth is still represented as a 16-bit integer in units of
      millimeters, but now all 16-bits are used to represent depth, allowing
      for a maximum expressible range of 65535mm (previously 8191mm).
• C
  • The Depth API function calls have changed:
    • ArFrame_acquireDepthImage() has been deprecated in favor of ArFrame_acquireDepthImage16Bits().
    • ArFrame_acquireRawDepthImage() has been deprecated in favor of ArFrame_acquireRawDepthImage16Bits().
    • The output image formats for both calls have changed from AR_IMAGE_FORMAT_DEPTH16 to AR_IMAGE_FORMAT_D_16.
    • Depth is still represented as a 16-bit integer in units of
      millimeters, but now all 16-bits are used to represent depth, allowing
      for a maximum expressible range to go 65535mm (previously 8191mm).

Deprecations

• Kotlin/Java

  • The Depth API function calls Frame.acquireDepthImage() and
    Frame.acquireRawDepthImage() are deprecated. Please use
    Frame.acquireDepthImage16Bits() and Frame.acquireRawDepthImage16Bits()
    instead.

• C

  • The Depth API function calls ArFrame_acquireDepthImage() and
    ArFrame_acquireRawDepthImage() are deprecated. Please use
    ArFrame_acquireDepthImage16Bits() and
    ArFrame_acquireRawDepthImage16Bits() instead.

Known issues

• Configuring a session with GeospatialMode.ENABLED while the session is running may cause the session to hang. This issue will be resolved in Google Play Services for AR (ARCore) version 1.32. In the meantime, ensure your app only sets a configuration with GeospatialMode.ENABLED while the session is paused.

Other changes

• HelloAR sample apps now visualize the Depth API representing longer-range
  depth values with new colors.

ARCore SDK for Android v1.30.0

Known issues

• None

Other changes

• Annotated API return values with @NonNull and @Nullable.
• Updated the build tool versions used for building samples: Gradle to 7.0.2 and Android Gradle plugin to 7.0.4. Upgrading these tools is not required for existing ARCore applications. For new features, known issues, incompatibility information, see Android documentation on Android Gradle plugin.

ARCore SDK for Android v1.29.0

Known issues

• None

Breaking & behavioral changes

• Beginning in November 2022, AR-enabled apps will no longer be able to acquire NDK images or image metadata. The SDK versions impacted depend on the specific function being called, see the deprecation announcement to learn more.
  • C: Calls to ArImage_getNdkImage and ArImage_getNdkCameraMetadata will always return nullptr for the AImage and ACameraMetadata objects.
  • Java: The Image object returned by Frame#acquireCameraImage() will be of size 0x0 pixels. Calls to Frame#getImageMetadata() will always throw IllegalArgumentException.
  • Unity (AR Foundation):
    • When using AR Foundation 2.1 (Unity 2019 LTS), calls to XRCameraSubsystem.TryGetLatestImage(out XRCameraImage) will always return false.
    • AR Foundation 4.x and later versions are unaffected, calls to XRCameraSubsystem.TryGetLatestImage(out XRCameraImage) will behave normally.
  • ARCore SDK for Unity (deprecated): Calls to Frame.CameraImage.AcquireCameraImageBytes() will be of size 0x0 pixels. Calls to Frame.CameraMetadata.GetAllCameraMetadataTags() will return an empty List<CameraMetadataTag>.
• ArImage#getCropRect() now returns a full-sized crop rectangle, i.e. all pixels in the Image are valid. See android.media.Image#getCropRect() for additional information.

Other changes

• hello_ar_java and hello_ar_kotlin: Changed an object's color when it is placed using SCREENSPACE_WITH_APPROXIMATE_DISTANCE to better distinguish objects placed using Instant Placement.

Bug fixes

• persistent_cloud_anchor_java: Added a missing build dependency to the sample. Fixes a bug where hosting any anchor would have state CloudAnchorState ERROR_NOT_AUTHORIZED even if the project was set up correctly.

ARCore SDK for Android v1.28.0

Known issues

• None

Breaking & behavioral changes

• Beginning in November 2022, AR-enabled apps will no longer be able to acquire NDK images or image metadata. The SDK versions impacted depend on the specific function being called, see the deprecation announcement to learn more.
  • C: Calls to ArImage_getNdkImage and ArImage_getNdkCameraMetadata will always return nullptr for the AImage and ACameraMetadata objects.
  • Java: The Image object returned by Frame#acquireCameraImage() will be of size 0x0 pixels. Calls to Frame#getImageMetadata() will always throw IllegalArgumentException.
  • Unity (AR Foundation):
    • When using AR Foundation 2.1 (Unity 2019 LTS), calls to XRCameraSubsystem.TryGetLatestImage(out XRCameraImage) will always return false.
    • AR Foundation 4.x and later versions are unaffected, calls to XRCameraSubsystem.TryGetLatestImage(out XRCameraImage) will behave normally.
  • ARCore SDK for Unity (deprecated): Calls to Frame.CameraImage.AcquireCameraImageBytes() will be of size 0x0 pixels. Calls to Frame.CameraMetadata.GetAllCameraMetadataTags() will return an empty List<CameraMetadataTag>.
• ArImage#getCropRect() now returns a full-sized crop rectangle, i.e. all pixels in the Image are valid. See android.media.Image#getCropRect() for additional information.

New APIs and capabilities

• None

Deprecations

• None

Other changes

• None

Bug fixes

• None

ARCore SDK for Android v1.27.0

Known issues

• None

Breaking & behavioral changes

• None

New APIs and capabilities

• None

Deprecations

• None

Other changes

• Added hello_ar_kotlin to demonstrate best practices when using Kotlin. For more information see the QuickStart for Android.
• Added ml_kotlin to demonstrate how an image classification model can be used with ARCore. For more information see Use ARCore as input for Machine Learning models.

Bug fixes

• None

ARCore SDK for Android v1.26.0

Known issues

• None

Breaking & behavioral changes

• targetSdkVersion inside the ARCore aar has been updated to API level 31. Specifying a targetSdkVersion in your project's build.gradle or AndroidManifest.xml will override the ARCore value.

New APIs and capabilities

• Added support for describing ARCore dataset locations with URIs for Recording and Playback.
  • C: Developer guide
  • Java: Developer guide

Deprecations

• The file path string based Recording and Playback methods RecordingConfig#getMp4DatasetFilePath() and RecordingConfig#setMp4DatasetFilePath() have been deprecated in favor of URI based methods RecordingConfig#getMp4DatasetUri() and RecordingConfig#setMp4DatasetUri().

Other changes

• Updated Java and native sample apps to targetSdkVersion 31 (Android 12).

Bug fixes

• None

ARCore SDK for Android v1.25.0

New APIs and capabilities

• None

Deprecations

• None

Other changes

• Updated Java and native sample apps to targetSdkVersion 30 (Android 11).

Bug fixes

• Various bug fixes and performance improvements.

ARCore SDK for Android v1.24.0

New APIs and capabilities

• Added new Raw Depth API that provides a depth image without image-space filtering.
  • All devices that support the existing Depth API in ARCore supported devices now also support the new Raw Depth API.
  • Java: Developer guide, Frame#acquireRawDepthImage(), Frame#acquireRawDepthConfidenceImage(), Config.DepthMode.RAW_DEPTH_ONLY.
  • C: Developer guide, ArFrame_acquireRawDepthImage(), ArFrame_acquireRawDepthConfidenceImage(), AR_DEPTH_MODE_RAW_DEPTH_ONLY.
• Added new Custom Data Track Recording/Playback API, augmentations of the recording and playback features that allow developers to record and playback data to and from custom specified tracks, packaged as MP4 recordings.
  • Java: Developer guide, Track, Frame#recordTrackData(), Frame#getUpdatedTrackData().
  • C: Developer guide, ArTrack, ArFrame_recordTrackData(), ArFrame_getUpdatedTrackData().
• Added new trackable type DepthPoint that provides a calculated depth pose with each frame by hit testing. These values are sampled from the latest depth image, which yields more accurate results on non-planar or low-texture areas in the environment.

Deprecations

None

Other changes

• Java: Added new raw_depth_java sample app.
• Java: Updated hello_ar_java to use DepthPoint hit results from Frame#hitTest() when placing assets.
• C: Updated hello_ar_c to use ArDepthPoint hit results from ArFrame_hitTest() when placing assets.

Bug fixes

• Fixed memory leaks in hello_ar_c when rendering a plane that was subsumed and when attempting to render a plane that was not being tracked.

ARCore SDK for Android v1.23.0

Breaking & behavioral changes

• AR-enabled apps built using ARCore SDK 1.11.0 or earlier are no longer able to host or resolve Cloud Anchors.
  • C: Cloud Anchors returned by ArSession_hostAndAcquireNewCloudAnchor and ArSession_resolveAndAcquireNewCloudAnchor will always have the state AR_CLOUD_ANCHOR_STATE_ERROR_INTERNAL.
  • Java: Cloud Anchors returned by Session#hostCloudAnchor(Anchor) and Session#resolveCloudAnchor(java.lang.String) will always have the state Anchor.CloudAnchorState.ERROR_INTERNAL.
  • Apps built with ARCore SDK 1.12.0 or later are unaffected. Their use of Cloud Anchors APIs is covered by the deprecation policy.

New APIs and capabilities

• Developers can enable ARCore API call logging to the Android debug log by sending a broadcast intent.
• Developers can enable the ARCore performance overlay by sending a broadcast intent.
• Added new API for switching between rear-facing (world) and front-facing (selfie) camera configs within the current Session.
  • Java: Developer guide, CameraConfigFilter.getFacingDirection(), CameraConfigFilter.setFacingDirection().
  • C: Developer guide, ArCameraConfigFilter_getFacingDirection() ArCameraConfigFilter_setFacingDirection().

Deprecations

• The following session features are being deprecated:
  • Java: Feature FRONT_CAMERA is deprecated. To create a session using the front-facing (selfie) camera, use Session.setCameraConfig(CameraConfig) to set a front-facing(selfie) camera config retrieved from Session.getSupportedCameraConfigs(CameraConfigFilter).
  • C: Feature AR_SESSION_FEATURE_FRONT_CAMERA is deprecated. To create a session using the front-facing (selfie) camera, use ArSession_setCameraConfig to set a front-facing(selfie) camera config retrieved from ArSession_getSupportedCameraConfigsWithFilter.

Deletions

• The following deprecated APIs have been deleted:
  • ArImageMetadata_getNdkCameraMetadata
  • ArImage_getNdkImage

Other changes

• Java: Updated hello_ar_java to use the cubemaps provided by Environmental HDR Lighting Estimation for specular reflections.
• Updated augmented_faces_java sample app to use the new ArCameraConfigFilter_setFacingDirection() API to create a session using the front-facing (selfie) camera instead of using the FRONT_CAMERA Session feature, which has been deprecated.
• Updated computer_vision_c sample app to use functions of 'ArImage' instead of functions of AImage to obtain image data, to avoid using previously deprecated ArImage_getNdkImage.

Bug fixes

• Various bug fixes and performance improvements.

ARCore SDK for Android v1.22.0

Breaking & behavioral changes

• Beginning in January 2021, AR-enabled apps built using ARCore SDK 1.11.0 or earlier will no longer be able to host or resolve Cloud Anchors.
  • C: Cloud Anchors returned by ArSession_hostAndAcquireNewCloudAnchor and ArSession_resolveAndAcquireNewCloudAnchor will always have the state AR_CLOUD_ANCHOR_STATE_ERROR_INTERNAL.
  • Java: Cloud Anchors returned by Session#hostCloudAnchor(Anchor) and Session#resolveCloudAnchor(java.lang.String) will always have the state Anchor.CloudAnchorState.ERROR_INTERNAL.
  • Apps built with ARCore SDK 1.12.0 or later are unaffected. Their use of Cloud Anchors APIs is covered by the Cloud Anchors deprecation policy.

Known issues

• Support for stereo camera depth is expected to become available in ARCore SDK 1.23.0.

New APIs and capabilities

None.

Deprecations

None.

Other changes

• Java: Updated hello_ar_java to use the cubemaps provided by Environmental HDR Lighting Estimation for specular reflections.

Bug fixes

• Various bug fixes and performance improvements.