RICOH THETA X におけるプラグイン開発 #Android

はじめに

リコーの @KA-2 です。

弊社ではRICOH THETAという全周囲360度撮れるカメラを出しています。
RICOH THETA V, RICOH THETA Z1, RICOH THETA Xは、OSにAndroidを採用しています。Androidアプリを作る感覚でTHETAをカスタマイズすることもでき、そのカスタマイズ機能を「プラグイン」と呼んでいます（詳細は本記事の末尾を参照）。

という訳で、皆様！RICOH THETA Xの日本発売日が決定しました！

【お知らせ】「RICOH THETA X」の国内発売日決定および関連アクセサリー新発売

「RICOH THETA X」の発売日が決定しました。併せて関連アクセサリー「TW-2」「 K-ACU2」「TL-3」を新発売しますのでお知らせします。

・発売日：7月22日(金)
・価格：オープン

詳細➜https://t.co/kJldPGK7yH
— RICOH THETA official (@theta_official) July 6, 2022

製品の詳細は、上記のリンクを参照頂きたいと思いますが、ざっくりお伝えすると、
画素数が増え、より高精細な360°映像を手軽に撮影できるようになっただけでなく、タッチディスプレイを搭載したり、本体のみで衛星による位置情報を取得できたり、記録メディア(microSD)や電池の交換ができるようになったりなど、使い勝手も大きく強化された機種になります。

前述のとおり、OSにAndroidを採用した機種ですので、プラグイン開発も行えます。
外観からも想像して頂けると思いますが、これまでよりもスマートフォンアプリに近いプラグインを開発できるようになっています。それだけでなく、THETA固有の事項（主に撮影に関する事項）について、少々お作法が変わった点もあります。

今回は、それらをひっくるめて、RICOH THETA Xでプラグイン開発をするにあたり、最初に抑えておいたほうが良い事項をひととおりお伝えします。

プラグインでできることの概要

https://github.com/ricohapi/theta-api-specs/tree/main/ricoh-theta-plugin のOverviewに同じ図の記載がありますが
大雑把に補足説明をします。

こちらは、プラグインから操れるハードウェアを一目でみれるようにした図です。
RICOH THETA Xは、これまでできていたことが一通りできます。（図中左側）
さらに、衛星測位が行え、タッチディスプレイがつき、できることが増えました。（図中右側）

概要としては上記の通りなのですが、もう少し細かな変更や、作成するプラグインによっては運用する上で有利になるハードウェアの変更点などがあります。
そういった所を、以下のように章に分割して、もう少し詳しく説明させて頂きます。

Camera API による撮影制御の作法変更
Web API ローカルループバックによる撮影制御の作法変更
タッチディスプレイ搭載のインパクト・注意点・便利情報
マイク利用の作法が減りました
通信(Bluetooth/USB Serial)の制限緩和
衛星測位の利用方法
記録メディア（microSD）交換により便利になること
電源関連の変更により便利になること
プラグインの起動とインストールが楽になりました

先に記述があるほどプログラミングに関わる重要な内容です。後半ほど「使い方によっては便利になるよ」という小ネタです。作成するプラグインによっては運用が楽になるかもしれません。

Camera API による撮影制御の作法変更

Camera API 利用開始/終了時の手続き省略

過去機種では、Camera APIを利用した撮影開始前（onResumeで行うことが多い）に"com.theta360.plugin.ACTION_MAIN_CAMERA_CLOSE"、Camera APIを利用した撮影終了時（onPauseで行うことが多い）に"com.theta360.plugin.ACTION_MAIN_CAMERA_OPEN"というIntentを送る必要がありました。
※THETA Plug-in Libraryに用意されているメソッド、notificationCameraClose()やnotificationCameraOpen()でも代用できます。
これは、ドキュメントにも記載されています。

RICOH THETA Xでは、この手続きが不要になりました！

ちょっと楽になったでしょ？

クラスの変更

これまでの機種では、Camera APIを利用する際、android.hardware.Cameraクラスを使って頂いていました。

OldImportSample.java

import android.hardware.Camera;

RICOH THETA Xでは、アップデートされたTHETA Plug-in Libraryに含まれるcom.theta360.hardware.Cameraクラスを使って頂くことになります。（ライブラリに含まれているXCamera.jarを使います）

NewImportSample.java

import com.theta360.hardware.Camera;

importするクラスが変わった点が大きな変更です。メソッドに大きな変更はありません。（過去機種と同じくAndroid Camera 1 APIベースです）
以下の点にご注意ください。

メソッドCamera.open()の第1引数にandroid.content.Contextを渡す必要があります。
インターフェイスCamera.ShutterCallbackにメソッドonShutterend()とonLongShutter()が追加されました。

細かなパラメータについてはドキュメントを参照してください。
RICOH THETA Xならばできること、などもあります。例えばFace Detectionが該当します。

