Civilized Development

21WOJP–Week 21: Creating Stacked Profile Views

In Jay Peak, we have provided the ability to create stacked profile views through the API. We did this by providing new overloads to the already existing methods that created profile views. The ‘ProfileView’ class exposes several ‘Create()’ and, as we saw last week, ‘CreateMultiple()’ methods to create single and multiple profile views. We also provided overloads for these methods that take a ‘StackedProfileViewsCreationOptions’ object, which defines how stacked profiles can be created.

The following example uses some of the code from last week to create multiple stacked profiles:

C#

private void createStackedProfileViews()
{
  ProfileView.CreateMultiple(_alignmentId, _insertionPoint, 
      _stackedOptions, _creationOptions);
}

private StackedProfileViewsCreationOptions _stackedOptions
{
  get
  {
    StackedProfileViewsCreationOptions options =
      new StackedProfileViewsCreationOptions(_defaultPVId,
        _defaultPVId, _defaultPVId);
    return options;
  }
}

private ObjectId _defaultPVId
{
  get
  {
    return _civildoc.Styles.ProfileViewStyles[0];
  }
}

VB.NET

Private Sub createStackedProfileViews()
  ProfileView.CreateMultiple(_alignmentId, _insertionPoint,
    _stackedOptions, _creationOptions)
End Sub

Private ReadOnly Property _stackedOptions() _
    As StackedProfileViewsCreationOptions
  Get
    Dim options As New StackedProfileViewsCreationOptions(
      _defaultPVId, _defaultPVId, _defaultPVId)
    Return options
  End Get
End Property

Private ReadOnly Property _defaultPVId() As ObjectId
  Get
    Return _civildoc.Styles.ProfileViewStyles(0)
  End Get
End Property

And with this installment, we complete the Jay Peak series. It has been many weeks of Jay Peak goodness, which I hope you have enjoyed and that allows you to derive great benefit from our latest release. The series has covered the most important features and enhancements we added, but there are some other gems that we will be looking at in the future, so stay tuned for more Civil 3D API talk.

21WOJP–Week 20: Create Multiple Profile Views

Jay Peak provides some enhancements to the ‘ProfileView’ object. One of them is the ability to create multiple profile views at once. The code is very simple, since it is just one straight call to a static method of ‘ProfileView’. Yet, it is a very powerful call since it takes a ‘MultipleProfileViewsCreationOptions’ object that allows to customize the behavior of the profile views being created. The following code shows how to create multiple profile views.

C#

private void createProfileViews()
{
  ProfileView.CreateMultiple(_alignmentId, _insertionPoint,
    _creationOptions);
}

private MultipleProfileViewsCreationOptions _creationOptions
{
  get
  {
    MultipleProfileViewsCreationOptions options =
      new MultipleProfileViewsCreationOptions();
    options.DrawOrder = ProfileViewPlotType.ByRows;
    options.GapBetweenViewsInColumn = 1000;
    options.GapBetweenViewsInRow = 1000;
    options.MaxViewInRowOrColumn = 3;
    options.StartCorner = 
      ProfileViewStartCornerType.UpperLeft;
    return options;
  }
}

VB.NET

Private Sub createProfileViews()
  ProfileView.CreateMultiple(_alignmentId, _insertionPoint,
    _creationOptions)
End Sub



Private ReadOnly Property _creationOptions() _
    As MultipleProfileViewsCreationOptions
  Get
    Dim options As New MultipleProfileViewsCreationOptions()
    options.DrawOrder = ProfileViewPlotType.ByRows
    options.GapBetweenViewsInColumn = 1000
    options.GapBetweenViewsInRow = 1000
    options.MaxViewInRowOrColumn = 3
    options.StartCorner = ProfileViewStartCornerType.UpperLeft
    Return options
  End Get
End Property

We use an alignment id, an insertion point, and the ‘MultipleProfileViewsCreationOptions’ object to create the multiple views. The ‘MultipleProvileViewsCreationOption’ object allows you to customize the draw order of the profile views, and things like the gap between rows and columns, maximum views in each row or column (depending on the draw order option), and the start corner to which the insertion point refers. The ‘CreateMultiple’ method provides other overloads that allow you to customize further how the views are created.

You can download the entire implementation of the command from the Civilized Development repository at BitBucket.

21WOJP–Week 19: Sampling Points

The most difficult thing for us to decided is the level of functionality we provide in the .NET API. We want to provide enough functionality and a flexible design that will allow our users to solve any problems, but we cannot provide solutions to every possible scenario, so we have to strike a balance between most-have vs. nice-to-have functionality.

During the design of the 2012 release, we had long discussions about many features. One of them was the ability to sample elevations on a surface. The COM implementation was crippled in many ways, and we wanted to avoid a similar design in .NET. At the end, it was obvious that we couldn’t provide every single scenario our users will want, but we needed to provide enough functionality to allow them to solve the problem themselves. And that is what we did. The 2012 API contains enough functionality to sample elevations from a Surface yourself. But apparently from the amount of responses I got, this was not enough.

When we planned the 2013 release, we revisit our discussions on how to provide the functionality our users wanted. Back in the COM days, we had many requests to provide functionality, not only to sample elevations between two points, but to also allow other type of entities like arcs and polylines. This is understandable because if you wanted, among other things, to create your own profile, you will need that functionality, so it seems reasonable that the API allows you to do it.

Of course, you cannot make everyone happy, so some of the complaints now are that sampling elevations between two points is more complicated in .NET than it used to be in COM. I agree, but let me explain why.

Again, this is a balancing exercise between complexity and flexibility. Initially, it may seem the .NET implementation is more complex, but this is just the case when you want to sample elevations between two points. If you were to try sampling elevations along a polyline in COM, you will immediately realize that there are other levels of complexity that you need to solve. These problems are already solved inside of Civil 3D behind the scenes, and it would not make sense that you will have to solve them again yourself.

The .NET API provides functionality to sample elevations along any type of Curve object, this includes Lines, Arcs, and Polylines, but it will also work with any other type of object derived from Curve. This solution provides all the flexibility you will need in any kind of situation and will allow you to solve any kind of problem requiring elevation samples.

Still, some of you will like to be able to sample elevations between two points. In this case, I recommend you review the implementation Partha Sarkar provided in the Infrastructure Modeling Blog. He demonstrates how adapt the current design to make it work the way the COM API used to, by creating a temporary polyline and use it to sample the elevations. This is a good technique if all you want is the good old COM functionality. If you need more flexibility, here is a command that will sample elevations from any kind of Curve derived object. Since the result of sampling elevations is a collection of Point3d objects, I use sampling points as the term instead of sampling elevations.

C#

using System;

using Autodesk.AutoCAD.DatabaseServices;
using Autodesk.AutoCAD.EditorInput;
using Autodesk.AutoCAD.Geometry;
using Autodesk.AutoCAD.Runtime;
using Autodesk.Civil.DatabaseServices;

