開発者用APIによる動画からの写真測量計算の実行

変更日 Tue, 18 Jul 2023 で 07:06 PM

目的

本ドキュメントでは、エアロボクラウドの開発者向けAPIを使用し、ドローン撮影ビデオを入力とした写真測量を実行するための手順を記載します。
なお、同APIはアルファ版のため、今後変更される可能性があります。
また、利用方法、利用料金につきましては、エアロボクラウドサポート（cloud-support@aerosense.co.jp
）までお問い合わせください。

前提

開発者用APIのURL

次のパスにアクセスすることで開発者用APIの仕様ドキュメントにアクセスすることができます。

/swagger/index.html

開発者用APIのアクセスキー

開発者用APIを利用するためには専用のアクセスキーをHTTPヘッダに設定する必要があります。

アクセスキーは専用の契約を結んだお客様にお渡ししています。

エアロボクラウドのアカウント

開発者用APIを利用するためには、上記専用のアクセスキーに加えてエアロボクラウドのアカウント（ログイン用メールアドレス・パスワード）が必要になります。

開発者用APIを利用する手順

開発者用APIを使用して動画を入力として写真測量を実行するための手順を操作順に記載します。

1. 開発者用APIを利用するためのアクセストークンを取得する

/swagger/index.html にアクセスします。

以下のようなページが表示されるので、「Authorize」をクリックします。

次のようなダイアログが作成されるので、以下の手順を実施します。

Value にアクセスキーを入力する
「Authorize」を押す
「Close」を押す

次に、「ID/PWによるトークン発行」を開きます。

以下のような表示になるので、「Try it out」を押します。

以下のような表示になるので、次の手順を実施します。

emailとpasswordに自身のメールアドレスとパスワードを入力する。
「Execute」を押す。

APIの呼び出しに成功すると、次のような表示になります。

「Response body」の表示の中にある「"token":」の値が開発者APIで利用できるトークンの値になります。

このトークンの値を、HTTPヘッダに「Authorization: Bearer {トークン}」の形で設定する必要がありますが、方法を次に説明します。

再び「Authorize」を開きます。

以下の手順を実施します。

Valueに「Bearer 取得したトークン」と入力します。Bearerと取得したトークンの間には１スペース入ります。

「Authorize」を押し、「Close」で閉じます。

ここまでの操作により、他の開発者用APIを実行するための準備が整いました。

2. 動画を入力とした写真測量を実行するためのAPIの呼び出し手順

次に、動画から写真測量を実行するためのAPIの呼び出しを一つ一つ説明します。

全体の流れとしては、APIを用いて以下の手順を実行することになります。

所属しているグループを確認する
ミッションを作成する
フォトボックスを作成する
入力となる動画ファイル（mp4）ともし有れば位置情報ファイル（srt）のアップロードのためのURLを作成
アップロードURLをcurlコマンドにより実行（コマンドラインから行う必要があります）
アップロードされた動画ファイルを用いた写真測量処理の実行
写真測量処理の進捗状況確認
写真測量処理の出力ファイル（オルソ画像）のダウンロードをcurlコマンドにより実行（コマンドラインから行う必要があります）

所属しているグループを確認する

以下、「グループ一覧」を開き「Try it out」によりAPIを実行して下さい。

成功すると次のような表示になります。

レスポンスの中に、所属しているグループ名・所属しているグループのIDが表示されますので、のちのミッション作成・フォトボックス作成ではどのグループを使用するか決めておく必要があります。

また、APIではグループ・ミッション・フォトボックスの「ID」が必要になります。

ミッションを作成する

「ミッションの作成」を開き、「Try it out」を押します。

作成したいグループのID、作成したいミッション名、ミッションのタイプをセットします。

appTypeの初期値として「agriculture（農業）」が入っていますが、ここでは農業向けの処理は対象としていないため、「survey」に置き換えてください。

処理が成功すると、作成したミッションのIDを取得することができます。このミッションIDをフォトボックス作成の時に利用します。

フォトボックスを作成する

「フォトボックス作成」を開き、「Try it out」を押します。

作成したいグループのID、ミッションID、作成したいフライト名、フライトの日付をセットします。

処理が成功すると、作成したフォトボックスのIDを取得することができます。このフォトボックスIDを写真測量処理の実行時に使用します。

アップロードのためのURLを作成する

「アップロードリクエスト」の「Try it out」からアップロードに必要なURLを作成します。

以下、入力内容を示します。

