The Geometry library provides vector representations for points, multipoints, polylines, polygons, and multipatches. Geometries are used by the geodatabase and graphic element systems to define the shapes of features and graphics. They supply operations that are used by the Editor and map symbology systems to define and symbolize features. Spatial references describe where these geometries are located on the earth. They also define the resolution and valid values for the coordinates used by the geometries. Almost every system in ArcObjects uses geometries and spatial references in some way.

 

To use geometries accurately, consistently, and predictably, you need to understand how geometries and spatial references work together.

 

Geometry objects are not meant to be extended by developers.

In addition to the top level geometry objects (Points, Multipoints, Polylines, and Polygons), Paths, Rings, and Segments serve as building blocks for polylines and polygons. Polylines contain paths and polygons contain rings. Paths and rings are sequences of vertices connected by segments. A segment is a parametric function that defines the shape of the curve connecting its vertices. Segment types include CircularArc, Line, EllipticArc, and BezierCurve. In addition to the X and Y coordinates for each vertex in a geometry, these vertex attributes can be defined: M (measure), Z (elevation), and ID (foreign key). Envelopes describe the spatial extent of other geometries, and GeometryBags provide operations on collections of geometries.

 

Multipoint, polyline, and polygon geometries have constraints on their shapes. For example, a polygon must have its interior clearly defined and separated from its exterior. When all constraints are satisfied, a geometry is said to be simple. When a constraint is violated, or it is not known if the constraint is met, then the geometry is said to be non-simple. The ITopologicalOperator, IPolygonN, and IPolylineN interfaces provide operations for testing and enforcing simplicity. The SDK documentation for the Simplify method of ITopologicalOperator describes these rules precisely.

 

Each vertex of a geometry, in addition to its X and Y coordinates, can have optional attributes, called vertex attributes. The Z vertex attribute is a double-precision value that can be used to represent heights or depths relative to a vertical coordinate system. The M vertex attribute, also called a measure, is a double-precision value that can be used to establish a linear reference system on a geometry (usually a polyline), such as the exits along a highway. The ID vertex attribute, also called a point ID, is a signed integer that can be used as a foreign database key to associate additional information with each vertex such as survey measurements. Vertex attributes can be added to or removed from any geometry at any time and in any combination. For example, a polyline could start out with no vertex attributes, have Zs added to it, then have IDs added to it, then have its Zs removed. When a geometry is aware of its vertex attributes, those attributes will be persisted as part of the geometry and will be included in the output of topological operations that involve that geometry. If a geometry is not aware of its attributes, then those attributes will be ignored when the geometry is persisted, and the attributes will not appear in the output of a topological operation involving that geometry. The attribute awareness of a geometry is controlled by the IZAware, IMAware, or IPointIDAware interface. The attribute values are not actually removed from a geometry if its awareness is disabled.

 

Geometries, especially the segment types, have a rich set of methods for defining their location. For example, the IConstructCircularArc interface shows the different ways you can define a circular arc segment. Typically, interfaces or methods that include the word "construct" in their name use a set of input parameters (including other geometries) to completely define the target geometry. The inputs are not altered.

 

Top level geometries support the classical set-theoretic operations for generating new geometries including union, intersection, difference, and symmetric difference. These operations are exposed on the ITopologicalOperator interface and usually operate on a pair of geometries at a time. ITopologicalOperator.ConstructUnion can operate on more than two. New geometries are created to represent the results. Top level geometries also support the IRelationalOperator interface, which can perform a variety of tests on a pair of geometries such as disjoint, contains, and touches.

 

Both of these interfaces use the spatial reference associated with the input geometries when determining the answer. Two important properties of a spatial reference are its coordinate grid and its XY tolerance. Different values for these properties can cause the relational and topological operators to produce different results. 

Geometries are georeferenced to the real world through a spatial reference. A spatial reference includes the coordinate system and several coordinate grids. A coordinate system includes information such as the unit of measure, the earth model used and, sometimes, how the data was projected. The coordinate grids are mathematical functions that define the XY, Z, and M resolution values and the corresponding domain extents. Each spatial reference also has a set of tolerance values. A geometry’s coordinates (or vertex attributes) must fall within the domain extent and be rounded to the resolution. The tolerance values are used by geometric operations that relate coordinates or compute new ones.

 

