Ctrlk
Developer PortalDemosGithub
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Equirect Query

Localize from a single 360° equirectangular panorama, with no camera intrinsics to supply.

What is an equirect query?

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 pose you get back

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.

Input requirements

Requirement
Value

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.

When to use it

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.

Rules and interactions

  • 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.

Response

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.

PreviousQuery Mode
NextHintFloorHeight

Last updated

Was this helpful?