using CivilSurface = Autodesk.Civil.DatabaseServices.Surface;

[assembly: CommandClass(
    typeof(Autodesk.CivilizedDevelopment.SamplingPointsCommands))]

namespace Autodesk.CivilizedDevelopment
{
    public class SamplingPointsCommands : SimpleDrawingCommand
    {
        [CommandMethod("CDS_SamplePointsOnSurface")]
        public void CDS_SamplePointsOnSurface()
        {
            using (Transaction tr = startTransaction())
            {
                ITerrainSurface surface = getSurface() as ITerrainSurface;
                if (surface == null) return;
                ObjectId curveId = getCurveId();

                displayPoints(surface.SampleElevations(curveId));
            }
        }

        private CivilSurface getSurface()
        {
            ObjectId surfaceId = promptForSurface();
            if (surfaceId.IsNull)
            {
                return null;
            }
            CivilSurface surface = surfaceId.GetObject(OpenMode.ForRead)
                as CivilSurface;
            return surface;
        }

        private ObjectId promptForSurface()
        {
            PromptEntityOptions options = new PromptEntityOptions(
                "\nSelect a TIN Surface: ");
            options.SetRejectMessage(
                "\nThe selected object is not a TIN Surface.");
            options.AddAllowedClass(typeof(CivilSurface), false);

            PromptEntityResult result = _editor.GetEntity(options);
            if (result.Status == PromptStatus.OK)
            {
                // Everything is cool; we return the selected
                // surface ObjectId.
                return result.ObjectId;
            }
            return ObjectId.Null;   // Indicating error.
        }

        private ObjectId getCurveId()
        {
            PromptEntityOptions options = new PromptEntityOptions(
                "\nSelect entity: ");
            options.SetRejectMessage(
                "\nThe selected entity is not of the valid type.");
            PromptEntityResult result = _editor.GetEntity(options);
            if (result.Status == PromptStatus.OK)
            {
                return result.ObjectId;
            }
            return ObjectId.Null;
        }

        private void displayPoints(Point3dCollection points)
        {
            foreach (Point3d point in points)
            {
                _editor.WriteMessage("\n" + point.ToString());
            }
        }
    }
}

VB.NET

Imports System

Imports Autodesk.AutoCAD.DatabaseServices
Imports Autodesk.AutoCAD.EditorInput
Imports Autodesk.AutoCAD.Geometry
Imports Autodesk.AutoCAD.Runtime
Imports Autodesk.Civil.DatabaseServices

Imports CivilSurface = Autodesk.Civil.DatabaseServices.Surface

<Assembly: CommandClass(
GetType(Autodesk.CivilizedDevelopment.SamplingPointsCommands))> 

Namespace Autodesk.CivilizedDevelopment
  Public Class SamplingPointsCommands
    Inherits SimpleDrawingCommand
    <CommandMethod("CDS_SamplePointsOnSurface")> _
    Public Sub CDS_SamplePointsOnSurface()
      Using tr As Transaction = startTransaction()
        Dim surface As ITerrainSurface = TryCast(getSurface(), 
          ITerrainSurface)
        If surface Is Nothing Then
          Return
        End If
        Dim curveId As ObjectId = getCurveId()

        displayPoints(surface.SampleElevations(curveId))
      End Using
    End Sub



    Private Function getSurface() As CivilSurface
      Dim surfaceId As ObjectId = promptForSurface()
      If surfaceId.IsNull Then
        Return Nothing
      End If
      Dim surface As CivilSurface =
        TryCast(surfaceId.GetObject(OpenMode.ForRead), CivilSurface)
      Return surface
    End Function



    Private Function promptForSurface() As ObjectId
      Dim options As New PromptEntityOptions(
        vbLf & "Select a TIN Surface: ")
      options.SetRejectMessage(
        vbLf & "The selected object is not a TIN Surface.")
      options.AddAllowedClass(GetType(CivilSurface), False)

      Dim result As PromptEntityResult = _editor.GetEntity(options)
      If result.Status = PromptStatus.OK Then
        ' Everything is cool; we return the selected
        ' surface ObjectId.
        Return result.ObjectId
      End If
      Return ObjectId.Null
      ' Indicating error.
    End Function



    Private Function getCurveId() As ObjectId
      Dim options As New PromptEntityOptions(vbLf & "Select entity: ")
      options.SetRejectMessage(
        vbLf & "The selected entity is not of the valid type.")
      Dim result As PromptEntityResult = _editor.GetEntity(options)
      If result.Status = PromptStatus.OK Then
        Return result.ObjectId
      End If
      Return ObjectId.Null
    End Function



    Private Sub displayPoints(points As Point3dCollection)
      For Each point As Point3d In points
        _editor.WriteMessage(vbLf + point.ToString())
      Next
    End Sub


  End Class
End Namespace

When we design the .NET API, we have to balance the functionality that we include to keep it flexible and to remove complexity. Often times, we will find functionality that it is not included but it is widely used and desired. In those cases, we will revisit our decisions and try to provide the best solution possible. This is why your feedback is very important, and your complaints necessary. I am sure we have missed things in the new 2013 API, so if you let us know, we are listening.

21WOJP – Week 18: Extracting Contours at Elevation

If you want to have all the power on how contours are created, you can always use the ‘ExtractContourAt()’ method. This method allows you to specified an elevation value at which the contours should be extracted, which in turn, gives you all the flexibility to extract contours using any kind of logic you will like. Of course, you want to insure the specified elevation is within the Surface’s elevation range.

The following command shows how the method is invoked to extract contours at a specified elevation, and how you can check the specified elevation is in range.

C#

[CommandMethod("CDS_ExtractSurfaceContoursAtElevation")]
public void CDS_ExtractSurfaceContoursAtElevation()
{
  using (Transaction tr = startTransaction())
  {
    ITerrainSurface surface = getSurface() as ITerrainSurface;
    if (surface == null) return;

    double elevation = getDouble("elevation");
    if (Double.IsNaN(elevation)) return;

    if (elevationInSurfaceRange(elevation, 
      surface as CivilSurface))
    {
      ObjectIdCollection contours = 
        surface.ExtractContoursAt(elevation);
      customizeContours(contours, _singleContourColor);
    }

    tr.Commit();
  }
}

private bool elevationInSurfaceRange(double elevation, 
  CivilSurface surface)
{
  GeneralSurfaceProperties properties = 
    surface.GetGeneralProperties();
  if (elevation < properties.MinimumElevation || 
    elevation > properties.MaximumElevation)
  {
    _editor.WriteMessage(
      "\nSpecified elevation not in surface range.");
    return false;
  }
  return true;

}

VB.NET

