The Topobase Insiders

Trace Grabber

One request that has come up a few times has to do with the use-case of performing a trace and generating a report from the results. For example, this capability would be used to generate mail-merge letters for clients affected by a planned outage.

There are a couple of ways of doing this, both involving a little programming. One way is to generate a Report PlugIn that performs the trace to generate an in memory table against which the report would be run. Unfortunately, this would mean writing a plugin for each trace type required, effectively requiring a re-writing or encapsulation of the existing trace workflow. Another way, and the topic of this post, is to capture the trace results from any trace to a table in Oracle that the report can be run against.

To make the table idea work correctly in the face of a multi-user environment, the trace results would need to be written to a different table for each user, or the table would need user specific fields for each record, or we could take advantage of a cool Oracle capability - a temporary table. A global temporary table is permanent, but the data in it is maintained only for the session, and visible only to the session. This means, each user sees only their own data and the data is erased when the session is disconnected. Perfect.

Even though the full feature data is available in the trace results, it is sufficient to save only the feature ID and the feature class ID in each result row. The report can then retrieve what it needs to write the report - it might not need or want all traced features for example. So, the temporary table creation SQL is:

create global temporary table trace_results
    (fid number(10,0), f_class_id number(10,0))
    on commit preserve rows

which of course only needs to be done once per document.

The real trick is to somehow get hold of the trace results. Start with a DocumentPlugIn and set up a button on the Main Toolbar for the user to press when they want to copy the trace results to the trace_results table. When the button is pressed, access the WorkflowUserPanelDesktop by cycling through the controls in the WorkflowExplorerDesktopFlyIn. From there, access the GeneralWorkflowContainerDesktop that has the trace results in the NetworkTraceResultFeatureExplorerData object in its DataList. It's OK, you probably don't have to understand.

This NetworkTraceResultFeatureExplorerData is the one that has the result features, unfortunately they are inaccessible, since there is no public accessor for them. But, by using reflection the value of the field holding the result list can be obtained. Given the list of features, it's a simple matter to insert the FID and FeatureClass.ID of each element in the list. The supplied code uses array inserts in case there are a lot of features. The Topobase Administrator Report Designer can now be used to create a report that accesses the records in the table.

To use the program, copy the TraceGrabber.dll and TraceGrabber.tbp file to the Topobase Client bin directory. Start Topobase Client and generate graphics. Expose the Main Toolbar by right clicking on the document in the Topobase Explorer and choosing it from the Toolbars submenu of the context menu.

Perform the desired trace, e.g. Find Connected, from the Workflow Explorer. Click on the Trace Grabber buttton. The trace results will be copied to the TRACE_RESULTS table. Use the Report Designer to create your report based on the TRACE_RESULTS table. It's a bit disconcerting because the Topobase Administrator will be using a different session connection and therefore can't see the results, but when the client runs the report it will work.

Of course, source code is supplied, so you can add code that automatically spawns the report when the button is pressed, avoiding the two step process of pressing the button and then running the report. A silly little default report is also included as an example.

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 TraceGrabber for Topobase 2010
Download TraceGrabber for Topobase 2011

Enhanced Stylization - Line Styles

The cartographic stylization engine in Topobase provides far better line stylization than AutoCAD can provide. For example, instead of just a single line with a pattern, thickness and color, you can have multiple lines of various thicknesses, with various embellishments and different joining and capping options. So, if you forgo fidelity when exporting data to a .dwg, you can take advantage of some excellent capabilities for line symbolization.

It is assumed that you have added layers using enhanced stylization, or set up the layer templates as described in Annotation Layers to automatically use enhanced stylization.

Start with a couple of standard line styles, one for a gas pipeline and one for a railway. These are standard linestyles that can be found in acad.lin, the AutoCAD line pattern definition file. They are named GAS_LINE and TRACKS respectively. Each has been given a little line thickness and a color. To be clear, what is shown in the image to the right are not AutoCAD lines, but rather linear features that have been symbolized to look like AutoCAD lines. There are discrepancies; for example, AutoCAD would not thicken the 'GAS' text when a polyline is given a width.

To put some context to these explorations, let's vary one thing at a time, starting with the geometry for the gas line. Let's say you wanted two parallel lines to run unbroken along each side of the linestring. If you open the pipeline layer file with a text editor you will see something like this (after formatting):

...
<SimpleSymbolDefinition>
  <Name>GAS_LINE</Name>
  <Graphics>
    <Path>
      <Geometry>M 6.5,0 l 0.166666666666667,0 M 6.66666666666667,0 ... </Geometry>
      <LineColor>%LINECOLOR%</LineColor>
      <LineWeight>%LINEWEIGHT%</LineWeight>
      <LineWeightScalable>false</LineWeightScalable>
    </Path>
    <Path>
      <Geometry>M 0,0 L 5,0 </Geometry>
      <LineColor>%LINECOLOR%</LineColor>
      <LineWeight>%LINEWEIGHT%</LineWeight>
      <LineWeightScalable>false</LineWeightScalable>
    </Path>
  </Graphics>
  <LineUsage>
    <Repeat>9.5</Repeat>
  </LineUsage>
