Android アプリケーションで EasyAR 機能を有効にする

本章では、Unity などの 3D engine を使用せずに、Android Studio で EasyAR の Android プロジェクトを設定する方法を紹介します。

準備

開始する前に、以下を準備してください。

• 最新バージョンの Android Studio

• JDK 8/11/17

• Android Gradle Plugin 4.0 以上

• Android NDK r28 以上

• EasyAR 認証ライセンスを取得

• EasyAR Sense のリリースバージョンを選択してダウンロード

注記

すべての Android デバイスが EasyAR Sense のすべての機能をサポートするわけではありません。一部の機能は追加 hardware や設定に依存します。詳細は、対応機能のデバイスサポート一覧を参照してください。

EasyAR Sense for Android をインポート

この節では、Unity ではない Android プロジェクトに EasyAR Sense SDK をインポートする方法を紹介します。EasyAR Sense は Java と C++ API を提供し、Kotlin もサポートしているため、慣れた言語で開発できます。

IDE によって設定方法が異なる場合があるため、ここでは Android Studio + Gradle に基づく典型的な設定方法のみを説明します。

API の使用方法を選択

EasyAR Sense for Android は、次の 2 つの API 使用方法を提供します。

• Java API のみを使用
• Java と C++ API を使用

プロジェクトの要件に応じて、いずれかを選択して設定してください。

Java API のみを使用

EasyAR の Java API のみを使用する場合、NDK の設定は不要です。

EasyAR.aar を app/libs/ または Gradle で指定したディレクトリに配置します。

Java と C++ API を使用

EasyAR の C++ API も同時に使用する必要がある場合は、Java 依存関係とネイティブライブラリの両方を設定する必要があります。

• Java レイヤーファイル

  EasyAR.jar を app/libs/ または Gradle で指定したパスに配置します。

• ネイティブライブラリ（.so）

  EasyAR が提供するネイティブライブラリを ABI ごとに次のパス、または Gradle で指定したパスに配置します。

  app/src/main/jniLibs/
  ├── armeabi-v7a/
  │   └── libEasyAR.so
  └── arm64-v8a/
      └── libEasyAR.so
  

• C++ ヘッダーファイル

  EasyAR SDK の include ディレクトリ下にある easyar フォルダーを、次のパス、または Android.mk/CMakeLists.txt で指定したパスにコピーします。

  app/src/main/jni/easyar/
  

  ヘッダーファイルのパスは、Android.mk または CMakeLists.txt で明示的に指定する必要があります。

Gradle 設定説明

C++ API を使用する場合は、Gradle で Native Build を有効にする必要があります。Java API のみを使用する場合、設定は不要です。ndk-build（Android.mk）で設定できます。

app/build.gradle に次を追加します。

android {
    externalNativeBuild {
        ndkBuild {
            path "src/main/jni/Android.mk"
        }
    }
}

CMake を使用する場合は、設定について Google 公式ドキュメントを参照してください。

NDK 設定

EasyAR をプリビルトライブラリとして宣言

include $(CLEAR_VARS)

# Make sure this path points to the current ABI directory in jniLibs
LOCAL_PATH := $(LOCAL_PATH_TOP)/../jniLibs/$(TARGET_ARCH_ABI)

LOCAL_MODULE := EasyAR
LOCAL_SRC_FILES := libEasyAR.so

include $(PREBUILT_SHARED_LIBRARY)

EasyAR とシステムライブラリをリンク

LOCAL_SHARED_LIBRARIES += EasyAR

# OpenGL ES (required)
LOCAL_LDLIBS += -lGLESv3

EasyAR の実行には少なくとも OpenGL ES 2.0 が必要です。OpenGL ES 3.0（GLESv3）の使用を推奨します。

ABI アーキテクチャを指定

無効なアーキテクチャがパッケージされないように、app/build.gradle で ABI を明示的に指定します。

android {
    defaultConfig {
        ndk {
            abiFilters "armeabi-v7a", "arm64-v8a"
        }
    }
}

いずれか 1 つのアーキテクチャだけが必要な場合は、対応する項目だけを残します。

AndroidManifest 権限設定

EasyAR Sense には次の権限が必要です。不足している場合、初期化失敗または黒画面の原因になります。

<uses-permission android:name="android.permission.CAMERA" />
<uses-permission android:name="android.permission.INTERNET" />

