Localize from a single 360° equirectangular panorama, with no camera intrinsics to supply.
An equirect query localizes a full 360° panorama instead of a perspective photo. You send one equirectangular image and get back one 6-DoF pose.
Set imageType to equirect on the form-data query endpoint:
curl -X POST "$BASE_URL/v1/vps/map/query-form" \
-H "Authorization: Bearer $TOKEN" \
-F "imageType=equirect" \
-F "mapCode=MAP_XXXXXXXXXXXX" \
-F "isRightHanded=true" \
-F "queryImage=@panorama.jpg"That is the whole request. Note what is not in it: no fx, no fy, no px, no py, no width, no height. A pinhole query needs those before a pixel can become a direction. An equirectangular image carries that already, so there is nothing to send.
The returned pose is the pose of the forward-looking view: the direction the centre column of the panorama faces.
That is the one thing to keep in mind when you use the result. Position is simply where the panorama was taken, but the rotation is only meaningful once you know which way "forward" is. If your panorama is oriented so its centre column points along your robot's or trolley's direction of travel, the returned rotation is that heading.
Projection
Equirectangular, the full sphere
Aspect ratio
At least 1.9:1, so a normal 2:1 panorama passes
Width
2048 to 16384 px
Format
JPEG or PNG, 30 MB or smaller
A file that misses the aspect or width rules returns 400. One that is only too large returns 413.
Larger is not better. A 4096 x 2048 panorama is a good default: plenty of detail, and a much smaller upload than a 16k image. Go wider only if you have measured a benefit on your own maps.
Equirect queries suit captures where the camera is not pointed by a person:
Tripod, trolley, and pole captures, where you already produce panoramas.
Robots and AMRs carrying a 360° camera, where the heading at query time is arbitrary.
Re-localizing against a 360 capture, using the same kind of imagery the map was built from.
Because one panorama covers the whole horizon, the query does not depend on the user happening to face a well-mapped surface. That makes it robust in corridors and open floors where a single perspective frame can easily point at a blank wall.
For a hand-held AR session, a pinhole frame from the device camera remains the right choice. It is smaller, faster, and it is what the SDKs already capture.
Optional. Omit imageType and the query runs as pinhole, so nothing changes for existing integrations.
Takes precedence over queryMode. A queryMode sent alongside imageType=equirect is not used. This is not an error.
Intrinsics are ignored, not rejected. If your client always sends fx and fy, you do not have to strip them.
All localization parameters work, including hintPosition, hintRadius, hintFloorHeight, geoHint, and hintMapCodes. See Localization.
Maps, MapSets, and versioned maps are all supported.
isRightHanded behaves as it does everywhere else. The returned pose follows the convention you declare. See Coordinate Systems.
This is a REST-only feature. The Unity, Quest, iOS, and Android SDKs capture perspective frames from the device camera and do not expose imageType. To use equirect queries, call the REST endpoint directly.
The response is the same shape as a pinhole query, so a client that already reads one needs no changes:
When no pose can be found, poseFound is false with an accompanying message.
Last updated
Was this helpful?
Was this helpful?
{
"poseFound": true,
"position": { "x": 3.90, "y": 2.22, "z": 7.68 },
"rotation": { "x": 0.0009, "y": 0.7455, "z": -0.0227, "w": 0.6662 },
"confidence": 0.91,
"mapIds": ["67e12d4bff7ecf561f2f8a0c"],
"mapCodes": ["MAP_XXXXXXXXXXXX"]
}