<CommandMethod("CDS_ExtractSurfaceContoursAtElevation")> _
Public Sub CDS_ExtractSurfaceContoursAtElevation()
  Using tr As Transaction = startTransaction()
    Dim surface As ITerrainSurface = TryCast(getSurface(), 
      ITerrainSurface)
    If surface Is Nothing Then
      Return
    End If

    Dim elevation As Double = getDouble("elevation")
    If [Double].IsNaN(elevation) Then
      Return
    End If

    If elevationInSurfaceRange(elevation,
        TryCast(surface, CivilSurface)) Then
      Dim contours As ObjectIdCollection =
        surface.ExtractContoursAt(elevation)
      customizeContours(contours, _singleContourColor)
    End If

    tr.Commit()
  End Using
End Sub

Private Function elevationInSurfaceRange(elevation As Double,
    surface As CivilSurface) As Boolean
  Dim properties As GeneralSurfaceProperties =
    surface.GetGeneralProperties()
  If elevation < properties.MinimumElevation Or
      elevation > properties.MaximumElevation Then
    _editor.WriteMessage(
      vbLf & "Specified elevation not in surface range.")
    Return False
  End If
  Return True

End Function

As always, you can download the full source code from the Civilized Development repository.

21WOJP–Week 17: Extracting Contour Ranges

Most of the time when working with contours, we want to work with a range starting at some elevation, ending at some other elevation, and using a specific interval. Fortunately, the API provides this functionality through overloaded ‘ExtractContours()’ methods.

The first overload take an elevation interval. The range is created starting at the surface’s minimum elevation and ending at its maximum elevation. These two values are determined by the ‘GeneralSurfaceProperties’ of the surface object. As we can see in the following example, it is very simple to create contours at a specified interval.

C#

[CommandMethod("CDS_ExtractSurfaceContoursAtInterval")]
public void CDS_ExtractSurfaceContoursAtInterval()
{
  using (Transaction tr = startTransaction())
  {
    ITerrainSurface surface = getSurface() as ITerrainSurface;
    if (surface == null) return;

    double interval = getDouble("interval");
    if (Double.IsNaN(interval)) return;

    ObjectIdCollection contours =
      surface.ExtractContours(interval);

    customizeContours(contours, _intervalContoursColor);

    tr.Commit();
  }
}

VB.NET

<CommandMethod("CDS_ExtractSurfaceContoursAtInterval")> _
Public Sub CDS_ExtractSurfaceContoursAtInterval()
  Using tr As Transaction = startTransaction()
    Dim surface As ITerrainSurface = TryCast(getSurface(), 
      ITerrainSurface)
    If surface Is Nothing Then
      Return
    End If

    Dim interval As Double = getDouble("interval")
    If [Double].IsNaN(interval) Then
      Return
    End If

    Dim contours As ObjectIdCollection = surface.ExtractContours(
      interval)

    customizeContours(contours, _intervalContoursColor)

    tr.Commit()
  End Using
End Sub

We can further customize the behavior by specifying the minimum and maximum elevation to utilize together with the interval. This other example does just that.

C#

[CommandMethod("CDS_ExtractSurfaceContoursFromToElevationRange")]
public void CDS_ExtractSurfaceContoursFromToElevationRange()
{
  using (Transaction tr = startTransaction())
  {
    ITerrainSurface surface = getSurface() as ITerrainSurface;
    if (surface == null) return;
                
    double minElevation = getDouble("minimum elevation");
    if (Double.IsNaN(minElevation)) return;

    double maxElevation = getDouble("maximum elevation");
    if (Double.IsNaN(maxElevation)) return;

    double interval = getDouble("interval");
    if (Double.IsNaN(interval)) return;

    ObjectIdCollection contours =
      surface.ExtractContours(
        minElevation, maxElevation, interval);

    customizeContours(contours, _rangedContoursColor);
                    
    tr.Commit();
  }
}

VB.NET

<CommandMethod("CDS_ExtractSurfaceContoursFromToElevationRange")> _
Public Sub CDS_ExtractSurfaceContoursFromToElevationRange()
  Using tr As Transaction = startTransaction()
    Dim surface As ITerrainSurface = TryCast(getSurface(), 
      ITerrainSurface)
    If surface Is Nothing Then
      Return
    End If

    Dim minElevation As Double = getDouble("minimum elevation")
    If [Double].IsNaN(minElevation) Then
      Return
    End If

    Dim maxElevation As Double = getDouble("maximum elevation")
    If [Double].IsNaN(maxElevation) Then
      Return
    End If

    Dim interval As Double = getDouble("interval")
    If [Double].IsNaN(interval) Then
      Return
    End If

    Dim contours As ObjectIdCollection = surface.ExtractContours(
      minElevation, maxElevation, interval)

    customizeContours(contours, _rangedContoursColor)

    tr.Commit()
  End Using
End Sub

As you can see, these methods are implemented as part of the ‘ITerrainSurface’ interface, which means they can be used with TIN and Grid surfaces, The ‘ExtractContours()’ methods provide great flexibility to extract contour information from a surface, and their functionality is what most users require. Next week, we will take a look at an even more flexible method provided by ‘ITerrainSurface’.

P.S. I refactored some of the code from last week to apply it to this week’s examples. I recommend you download the latest source from the Civilized Development Repository at BitBucket.

21WOJP–Week 16: Extracting Major and Minor Contours

As we’ve been seeing lately, Jay Peak adds some additional functionality to the Surfaces API that was missing in previous releases. One of the most requested feature was the ability to extract surface contours. In the COM API, this functionality was very rudimentary and inflexible. With the new .NET implementation, we are giving you the power, so you can work with surface contours in any way you want.

I decided to create a series of posts instead of humongous article, so it is easier to follow the samples and understand the functionality. Bear with me through the series as I explain how this functionality works.

As you probably know, the Surface object in Civil 3D can be represented by major and minor contours. You can make this contours visible and control their parameters through the Surface style. However, this doesn’t give you any information about the contours unless you extract them.

The API defines two methods to extract these contours: ‘ExtractMajorContours()’ and ‘ExtractMinorContours()’. These two methods are declared in the ‘ITerrainSurface’ interface, which is implemented by ‘TinSurface’ and ‘GridSurface’; therefore, you can extract contour information from both of them. The following example implements a command that extracts these contours from a selected surface.

C#

using System;

using Autodesk.AutoCAD.DatabaseServices;
using Autodesk.AutoCAD.EditorInput;
using Autodesk.AutoCAD.Runtime;
using Autodesk.Civil;
using Autodesk.Civil.DatabaseServices;

using CivilSurface = Autodesk.Civil.DatabaseServices.Surface;
using AcadEntity = Autodesk.AutoCAD.DatabaseServices.Entity;

[assembly: CommandClass(
  typeof(Autodesk.CivilizedDevelopment.SurfaceExtractContoursCommands))]