完全な例:

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="cn.easyar.samples.helloar">

    <uses-permission android:name="android.permission.CAMERA" />
    <uses-permission android:name="android.permission.INTERNET" />

</manifest>

EasyAR を初期化

アプリケーション起動時に Engine.initialize を呼び出して初期化します。

例（Java）:

@Override
protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    Engine.initialize(this, key);
}

注記

EasyAR 関連機能を使用する前に、初期化を完了しておく必要があります。

追加設定

Android プラットフォームでは、システムバージョンや使用する機能によって、以下の設定や制限にも注意が必要な場合があります。

ARCore 使用の設定

プロジェクトで ARCore を使用する場合は、公式ドキュメントを参照して AndroidManifest.xml と build.gradle の関連設定を完了してください。

また、EasyAR を初期化する前に、ARCore の native library を明示的にロードする必要があります。

System.loadLibrary("arcore_sdk_c");

注記

ARCore v1.19.0 より前のバージョンを使用する場合、Android 11 では検出できません。 これは Android 11 から app visibility 制限が導入され、AndroidManifest.xml で ARCore package 名を宣言する必要があるためです。

<queries>
    <package android:name="com.google.ar.core" />
</queries>

難読化 (ProGuard) の設定

Java コードで obfuscation を有効にする場合は、cn.easyar namespace を除外する必要があります。

EasyAR Sense は runtime に JNI を通じて class name reflection で Java types を取得します。 cn.easyar 配下の class が obfuscated またはリネームされると、undefined behavior が発生する可能性があります。

基本ルール

-keep class cn.easyar.** { *; }

推奨される精密ルール

-dontwarn javax.annotation.Nonnull
-dontwarn javax.annotation.Nullable
-keepattributes *Annotation*

-keep class cn.easyar.RefBase { native <methods>; }
-keepclassmembers class cn.easyar.* {
    <fields>;
    protected <init>(long, cn.easyar.RefBase);
}
-keep,allowobfuscation interface cn.easyar.FunctorOf* { *; }

-keep class cn.easyar.Buffer { native <methods>; }
-keep class cn.easyar.Engine { native <methods>; }
-keep class cn.easyar.JniUtility { native <methods>; }

-keep class cn.easyar.engine.** { *; }
-keep class cn.easyar.CameraParameters
-keep interface cn.easyar.FunctorOfVoidFromInputFrame

上記の ProGuard ルールは EasyAR の aar library にすでに含まれているため、通常は重複設定は不要です。

Scoped Storage

Android 10 から導入された Scoped Storage メカニズムは、file paths に依存する一部 API に影響します。これは、/sdcard 配下の non-media paths、例えばカスタムディレクトリが Android 10 で直接アクセスできないためです。EasyAR への影響としては、screen recording など file paths を渡す必要がある一部 API が、Android 10 では media paths の直接読み書きをサポートしませんが、Android 11 では正常に動作します。

解決方法:

• 簡易方法 (Android 10) AndroidManifest.xml で Scoped Storage を無効にする:

  <application
      android:requestLegacyExternalStorage="true"
      ... >
  </application>
  

• 推奨方法

  • app internal storage のみを使用する
  • または MediaStore を通じて media paths とデータ交換する

Android Gradle Plugin と NDK

NDK r22 以降、デフォルトで LLD linker が使用され、llvm-strip と組み合わせて使用する必要があります。これは Android Gradle Plugin 4.0 未満に組み込まれた strip tool と互換性がありません。 解決方法:

• Android Gradle Plugin 4.0 以上へアップグレード
• または packagingOptions で doNotStrip を使用して stripping を無効化 (非推奨)

Windows パス長制限

Windows システムでは、プロジェクト内の任意のファイル、build 中に生成される一時ファイルを含む、絶対パス長が 260 文字を超える場合、 Android Studio build が失敗する可能性があります。

解決方法:

• プロジェクトをより短い path に置く (例: C:\user\project)
• 深すぎるディレクトリ階層を避ける

関連情報

• EasyAR Mega がサポートするデバイス
• image tracking がサポートするデバイス
• motion tracking がサポートするデバイス
• sparse spatial mapping がサポートするデバイス
• dense spatial mapping がサポートするデバイス
• motion tracking と EasyAR の他モジュールの関係