...

The <Geometry> element for the paths are a bunch of M (move to) and L (line to) operations as described in Enhanced Stylization - Flow Direction, with the added caveat that lower case L means the target coordinates are relative to the current location.

The first <Path> element, the complicated one, draws the 'GAS' text and the second <Path> element draws the lines between the text. As I said, this is only an approximation to the linetype in the acad.lin file, so the 'GAS' text is drawn with a whole lot of little segments, and not an embedded shape like in the AutoCAD line style.

The symbolization basically draws a line from 0,0 to 5,0 (the second <Path> element) and then draws a few lines that look like the word 'GAS' within a bounding box of approximately 6.0,-0.5 to 8.6667,0.5 (the first <Path> element), and then repeats the whole process at 9.5 unit intervals (the <Repeat> value). So to draw parallel lines above and below the 'GAS' text, one would have to offset them more than 0.5 units, say 0.7 units, and to make them look continuous they would need to be 9.5 units long, so that the repetition by the next symbolization will join with the first.

Thus, we modify the second <Path> <Geometry> element to be two lines:

      <Geometry>M 0,0.7 L 9.5,0.7 M 0,-0.7 L 9.5,-0.7</Geometry>

which gives the result shown to the right.

If you're not happy with the font of the 'GAS' text either (really, who uses STANDARD text anymore), you can replace the drawn text with a real piece of text. The <Text> element has a lot of options. You will need a <Content> element with the word 'GAS' in it and a <FontName> element with a valid font name like 'Swiss 721 Black BT'. The available font names can be obtained from the list shown in the Windows Control Panel by double-clicking the Fonts icon.

Beyond that, to emulate the existing style we will need a <Height> element to set the height to 1.0, and <PositionX> and <PositionY> elements to set the position. The default horizontal alignment mode is Center and the default vertical alignment mode is Halfline, so the necessary position coordinates are 7.33335,0.0 (in the middle of the bounding box of the original text). To set the font color to be the same as the line color, add a <TextColor> element with a value of %LINECOLOR% so that setting the line color also sets the text color.

So the first <Path> element is replaced with:

<Text>
  <Content>'GAS'</Content>
  <FontName>'Swiss 721 Black BT'</FontName>
  <Height>1.0</Height>
  <PositionX>7.33335</PositionX>
  <PositionY>0.0</PositionY>
  <TextColor>%LINECOLOR%</TextColor>
</Text>

which gives the result shown to the right.

If the 'GAS' text repeats too often, the repeat interval can be extended, say to 20, but then the path elements for the (parallel) lines and probably the position elements for the text would also need to be altered.

Turning now to the railway line style, if we wanted to have the symbolization look more like train tracks, we could also change the single central line to a double parallel line as above. Opening the railway layer file you find symbolization like this:

<Graphics>
  <Path>
    <Geometry>M 1.5,0 l 0,2.5 M 1.5,0 l 0,-2.5 </Geometry>
    <LineColor>%LINECOLOR%</LineColor>
    <LineWeight>%LINEWEIGHT%</LineWeight>
    <LineWeightScalable>false</LineWeightScalable>
  </Path>
  <Path>
    <Geometry>M 0,0 L 1.5,0 M 1.5,0 L 3,0 </Geometry>
    <LineColor>%LINECOLOR%</LineColor>
    <LineWeight>%LINEWEIGHT%</LineWeight>
    <LineWeightScalable>false</LineWeightScalable>
  </Path>
</Graphics>
<LineUsage>
  <Repeat>3</Repeat>
</LineUsage>

The first <Path> element draws the railway ties 2.5 units to left and right, while the second <Path> element draws the central line (actually in two segments, but this is redundant). So, let's change the central line to be two parallel lines offset by 1.9. Then the second path <Geometry> element becomes:

<Geometry>M 0,1.9 L 3.0,1.9 M 0,-1.9 L 3,-1.9</Geometry>

which gives the results on the right.

Although it's possible to increase the line thickness so that the railway ties look like railway ties, this would also thicken the railway rails. To get thick railway ties without thick rails one can change the geometry of the first path to outline the ties as rectangles with a thickness of 0.6:

<Geometry>M 1.2,0 l 0,2.5 l 0.6,0 l 0,-5 l -0.6,0 Z</Geometry>

The result is shown to the right.

To fill the outline though, a few more tricks are required. First, a <FillColor> element must be added to the path for the railway ties, so the final <Path> element is as follows:

<Path>
  <Geometry>M 1.2,0 l 0,2.5 l 0.6,0 l 0,-5 l -0.6,0 Z</Geometry>
  <LineColor>%LINECOLOR%</LineColor>
  <LineWeight>%LINEWEIGHT%</LineWeight>
  <FillColor>%FILLCOLOR%</FillColor>
  <LineWeightScalable>false</LineWeightScalable>
