Class PositionHelper

Provides helper methods for various position and coordinate tasks.
Inheritance
System.Object
PositionHelper
Namespace: Mars.Common
Assembly: Mars.Common.dll
Syntax
public static class PositionHelper : object
Remarks
This class is a collection of several helper methods to compute new positions based on a source with direction and distance (see , GetRelativePosition(Double, Double, Double, Double) and CalculateDerivedPosition(Position, Double, Double)) and can be used to calculate distances or to retrieve direction from input bearings of radian yaw (see GetDistanceFromLatLonInKm(Double, Double, Double, Double), GetDistanceFromLatLonInM(Double, Double, Double, Double) and GetDirection(Double) ). The other methods will not be needed in most situations.

Methods

CalculateDerivedPosition(Position, Double, Double)

Calculates the end-point from a given source at a given range (meters) and bearing (degrees). This methods uses simple geometry equations to calculate the end-point.
Declaration
public static Position CalculateDerivedPosition(Position source, double range, double bearing)
Parameters
Type Name Description
Position source Point of origin
System.Double range Range in meters
System.Double bearing Bearing in degrees
Returns
Type Description
Position End-point from the source given the desired range and bearing.

CalculateDerivedPosition(Double, Double, Double, Double)

Calculates the end-point from a given source at a given range (meters) and bearing (degrees). This methods uses simple geometry equations to calculate the end-point.
Declaration
public static Position CalculateDerivedPosition(double longitude, double latitude, double range, double bearing)
Parameters
Type Name Description
System.Double longitude The longitude/x component of the source coordinate.
System.Double latitude The longitude/x component of the source coordinate.
System.Double range Range in meters
System.Double bearing Bearing in degrees
Returns
Type Description
Position End-point from the source given the desired range and bearing.

CalculateRelativePosition(Position, Double, Double)

Calculates the relative position from a source towards a bearing with distance to pass.
Declaration
public static Position CalculateRelativePosition(this Position source, double bearing, double distance)
Parameters
Type Name Description
Position source The source position
System.Double bearing The bearing ranging withing 0 to 360
System.Double distance The distance as a unitless ways
Returns
Type Description
Position

CalculateRelativePosition(Double, Double, Double, Double, out Double)

Declaration
public static double CalculateRelativePosition(double originLongitude, double originLatitude, double bearing, double distance, out double y)
Parameters
Type Name Description
System.Double originLongitude
System.Double originLatitude
System.Double bearing
System.Double distance
System.Double y
Returns
Type Description
System.Double

CalculateTargetCoordinate(Double, Double, Double, Double, out Double)

Calculates the target point from a given source point, bearing an distance.
Declaration
public static double CalculateTargetCoordinate(double sourceX, double sourceY, double distance, double bearing, out double targetX)
Parameters
Type Name Description
System.Double sourceX X-coordinate of the source.
System.Double sourceY Y-coordinate of the source.
System.Double distance distance between target and source.
System.Double bearing Bearing towards target.
System.Double targetX Output x-coordinate of the target.
Returns
Type Description
System.Double Returns the y-coordinate of the target and the x-coordinate as output-parameter.

CoordinateEnumerable(Geometry)

This method iterates over a and returns each containing coordinate of a given geometry.
Declaration
public static IEnumerable<Coordinate> CoordinateEnumerable(this Geometry geometry)
Parameters
Type Name Description
Geometry geometry The single/multi geometry or geometry collection.
Returns
Type Description
IEnumerable<Coordinate> Returns an iterator on the given geometry returning each containing

DegreesToRadians2(Double)

Declaration
public static double DegreesToRadians2(double angle)
Parameters
Type Name Description
System.Double angle
Returns
Type Description
System.Double

GetBearing(Position, Position)

Calculates the bearing, in degrees between two geospatial-Positions
Declaration
public static double GetBearing(this Position pt1, in Position pt2)
Parameters
Type Name Description
Position pt1 A Position object representing the origin location
Position pt2 A Position object representing the destination location
Returns
Type Description
System.Double A value indicating the bearing from the origin to the destination

GetBearing(Double, Double, Double, Double)

Calculates the bearing, in degrees between two (geographic) points
Declaration
public static double GetBearing(double x1, double y1, double x2, double y2)
Parameters
Type Name Description
System.Double x1 The x or longitude of the origin location in decimal notation in degree
System.Double y1 The y or latitude of the origin location in decimal notation in degree
System.Double x2 The x or longitude of the destination location in decimal notation in degree
System.Double y2 The y or latitude of the destination location in decimal notation in degree
Returns
Type Description
System.Double A value indicating the bearing from the origin to the destination

GetDirection(Double)

Maps the

bearing

to the respective direction type DirectionType
Declaration
public static DirectionType GetDirection(double bearing)
Parameters
Type Name Description
System.Double bearing The direction in range of 0-360
Returns
Type Description
DirectionType Returns a concrete direction abstracting from the bearing