namespace Autodesk.CivilizedDevelopment
{
  public class SurfaceExtractContoursCommands : SimpleDrawingCommand
  {
    [CommandMethod("CDS_ExtractSurfceContours")]
    public void CDS_ExtractSurfceContours()
    {
      ObjectId surfaceId = promptForTinSurface();
      if (surfaceId.IsNull)
      {
        write("\nNo Surface selected.");
        return;
      }

      using (Transaction tr = startTransaction())
      {
        CivilSurface surface = surfaceId.GetObject(OpenMode.ForRead)
          as CivilSurface;
        showGeneralProperties(surface.Name, 
          surface.GetGeneralProperties());
        ITerrainSurface terrainSurface = surface as ITerrainSurface;
        if (terrainSurface != null)
        {
          extractMajorContours(terrainSurface);
          extractMinorContours(terrainSurface);
        }

        tr.Commit();
      }
    }

    private void showGeneralProperties(string name, 
      GeneralSurfaceProperties props)
    {
      _editor.WriteMessage("\nSurface name: " + name);
      _editor.WriteMessage("\n- Max elevation: " + 
        props.MaximumElevation);
      _editor.WriteMessage("\n- Min elevation: " + 
        props.MinimumElevation);
    }

    private void extractMajorContours(ITerrainSurface surface)
    {
      ObjectIdCollection contours = surface.ExtractMajorContours(
        SurfaceExtractionSettingsType.Model);
      AutoCAD.Colors.Color blue = 
        AutoCAD.Colors.Color.FromRgb(0, 0, 255);
      customizeContours(contours, blue);
    }

    private void extractMinorContours(ITerrainSurface surface)
    {
      ObjectIdCollection contours = surface.ExtractMinorContours(
        SurfaceExtractionSettingsType.Model);
      AutoCAD.Colors.Color lightblue =
        AutoCAD.Colors.Color.FromRgb(0, 255, 255);
      customizeContours(contours, lightblue);
    }

    private void customizeContours(ObjectIdCollection contours, 
      AutoCAD.Colors.Color color)
    {
      foreach (ObjectId id in contours)
      {
        AcadEntity entity = id.GetObject(OpenMode.ForWrite) 
          as AcadEntity;
        entity.Color = color;
      }
    }


    private ObjectId promptForTinSurface()
    {
      PromptEntityOptions options = new PromptEntityOptions(
        "\nSelect a Surface: ");
      options.SetRejectMessage(
        "\nThe selected object is not a Surface.");
      options.AddAllowedClass(typeof(CivilSurface), false);

      PromptEntityResult result = _editor.GetEntity(options);
      if (result.Status == PromptStatus.OK)
      {
        // Everything is cool; we return the selected
        // surface ObjectId.
        return result.ObjectId;
      }
      return ObjectId.Null;   // Indicating error.
    }
  }
}

VB.NET

Imports System

Imports Autodesk.AutoCAD.DatabaseServices
Imports Autodesk.AutoCAD.EditorInput
Imports Autodesk.AutoCAD.Runtime
Imports Autodesk.Civil
Imports Autodesk.Civil.DatabaseServices

Imports CivilSurface = Autodesk.Civil.DatabaseServices.Surface
Imports AcadEntity = Autodesk.AutoCAD.DatabaseServices.Entity

<Assembly: CommandClass(
  GetType(Autodesk.CivilizedDevelopment.SurfaceExtractContoursCommands))> 

Namespace Autodesk.CivilizedDevelopment
  Public Class SurfaceExtractContoursCommands
    Inherits SimpleDrawingCommand
    <CommandMethod("CDS_ExtractSurfceContours")> _
    Public Sub CDS_ExtractSurfceContours()
      Dim surfaceId As ObjectId = promptForTinSurface()
      If surfaceId.IsNull Then
        write(vbLf & "No Surface selected.")
        Return
      End If

      Using tr As Transaction = startTransaction()
        Dim surface As CivilSurface =
          TryCast(surfaceId.GetObject(OpenMode.ForRead), CivilSurface)
        showGeneralProperties(surface.Name,
                              surface.GetGeneralProperties())
        Dim terrainSurface As ITerrainSurface =
          TryCast(surface, ITerrainSurface)
        If terrainSurface IsNot Nothing Then
          extractMajorContours(terrainSurface)
          extractMinorContours(terrainSurface)
        End If

        tr.Commit()
      End Using
    End Sub



    Private Sub showGeneralProperties(name As String,
                                      props As GeneralSurfaceProperties)
      _editor.WriteMessage(vbLf & "Surface name: " + name)
      _editor.WriteMessage(vbLf & "- Max elevation: " +
                           props.MaximumElevation)
      _editor.WriteMessage(vbLf & "- Min elevation: " +
                           props.MinimumElevation)
    End Sub



    Private Sub extractMajorContours(surface As ITerrainSurface)
      Dim contours As ObjectIdCollection =
        surface.ExtractMajorContours(SurfaceExtractionSettingsType.Model)
      Dim blue As AutoCAD.Colors.Color =
        AutoCAD.Colors.Color.FromRgb(0, 0, 255)
      customizeContours(contours, blue)
    End Sub



    Private Sub extractMinorContours(surface As ITerrainSurface)
      Dim contours As ObjectIdCollection =
        surface.ExtractMinorContours(SurfaceExtractionSettingsType.Model)
      Dim lightblue As AutoCAD.Colors.Color =
        AutoCAD.Colors.Color.FromRgb(0, 255, 255)
      customizeContours(contours, lightblue)
    End Sub



    Private Sub customizeContours(contours As ObjectIdCollection,
                                  color As AutoCAD.Colors.Color)
      For Each id As ObjectId In contours
        Dim entity As AcadEntity =
          TryCast(id.GetObject(OpenMode.ForWrite), AcadEntity)
        entity.Color = color
      Next
    End Sub




    Private Function promptForTinSurface() As ObjectId
      Dim options As New PromptEntityOptions(
        vbLf & "Select a TIN Surface: ")
      options.SetRejectMessage(
        vbLf & "The selected object is not a TIN Surface.")
      options.AddAllowedClass(GetType(CivilSurface), False)

      Dim result As PromptEntityResult = _editor.GetEntity(options)
      If result.Status = PromptStatus.OK Then
        ' Everything is cool; we return the selected
        ' surface ObjectId.
        Return result.ObjectId
      End If
      Return ObjectId.Null
      ' Indicating error.
    End Function


  End Class
End Namespace

For illustration purposes, we retrieve all the contours and edit the returned polylines to change their color. If you don’t care about keeping the polylines, you can process the information and not commit the transaction at the end, which will remove them from the drawing.

NOTE: I am showing the entire source file, so you can follow some of the using aliases I created. The name ‘Surface’ creates a conflict between the Civil API and the AutoCAD API, and I declare an alias that I use in the code. This is also true of the ‘Entity’ name.

21WOJP–Week 15: What’s the Closest Surface Point?

Today, we are going to take a look at the ‘ExtractBorder()’ method defined in the ITerrainSurface interface implemented by ‘TinSurface’ and ‘GridSurface’. The method is very basic. Similarly to the ‘ExtractGridded()’ method, ‘ExtractBorder()’ returns an ‘ObjectIdCollection’ with ids pointing to ‘Polyline3d’ objects that represent the surface border. The reason a collection is returned is because a surface may have areas in between which are not part of the surface. Take a look at the following screen shot.