過去機種とRICOH THETA X共用のCamera API利用プラグインを作成する

前述のようなimportするクラスの変更があるため、過去機種とRICOH THETA X共用のCamera API利用プラグインを作成したい場合には、少し工夫が必要です。
方法としては、以下2通りがあります。

ご自身で、機種名（Build.MODEL）から利用するクラスを使い分ける
THETA Plug-in Library の中のfactoryクラス（ com.theta360.pluginlibrary.factory.Camera ）を利用する
※importだけでなく factory クラスのabstractCamera() というAPIに機種名を与え、インスタンスを生成します。

サンプルコードについて

過去機種とRICOH THETA X共用 Camera API利用プラグインのサンプルコード
https://github.com/ricohapi/theta-plugin-camera-api-sample
THETA X のみ対応 Camera API利用プラグインのサンプルコード
Kotlin版：https://github.com/ricohapi/theta-plugin-camera-api-sample-x
Java版：https://github.com/ricohapi/theta-plugin-camera-api-sample-x/tree/java
※本サンプルのみ、Kotlin版も用意してみました。

Web API ローカルループバックによる撮影制御の作法変更

プラグインからのWeb API利用開始/終了時の手続き追加

RICOH THETA Xでは、プラグインからWeb APIを利用する場合、利用開始前（onResumeの先頭が良いと思います）に「com.theta360.plugin.ACTION_PLUGIN_WEBAPI_CAMERA_OPEN」利用終了時（onPauseの末尾が良いと思います）に「com.theta360.plugin.ACTION_PLUGIN_WEBAPI_CAMERA_CLOSE」のインテントを送る手続きが追加されました。
※THETA Plug-in Libraryに用意されているメソッド、notificationWebApiCameraOpen()やnotificationWebApiCameraClose()でも代用できます。

ドキュメントの「RICOH THETA X」の説明を参照してください。

過去機種とRIOCH THETA X共用のWeb API利用プラグインを作成する場合、上記インテントを送るように書いておけばOKです。過去機種で上記のインテントを送っても無視されます。

とはいえ、機種ごとにWeb APIで設定できる値が微妙に違ったり、使えるAPIが異なる点も少々あります。
このあたりは、動作確認を行いながら各自で対応してください。

サンプルコードについて

サンプルコードである THETA Plug-in SDKが更新されています。
以下3点程度の違いですので、大きな変化はありません。

build.gradleでRICOH THETA Xにも対応した最新のTHETA Plug-in Libraryをimplementationしている
onResume()先頭で、notificationWebApiCameraOpen()を呼んでいる。
onPause()末尾で、notificationWebApiCameraClose()を呼んでいる。

このサンプルは、「シャッターボタンが押されるとtakePictureする」というシンプルな構成なので問題が生じないのですが、これまで、このコミュニティで紹介してきたようなWeb APIを多用するプラグインを作成する場合、以下のことに注意して作成してください。

"WebAPIを使ってプラグイン起動前の撮影設定に戻す処理"は、
onPause()にてnotificationWebApiCameraClose ()を実行したあと、
onStop()で行ってください！

MainActivity.java

    // Only execute notificationWebApiCameraClose () with onPause ().
    @Override
    protected void onPause() {
        //Execute it before super.onPause ().
        notificationWebApiCameraClose();
        super.onPause();
    }

    // Restore the settings with onStop ().
    @Override
    protected void onStop() {
        new RestorSettingsTask( /*This is a sample Task*/ ).execute();
        super.onStop();
    }

notificationWebApiCameraClose()を実行したあとに WebAPIを使うという点で少々混乱するかもしれないのですが、「THETA X で Web APIを利用するときの独自作法」として使って頂きますようお願いします。

なお、過去機種ではベースとなったOSのバージョンが Android 7.1.1でした。RICOH THETA XではAndroid 10.0 がベースとなっています。build.gradleに記載してあるAndroidのSDKのバージョンも数値が上がっています。ご参考まで。

タッチディスプレイ搭載のインパクト・注意点・便利情報

タッチディスプレイ搭載により、プラグインはスマートフォンアプリにとても近づきました。
とは言ったものの「どれくらい？」が頭をよぎりますよね。

RICOH THETA Xを開発者モードにしないと試せないことではありますが、自己責任で探してきたスマートフォンアプリのapkを無理やりインストールすると、多くのものが動いてしまうのです！（※動かないものもありますので注意）。
例えば、スマートフォン用編集アプリ「THETA+」も静止画編集ができました。（他の機能も動きそうですが試してないだけです。画像の保存先は内部メモリになってしまうので編集結果を取り出すにはひと手間加えないといけなそうです。）

