Working with Surface Properties

Just happens, I was helping one of the interns that is working with us this summer, and she needed some demo code to work with TIN Surfaces. I prepared a small demo, to help her understand the concepts, and I thought it will be a good example also, to explain some of the concepts in the new design of the Surfaces .NET API that I started to talk about in my previous post.

In the demo, I created a small command “CDS_TinSurfacePropertiesDemo” that will prompt the user for a TIN Surface and display some properties. TIN Surfaces are one of the four type of surfaces supported by Civil 3D. Here is the implementation of the command.

C#

[CommandMethod("CDS_TinSurfacePropertiesDemo")]
public void CDS_TinSurfacePropertiesDemo()
{
    ObjectId surfaceId = promptForTinSurface();
    if (ObjectId.Null == surfaceId)
    {
        _write("\nNo TIN Surface object was selected.");
        return; // We don't have a surface; we can't continue.
    }
    using (Transaction tr = startTransaction())
    {
        TinSurface surface = surfaceId.GetObject(
            OpenMode.ForRead) as TinSurface;
        _write("\nInformation for TIN Surface: " + surface.Name);
        writeGeneralProperites(surface.GetGeneralProperties());
        writeTerrainProperties(surface.GetTerrainProperties());
        writeTinSurfaceProperties(surface.GetTinProperties());
    }
}

VB.NET

<CommandMethod("CDS_TinSurfacePropertiesDemo")> _
Public Sub CDS_TinSurfacePropertiesDemo()
  Dim surfaceId As ObjectId = promptForTinSurface()
  If ObjectId.Null = surfaceId Then
    _write(vbLf & "No TIN Surface object was selected.")
   ' We don't have a surface; we can't continue.
    Return
  End If
  Using tr As Transaction = startTransaction()
    Dim surface As TinSurface = TryCast(surfaceId.GetObject( _
      OpenMode.ForRead), TinSurface)
    _write(vbLf & "Information for TIN Surface: " + surface.Name)
    writeGeneralProperites(surface.GetGeneralProperties())
    writeTerrainProperties(surface.GetTerrainProperties())
    writeTinSurfaceProperties(surface.GetTinProperties())
  End Using
End Sub

The command opens the selected TIN Surface object and displays some of it properties. This is done in the ‘write***’ methods that we will implement, but notice how the properties are being access by methods exposed in the TIN Surface object.

General Properties

All Surface object in Civil 3D expose a ‘GetGeneralProperties() method that returns a structure with general properties of the surface. We can see in the implementation of ‘writeGeneralProperties()’ the properties that are exposed.

C#

private void writeGeneralProperites(GeneralSurfaceProperties p)
{
    _write("\nGeneral Properties:");
    _write("\n-------------------");
    _write("\nMin X: " + p.MinimumCoordinateX);
    _write("\nMin Y: " + p.MinimumCoordinateY);
    _write("\nMin Z: " + p.MinimumElevation);
    _write("\nMax X: " + p.MaximumCoordinateX);
    _write("\nMax Y: " + p.MaximumCoordinateY);
    _write("\nMax Z: " + p.MaximumElevation);
    _write("\nMean Elevation: " + p.MeanElevation);
    _write("\nNumber of Points: " + p.NumberOfPoints);
    _write("\n--");
}

VB.NET

Private Sub writeGeneralProperites(p As GeneralSurfaceProperties)
  _write(vbLf & "General Properties:")
  _write(vbLf & "-------------------")
  _write(vbLf & "Min X: " & Convert.ToString(p.MinimumCoordinateX))
  _write(vbLf & "Min Y: " & Convert.ToString(p.MinimumCoordinateY))
  _write(vbLf & "Min Z: " & Convert.ToString(p.MinimumElevation))
  _write(vbLf & "Max X: " & Convert.ToString(p.MaximumCoordinateX))
  _write(vbLf & "Max Y: " & Convert.ToString(p.MaximumCoordinateY))
  _write(vbLf & "Max Z: " & Convert.ToString(p.MaximumElevation))
  _write(vbLf & "Mean Elevation: " & Convert.ToString(p.MeanElevation))
  _write(vbLf & "Number of Points: " & Convert.ToString( _
    p.NumberOfPoints))
  _write(vbLf & "--")
End Sub