What you see in the screenshot is a single surface representing two islands. If you were to select the surface, you will see both quadrilaterals are selected and are part of the same surface (you can find this drawing, ‘islands.dwg’ posted with the source). In a scenario like this, the border is represented by two polylines (Polyline3d objects).

Finding the Closest Surface Point to a Point Outside of the Surface

The Surfaces API provides several properties and methods to retrieve information about points in a surface. You can find the elevation at a specified X/Y values. You can find a triangle, point, or edge at a specified X/Y, etc. But most of these methods will throw an exception if the point is not located on top of the surface, which makes more difficult to find surface information from external points.

Augusto Goncalves wrote a wonderful post explaining how you can find the closest edge at an X/Y. His method first uses ‘FindEdgeAtXY()’ in case the point is on top of the surface, and if that fails, then searches for the edge himself.

I got some reports of performance issues with Augusto’s implementation, so I started investigating and finally, I talked to Dr. John Lewis, who around this town is known as “The Surface Master”. Jokes aside, John has worked on the surface engine for many years, and if there is someone who knows about its performance and best approaches is him. As he explained to me, the Surface engine used by Civil 3D is optimized for operations that work inside of the surface. but when you try to do the work yourself and support other functionality, it may be worth it to use other means. He gave me the idea for the implementation below.

DISCLAIMER: I have not compared performance of Augusto’s implementation vs. the code I will show below, but I have not seen any significant performance impact in my implementation. Also, the results are not exactly the same, so keep reading.

The first difference between the solution I will provide and Augusto’s is that I do not return a ‘TinSurfaceEdge’ object; I just return a ‘Point3d’. You have to take this into account and evaluate it in the context of the problem you are trying to solve. With my result, you can still find the edge using the existing API if you really need the edge object; although, you may have to adjust by some tolerance value, but I’ll leave that as an exercise to the reader.

The second difference is that my implementation assumes the point is not on top of the surface. If you know the point is outside of the surface, this is a straight shot at it. Otherwise, you can combine Augusto’s implementation with mine to write a function that tests for both.

Let me start by showing you the code, and then I will discuss the implementation.

C#

[CommandMethod("CDS_FindClosestPointOnSurface")]
public void CDS_FindClosestPointOnSurface()
{
  ObjectId surfaceId = promptForTinSurface();
  if (surfaceId.IsNull)
  {
    write("\nNo TIN Surface selected.");
    return;
  }

  PromptPointResult result = _editor.GetPoint(
    "\nSelect point outside surface: ");
  if (result.Status != PromptStatus.OK)
  {
    write("\nNo point selected.");
    return;
  }

  Point3d selectedPoint = result.Value;
  Point3d closestPointFound = Point3d.Origin;
  double shortestDistanceSoFar = Double.MaxValue;

  using (Transaction tr = startTransaction())
  {
    TinSurface surface = surfaceId.GetObject(OpenMode.ForRead) 
      as TinSurface;
    write("\nSelected surface: " + surface.Name);
    write("\nSelected point: " + selectedPoint.ToString());
    ObjectIdCollection borders = surface.ExtractBorder(
      SurfaceExtractionSettingsType.Model);
    foreach (ObjectId borderId in borders)
    {
      Polyline3d border = borderId.GetObject(OpenMode.ForRead) 
        as Polyline3d;
      Point3d closestToBorder = 
        border.GetClosestPointTo(selectedPoint, false);
      double distance = selectedPoint.DistanceTo(closestToBorder);
      if (distance < shortestDistanceSoFar)
      {
        closestPointFound = closestToBorder;
        shortestDistanceSoFar = distance;
      }
    }
  }

  write("\nClosest point found: " + closestPointFound.ToString());

  using (Transaction tr = startTransaction())
  {
    BlockTableRecord btr = tr.GetObject(_database.CurrentSpaceId, 
      OpenMode.ForWrite) as BlockTableRecord;
    Line line = new Line(selectedPoint, closestPointFound);
    btr.AppendEntity(line);
    tr.AddNewlyCreatedDBObject(line, true);
    tr.Commit();
  }
}

VB.NET

<CommandMethod("CDS_FindClosestPointOnSurface")> _
Public Sub CDS_FindClosestPointOnSurface()
  Dim surfaceId As ObjectId = promptForTinSurface()
  If surfaceId.IsNull Then
    write(vbLf & "No TIN Surface selected.")
    Return
  End If

  Dim result As PromptPointResult = _editor.GetPoint(
    vbLf & "Select point outside surface: ")
  If result.Status <> PromptStatus.OK Then
    write(vbLf & "No point selected.")
    Return
  End If

  Dim selectedPoint As Point3d = result.Value
  Dim closestPointFound As Point3d = Point3d.Origin
  Dim shortestDistanceSoFar As Double = [Double].MaxValue

  Using tr As Transaction = startTransaction()
    Dim surface As TinSurface = TryCast(
      surfaceId.GetObject(OpenMode.ForRead), TinSurface)
    write(vbLf & "Selected surface: " & surface.Name)
    write(vbLf & "Selected point: " & selectedPoint.ToString())
    Dim borders As ObjectIdCollection = surface.ExtractBorder(
      SurfaceExtractionSettingsType.Model)
    For Each borderId As ObjectId In borders
      Dim border As Polyline3d = TryCast(
        borderId.GetObject(OpenMode.ForRead), Polyline3d)
      Dim closestToBorder As Point3d =
        border.GetClosestPointTo(selectedPoint, False)
      Dim distance As Double = selectedPoint.DistanceTo(closestToBorder)
      If distance < shortestDistanceSoFar Then
        closestPointFound = closestToBorder
        shortestDistanceSoFar = distance
      End If
    Next
  End Using

  write(vbLf & "Closest point found: " & closestPointFound.ToString())

  Using tr As Transaction = startTransaction()
    Dim btr As BlockTableRecord = TryCast(tr.GetObject(
      _database.CurrentSpaceId, OpenMode.ForWrite), BlockTableRecord)
    Dim line As New Line(selectedPoint, closestPointFound)
    btr.AppendEntity(line)
    tr.AddNewlyCreatedDBObject(line, True)
    tr.Commit()
  End Using
End Sub

The command prompts the user to select a surface and a external point. Because the point is not on top of the surface, we know the closest point is going to be at the border, so we use ‘ExtractBorder()’, which is a very efficient operation executed in the surface engine, to collect the ‘Polyline3d’ objects representing the border.

Once we have the ids for the ‘Polyline3d’ objects, we open them and use the ‘GetClosestPointTo()’ method to find the closest point between the ‘Polyline3d’ and our specified point.

Then, we use ‘Point3d.DistanceTo()’ to calculate the distance between the two points, and if this is the shortest distance so far, we keep that value and cache the point found.

