# 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
### 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
---
# Agent Instructions: 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:
```
GET https://docs.multiset.ai/basics/localization/hint-floor-height.md?ask=
```
The question should be specific, self-contained, and written in natural language.
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.
