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 CalculateMovementVector(Position, Double, Double, Double), 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

CalculateBearingCartesian(Double, Double, Double, Double)

Declaration
public static double CalculateBearingCartesian(double x1, double y1, double x2, double y2)
Parameters
Type Name Description
System.Double x1
System.Double y1
System.Double x2
System.Double y2
Returns
Type Description
System.Double

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.

CalculateDiscretePosition(Double, Double, Double, Double, Double)

Calculates a new discrete grid-position on the line between a source and target.
Declaration
public static Position CalculateDiscretePosition(double x1, double y1, double x2, double y2, double stepDistance)
Parameters
Type Name Description
System.Double x1 The X component of the source location.
System.Double y1 The Y component of the source location.
System.Double x2 The X component of the target location.
System.Double y2 The Y component of the target location.
System.Double stepDistance The travelling distance to pass.
Returns
Type Description
Position Returns a new discrete grid-position which lies on the line with the slope of the source and the target location

CalculateDiscretePositionByBearing(Double, Double, Double, Double)

Calculates a new discrete position based on an outgoing source location given by x and y coordinate, a bearing specifying the direction and the distance to pass.
Declaration
public static Position CalculateDiscretePositionByBearing(double x, double y, double bearing, double stepDistance)
Parameters
Type Name Description
System.Double x The x coordinate of the source.
System.Double y The y coordinate of the source.
System.Double bearing The angle in degrees within the value range [0-360].
System.Double stepDistance The travelling distance to pass.
Returns
Type Description
Position Returns a new Position reached by the distance towards a direction.

CalculateIntersectionPoint(Double, Double, Double, Double, Double, Double, Double, Double)

Declaration
public static Position CalculateIntersectionPoint(double p0X, double p0Y, double p1X, double p1Y, double p2X, double p2Y, double p3X, double p3Y)
Parameters
Type Name Description
System.Double p0X
System.Double p0Y
System.Double p1X
System.Double p1Y
System.Double p2X
System.Double p2Y
System.Double p3X
System.Double p3Y
Returns
Type Description
Position

CalculateMovementVector(Position, Double, Double, Double)

Calculate a movement vector based on current position, headings and distance.
Declaration
public static Position CalculateMovementVector(this Position pos, double distance, double yaw, double pitch = null)
Parameters
Type Name Description
Position pos Current position.
System.Double distance Traveling distance.
System.Double yaw Heading of the agent.
System.Double pitch Climb angle.
Returns
Type Description
Position The movement vector [x,y].

CalculateMovementVector(Double[], Double, Double, Double)

Calculate a cartesian movement vector based on current position, headings and distance. For geospatial movement vector use CalculateDerivedPosition(Double, Double, Double, Double)
Declaration
public static double[] CalculateMovementVector(double[] pos, double distance, double yaw, double pitch = null)
Parameters
Type Name Description
System.Double[] pos Current position.
System.Double distance Traveling distance.
System.Double yaw Heading of the agent.
System.Double pitch Climb angle.
Returns
Type Description
System.Double[] The movement vector [x,y].

CalculatePosition(Double, Double, Double, Double, Double)

Calculates a new continuous position on the line between a source and target.
Declaration
public static Position CalculatePosition(double x1, double y1, double x2, double y2, double stepDistance)
Parameters
Type Name Description
System.Double x1 The X component of the source location.
System.Double y1 The Y component of the source location.
System.Double x2 The X component of the target location.
System.Double y2 The Y component of the target location.
System.Double stepDistance The travelling distance to pass.
Returns
Type Description
Position Returns a new discrete grid-position which lies on the line with the slope of the source and the target location

CalculatePositionByBearing(Double, Double, Double, Double)

Calculates a new continuous position based on an outgoing source location given by x and y coordinate, a bearing specifying the direction and the distance to pass.
Declaration
public static Position CalculatePositionByBearing(double x, double y, double bearing, double stepDistance)
Parameters
Type Name Description
System.Double x The x coordinate of the source.
System.Double y The y coordinate of the source.
System.Double bearing The angle in degrees within the value range [0-360].
System.Double stepDistance The travelling distance to pass.
Returns
Type Description
Position Returns a new Position reached by the distance towards a direction.

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

CalculateTargetByBearingAndDistance(Double, Double, Double, Double, out Double)

Calculates a new continuous position based on an outgoing source location given by x and y coordinate, a bearing specifying the direction and the distance to pass.
Declaration
public static double CalculateTargetByBearingAndDistance(double sourceX, double sourceY, double bearing, double distance, out double targetY)
Parameters
Type Name Description
System.Double sourceX The x coordinate of the source.
System.Double sourceY The y coordinate of the source.
System.Double bearing The angle in degrees within the value range [0-360].
System.Double distance The travelling distance to pass.
System.Double targetY The output y-coordinate of the target.
Returns
Type Description
System.Double Returns the x-coordinate of the target.

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

GetDirectionType(Double, Double)

Maps the bearing change to one of the fixed directions described in DirectionType.
Declaration
public static DirectionType GetDirectionType(double incomingBearing, double outgoingBearing)
Parameters
Type Name Description
System.Double incomingBearing The bearing before, in value range 0-360.
System.Double outgoingBearing The bearing after the change, in value range 0-360.
Returns
Type Description
DirectionType Returns one of the eight directions

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.

ToPositions(Coordinate[], out Int32[])

Converts the external coordinate array object into the internal position collection.
Declaration
public static Position[] ToPositions(this Coordinate[] coordinates, out int[] positionLength)
Parameters
Type Name Description
Coordinate[] coordinates The collection.
System.Int32[] positionLength The output geometry length with the same amount of elements as the results, each indicating the distance along the path starting from the first element.
Returns
Type Description
Position[] Returns a new array of Position object.

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.