> ## Documentation Index
> Fetch the complete documentation index at: https://avala.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Ground Reconstruction
> Build and edit a ground surface for LiDAR sequences, then snap annotations to it
Ground Reconstruction builds a **ground surface** for a LiDAR sequence: a smooth, curved skin that follows the real road, floor, or terrain under your data.
Once you have one, annotation gets easier. Cuboids and polyline points can snap down onto the ground, so you stop adjusting height by hand.
It works in two stages: the computer makes a first attempt from the point cloud, then you fix the parts it got wrong. Every edit can be undone, and nothing is stored until you submit.
## When to Use
Use Ground Reconstruction when:
* You are annotating a LiDAR point cloud sequence
* You want cuboids or polyline points to sit on the ground automatically
* A downstream tool needs height-above-ground (e.g. separating objects from the road)
## Generate the surface
1. Open a LiDAR sequence and pick the **Ground reconstruction** tool.
2. Choose an **Algorithm**:
* **Cloth simulation (continuous)** — the default. Imagine dropping a cloth over the scene from below: it drapes over the real ground and ignores cars, people, and trees. Best for roads and outdoor scenes.
* **Grid (per-cell, fast)** — quicker, and good when your points are dense and the ground is fairly flat.
3. Press **Generate ground**.
You will see *Aggregating frames and reconstructing…*, then *Surface ready · N ground cells*.
If the result looks wrong, change a setting and press **Generate ground** again. Re-running is safe — nothing is committed yet. Start with **Cell size**: smaller means more detail but more memory. The **Ignore points…** sliders throw away points too close to the sensor, or too far away in a given direction, which helps when distant noise drags the surface around.
Only **Cloth simulation** produces the point-support data that **Trim unsupported ground** needs. If that button is greyed out, you generated with **Grid**, or you loaded a surface saved before support data existed.
## Clean it up
Five tools, all undoable.
**Suppress spikes** — one click. Pulls cells that stick up or down oddly back onto the surface. A slider appears: **Apply** to keep, **Cancel** to discard.
**Trim unsupported ground** — one click. Removes the "skirt": surface the computer guessed at where there were no actual LiDAR points. The fastest way to delete ground floating out into empty space. Also has a slider, with **Apply** / **Cancel**.
**Erase** (`X`) — draw a loop around ground you do not want; it disappears on release. The tool stays open, so keep erasing. To move the camera, switch to **Navigate** (or press `Space`), orbit, then switch back to **Lasso**.
**Fill** (`G`) — the opposite. Draw a loop around a hole and it fills in using the real ground nearby. Two settings: **Direction** (how many directions each hole searches) and **distance** (how far it looks). Widen them if holes refuse to fill.
**Brush** (`B`) — sculpt by hand. Drag over the surface to push it around. A shaded disc shows exactly which area the brush will affect.
| Mode | Shortcut | What it does |
| ------ | -------- | ---------------------------- |
| Raise | `7` | Pushes the ground up |
| Lower | `8` | Pushes the ground down |
| Smooth | `9` | Irons out bumps and waviness |
Press and hold without moving and the brush keeps applying to the same spot — useful for one stubborn bump. **Strength** sets how far each stroke moves the ground; the radius sets how wide the brush is. A flat/feathered option controls the edge: feathered fades out (softer, natural), flat moves the whole circle equally (good for deliberate steps). Each stroke is one undo step.
## Snap annotations to the ground
Turn on the **ground snap** toggle and cuboids and 3D/4D polyline points sit down onto the surface as you place and move them. Turn it off any time — it does not change anything already placed.
## Save
Saving takes **two steps**, and it is easy to stop after the first.
1. Press **Done** to finish with the ground tool. This closes the tool and keeps your work, but **nothing has been stored yet**.
2. Press **Save and submit**. This is what stores the ground.
What you see on screen is exactly what gets stored.
If you built the ground while only part of the sequence was loaded, you will see **"Save ground from an incomplete sequence?"**. The saved surface covers the **whole** sequence, so areas you never reconstructed may be missing or wrong, and snapping and height-above-ground inherit that. Either **Cancel**, load the rest of the frames and re-generate — or press **Save anyway** if the missing parts do not matter.
If nothing actually changed — you only opened the tool, or you undid every edit back to where you started — **Done** stores nothing. That is deliberate.
## Shortcuts
| Shortcut | Action |
| -------- | ------------------------------------------ |
| `Space` | Flip between moving the camera and editing |
| `B` | Brush |
| `G` | Fill |
| `X` | Erase |
| `7` | Brush → Raise |
| `8` | Brush → Lower |
| `9` | Brush → Smooth |
`B`, `G` and `X` work from anywhere, so you can jump straight from erasing to filling without returning to the toolbar. `7`/`8`/`9` only act while the Brush is open and you are not mid-stroke.
Fill is `G` rather than `F` because `F` is the browser's full-screen key.
Your usual keys keep working: `W` `A` `S` `D` `Q` `E` fly the camera, `1`/`2`/`3` change point-cloud colouring, and anything with `Ctrl` / `⌘` / `Shift` / `Alt` (like undo) is never intercepted.
While a **Suppress spikes** or **Trim unsupported ground** slider panel is open, all of the above are switched off — finish with **Apply** or **Cancel** first.
## Common Mistakes
| What you see | What is happening |
| ------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Trim unsupported ground** is greyed out | The surface has no point-support data. Re-generate with **Cloth simulation**. |
| Brush / Erase / Fill are greyed out | There is no surface yet. Press **Generate ground** first. |
| *"No ground surface to submit — press Generate ground first"* | You submitted without generating anything. |
| *"The reconstructed ground has no observed cells…"* | The settings were too strict for your data. Use a larger **cell size**, a lower **min points / cell**, or wider distance limits, then generate again. |
| You pressed **Done** and nothing was saved | **Done** only closes the tool. Press **Save and submit** to store the ground. |
| Ground floats out into empty space | Use **Trim unsupported ground**, or **Erase** the region. |
| The surface climbs over cars or bushes | Re-generate with a larger **cell size**, or use the **Ignore points…** sliders to drop distant noise. |
| Holes will not fill | Increase the fill **Direction** count and search **distance**. |
| The camera will not move while editing | Press `Space`, or click **Navigate**. |
## Related Tools
* [3D Cuboid](/docs/annotation/guides/tools/cuboid-3d) -- Snaps to the ground surface you build here
* [3D Polyline](/docs/annotation/guides/tools/polyline-3d) -- Waypoints also snap to the ground
* [Segmentation](/docs/annotation/guides/tools/segmentation) -- For pixel-level semantic labels