LoginSignup
8

posted at

updated at

THETA関連APIのまとめ(2022年11月更新版)

1. はじめに

THETAを使った開発をしてみようという人のために、開発の仕方をまとめてみた。手軽に試せるようにコマンドなどでの使用例を記載した。公式の仕様はgithubのricohapi/awesome-thetaでまとめられている。

  • RICOH THETA Xについて追記 (2022/10/07)
  • api.ricohサイトが閉鎖されたため、リンクを修正(2022/10/27)

動作環境

記事中では以下の環境を中心に動作確認した。

  • macOS Catalina (10.15.7)
  • RICOH THETA V, Firmware ver.3.50.1

2. THETAシリーズと対応API/機能

モデルによって対応しているAPI/機能が異なっており、ここに詳細が記載されている。

発売年 モデル名 Web API USB API BLE API UVC対応 Plugin対応
2013 RICOH THETA v1 - - - -
2014 RICOH THETA m15 v1 - - - -
2015 RICOH THETA S v2/v2.1 MTP v1.1 - HD/2K -
2016 RICOH THETA SC v2/v2.1 MTP v1.1 - - -
2017 RICOH THETA V v2.1 MTP v1.1 GATT 2K/4K Android API
2019 RICOH THETA Z1 v2.1 MTP v1.1 GATT 2K/4K Android API
2019 RICOH THETA SC2 - - -
2022 RICOH THETA X v2.1 MTP v1.1 GATT 2K/4K(天頂補正) Android API
  • THETA V/Z1のBLE (Bluetooth Low Energy)はデフォルトでは無効。WLANのAPモードで接続後、WebAPIから有効化できる(後述)。
  • THETA SC2はWebAPI/USBAPIに公式には対応していないが、概ね利用できる。

3. 各種API/機能

3-1. Web API

GoogleのOpen Spherical Camera(OSC)で定義されたコマンドの他に、THETA用の拡張コマンドが多数定義されている。元々THETAは画面を持たず、スマホからの操作が想定されていたため、ほぼすべての操作をWebAPIを介して行うことができる。

WebAPIのバージョン

WebAPIは初代のTHETAから対応しているが、モデルによってプロトコルが異なる。現状はOSC ver.2がベースのWebAPI v2.1が利用されている。THETA S/SCのWebAPI v2.0はデフォルトがOSC ver.1ベースのため、camera.startSessionが必要となる。THETA V/Z1(/SC2)ではOSC ver.2がデフォルトとなり、OSC ver.2ではステートレスになったため、camera.startSessionは不要になった。THETA S/SCではv2.1にも対応しており、client_versionをセットすることでv2.1に切り替えられるが、切断するとデフォルトのv2に戻る。

WebAPIバージョン ベースプロトコル
v1 PTP-IPベース
v2 OSC ver.1ベース
v2.1 OSC ver.2ベース

CLモード

THETA V/Z1ではCLモードが利用できる。CLモードは無線LANルータに接続する無線LAN接続のモード(PCやスマホのWi-Fi接続と同じ)である。デフォルトの無線LAN接続設定はAPモード(1:1接続するモード)となっており、スマホアプリもしくはWebAPI(_network_type)で切り替えることでCLモードが利用できる。CLモードではダイジェスト認証が必須となり、BLE設定などいくつかのWebAPIの利用が制限されている。

WebAPI v2.1 (OSC ver.2)での撮影

