The REST API is used to interact with the Immersal Cloud Service. It can be used to submit images for map construction, construct maps, load them, and even run the visual positioning localization process on the Cloud Service.
All REST API calls take JSON as input and also return the result as JSON.
All calls, except login
, need a valid developer token for authentication.
We provide a sample implementation in C# (see the REST.cs
class in the SDK samples). It should be quite straightforward to make the API calls in JSON from e.g. JavaScript & WebXR applications, and on other platforms.
count
and a list of all jobs.{"error": "none","count": 2,"jobs": [{"id": 9383,"version": "1.8.0","creator": "[email protected]","bank": 0,"size": 15,"work": "/im/s00/job/IEuomF","status": "done","privacy": "0","server": "172.31.0.163","name": "TestMap","latitude": 60.163257817728663,"longitude": 24.939001151402682,"altitude": 19.666602622779706,"created": "2020-09-11 13:56:51","modified": "2020-09-11 13:57:19","sha256_al": "3b1a83c27e6a61fa376dfe42d8196e076bd29e77ac133ba3531ac9385a5c1f66","sha256_sparse": "1d985d30ad2fcbbf5d08eb5bc78238e6c386d15eba796c0d36aaf3701477af1b","sha256_dense": "ef72bd391c92d365e86419ca22013c9ce709396c4372b5e5a8663127f961fdd3","sha256_tex": "c7d7638c3bdba3b18d37abee82d8b36e2e97312980590f455025faa51c816ac5"}, {"id": 8924,"version": "1.7.0","creator": "[email protected]","bank": 0,"size": 62,"work": "/im/s00/job/QvkuFY","status": "done","privacy": "0","server": "172.31.22.8","name": "M01courtyard","latitude": 60.167185396129049,"longitude": 24.922240769354836,"altitude": 42.585041169197332,"created": "2020-08-27 10:44:09","modified": "2020-08-27 10:44:09","sha256_al": "1ea5f978575651629c703b070acf95e4585864226fcde72674643c29a50893c4","sha256_sparse": "dc41d50657f503a3b78cd76895315097abb8b68846d7fefc26f873ae0eff7217","sha256_dense": "fa1d9667a338920ad65e955f36312feb06980edd3ff0c9ab0c6456a8c82a42ff","sha256_tex": ""}]}​
{"error": "none","id": 7065,"size: 300}
token
is not given, all public maps within the defined area will be listed.count
and a list of all jobs.{"error": "none","count": 2,"jobs": [{"id": 9383,"version": "1.8.0","creator": "[email protected]","bank": 0,"size": 15,"work": "/im/s00/job/IEuomF","status": "done","privacy": "0","server": "172.31.0.163","name": "TestMap","latitude": 60.163257817728663,"longitude": 24.939001151402682,"altitude": 19.666602622779706,"created": "2020-09-11 13:56:51","modified": "2020-09-11 13:57:19","sha256_al": "3b1a83c27e6a61fa376dfe42d8196e076bd29e77ac133ba3531ac9385a5c1f66","sha256_sparse": "1d985d30ad2fcbbf5d08eb5bc78238e6c386d15eba796c0d36aaf3701477af1b","sha256_dense": "ef72bd391c92d365e86419ca22013c9ce709396c4372b5e5a8663127f961fdd3","sha256_tex": "c7d7638c3bdba3b18d37abee82d8b36e2e97312980590f455025faa51c816ac5"}, {"id": 8924,"version": "1.7.0","creator": "[email protected]","bank": 0,"size": 62,"work": "/im/s00/job/QvkuFY","status": "done","privacy": "0","server": "172.31.22.8","name": "M01courtyard","latitude": 60.167185396129049,"longitude": 24.922240769354836,"altitude": 42.585041169197332,"created": "2020-08-27 10:44:09","modified": "2020-08-27 10:44:09","sha256_al": "1ea5f978575651629c703b070acf95e4585864226fcde72674643c29a50893c4","sha256_sparse": "dc41d50657f503a3b78cd76895315097abb8b68846d7fefc26f873ae0eff7217","sha256_dense": "fa1d9667a338920ad65e955f36312feb06980edd3ff0c9ab0c6456a8c82a42ff","sha256_tex": ""}]}​
{"error": "none","imageCount": 5,"bankMax": 1,"imageMax": 256,"eulaAccepted": true}
{"error": "none","path": "path_on_the_server"}
{"error": "none","token": "xyz","banks": 1 // number of image banks, limited to 1 currently}
{"error": "auth" // invalid username}​{"error": "password" // wrong password}
anchor
parameter to false
will retain the anchor image.{"error": "none"}
{"error": "none","success": true,"map": 7587,"px": -0.5459369421005249,"py": 0.0632220059633255,"pz": 0.36885133385658264,"r00": 0.68967300653457642,"r01": 0.14381979405879974,"r02": -0.709695041179657,"r10": 0.0070222793146967888,"r11": 0.97870355844497681,"r12": 0.20515856146812439,"r20": 0.7240869402885437,"r21": -0.14647600054740906,"r22": 0.67397546768188477}
{"error": "none","success": true,"map": 7587,"px": -0.5459369421005249,"py": 0.0632220059633255,"pz": 0.36885133385658264,"r00": 0.68967300653457642,"r01": 0.14381979405879974,"r02": -0.709695041179657,"r10": 0.0070222793146967888,"r11": 0.97870355844497681,"r12": 0.20515856146812439,"r20": 0.7240869402885437,"r21": -0.14647600054740906,"r22": 0.67397546768188477}
{"error": "none","b64": "azdfazdf","sha256_al": "hash"}​
{"error": "none"}
{"error": "none"}
{"error": "none","ecef":[2884704.4529634975,1341415.1204073559,5509576.2819128353,0.48534169793128967,0.87242347002029419,0.05762564018368721,0.23218682408332825,-0.19214998185634613,0.9535028338432312,0.84293103218078613,-0.44939476251602173,-0.29582363367080688,9.4544391632080078]}
The code below is an example of using the REST API to log in a user and retrieving their token. Except for the SDKLoginRequest
class, all other Request
classes inherit the requisite token from SDKRequestBase
.
See the Immersal.Samples.Mapping.MapperJobs
and Immersal.Samples.Mapping.Mapper
classes and Samples/Scenes/MappingApp
for more examples.
SDKLoginRequest loginRequest = new SDKLoginRequest();loginRequest.login = "[email protected]";loginRequest.password = "password";​string jsonString = JsonUtility.ToJson(loginRequest);using (UnityWebRequest request = UnityWebRequest.Put(string.Format(Endpoint.URL_FORMAT, m_Sdk.localizationServer, Endpoint.LOGIN), jsonString)){request.method = UnityWebRequest.kHttpVerbPOST;request.useHttpContinue = false;request.SetRequestHeader("Content-Type", "application/json");request.SetRequestHeader("Accept", "application/json");yield return request.SendWebRequest();​SDKLoginResult loginResult = JsonUtility.FromJson<SDKLoginResult>(request.downloadHandler.text);if (loginResult.error == "none"){Debug.Log(loginResult.token);}}
Represents a server job that is calculating the map
[Serializable]public class SDKJob{public int id;public int size;public int bank;public string work;public string status; // "done" | "sparse" | "processing" | "failed" | "pending"public string server;public string name;public double latitude;public double longitude;public double altitude;public string created;public string modified;}
Encapsulates a map's ID, might be extended in the future. Currently only used in SDKLocalizeRequest
. In JavaScript and other platforms, this could be represented as a typical JSON object, e.g. {"id": 6779}
.
[Serializable]public class SDKMapId{public int id;}
Log in request / response
[Serializable]public class SDKLoginRequest{public string login;public string password;}​[Serializable]public class SDKLoginResult{public string error; // "none" | "auth"public string token; // developer tokenpublic int banks; // number of image banks, limited to 1 currently}
Clear request / response
[Serializable]public class SDKClearRequest : SDKRequestBase{public int bank; // id of image bank to clearpublic bool anchor; // if true, clears also anchor points (i.e. empty cloud)}​[Serializable]public class SDKClearResult{public string error;}
Construct request / response
[Serializable]public class SDKConstructRequest : SDKRequestBase{public int bank; // id of image bankpublic string name; // name for the map}​[Serializable]public class SDKConstructResult{public int id; // id of the construction job / mappublic int size; // number of images used to create the mappublic string error;}
Status request / response
[Serializable]public class SDKStatusRequest : SDKRequestBase{public int bank;}​[Serializable]public class SDKStatusResult{public int imageCount;public int bankMax;public int imageMax;public bool eulaAccepted;public string error;}
Jobs request / response
[Serializable]public class SDKJobsRequest : SDKRequestBase{public int bank;}​[Serializable]public class SDKJobsResult{public int count;public SDKJob[] jobs;public string error;}
The same as SDKJobsRequest
, but only fetches the maps within the user's GPS location and range. If token
is not given, all public maps will be fetched.
public class SDKGeoJobsRequest : SDKJobsRequest{public double latitude;public double longitude;public double radius;}
Image request / response
[Serializable]public class SDKImageRequest : SDKRequestBase{public int bank;public int run;public int index;public bool anchor;public double px; // camera x positionpublic double py; // camera y positionpublic double pz; // camera z positionpublic double r00; // rotation matrix row 0, col 0public double r01; // rotation matrix row 0, col 1public double r02; // rotation matrix row 0, col 2public double r10; // rotation matrix row 1, col 0public double r11; // rotation matrix row 1, col 1public double r12; // rotation matrix row 1, col 2public double r20; // rotation matrix row 2, col 0public double r21; // rotation matrix row 2, col 1public double r22; // rotation matrix row 2, col 2public double fx; // camera intrinsics focal length xpublic double fy; // camera intrinsics focal length ypublic double ox; // camera intrinsics principal point xpublic double oy; // camera intrinsics principal point ypublic double latitude; // WGS84 latitudepublic double longitude; // WGS84 longitudepublic double altitude; // GPS elevationpublic string b64; // Base64-encoded PNG image, 8-bit grayscale or 24-bit RGB}​[Serializable]public class SDKImageResult{public string path;}
Localize request / response
The result (when localization has been successful) is a projection matrix in the AR Cloud space. It can be used to extract the position and rotation of the AR device, which then again can be combined with the device's local SLAM tracking.
[Serializable]public class SDKLocalizeRequest : SDKRequestBase{public double fx; // camera intrinsics focal length xpublic double fy; // camera intrinsics focal length ypublic double ox; // camera intrinsics principal point xpublic double oy; // camera intrinsics principal point ypublic string b64; // Base64-encoded PNG image, 8-bit grayscale or 24-bit RGBpublic SDKMapId[] mapIds; // list of maps to localize against}​[Serializable]public class SDKLocalizeResult : SDKResultBase{public bool success;public int map; // ID of the map if localization was successfulpublic float px; // x position within the mappublic float py; // y position within the mappublic float pz; // z position within the mappublic float r00; // rotation matrix row 0, col 0public float r01; // rotation matrix row 0, col 1public float r02; // rotation matrix row 0, col 2public float r10; // rotation matrix row 1, col 0public float r11; // rotation matrix row 1, col 1public float r12; // rotation matrix row 1, col 2public float r20; // rotation matrix row 2, col 0public float r21; // rotation matrix row 2, col 1public float r22; // rotation matrix row 2, col 2}
Geo-localize request. The response is the same as with
SDKLocalizeRequest
.
This request localizes against maps within a given radius near the device's GPS coordinates. The mapIds
array can be left empty in this case.
[Serializable]public class SDKGeoLocalizeRequest : SDKLocalizeRequest{public double latitude;public double longitude;public double radius;}
ECEF request / response
[Serializable]public class SDKEcefRequest : SDKRequestBase{public int id; // map ID}​[Serializable]public class SDKEcefResult : SDKResultBase{public double[] ecef; // ECEF coordinates}
Delete map request / response
[Serializable]public class SDKDeleteMapRequest : SDKRequestBase{public int id; // map ID}​[Serializable]public class SDKDeleteMapResult : SDKResultBase{​}
Restore map images request / response
After restoring the map's images, it is possible to add more images to the map and recalculate it.
[Serializable]public class SDKRestoreMapImagesRequest : SDKRequestBase{public int id; // map ID}​[Serializable]public class SDKRestoreMapImagesResult : SDKResultBase{​}
Map request / response
[Serializable]public class SDKMapRequest : SDKRequestBase{public int id; // map ID}​[Serializable]public class SDKMapResult{public string md5_al; // MD5 hash for the loaded mappublic string b64; // Base64 encoded .bytes map file}
The REST API uses the following error codes (TBD):
Error Code | Meaning |
400 | Bad Request -- Your request is invalid. |
​