# Build the mesh

A map built from standard-camera or 360° video is **Ready** once it can localize and its point cloud is viewable in Space Studio — but it does not have a mesh yet. AR occlusion and navigation need one, so choose how to build it on the map card.

Mobile 3D scans and LiDAR scans skip this step: their surface geometry comes from the scan itself, so their map cards have no **Mesh** section. For Polycam and KIRI Engine that geometry exists only if the optional Mesh ZIP was uploaded alongside the Raw Data.

## Why a Ready map has no mesh

Localization uses the sparse point cloud and does not need a mesh. A mesh is the continuous surface laid over those points; building it costs a large amount of extra compute, and not every map needs it — localization and content authoring work without one.

Separating this step makes the map usable first and leaves you free to decide whether and how to add surface geometry later. While you decide, the map keeps localizing, Space Studio still opens, and Content stays editable.

## How the two methods differ

The Ready map card has a **Mesh** section that reads "The map already localizes and its point cloud is viewable. AR occlusion and navigation need a mesh — pick how to build it", followed by the two entry points.

| | Build on server | Download workpack |
| --- | --- | --- |
| What you do | Select one button | Download, run it on your own computer, upload the result |
| What you need | Nothing | Desktop Metashape Professional |
| Typical duration | Several hours | Depends on frame count and frame size: about 6 minutes measured for 263 standard-camera frames; 360° frames are much larger and take considerably longer |
| The map meanwhile | Stays usable and localizes | Stays usable and localizes |
| Suits | No hurry, or no Metashape at hand | You want the result sooner, or you want control over the build |

A mesh from either method serves exactly the same purposes. Publication, tiling, and navigation derivation afterwards are identical.

## Build on server

1. In the **Mesh** section, select **Build on server**.
2. The confirmation explains that this reuses the existing sparse reconstruction and runs only the mesh stage; SfM does not run again.
3. The card switches to **Building mesh**. Select **Cancel** if you need to stop it.

The map stays online throughout and localization is unaffected. The job queues for mapping capacity, so the start time depends on current load.

## Download a workpack and build in desktop Metashape

The workpack contains this map's video frames, the camera poses we solved, a Metashape script, and an offline README. The script keeps **the poses frozen throughout** and never lets Metashape re-align the cameras — so the resulting mesh already shares the map's coordinate frame and needs no alignment step when you send it back.

### Before you start

- **Metashape Professional** with an activated licence or the official 30-day full trial. Standard edition and Demo mode will not work: Demo can compute but cannot save a project or export a model, so hours of work would be wasted.
- Disk space: the extracted frames, depth maps, and project typically need several times the size of the workpack itself.
- Enable your GPU under **Preferences ▸ GPU** in Metashape — it is several times faster.

### Steps

1. In the **Mesh** section, select **Download workpack**. The download starts once packing finishes.
2. Extract the whole archive into one directory. Do not run the script from inside the archive, and do not extract only part of the archive.
3. Open Metashape and select **File ▸ New** to create an empty project.
4. Select **Tools ▸ Run Script…**, pick `build_refined_mesh.py` from the extracted directory, and leave the arguments box empty.
5. The script then runs on its own and logs every step to Metashape's Console pane. Leave Metashape open until it reports that the artifacts are in `out/` — that directory then holds one `.glb` model and one `build_report.json` run report.
6. Return to the map card, select **Upload mesh**, and pick that `.glb`. Publication starts automatically once the upload completes.

`build_report.json` records the self-check numbers from the run. Sending it is optional; if something goes wrong, it helps us find the cause faster.

## What happens after you upload

The uploaded file is stored first, and publication starts right after. The card shows the file's size and notes that it counts toward this map's storage. Publication checks the file's format, whether it lines up with the map, and whether it was built from this map's current version. If publication does not start on its own — for example because the map is busy with another job — the card keeps the file and offers **Publish it**; select it to try again without uploading the file a second time.

- **Passes**: publication completes and the mesh is immediately available.
- **Does not pass**: the card explains that it cannot be published. Download the workpack again, re-export from Metashape, and upload a new file. The rejected one still uses storage, and you can select **Delete it** on the card.
- **The map was rebuilt in the meantime**: the frozen poses no longer match, so that mesh cannot be published. Download a fresh workpack and repeat.

## After one method fails

A failed server build will not be retried: **Build on server** becomes unavailable on this map, and the card directs you to desktop Metashape instead. This is deliberate: a server build occupies hours of compute, and repeating a method that has already proven unworkable only consumes capacity.

When a desktop upload is rejected, the verdict applies to **the single file you uploaded**, not to the method. Correct it in Metashape, re-export, and upload again.

## Once the mesh is ready

- In the Space Studio Map Panel, enable **Mesh** to see the surface and **Wire** to overlay triangles for continuity inspection.
- AR clients gain occlusion: virtual objects are correctly hidden behind real walls and furniture.
- The system tries to derive a walkable grid for AR navigation from the mesh. When the floor is buried under reflections, walking people, or very dense detail, that derivation can come up empty — the mesh and AR occlusion still work, and the card marks the map **Navigation unavailable**. This depends on the scene itself; there is no parameter to tune.

## Next

- Continue to [Explore a map](/tutorials/maps/explore) to inspect the mesh alongside the point cloud.
- Return to [Manage maps](/tutorials/maps/manage) for the card's other states and actions.