Class Geography

Namespace: YndigoBlue.Velocity.Model

Assembly: YndigoBlue.Velocity.dll

Represents geographic spatial data with coordinate reference system (SRID) support for earth-based locations.

public class Geography : IEquatable<Geometry>, IEquatable<Geography>

Inheritance: object

Geography

Implements: IEquatable<Geometry>

IEquatable<Geography>

Remarks

Warning

Geospatial data types (Geography and Geometry) are not available in the Community Edition of Velocity. They require the Full Edition.

Geography wraps NetTopologySuite's Geometry to represent spatial data that uses geographic coordinate systems (latitude/longitude) rather than planar coordinates. Geography types are used for real-world locations on the Earth's surface.

Geography vs Geometry:

Geography: Uses latitude/longitude coordinates (SRID typically 4326 for WGS 84). Calculations account for Earth's curvature. Used for GPS coordinates, maps, locations.
Geometry: Uses planar (X,Y) coordinates (SRID 0 or custom). Calculations use Euclidean math. Used for CAD drawings, game maps, abstract shapes.

Geography supports all standard spatial types from NetTopologySuite:

Point: Single location (e.g., a building, city)
LineString: Connected line segments (e.g., a road, river)
Polygon: Closed area (e.g., country boundary, park)
MultiPoint, MultiLineString, MultiPolygon: Collections of the above
GeometryCollection: Mixed collection of spatial objects

Coordinate Reference Systems (SRID):

The SRID (Spatial Reference Identifier) defines the coordinate system:

4326: WGS 84 - Standard GPS coordinates (longitude, latitude)
3857: Web Mercator - Used by web mapping (Google Maps, OpenStreetMap)
Custom: Other EPSG codes for regional coordinate systems

Geography is stored in the database using database-specific spatial types and can be queried using spatial functions and indexes via SpatialIndex.

Examples

Creating and storing a geographic point (city location):

using NetTopologySuite.Geometries;

using (Manager manager = new Manager(connection))
{
    Schema schema = manager.LoadSchema("my_schema");

    Table citiesTable = schema.CreateTable("cities");
    citiesTable.CreateColumn("id", DataType.Integer);
    citiesTable.CreateColumn("name", DataType.VarChar, size: 100);
    citiesTable.CreateColumn("location", DataType.Geography);

    manager.BuildSchema(schema);

    // Insert San Francisco's location (longitude, latitude in WGS 84)
    Record<Table> record = new Record<Table>(citiesTable);
    record.SetFieldInteger("id", 1);
    record.SetFieldVarChar("name", "San Francisco");

    Point sfLocation = new Point(-122.4194, 37.7749);
    sfLocation.SRID = 4326; // WGS 84 coordinate system
    Geography sfGeography = new Geography(sfLocation);

    record.SetFieldGeography("location", sfGeography);
    manager.AddRecord(record);
}

Retrieving and using geographic data:

Query query = new Query();
query.AddFromItem(citiesTable);
query.AddSelectItem(citiesTable["name"]);
query.AddSelectItem(citiesTable["location"]);

IEnumerable<Result> results = manager.Retrieve(query);

foreach (Result result in results)
{
    string cityName = result.GetFieldVarChar("name");
    Geography location = result.GetFieldGeography("location");

    Console.WriteLine($"{cityName}:");
    Console.WriteLine($"  Longitude: {location.Coordinate.X}");
    Console.WriteLine($"  Latitude: {location.Coordinate.Y}");
    Console.WriteLine($"  SRID: {location.SRID}");
    Console.WriteLine($"  WKT: {location.AsText()}");
}

Working with polygons (geographic boundaries):

// Define a polygon representing a park boundary
Coordinate[] parkBoundary = new Coordinate[]
{
    new Coordinate(-122.42, 37.78),
    new Coordinate(-122.42, 37.77),
    new Coordinate(-122.41, 37.77),
    new Coordinate(-122.41, 37.78),
    new Coordinate(-122.42, 37.78)  // Close the polygon
};

LinearRing ring = new LinearRing(parkBoundary);
Polygon parkPolygon = new Polygon(ring);
parkPolygon.SRID = 4326;

Geography parkGeography = new Geography(parkPolygon);

Record<Table> record = new Record<Table>(parksTable);
record.SetFieldVarChar("name", "Golden Gate Park");
record.SetFieldGeography("boundary", parkGeography);

manager.AddRecord(record);

Working with lines (routes, roads):

