StarThrower.Gis.GeoUtilities 2.0.0

StarThrower.Gis.GeoUtilities

Geographic and coordinate system utilities including shape parsing, spatial calculations, and geometry helpers.

StarThrower.Gis.GeoUtilities is a geodesy library: it models coordinate reference systems (datums, ellipsoids, prime meridians, angular/linear units, map projections, and geoid gravity models), translates coordinates between them — including datum shifts and geoid/ellipsoid height conversions — and provides ESRI shapefile-style geometry types (PointShape, PolylineShape, PolygonShape, etc.) for representing parsed vector features.

Installation

dotnet add package StarThrower.Gis.GeoUtilities

Coordinate Reference System Model

A coordinate reference system is built from several composable pieces, each represented by an interface and an abstract base class:

All of these expose a ToXml() method that produces a self-describing XML fragment (e.g. <datum>, <ellipsoid>, <geographicCoordinateSystem>).

Built-in Reference Data

The library ships with a large catalog of concrete implementations, organized one type per file:

Factories

Every reference-data category has a corresponding static factory class that locates the concrete type via reflection and returns a singleton instance:

Each factory exposes the same shape of members:

• GetInstanceOfX(Type) / GetInstanceOfX(string typeName) — returns the singleton instance of the requested type, looked up by name via Assembly.GetExecutingAssembly().GetTypes().
• XTypeExists(string typeName) — true if a matching type was found.
• GetXType(string typeName) — the resolved Type, or throws if not found/ambiguous.

DatumFactory, EllipsoidFactory, GeoidFactory, GeographicCoordinateSystemFactory, and ProjectedCoordinateSystemFactory additionally support user-defined instances — datums, ellipsoids, geoids, and coordinate systems constructed at runtime from caller-supplied parameters (e.g. GetInstanceOfNewUserDefinedDatum(name, ellipsoid, deltaX, ..., north, south, east, west)), looked up afterwards by name via GetInstanceOfExistingUserDefinedDatum(name).

Invalid or ambiguous type names throw InvalidXTypeException / AmbiguousXTypeException (see Exceptions).

GeoUtil

GeoUtil is the static entry point for coordinate translation and validation.

Translate Pipeline

Translate converts a coordinate in any supported coordinate system to any other:

1. Convert from csFrom to geodetic coordinates in csFrom's datum (csFrom.ToGeodetic).
2. If csFrom.Datum and csTo.Datum differ, shift to WGS84 via csFrom.Datum.ToWgs84 — using a Molodensky shift for 3-parameter datums within range, or a 3-step geocentric conversion (Toms 1996) for 7-parameter datums or out-of-range latitudes — then shift from WGS84 to csTo's datum via csTo.Datum.FromWgs84.
3. Adjust the vertical (zAlt) component according to csFrom.HeightType and csTo.HeightType, using the EGM96 or EGM84 geoid models where a geoid/ellipsoid height conversion is required.
4. Convert from geodetic coordinates in csTo's datum to csTo (csTo.FromGeodetic).
5. Compute combined error-propagation statistics for the conversion and attach them to the result via ITranslationResult.SetComputationalError(ce90, le90, se90).

ITranslationResult

public interface ITranslationResult
{
    double xLon { get; }
    double yLat { get; }
    double zAlt { get; }
    double ce90 { get; }
    double le90 { get; }
    double se90 { get; }
    void SetComputationalError(double ce90, double le90, double se90);
}

ce90/le90/se90 are the 90% circular, linear, and spherical error estimates accumulated across the datum shift and height conversion steps.

HeightType

public enum HeightType
{
    NoHeight = 0,
    EllipsoidHeight = 1,
    GeoidOrMslHeight = 2,
    MslEgm96VgNsHeight = 3,
    MslEgm8410dBlHeight = 4,
    MslEgm8410dNsHeight = 5
}

Determines whether, and how, Translate converts the zAlt component between ellipsoid height and mean-sea-level (geoid) height using the EGM96 or EGM84 grids and natural-spline (Ns) or bilinear (Bl) interpolation.

Usage

Translating Between Coordinate Systems

using StarThrower.Gis.GeoUtilities;
using StarThrower.Gis.GeoUtilities.CoordinateSystems.Geographic;
using StarThrower.Gis.GeoUtilities.CoordinateSystems.Projected;

IGeographicCoordinateSystem wgs84 =
    GeographicCoordinateSystemFactory.GetInstanceOfGeographicCoordinateSystem(typeof(GeodeticWgs84));

IProjectedCoordinateSystem utm =
    ProjectedCoordinateSystemFactory.GetInstanceOfProjectedCoordinateSystem(typeof(UtmWgs84));

