> For the complete documentation index, see [llms.txt](https://multiset.gitbook.io/multiset/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://multiset.gitbook.io/multiset/fundamentals/localization/equirect-query.md).

# Equirect Query

### 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](/multiset/fundamentals/rest-api-docs/map-query.md#image-type-imagetype):

```bash
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`.

{% hint style="info" %}
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.
{% endhint %}

### 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](/multiset/fundamentals/localization.md).
* **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](/multiset/fundamentals/localization/coordinate-systems.md).

{% hint style="warning" %}
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.
{% endhint %}

### Response

The response is the same shape as a pinhole query, so a client that already reads one needs no changes:

```json
{
  "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"]
}
```

When no pose can be found, `poseFound` is `false` with an accompanying message.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://multiset.gitbook.io/multiset/fundamentals/localization/equirect-query.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.