MENU
      ARC eye VL API
        • PDF

        ARC eye VL API

        • PDF

        Article summary

        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

        MethodRequest URI
        POSTCall with the InvokeURL of ARC eye > API > Check API integration key

        Request headers

        NameDescription
        X-ARCEYE-SECRETUse the secret key of ARC eye > API > Check API integration key
        Content-Typemultipart/form-data

        Request body

        Field nameRequiredData typeDescriptionRestrictions
        imageYfileCan be omitted for WiFi requests
        cameraParametersNstringEnter 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
        lastPoseNstring- 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
        odometryNstring- 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
        withGlobalNboolean- 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"
        withInlierNbooleanIf true, valid 3D-2D correspondences used during positioning are added to the response
        wifiNfileWiFi signal strength scan file in JSON format
        datasetInfoNstringPerform 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'
        Bash
        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 datasetInfo="1F,T2B00652308180853"
        Bash

        Response

        Response body

        Field nameData typeDescription
        resultstringResponse result: "SUCCESS", "FAILURE"
        messagestringResult message
        tipsstringAdditional information
        posestringIt refers to the image name, tx, ty, tz, qw, qx, qy, qz values
        totalintTotal number of feature points extracted from the query image
        inlierintTotal number of valid feature points extracted from the query image
        inliersarrayValid 3D-2D correspondences used for localization
        - [U,V]: pixel coordinates on the image
        - [X,Y,Z]: corresponding 3D points
        residualfloatprojection error of valid feature points (in pixels)
        statusstringServer status
        floorstringFloor information of the query image
        lonLatstringLongitude, latitude
        globalPosestringIt refers to the image name, longitude, latitude, altitude, qw, qx, qy, qz values
        nnPosesstring[]It refers to the image names of neighboring reference images, tx, ty, tz, qw, qx, qy, qz values
        datasetInfostringA concatenation of the names of each layer separated by the scan
        confidencefloatConfidence value for the estimated pose (value between 0 and 1, the closer to 1, the higher the confidence)

        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",
          "confidence" : 0.834586441516876
        }
        JSON
        {
          "result": "FAILURE",
          "status": "success",
          "message": "internal server error",
          "pose": "failed",
          "floor": "",
          "lonLat": "",
          "globalPose": "",
          "datasetInfo": ""
        }
        JSON

        Error code

        Error response:

        {
          "code": "9999",
          "message": "Unknown server error.",
          "path": "/api/v1",
          "product": "ARC eye",
          "traceId": "9c1f55ac7d8341d792a922b2590c045f",
          "timestamp": 1570776853475,
          "status": "500"
        }
        JSON
        Error codeHTTP statusDescription
        0001404Not Found
        0020401Unauthorized
        0030403Forbidden
        010040xInvalid Parameter
        0101409Duplicate
        100050xInternal API Error
        1001500Processing Error
        9999500Unknown Error

        WiFi response

        WiFi response body

        Field nameData typeDescription
        resultstringResponse result: "SUCCESS", "FAILURE"
        messagestringResult message
        positionstringtwo-degree-of-freedom position value in mapping space (XY plane)
        lonLatstringLongitude, latitude
        datasetInfostringA concatenation of the names of each layer separated by the scan
        datasetInfoScorefloatLocation 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
        }
        JSON

        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",
          "errors": { // optional
            "datasetInfo": "Naver_1784_1F",
            "datasetInfoScore": 0.6852494
          }
        }
        JSON
        Error codeHTTP statusDescription
        0001404Not Found
        0020401Unauthorized
        0030403Forbidden
        010040xInvalid Parameter
        0100400"there is no location" (if the location parameter is not passed)
        0100400"failed to parse wifi scan file" (if there is a problem with the WiFi data entered)
        0100404"failed to get location info from qdrant: xxx" (if information about the location is not available from the Qdrant DB)
        0100404"failed to get wifi-finder model file from S3" (if there is no processed WiFi Finder model)
        0100404"wifi-loc model does not exists" (if there is no processed WiFi Loc model)
        0100422"failed, it has low dataset info score" (if there is no valid (strong) WiFi signal at the target location)
        0100422"failed to get location info from qdrant: xxx" (if location is difficult to distinguish due to low DatasetInfoScore)
        0101409Duplicate
        1000500"No matching AP list exists" (if there is no WiFi signal with a matching MAC address)
        1000500"failed to load qdrant" (If there is an error between internal server communication (no communication with Qdrant vector DB))
        1000500"failed to get global position filefrom qdrant" (if there is an error between internal server communication (global position information is not received from Qdrant))
        1000500"out of service, due to there is no valid xxx" (if there is an error between internal server communication (no xxx))
        1001500Processing Error
        9999500Unknown Error

        Was this article helpful?

        Changing your password will log you out immediately. Use the new password to log back in.
        First name must have atleast 2 characters. Numbers and special characters are not allowed.
        Last name must have atleast 1 characters. Numbers and special characters are not allowed.
        Enter a valid email
        Enter a valid password
        Your profile has been successfully updated.