グループID
ファイルパス（この例では video/2023/03/28 というディレクトリを作成し、その中にtest.mp4を格納する指示を出しています。ディレクトリは任意の階層を指定することができ、ユーザー側の管理のために活用することができます。後ほど記述する、フォルダ一覧表示API・ファイル一覧表示APIによりアップロードしたファイルがどのような階層になっているかを確認することができます。）
ファイルのcontentType（取得したURLを使用する時に必要になります）
ファイルのmodifiedAt（取得したURLを使用する時に必要になります）

APIが成功すると、以下のように uploadURLを取得することができます。

このURLを API仕様書から実行することはできないため、次のcURLコマンドの説明に基づいて実行する必要があります。

コマンドラインからアップロードを実行する

上記で取得したアップロードURLを cURLコマンドなどのパラメーターとしてコマンドラインから実行する必要があります。

必要な情報は以下となります。

アップロードURL作成時に指定したModifiedAtの日付
アップロードURL作成時に指定したContent-Type（この例では video/mp4)
アクセスキー
トークン
アップロードURL
アップロードする実際のファイル名

上記の情報を、次のコマンドラインのそれぞれの場所に設定します。

以下のコマンドは、アップロードを実行する「test.mp4」と同じディレクトリで実行する必要があります。

青色にハイライトされた部分は、上記の情報に置き換える必要があります。

mp4ファイルのアップロードのコマンド例

curl -i -X PUT -H "Content-Type:video/mp4" -H "x-goog-meta-modified-at:指定していたModifiedAtの日付" -H "X-Api-Key:アクセスキー" -H "Authorization:Bearer トークン" "取得したアップロードURL" -T test.mp4

srtファイルのアップロードのコマンド例

curl -i -X PUT -H "Content-Type:application/x-subrip" -H "x-goog-meta-modified-at:指定していたModifiedAtの日付" -H "X-Api-Key:アクセスキー" -H "Authorization:Bearer トークン" "取得したアップロードURL" -T test.srt

アップロードされた動画ファイルを用いた写真測量の実行

「点検動画向けSfM処理開始」を開き「Try it out」を有効にし、次の手順を実施します。

グループIDの入力
ミッションIDの入力
フォトボックスIDの入力
SfMの実行パラメーターの入力

SfM実行パラメーターの説明

サンプルとなるSfM実行パラメーター示します。

{
  "videoType": "video-infrared",
  "storagePaths": {
    "exportPath": "example/exports",
    "videoPath": "example/videoPath",
    "videoFiles": [
      {
        "type": "mp4",
        "file": "xxxx.mp4"
      },
      {
        "type": "srt",
        "file": "xxxx.srt"
      },
      {
        "type": "mp4",
        "file": "yyyy.mp4"
      },
      {
        "type": "srt",
        "file": "yyyy.srt"
      }
    ]
  },
  "sfmParams": {
    "frameStep": 10,
    "videoTimeRanges": [
      {
        "fileName": "xxxx.mov",
        "startAt": 40,
        "endAt": 0
      },
      {
        "fileName": "xxxx.mov",
        "startAt": 0,
        "endAt": 0
      }
    ],
    "matchingAccuracy": "Highest",
    "denseQuality": "Ultra"
  },
  "exportEpsg": 6677
}