Once we have processed all the borders, ‘closestPointFound’ will contain the closest point and ‘shortestDistanceSoFar’ will contain the distance to that point. The command adds a line between this point and the one we specified, so we can easily see the result.

The performance, even with large surfaces, is stellar, so give it a shot and let me know if you have any questions or issues. As always, you can download the entire source code from BitBucket.

21WOJP–Week 14: Extracting a Grid from a TIN Surface

It has been a long time since my last post due to, go figure, all the work we are doing for our next release. It is very hard to keep the weekly post and do my actual work during times like this. I still want to complete the series and I ask you to be patient if I miss some week. There are some more topics to cover, which I think are very interesting.

This week I will like to talk about extracting a grid from a TIN surface. This functionality exists in the application and has been exposed through the API. The API for this functionality is very simple. You just need to get a TIN surface and invoke its ‘ExtractGridded()’ method. The method takes a ‘SurfaceExtractionSettingsType’, which can have a value of ‘Model’ or ‘Plan’. This directly corresponds to 2d or 3d (We use ‘Model’ in the example, which is 3d).

Once the polylines that create the grid are extracted, you can manipulate them as any other object. In the example, we just change their color so you can distinguish them, but you can do whichever manipulation you like. Some people will not want to keep the polylines around, in which case, you can extract the information you want and not commit the transaction, so the polylines are not added to the drawing.

Here is the entire source, which you can also get from the Civilized Development repository at BitBucket.

C#

[CommandMethod("CDS_ExtractGrid")]
public void CDS_ExtractGrid()
{
  ObjectId surfaceId = promptForTinSurface();
  if (surfaceId == ObjectId.Null)
  {
    write("\nNo TIN Surface selected.");
    return;
  }

  using (Transaction tr = startTransaction())
  {
    TinSurface surface = surfaceId.GetObject(OpenMode.ForRead)
      as TinSurface;
    ObjectIdCollection ids = surface.ExtractGridded(
      SurfaceExtractionSettingsType.Model);
                
    foreach (ObjectId id in ids)
    {
      Polyline3d polyline =
        id.GetObject(OpenMode.ForWrite) as Polyline3d;
      if (polyline != null)
      {                        
        using (polyline)
        {
          polyline.Color = 
            AutoCAD.Colors.Color.FromRgb(255, 0, 0);
        }
      }
    }
    tr.Commit();
  }
}

private ObjectId promptForTinSurface()
{
  PromptEntityOptions options = new PromptEntityOptions(
    "\nSelect a TIN Surface: ");
  options.SetRejectMessage(
    "\nThe selected object is not a TIN Surface.");
  options.AddAllowedClass(typeof(TinSurface), true);

  PromptEntityResult result = _editor.GetEntity(options);
  if (result.Status == PromptStatus.OK)
  {
    return result.ObjectId;
  }
  return ObjectId.Null;   // Indicating error.
}

VB.NET

<CommandMethod("CDS_ExtractGrid")> _
Public Sub CDS_ExtractGrid()
  Dim surfaceId As ObjectId = promptForTinSurface()
  If surfaceId = ObjectId.Null Then
    write(vbLf & "No TIN Surface selected.")
    Return
  End If

  Using tr As Transaction = startTransaction()
    Dim surface As TinSurface =
      TryCast(surfaceId.GetObject(OpenMode.ForRead), TinSurface)
    Dim ids As ObjectIdCollection = surface.ExtractGridded(
      SurfaceExtractionSettingsType.Model)
    For Each id As ObjectId In ids
      Dim polyline As Polyline3d =
        TryCast(id.GetObject(OpenMode.ForWrite), Polyline3d)
      If polyline IsNot Nothing Then
        Using polyline
          polyline.Color = AutoCAD.Colors.Color.FromRgb(255, 0, 0)
        End Using
      End If
    Next
    tr.Commit()
  End Using
End Sub

    Private Function promptForTinSurface() As ObjectId
      Dim options As New PromptEntityOptions(vbLf & _
        "Select a TIN Surface: ")
      options.SetRejectMessage(vbLf & _
        "The selected object is not a TIN Surface.")
      options.AddAllowedClass(GetType(TinSurface), True)

      Dim result As PromptEntityResult = _editor.GetEntity(options)
      If result.Status = PromptStatus.OK Then
        ' Everything is cool; we return the selected
        ' surface ObjectId.
        Return result.ObjectId
      End If
      Return ObjectId.Null
      ' Indicating error.
    End Function

21WOJP–Week 13: Adding Components to a Label Style

Last week, we took a look at how we could access some of the label properties for COGO points, and how we could override the label through the Point Group. But things get more interesting when you start creating your own label style that can be applied to objects. Today, we will take a look at how to add components to a label style. In my example, I will create a COGO point label style, but the concepts apply to all the label styles.

In the following example, we will create a new point label style named “Demo”. Then, we will add some components to demonstrate how they are created and customized. Here is the basic implementation of the command.

C#

[CommandMethod("CDS_CreateDemoPointLabelStyle")]
public void CDS_CreateDemoPointLabelStyle()
{
  createPointLabelStyle("Demo"); 
}

private void createPointLabelStyle(string name)
{
  ObjectId styleId = _pointLabelStyles.Add(name);
  removeAllComponents(styleId);
  customizeStyle(styleId);
}

private LabelStyleCollection _pointLabelStyles
{
  get
  {
    return _civildoc.Styles.LabelStyles.PointLabelStyles.LabelStyles;
  }
}

VB.NET

<CommandMethod("CDS_CreateDemoPointLabelStyle")> _
Public Sub CDS_CreateDemoPointLabelStyle()
  createPointLabelStyle("Demo")
End Sub

Private Sub createPointLabelStyle(name As String)
  Dim styleId As ObjectId = _pointLabelStyles.Add(name)
  removeAllComponents(styleId)
  customizeStyle(styleId)
End Sub

Private ReadOnly Property _pointLabelStyles() As LabelStyleCollection
  Get
    Return _civildoc.Styles.LabelStyles.PointLabelStyles.LabelStyles
  End Get
End Property

When we create a new point label style, the object is initialized with three text components. We want to start from scratch, so the first thing that we do is remove them. Here is the implementation to remove the text components that get created by default.

C#

private void removeAllComponents(ObjectId styleId)
{
  IEnumerable<string> componentNames = getTextComponentNames(styleId);
  removeComponents(styleId, componentNames);
}

private IEnumerable<string> getTextComponentNames(ObjectId styleId)
{
  List<string> names = new List<string>();
  using (Transaction tr = startTransaction())
  {
    LabelStyle style = styleId.GetObject(OpenMode.ForRead)
      as LabelStyle;
    foreach (ObjectId id in style.GetComponents(
      LabelStyleComponentType.Text))
    {
      LabelStyleComponent component =
        id.GetObject(OpenMode.ForRead) as LabelStyleComponent;
      names.Add(component.Name);
    }
  }
  return names;
}

