Working with Polygons

Working with Polygons

If you need to define more than a single point location in a data source, you can create a polygon data source. Like point data sources, polygon data sources include spatial and non-spatial entities.

Overview of Polygons

A polygon data source allows you to define one or more regions on a map. You can then use these regions to find relations to other polygons, point data sources, addresses, and specific geographic locations. For example, you may define the delivery area for a store as a polygon. You can then look up a customer's address and determine if that address is within the delivery area. Polygons can be as simple as a single ring of connected points, or may be complex, with an external ring containing numerous internal rings that define areas not included in the polygon.

Defining a Polygon

A polygon data source contains one or more polygons. Polygons are defined by an ordered series of latitude/longitude points (vertices) with an implied connection between consecutive vertices and between the last and first vertex. A single polygon data source can contain up to 500 vertices.

Each polygon consists of a single external ring and may include multiple internal rings. When you create a polygon, you must first define the external ring. The following illustration shows the external ring of a polygon with 6 vertices and the implied edges drawn between each.

Note that the implied edges of the polygon cannot intersect one another.

In addition to the external ring, a polygon can contain one or more internal rings. Like the external ring, internal rings are defined by an ordered list of vertices, and no two implied edges may intersect. Therefore, each internal ring must be entirely contained within the external ring. In addition, you cannot create an internal ring within an existing internal ring. The following illustration shows the same external ring with two internal rings.

Note An internal or external ring must contain at least 3 vertices.

Polygon Properties

Like point data sources, a polygon data source requires a value for the EntityID property. You may also optionally provide a value for the Name and Display Name properties. Unlike point data sources, however, you do not have to provide values for the Latitude and Longitude properties. If you do not provide a value for the Latitude or Longitude property, the properties will be automatically set to the latitude and longitude of the center point of the bounding rectangle for the polygon.

Note The point defined by the Latitude and Longitude properties may not lie within the polygon.

In addition to the reserved properties, you can define custom properties for polygons.

Finding Polygons

You can find polygons by either their spatial (location) or non-spatial properties.

Finding a Polygon by Location

When finding a polygon by location, you can use either a LatLong or LatLongRectangle. For example, you can determine if a LatLong point lies within a polygon. You can also determine if a polygon is contained within a LatLongRectangle, or if the rectangle and polygon are connected in any way. The following illustration shows the possible relationships between a rectangle and polygon.

To find a polygon, follow these basic steps:

1. Create a FindPolygonSpecification object.

   The FindPolygonSpecification object contains the specifications for the polygon you are trying to find: the data source name, a find filter, the find options, and a spatial filter. The spatial filter is used to find a polygon based on its location, as described previously. The following code shows how to set the properties to determine if a specific point is within a specified polygon:

   FindPolygonSpecification findPolySpec = new FindPolygonSpecification();
   
   LatLongSpatialFilter filter = new LatLongSpatialFilter();
   filter.LatLong = new LatLong();
   filter.LatLong.Latitude = Convert.ToDouble(txtLatitude.Text);
   filter.LatLong.Longitude = Convert.ToDouble(txtLongitude.Text);
   
   FindFilter ff = new FindFilter();
   ff.EntityTypeName = "MyEntityName";
   
   findPolySpec.SpatialFilter= filter;
   findPolySpec.DataSourceName="MyDataSource";
   findPolySpec.Filter = ff;
   
   
   

2. Call the FindPolygon method. The following code shows how to determine if a specific point is within the specified polygon:

   FindResults results = finder.FindPolygon(findPolySpec);
   if (results.NumberFound==1)
   {
       lblCheckPoint.Text="The specified point is in the polygon.";
   }
   else
   {
       lblCheckPoint.Text="The specified point is not in the polygon.";
   }
   
   

Finding a Polygon by Property

To find a polygon by any non-spatial properties, you use the FindByID or FindByProperty methods. You use these methods the same way when working with either a point data source or a polygon data source.

Displaying Polygons

To display a polygon data source on a map retuned by MapPoint Web Service, you perform the following steps:

1. Create MapSpecification, MapView, and RenderServiceSoap objects, exactly as you would to render any map:

   MapSpecification spec = new MapSpecification();
   spec.DataSourceName = "MapPoint.NA";
   spec.Views = views;
   spec.Options = mo;
   
   
   

2. Create an array of Polygon objects. For each Polygon object, set the DataSourceName, EntityID, BorderColor, and FillColor properties.

   MapPointColor fillColor = new MapPointColor();
   fillColor.Alpha=Convert.ToByte(txtFillAlpha.Text);
   fillColor.Blue=Convert.ToByte(txtFillBlue.Text);
   fillColor.Green=Convert.ToByte(txtFillGreen.Text);
   fillColor.Red=Convert.ToByte(txtFillRed.Text);
   
   MapPointColor lineColor = new MapPointColor();
   lineColor.Alpha=Convert.ToByte(txtLineAlpha.Text);
   lineColor.Blue=Convert.ToByte(txtLineBlue.Text);
   lineColor.Green=Convert.ToByte(txtLineGreen.Text);
   lineColor.Red=Convert.ToByte(txtLineRed.Text);
   
   Polygon poly = new Polygon();
   poly.DataSourceName = "MyDataSource"; 
   poly.EntityID = "MyEntityID";
   poly.BorderColor=lineColor;
   poly.FillColor=fillColor;
   
   
   

3. Set the MapSpecification.Polygons property to the polygon array.

   spec.Polygons = new Polygon[1];
   spec.Polygons[0] = poly;
   
   
   

4. Set the MapSpecification.Options.Format.MimeType property to either the image/jpeg or image/png MIME type.

   spec.Options = new MapOptions();
   spec.Options.Format = new ImageFormat();
   spec.Options.Format.MimeType = "image/jpeg";
   
   
   

   Note Although you can use the image/gif MIME type for all of your maps, polygons display best when you choose either the image/jpeg or image/png MIME type.

5. Call the RenderServiceSoap.GetMap method.

   MapImage[] mi = render.GetMap(spec);
   pictMap.Image = new Bitmap(new System.IO.MemoryStream(mi[0].MimeData.Bits));
   
   
   

The returned map image will include the map data and each of the polygons in the array, drawn with the specified colors.

For more information, see the sample application "Working with Polygons".

Creating Polygons

There are several ways you can create and prepare polygon data for upload to the Customer Service Site:

1. You can convert existing polygon data that you have created in other applications by using the polygon conversion tool.

2. You can manually create an XML file that contains the polygon data.