WebAPI v2.1ベースのTHETA V以降であれば、次の一行で撮影できるため、簡単にAPIを試すことができる。THETAYL00123456の部分を自身のカメラのシリアル番号に変更すれば良い。CLモードではダイジェスト認証が利用されるため、--digestでCLモード接続のためのIDとパスワードを設定する。IDとパスワードはRICOH THETAスマホアプリで設定できる。(参考

terminal
% curl -X POST http://THETAYL00123456.local./osc/commands/execute --data '{"name":"camera.takePicture"}' -H 'content-type: application/json' --digest -u THETAYL00123456:00123456

3-2. USB API

USB Media Transfer Protocol (MTP) v.1.1をベースに、THETA用に機能拡張したUSB APIを利用できる。

USB API(MTP v1.1)での撮影

ここではgphoto2をインストールして一般的なMTPの機能を使って撮影してみる。

terminal
% brew install gphoto2
  • 接続確認

THETAを静止画モードにした状態でUSBでMacと繋げる。

terminal
% gphoto2 --auto-detect
Model                          Port
----------------------------------------------------------
USB PTP Class Camera           usb:020,010
% gphoto2 --summary
Camera summary:
Manufacturer: Ricoh Company, Ltd.
Model: RICOH THETA V
...
  • 静止画撮影
terminal
% gphoto2 --capture-image
New file is in location /store_00020001/DCIM/100RICOH/R0010680.JPG on the camera
  • ファイルのダウンロード
terminal
% gphoto2 --get-file /store_00020001/DCIM/100RICOH/R0010680.JPG
Saving file as R0010680.JPG
  • 撮影+ダウンロード+削除(一括実行)
terminal
% gphoto2 --capture-image-and-download --filename ./test.jpg
New file is in location /store_00020001/DCIM/100RICOH/R0010681.JPG on the camera
Saving file as ./test.jpg
Deleting file /store_00020001/DCIM/100RICOH/R0010681.JPG on the camera
  • バッテリレベル取得
terminal
% gphoto2 --get-config=batterylevel
Label: Battery Level
Readonly: 1
Type: TEXT
Current: 100%
END

3-3. BLE API

Bluetooth Low Energy用のBLE APIは、Bluetooth SIGのGATTをベースにTHETA用に独自にサービス定義されたAPIである。GATTはBluetooth LEの基本となるデータ転送の方法を定義したプロファイルであり、サービスと属性(Characteristic)で構成される。この属性(状態やコマンド)の値を読み書きするのが基本となる。
THETAはBLEのPeripheral(Advertiseする側)として動作し、BLE接続するアプリを作る際はCentral(Scanする側)のソフトを作ることになる。

提供サービス

THETAで定義されているサービスは以下の通り。全てのサービスと属性はこちらに記載されている。

サービス名 UUID 機能
Camera Information 9A5ED1C5-74CC-4C50-B5B6-66A48E7CCFF1 ファームウエアバージョンなど、カメラ情報の取得
Camera Status Command 8AF982B1-F1FF-4D49-83F0-A56DB4C431A7 バッテリ情報など、カメラのステータス取得
Camera Control Command 32886D39-BA23-425C-BCAE-9C1DB0066922 音量などの、カメラの設定情報の取得
Shooting Status Command 9AD04FDF-E62B-43E4-8593-7631FCD29874 撮影時エラーなど、カメラの撮影状態の取得
Shooting Control Command 1D0F3602-8DFB-4340-9045-513040DAD991 カメラの撮影処理
Shooting Control Command v2 38EF1533-B0CC-4722-B6B6-8B23C27ECE5C 絞り設定などZ1やVのFirm ver.3以降で追加されたカメラの撮影処理
GPS Control Command 84A0DD62-E8AA-4D0F-91DB-819B6724C69E カメラに位置情報を設定する
WLAN Control Command F37F568F-9071-445D-A938-5441F2E82399 カメラのWi-Fi設定
Bluetooth Control Command 0F291746-0C80-4726-87A7-3C501FD3B4B6 カメラのBluetooth設定

BLEでの接続

BLEを有効にするにはAPモードで接続した上で、WebAPIを利用して準備する必要がある。APモードでWi-Fi接続(THETAとPCを1:1でWi-Fi接続)し、以下の手順でBLEを有効にする。

  1. BLE用パスワードの登録

Web APIのcamera._setBluetoothDeviceで自分のパスワードを設定する。ここではuuidgenコマンドで生成した文字列("50BC9100-F957-4EC2-BBDF-196D6561A7BF")を設定する。

terminal
% uuidgen
50BC9100-F957-4EC2-BBDF-196D6561A7BF

% curl -X POST 192.168.1.1/osc/commands/execute --data '{"name":"camera._setBluetoothDevice","parameters":{"uuid":"50BC9100-F957-4EC2-BBDF-196D6561A7BF"}}' -H 'content-type: application/json'

{"name":"camera._setBluetoothDevice","results":{"deviceName":"00129704"},"state":"done"}
terminal
% curl -X POST 192.168.1.1/osc/commands/execute --data '{"name":"camera.setOptions","parameters":{"options":{"_bluetoothPower":"ON"}}}' -H 'content-type: application/json'
{"name":"camera.setOptions","state":"done"}
    1. BLEで接続

BLEでの接続確認を行うため、AppleのBluetooth Explorerや、iPhoneのBLExplrアプリLightBlue(iOS版),LightBlue(Android版)を利用できる。これらのアプリはBLEアプリを作る際のデバッグでも利用できるため便利である。Bluetooth ExplorerはmacOSで動作するアプリであり、Apple Developer Connection(ADC)のサイトからAdditional Tools for XCodeをダウンロードすると、中に含まれている。ダウンロードにはADCの開発者登録が必要となる。以降、Bluetooth Explorerでの例を示す。

Bluetooth Explorerを起動して、"Devices"メニューから"Low Energy Devices"を選ぶと、THETAがシリアル番号で表示される。このシリアル番号を選択して"Connect"すると、先に説明したサービスリストが表示される。
BLEDevice.png

    1. BLE APIを有効化

WebAPI(_setBluetoothDevice)で先ほど登録した自身のパスワードを用いてBLE上で認証を行う。認証にはBluetooth Control Commandサービス(0F291746-0C80-4726-87A7-3C501FD3B4B6)にある、Auth Bluetooth Device(EBAFB2F0-0E0F-40A2-A84F-E2F098DC13C3)を用いる。ここに自身のパスワードを書き込むことで、BLE APIを有効化できる。Bluetooth Explorerで、EBAFB2F0-0E0F-40A2-A84F-E2F098DC13C3のCharacteristicを選択し、先に設定したパスワード("50BC9100-F957-4EC2-BBDF-196D6561A7BF")を"UTF8"で設定("Write")する。すると、BLE接続が有効となり、それまで"Value"と表示された部分に実際の値が表示されるようになる。この有効化はBLE接続の度に毎回必要となる。
BLEDeviceAuth.png

BLE APIでの撮影

ここでBLE APIを用いた撮影を試してみる。Shooting Control Commandサービス(1D0F3602-8DFB-4340-9045-513040DAD991)の中に、Take Picture属性(FEC1805C-8905-4477-B862-BA5E447528A5)がある。ここに"1"を"RAW"で設定("WRITE")すると、撮影が行われる。
BLEDeviceTakePicture.png

3-4. UVC対応

APIではないのだが、システムの一部として利用されることが多いため、UVCについても少し記載する。THETA S / V/ Z1で利用でき、モデルや設定で利用できるバージョンが異なる。THETA V/Z1ではEquirectangular形式でカメラから画像が出力されるため、THETA SでEquirectangularで出力する際に必要であったDualFish Blenderが必ずしも必要ではなくなった。ただし、UVCを扱うアプリでうまく動作しない場合があるため、RICOH THETA UVC 4Kが配布されている。

モデル UVC version 備考
RICOH THETA S v1.1(720p@15fps/MotionJPEG)
v1.5(FHD@30fps/H.264)
Dual Fish出力。Equirectangularでの出力や
FHDの利用にはDualFish Blenderが必要。
RICOH THETA V v1.5 (FHD or 4K @30fps/H.264) Equirectangular出力
RICOH THETA Z1 v1.5 (FHD or 4K @30fps/H.264) Equirectangular出力
RICOH THETA X v1.5 (FHD or 4K @30fps/H.264) Equirectangular出力 (天頂補正可能)

UVC ver.1.5ではVideo Frame Descriptorの定義としてH.264/VP8など高解像度動画で利用される形式が含まれるようになったが、ver.1.1ではそれらは定義されておらず、主に非圧縮やMJPEGが利用されていた。THETA Vが発売された2017年秋ごろにWindows10(ver.1703)やmacOS(10.12.4)でUVC ver.1.5が利用できるようになった。UbuntuでのUVC ver.1.5対応については今年(2020)の夏にlibuvc for RICOH THETAが公開されており、この活用についてtheta360.guide内のトピックの後半で議論されている。

3-5. Plugin対応

THETA V/Z1はAndroid OSがベースとなっており、アプリ(=プラグイン)を開発してインストールできる。詳細は他にも多くの記事があるので、ここでは説明を省略するが、上記のWebAPIはほぼそのまま、プラグインの中からlocalhost宛ての通信として実行できる。カメラの中では撮影アプリ(com.theta360.receptor)が常駐しており、WebAPIを受け付けている。この辺りの構成はここで紹介されている。また、"THETAのプラグイン開発Tips"を以前書いたため紹介しておく。

4. まとめ

これまでのTHETAのモデルとそれぞれの対応APIについて、改めて仕様を確認した。特に巷のBLE APIの使い方紹介が少なかったため、BLE APIを中心に説明を行い、実際に撮影するところまでを紹介した。ただし、各種APIの中ではWeb APIが最も使いやすい。WebAPIが利用できる環境であれば、WebAPIを利用するのが良いと思う。CLモードを使えばWLAN設定の変更も必要ないため、PC/Macからも比較的簡単にcurlコマンドなどでWebAPIを使った通信を行える。BLE APIは外部から接続設定を行うことなく利用できるため、WLANが使えない環境などで利用できる。アダプタなどを利用して有線LANも利用可能な場合があるが、有線での確実な通信を行いたい場合にはUSB APIも選択肢となる。用途に合わせたAPIを選択すると良いだろう。

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
What you can do with signing up
8