The Topobase Insiders

Extending the Electric Explorer

Although the Topobase team may seem to have a god-like prescience anticipating functionality you might need, there may be the odd workflow or function that you feel could be added, improved or enhanced. For those rare occasions, the Topobase API provides a rich environment for customization. This post describes how to augment the functionality of the electric modules. The electric modules differ from other vertical modules in that in addition to a data model, workflows, reports etc. they have the Electric Explorer panel.

The Electric Explorer provides purpose-built functionality to manipulate conductors, ducts, devices etc. for convenience and data consistency.

In this sample, two context menu items are added to the Conductor container. The first merges the geometry of two conductors. Unlike the built in Merge Conductors function, it uses conductors selected in the Conductor container rather than requesting the user to select conductors from the graphics screen. This is useful if you don’t have cross sections displayed on every segment - to be able to pick conductors from.

The second added context menu item operates similar to dragging conductors from the Conductor container onto ducts in the Ducts container. Free standing conductors are assigned to (enclosed in) the ducts, but for this operation the conductor geometry is kept rather than changing it to follow the segment geometry. This provides the ability to have a semi-schematic type of drawing without resorting to a full-blown schematic.

For these menu items, the ‘hook’ into the Topobase system is – as usual – a PlugIn. This DocumentPlugIn monitors the ElectricExplorerDocumentFlyIn waiting for the FlyInInitComplete event. This event is raised after all the configured containers have been initialized. At that point a reference to the Conductor container can be obtained and the new context menu items added.

Adding to the Context menu involves passing an instance of a class to the container's ExtendMenu method. This class must have event handler methods tagged with a FeatureContainerContextMenuItem attribute as shown below. There are similar attributes for tagging New and More menu handlers.

[FeatureContainerContextMenuItem (
    "MergeSelectedConductors",
    "MergeConductorCaption",
    FeatureContainerNames.Conductor,
    TBGridViewContextMenuItemState.DelegateToHandler,
    DisplayIndex = 200,
    GroupName = "21Modify",
    ToolTipResourceName = "Merges selected conductors",
    IconNameEnum = IconNames.MergeConductors)]
