--- title: "Visual Localization" slug: "arc-eye-vl-api" updated: 2026-09-17T09:57:56Z published: 2026-09-17T09:57:56Z canonical: "api.ncloud-docs.com/arc-eye-vl-api" --- > ## Documentation Index > Fetch the complete documentation index at: https://api.ncloud-docs.com/llms.txt > Use this file to discover all available pages before exploring further. # Visual Localization Classic/VPC環境で利用できます。 カメラを含むビジョンデバイスから収集された情報を通じて、屋外と GPSが届かない屋内でも画像だけで現在位置の測位情報を照会します。さらに、デバイスから収集された WiFi電波強度(RSSI)を利用して、GPSが届かない屋内で現在の大まかな位置を教えてくれる測位サービス(WiFi Localization)も追加で提供します。これにより、デバイスが位置するおおよその位置とともにロケーション情報も提供されるため、より正確にリクエスト(半径サーチ: lastPose + odometryの組み合わせ)できます。 参考 WiFi Localization機能関連の次の点をご確認ください。 - RSSIの詳細は、[Received signal strength indicator](https://en.wikipedia.org/wiki/Received_signal_strength_indicator)をご参照ください。 - 2024年7月以前にスキャンされた空間については、WiFi Localization機能はサポートされません。 ## 事前段階 ARC eye VL APIを使用するための事前段階は次の通りです。 ### 1. 空間データの構築 コンソールで空間データを構築します。SLAMデータ変換から SLAMデータマージ、ローカライズ、VLデータ変換まで、すべての操作を順に行ってください。実行方法の詳細は、[ARC eyeご利用ガイド](https://guide.ncloud-docs.com/docs/ja/arceye-overview)をご参照ください。 ### 2. APIをデプロイ VLデータマージに成功すると、NAVERクラウドプラットフォームコンソールの **Menu** > **All Services** > **Digital Twin** > **ARC eye** > **Visual Localization** > **API**メニューに**待機**状態の APIが作成されます。その APIを選択してデプロイします。**完了**状態でデプロイが完了すると、ARC eye VL APIを使用できます。APIサービスが**停止**中の状態では、ほかの APIをデプロイできません。 デプロイ方法の詳細は、[ARC eyeご利用ガイド](https://guide.ncloud-docs.com/docs/ja/arceye-api)をご参照ください。 ## リクエスト リクエスト形式を説明します。リクエスト形式は次の通りです。 | メソッド | URI | | --- | --- | | POST | [InvokeURL](/docs/ja/arc-eye-overview#APIURL) | 参考 `/api/vi~`パスは、現在のバージョンパスである`/vl/v1/~`の以前のバージョンです。 ### リクエストヘッダ ARC eye APIで共通して使用されるヘッダの詳細は、[ARC eyeのリクエストヘッダ](/docs/ja/arc-eye-overview#%EC%9A%94%EC%B2%AD%ED%97%A4%EB%8D%94)をご参照ください。 ### リクエストボディ リクエストボディの説明は次の通りです。 | フィールド | タイプ | 必須の有無 | 説明 | | --- | --- | --- | --- | | `image` | File | Required | 測位対象の画像 - wifiリクエスト時、省略可能 | | `cameraParameters` | String | Optional | カメラパラメータ情報 - 入力しないとデフォルト値で動作 - fx,fy,cx,cy,k1,k2,p1,p2,k3 - fx,fy: カメラレンズの焦点距離(focal length) - cx,cy: イメージセンサーの主点座標(principal point) - k1,k2: レンズの1次、2次放射状歪み(radial distortion)補正係数 - p1,p2: レンズの接線歪み(tangential distortion)補正係数 - k3: レンズの高次放射状歪み(radial distortion)補正係数 | | `lastPose` | String | Optional | クエリ画像の作成時に推定された画像の6-dof姿勢情報 - コンマで区切る - 最近レスポンスを受けた姿勢の値に`odometry`の値を足す - `odometry`使用時、必ず入力 | | `odometry` | String | Optional | 最後のクエリ画像を送信した時点と現在のクエリ画像を送信した時点間の姿勢変化量 - コンマで区切る - `lastPose`使用時、必ず入力 | | `withGlobal` | Boolean | Optional | `lastPose`の解析方法 - `true` \| `false` - `true`: `lastPose`の値を「緯度、経度、tz、qw、qx、qy、qz」と解析 - `false`: `lastPose`の値を「tx、ty、tz、qw、qx、qy、qz」と解析 | | `withInlier` | Boolean | Optional | 測位時に使用した有効な3D-2D correspondences(3D空間の点に対応する2D画像のピクセル座標)値を表示するかどうか - `true` \| `false` - `true`: 表示 - `false`: 表示しない | | `wifi` | File | Optional | WiFiの電波強度スキャンファイル - JSON形式 | | `datasetInfo` | String | Optional | ロケーションレイヤー名に対応する加工データのみ利用して VLクエリを実行 - ロケーション名はコンマで区切る | ### リクエスト例 リクエストのサンプルコードは次の通りです。 ``` curl --location --request POST '{InvokeURL}' \ --header 'X-ARCEYE-SECRET: {SecretKey}' \ --header 'Content-Type: multipart/form-data' \ --form 'image=@location.jpg;type=image/jpeg' \ --form 'odometry=0,0,0,1,0,0,0' \ --form 'lastPose=0,0,0,1,0,0,0' \ --form 'cameraParameters=1186.7,1406.5,540,960,0.0,0.0,0.0,0.0,0.0' \ --form 'withInlier=true' \ --form 'datasetInfo=1F,T2B00652308180853' ``` ## レスポンス レスポンス形式を説明します。 ### レスポンスボディ(成功) 照会に成功した場合のレスポンスボディの説明は次の通りです。 | フィールド | タイプ | 必須の有無 | 説明 | | --- | --- | --- | --- | | `result` | String | - | レスポンス結果 - `SUCCESS` \| `FAILURE` \| `ERROR` - `SUCCESS`: 成功 - `FAILURE`: 失敗 - `ERROR`: エラー | | `status` | String | - | レスポンス結果の状態 | | `message` | String | - | レスポンス結果メッセージ | | `tips` | String | - | 測位結果の参考情報 | | `pose` | String | - | 画像名、tx、ty、tz、qw、qx、qy、qz値 | | `total` | Number | - | クエリ画像から抽出された特徴点の総数 | | `inlier` | Number | - | クエリ画像から抽出された有効な特徴点の総数 | | `inliers` | Array | - | 測位時に使用した有効な3D-2D correspondences情報: [inliers](/docs/ja/arc-eye-vl-api#inliers) | | `residual` | Number | - | 有効な特徴点のプロジェクションエラー(ピクセル単位) | | `floor` | String | - | クエリ画像の層情報 | | `lonLat` | String | - | 経度(Longitude)、緯度(Latitude)の値 | | `globalPose` | String | - | 画像名、緯度、経度、高度(altitude)、qw、qx、qy、qzの値 | | `nnPose` | Array | - | 隣接するリファレンス画像の画像名、tx、ty、tz、qw、qx、qy、qzの値 | | `datasetInfo` | String | - | スキャン時に区分した各階層の名前を1つに繋げた値 | | `confidence` | Number | - | 推定された姿勢の信頼度 - 0に近いほど信頼度が低く、1に近いほど信頼度が高い | | `position` | String | - | マッピング空間における2自由度の位置の値(XY平面) | | `datasetInfoScore` | String | - | ロケーション区分の精度 - 0に近いほど信頼度が低く、1に近いほど信頼度が高い | #### `inliers` `inliers`の説明は次の通りです。 | フィールド | タイプ | 必須の有無 | 説明 | | --- | --- | --- | --- | | `U` | Number | - | 2D画像上のピクセル座標 | | `V` | Number | - | 2D画像上のピクセル座標 | | `X` | Number | - | 3D Xポイント | | `Y` | Number | - | 3D Yポイント | | `Z` | Number | - | 3D Zポイント | ### レスポンスボディ(WiFi成功) WiFi Localizationによる照会に成功した場合のレスポンスボディの説明は次の通りです。 | フィールド | タイプ | 必須の有無 | 説明 | | --- | --- | --- | --- | | `result` | String | - | レスポンス結果 - `SUCCESS` \| `FAILURE` - `SUCCESS`: 成功 - `FAILURE`: 失敗 | | `position` | String | - | マッピング空間における2自由度の位置の値(XY平面) | | `lonLat` | String | - | 経度(Longitude)、緯度(Latitude)の値 | | `datasetInfo` | String | - | スキャン時に区分した各階層の名前を1つに繋げた値 | | `datasetInfoScore` | String | - | ロケーション区分の精度 - 0に近いほど信頼度が低く、1に近いほど信頼度が高い | ### レスポンスボディ(失敗) 照会に失敗した場合のレスポンスボディの説明は次の通りです。 | フィールド | タイプ | 必須の有無 | 説明 | | --- | --- | --- | --- | | `result` | String | - | レスポンス結果 - `SUCCESS` \| `FAILURE` - `SUCCESS`: 成功 - `FAILURE`: 失敗 | | `status` | String | - | レスポンス結果の状態 | | `message` | String | - | レスポンス結果メッセージ | | `pose` | String | - | 画像名、tx、ty、tz、qw、qx、qy、qz値 | | `floor` | String | - | クエリ画像の層情報 | | `lonLat` | String | - | 順に経度(Longitude)、緯度(Latitude) | | `globalPose` | String | - | 順に画像名、緯度、経度、高度(altitude)、qw、qx、qy、qzの値 | | `confidence` | Number | - | 推定された姿勢の信頼度 - 0に近いほど信頼度が低く、1に近いほど信頼度が高い | ### レスポンス例 レスポンスのサンプルコードは次の通りです。 #### 成功 照会に成功した場合のレスポンスのサンプルコードは次の通りです。 ``` { "result": "SUCCESS", "status": "success", "message": "Localization successful", "tips": "", "pose": "VL0_0000050014880892_000000006.jpg,2.746507,9.889554,-20.729435,0.657244,-0.096816,-0.068169,0.744318", "total": 7738, "inlier": 1762, "inliers": [ { "U": 356.8439, "V": 146.9978, "X": 114.01553, "Y": 233.33755, "Z": 12.9115095 } ], "residual": 5.998124, "floor": "ground", "lonLat": "126.61787915108854,37.47318807235039", "globalPose": "VL0_0000050014880892_000000006.jpg,37.47318807235039,126.61787915108854,21.688565,0.657244,-0.096816,-0.068169,0.744318", "nnPoses" : [ "40027089_1665033685979869.jpg,753.835632,-1213.756958,10.821537,-0.248478,0.098745,-0.0035,0.963585", "40027089_1652160158579869.jpg,734.655884,-1225.50354,11.025743,0.947723,0.057711,-0.073033,0.305217", ... "40027089_1652160155379869.jpg,732.119873,-1227.255127,11.040028,0.948575,0.056153,-0.07237,0.303009", "40027089_1652160158979869.jpg,734.967834,-1225.28418,11.024983,0.946591,0.057514,-0.07298,0.308759" ], "datasetInfo": "NationalMuseumKorea_1F_T2B00652308180853", "confidence": 0.834586441516876 } ``` #### 成功(WiFi) WiFi Localizationによる照会に成功した場合のレスポンスのサンプルコードは次の通りです。 ``` { "result": "SUCCESS", "position": "16.6337711608804,5.690108685931897", "lonLat": "127.105412759367,37.359465269300976", "datasetInfo": "Naver_1784_1F", "datasetInfoScore": 0.6852494 } ``` #### 失敗 照会に失敗した場合のレスポンスのサンプルコードは次の通りです。 ``` { "result": "FAILURE", "status": "success", "message": "Invalid parameters", "pose": "", "floor": "", "lonLat": "", "globalPose": "", "confidence": 0 } ``` 参考 API呼び出しに失敗した場合のレスポンスボディとレスポンスのサンプルコードは、[ARC eyeの概要](/docs/ja/arc-eye-overview#%EC%9D%91%EB%8B%B5)をご参照ください。