ARC eye VL API
- Print
- PDF
ARC eye VL API
- Print
- PDF
Article summary
Did you find this summary helpful?
Thank you for your feedback
Overview
The ARC eye Visual Localization (VL) API provides positioning services that use information collected from vision devices, including cameras, to pinpoint your current location outdoors as well as indoors without GPS coverage. You can get indoor location data from images alone.
Note
WiFi Localization: This feature provides additional location services that use WiFi signal strength (RSSI) collected from the device to approximate where you are indoors without GPS coverage. The location information is provided along with the approximate location of the device. This can be used to send more accurate ARC eye VL API requests (radius research: lastPose + odometry combination).
Reference: What is RSSI?
Caution
ARC eye WiFi Localization is not supported for spaces scanned before July 2024.
Build spatial data
You can build spatial data in the console to use the VL API. You need to do everything in order, from converting SLAM data, to merging SLAM data, to localizing, to converting VL data. For more information, see the ARC eye User Guide.
Prepare API
Once the VL data merge is successful, an API is created in the ARC eye > API menu with a status of "Pending." Select and deploy that API to use the VL API.
If you create another API and change the version to deploy, the existing API will be stopped. * You can't deploy another API while it is stopped.
Request
| Method | Request URI |
|---|---|
| POST | Call with the InvokeURL of ARC eye > API > Check API integration key |
Request headers
| Name | Description |
|---|---|
| X-ARCEYE-SECRET | Use the secret key of ARC eye > API > Check API integration key |
| Content-Type | multipart/form-data |
Request body
| Field name | Required | Data type | Description | Restrictions |
|---|---|---|---|---|
| image | Y | file | Can be omitted for WiFi requests | |
| cameraParameters | N | string | Enter the camera parameter information. If not entered, it runs with default values fx, fy, cx, cy, k1, k2, p1, p2, k3 - (fx,fy): focal length - (cx,cy): principal point - (k1,k2): radial distortion - (p1,p2): tangential distortion - (k3): radial distortion | |
| lastPose | N | string | - Comma-separated 6-DoF pose information for the image estimated at the time the query image was created - Add the odometry value to the recently responded pose value | Must be used with odometry |
| odometry | N | string | - Comma-separated 6-DoF pose information - Pose change between when the last query image was sent and when the current query image was sent | Must be used with lastPose |
| withGlobal | N | boolean | - If true, interpret lastPose value as "latitude, longitude, tz, qw, qx, qy, qz" - If not set or false, interpret lastPose value as "tx, ty, tz, qw, qx, qy, qz" | |
| withInlier | N | boolean | If true, valid 3D-2D correspondences used during positioning are added to the response | |
| wifi | N | file | WiFi signal strength scan file in JSON format | |
| datasetInfo | N | string | Perform a VL query using only the processed data corresponding to the location layer name (location names are separated by a comma) |
CURL example:
curl -X POST '{invokeUrl}' \
-H 'X-ARCEYE-SECRET: {secretKey}' \
-H 'Content-Type: multipart/form-data' \
-F 'image=@location.jpg;type=image/jpeg'
curl -X POST '{invokeUrl}' \
-H 'X-ARCEYE-SECRET: {secretKey}' \
-H 'Content-Type: multipart/form-data' \
-F 'image=@location.jpg;type=image/jpeg' \
-F 'odometry=0,0,0,1,0,0,0' \
-F 'lastPose=0,0,0,1,0,0,0' \
-F 'cameraParameters=1186.7,1406.5,540,960,0.0,0.0,0.0,0.0,0.0' \
-F 'withInlier=true' \
-F dataset_info="1F,T2B00652308180853"
Response
Response body
| Field name | Data type | Description |
|---|---|---|
| result | string | Response result: "SUCCESS", "FAILURE" |
| message | string | Result message |
| tips | string | Additional information |
| pose | string | It refers to the image name, tx, ty, tz, qw, qx, qy, qz values |
| total | int | Total number of feature points extracted from the query image |
| inlier | int | Total number of valid feature points extracted from the query image |
| inliers | array | Valid 3D-2D correspondences used for localization - [U,V]: pixel coordinates on the image - [X,Y,Z]: corresponding 3D points |
| residual | float | projection error of valid feature points (in pixels) |
| status | string | Server status |
| floor | string | Floor information of the query image |
| lonLat | string | Longitude, latitude |
| globalPose | string | It refers to the image name, longitude, latitude, altitude, qw, qx, qy, qz values |
| nnPoses | string[] | It refers to the 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 |
Response example
{
"result": "SUCCESS",
"status": "success",
"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": [
"VL0_1663124545528216.jpg,3.219894,17.559616,-19.898514,0.720037,-0.121523,-0.006865,0.683177",
"VL1_1663124536528144.jpg,3.498234,18.586061,-20.282135,0.721541,-0.07256,-0.117165,0.678518",
"VL2_1663124537528455.jpg,2.849693,18.648811,-20.386539,0.631969,-0.018601,-0.109304,0.767022",
"VL0_1663124544528213.jpg,3.159655,16.287134,-19.874195,0.701073,-0.139553,0.015575,0.699127",
"VL1_1663124521528042.jpg,4.446866,15.010426,-19.975168,0.755891,-0.150474,-0.035666,0.636171",
"VL1_1663124543528186.jpg,3.704958,15.066489,-20.11025,0.761836,-0.152187,-0.059388,0.626832",
"VL4_1663124540528089.jpg,4.224849,16.700996,-20.057743,0.601045,-0.055503,-0.034118,0.796555",
"VL0_1663124547528227.jpg,2.683109,20.13681,-20.074528,0.543752,-0.150696,-0.013089,0.825502",
"VL4_1663124516527975.jpg,3.005801,17.602791,-20.282951,0.761109,-0.017261,-0.000655,0.648394",
"VL2_1663124520528189.jpg,5.639919,15.146515,-19.748491,0.675394,-0.108291,-0.088871,0.724029",
"VL1_1663124513527983.jpg,4.592686,18.804764,-20.067684,0.770351,-0.120287,-0.11107,0.616242"
],
"datasetInfo": "NationalMuseumKorea_1F_T2B00652308180853"
}
{
"result": "FAILURE",
"status": "success",
"message": "internal server error",
"pose": "failed",
"floor": "",
"lonLat": "",
"globalPose": "",
"datasetInfo": ""
}
Error code
Error response:
{
"code": "9999",
"message": "Unknown server error.",
"path": "/api/v1",
"product": "ARC eye",
"traceId": "9c1f55ac7d8341d792a922b2590c045f",
"timestamp": 1570776853475,
"status": "500"
}
| Error code | HTTP status | Description |
|---|---|---|
| 0001 | 404 | Not Found |
| 0020 | 401 | Unauthorized |
| 0030 | 403 | Forbidden |
| 0100 | 40x | Invalid Parameter |
| 0101 | 409 | Duplicate |
| 1000 | 50x | Internal API Error |
| 1001 | 500 | Processing Error |
| 9999 | 500 | Unknown Error |
WiFi response
WiFi response body
| Field name | Data type | Description |
|---|---|---|
| result | string | Response result: "SUCCESS", "FAILURE" |
| message | string | Result message |
| position | string | two-degree-of-freedom position value in mapping space (XY plane) |
| lonLat | string | Longitude, latitude |
| datasetInfo | string | A concatenation of the names of each layer separated by the scan |
| datasetInfoScore | float | Location classification accuracy (closer to 0 means less confidence, closer to 1 means more confidence) |
WiFi response example
{
"result": "SUCCESS",
"position": "16.6337711608804,5.690108685931897",
"lonLat": "127.105412759367,37.359465269300976",
"datasetInfo": "Naver_1784_1F",
"datasetInfoScore": 0.6852494
}
WiFi error code
Error response:
{
"traceId": "3d77c10b1a0646659b6c897a35a5fa64",
"path": "/vl/v1/300568/9bb1a2b6f8031e355dfdb8e5205a1f7a860b167a0fcbd35681235f35c3629634/location",
"timestamp": 1725449250446,
"product": "ARC eye",
"status": 422,
"code": "0100",
"message": "Invalid parameters.",
"details": "there are no valid signals"
}
| Error code | HTTP status | Description |
|---|---|---|
| 0001 | 404 | Not Found |
| 0020 | 401 | Unauthorized |
| 0030 | 403 | Forbidden |
| 0100 | 40x | Invalid Parameter |
| 0100 | 400 | "there is no location" (if the location parameter is not passed) |
| 0100 | 400 | "failed to parse wifi scan file" (if there is a problem with the WiFi data entered) |
| 0100 | 404 | "failed to get location info from qdrant: xxx" (if information about the location is not available from the Qdrant DB) |
| 0100 | 404 | "failed to get wifi-finder model file from S3" (if there is no processed WiFi Finder model) |
| 0100 | 404 | "wifi-loc model does not exists" (if there is no processed WiFi Loc model) |
| 0100 | 422 | "failed, it has low dataset info score" (if there is no valid (strong) WiFi signal at the target location) |
| 0100 | 422 | "failed to get location info from qdrant: xxx" (if location is difficult to distinguish due to low DatasetInfoScore) |
| 0101 | 409 | Duplicate |
| 1000 | 500 | "No matching AP list exists" (if there is no WiFi signal with a matching MAC address) |
| 1000 | 500 | "failed to load qdrant" (If there is an error between internal server communication (no communication with Qdrant vector DB)) |
| 1000 | 500 | "failed to get global position filefrom qdrant" (if there is an error between internal server communication (global position information is not received from Qdrant)) |
| 1000 | 500 | "out of service, due to there is no valid xxx" (if there is an error between internal server communication (no xxx)) |
| 1001 | 500 | Processing Error |
| 9999 | 500 | Unknown Error |
Was this article helpful?