Introduction
More than ever, developers are being required to add feature rich maps into their new or existing applications. This sort of thing can be daunting. Not just from the standpoint of rendering maps visually, but the GIS expertise alone that is needed can make enhancements of this nature cost prohibitive. With Map Suite it is easy and you don't need a degree in GIS.
Register and download the trial version
(Note: This paper covers the Winforms Edition of Map Suite but most of the concepts and all of the example code is the same for the Webforms (ASP.NET) version as well.)
Your First Map
After you have downloaded and installed the trial version of Map Suite, open Visual Studio.NET, create a new Windows Application and add the Map Suite Map Control to your Toolbox. You can do this by using the Add/Remove Items feature and browsing to the winformsedition.dll file that resides in the installation directory of Map Suite. (By default this is C:\Program Files\Spatially Aware\[The Version Installed]\). Once you have that added you can simply drag and drop a new Map Control onto the Windows Form and you are now ready to create a map. Using the sample data for Mexico that installs with Map Suite, we can quickly create a new Map and let Map Suite render using its defaults. The below code is implemented in the Form's Load method:
Private Sub Form1_Load(ByVal sender As System.Object, _
ByVal e As System.EventArgs) Handles MyBase.Load
Map1.Layers.Add(New MapSuite.Layer( _
"C:\Program Files\Spatially Aware\[YOUR MAPSUITE VERSION]\SampleData\Mexico\
states.shp"))
Map1.Refresh()
End Sub
(Note: The data used by Map Suite is ESRI Shape File format data which includes a vector .shp file, and index .shx file and a data .dbf file. All three are used to help render shapes of the map and provide related data. More information about Shape Files can be found here.)
If you compile the code and run the sample, you will see a map that is the states of the country of Mexico. Notice that Map Suite picked an arbitrary color and if you stop and run the application again you will see another random color. That is because you have not told Map Suite how to render the Layer you have just created so it decides on its own what colors to use.
Thresholds and Symbol Renderers
To get the map to render the way you want it to you can use Thresholds and Symbol Renderers. A Threshold is the viewable distance across from left to right. To understand this better, imagine a glass bottom elevator and what you might see in the viewable area of the floor as you move up and down over an area of the earth. As you move up or away, you can see more of a particular area and in less detail. As you move down or closer, you can see less of an area but it shows greater discernible detail. Thresholds can be defined to have an upper and lower extent defined so that they know when to render certain features of the map. A Symbol Renderer tells the Threshold how to render, for example a blue border and yellow fill. More on Thresholds and SymbolRenderers in a bit.
Map Units and Threshold Units
For the map's Thresholds to work properly, it is important to understand the units of measurement that your map is in. While this is easy to do, if not set properly it can cause your map to render unpredictably or not at all. Let's use the Mexico Shape File as an example. The map unit for a shape file is usually one of three units of measure: Decimal Degrees, Meters or Feet. Our Mexico shape file is in Decimal Degrees so we will set the MapUnit property accordingly:
Map1.MapUnit = Geometry.MapLengthUnits.DecimalDegrees
Once this is set correctly, we can now work in the measurement we are comfortable with, say Miles and Map Suite will automatically provide the correct conversion as we are using Thresholds and other functionality such as Spatial Querying.
The next step is to declare a Layer to add to the Map so we can set some properties:
Dim mexicoLayer As New Layer( _
"C:\Program Files\Spatially Aware\[YOUR MAPSUITE VERSION]\SampleData\Mexico
\states.shp")
Now let's create a Threshold to control the look of our Layer and when it is to be rendered. Remember that our Threshold is going to tell us at what extent it should be shown. Create a new Threshold and provide it an upper and lower values in the constructor:
Dim mexicoThreshold As New Threshold(2100, 0)
Now you need to provide information about how Map Suite should render the map. This is where the SymbolRenderer comes in. A Threshold has a collection of SymbolRenderers. Let's add a new one that makes our border blue and the filled in area yellow:
mexicoThreshold.SymbolRenderers.Add(
New SymbolRenderer(New AreaSymbol(New Pen(Color.Blue),
New SolidBrush(Color.Yellow))))
In the code above, a new SymbolRenderer is added to the SymbolRenderers collection of the Threshold. In the constructor you can pass in a BaseSymbol. The BaseSymbol class is the super class for AreaSymbol (Polygons), LineSymbol(Lines) and PointSymbol(Points). Since the Mexico shape file is a polygon layer, you use a new AreaSymbol and provide it a new Pen and SolidBrush object. As you can see, we declared the Pen to be blue and the filled SolidBrush area to be yellow.
Now that you have your Threshold and SymbolRenderer you need to tell Map Suite what unit of measure you are want to work with and add it to the Layer we declared:
mexicoLayer.ThresholdUnit = Geometry.ThresholdUnits.miles
mexicoLayer.Thresholds.Add(mexicoThreshold)
Below is the completed code for our Form's Load() method:
Private Sub Form1_Load(ByVal sender As System.Object, _
ByVal e As System.EventArgs) Handles MyBase.Load
Map1.MapUnit = Geometry.MapLengthUnits.DecimalDegrees
Dim mexicoLayer As New Layer( _
"C:\Program Files\Spatially Aware\[YOUR MAPSUITE VERSION]\SampleData\Mexico
\states.shp")
Dim mexicoThreshold As New Threshold(2100, 0)
mexicoThreshold.SymbolRenderers.Add(New SymbolRenderer( _
New AreaSymbol(New Pen(Color.Blue),
New SolidBrush(Color.Yellow))))
mexicoLayer.ThresholdUnit = Geometry.ThresholdUnits.miles
mexicoLayer.Thresholds.Add(mexicoThreshold)
Map1.Layers.Add(mexicoLayer)
Map1.Refresh()
End Sub
Compile and run the sample code and your map should render as shown below:
Moving Around the Map
Now that you have the map rendering the way you want you can now provide a way to move around the map with operations like Zooming, Panning, Track Zoom etc. You can do this with a single line of code. Add three buttons to your Windows Form and label one Zoom In, the second Zoom Out and the third Pan. Add code to each button as shown below:
Private Sub Button1_Click(ByVal sender As System.Object, _
ByVal e As System.EventArgs) Handles Button1.Click
Map1.ZoomIn(40)
End Sub
Private Sub Button2_Click(ByVal sender As System.Object, _
ByVal e As System.EventArgs) Handles Button2.Click
Map1.ZoomOut(40)
End Sub
Private Sub Button3_Click(ByVal sender As System.Object,
ByVal e As System.EventArgs) Handles Button3.Click
Map1.Mode = Winforms.ModeType.Pan
End Sub
As you can see, the code for moving around the map is very intuitive. The Map's ZoomIn and ZoomOut methods each take a percentage for how much the map should change each time they are invoked. The Mode property of the Map can be set to various values as defined in the Winforms.ModeType Enumeration.
Let's go ahead and add TrackZoomIn capability so we can select an area of the Map and move in quickly. Add a fourth button to your Windows Form and label it Track Zoom:
Private Sub Button4_Click(ByVal sender As System.Object, _
ByVal e As System.EventArgs) Handles Button4.Click
Map1.Mode = Winforms.ModeType.TrackZoomIn
End Sub
[This is great for moving around the Map but what if you want to get back to the starting point (the full extent) of the Map quickly. That's just as easy to do. Add a fifth buttton to the Windows Form and label it Full Extent:]
Adding More Layers
Now that you have a working Map of Mexico you can now add more Layers to enhance the Map. Let's add a new Layer for the cities which will be points on the Map:
Dim mexicoCitiesLayer As New Layer( _
"C:\Program Files\Spatially Aware\[YOUR MAPSUITE VERSION]\SampleData\Mexico
\cities.shp")
Now we need to create a Threshold for the new layer to tell it how and when to render.
Dim mexicoCitiesThreshold As New Threshold(1000, 0)
mexicoCitiesThreshold.SymbolRenderers.Add(New SymbolRenderer(_
New PointSymbol(PointStyleEnum.Circle, New Pen(Color.Navy), _
New SolidBrush(Color.White), 8)))
mexicoCitiesLayer.ThresholdUnit = Geometry.ThresholdUnits.miles
mexicoCitiesLayer.Thresholds.Add(mexicoCitiesThreshold)
Make sure and add the new Layer to the Map:
Map1.Layers.Add(mexicoCitiesLayer)
There are a couple of things to note with this code. First, the upper Threshold is set at 1000. What this means is that the Threshold will not render until it reaches that point when zooming in closer to the Map. If you run the sample you will not see the cities of Mexico render until you reach that defined range. Secondly, our SymbolRender took an argument of type PointSymbol since we are dealing with points in our shape file:
Now that we have cities, it might be a good idea to give them some labels so we can tell which city is which. This can be done in Map Suite using a LabelRenderer:
mexicoCitiesThreshold.LabelRenderers.Add(New LabelRenderer("NAME", _
New TextSymbol(New Font("Arial", 10),
New SolidBrush(Color.Black))))
The code above accesses the associated DBF data file for the shape file and gets the data in the column called 'NAME'. It then uses a TextSymbol with a Font and a SolidBrush in the constructor to create the labels and place them on the Map:
Summary
As you can see, it is easy to get a full featured Map going and with very little code. This sample only touches on the very basics of using Map Suite. With the power of GDI+ at it's core, and the APIs designed for the average developer without knowledge of GIS, the possibilities are endless.
Other Resources
There are several other resources to help get you started quickly to using Map Suite and adding feature rich maps to your .NET applications:
Sample Applications
There are 40+ sample applications included with Map Suite when you download the trail version that include the source code to show you how to do various operations using the Map Suite component. It is very beneficial to go through those examples and the code. Both VB.NET and C# are included.
View the Map Suite sample applications online
Map Suite Render USA
If you need to have a fully functional map of the United States ready to go, that you can build your business application around, then Map Suite Render USA is for you. Maps Suite Render USA is an Add-In for Map Suite that automates the entire process and creates a seamless view from the states all the way down to the street networks for the entire US. With just a few lines of code and either the Winforms or Webforms edition of our mapping control you can have an instant USA mapping application. This allows you to spend very little time on your maps and more time worrying about the business process for your application.
See Map Suite Render USA in action online
Discussion Forums
The Map Suite Discussion Forums are a great place to get answers to all of your Map Suite development questions. The Spatially Aware Support Team monitors the forums daily and can help you on your way to being successful with Map Suite.
Visit the Discussion Forums online
