Terrain Analysis
Introduction
The Terrain Analysis cluster provides a series of components that help you understand, quantify, and visualize terrain characteristics. These tools cover earthwork calculations, slope analysis, watershed delineation, and cross-section profiling.
All analysis components work with mesh terrain surfaces and produce both geometric outputs (meshes, curves, points) and numerical data (volumes, angles, values) for downstream use in design iteration and reporting.
Color Maps
Several analysis components support color-coded visualization using selectable color maps. The following color maps are available:
Color maps can be selected via the component’s right-click context menu. The selection is saved with the Grasshopper document.
Component Usage
Please refer to the following sections for each component from this cluster.
Cut & Fill Analysis
This component computes the volumetric difference between an existing terrain and a proposed terrain within specified boundary areas. It calculates cut volume (material removed), fill volume (material added), and net balance.
| Param. | Abbr. | I/O | Required | Description |
|---|---|---|---|---|
Boundary | B | Yes | One or more closed boundary curves defining the analysis area(s). | |
Existing | E | Yes | Existing terrain mesh covering the analysis area. | |
Proposed | P | Yes | Proposed terrain mesh covering the analysis area. | |
GridSize | G | No | Size of the sampling grid cell (world units). Smaller values give more accurate results but increase computation time. Default: 10. | |
AnalysisMesh | M | Color-coded mesh showing cut (red) and fill (green) areas with height-based 3D visualization. | ||
CutMeshes | CM | Mesh faces in cut areas (where material is removed). | ||
FillMeshes | FM | Mesh faces in fill areas (where material is added). | ||
CutVolume | C | Volume of material to be excavated (per boundary). | ||
FillVolume | F | Volume of material to be added (per boundary). | ||
NetVolume | N | Net volume difference. Positive = net fill, negative = net cut (per boundary). |
Right-click the component to select from available color maps. The default is RedWhiteGreen, which shows cut as red, neutral as white, and fill as green.
The GridSize parameter controls the sampling density. A smaller grid size produces more accurate volume calculations but takes longer to compute. For early design iterations, use larger values (20-50); for final calculations, use smaller values (5-10).
Tip: Aim for a net volume close to zero to minimize material hauling costs. Use the separate cut and fill volumes to plan phasing and stockpile locations.
Slope Analysis
This component analyzes terrain slope and visualizes it with a color-coded mesh. It samples the terrain on a grid, calculates the slope angle at each point, and generates both visual and numerical outputs.
| Param. | Abbr. | I/O | Required | Description |
|---|---|---|---|---|
Mesh | M | Yes | Terrain mesh to analyze. | |
GridSize | G | No | Grid size for sampling. Smaller values give more detail but slower computation. Default: 10.0. | |
SlopeBounds | B | No | Slope range for color mapping (degrees). Slopes outside this range are clamped to min/max colors. Default: 0 to 90. | |
AnalysisMesh | M | Color-coded mesh showing slope values mapped to the specified bounds. | ||
SamplePoints | P | Grid points where slope was sampled. | ||
SlopeValues | S | Slope angle at each sample point (degrees). | ||
SlopeVectors | V | Direction vectors showing downhill direction at each point, scaled by grid size. | ||
InBounds | IB | Boolean list indicating whether each slope is within the specified bounds. |
Right-click the component to select from available color maps. The default is Viridis, a perceptually uniform colormap that is colorblind-friendly. For a full list of available color maps, see the Color Maps section.
Use SlopeBounds to focus the visualization on a specific slope range. For example, to highlight areas exceeding ADA requirements, set bounds to 0 to 8.33 (1:12 slope). Areas outside the bounds will show as the minimum or maximum color.
Tip: The InBounds output is useful for filtering points or selecting areas that meet specific slope criteria, such as accessible routes or buildable areas.
Watershed Analysis
This component automatically segments terrain into watershed (drainage basin) regions. Each basin represents an area where water flows to a common outlet point (sink).
| Param. | Abbr. | I/O | Required | Description |
|---|---|---|---|---|
Mesh | M | Yes | Terrain mesh to analyze. | |
Resolution | R | No | Grid resolution for analysis. If not provided, automatically derived from mesh vertex density. | |
MinArea | A | No | Minimum watershed area. Smaller watersheds are merged into neighbors. Set to 0 to keep all. Default: 0. | |
EdgeTolerance | T | No | Distance from mesh boundary (in grid cells) to detect edge watersheds. Edge watersheds are merged with interior neighbors. Default: 1.5. | |
WatershedMeshes | WM | Segmented mesh pieces for each watershed basin, with unique colors. | ||
Boundaries | B | 3D boundary curves (ridgelines) between watersheds. | ||
Sinks | S | Outlet points (local minima) where water accumulates in each basin. |
If no resolution is provided, the component automatically derives an appropriate grid size from the mesh’s average edge length. A remark message will show the derived value.
Watersheds with sinks near the mesh boundary represent incomplete catchments where water flows off the edge. The EdgeTolerance parameter controls how these are handled—they are automatically merged with adjacent interior watersheds for cleaner results.
Use MinArea to consolidate small watersheds into larger neighbors. This is useful for removing noise from complex terrain or focusing on major drainage patterns.
Tip: The watershed boundaries represent ridgelines where water divides. These are useful for planning grading, identifying natural drainage corridors, and understanding site hydrology.
Cross-Section Analysis
This component generates terrain cross-section profiles along a guide curve. It samples the terrain at regular intervals perpendicular to the curve, producing profile curves and reference planes.
| Param. | Abbr. | I/O | Required | Description |
|---|---|---|---|---|
Mesh | M | Yes | Terrain mesh to analyze. | |
Curve | C | Yes | Guide curve along which to compute cross-sections. | |
Count | N | No | Number of cross-section sampling locations (evenly distributed along curve). Default: 10. | |
Width | W | No | Width of each cross-section profile (perpendicular to curve). Default: 10.0. | |
Sections | S | Cross-section profile curves showing the terrain cut. | ||
Planes | P | Reference planes for each cross-section, useful for reorienting or documenting sections. |
Each cross-section is generated by casting rays downward onto the terrain along a line perpendicular to the guide curve. The resulting points are connected into a polyline profile curve.
The output planes are positioned at the midpoint of each profile curve, with the X-axis aligned perpendicular to the guide curve and the Z-axis pointing up. These planes can be used to reorient sections for documentation or to place annotations.
Tip: Use cross-sections along roads, paths, or property lines to document existing conditions and proposed grading. The profile curves can be used directly in 2D drawings or further analyzed for earthwork calculations.
Example: Combined Analysis Workflow
This example demonstrates a typical terrain analysis workflow that combines editing, cut & fill analysis, and cross-section extraction.
The workflow consists of three main steps:
-
Terrain Editing: Start by modifying the existing terrain using the terrain editing tools. In this example, we use area-based editing to create a flat building pad on a sloped site.
-
Cut & Fill Analysis: Connect the original terrain mesh to the
Existinginput and the edited terrain to theProposedinput of the Cut & Fill component. The color-coded output mesh immediately shows where material needs to be removed (red) or added (green), along with volume calculations. -
Cross-Section Extraction: Draw a guide curve through the site and use the Cross-Section component to generate profile curves. These sections clearly show the relationship between existing and proposed grades, making it easy to verify the design and prepare construction documents.
Tips
- Iterative analysis: Run cut/fill analysis after each major edit to track progress toward a balanced site.
- Combine tools: Use rain simulation to verify that slope analysis and watershed boundaries align with intended drainage.
- Documentation: Cross-sections are essential for construction documents—generate them along key alignments.
- Performance: For large meshes, start with coarser grid sizes to preview results, then refine for final analysis.