We can see that Minimum/Maximum values for X/Y/Elevation have been provided, as well as the mean elevation point in the Surface. The ‘GeneralSurfaceProperties’ structure also exposes the number of points in the Surface.

Terrain Surface Properties

TIN Surfaces implement the ‘ITerrainSurface’ interface. This interface exposes the ‘GetTerrainProperties()’ method, which returns a ‘TerrainSurfaceProperties’ structure containing Terrain specific properties. The implementation of ‘writeTerrainProperties()’ shows the contents of ‘TerrainSurfaceProperties’.

C#

private void writeTerrainProperties(TerrainSurfaceProperties p)
{
    _write("\nTerrain Surface Properties:");
    _write("\n---------------------------");
    _write("\nMin Grade/Slope: " + p.MinimumGradeOrSlope);
    _write("\nMax Grade/Slope: " + p.MaximumGradeOrSlope);
    _write("\nMean Grade/Slope: " + p.MeanGradeOrSlope);
    _write("\n2D Area: " + p.SurfaceArea2D);
    _write("\n3D Area: " + p.SurfaceArea3D);
    _write("\n--");
}

VB.NET

Private Sub writeTerrainProperties(p As TerrainSurfaceProperties)
  _write(vbLf & "Terrain Surface Properties:")
  _write(vbLf & "---------------------------")
  _write(vbLf & "Min Grade/Slope: " & Convert.ToString(p.MinimumGradeOrSlope))
  _write(vbLf & "Max Grade/Slope: " & Convert.ToString(p.MaximumGradeOrSlope))
  _write(vbLf & "Mean Grade/Slope: " & Convert.ToString(p.MeanGradeOrSlope))
  _write(vbLf & "2D Area: " & Convert.ToString(p.SurfaceArea2D))
  _write(vbLf & "3D Area: " & Convert.ToString(p.SurfaceArea3D))
  _write(vbLf & "--")
End Sub

Terrain Surface properties will tell you the minimum, maximum, and mean grade/slope. They also expose the surface area in 2D, and in 3D.

TIN Surface Properties

Of course, TIN Surfaces implement the ‘ITinSurface’ interface, which exposes a ‘GetTinProperties()’ that returns a ‘TinSurfaceProperties’ structure with properties about the TIN. The ‘writeTinSurfaceProperties()’ implementation shows the exposed properties in ‘TinSurfaceProperties’.

C#

private void writeTinSurfaceProperties(TinSurfaceProperties p)
{
    _write("\nTIN Surface Properties:");
    _write("\n-----------------------");
    _write("\nMin Triangle Area: " + p.MinimumTriangleArea);
    _write("\nMin Triangle Length: " + p.MinimumTriangleLength);
    _write("\nMax Triangle Area: " + p.MaximumTriangleArea);
    _write("\nMax Triangle Length: " + p.MaximumTriangleLength);
    _write("\nNumber of Triangles: " + p.NumberOfTriangles);
    _write("\n--");
}

VB.NET

Private Sub writeTinSurfaceProperties(p As TinSurfaceProperties)
  _write(vbLf & "TIN Surface Properties:")
  _write(vbLf & "-----------------------")
  _write(vbLf & "Min Triangle Area: " & Convert.ToString(p.MinimumTriangleArea))
  _write(vbLf & "Min Triangle Length: " & Convert.ToString(p.MinimumTriangleLength))
  _write(vbLf & "Max Triangle Area: " & Convert.ToString(p.MaximumTriangleArea))
  _write(vbLf & "Max Triangle Length: " & Convert.ToString(p.MaximumTriangleLength))
  _write(vbLf & "Number of Triangles: " & Convert.ToString(p.NumberOfTriangles))
  _write(vbLf & "--")
End Sub

TIN Surface properties give access to minimum and maximum triangle area and length. The structure also exposes the number of triangles in the surface.

Conclusion

We saw in the previous post there are four type of surface objects in Civil 3D. Some types share properties, and these properties are exposed by implementing four different interfaces: ‘ITerrainSurface’, ‘IVolumeSurface’, ‘ITinSurface’, and ‘IGridSurface’. These interfaces expose methods that allow to access specific properties.

You can download the complete source code and play with it as you please. Maybe, you want to tweak the code so it works for all four types of surfaces and send it to me. If you do, make sure you put the “BLOG:” prefix in the subject.