private void removeComponents(ObjectId styleId, 
  IEnumerable<string> componentNames)
{
  using (Transaction tr = startTransaction())
  {
    LabelStyle style = styleId.GetObject(OpenMode.ForWrite)
      as LabelStyle;
    foreach (string name in componentNames)
    {
      style.RemoveComponent(name);
    }

    tr.Commit();
  }
}

VB.NET

Private Sub removeAllComponents(styleId As ObjectId)
  Dim componentNames As IEnumerable(Of String) = getTextComponentNames(
    styleId)
  removeComponents(styleId, componentNames)
End Sub

Private Function getTextComponentNames(styleId As ObjectId) _
    As IEnumerable(Of String)
  Dim names As New List(Of String)()
  Using tr As Transaction = startTransaction()
    Dim style As LabelStyle = TryCast(styleId.GetObject(OpenMode.ForRead), 
      LabelStyle)
    For Each id As ObjectId In style.GetComponents(
        LabelStyleComponentType.Text)
      Dim component As LabelStyleComponent = TryCast(
        id.GetObject(OpenMode.ForRead), LabelStyleComponent)
      names.Add(component.Name)
    Next
  End Using
  Return names
End Function

Private Sub removeComponents(styleId As ObjectId, componentNames _
    As IEnumerable(Of String))
  Using tr As Transaction = startTransaction()
    Dim style As LabelStyle = TryCast(styleId.GetObject(OpenMode.ForWrite), 
      LabelStyle)
    For Each name As String In componentNames
      style.RemoveComponent(name)
    Next

    tr.Commit()
  End Using
End Sub

After we clean-up the style, we add three components. The first one will be a leader/line that will go from the <feature>, in this case the point, to the text of the label. The following code shows how to create the line component.

C#

private void customizeStyle(ObjectId styleId)
{
  using (Transaction tr = startTransaction())
  {
    addStyleComponents(styleId);
    tr.Commit();
  }
}

private void addStyleComponents(ObjectId styleId)
{
  LabelStyle style = styleId.GetObject(OpenMode.ForWrite)
    as LabelStyle;
  addLeaderComponent(style);
  addPointNumberComponent(style);
  addLocationComponent(style);
}

private void addLeaderComponent(LabelStyle style)
{
  ObjectId id = style.AddComponent("Leader", 
  LabelStyleComponentType.Line);
  LabelStyleLineComponent component = id.GetObject(OpenMode.ForWrite)
    as LabelStyleLineComponent;
  component.General.StartAnchorPoint.Value = AnchorPointType.MiddleCenter;
}

VB.NET

Private Sub customizeStyle(styleId As ObjectId)
  Using tr As Transaction = startTransaction()
    addStyleComponents(styleId)
    tr.Commit()
  End Using
End Sub

Private Sub addStyleComponents(styleId As ObjectId)
  Dim style As LabelStyle = TryCast(styleId.GetObject(OpenMode.ForWrite), 
    LabelStyle)
  addLeaderComponent(style)
  addPointNumberComponent(style)
  addLocationComponent(style)
End Sub

Private Sub addLeaderComponent(style As LabelStyle)
  Dim id As ObjectId = style.AddComponent("Leader",
    LabelStyleComponentType.Line)
  Dim component As LabelStyleLineComponent = TryCast(
    id.GetObject(OpenMode.ForWrite), LabelStyleLineComponent)
  component.General.StartAnchorPoint.Value = AnchorPointType.MiddleCenter
End Sub

We create two text components. The first one will show the point number; the second one will show the location of the point in the format (northing, easting, elevation). Here is the code.

C#

private void addPointNumberComponent(LabelStyle style)
{
  ObjectId id = style.AddComponent("PN", 
    LabelStyleComponentType.Text);
  LabelStyleTextComponent component = id.GetObject(OpenMode.ForWrite)
    as LabelStyleTextComponent;
  component.Text.Attachment.Value = LabelTextAttachmentType.MiddleLeft;
  component.Text.Contents.Value = _pointNumber;
  component.General.AnchorComponent.Value = "Leader";
  component.General.AnchorLocation.Value = AnchorPointType.End;
}

private void addLocationComponent(LabelStyle style)
{
  ObjectId id = style.AddComponent("Location", 
    LabelStyleComponentType.Text);
  LabelStyleTextComponent component = id.GetObject(OpenMode.ForWrite)
    as LabelStyleTextComponent;
  component.Text.Attachment.Value = LabelTextAttachmentType.TopLeft;
  string value = String.Format("({0}, {1}, {2})", 
    _northing, _easting, _elevation);
  component.Text.Contents.Value = value;
  component.General.AnchorComponent.Value = "PN";
  component.General.AnchorLocation.Value = AnchorPointType.BottomLeft;
}

VB.NET

Private Sub addPointNumberComponent(style As LabelStyle)
  Dim id As ObjectId = style.AddComponent("PN",
    LabelStyleComponentType.Text)
  Dim component As LabelStyleTextComponent = TryCast(
    id.GetObject(OpenMode.ForWrite), LabelStyleTextComponent)
  component.Text.Attachment.Value = LabelTextAttachmentType.MiddleLeft
  component.Text.Contents.Value = _pointNumber
  component.General.AnchorComponent.Value = "Leader"
  component.General.AnchorLocation.Value = AnchorPointType.[End]
End Sub

Private Sub addLocationComponent(style As LabelStyle)
  Dim id As ObjectId = style.AddComponent("Location",
    LabelStyleComponentType.Text)
  Dim component As LabelStyleTextComponent = TryCast(
    id.GetObject(OpenMode.ForWrite), LabelStyleTextComponent)
  component.Text.Attachment.Value = LabelTextAttachmentType.TopLeft
  Dim value As String = [String].Format("({0}, {1}, {2})",
    _northing, _easting, _elevation)
  component.Text.Contents.Value = value
  component.General.AnchorComponent.Value = "PN"
  component.General.AnchorLocation.Value = AnchorPointType.BottomLeft
End Sub

The ‘LabelStyle’ class applies to all labels in Civil 3D; however, not every object supports every component type. When a component is added to the ‘LabelStyle’ the type is checked to see if its supported by the labeled object. If it is not supported, an exception will be thrown. Fortunately, the ‘LabelStyle’ object exposes a ‘IsSupporteType()’ method that allows you to check if the type is supported for a specific instance of ‘LabelStyle’.

In future posts, we will dive more into the Labels API, and we will see what things we can do with it. For now, you can start playing adding components, which is a good starting point. Don’t forget to download the full source from the Civilized Development repository.

21WOJP–Week 12: Quick Point Labels

It has been a couple of very busy weeks, so I did not have much time for blogging. Plus I have been on training most of this week (you got to keep your skills sharp), so this is going to be a quick post. Still, I do not want to leave you without any information for two weeks, and this post will serve as an introduction for future posts.

