# HintFloorHeight

### Overview

`hintFloorHeight` is a localization hint that limits the search to a specific vertical range. This is particularly useful in multi-floor buildings where frames from different floors may look visually similar.

By filtering to the expected floor before running feature matching, you reduce both the search space and the likelihood of cross-floor mismatches.

### How It Works

The VPS system uses map-local Y coordinates to represent height. When you provide `hintFloorHeight: [y_min, y_max]`, the search runs within that Y range only.

**Coordinate system notes:**

* Y is the vertical axis in both single-Map and MapSet (global) coordinate spaces
* Positive Y is typically up, but the exact values depend on how your map was captured
* For MapSet queries, positions are expressed in the shared global coordinate system

<figure><img src="https://3163433004-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FokTDI7QVY04Zvb1pQ8Ry%2Fuploads%2Fb0EhuF889sow0L6Sf3Fb%2FScreenshot%202026-04-07%20at%206.00.15%E2%80%AFPM.png?alt=media&#x26;token=dc994919-7657-40f0-9e65-92b5126a140d" alt=""><figcaption></figcaption></figure>

### Parameter Format

| Endpoint type                                                   | Format               | Example                           |
| --------------------------------------------------------------- | -------------------- | --------------------------------- |
| JSON body (`/vps/map/query`)                                    | Array of two numbers | `"hintFloorHeight": [1.5, 4.5]`   |
| Form-data (`/vps/map/query-form`, `/vps/map/multi-image-query`) | JSON-encoded string  | `"hintFloorHeight": "[1.5, 4.5]"` |

Order does not matter — `[-3, -1]` and `[-1, -3]` both select frames with y ∈ \[-3, -1].

***

### Combination with hintPosition

`hintFloorHeight` and `hintPosition` can be used together. The pipeline applies them in sequence:

1. **hintPosition** — filters to frames within the 25 m horizontal radius
2. **hintFloorHeight** — further restricts to frames within the vertical band

This two-stage filter is ideal when you know both the approximate XZ location and the floor level.

***

### Examples

```json
// Floor 1: floor at y=0, ceiling at y=3.0
{
  "hintFloorHeight": [0.0, 3.0]
}

// Floor 2: floor at y=3.0, ceiling at y=6.0
{
  "hintFloorHeight": [3.0, 6.0]
}

// Basement (negative Y)
{
  "hintFloorHeight": [-3.0, -0.5]
}

// Combined with hintPosition (JSON body)
{
  "hintPosition": [12.5, 2.0, -7.3],
  "hintFloorHeight": [0.0, 3.0]
}

// Form-data endpoint — pass as JSON string
"hintFloorHeight": "[1.5, 4.5]"
```

**MapSet multi-map example:** In a MapSet where Floor 1 maps span y ∈ \[0, 3] in global space, pass `"hintFloorHeight": [0, 3]` to restrict search to only Floor 1 maps across all constituent maps.

***

### Best Practices

* Measure floor and ceiling Y values from a known localization result or from the map's coordinate metadata
* Add a small buffer (e.g. ±0.3 m) to account for device height variation and imprecise floor detection
* For tall single-floor spaces (e.g. warehouses), use a generous range that covers the full height of the space
* Combine with `hintPosition` when you have both horizontal and vertical context — this gives the tightest search scope and best latency