21WOJP – Week 5: COGO Point Basics

Most of the API work done in Jay Peak was around providing a full COGO Point .NET API. COGO Points are an important piece in Civil 3D, and from an API perspective they present some challenges because of the  way they are implemented in the application. During the following weeks, we will take an in-depth look at the COGO Points .NET API, and I will explain the correct way to work with COGO Point objects.Today, we will take a look at some basic functionality like the different ways to create COGO Points and access their properties.

Creating COGO Points

There are several similar, yet different ways to create new COGO Points using the .NET API. You can create COGO Points one by one, or you can create several at once, which is more efficient when creating a large number of points.

The basics are the same. COGO Points are created through the ‘CogoPointCollection’ object exposed through the ‘’CogoPoints’ property in ‘CivilDocument’. The collection exposes several overloads of the ‘Add()’ method that creates new ‘CogoPoint’ objects and returns their id.

The following command demonstrates the different ways in which you can create COGO Points, as you can see, it will display information from the created objects, but we will look at that more in deep later on. For now, take a look at the implementation of the command.

C#

[CommandMethod("CDS_CreateRandomPoints")]
public void CDS_CreateRandomPoints()
{
  RandomCoordinateGenerator generator = 
    new RandomCoordinateGenerator();
  CogoPointCollection points = _civildoc.CogoPoints;

  // From Point3d
  Point3d coordinate = generator.GetCoordinate();
  ObjectId pointId = points.Add(coordinate);
  write("\nSingle Point from coordinate.");
  display(pointId);

  coordinate = generator.GetCoordinate();
  pointId = points.Add(coordinate, "Sample description.");
  write("\nSingle Point from coordinate and description.");
  display(pointId);

  coordinate = generator.GetCoordinate();
  pointId = points.Add(coordinate, "Sample description",  
    true, false);
  write("\nSingle Point from coordinate with description, "
    + "using description key, and not matching parameters.");
  display(pointId);

  // From Point3dCollection
  Point3dCollection coordinates = generator.GetCoordinates(10);
  ObjectIdCollection pointIds = points.Add(coordinates);
  write("\nPoints from coordinate collection.");
  display(pointIds);

  coordinates = generator.GetCoordinates(5);
  pointIds = points.Add(coordinates, "Group of 5");
  write("\nPoints from coordinate collection with description.");
  display(pointIds);

  coordinates = generator.GetCoordinates(7);
  pointIds = points.Add(coordinates, "Group of 7", true, true);
  write("\nPoints from coordinate collection with description,"
    + "using description key, and not matching parameters.");
  display(pointIds);
}

VB.NET

<CommandMethod("CDS_CreateRandomPoints")> _
Public Sub CDS_CreateRandomPoints()
  Dim generator As New RandomCoordinateGenerator()
  Dim points As CogoPointCollection = _civildoc.CogoPoints

  ' From Point3d
  Dim coordinate As Point3d = generator.GetCoordinate()
  Dim pointId As ObjectId = points.Add(coordinate)
  write(vbLf & "Single Point from coordinate.")
  display(pointId)

  coordinate = generator.GetCoordinate()
  pointId = points.Add(coordinate, "Sample description.")
  write(vbLf & "Single Point from coordinate and description.")
  display(pointId)

  coordinate = generator.GetCoordinate()
  pointId = points.Add(coordinate, "Sample description", True, False)
  write(vbLf & "Single Point from coordinate with description, " _
    & "using description key, and not matching parameters.")
  display(pointId)

  ' From Point3dCollection
  Dim coordinates As Point3dCollection = generator.GetCoordinates(10)
  Dim pointIds As ObjectIdCollection = points.Add(coordinates)
  write(vbLf & "Points from coordinate collection.")
  display(pointIds)

  coordinates = generator.GetCoordinates(5)
  pointIds = points.Add(coordinates, "Group of 5")
  write(vbLf & "Points from coordinate collection with description.")
  display(pointIds)

  coordinates = generator.GetCoordinates(7)
  pointIds = points.Add(coordinates, "Group of 7", True, True)
  write(vbLf & "Points from coordinate collection with description," _
    & "using description key, and not matching parameters.")
  display(pointIds)