// Geographic (lon/lat, decimal degrees) -> UTM (easting/northing, meters)
ITranslationResult utmResult = GeoUtil.Translate(wgs84, utm, -77.0365, 38.8977, 0.0);

if (utmResult is StarThrower.Gis.GeoUtilities.IZone)
{
    // UTM results carry their zone via Translations.ZonedResult, which implements IZone
}

// Round trip back to geographic
ITranslationResult geoResult = GeoUtil.Translate(utm, wgs84, utmResult.xLon, utmResult.yLat, utmResult.zAlt);

Working with Points

using StarThrower.Gis.GeoUtilities;
using StarThrower.Gis.GeoUtilities.Formatting;

GeoPoint point = new GeoPoint(-77.0365, 38.8977);

IDmsFormatter dms = DmsFormatterFactory.Create(DmsFormat.Dms1);
string lonDms = dms.DdToDmsEw(point.xLon); // e.g. "77° 02' 11.40\" W"
string latDms = dms.DdToDmsNs(point.yLat); // e.g. "38° 53' 51.72\" N"

Shapes

The Shapes namespace models ESRI shapefile geometry types, used to represent parsed vector features:

All shape types implement ICloneable and the library's ItemCopy(object) convention (throwing FailedItemCopyException on failure).

using StarThrower.Gis.GeoUtilities.Shapes;

PolygonShape polygon = new PolygonShape();
polygon.AddPart();

ClosedPart ring = polygon.GetPart(0);
ring.AddPoint(new PointShape(-77.05, 38.90));
ring.AddPoint(new PointShape(-77.00, 38.90));
ring.AddPoint(new PointShape(-77.00, 38.85));
ring.AddPoint(new PointShape(-77.05, 38.85));

GeoRectangle extent = polygon.Extent;
int totalPoints = polygon.PointCount;

Exceptions

Usage Notes

• Singletons. Factory-returned instances (datums, ellipsoids, geoids, units, prime meridians, and built-in coordinate systems) are singletons per concrete type — do not assume each call to GetInstanceOfX returns a distinct object, except for UserDefined/zoned instances which are cached by name/zone.
• Geoid.NsInterpolate/BlInterpolate throw ArgumentOutOfRangeException for latitude/longitude values outside the geoid grid's coverage; ToEllipsoidHeightNs, FromEllipsoidHeightNs, ToEllipsoidHeightBl, and FromEllipsoidHeightBl are virtual and throw NotSupportedException unless overridden (only Egm84 and Egm96 implement them).
• UTM zoning. UtmWgs84/UtmWgs84Ns/UtmWgs72/UtmWgs72Ns are IZonedCoordinateSystems; FromGeodetic determines the correct IZone from the input coordinates and delegates to the zone-specific singleton instance via ProjectedCoordinateSystemFactory. The Ns variants use a 10,000,000 m false northing for the southern hemisphere.
• DMS formatting. DmsFormatterFactory.Create(DmsFormat) returns a singleton IDmsFormatter: DmsFormat.Default/Dms1 produces [°][d][d]d° [m]m' ss.ss"-style strings; Dms2 produces {N|S|E|W}[d]d{D}[m]m{M}[s]s[.ss]{S}-style strings.
• Datum domain validation. GeoUtil.Translate throws InvalidOperationException if the translated coordinate falls outside the destination datum's valid region (Datum.Domain, checked via Datum.Validate).

Known Limitations

• Most non-UTM projected coordinate systems do not yet project. Of the 32 types in CoordinateSystems/Projected/, only MercatorWgs84 and the four UTM variants (UtmWgs84/UtmWgs84Ns/UtmWgs72/UtmWgs72Ns) have working ToGeodetic/FromGeodetic implementations. The other 26 (e.g. LambertConformalConic1Wgs84, MollweideWgs84, TransverseMercatorWgs84) currently pass the input coordinate through unchanged. The underlying projection math for all of these already exists in Projections/ — the coordinate-system wrapper classes just don't call into it yet. See #11.
• Datum.FromWgs84 is a no-op for almost every datum. Converting a coordinate from WGS84 into any datum other than Wgs1972/Wgs1984 currently returns the input unchanged. The seven-parameter/geocentric shift path (GeocentricShiftToWgs84) is similarly unimplemented, affecting Osgb1936, European1950, and UserDefined datums specifically. See #12.

Dependencies

• StarThrower.ByteUtilities — endian-aware byte conversions used by Egm84/Egm96 to read binary geoid grid files.
• StarThrower.MathUtilities
• StarThrower.StringUtilities

License

Copyright © 2026 Stephen Elmer. Licensed under the MIT License.