他にも、様々なスマートフォン用アプリが動作しています。Android 10ベースですので、古くてシンプルなほうが動く感じがあります。
"動作するものはプラグイン化できる"ということを示唆します。
今後の記事では「こんなアプリが動いたから、こんなプラグイン作れそうだよ」という紹介も行っていきたいと思っています。

タッチディスプレイの注意点

色々なスマートフォンアプリが動作するので、作れるプラグインの幅が広がるぜ！
とはいえ、あらかじめわかっている制限もありますので紹介しておきます。

解像度は、横360×縦640ドットになります。
（スマートフォンアプリによっては画面がすべて表示されないものもありました）
ピンチイン・ピンチアウトには対応していないデバイスです。
画面に拡大縮小ボタンを設けるなどして対応してください。

便利情報

Settings画面の開き方

Vysor利用時に表示されるのは本体画面そのものです。
プラグイン開発で必要になることが多いSettings画面を開く歯車アイコンが見えませんが、開発者モードにした方は以下コマンドで表示できます。

adb shell am start com.android.settings

主に、以下の目的で利用してください。（製品では変更できない項目まで変更できてしまいます。自己責任での利用をお願いします。）

RICOH THETA Xを工場出荷状態に初期化する時
（システム→詳細設定→リセットオプション→すべてのデータを消去）
開発中のプラグインにパーミッションを与える時
（アプリと通知→ **個のアプリをすべて表示→目的のアプリ=プラグインを開いてパーミッションを与える）
開発中のプラグインを起動する時
（アプリと通知→ **個のアプリをすべて表示→目的のアプリ=プラグインを開く→開くをタップして起動）

キーコードの送出

RICOH THETA Xには HOMEボタンやBACKボタンがありません。
スマートフォンアプリを試してみる時、アプリの終了方法が電源Offだけになってしまうのですが、、、
adbコマンドを使って以下のキーコードを送ると、アプリを終了したり画面遷移ができたりします。

adb shell input keyevent KEYCODE_HOME
adb shell input keyevent KEYCODE_BACK

マイク利用の作法が減りました

RICOH THETA VやRICOH THETA Z1は、4chマイクを搭載していたため、プラグインからマイクを利用する前にモノラルマイクへ切り替える作法が必要でした。こちらのドキュメントに記載があります。「B-format Selection」という箇所です。

RICOH THETA Xはモノラルマイクですので、この作法が不要になります！
このため、以下のように、イコライザ表示（音入力をFFTして周波数毎に音圧表示）を行うスマートフォン用アプリもそのまま動きました。
プログラミングを行う時には、スマートフォンアプリを作成する知識だけで行えるということになります。

通信(Bluetooth/USB Serial)の制限緩和

Bluetoothのペアリングが楽になりました

過去機種では、画面が無かったりボタン数が少ない事情から、Bluetoothの振る舞いがTHETA固有の振る舞いでした。
RICOH THETA Xでは、画面がついたことから、概ねスマートフォンのようにBluetooth機器をペアリングできます。

上の写真では、特別なプラグインを作ることなく、HID over GATTのマウス、Bluetooth 3.0のキーボードを同時に接続しています。
もちろん操作も可能です。Wireless Live Streamingのキーボード入力もできていますし、一番右側の写真をよくみるとマウスカーソルが表れています。
ただし、プラグイン起動前にペアリングしておく必要があります。（プラグイン起動中に諸設定のメニューは出せません）

また、複数の機器を同時利用できますが、HID over GATTのHID機器（BLEを利用したHID機器）については、同時利用できるのは１つまでとなっています。

もちろん、A2DP, AVRCP,HSPのプロファイルに対応したマイク・スピーカを接続することもできます。過去機種と比べるとマイクにも対応したのが進化です。ただし、マイクを利用するプラグインを作成しないとマイク利用はできません。製品の動画記録に外部マイクの入力は対応していません。

USB Serial接続時システムダイアログに答えられるようになりました

過去機種でも、THETAのUSB Hostの機能を利用して、USB Serialで外部機器と通信することができていましたが、
過去機種では、THETAと外部機器を接続したときにAndroidのシステムがだすダイアログに、一般ユーザーは答えられない（開発者モードにしたTHETAでVysorを利用しないと答えられない）という都合から、ストアに公開できるようなUSB Serial利用プラグインを作成することができませんでした。
RICOH THETA Xでは、「画面がついたから」という理由ではありますが、この制限がなくなりました。

上の写真は、スマートフォン用アプリの「Serial USB Terminal」を動作させた様子です。
特別なことをしなくてもダイアログに答えて利用できています。
Bluetoothキーボードもつなぐと、入力も楽になります。（画面は小さいのですが）

作成できるプラグインの幅が広がりますね。

衛星測位の利用方法

スマートフォンアプリを作成するための情報（＝AndroidのAPI）のみで、衛星を使った位置情報の取得が行えます！