XY values can be georeferenced with a geographic or projected coordinate system. A geographic coordinate system (GCS) is defined by a datum, an angular unit of measure, usually either degrees or grads, and a prime meridian. A projected coordinate system (PCS) consists of a linear unit of measure, usually meters or feet, a map projection, the specific parameters used by the map projection, and a GCS. A PCS or GCS can have a vertical coordinate system as an optional property. A vertical coordinate system (VCS) georeferences Z values. A VCS includes either a geodetic or vertical datum, a linear unit of measure, an axis direction, and a vertical shift. M, or measure, values do not have a coordinate system.

 

A spatial reference that includes an unknown coordinate system (UCS) includes a grid (domain extent) and a tolerance only. It is not possible to georeference a geometry associated with a UCS. If at all possible, you should not use a UCS. When a GCS or PCS is used, appropriate default XY domain extent, resolution, and tolerance values can be calculated. All grid and tolerance information for coordinates and attributes are associated with the PCS, GCS, or UCS. A VCS georeferences Z coordinates but does not have a well-defined default grid.

Some of the more widely used geometry objects are described in this section.

 

GeometryEnvironment

GeometryEnvironment provides a way of creating geometries from different inputs and setting or getting global variables for controlling the behavior of geometry methods. It also provides Java and .NET friendly versions of methods originally defined on other geometry objects (see the IGeometryBridge and IGeometryBridge2 interfaces). The GeometryEnvironment object is a singleton object, so calling new several times doesn't create a new object each time. Instead, it returns a reference to the existing GeometryEnvironment.

 

For additional information on working with the GeometryEnvironment class, see Working with the GeometryEnvironment.

 

Envelope

For many applications, the coordinates of a geometry are treated as existing in a planar (Cartesian) coordinate space. An Envelope object is a rectangle with sides parallel to that space defining the spatial extent of a geometry. It can also describe the extent of the geometry’s Z, ID, and M vertex attributes. You can obtain copies of envelopes of other geometries or create envelopes directly. In the first case, the spatial reference of the envelope is the spatial reference of its defining geometry.

 

One way to use envelopes for geometric operations is explained in Finding combined extents of two geometries.

 

GeometryBag

GeometryBag is a set of references to other geometry objects supporting the IGeometry interface. Objects of any level (Polyline, Polygon, Muiltipatch, and Muiltipoint) can be added to GeometryBag via the IGeometryCollection interface. However, placing objects of different geometry types may not be suitable when using GeometryBag in some topological operations. For example, GeometryBag must contain strictly polygons, strictly polylines, or strictly envelopes when using it as a parameter to ITopologicalOperator.ConstructUnion.

 

As with other geometries, a geometry bag has a spatial reference property. A geometry added to a bag will reference the same spatial reference as the bag. If the bag has no spatial reference, then neither will the added geometry after it is added to the bag. This is usually an error. Take care to define the spatial reference of the bag before adding geometries to it.

 

The Union Polygons example illustrates how to use GeometryBag to union a series of polygons, creating a single output geometry.

 

Point

A Point object is a two-dimensional point, optionally with M, Z, and ID attributes.

 

Multipoint

A Multipoint object is an ordered collection of points that optionally has M, Z, and ID attributes. The IPointCollection interface implemented by a Multipoint object provides direct access to its point elements. This is different than how IPointCollection behaves when that interface is used to provide access to the vertices of a polyline or polygon. In that case, you are working with copies of the points.

 

The following examples illustrate how to create a multipoint geometry:

How to efficiently create a Multipoint

How to create a Multipoint from a Polyline

 

Polyline

A Polyline object is an ordered collection of paths that optionally has M, Z, and ID attributes. The IPointCollection interface on Polyline manipulates copies of its vertices. Use the IGeometryCollection interface to directly access its paths and the ISegmentCollection interface to directly access its segments.

 

The IPointCollection and ISegmentCollection interfaces are also available on Path objects and are characterized the same way.

 

The polyline structure is shown in the following diagram.

 

 

Polygon

A Polygon object is a collection of rings ordered by their containment relationship; optionally has M, Z, and ID attributes. Each ring is a collection of segments. The IPointCollection interface on Polygon and Ring manipulates copies of vertices. Use the IGeometryCollection and ISegmentCollection interfaces to access rings and segments directly.

 

The polygon structure is shown in the following diagram.

 

 

MultiPatch

