Visual Localization

Available in Classic and VPC

Using information collected from vision devices, including cameras, you can check your current location even outdoors and indoors where GPS does not work, using only images. Additionally, it offers a location positioning service (WiFi Localization) that uses WiFi signal strength (RSSI) collected from the device to provide an approximate current location in indoor areas where GPS is unavailable. This allows for more accurate requests (radius search: lastPose + odometry combination) by providing both the approximate location of the device and location information.

Note

See the following for information about the WiFi Localization feature.

For more information about RSSI, see Received signal strength indicator.
The WiFi Localization feature is not supported for spaces scanned before July 2024.

Preliminary steps

The preliminary steps for using the ARC eye VL API are as follows:

1. Build spatial data

Build spatial data on the console. Proceed with all tasks in order, from SLAM data conversion to SLAM data merging, localization, and VL data conversion. For more information, see the ARC eye User Guides.

2. Deploy API

When VL data merging is successful, an API with a Pending status will be created in the ARC eye > Visual Localization > API menu of the NAVER Cloud Platform console. Select the API and deploy it. Once deployment is complete and the status is Completed, you can use the ARC eye VL API. You cannot deploy other APIs while the API service is Stopped.
For more information on deployment, see the ARC eye User Guides.

Request

This section describes the request format. The method and URI are as follows:

Method	URI
POST	InvokeURL

Note

The /api/vi~ path is the previous version of /vl/v1/~, which is the current version path.

Request headers

For information about the headers common to all ARC eye APIs, see ARC eye request headers.

Request body

You can include the following data in the body of your request:

Field	Type	Required	Description
`image`	File	Required	Positioning target image Can be omitted for WiFi requests
`cameraParameters`	String	Optional	Camera parameter information Operate with default values when not entered. fx, fy, cx, cy, k1, k2, p1, p2, k3 fx, fy: focal length of the camera lens cx, cy: principal point coordinates of the image sensor k1, k2: primary and secondary radial distortion correction coefficients of the lens p1, p2: tangential distortion correction coefficient of the lens k3: radial distortion correction coefficient of the lens
`lastPose`	String	Optional	6-dof pose information estimated at the time of query image generation Separated by commas Add `odometry` value to the most recent pose value received. Required when using `odometry`
`odometry`	String	Optional	Pose change between when the last query image was sent and when the current query image was sent Separated by commas Required when using `lastPose`
`withGlobal`	Boolean	Optional	How to interpret the `lastPose` value `true` \| `false` `true`: Interpret the `lastPose` value by "latitude, longitude, tz, qw, qx, qy, qz." `false`: Interpret the `lastPose` value by "tx, ty, tz, qw, qx, qy, qz."
`withInlier`	Boolean	Optional	Whether to display the valid 3D-2D correspondences (3D space points and corresponding 2D image pixel coordinates) used for location positioning `true` \| `false` `true`: display `false`: not display
`wifi`	File	Optional	WiFi signal strength scan file JSON format
`datasetInfo`	String	Optional	Perform a VL query using only the processed data corresponding to the location layer name. Location names are separated by commas.

Request example

The request example is as follows:

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'

Response

This section describes the response format.

Response body (success)

The following describes the response body when the query is successful.

Field	Type	Required	Description
`result`	String	-	Response result `SUCCESS` \| `FAILURE` \| `ERROR` `SUCCESS`: succeeded `FAILURE`: failed `ERROR`: error
`status`	String	-	Response result status
`message`	String	-	Response result message
`tips`	String	-	Reference information for location positioning results
`pose`	String	-	Image name, tx, ty, tz, qw, qx, qy, qz values
`total`	Number	-	Total number of feature points extracted from the query image
`inlier`	Number	-	Total number of valid feature points extracted from the query image
`inliers`	Array	-	Valid 3D-2D correspondences information used for location positioning
`residual`	Number	-	Projection error of valid features (in pixels)
`floor`	String	-	Floor information of the query image
`lonLat`	String	-	Longitude and latitude values
`globalPose`	String	-	Image name, longitude, latitude, altitude, qw, qx, qy, qz values
`nnPose`	Array	-	Image names of neighboring reference images, tx, ty, tz, qw, qx, qy, qz values
`datasetInfo`	String	-	A concatenation of the names of each layer separated by the scan
`confidence`	Number	-	Confidence value for estimated pose Closer to 0 means less confidence, closer to 1 means more confidence.
`position`	String	-	Two-degree-of-freedom position value in mapping space (XY plane)
`datasetInfoScore`	String	-	Location classification accuracy Closer to 0 means less confidence, closer to 1 means more confidence.

`inliers`

The following describes inliers.

Field	Type	Required	Description
`U`	Number	-	Pixel coordinates on 2D image
`V`	Number	-	Pixel coordinates on 2D image
`X`	Number	-	3D X point
`Y`	Number	-	3D Y point
`Z`	Number	-	3D Z point

Response body (WiFi success)

The following describes the response body when the query via WiFi Localization is successful.

Field	Type	Required	Description
`result`	String	-	Response result `SUCCESS` \| `FAILURE` `SUCCESS`: succeeded `FAILURE`: failed
`position`	String	-	Two-degree-of-freedom position value in mapping space (XY plane)
`lonLat`	String	-	Longitude and latitude values
`datasetInfo`	String	-	A concatenation of the names of each layer separated by the scan
`datasetInfoScore`	String	-	Location classification accuracy Closer to 0 means less confidence, closer to 1 means more confidence.

Response body (failure)

The following describes the response body when the query fails.

Field	Type	Required	Description
`result`	String	-	Response result `SUCCESS` \| `FAILURE` `SUCCESS`: succeeded `FAILURE`: failed
`status`	String	-	Response result status
`message`	String	-	Response result message
`pose`	String	-	Image name, tx, ty, tz, qw, qx, qy, qz values
`floor`	String	-	Floor information of the query image
`lonLat`	String	-	Longitude, latitude in order
`globalPose`	String	-	Image name, latitude, longitude, altitude, qw, qx, qy, qz values in order
`confidence`	Number	-	Confidence value for estimated pose Closer to 0 means less confidence, closer to 1 means more confidence.

Response example

The response example is as follows:

Succeeded

The following is a sample response upon a successful query.

{
  "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
}

Success (WiFi)

The following is a sample response when the query via WiFi Localization is successful.

{
  "result": "SUCCESS",
  "position": "16.6337711608804,5.690108685931897",
  "lonLat": "127.105412759367,37.359465269300976",
  "datasetInfo": "Naver_1784_1F",
  "datasetInfoScore": 0.6852494
}

Failure

The following is a sample response upon a failed query.

{
  "result": "FAILURE",
  "status": "success",
  "message": "Invalid parameters",
  "pose": "",
  "floor": "",
  "lonLat": "",
  "globalPose": "",
  "confidence": 0
}

Note

For response bodies and response examples when API calls fail, see ARC eye overview.