スマートフォン用アプリも動作するものがあるわけですが、そんなプラグインを作ってストアに公開してみました。
近日中に記事を作成して公開しますので乞うご期待！

記録メディア（microSD）交換により便利になること

RICOH THETA Xは microSDカードスロットが付き、記録メディアの交換ができるようになりました。

一見するとプラグインにはあまり関係なさそうな事項ですが、
本件は、「プラグインで"映像以外のデータ"を保存したとき、取り出し方法が簡単になる！」というメリットになります。

RICOH THETA Xを含め、RICOH THETAシリーズは、USBケーブルでPCに接続した際、PCから見えるファイルの種類を映像のデータ（JPG,DNG,MP4,exr）に限定しています。
microSDカードが取り外せることにより、上記の制限を受けずにデータを取り出せます。

例えば、衛星測位のログをmicroSDカードに保存するプラグインを作った場合、ログの取り出しが簡単になるのです。
このようなケースにおいて、過去機種ではWeb UI（プラグインにサーバーのコードを書く必要がある）を使ってダウンロードさせる方法が考えられますが、RICOH THETA XではWeb UIを実装しない選択肢もでてきます。

ちょっと便利かもな小ネタでした。

電源関連の変更により便利になること

電源にまつわる事項で以下3点が改善されています。
作成するプラグインによっては動作させるときに便利になります！

電池なし駆動も行えるようになりました
※最低でも5v 3.0A供給が行えるPDに対応したACアダプタ利用時
USB Hostと外部給電の両立が可能なType-CのUSBハブに対応しました
RICOH THETA Z1は端子形状がType-Cであったものの、USB Hostと外部給電の両立可能なUSBハブに対応できていませんでいしたが、RICOH THETA Xは対応しています。プラグインよりも本体機能のUSBライブストリーミングを行うときに便利な情報かもしれません。
端子位置が側面となり、給電動作させるときに TE-1/TE-2が不要となりました
以下写真のとおりです。三脚に固定して給電しながら連続動作させるようなケースで便利です。

プラグインの起動とインストールが楽になりました

プラグインの起動ついて

過去機種では、多くのプラグインをインストールできても、すぐに起動できるプラグインの数に限りがありました。
制限以上のプラグインを起動するには、PC用アプリやスマートフォン用アプリで設定を切り替える必要がありました。
（RICOH THETA Z1の場合には、Plug-in Launcher for Z1というプラグインで、上記制限をなくすこともできていましたが）

RICOH THETA Xでは、この制限がなくまりました！
画面右端を左側にスワイプすると、写真左側のようなメニューが表示され、目的のプラグインを自由に起動することができます。

なお、開発中のプラグインを起動メニューに加えるには、インストール後に電源Off→On操作を行うか、以下コマンドでリブートをします。

adb shell am start com.android.settings

プラグインのインストールについて

過去機種では、プラグインをインストールするには、PC用アプリが必要でした。手順はコチラ。

<2023/2/14 追記>
2023年5月末より、THETA X本体から直接インストールする方法が廃止される予定です。PCと接続してインストールする方法は維持されます。
詳細はこちらhttps://topics.theta360.com/ja/news/2023-02-14-2/の案内を参照ください。

RICOH THETA Xでは、CLモードでネットワークに接続すると、本体に直接インストールできます！
写真左側のメニュー左上のお店マークアイコンをタップし、インストール可能なプラグインを一覧表示したあと、目的のプラグインページを開くと写真右側のようになります。あとはインストールボタンを押すだけです。（いくらか利用規約の確認などもあります）

おわりに

RICOH THETA Xのみに対応したプラグインを開発するという視点では、手間はこれまでとあまり変わらぬまま、スマートフォンアプリのような画面も作成でき、THETA固有の制限が減り、作れるプラグインの可能性が広がったと思います。

過去の機種とRICOH THETA X、どちらにも対応したプラグイン開発するという視点では、少々面倒ごとが増えているかもしれません。
UIに関するハードウェアが異なるという点、撮影を行う場合、機種ごとに設定できるパラメータの範囲が微妙に異なる点を１つのアプリケーションで全て対応するという所が面倒ごとになると思います。

これからも、「○○をするプラグインの作り方」というような事例の紹介を行っていきます。
さらに THETA Xについては、「事例を作成するまでに至ってないけれどスマートフォンアプリが動いたから、こんなプラグインも作れそうですよ？」というような紹介も行っていきたいと考えています。

お楽しみに！

RICOH THETAプラグインパートナープログラムについて

THETAプラグインをご存じない方はこちらをご覧ください。
パートナープログラムへの登録方法はこちらにもまとめてあります。
QiitaのRICOH THETAプラグイン開発者コミュニティ TOPページ「About」に便利な記事リンク集もあります。
興味を持たれた方はTwitterのフォローとTHETAプラグイン開発者コミュニティ(Slack)への参加もよろしくおねがいします｡