// Define a route as a line
Coordinate[] routePoints = new Coordinate[]
{
    new Coordinate(-122.42, 37.78),
    new Coordinate(-122.41, 37.77),
    new Coordinate(-122.40, 37.76)
};

LineString routeLine = new LineString(routePoints);
routeLine.SRID = 4326;

Geography routeGeography = new Geography(routeLine);

Console.WriteLine($"Route length: {routeGeography.Length} degrees");
Console.WriteLine($"Start point: {routeGeography.Coordinates[0]}");
Console.WriteLine($"End point: {routeGeography.Coordinates[routeGeography.NumPoints - 1]}");

Using geography properties:

Geography cityLocation = result.GetFieldGeography("location");

// Access spatial properties
bool isEmpty = cityLocation.IsEmpty;
bool isValid = cityLocation.IsValid;
double area = cityLocation.Area;  // For polygons
double length = cityLocation.Length;  // For lines
Point centroid = cityLocation.Centroid;  // Center point

// Get coordinates
Coordinate singlePoint = cityLocation.Coordinate;  // First coordinate
Coordinate[] allPoints = cityLocation.Coordinates;  // All coordinates
int pointCount = cityLocation.NumPoints;

// Get boundary (for polygons)
Geometry boundary = cityLocation.Boundary;

// Get envelope (bounding box)
Geometry envelope = cityLocation.Envelope;

Converting to/from text formats:

Geography location = result.GetFieldGeography("location");

// Get Well-Known Text (WKT) representation
string wkt = location.AsText();
// Output: "POINT (-122.4194 37.7749)"

// Get Well-Known Binary (WKB) representation
byte[] wkb = location.AsBinary();

// These can be stored or transmitted and later reconstructed
Console.WriteLine($"Location as WKT: {wkt}");

Constructors

Geography(Geometry): Initializes a new Geography wrapping the provided geometry.

Properties

Area: Gets the area of this geography in the coordinate system's units. Non-zero only for Polygon and MultiPolygon types.

Boundary: Gets the boundary of this geography as a Geometry. For polygons this is a LineString; for points it is the empty set.

BoundaryDimension: Gets the dimension of the boundary of this geography.

Centroid: Gets the centroid (geometric centre) of this geography as a NetTopologySuite.Geometries.Point.

Coordinate: Gets the first coordinate of this geography, or null if the geometry is empty.

Coordinates: Gets all coordinates that make up this geography as a flat array.

Dimension: Gets the topological dimension of this geography (0 for points, 1 for lines, 2 for polygons).

Envelope: Gets the minimum bounding rectangle of this geography as a Geometry.

EnvelopeInternal: Gets the minimum bounding rectangle of this geography as an NetTopologySuite.Geometries.Envelope value type.

Geometry: Gets the underlying NetTopologySuite NetTopologySuite.Geometries.Geometry object that holds the spatial data.

GeometryType: Gets the name of the geometry type (e.g. "Point", "Polygon", "LineString").

InteriorPoint: Gets a point that is guaranteed to lie on or within this geography.

IsEmpty: Gets a value indicating whether this geography contains no coordinates.

IsRectangle: Gets a value indicating whether this geography is an axis-aligned rectangle.

IsSimple: Gets a value indicating whether this geography is topologically simple (no self-intersections).

IsValid: Gets a value indicating whether this geography is topologically valid according to OGC rules.

Length: Gets the length of this geography in the coordinate system's units. Non-zero only for linear types (LineString, MultiLineString, and polygon boundaries).

NumGeometries: Gets the number of component geometries when this geography is a collection type; returns 1 for simple types.

NumPoints: Gets the total number of points (vertices) in this geography.

OgcGeometryType: Gets the OGC geometry type enumeration value for this geography.

PointOnSurface: Gets a point that lies on the surface of this geography (alias for InteriorPoint).

PrecisionModel: Gets the NetTopologySuite.Geometries.PrecisionModel used by the geometry factory that created this geography.

SRID: Gets the Spatial Reference Identifier (SRID) of this geography. Use 4326 for WGS 84 (GPS coordinates).

Methods

AsBinary(): Returns the Well-Known Binary (WKB) representation of this geography.

AsText(): Returns the Well-Known Text (WKT) representation of this geography, for example "POINT (-122.4194 37.7749)".

Equals(Geometry): Determines whether this geography is spatially equal to a raw Geometry object.

Equals(Geography): Determines whether this geography is spatially equal to another Geography.

ToString(): Returns the WKT string representation of this geography.