Map Versioning

Merge scans of the same space captured at different times, without breaking the content layer.

Overview

MultiSet Map Versioning lets developers merge scans captured at different intervals into a single coordinate system. Unlike traditional scan merging, which relies on algorithms like ICP and weak visual features, MultiSet Map Versioning is powered by the MultiSet VPS under the hood. This means it can merge scans taken months apart, even when there are significant visual and geometric changes between them.

With Map Versions, a developer's content layer coordinates don't need to be updated when a map is updated, even if a different local coordinate system is used, MultiSet handles the transformation automatically.

Map Version panel — toggle Query Active per map to control which maps are used for localization

When to use Map Versioning

Use a Map Version when you are updating a scan of a space you have already mapped, whether you re-scanned the whole space or only part of it. The new scan covers the same physical area as the original, and versioning keeps your content layer anchored to the original coordinate frame.

Extending coverage instead? Use a MapSet. If the new scan covers additional area rather than re-capturing existing area, for example a new wing, an adjacent building, or another floor, add it to a MapSet instead of creating a Map Version. Map Versioning is for the same area over time; a MapSet is for stitching different areas together.

Your situation	Use
Re-scanned the whole space	Map Version
Re-scanned one section of the space	Map Version, with both maps Query Active
Scanned a new area to extend coverage	MapSet
Re-scanned one map that is already inside a MapSet	Map Version on that individual map

How it works

A Map Version groups two or more scans of the same physical space:

• One scan is the base map, its coordinate frame is the version's coordinate frame and the one your content layer is authored against.

• Every other scan added to the version is aligned to that base by the MultiSet VPS, which computes a rigid transform (relativePose) between the two scans.

• At any time, one or more maps in the version are active. When you query the base map, the VPS localizes against every active map in the version and transforms the returned pose back into the base map's coordinate frame. You choose which maps are active with the Query Active toggle in the Developer Portal.

Why MultiSet VPS instead of ICP?

Traditional scan-merging techniques, such as ICP (Iterative Closest Point) and matchers built on low-level geometric or visual features, work well only when the two scans look almost identical. They fail in the cases that matter most in the real world:

• Furniture rearranged, walls repainted, fixtures swapped out

• Different hardware, so different coordinate systems: LHS, RHS Y Up, RHS Z Up, etc

• Different sensor or different point density (e.g. iPhone LiDAR vs. Matterport vs. Leica)

• Different lighting conditions or season

• Months between captures, with cumulative change to the space

MultiSet Map Versioning uses the same VPS pipeline that powers MultiSet localization. Because the VPS reasons about the scene at the level of recognizable structure rather than raw geometry, it stays robust under drastic change between captures. The output is a clean rigid transform between the new scan and the base map, even when ICP would have given up.

Content layer stays put

The biggest practical benefit: your content layer never has to move.

Anchors, navigation paths, instruction overlays, and any other authored content live in the base map's coordinate frame. When you scan the space again, possibly with a different device that uses a different local coordinate system, you add the new scan as a version and activate it. MultiSet's VPS computes the transform once; from then on every query against the base map is transparently translated to the active map.

The content you authored in your app (navigation paths, AR instructions, anchors) does not need to be re-authored when you re-scan the space, even if the new scan uses a completely different local coordinate system.

Create a Map Version in the Developer Portal

The quickest way to version a map is from the Developer Portal. No API calls required.

1. Open the map's Map Details. In the Maps list, click the map you want to use as the base. On its Map Details screen, scroll to the Map Version section and click + Create Map Version.

Map Details → Map Version section → Create Map Version.

2. Pick the target map. In the Create Map Version dialog, the map you opened is set as the Source Map (Base): its coordinate frame becomes the version's frame. Search for and select the newer scan of the same space as the Target Map, then click Create Version.

Choose the newer scan as the target map, then Create Version.

3. Wait for alignment. The target map is added to the version with a Pending status while the MultiSet VPS computes the transform between the two scans. The base map is Ready and Query Active from the start.

The new scan shows Pending while the VPS aligns it to the base map.

4. Activate the new scan. Once the target map turns Ready, toggle Query Active to include it in localization queries. Use View pose to inspect the computed relative pose, and + Add Map Version to add further scans over time. At least one map must remain Query Active.

Once Ready, toggle Query Active to include the scan in queries; View pose shows its relative pose.

Query more than one map at a time

