Tutorial: Making a Mapset

Overview

This lesson teaches you how to place point graphics on a map by reading in data from an external source and matching it to existing items on the map using find item lookups. “Putting dots on the map” is the first step for even the most sophisticated map application. (4.4.7)

This tutorial is part of the [[Course: Partner Workbench]].

audience

  • system administrators and IT staff
  • power users
  • developers

objectives

  • work through a real-life example which provides a geographic view of tabular data
  • learn about mapsets, frontends, legends, and styles

prerequisites

You need a working Partner installation and basic familiarity with the Workbench. We’ll use the data input file and code from [[Tutorial: Scripted Data Input]]; that and its prerequisites should give you everything you need.

Note: Starting the Map Viewer in the Workbench

Whenever we tell you to start or restart the Map Viewer, don’t do so from your desktop icon or shortcut. Instead, do so from the Workbench/Start Map Viewer menu item in the Workbench. When the Map Viewer is started from the Workbench, the two talk to each other and allow additional functionality.

Generally, don’t restart the Map Viewer (e.g. from Preferences, or Update, etc.) using the normal mechanisms; instead just close the Map Viewer window, then select the Workbench/Start Map Viewer menu item again.

A Real-Life Example

We should start first by giving credit to a good customer and friend, Bob Slezak at UGI, Inc. in Wilkes-Barre, Pennsylvania. This example was inspired by a real application of Bob’s.

UGI, like many of our customers, is a utility, and the division Bob works for is the electric distribution side. Electricity is generally carried on wires supported by poles, and a variety of things can happen to those poles that keep them from doing their job of holding the wires off the ground. One type of accident is when the pole is hit by a car or other vehicle; doubly unfortunate because both the driver and the pole may be damaged by the accident.

While any pole within reasonable distance of a road could conceivably be hit, some poles are more at risk than others. For example, a pole on the apex of a poorly-banked curve may be more likely to be hit, or one that is too close to the road. Analyzing poles with a history of accidents could help the utility mitigate the problem by moving problem poles to safer spots. And, of course, since often the geographic location of the pole is crucial in this analysis, showing them on the map makes the process much easier.

As is often the case, our data source does not have the geographic locations of the poles. Instead, we simply have a pole number and a hit count. Luckily, we can use the Partner platform’s Find Item facility to locate poles using their number, then place icons indicating the problematic ones on top of those poles.

So, our nutshell requirements are this:

  • read a data file containing pole numbers and hits
  • create and place point entities using find-item lookups of the pole numbers
  • view the problem poles via distinctive icons on the map
  • view the data for a problem pole by clicking on the icon
  • see a list of poles and go to specific ones with a custom find item

Mapsets Explained

A Mapset is an object-oriented application layer in the Partner Map Viewer. It can contain:

  • data import frontends
  • find items
  • menu items
  • wheel menu behavior
  • tools
  • scripts
  • libraries
  • legends
  • styles

The most visible part of a mapset is the map data layer shown on the map. This can be turned on and off independently from other mapsets, and has its own distinct graphic types and data types. Selecting visible graphics allows you to see the data for them and interact with them using the wheel menu. [[Image:DynamicDataPanel.png|none|frame|The data panel and wheel menu will display data and options based on the selected item.]]

There are three major types of mapset:

  • Image mapsets are built from raster images such as aerial or satellite photography
  • Static mapsets are generated using the Map Translator batch process from large GIS or CAD data sources
  • Dynamic mapsets are generated on-the-fly by reading external data into the map viewer itself and converting it to map data

You can see the available mapsets by looking in the Preferences editor (menu Platform/Preferences), and you can see the loaded mapsets by looking in the Contents menu (menu View/Contents/). Only mapsets that are both loaded and checked in the Contents menu will be visible. [[Image:Preferences.png|none|frame|Mapsets must be selected in both the preferences menu and in View/Contents in order to be visible in the map viewer.]]

While mapsets are largely independent of each other, they can interact with other mapsets. In this case we are going to base our mapset on pole locations provided by the static Background mapset.