videoType : video-infrared または video-rgb を受け取ります（赤外動画または可視動画の指定）これ以外を入力するとエラーとなります。
storagePath : 使用するビデオや結果の出力のクラウド上のパスを指定します。指定しないとエラーになります。
- exportPath : 写真測量の結果（オルソや点群）の保存希望フォルダパスを入力します。ダウンロードAPIにここで入力したフォルダパスを指定することでダウンロードが可能になります。
- videoPath : 写真測量の入力になる動画(mp4)や位置情報ファイル(srt)のフォルダパスを指定します。動画が存在しないパスを指定するとエラーになります。すでに説明したアップロードAPIで設定したフォルダパスを使用します。この例では videos/2023/03/28 となります。
- videoFiles : 写真測量の入力となるビデオファイル（mp4）と位置情報ファイル(srt）のペアを指定します。ペアと認識するためには、次の条件が必須になります。
  - xxxx.mp4 と xxxx.srt のようにファイル名の部分「xxxx」が一致していること
  - [{type:mp4, file:xxxx.mp4}, {type:srt, file:xxxx.srt}, {type:mp4, file:yyyy.mp4}, {type:srt, file: yyyy.srt}]のように１次元配列としていますが、これで問題有りません。サーバー側で「xxxx」「yyyy」のファイル名が一致しているものをペアとして認識します。
  - 但し、[{type:mp4, file:xxxx.mp4}, {type:srt, file:xxxx.srt}, {type:mp4, file:yyyy.mp4}] のように一部のペアが欠けている場合、APIサーバー側では位置情報ファイル(srt）が揃っていないものと認識し、位置情報は全て使用せず、ビデオのみから写真測量を試みます。
- このペアは複数あっても良く、複数のビデオファイルが入力されるとそれらのファイルを結合して写真測量を行うように試みます。そのため、全く関係のない動画ファイルを複数入力した場合は処理が成功しない事が考えられます。
- 利用料金については現在検討中ですが、１ファイルに対して固定の利用料金（○○○円／１ファイル）を適用する前提で検討しています。複数の動画ファイルを連結して処理した場合、動画数 x 1ファイルあたりの処理料金を適用する想定でいます。
sfmParams : 写真測量の各種パラメータを設定します。省略可能です。
- frameStep（省略を推奨） : 実際の動画ファイルのフレームを何枚おきに使用するかを指定します。デフォルトでは1フレーム/秒となるように調整されます。例えば、動画ファイルのフレームレートが30フレーム/秒だとすると、30を指定すると　1フレーム/秒が実際の写真測量に使用されます。（検証より1フレーム/秒で計算すると最も良いオルソが取得される事がわかっておりますので、ここでは特に値を設定せずお使いいただくことを推奨致します）
- videoTimeRanges：写真測量で使う動画の範囲を動画ファイルごとに指定します.
  - fileName：動画ファイル名（パスではない）を指定します。動画ファイル名は、videoFIlesで指定したファイル名と同一である必要があります。（一致していない場合、開始、終了時刻が無効となり、すべての範囲を使って解析します.
  - startAt : 動画ファイルのどの部分から写真測量を開始するかを（ms : ミリ秒）で指定します。動画の先頭部分に不要な地物が写り込んでいる場合、それを除去して写真測量を実行することで成果物の品質が向上する可能性があります。
  - endAt : 動画ファイルのどの部分で写真測量を終了するかを（ms : ミリ秒）で指定します。
- matchingAccuracy（省略を推奨） : 動画から取り出したフレームを使って写真測量を実行する際の、写真マッチング（３次元再構築）の精度を指定します。検証により最も良い品質の成果が得られる値がデフォルトで使用されますので、基本的に入力をする必要はありません。
- denseQuality（省略を推奨） : 写真マッチングにより再構築された３次元点群をどれだけ高密度化するかを指定します。検証により最も良い品質の成果が得られる値がデフォルトで使用されますので、基本的に入力をする必要はありません。
exportEpsg: オルソ画像の座標系を数値で設定します。設定しないとエラーとなります。ただし、座標系が定義できない場合（= srtファイルを指定しない場合）、0を指定します.

写真測量処理の進捗状況確認

処理が終了すると、登録されたアカウント（メールアドレス）あてに、計算終了の旨のメールが届きます.

写真測量の出力ファイル（オルソ画像・点群）のダウンロード

コマンドラインからダウンロードを実行します
(2023/5/20現在ダウンロードAPIは、swagger UIでは正しく機能しませんので、ご注意ください(TBD))

以下のダウンロードURLをcurlコマンドにより実行する必要があります。

必要な情報は以下となります。

グループID( グループ一覧APIから取得 )
クラウド上の出力対象ファイルパス（ファイル一覧APIから取得）
アクセスキー
トークン
出力ファイル名（任意）

上記の情報を、次のコマンドラインのそれぞれの場所に設定します.

curl -X GET -H "Content-Type:application/octet-stream" -H "X-Api-Key:アクセスキー" -H "Authorization:Bearer トークン" "https://aerobocloud.net/dev/api/groups/グループID/storage/files/クラウド上の出力対象ファイルパス" --output "出力ファイル名（任意）"

オルソファイルのダウンロードのコマンド例
(ここでは、groupID = 000000000, クラウド上のオルソ画像ファイルパスを"20230523_test/output/ortho/orthomosaic.tif" としています)
curl -X GET -H "Content-Type:application/octet-stream" -H "X-Api-Key:hogehoge" -H "Authorization:Bearer hogehoge" "https://aerobocloud.net/dev/api/groups/000000000/storage/files/20230523_test/output/ortho/orthomosaic.tif" --output "orthomosaic.tif"
点群ファイルのダウンロードのコマンド例
(ここでは、groupID = 000000000, クラウド上の点群ファイルパスを"20230523_test/output/pointcloud/pointcloud.laz"としています)
curl -X GET -H "Content-Type:application/octet-stream" -H "X-Api-Key:hogehoge" -H "Authorization:Bearer hogehoge" "https://aerobocloud.net/dev/api/groups/000000000/storage/files/20230523_test/output/pointcloud/pointcloud.laz" --output "pointcloud.laz"

以上.