public void MergeSelectedConductors (object sender, MenuItemEventArgs args)
{
...

This attribute has many options which are explained in the help system by pressing F1 in Visual Studio (if you've registered the API help). Of note, the second parameter is the name of a resource in the assembly resources rather than the caption for the menu item directly. This is so the menu item text can be localized by changing the resource associated with the name.

The TBGridViewContextMenuItemState parameter has a number of options that dictate when the menu item should be enabled or disabled. In this case it is set to DelegateToHandler which is slightly more complicated and needs some explanation.

With this option, the handler method is called two ways. The first way is identified when the MenuItemEventArgs.DeclareEnableStatus is set to true. In this case the method should set the MenuItemEventArgs.EnableMenuItem to true or false depending on whether the menu should be enabled or not respectively. The second way is when the method should actually do the work associated with the menu item. For example:

if (args.DeclareEnableStatus)
    args.EnableMenuItem = 1 < container.SelectedItems.Count;
else
    ... (do the needful)

This would enable the menu if there are at least two items selected in the container. Because this test is supposed to execute quickly so that the context menu appears immediately when the user right-clicks, it is best to leave difficult, deep or time consuming criteria tests to when the user clicks the menu item. Of course an error message is required in that case.

Once the user clicks the menu item, the actual work begins. For the Merge Selected Conductors operation, it is relatively straight forward to test if all the selected conductors form a continuous linear path with contiguous end points. If this is the case the new geometry is assigned to the first selected conductor and the others are deleted after any relations to ducts and segments have been redirected.

For the Associate Conductor operation, the operation is much simpler. The original geometry of the conductor is remembered, the out-of-the-box method to move conductors into ducts is called, and then the original geometry is restored.

This demo is available as a ZIP file which you can download using the link below. To build this project, define the environment variable TopobaseClientDirectory to point to the Topobase Client directory and execute the solution file:

C:>set TopobaseClientDirectory=C:\Program Files\Autodesk Topobase Client 2010
C:>ElectricExplorerExtension.sln

Build the solution. Run Topobase client, open an electric workspace and you should see the new menu items when you right click in the conductor container.

AUTODESK DOES NOT GUARANTEE THAT YOU WILL BE ABLE TO SUCCESSFULLY DOWNLOAD OR IMPLEMENT ANY SAMPLE CODE. SAMPLE CODE IS SUBJECT TO CHANGE WITHOUT NOTICE TO YOU. AUTODESK PROVIDES SAMPLE CODE "AS IS" WITHOUT WARRANTY OF ANY KIND, WHETHER EXPRESS OR IMPLIED, INCLUDING WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT SHALL AUTODESK OR ITS SUPPLIERS BE LIABLE FOR ANY DAMAGES WHATSOEVER INCLUDING DIRECT, INDIRECT, INCIDENTAL, CONSEQUENTIAL, LOSS OF DATA, OR LOSS OF BUSINESS PROFITS OR SPECIAL DAMAGES, THAT MAY OCCUR AS A RESULT OF IMPLEMENTING OR USING ANY SAMPLE CODE, EVEN IF AUTODESK OR ITS SUPPLIERS HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

Download ElectricExplorerExtension

Working with progress bars

This is the third post regarding the Feature History Administrator plug-in. In the previous two posts you could learn how to create a new DocumentAdminPage from scratch and then how to extend it with some logic. And as I have already mentioned, I was not happy how it has been implemented :-)

One important thing for a good user experience is when a process takes more than a few seconds the application has to inform the user about the progress. See also here for some background information about that. Showing the progress of a function has several benefits:

• the user sees that the software is still working (!),
• it shows where the process roughly is and
• it can also give a hint when the process will be finished.

So let's add a progress form to the Analyze() method. The class we can use is the StatusForm and it is located in the Topobase.Data.Util namespace. (There is also a ConsoleStatusDisplay which can be used when you have is a console application). The StatusForm can either act as an infinite progress bar, if you have no idea how long the process takes, or a 0% to 100% progress bar.

The StatusForm consumes a background job, so let's first create one:

 BackgroundJob<IList<FeatureClass>> job =
       controller.Analyze;
 StatusForm<IList<FeatureClass>> form = 
       new StatusForm<IList<FeatureClass>>(job);

The Analyze() method has to look like this: the first parameter is the StatusDisplay (to update the progress bar) followed by list of objects:

 public void Analyze(IStatusDisplay statusDisplay, 
       params IList<FeatureClass>[] parameters)

The StatusForm and its background job can be cancelable. In our plug-in we would like to let the user be able to cancel the process, so let's set the right property:

 form.CancelButtonEnabled = true;

We have to let the background job know which feature classes it has to analyze. Since it can't access the other properties from this class (cross-thread) we have to pass such information to the background job. Therefore we need to define it accordingly when we instantiate the StatusForm. In our example we need a list of Feature classes (StatusForm<IList<FeatureClass>>).

 // pass the list of selected feature classes
 // to the background job.
 form.SetParameters(this.SelectedFeatureClasses);

 // show the progress form,
 // this method starts the background job
 form.ShowDialog(this);

After calling the ShowDialog method the background job is started in a new thread. The GUI thread is now paused until the background job has finished.

If you take a look at the updated sample you will notice that I moved the Analyze() method to a new class called Controller. This is not necessary for the StatusForm, but I thought it would make sense to extract the logic from the UI and also improve the overall readability. Like the previous DocumentAdminPage samples this one is also written in C# and compatible with the official Topobase 2010 version.

Download project (16.1K)

Feel free to contact me for any questions or comments about this sample.

AUTODESK DOES NOT GUARANTEE THAT YOU WILL BE ABLE TO SUCCESSFULLY DOWNLOAD OR IMPLEMENT ANY SAMPLE CODE. SAMPLE CODE IS SUBJECT TO CHANGE WITHOUT NOTICE TO YOU. AUTODESK PROVIDES SAMPLE CODE "AS IS" WITHOUT WARRANTY OF ANY KIND, WHETHER EXPRESS OR IMPLIED, INCLUDING WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT SHALL AUTODESK OR ITS SUPPLIERS BE LIABLE FOR ANY DAMAGES WHATSOEVER INCLUDING DIRECT, INDIRECT, INCIDENTAL, CONSEQUENTIAL, LOSS OF DATA, OR LOSS OF BUSINESS PROFITS OR SPECIAL DAMAGES, THAT MAY OCCUR AS A RESULT OF IMPLEMENTING OR USING ANY SAMPLE CODE, EVEN IF AUTODESK OR ITS SUPPLIERS HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

Four Color Themer

This post falls under the frivolous "pretty maps" category.

Most political area maps are colored arbitrarily so that no two adjacent regions have the same color.

Although you can easily change your schema and make a theme based on the data values of a feature class, e.g. a "COLOR" attribute, there isn't an easy way to assign these color values. You could edit each feature and set the color value, but most programmers will go to extraordinary lengths to avoid such manual labor.

So instead we turn to automated methods. There is quite a body of literature regarding map coloring. The four color theorem says that any planar map can be colored so that no two adjacent regions have the same color by using just four colors. The algorithms for four coloring a graph (the mathematical abstraction used to represent areas of a map) are quite complex and coding an algorithm such as the one described in Efficiently four-coloring planar graphs again begins to look too much like work to a lazy programmer.

So we now turn to less rigorous but easier methods to color a map. The method illustrated here is to randomly color each region so that it doesn't conflict with its neighbors. This won't always generate a four color map, but most published maps use five or more colors anyway.

We can get Oracle to do most of the heavy lifting in generating the connectivity graph of the map regions - which basically describes what is adjacent to what. A simple query using SDO_RELATE with the mask set to ANYINTERACT will quickly find all pairs of regions that touch in any way. To eliminate regions that only touch at their respective corners, requires resorting to a small trick however. Regions that touch only at corners will have a common boundary with a length of zero.

This length can be computed by using SDO_LENGTH to compute the perimeter of the intersection between the two geometries, which can be obtained with SDO_INTERSECTION.

The program code can easily ignore connectivity between regions with a zero length intersection perimeter, and doesn't need to read the data in any particular order, so the query can look like this (where <feature_class_name> is the name of the class to join with itself):

select a.fid fid1, b.fid fid2,
sdo_geom.sdo_length (sdo_geom.sdo_intersection (a.geom, b.geom, 0.000001), 0.000001) len
from <feature_class_name> a inner join <feature_class_name> b
on sdo_relate (a.geom, b.geom, 'mask=anyinteract') = 'TRUE'

After setting up the data structure containing the connectivity, each region is processed by asking it what colors are allowed based on the colors of its neighbors. If there are many, choose one at random. If there is only one allowed, use it. In the case that no colors are allowed because adjacent neighbors have used all the colors, leave it unassigned and process it on a subsequent pass with one more color in the palette.

The colored graph could then be used to assign a "COLOR" attribute of each feature if you know or can adjust the schema, but for demonstration purposes, one can set up a layer with multiple filters of the form:

fid in (fid1, fid2, fid3, ...)

where each of the fid values is the same color. This works well for hundreds of regions, but gets a little sluggish with tens of thousands.

This demo is available as a ZIP file which you can download using the link below. You will need an accurate polygonal data layer with adjoining regions - like a map. To build this project, define the environment variable TopobaseClientDirectory to point to the Topobase Client directory and execute the solution file:

C:>set TopobaseClientDirectory=C:\Program Files\Autodesk Topobase Client 2010
C:>FourColor.sln

Build the solution. Next create a workflow called FourColor in Topobase Administrator containing the script:

Sub Run
  Me.RunMethod("FourColor.dll", "FourColor.FourColorWorkflow", "Color")
End Sub

Run Topobase client, generate graphics (required to get a template layer definition) and execute FourColor from the Workflow explorer. Select one of the polygonal layers from the list and click the Color button to generate a four color layer. If you get five colors and want four instead, you can repeat the color operation, which replaces the current coloring.

AUTODESK DOES NOT GUARANTEE THAT YOU WILL BE ABLE TO SUCCESSFULLY DOWNLOAD OR IMPLEMENT ANY SAMPLE CODE. SAMPLE CODE IS SUBJECT TO CHANGE WITHOUT NOTICE TO YOU. AUTODESK PROVIDES SAMPLE CODE "AS IS" WITHOUT WARRANTY OF ANY KIND, WHETHER EXPRESS OR IMPLIED, INCLUDING WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT SHALL AUTODESK OR ITS SUPPLIERS BE LIABLE FOR ANY DAMAGES WHATSOEVER INCLUDING DIRECT, INDIRECT, INCIDENTAL, CONSEQUENTIAL, LOSS OF DATA, OR LOSS OF BUSINESS PROFITS OR SPECIAL DAMAGES, THAT MAY OCCUR AS A RESULT OF IMPLEMENTING OR USING ANY SAMPLE CODE, EVEN IF AUTODESK OR ITS SUPPLIERS HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

Download FourColor