How to define polygons and polylines

Summary
This topic describes how you can define polygon and polyline geometries by specifying individual vertices. It also describes how to define multipart polygons and polylines. A basic introduction to the concept of geometrical correctness or "simplicity" is given, with advice on when you might need to consider this.

In this topic

To use the code in this topic, add references to ESRI.ArcGISExplorer.dll and ESRI.ArcGISExplorer.Application.dll. Add the following namespace references via using (C#) or Imports (VB .NET) statements:
  • ESRI.ArcGISExplorer.Geometry

Creating a single part polyline or polygon

You can define the shape of a new Polyline or Polygon object by using the AddPoint method to add a series of points that define the vertices of the shape. Alternatively, add multiple points at once (more efficient, particularly for adding large numbers of points) using the AddPoints methods. See the following code example:
[C#] 
// Create a polyline.
Polyline pLine1 = new Polyline();
// An array is a simple way to define and add multiple points at once.
pLine1.AddPoints(new ESRI.ArcGISExplorer.Geometry.Point[]
{
    new ESRI.ArcGISExplorer.Geometry.Point(0, 0), new
        ESRI.ArcGISExplorer.Geometry.Point(2, 2)
}

);
// Additional points are added to the end of the line.
pLine1.AddPoint(new ESRI.ArcGISExplorer.Geometry.Point(4, 2));
[VB.NET] 
'Create a polyline.
Dim pLine1 As Polyline = New Polyline()
' An array is a simple way to define and add multiple points at once.
pLine1.AddPoints(New ESRI.ArcGISExplorer.Geometry.Point() {New ESRI.ArcGISExplorer.Geometry.Point(0, 0), New ESRI.ArcGISExplorer.Geometry.Point(2, 2)})
' Additional points are added to the end of the line.
pLine1.AddPoint(New ESRI.ArcGISExplorer.Geometry.Point(4, 2))
Alternatively, you can add points in the overloaded constructor if you know the vertices when the polyline or polygon is instantiated. Methods that add multiple points take anything that is a generic enumerable set of points—anything that you can cast to System.Collections.Generic.IEnumerable<Point> (or System.Collections.Generic.IEnumerable(Of Point) in VB).
The following code example results in the same polyline as the preceding code example:
[C#] 
// pointList supports System.Collections.Generic.IEnumerable<Point>.
System.Collections.Generic.List < ESRI.ArcGISExplorer.Geometry.Point >
    pointList = new System.Collections.Generic.List <
    ESRI.ArcGISExplorer.Geometry.Point > ();
pointList.Add(new ESRI.ArcGISExplorer.Geometry.Point(0, 0));
pointList.Add(new ESRI.ArcGISExplorer.Geometry.Point(2, 2));
pointList.Add(new ESRI.ArcGISExplorer.Geometry.Point(4, 2));
// Using overloaded constructor as alternative to AddPoints.
Polyline pLine2 = new Polyline(pointList);
[VB.NET] 
' pointList supports System.Collections.Generic.IEnumerable<Point>.
Dim pointList As System.Collections.Generic.List(Of ESRI.ArcGISExplorer.Geometry.Point) = New System.Collections.Generic.List(Of ESRI.ArcGISExplorer.Geometry.Point)
pointList.Add(New ESRI.ArcGISExplorer.Geometry.Point(0, 0))
pointList.Add(New ESRI.ArcGISExplorer.Geometry.Point(2, 2))
pointList.Add(New ESRI.ArcGISExplorer.Geometry.Point(4, 2))
' Using overloaded constructor as alternative to AddPoints.
Dim pLine2 As Polyline = New Polyline(pointList)

Closing polygons

Similar AddPoint, AddPoints, and overloaded constructors are available on the Polygon class. Polygons must define a closed shape to display correctly; that is, the first point must be at the same location as the last point. If necessary, the Close method adds a new point as the last point at the same location as the first point. See the following code example:
[C#] 
Polygon pGon = new Polygon(new ESRI.ArcGISExplorer.Geometry.Point[]
{
    new ESRI.ArcGISExplorer.Geometry.Point(0, 0), new
                                   ESRI.ArcGISExplorer.Geometry.Point(0, 6), new
                                   ESRI.ArcGISExplorer.Geometry.Point(6, 6), new
                                   ESRI.ArcGISExplorer.Geometry.Point(6, 0)
}

);
pGon.Close(); // Ensures the polygon is a closed shape by adding point at 0, 0.
[VB.NET] 
Dim pGon As Polygon = New Polygon(New ESRI.ArcGISExplorer.Geometry.Point() {New ESRI.ArcGISExplorer.Geometry.Point(0, 0), New ESRI.ArcGISExplorer.Geometry.Point(0, 6), New ESRI.ArcGISExplorer.Geometry.Point(6, 6), New ESRI.ArcGISExplorer.Geometry.Point(6, 0)})
pGon.Close() ' Ensures the polygon is a closed shape by adding point at 0, 0.
By default, new geometries have the World Geodetic System 1984 (WGS 1984) CoordinateSystem. Any points added to polygons or polylines will have their current CoordinateSystem discarded and will take on the CoordinateSystem of the polygon or polyline; therefore, project any points that have their coordinates set based on a different CoordinateSystem. If you are unsure that your polygon contains overlapping sections or incorrectly defined parts, see the Determining if a polygon is a polygon (simplification) section in this topic.

Creating a multipart polygon or polyline

Polylines and polygons can have multiple parts, in which case they are referred to as "multipart" geometries.
For polylines, each part is known as a path and forms a single continuous line; each path in the polyline can be separate from the other paths.
You can think of a multipart polyline as having a zero-based array of individual paths. By default, you always work only with the first path of a polyline, as this is the simplest case.
To add paths to a polyline, use the AddPath method. To add points to specific paths of a multipart polyline, look for overloaded methods that take a path index parameter. See the following code example:
[C#] 
// Define first path - index 0.
Polyline multiLine = new Polyline(new ESRI.ArcGISExplorer.Geometry.Point[]
{
    new ESRI.ArcGISExplorer.Geometry.Point(0, 0), new
                                   ESRI.ArcGISExplorer.Geometry.Point(2, 2), new
                                   ESRI.ArcGISExplorer.Geometry.Point(4, 2)
}

);
// Define second path - index 1.
multiLine.AddPath(new ESRI.ArcGISExplorer.Geometry.Point[]
{
    new ESRI.ArcGISExplorer.Geometry.Point(0, 1), new
                                   ESRI.ArcGISExplorer.Geometry.Point(2, 3), new
                                   ESRI.ArcGISExplorer.Geometry.Point(4, 3)
}

);
multiLine.AddPoint(0, new ESRI.ArcGISExplorer.Geometry.Point(5, 1)); 
                   // Add a point to the first path.
multiLine.AddPoint(1, new ESRI.ArcGISExplorer.Geometry.Point(5, 2)); 
                   // Add a point to the second path.
[VB.NET] 
' Define first path - index 0.
Dim multiLine As Polyline = New Polyline(New ESRI.ArcGISExplorer.Geometry.Point() {New ESRI.ArcGISExplorer.Geometry.Point(0, 0), New ESRI.ArcGISExplorer.Geometry.Point(2, 2), New ESRI.ArcGISExplorer.Geometry.Point(4, 2)})
' Define second path - index 1.
multiLine.AddPath(New ESRI.ArcGISExplorer.Geometry.Point() {New ESRI.ArcGISExplorer.Geometry.Point(0, 1), New ESRI.ArcGISExplorer.Geometry.Point(2, 3), New ESRI.ArcGISExplorer.Geometry.Point(4, 3)})
multiLine.AddPoint(0, New ESRI.ArcGISExplorer.Geometry.Point(5, 1))
multiLine.AddPoint(1, New ESRI.ArcGISExplorer.Geometry.Point(5, 2))
For polygons, each part is known as a ring and forms a single closed shape. Rings can be contained within other rings, forming holes and islands in the polygon shape. Define points in a single part polygon in a clockwise direction.
You can think of a multipart polygon as having a zero-based array of individual rings. By default, you always work only with the first ring of a polygon, as this is the simplest case.
To add rings to the polygon, use the AddRing method. If you are adding a ring that defines a hole within an existing ring, define the points in a counterclockwise direction. See the following code example:
[C#] 
Polygon multiPgon = new Polygon(new ESRI.ArcGISExplorer.Geometry.Point[]
{
    new ESRI.ArcGISExplorer.Geometry.Point(0, 0), new
                                   ESRI.ArcGISExplorer.Geometry.Point(0, 6), new
                                   ESRI.ArcGISExplorer.Geometry.Point(6, 6), new
                                   ESRI.ArcGISExplorer.Geometry.Point(6, 0)
}

);
multiPgon.AddRing(new ESRI.ArcGISExplorer.Geometry.Point[]
{
    new ESRI.ArcGISExplorer.Geometry.Point(2, 2), new
                                   ESRI.ArcGISExplorer.Geometry.Point(4, 2), new
                                   ESRI.ArcGISExplorer.Geometry.Point(4, 4), new
                                   ESRI.ArcGISExplorer.Geometry.Point(2, 4)
}

);
multiPgon.Close(); // Closes all rings.
[VB.NET] 
Dim multiPgon As Polygon = New Polygon(New ESRI.ArcGISExplorer.Geometry.Point() {New ESRI.ArcGISExplorer.Geometry.Point(0, 0), New ESRI.ArcGISExplorer.Geometry.Point(0, 6), New ESRI.ArcGISExplorer.Geometry.Point(6, 6), New ESRI.ArcGISExplorer.Geometry.Point(6, 0)})
multiPgon.AddRing(New ESRI.ArcGISExplorer.Geometry.Point() {New ESRI.ArcGISExplorer.Geometry.Point(2, 2), New ESRI.ArcGISExplorer.Geometry.Point(4, 2), New ESRI.ArcGISExplorer.Geometry.Point(4, 4), New ESRI.ArcGISExplorer.Geometry.Point(2, 4)})
multiPgon.Close() ' Closes all rings.

Determining if a polygon is a polygon (simplification)

Geometrical shapes have constraints on their shapes. For example, a polygon is only a valid polygon shape if it has closed rings that clearly define the interior and exterior of the shape. The Simplify method applies these rules for you. The geometry you get out might have vertices in different locations, different numbers of vertices, or paths and rings to what you originally specified. See the following code example:
[C#] 
Polygon pGonSimple = GeometryOperations.Simplify(multiPgon);
[VB.NET] 
Dim pGonSimple As Polygon = GeometryOperations.Simplify(pGon)
Geometries retrieved from a table based on a geodatabase will always be "simple" (have been simplified), as the geodatabase enforces simplicity when it is edited. Graphics do not enforce simplicity in the same way; however, they might have problems when displayed if the geometry is not simple. 
Geometrical simplicity is particularly important when looking at the spatial properties of a shape; for example, a non-simple polygon might return an invalid value for its area because the polygon is not defined correctly. This might affect polygons more than polylines, as polygons have more complex geometrical rules for simplicity.


See Also:

Geometry library overview
Polyline class members
Polygon class members
GeometryOperations.Simplify method