# Structure Excavation \[STG]

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.