End Sub

The ‘Add()’ method overloads are categorized in two basic ways: creating a single COGO Point object from a ‘Point3d’ or creating multiple COGO Point objects from a ‘Point3dCollection’. Variations of these two categories allows you specify other parameters for the creation, like the description used for the COGO Points. We will not go too deep into the different parameters, since their explanation requires understanding other concepts that we will look at in a later post.

Accessing COGO Point Properties

Like other Civil 3D objects, COGO Points are assigned an ‘ObjectId’ when created. This allows you to open the object and access its properties. The ‘display()’ methods in the example below shows how to do this.

C#

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

private void display(ObjectIdCollection pointIds)
{
  using (Transaction tr = startTransaction())
  {
    foreach (ObjectId pointId in pointIds)
    {
      CogoPoint point = pointId.GetObject(OpenMode.ForRead)
        as CogoPoint;
      displayPointInfo(point);
    }
  }
}

private void displayPointInfo(CogoPoint point)
{
  write("\nPoint Number: " + point.PointNumber.ToString());
  write("\n- Location: " + point.Location.ToString());
  write("\n- - Northing: " + point.Northing.ToString());
  write("\n- - Easting: " + point.Easting.ToString());
  write("\n- - Elevation: " + point.Elevation.ToString());
  write("\n- Description: " + point.FullDescription);
  write("\n- Raw Description: " + point.RawDescription);
}

VB.NET

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

Private Sub display(pointIds As ObjectIdCollection)
  Using tr As Transaction = startTransaction()
    For Each pointId As ObjectId In pointIds
      Dim point As CogoPoint =
        TryCast(pointId.GetObject(OpenMode.ForRead), CogoPoint)
      displayPointInfo(point)
    Next
  End Using
End Sub

Private Sub displayPointInfo(point As CogoPoint)
  write(vbLf & "Point Number: " & point.PointNumber.ToString())
  write(vbLf & "- Location: " & point.Location.ToString())
  write(vbLf & "- - Northing: " & point.Northing.ToString())
  write(vbLf & "- - Easting: " & point.Easting.ToString())
  write(vbLf & "- - Elevation: " & point.Elevation.ToString())
  write(vbLf & "- Description: " & _
    Convert.ToString(point.FullDescription))
  write(vbLf & "- Raw Description: " & _
    Convert.ToString(point.RawDescription))
End Sub

The ‘display()’ methods open the ‘CogoPoint’ objects and pass them to ‘displayPointInfo()’, which reads the properties and displays them. In this sample, we are just reading properties from the ‘CogoPoint’ object, so this way of accessing them and getting their properties should be fine. However, COGO Points are implemented different than other Civil 3D objects for performance and scalability issues. In a later post, we will talk about the actual implementation of the COGO Point object and how to work more efficiently when we need to update/write to it.

The ‘CDS_CreateRandomPoints’ command uses a ‘RandomCoordinateGenerator’ object to randomly create new locations/coordinates for the points. The full source code contains the implementation of this class. Alternatively, you can download the source files and add them to your own project.

Comments

[Udo]

As nice as this is but why are still not all objects accessable via the .net API ? Why is the .net API still incomplete ?

[Udo]

As nice as this is but why are still not all objects accessable via the .net API ? Why is the .net API still incomplete ?

[Isaac Rodriguez]

Hi Udo,

As you may already know, Civil 3D is a moving target. There are a lot of features being implemented with every release, which makes it very difficult to provide a full API.

We are working very hard to complete all the objects, but we also want to have an API that works well and serves our customers' needs, and that takes time.

You are more than welcome to send me a list of requirements for objects that are missing and are important to you, and I will evaluate them and consider them while planning the work to be done. No guarantees though.