The MultiPatch geometry type was initially developed to address the needs for a three-dimensional (3D) polygon geometry type—unconstrained by two-dimensional (2D) validity rules. Without eliminating the constraints that rule out vertical walls, for example, representing extruded 2D lines and footprint-polygons for 3D visualization would not be possible. In addition to eliminating 2D constraints, MultiPatches provide more control over polygon face orientations, and a better definition of polygon face interiors.

 

Since ArcGIS version 9.0, multipatches have also been extended to provide advanced geometric representations for 3D features. These complex 3D objects can be part of a Synthetic Landscape Model, stored in a geodatabase. The target of these extensions is improved visualization quality.

 

One key capability since version 9.0 is that of supporting per-vertex normals that improve the quality of shading under illumination. Another key capability is that of precise image/texture mapping onto the MultiPatch geometry, via explicit texture coordinates. The geometry of a MultiPatch is inlined with GeometryMaterialList, which contains one or more GeometryMaterials. These GeometryMaterials can be a color, a texture (image), or both. The new class for this functionality is GeneralMultiPatchCreator, which is used to construct MultiPatch.

 

The relationship between the objects used in MultiPatch construction is illustrated here.

 

 

Another feature of MultiPatch is the support of part triangles. This extends the original MultiPatch parts (i.e., Triangle Strip, Triangle Fan, Outer Ring, Inner Ring, First Ring, and Ring). The part triangle completes the range of vertex-based part types and facilitates capturing the output results of different triangle-mesh tessellation or 3D object importers (e.g., from 3D Studio models), which contain non-connected triangles, into a MultiPatch geometry. You can also use the part triangles as an addition to the initial MultiPatch part types offered.

 

A single part triangle represents a collection of triangular faces. Each consecutive triplet of vertices defines a new triangle. The size of a part triangle must be a multiple of three as shown in the following illustration.

 

 

Regarding the use of rings, the following are important notes about MultiPatch geometries:

 

To construct a textured MultiPatch geometry, you should use the IGeneralMultiPatchCreator interface even though the IEncode3DProperties interface that includes the PackTexture2D method still works. With the introduction of explicit vertex normals and texture coordinates, the usage of IEncode3DProperties is now deprecated.

Some of the more widely used spatial reference objects are described in this section.

 

SpatialReferenceEnvironment

SpatialReferenceEnvironment is a singleton object used for creating, loading, and storing entire spatial references. Spatial references are often cloned and copied internally. Setting up SpatialReferenceEnvironment as a singleton object conserves resources and makes it less likely that a spatial reference will be deleted before it is no longer in use. SpatialReferenceEnvironment can also create predefined components used for building spatial references (projections, datums, prime meridians, and so on). You can also use it to convert between low and high precision spatial references.

 

The following topics include additional information on how to use SpatialReferenceEnvironment for the functions referenced above.

 

GeographicCoordinateSystem

GeographicCoordinateSystem includes a name, angular unit of measure, datum (which includes a spheroid), and a prime meridian. It is a model of the earth in a 3D coordinate system. Latitude-longitude, or lat/lon, data is in a GCS. You can access the majority of the properties and methods through the IGeographicCoordinateSystem interface, with a few more properties available in IGeographicCoordinateSystem2. Although you probably won't need to create a custom GCS, the IGeographicCoordinateSystemEdit interface contains the Define and DefineEx methods if you do.

 

To access the hundreds of predefined GCSs, ISpatialReferenceFactory has the CreateGeographicCoordinateSystem method. The predefined GCSs are listed in the esriSRGeoCSType, esriSRGeoCS2Type, and esriSRGeoCS3Type enumerations. The parts of a GCS, such as the datum, angular unit, and prime meridian, are objects as well. All support ISpatialReference2 and ISpatialReferenceFactory. Make use of the predefined objects available in the various esriSR* enumerations.

 

The IGeographicCoordinateSystem2 interface supplies the AngularConversionFactor method, which will return a value that converts the units of measure between two GCSs.

 

The ExtentHint, LeftLongitude, and RightLongitude properties are interrelated. Usually, data in a GCS has longitude values between -180 and 180 if the unit of measure is degrees. Some datasets are designed to use a minimum longitude value of 0 or -360. The LeftLongitude property controls whether the data is considered as -360 to 0, -180 to 180, or 0 to 360. This is only pertinent when you’re inverse projecting projected coordinates for storage in a GCS-based feature class that has a non-standard longitude range. The ArcObjects framework usually deals with this detail for you. Note that the left longitude property is not considered when comparing two GCSs for equality.

 