As we saw during week 6 in the “COGO Point Bulk Operations” article, the COGO point object in itself is a very lightweight object, which only contains its graphical representation. A big part of representing a point is its label; therefore, the COGO point object, unlike other objects, exposes label properties right in the object itself.

The following example selects a COGO point object and displays its properties related to its label.

C#

[CommandMethod("CDS_ShowCogoPointLabelProperties")]
public void CDS_ShowCogoPointLabelProperties()
{
  ObjectId pointId = selectCogoPoint();
  if (pointId == ObjectId.Null)
  {
    return;
  }
  showLabelProperties(pointId);
}

private ObjectId selectCogoPoint()
{
  PromptEntityOptions options = new PromptEntityOptions(
    "Select COGO point: ");
  options.SetRejectMessage("\nInvalid COGO point selected.");
  options.AddAllowedClass(typeof(CogoPoint), true);
  PromptEntityResult result = _editor.GetEntity(options);
  if (result.Status == PromptStatus.OK)
  {
    return result.ObjectId;
  }
  return ObjectId.Null;
}

private void showLabelProperties(ObjectId pointId)
{
  using (Transaction tr = startTransaction())
  {
    CogoPoint point = pointId.GetObject(OpenMode.ForRead)
      as CogoPoint;
    showLabelPropertiesFor(point);
  }
}

private void showLabelPropertiesFor(CogoPoint point)
{
  write("\nPoint Label Properties:");
  write("\n- Style: " + getLabelStyleName(point.LabelStyleId));
  write("\n- Style override: " 
    + getLabelStyleName(point.LabelStyleIdOverride));
  write("\n- Visible: " + point.IsLabelVisible.ToString());
  write("\n- Location: " + point.LabelLocation.ToString());
  write("\n- Rotation: " + point.LabelRotation.ToString());
  write("\n- Dragged: " + point.IsLabelDragged.ToString());
  write("\n- Pinned: " + point.IsLabelPinned.ToString());
}

private string getLabelStyleName(ObjectId id)
{
  LabelStyle style = id.GetObject(OpenMode.ForRead) as LabelStyle;
  return style.Name;
}

VB.NET

<CommandMethod("CDS_ShowCogoPointLabelProperties")> _
Public Sub CDS_ShowCogoPointLabelProperties()
  Dim pointId As ObjectId = selectCogoPoint()
  If pointId = ObjectId.Null Then
    Return
  End If
  showLabelProperties(pointId)
End Sub

Private Function selectCogoPoint() As ObjectId
  Dim options As New PromptEntityOptions("Select COGO point: ")
  options.SetRejectMessage(vbLf & "Invalid COGO point selected.")
  options.AddAllowedClass(GetType(CogoPoint), True)
  Dim result As PromptEntityResult = _editor.GetEntity(options)
  If result.Status = PromptStatus.OK Then
    Return result.ObjectId
  End If
  Return ObjectId.Null
End Function

Private Sub showLabelProperties(pointId As ObjectId)
  Using tr As Transaction = startTransaction()
    Dim point As CogoPoint = TryCast(pointId.GetObject(OpenMode.ForRead), 
      CogoPoint)
    showLabelPropertiesFor(point)
  End Using
End Sub

Private Sub showLabelPropertiesFor(point As CogoPoint)
  write(vbLf & "Point Label Properties:")
  write(vbLf & "- Style: " & getLabelStyleName(point.LabelStyleId))
  write(vbLf & "- Style override: " _
    & getLabelStyleName(point.LabelStyleIdOverride))
  write(vbLf & "- Visible: " & point.IsLabelVisible.ToString())
  write(vbLf & "- Location: " & point.LabelLocation.ToString())
  write(vbLf & "- Rotation: " & point.LabelRotation.ToString())
  write(vbLf & "- Dragged: " & point.IsLabelDragged.ToString())
  write(vbLf & "- Pinned: " & point.IsLabelPinned.ToString())
End Sub

Private Function getLabelStyleName(id As ObjectId) As String
  Dim style As LabelStyle = TryCast(id.GetObject(OpenMode.ForRead), 
    LabelStyle)
  Return style.Name
End Function

The code, among other things, shows the label style name. There is also a label style override property, which returns the ‘ObjectId’ of the label style that overrides the one explicitly set in the COGO point. This property is read-only and comes from the primary point group to which the COGO point belongs. Of course, you have to state in the point group that you want to override the point label style. Here is an example of how to do that.

C#

[CommandMethod("CDS_OverrideLabelsForGroup")]
public void CDS_OverrideLabelsForGroup()
{
  using (Transaction tr = startTransaction())
  {
    ObjectId pointGroupId = promptForPointGroup();
    if (pointGroupId == ObjectId.Null)
    {
      return;
    }
    overrideLabelsForPointsIn(pointGroupId);
    tr.Commit();
  }        
}

private ObjectId promptForPointGroup()
{
  PromptResult result = _editor.GetString(
    "\nEnter point group name: ");
  if (result.Status == PromptStatus.OK)
  {
    return findGroup(result.StringResult);
  }
  return ObjectId.Null;
}

private void overrideLabelsForPointsIn(ObjectId pointGroupId)
{
  PointGroup group = pointGroupId.GetObject(OpenMode.ForWrite)
    as PointGroup;
  group.IsPointLabelStyleOverridden = true;
}

private ObjectId findGroup(string name)
{
  foreach (ObjectId id in _civildoc.PointGroups)
  {
    PointGroup group = id.GetObject(OpenMode.ForRead) 
      as PointGroup;
    if (group.Name == name)
    {
      return id;
    }
  }
  return ObjectId.Null;
}

VB.NET

<CommandMethod("CDS_OverrideLabelsForGroup")> _
Public Sub CDS_OverrideLabelsForGroup()
  Using tr As Transaction = startTransaction()
    Dim pointGroupId As ObjectId = promptForPointGroup()
    If pointGroupId = ObjectId.Null Then
      Return
    End If
    overrideLabelsForPointsIn(pointGroupId)
    tr.Commit()
  End Using
End Sub

Private Function promptForPointGroup() As ObjectId
  Dim result As PromptResult = _editor.GetString(vbLf _
    & "Enter point group name: ")
  If result.Status = PromptStatus.OK Then
    Return findGroup(result.StringResult)
  End If
  Return ObjectId.Null
End Function

Private Sub overrideLabelsForPointsIn(pointGroupId As ObjectId)
  Dim group As PointGroup = TryCast(
    pointGroupId.GetObject(OpenMode.ForWrite), PointGroup)
  group.IsPointLabelStyleOverridden = True
End Sub

Private Function findGroup(name As String) As ObjectId
  For Each id As ObjectId In _civildoc.PointGroups
    Dim group As PointGroup = TryCast(id.GetObject(OpenMode.ForRead), 
      PointGroup)
    If group.Name = name Then
      Return id
    End If
  Next
  Return ObjectId.Null
End Function

In a future post, we will look at the Labels API more in deep, since it is also part of the new functionality in Jay Peak.