Class PositionHelper

Provides helper methods for various position and coordinate tasks.

Inheritance

System.Object

PositionHelper

Inherited Members

System.Object.Equals(System.Object)

System.Object.Equals(System.Object, System.Object)

System.Object.GetHashCode()

System.Object.GetType()

System.Object.MemberwiseClone()

System.Object.ReferenceEquals(System.Object, System.Object)

System.Object.ToString()

Namespace: Mars.Common

Assembly: Mars.Common.dll

Syntax

public static class PositionHelper

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

| Improve this Doc View Source

CalculateBearingCartesian(Double, Double, Double, Double)

Provides helper methods for various position and coordinate tasks.

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

Remarks

| Improve this Doc View Source

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.

Remarks

| Improve this Doc View Source

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.

Remarks

| Improve this Doc View Source

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

Remarks

| Improve this Doc View Source

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.

Remarks

Exceptions

Type	Condition
System.ArgumentException	The bearing is outside the degree value range [0-360].

| Improve this Doc View Source

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

Provides helper methods for various position and coordinate tasks.

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

Remarks

| Improve this Doc View Source

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 = 0)

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].

Remarks

| Improve this Doc View Source

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 = 0)

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].

Remarks

| Improve this Doc View Source

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

Remarks

| Improve this Doc View Source

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.

Remarks

Exceptions

Type	Condition
System.ArgumentException	The bearing is outside the degree value range [0-360].

| Improve this Doc View Source

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

Remarks

| Improve this Doc View Source

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

Provides helper methods for various position and coordinate tasks.

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

Remarks

| Improve this Doc View Source

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.

Remarks

| Improve this Doc View Source

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.

Remarks

| Improve this Doc View Source

CoordinateEnumerable(Geometry)

This method iterates over a NetTopologySuite.Geometries.CoordinateSequence and returns each containing coordinate of a given geometry.

Declaration

public static IEnumerable<Coordinate> CoordinateEnumerable(this Geometry geometry)

Parameters

Type	Name	Description
NetTopologySuite.Geometries.Geometry	geometry	The single/multi geometry or geometry collection.

Returns

Type	Description
System.Collections.Generic.IEnumerable<NetTopologySuite.Geometries.Coordinate>	Returns an iterator on the given `geometry` returning each containing NetTopologySuite.Geometries.Coordinate

Remarks

| Improve this Doc View Source

DegreesToRadians2(Double)

Provides helper methods for various position and coordinate tasks.

Declaration

public static double DegreesToRadians2(double angle)

Parameters

Type	Name	Description
System.Double	angle

Returns

Type	Description
System.Double

Remarks

| Improve this Doc View Source

GetBearing(Position, in 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 System.Double value indicating the bearing from the origin to the destination

Remarks

| Improve this Doc View Source

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 System.Double value indicating the bearing from the origin to the destination

Remarks

| Improve this Doc View Source

GetBearingCartesian(Position, in Position)

Calculates the cartesian bearing, in degrees between two cartesian Positions

Declaration

public static double GetBearingCartesian(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 System.Double value indicating the bearing from the origin to the destination

Remarks

| Improve this Doc View Source

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

Remarks

Exceptions

Type	Condition
System.ArgumentException	The direction is outside the range.

| Improve this Doc View Source

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

Remarks

Exceptions

Type	Condition
System.ArgumentOutOfRangeException	The value is outside the value range 0-360.

| Improve this Doc View Source

GetDistanceFromLatLonInKm(Double, Double, Double, Double)

Provides helper methods for various position and coordinate tasks.

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

Remarks

| Improve this Doc View Source

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.

Remarks

| Improve this Doc View Source

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 System.Double value indicating the bearing from the origin to the destination
System.Double	distance	A System.Double 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

Remarks

| Improve this Doc View Source

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

Remarks

| Improve this Doc View Source

MetersToDecimalDegrees(Double, Double)

Converts a meter value into the corresponding decimal degree distance value

Declaration

public static double MetersToDecimalDegrees(double meters, double latitude)

Parameters

Type	Name	Description
System.Double	meters	That will be converted.
System.Double	latitude	Required to determine the distance projection.

Returns

Type	Description
System.Double	The converted distance in geo-referenced format.

Remarks

| Improve this Doc View Source

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.

| Improve this Doc View Source

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
NetTopologySuite.Geometries.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.

| Improve this Doc View Source

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
NetTopologySuite.Geometries.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.

| Improve this Doc View Source

RotateCoordinateAround(Double, Double, Double, Double, Double, out Double)

This function rotates a given coordinate around a fixed (, ) coordinate at level.

Declaration

public static double RotateCoordinateAround(double rotatingPointX, double rotatingPointY, double sourceX, double sourceY, double degree, out double rotationTargetY)

Parameters

Type	Name	Description
System.Double	rotatingPointX	The x-coordinate of the coordinate to rotate.
System.Double	rotatingPointY	The y-coordinate of the coordinate to rotate.
System.Double	sourceX	The x-coordinate of the fixed point in space to rotate around.
System.Double	sourceY	The y-coordinate of the fixed point in space to rotate around.
System.Double	degree	The range to rotate the point.
System.Double	rotationTargetY	The output y-coordinate of target coordinate rotated to.

Returns

Type	Description
System.Double	Returns the x-coordinate of the target coordinate rotated to by `degree` around `source`.

Remarks

| Improve this Doc View Source

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
NetTopologySuite.Geometries.Coordinate	Returns a new NetTopologySuite.Geometries.Coordinate with the properties of the input position.

Remarks

| Improve this Doc View Source

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.

Remarks

| Improve this Doc View Source

ToPosition(Coordinate)

Transform a NetTopologySuite.Geometries.Coordinate object into a Position object.

Declaration

public static Position ToPosition(this Coordinate coordinate)

Parameters

Type	Name	Description
NetTopologySuite.Geometries.Coordinate	coordinate	The coordinate that should be transformed.

Returns

Type	Description
Position	The equivalent Position.

Remarks

| Improve this Doc View Source

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.