GetDistanceFromLatLonInKm(Double, Double, Double, Double)

Declaration
public static double GetDistanceFromLatLonInKm(double lat1, double lon1, double lat2, double lon2)
Parameters
Type Name Description
System.Double lat1
System.Double lon1
System.Double lat2
System.Double lon2
Returns
Type Description
System.Double

GetDistanceFromLatLonInM(Double, Double, Double, Double)

Calculates the distance in meters between to geospatial coordinate with latitude and longitude input.
Declaration
public static double GetDistanceFromLatLonInM(double lat1, double lon1, double lat2, double lon2)
Parameters
Type Name Description
System.Double lat1 The latitude component of the first position.
System.Double lon1 The longitude component of the first position.
System.Double lat2 The latitude component of the second position.
System.Double lon2 The longitude component of the second position.
Returns
Type Description
System.Double Returns the distance of these two points in meters.

GetRelativePosition(Position, Double, Double)

Calculates the end-point from a given source at a given range (meters) and bearing (degrees). This methods uses simple geometry equations to calculate the end-point.
Declaration
public static Position GetRelativePosition(this Position sourceGpsCoordinate, double bearing, double distance)
Parameters
Type Name Description
Position sourceGpsCoordinate A Position object representing the origin location
System.Double bearing A value indicating the bearing from the origin to the destination
System.Double distance A value representing the distance in miles from the origin to the destination coordinate
Returns
Type Description
Position A Position value representing the new coordinate calculated from the source point

GetRelativePosition(Double, Double, Double, Double)

Calculates the end-point from a given source at a given range (meters) and bearing (degrees). This methods uses simple geometry equations to calculate the end-point.
Declaration
public static Position GetRelativePosition(double originLatitude, double originLongitude, double bearing, double distance)
Parameters
Type Name Description
System.Double originLatitude
System.Double originLongitude
System.Double bearing
System.Double distance
Returns
Type Description
Position

RandomPositionFromGeometry(Envelope)

This function calculates a random Position restricted by the given envelope representing a bounding box of an area.
Declaration
public static Position RandomPositionFromGeometry(this Envelope envelope)
Parameters
Type Name Description
Envelope envelope The envelopment of a geometry to restrict the selection of a random Position
Returns
Type Description
Position Returns a new randomly selected position Position
Remarks
The random function select coordinates evenly distributed.

RandomPositionFromGeometry(Geometry)

This function calculates a random Position restricted by the given geometry which can be either a Multi-/Polygon, Multi-/Point or Multi-/Line.
Declaration
public static Position RandomPositionFromGeometry(this Geometry geometry)
Parameters
Type Name Description
Geometry geometry The geometry to restrict the selection of a random Position
Returns
Type Description
Position Returns a new randomly selected position Position
Remarks
The random function select coordinates evenly distributed.

RandomPositionFromGeometry(BoundingBox)

This function calculates a random Position restricted by the given envelope representing a bounding box of an area.
Declaration
public static Position RandomPositionFromGeometry(this BoundingBox boundingBox)
Parameters
Type Name Description
BoundingBox boundingBox The envelope of a geometry to restrict the selection of a random Position
Returns
Type Description
Position Returns a new randomly selected position Position
Remarks
The random function select coordinates evenly distributed.

ToCoordinate(Position)

Converts the internal position object to the widely accepted GeoAPI.Geometries.Coordinate which represents a geospatial object. and can be used in combination with several gis-libraries.
Declaration
public static Coordinate ToCoordinate(this Position position)
Parameters
Type Name Description
Position position The Position to convert.
Returns
Type Description
Coordinate Returns a new with the properties of the input position.

ToGeoPosition(IRasterLayer, Position)

Transform the grid position of a cell within a raster layer into a geo position. Grid Position(2,2) into Geo Position(31.52, -24.58)
Declaration
public static Position ToGeoPosition(this IRasterLayer rasterLayer, Position gridPosition)
Parameters
Type Name Description
IRasterLayer rasterLayer Holds the grid and geo references.
Position gridPosition The position of the cell within the raster grid.
Returns
Type Description
Position The geo Position of the grid cells center point.

ToPosition(Coordinate)

Transform a object into a Position object.
Declaration
public static Position ToPosition(this Coordinate coordinate)
Parameters
Type Name Description
Coordinate coordinate The coordinate that should be transformed.
Returns
Type Description
Position The equivalent Position.

Validate(Double, Double)

Validates the coordinate.
Declaration
public static bool Validate(double latitude, double longitude)
Parameters
Type Name Description
System.Double latitude The latitude.
System.Double longitude The longitude.
Returns
Type Description
System.Boolean True, if the coordinate is valid, false otherwise.