21WOJP - Week 6 – COGO Points Bulk Operations

The COGO Point object in Civil 3D had some special requirements that influence its design and make it different from other Civil 3D (or AutoCAD) objects. Among its special requirements, there were two of great importance: performance and scalability. This does not mean that other Civil 3D objects have been implemented with complete disregard for performance and scalability, but COGO Points are different because a drawing may contain thousands if not millions of point.

You won’t find many drawings with thousands of Corridors, Alignments, or Surfaces. As a matter of fact, I assure you, you won’t find any. But you can easily find drawings containing thousands or more COGO Points. The design of other objects if applied to COGO Points will be very inefficient. It will be slow to process points, and it will consume a lot of memory. It will impact the performance, but worse yet, it will make the feature not scalable for industry needs.

In reality, without going to deep into the implementation details, the COGO Point ‘DBObject’ is a very simple object containing no data, other than its graphical representation for display purposes. All the data for the COGO Points in a drawing is stored in what we call internally the “points node”. An abstraction of this node is provided through the API in the form of a ‘CogoPointCollection’ object, which is exposed by the ‘CogoPoints’ property of the ‘CivilDocument’ object.

This design allows the ‘CogoPointCollection’ to expose an interface that makes editing COGO Point properties very efficiently when processing multiple ‘CogoPoint’ objects. Let’s take a look at a quick example.

C#

[CommandMethod("CDS_OffsetPointElevations")]
public void CDS_OffsetPointElevations()
{
  PromptDoubleResult result = _editor.GetDouble(
    "\nEnter elevation offset: ");
  if (result.Status == PromptStatus.OK)
  {
    double offset = result.Value;
    CogoPointCollection points = _civildoc.CogoPoints;
    points.SetElevationByOffset(points, offset);
  }
}

VB.NET

<CommandMethod("CDS_OffsetPointElevations")> _
Public Sub CDS_OffsetPointElevations()
  Dim result As PromptDoubleResult = _editor.GetDouble(vbLf _ 
    & "Enter elevation offset: ")
  If result.Status = PromptStatus.OK Then
    Dim offset As Double = result.Value
    Dim points As CogoPointCollection = _civildoc.CogoPoints
    points.SetElevationByOffset(points, offset)
  End If
End Sub

As you probably figured out, the command prompts the users of an offset elevation value, and then modifies the elevation property of all points in the drawing by that offset. You can see how easy it is to do this through the ‘bulk operation’ methods exposed by the ‘CogoPointCollection’ class.

If you dive into the ‘CogoPointcollection’ methods, you will see that there are several “Set…” methods that allow setting properties of the ‘CogoPoint’ objects contained in the collection. These methods usually have the following overloads:

• ObjectId, Value: When the method takes an ‘ObjectId’ and a ‘Value’, it is setting the property for a single ‘CogoPoint’ object (the ‘CogoPoint’ object to which the ‘ObjectId’ refers). These methods work the same as if you were to open the ‘ObjectId’ for write and set the same property in the ‘CogoPoint’ object.
• IEnumerable<ObjectId>, Value: A second overload will take an IEnumerable of ‘ObjectId’ and a value. In this case, the same value is being set for all the ‘CogoPoint’ objects represented by the specified object ids.
• IEnumerable<ObjectId>, IEnumerable<”Value”>: This third overload allows to set the property for each of the specified ‘CogoPoint’ object and specify individual values for each one of them.

There are two things to consider when you are using the last overload that takes ‘IEnumerables’ for ‘ObjectId’ and ‘Values’. If the number of items the ‘ObjectId’ enumerable <x> is larger than the number of items in the ‘Values’ enumerable <y>, only <y> number of points are updated. If the number of ‘Values’ <y> is larger than the number of points <x>, all the specified points are updated, but the remaining values are ignored.

Bulk operations for COGO Points are very powerful and efficient. When working with COGO Points, you want to find ways to make edits in bulk better than opening each of the individual objects. The interface exposed through the ‘CogoPointCollection’ class allows you to write efficient code for editing COGO Points and provides great flexibility on how the edits are performed.

As usual, you can download the source code from the Civilized Development repository at bit bucket.

P.S: I realized that the build process for Colibra (the process that was packaging the code and sample) is not working and the generated ZIP file was empty. So I’ve been posting empty ZIP files to dropbox for a while and I haven’t heard any complaints. This means readers have either downloaded the source from Bit Bucket, synching the repository, or not downloading the source at all. In order to save me some time from now on, I will just post the source and related files to bit bucket. You can still download a ZIP file from the bit bucket interface.