</Path>

Then the FILLCOLOR parameter must be itemized in the <ParameterDefinition> element. This <Parameter> element can be copied from a point layer that already has this element.

<Parameter>
  <Identifier>FILLCOLOR</Identifier>
  <DefaultValue>0xffffffff</DefaultValue>
  <DisplayName>&Fill Color</DisplayName>
  <Description>Fill Color</Description>
  <DataType>FillColor</DataType>
</Parameter>

Finally, in order to be able to set the parameter from the Style and Label Editor user interface, the <ParameterOverrides> element needs to have an additional <Override> element to set the fill color for the linestyle:

<Override>
  <SymbolName>TRACKS</SymbolName>
  <ParameterIdentifier>FILLCOLOR</ParameterIdentifier>
  <ParameterValue>0xFFFF0000</ParameterValue>
</Override>

The results are shown to the right.

At this point you can click on the Expression builder for the FillColor parameter and create an expression to stylize the fill color value of the ties. For example you might want to theme the ties based on material. The expression shown on the right would provide that. The LOOKUP function has a first parameter of the attribute to use (TIE) and a second parameter of the default (0xFFFF0000) color. Note that the color format is 0x to indicate a hexadecimal value followed by two hexadecimal characters for each of alpha, red, green and blue values. So, in this example, the first FF indicates a fully opaque alpha, and the second FF is full red, and the following two pairs of zeros indicate no green or blue, so the color is red like the outline lines. The rest of the parameters to LOOKUP are index and value pairs. In this case, if the TIE attribute is 'Concrete' then use 0xFF00FF00 (full alpha, no red, full green and no blue), and if it is 'Wood' then use 0xFF0000FF (full alpha, no red or green and full blue) - green for concrete and blue for wood. By setting the alpha values to smaller values (e.g. 77) you can get transparent fills. The point symbol in the images in this post has a value of CC for alpha.

This is the symbolization for wood ties:

The resulting layer files are available for download, in case they might be useful as an example.

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 Sample Display Model

Enhanced Stylization - Bitmap Symbols

MapGuide Studio, the MapGuide authoring environment, has the capability to create symbols that use bitmaps, but there is no corresponding capability in Topobase. There is, however, a way to manually create layers using images as symbols.

To start with, you'll need a .png file with 32 bit depth. You can check the bit depth of an existing file by right-clicking on the file in Windows Explorer and viewing the properties. There, in the Details tab of Vista or the Summary tab of XP, the bit depth will be listed as either 8, 24 or 32 bits. If you don't already have a .png format file or it isn't 32 bits, you can use any one of many programs to edit it, for example Paint.Net, but unfortunately you can't use the Paint program that ships with Windows as that will only create 24 bit .png files.

To be able to place the image into an XML layer file, which is only text, the image file needs to be converted to text. For this, the Base64 encoding is used. Of course you could convert an image to Base64 by hand, but it's much easier and faster to write a program to do it. The tiny program supplied below does just that.

It is a command line program that takes as arguments the name of the file to encode and the name of the text file that will be produced. For example, if you are converting the file Wikipedia-logo.png to Wikipedia-logo.txt the command would be:

Base64Encoder Wikipedia-logo.png Wikipedia-logo.txt

Now for a little text editing. Start by creating a layer of a point feature class using enhanced stylization. Style the layer to set the size context to Map and adjust the width and height to get the desired size. Apply the stylization. Right-click on the layer in Display Manager and choose Save Layer... to create the XML file.

Edit the saved .layer file with a text editor and replace all references to the name Circle to something more meaningful. Next, remove the contents of the <Graphics> element, i.e. remove from <Path> up to the </Path>, and replace this Path element with an Image element. The <Image> element must contain a <Content> element. The <Content> element contains the text produced by the Base64Encoder program. The Base64 encoding for a converted .png file will start with the letters iVBOR and be rather substantial in size, so the bulk of it is replaced by ellipses in the following example:

<SimpleSymbolDefinition>
<Name>Wikipedia</Name>
<Description>Wikipedia Logo</Description>
<Graphics>
<Image>
<Content>
iVBOR...
...        this is the rather large output from the Base64Encoder program
...CYII=
</Content>
</Image>
</Graphics>

As described in the OsGeo documentation, you can also add SizeX and SizeY elements to specify the size of the symbol in millimeters, an Angle element to specify the rotation angle of the image, and PositionX and PositionY elements to specify the image center in millimeters within the symbol. Of course these can be parameterized if desired.

Now you can drag and drop your edited layer file into the Display Manager or add your layer to a Display Model and you should see your point features represented as your image symbols.

Note: If you have areas in the image that should allow the background color to show through, i.e. the alpha or transparency value of those pixels is zero, then you must use Topobase 2011 as this is not supported in Topobase 2010.

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 Base64Encoder