GetHorizon returns a WKSEnvelope describing the extent of a GCS based on its unit of measure and LeftLongitude. This method can be used to define a standard coordinate grid for the GCS. It is used internally by the ISpatialReferenceResolution.ConstructFromHorizon method.

 

ProjectedCoordinateSystem

ProjectedCoordinateSystem includes a name, linear unit of measure, GCS, map projection, and any parameters required by the map projection. Using the term 'projection' for a coordinate system is imprecise. The term 'projection' should be used for the actual mathematical function. Transverse Mercator and Lambert Conformal Conic are map projections. Universal transverse Mercator (UTM) and State Plane are PCSs that are based on particular map projections. Each PCS must include a GCS. Map projection parameters can be linear, angular, or unitless. A unitless parameter includes scale factor and option. Angular parameters are the central meridian, standard parallels, and latitude of origin. Linear parameters are false easting and false northing. Use the GetDefaultParameters method on the IProjection interface to determine which parameters a particular map projection expects.

 

The parts of a PCS, such as the projection, linear unit, and GCS, are objects as well. All support ISpatialReference2 and ISpatialReferenceFactory. When defining a custom PCS, make use of the predefined objects available in the various esriSR* enumerations.

 

You can access the majority of the properties and methods through the IProjectedCoordinateSystem2 interface although a few more properties are available in IProjectedCoordinateSystem3 and IProjectedCoordinateSystem4. The IProjectedCoordinateSystemEdit interface contains the Define method, which allows you to define a custom PCS. To access the hundreds of predefined PCSs, ISpatialReferenceFactory has the CreateProjectedCoordinateSystem method. The predefined PCSs are listed in the esriSRProjCSType, esriSRProjCS2Type, esriSRProjCS3Type, and esriSRProjCS4Type enumerations.

 

VerticalCoordinateSystem

VerticalCoordinateSystem includes a name, linear unit of measure, a vertical or geodetic (horizontal) datum, a direction, and optionally, a vertical shift. A VCS defines the origin of Z coordinate values. A common application is for Z values to represent elevations or depths, when Z values increase "up" (against the direction of gravity) or decrease 'down' (in the direction of gravity), respectively. You can access the majority of the properties and methods through the IVerticalCoordinateSystem interface. Although you probably won't need to create a custom VCS, the IVerticalCoordinateSystemEdit interface contains the Define method if you do.

The transformation objects can be used to apply various linear coordinate transformations to top-level geometries (Points, Multipoints, Polylines, and Polygons). Typically, you create a particular kind of transformation object, define its properties, then pass it to the geometry being transformed to perform the transform on that geometry. Only occasionally will you need to extract the points from the geometry and transform them directly, or transform arrays of WKSPoints directly.

 

AffineTransformation2D

AffineTransformation2D is a 3x3 matrix that implements conformal (angle preserving) affine and general affine transformations. A minimum of two pairs of points are required to exactly define a conformal affine transformation. A 2D conformal transformation is also called a Helmert transformation. A minimum of three pairs of points are required to define a general affine transformation. Additional points are required to determine root mean square (RMS) error information for the transformation. One use for AffineTransformation2D is to register a paper map into a known coordinate system when digitizing.

 

AffineTransformation3D

AffineTransformation3D is a 4x4 matrix that supports definition of general affine transformations from control points. It will not determine conformal affine transformations.

 

ProjectiveTransformation2D

ProjectiveTransformation2D requires a minimum of four pairs of points to define the transformation. The projective transformation is only used to transform coordinates digitized directly off high altitude aerial photography or aerial photographs of relatively flat terrain assuming that there is no systematic distortion in the air photos. A projective transformation uses eight parameters.

 

Geotransformation

Moving your data between projected coordinate systems may also involve transforming geographic coordinate systems. Because the geographic coordinate systems contain datums that are based on spheroids, a geographic transformation (geotransformation) also changes the underlying spheroid. Other frequently used terms for a geographic transformation include datum shift and geodetic transformation.

 

A geographic transformation is a mathematical operation that takes the coordinates of a point in one geographic coordinate system and returns the coordinates of the same point in another geographic coordinate system. There is also an inverse transformation to allow coordinates to be put back to the first coordinate system from the second. There are many different types of mathematical operations used to achieve this task.