Query Mode

Choose between the fast default engine (VPS-1) and the slower, more accurate deep-search engine (VPS-2) for Single Frame Query.

What is Query Mode?

Query mode selects which localization engine handles a Single Frame Query. It lets you trade latency for accuracy on a per-request basis, without changing anything about your map or the rest of your request.

Mode	Speed	Accuracy	Use for
vps-1 (default)	Fastest (~2 seconds)	Standard	Real-time, interactive localization
vps-2	Slower (~3 to 4 seconds)	Up to 15% higher recall and improved accuracy	Offline or background workflows, difficult scenes

Query mode is set with the queryMode parameter. If you omit it, the request uses vps-1.

Query mode applies to the Single Frame Query only (/vps/map/query and /vps/map/query-form). It has no effect on the Multi Frame Query. For how single-frame and multi-frame queries differ, see Localization.

VPS-1 (Default)

vps-1 is the standard single-image engine and the default when queryMode is not provided. It returns a pose in roughly 2 seconds, which makes it the right choice for anything interactive.

Use VPS-1 when:

• You are localizing in real time (live AR, in-app navigation, continuous re-localization).

• Response time matters more than squeezing out the last few percent of accuracy.

• The scene is well textured and not visually repetitive.

VPS-2 (Deep Search)

vps-2 is a deep-search engine that searches more of the map before estimating a pose. It delivers up to 15% higher recall and improved accuracy, at the cost of higher latency (around 3 to 4 seconds per query).

Use VPS-2 when:

• You are running an offline or background workflow where a few extra seconds do not matter.

• The environment is challenging or visually repetitive (long corridors, basements, warehouses, transit stations) and vps-1 sometimes fails to find a pose.

• You want to verify or improve a result: retry a failed or low-confidence vps-1 query with vps-2.

• Accuracy is strictly more important than speed for the task.

A common pattern is to query with vps-1 first for a fast result and fall back to vps-2 only when the response has poseFound: false or low confidence.

API Usage

Pass queryMode alongside your usual query parameters. It is optional and defaults to vps-1. Allowed values are vps-1 and vps-2.

JSON body (/vps/map/query)

{
    "mapCode": "MAP_RJFKKWQ1787J",
    "queryMode": "vps-2",
    "queryImage": "data:image/png;base64,...",
    "cameraIntrinsics": { "fx": 664.38, "fy": 664.38, "px": 478.97, "py": 364.99 }
}

Form-data (/vps/map/query-form)

On the form-data endpoint, queryMode is a plain string form field:

queryMode: vps-2

See Map Query for the full request and response reference.