# Structure Excavation \[CSB]

The Structure Excavation object calculates the volume of earth that needs to be removed to construct a foundation. It automatically generates excavation geometry from a selected footing and computes quantities based on the original ground surface.

## General

**Foundation:** Select the footing that defines the excavation boundary. The excavation extends from the footing bottom to the original ground surface. This is a required input.

**Excavation Type:** Determines the shape of excavation walls.

* **Vertical (0)**: Straight vertical walls from bottom to top
* **Sloped (1)**: Angled walls that widen toward the top for soil stability

**Slope Ratio (H/V):** The horizontal to vertical ratio for sloped excavation walls. Only shown when Excavation Type is set to Sloped. Common values include:

* 1:1 (45 degrees)
* 1.5:1 (gentle slope)
* 2:1 (very gentle slope)

A ratio of 1.5 means 1.5 feet horizontal for every 1 foot vertical. Must be a positive value.

**Boundary Offset Beyond Footing:** Additional clearance distance beyond the footing edge in all directions. This provides working space around the footing for construction activities. Default is 12 inches. Must be non-negative.

## Top Elevation

**Elevation Source:** Method to define the original ground surface.

* **Elevation (0)**: Manual input of a single elevation value for flat ground
* **From DTM (1)**: Use a Digital Terrain Model for variable ground surface

**Top Elevation:** Manual elevation of the original ground surface. Only shown when Elevation Source is set to Elevation. This represents the existing ground surface before excavation.

**Digital Terrain Model:** Select a DTM object representing the existing ground. Only shown when Elevation Source is set to From DTM. The DTM must cover the excavation area.

{% hint style="info" %}
When using DTM mode, the excavation volume is computed as a precise prism volume between the DTM surface and the excavation bottom. This accounts for natural ground variations across the excavation area.
{% endhint %}

## Display

**Show Excavation:** Toggle to show or hide the excavation volume in the 3D view.

**Opacity:** Transparency of the 3D visualization. Range from 0 (fully transparent) to 1 (fully opaque). Default is 0.7.

## Quantities

All quantity fields are read-only computed values.

**Excavation Volume:** Total volume of earth to be removed. Calculated using:

* DTM mode: Computed prism volume from terrainGrid function
* Elevation mode (Vertical): Average Depth × Bottom Area
* Elevation mode (Sloped): Frustum formula = (h/3) × (A\_bottom + A\_top + √(A\_bottom × A\_top))

**Top Surface Area:** Area of the original ground surface within the excavation boundary.

**Bottom Surface Area:** Area at the bottom of the excavation (at footing bottom elevation).

**Min Excavation Depth:** Minimum depth from ground to footing bottom. Particularly useful with DTM input to show the shallowest point.

**Max Excavation Depth:** Maximum depth from ground to footing bottom. Shows the deepest point of excavation.

**Average Excavation Depth:** Average depth of excavation across the area.

## Supported Foundation Types

Structure Excavation works with:

* **Custom Footing** (OBPFoundation): Footing with point list or section-based geometry
* **Rectangular Footing** (OBPFoundationRectangular): Standard rectangular footing

The excavation boundary is automatically derived from the footing polygon, offset outward by the specified boundary offset distance.


---

# 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.openbrim.org/templates/cable-stayed-bridge-workflow/substructure-csb/earthwork-csb/structure-excavation-csb.md?ask=<question>
```

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.