A version is not limited to a single active scan. Any number of the maps in a version can be query active at once, and a localization query against the base map runs against all of them, returning the pose in the base map's coordinate frame either way.

This is what makes partial updates practical. If you re-scan only one section of a space, you do not have to replace the whole map: keep the original active for the areas that have not changed, activate the new scan for the section that has, and queries resolve against whichever one the user is actually standing in.

From the Developer Portal

Each map in the Map Version panel has its own Query Active toggle. Turn it on for every map you want localization to run against.

Both maps in this version are query active, so localization runs against both.

A map has to reach Ready before it can be activated, and at least one map must stay active at all times, so the last active map cannot be switched off.

Over the API

Use the activate endpoint and pass mapCodes with the full set of maps you want active:

{
    "mapCodes": ["MAP_BTTE1MOXYVT8", "MAP_QQYKIBHXZE01"]
}

The call replaces the active set, so any map in the version that is not listed is deactivated. To activate a single map, send mapCode instead. See Activate Maps in Version for the full request and response.

Detecting and applying a version at runtime

When a map has been versioned, the map details response carries two new fields, this is how a client app discovers that a version exists:

{
    "versionCode": "MVER_3VG3VINCWUIR",
    "activeMapCode": "MAP_KRXDJ14SY7ER"
}

Once your client sees these fields on a map response, the flow is:

1. Call Get Map Version with the versionCode to fetch the version's full state, including the relative pose (offset) of the active map against the base.

2. Download the mesh / map data for the active map (activeMapCode) instead of the base map. This is the geometry that VPS queries are actually running against.

3. Apply the relative pose as an offset when loading the active map's mesh into your scene. With this offset applied, the new mesh lines up exactly on top of your existing content layer (which was authored in the base map's coordinate frame).

The result: the new, fresher mesh is rendered in the right place, your anchors and navigation paths stay where you originally put them, and VPS query responses already arrive in the base map's frame, so no further client-side conversion is needed.

Versioning an individual Map

The simplest case: a single base map, scanned again later.

1. Create a Map Version with the original map as sourceMapCode (it becomes the base) and the newer scan as targetMapCode.

2. The MultiSet VPS computes the transform between the two scans. The new map's status moves through pending → computing → ready as the job progresses.

3. Activate the newer scan with the Activate Map in Version API. From this point on, queries against the original map's code are routed to the newer scan, and the response is transformed back, so your content layer is unaffected.

4. When you scan again next quarter, add it as another version. The transform is computed against the currently active map, not against the original base, which keeps quality high as the space drifts further from the original scan over time.

See the Map Version REST API page for the full request/response shapes.

Versioning a Map that is part of a MapSet

Map Versions and MapSets compose cleanly:

• A MapSet groups maps that cover different physical areas of a venue (e.g. several floors, or several rooms).

• A Map Version groups scans that cover the same physical area at different points in time, or from different hardware.

To re-scan one map inside a MapSet, create a Map Version on that individual map. The MapSet keeps pointing at the same mapCode, the version layer transparently swaps in the newer scan. The relative pose between maps in the MapSet does not need to be re-computed, only the transform between the old and new scan of the one updated map.

You don't version the MapSet itself. You version the individual maps that compose it. This keeps each capture session isolated: re-scanning Floor 2 doesn't affect Floor 1's alignment.

Mix hardware between versions

You don't have to use the same scanning hardware for every version of a map. Add versions captured with:

• MultiSet Mapping App (iPhone / iPad with LiDAR)

• Matterport (E57 / MatterPak)

• Insta360 and other 360° cameras

• Leica, NavVis, Faro, Xgrids scanners

The VPS computes the alignment regardless of which device produced either scan. This lets you start with a quick phone capture, then upgrade to a higher-fidelity professional scan later, without losing the content layer you already built.

See Third Party Scans for supported formats and upload flows.

Lifecycle

Status	Meaning
pending	The scan has been added to the version and is queued for alignment.
computing	VPS is actively computing the transform between this scan and the version's source map.
ready	Transform is computed; this map can be set as active (toggle Query Active).
failed	VPS could not align this scan to the source. failureReason will be populated.

A version always has exactly one base map (its coordinate frame is the version's frame) and one or more active maps (the scans VPS queries run against). When a version is first created only the base map is active; use the Query Active toggle in the Developer Portal to activate or deactivate additional maps for querying. At least one map must stay active.