Mapsets are stored in any of the config/* directories, under the subdirectory mapsets and then with a directory with the same name as the mapset. For example, the Drawing mapset is found in config/customer/mapsets/Drawing/. [[Image:DrawingMapset.png|none|frame|Mapsets can be found in the config directory. The Drawing mapset is modular, see below.]]

Mapsets can be modular; this means that they use code and default files from a module. In this case you may find parts of a mapset in both config/ and modules/ hierarchies. Compare the contents of config/customer/mapsets/Drawing/ with modules/customer/Drawing/mapsets/Drawing/ to get a feel for what this means. [[Image:DrawingModule.png|none|frame|Modules can be found in the modules directory.]]

Translator frontend scripts go in the subdirectory translator/frontends/ under the mapset’s home directory. You can have any number of scripts, with any name you like. They will be run in alphabetical order during mapset refresh. [[Image:FrontendPlacement.png|none|frame|The frontend scripts are placed as shown.]]

Placing Data Using Find Item Lookups

Sometimes our input data will have geographic coordinates, generally in feet (easting and northing) or degrees (longitude and latitude).

More often, however, our data does not have geographic coordinates, but can be placed on the map by referring to something else that’s already there. That is the case with our pole hit data.

We’ll show you how the code works below, but when planning a mapset, you can perform a manual test to see if your data matches up with a find item.

In the Map Viewer, click the Find tab and examine the Type drop box for a list of find items that are available to you. [[Image:AvailableFindItems.png|none|frame|A list of available find items.]]

Double clicking a find item selects the corresponding map data item in the map view panel. Select the Data tab to see the data fields and values for the found item. [[Image:DatatypeFields.png|none|frame|Fields belonging to the selected map data item.]]

We’ll use the find item named “Pole Tag Number” in our example. Select it and try the following pole numbers to be sure they can be found:

  • 15926
  • 54859
  • 47507

Time To Dots

OK, enough planning already. Let’s see how quickly we can get our data into the map as visible icons.

Data File

We’ll use the same data file we used in the previous [[Tutorial: Scripted Data Input]]. It should still be there if you ran through that tutorial.

data/Tutorial/PoleHits.csv

pole,hits
15926,3
15730,5
15563,1
27699,4
54859,6
47507,2

Mapset

Now we need to create a mapset. Select the directory named config/ and create a subdirectory named seat/ if there isn’t one there already. In config/seat create a subdirectory named mapsets/ and select it. There should be a “Mapsets” editor tab for this directory. Click the “New Mapset” link and type in “Pole Hits” (yes, spaces are OK). It will create the directory for you. Select it, and make the “Mapset” tab active. You will see a list of standard directories and a “make” link for each to create it. [[Image:MapsetTab.png|none|frame|The Mapset tab offers various standard options.]]

Frontend Script

We’ll steal some code from [[Tutorial: Scripted Data Input]], but we need to put it in a translator frontend script. From the “Mapset” tab, click the “make” link next to translator/frontends, then click the link for that directory. Create a new file named “PoleHits.groovy” and copy the following into your file:

config/seat/mapsets/Pole Hits/translator/frontends/PoleHits.groovy

import com.partnersoft.system.SystemServices;
import com.partnersoft.formats.csv.CsvDataRecordSource;

file = SystemServices.vfs().fileFor("data/Tutorial/PoleHits.csv");
source = new CsvDataRecordSource(file);
for (record in source) {
    pole = record.get("pole");
    hits = record.get("hits");
    log.info("Read record: " + record);
    log.info("Pole = " + pole);
    log.info("Hits = " + hits);

    // add point to mapset
    graphicType = "Pole Hits";
    dataType = "Pole Hits";
    translator.placePointsUsingFindItem("Pole Tag Number", pole, dataType, graphicType, record);
}
source.close();

A close look at the script above will reveal that the “Pole Tag Number” is used as the first parameter in the translator.placePointsUsingFindItem() method. This is not a value we provided in our csv, but rather is the name of the Find Item index that contains background map poles, as defined in the translator and visible in the “Find” tab of the Map Viewer. This is a key point, since we never provided any type of coordinates for placement on our map.

Instead, placePointsUsingFindItem() allows the software to look up coordinate locations for poles by searching for them by number in the “Pole Tag Number” Find Item index. It then places new point shapes at those locations with our new types and data.

Enabling and Refreshing the Map Set

Now we need to start the Map Viewer and configure the legend.

Go to the Workbench menu, and click Start Map Viewer. This will launch the Map Viewer within the Workbench environment. In this mode, the Map Viewer will interact with the Workbench, and you can make changes in your mapset and apply them immediately to what you see in the Map Viewer without restarting.

Your map set must be enabled for loading. This is done automatically if you used the “new mapset” link in the mapsets edit tab, but not if you created your mapset using the plain old directory tools. To enable for loading, in the Map Viewer click the menu Platform/Preferences and make sure the Pole Hits mapset is checked. Apply the changes but don’t restart using that button - instead, close the window, close the Map Viewer window, then restart the Map Viewer from the Workbench using the Workbench/Start Map Viewer menu item.

Your map set must also be visible in contents. This is done with the menu View/Contents/. In that submenu you should see Pole Hits, click it so that it is checked and it should now be marked as visible. [[Image:Preferences.png|none|frame|Note that in the above image Pole Hits are not enabled in the View/Contents menu. Go ahead and click Pole Hits to make them visible.]]

However, you won’t have any data until the frontend script is run by a refresh. You can do this in one of two ways: via the menu item View/Refresh All, or by going to the Workbench and clicking the “Run” button. The Workbench will automatically detect if a script is a mapset frontend and will refresh the mapset. This allows you to edit and debug your mapset frontend in the Workbench without having to constantly go back to the Map Viewer. [[Image:Refresh.png|none|frame|Refreshing from within the map viewer.]] [[Image:RunRefresh.png|none|frame|Refreshing from within the workbench.]]

After refreshing, you won’t see any new points, but you should see the following message in the Workbench log view:

warn : Invalid point graphic type: point-Pole Hits - you probably need to add it to your legend.

So... let’s add it to our legend. Go to legends/default.xml in your mapset.

A nice feature of the workbench is the xml editing interface. You can view the legend in XML format, with syntax highlighting, using the XML tab. [[Image:XmlInTextTab.png|none|frame|Color coded xml in the Text tab.]]

However, a more user-friendly form-based interface is also available on the Legend tab. This form helps ensure that your configuration is valid, and it helpfully adds new graphic types (like our point-Pole Hits type) to the list for configuration. [[Image:XmlGUI.png|none|frame|Easy xml editing via the Legend tab.]]

Right now the point-Pole Hits field has an empty drop box. This means that there is no style assigned to our points, so they are not shown and we get the “Invalid point graphic type” warning. Available point styles are provided in a picklist selector to the right of the graphic type; clicking the selector shows the available options. Since the only point style we currently have defined is “default”, you must choose between “default” or nothing. Choose “default” and then click the Apply button.

Dots!

Go back to the map viewer, and refresh your mapset via the View/Refresh menu. Your points should appear as red dots on the map.

[[Image:DotsOnTheMap.png|none|frame|Now the map will display the red dots at the poles’ locations.]]

If you select one of the dots by clicking on the map, the Data tab will display the data specific to that pole. The data that is displayed corresponds to the selected find item, in this case Pole Hits.

When the Map Viewer is running from the Workbench, a Workbench tab is added next to Data, Find, and Edit. This displays under-the-hood details about selected items, such as which mapset they came from, what their data ID is, and what style they are assigned to at the current scale. This tab is under heavy development at the moment so we’ll defer documentation until later.

Adding a Dynamic Find Item

Find items allow you to quickly look up map data items using the values from one or more data fields.

While most Find Item indexes are created by the Map Translator for your background map data, you can also have “dynamic” Find Item indexes that are generated from your dynamic mapset. We can create one that works with our “Pole Hits” data instead of just listing and selecting background map data.

At the moment, there is no user-friendly form for find item configuration. It’s a straightforward XML file, however.

Create a new directory named finds in your mapset’s translator/ directory. There is a quick link on the mapset editor tab for this, or you can just create it using the normal directory tools. [[Image:EasyFindsDirectory.png|none|frame|Easy finds directory creation. Note that the Pole Hits mapset is selected and the Mapset tab is the active tab.]]

Then, create a file named Pole Hits.xml in that directory and put the following into it:

config/seat/mapsets/Pole Hits/translator/finds/Pole Hits.xml

<?xml version='1.0' encoding='US-ASCII'?>
<cog>
  <FindItemIndex name='Pole Hits'>
    <Boolean name='includePoints'>
      true
    </Boolean>
    <Boolean name='includeLines'>
      false
    </Boolean>
    <Boolean name='includeText'>
      false
    </Boolean>
    <Naming-of-List-of-String name='sources'>
      <List-of-String name='Pole Hits'>
        <String>pole</String>
      </List-of-String>
    </Naming-of-List-of-String>
  </FindItemIndex>
</cog>

It’s a bit wordy, but the important thing to understand is that, in the “sources” section, we are using the “pole” field from the “Pole Hits” data type. The data type and value for “pole” are set in the frontend script we edited above. The data type will be displayed at the top of the data panel when this type of item is selected.

The name of the file, also “Pole Hits”, will be used as the name of the new find item we are creating.

Refreshing runs the frontend and refreshes both the shapes in your mapset and any entries in find item indexes.

Restart the Map Viewer, and Refresh your mapset. Go to the Find tab and select the “Pole Hits” find item. You should see a list of all the pole numbers from the Pole Hits data file. Double-click one to select it and ensure it is visible in the map view. Switch to the Data tab to see the associated data for the item.

[[Image:Finds.png|none|frame|The Pole Tag Numbers are now visible.]]

Summary

You now have the basics of loading external data records and associating them with existing background map data with cute symbols. This is a starting point for 90% of applications in the Partner system.

Moving On

Read-only map data is fine, but you get to modify it in Tutorial: Editable Mapset.