
Developer Guide - 2.3.1.1
INTRODUCTION
What is CoordinateSharp?
CoordinateSharp is a simple .NET Standard library designed to assist with geographic coordinate conversions, formatting and location based celestial calculations.
CoordinateSharp has the ability to convert various Geodetic lat/long formats, UTM, MGRS(NATO UTM) and Cartesians (X, Y, Z). It also provides a wide array
of location based solar/lunar information such as rise/set times, phase info and more.
Prerequisites
.NET 4.0 or greater or .NET Standard 2.0, 1.4, 1.3 Supported Platforms
Installation
CoordinateSharp is available as a nuget package from nuget.org
Alternatively, you may download the library directly here.
Updates and Changes
Change notes can be viewed here
Questions and Issues
If you have any issues or questions create an issue on our GitHub Project Page.
CONTENTS
- Coordinates (Geodetic)
- Coordinate Conversion Formats
- Celestial Information
- Time Zones
- Distances, Bearings and Moving Coordinates
- Binding
- Julian Dates
- Geo-Fencing
- Eager Loading
- Benchmarks
- Credit
COORDINATES (GEODETIC)
Creating a Coordinate Object
The Coordinate
object is the "main" class of this library. For the most part, it contains all of the
information you will need. The following method is one of the most basic ways to create a Coordinate
.
//Seattle coordinates on 5 Jun 2018 @ 10:10 AM (UTC)
Coordinate c = new Coordinate(47.6062, -122.3321, new DateTime(2018,6,5,10,10,0));
Console.WriteLine(c); // N 47º 36' 22.32" W 122º 19' 55.56"
Console.WriteLine(c.CelestialInfo.SunSet); // 5-Jun-2018 4:02:00 AM
Console.WriteLine(c.UTM); // 10T 550200mE 5272748mN
Parsing a Coordinate From a String
CoordinateSharp has the ability to try and parse a Coordinate
from a provided string. The parser will return false
if it fails.
The advantage of this, is that you do not have to control the format in which a user inputs a coordinate. The disadvantage of this is that it will fail
with a bool
value instead of a detailed error message.
string s = "34X 551586mE 8921410mN"; //UTM Coordinate
Coordinate c; //Create new Coordindate to populate
if(Coordinate.TryParse(s, out c))
{
//Coordinate parse was successful
//Coordinate object has now been created and populated
Console.WriteLine(c); //N 80º 20' 44.999" E 23º 45' 22.987"
}
You may also parse with a GeoDate
using the TryParse()
overload.
If you need to work with Latitudes and Longitudes individually you may use the CoordinatePart.TryParse()
method.
Coordinate c = new Coordinate();
c.GeoDate = DateTime.Now //Date needed if grabbing celestial info
CoordinatePart lat;
CoordinatePart.TryParse("N 45.65", out lat);
CoordinatePart lng;
CoordinatePart.TryParse("W 15.58", out lng);
c.Latitude = lat;
c.Longitude = lng;
Because there are multiple types of Cartesian coordinates, you may need to specify what cartesian system you intend for your
parser to work in. Spherical Cartesian is the default method, but it may be changed using an overload.
//Specifies input is in ECEF if X, Y, Z coordinate parses successfully.
Coordinate.TryParse(s, CartesianType.ECEF, out c);
The coordinate parser will be expanded constantly so provided suggestions on formats that should parse are greatly appreciated.
Creating a Coordinate From Other Degree Values
The Coordinate
constructor only accepts Latitude and Longitude in signed degrees.
With that said you can still create a Coordinate
with other formats. For latitude / longitude type coordinates
you can build a Coordinate
using the method below.
It should be noted that this method is expensive if eager loading is being used (explained later in this guide). Eager loading
is turned on by default, so using this method will cause all conversions to occur 3 separate times (once during Coordinate
creation, and once
for each CoordinatePart
). This expense is usually negligible, but may become a factor during bulk or heavy usage.
//DMS Formatted: N 40º 34' 36.552" W 70º 45' 24.408.
Coordinate c = new Coordinate();
c.Latitude = new CoordinatePart(40,34, 36.552, CoordinatesPosition.N);
c.Longitude = new CoordinatePart(70, 45, 24.408, CoordinatesPosition.W);
c.Latitude.ToDouble(); // Returns 40.57682 (Signed Degree)
c.Longitude.ToDouble(); // Returns -70.75678 (Signed Degree)
To create a Coordinate
using a format other than latitude & longitude (such as UTM), either
use the TryParse()
method OR reference the appropriate section of this document for further instruction.
The default output of a Coordinate
or Coordinate.ToString()
is in DMS format. Formats may be changed by passing or editing the FormatOptions
property contained in the Coordinate
object.
Coordinate c = new Coordinate(40.57682, -70.75678);
c.FormatOptions.CoordinateFormatType = CoordinateFormatType.Degree_Decimal_Minutes;
c.FormatOptions.Display_Leading_Zeros = true;
c.FormatOptions.Round = 3;
c.ToString(); // N 40º 34.609' W 070º 045.407'
c.Latitude.ToString(); // N 40º 34.609'
c.Longitude.ToString(); // W 070º 45.407'
Coordinate Conversion Formats
Universal Transverse Mercator and Military Grid Reference System
UTM and MGRS (NATO UTM) formats are available for display. They are converted from the lat/long decimal values.
The default ellipsoid is WGS84 but a custom ellipsoid may be passed.
These formats are accessible from the Coordinate
object.
Coordinate c = new Coordinate(40.57682, -70.75678);
c.UTM.ToString(); // Outputs 19T 351307mE 4493264mN
c.MGRS.ToString(); // Outputs 19T CE 51307 93264
The UTM/MGRS systems should not be used in circumpolar regions. You may check the WithinCoordinateSystemBounds
property to see if you
are outside the limitations of the system. It should also be noted to both UTM and MGRS ToString()
methods will return empty (not null) if a conversion from
Lat/Long is outside the systems limitations.
Coordinate c = new Coordinate(-82,10);
if(!c.MGRS.WithinCoordinateSystemBounds)
{
Console.WriteLine("MGRS cannot be used at this latitude");
Console.WriteLine(c.MGRS); //Will return empty string.
}
To convert UTM or MGRS coordinates into Lat/Long.
UniversalTransverseMercator utm = new UniversalTransverseMercator("T", 32, 233434, 234234);
Coordinate c = UniversalTransverseMercator.ConvertUTMtoLatLong(utm);
You may change or pass a custom ellipsoid by using the Equatorial Radius (Semi-Major Axis) and Inverse of Flattening of the datum. This will cause UTM/MGRS conversions to be based on the new ellipsoid.
Note Regarding Datums: When setting a custom "ellipsoid" you aren't truly setting a datum point, but a reference ellipsoid.
This library isn't designed for mapping and has no way of knowing how a coordinate correlates with an actual map.
This is solely used to changed the earth's shape during calculations to increase accuracy in specific regions.
In most cases the default datum value is sufficient.
To change the current ellipsoid
c.Set_Datum(6378160.000, 298.25);
To create an object with the custom ellipsoid.
UniversalTransverseMercator utm = new UniversalTransverseMercator("Q", 14, 581943.5, 2111989.8, 6378160.000, 298.25);
c = UniversalTransverseMercator.ConvertUTMtoLatLong(utm);
Some UTM formats may contain a "Southern Hemisphere" boolean value instead of a Lat Zone character.
If this is the case for a UTM you are converting, just use the letter "C" for southern hemisphere UTMs and "N" for northern hemisphere UTMs.
//MY UTM COORD ZONE: 32 EASTING: 233434 NORTHING: 234234 (NORTHERN HEMISPHERE)
UniversalTransverseMercator utm = new UniversalTransverseMercator("N", 32, 233434, 234234);
Coordinate c = UniversalTransverseMercator.ConvertUTMtoLatLong(utm);
NOTE: UTM conversions below and above the 85th parallels become highly inaccurate. MGRS conversion may suffer accuracy loss even sooner. No attempts are made by
this library to correct for Norway's modified grid. Lastly, due to grid overlap the MGRS coordinates input, may not be the same ones output in the created Coordinate class.
If accuracy is in question you may test the conversion by following the steps below.
MilitaryGridReferenceSystem mgrs = new MilitaryGridReferenceSystem("N", 21, "SA", 66037, 61982);
Coordinate c = MilitaryGridReferenceSystem.MGRStoLatLong(mgrs);
Coordinate nc = MilitaryGridReferenceSystem.MGRStoLatLong(c.MGRS); //c.MGRS is now 20N RF 33962 61982
Debug.WriteLine(c.ToString() + " " + nc.ToString()); // N 0º 33' 35.988" W 60º 0' 0.01" N 0º 33' 35.988" W 60º 0' 0.022"
In the above example, the MGRS values are different once converted, but the Lat/Long is almost the same once converted back.
Spherical Earth Cartesian (X, Y, Z) is available for display. They are converted from the lat/long radian values.
This format is accessible from the Coordinate
object. You may also convert a Cartesian coordinate into a lat/long coordinate.
This conversion uses the Haversine formula. It is sufficient for basic application only as it assumes a spherical earth.
To Cartesian:
Coordinate c = new Coordinate(40.7143538, -74.0059731);
c.Cartesian.ToString(); //Outputs 0.20884915 -0.72863022 0.65228831
To Lat/Long:
Cartesian cart = new Cartesian(0.20884915, -0.72863022, 0.65228831);
Coordinate c = Cartesian.CartesianToLatLong(cart);
//OR
Coordinate c = Cartesian.CartesianToLatLong(0.20884915, -0.72863022, 0.65228831);
Earth Centered Earth Fixed (ECEF) Cartesian coordinates are available. The are converted using the WGS84 ellipsoid by default, but the ellipsoid may be changed by using the SetDatum()
function. There is no geoid model included in this conversion.
To ECEF:
Coordinate c = new Coordinate(40.7143538, -74.0059731);
c.ECEF.ToString(); //Outputs 1333.97 km, -4653.936 km, 4138.431 km
To Lat/Long:
ECEF ecef = new ECEF(1333.97, -4653.936, 4138.431);
Coordinate c = ECEF.ECEFToLatLong(ecef);
//OR
Coordinate c = ECEF.ECEFToLatLong(1333.97, -4653.936, 4138.431);
When converting from ECEF to GeoDetic Lat/Long, the altitude or height from the conversion may be desired.
The post conversion height may be accessed in the ECEF
class using the Distance
object GeoDetic_Height
.
You may also set the height of the coordinate for ECEF conversions by using the Set_GeoDetic_Height()
.
ECEF height starts at Mean Sea Level (MSL) based on the provided ellipsoid.
NOTE: ECEF.GeoDetic_Height
will always be set at 0 unless a coordinate is converted from ECEF to Lat/Long or
the value is manually updated using ECEF.Set_GeoDetic_Height()
.
Setting the GeoDetic height for ECEF conversions:
Coordinate c = new Coordinate(45 , 45);
c.ECEF.ToString(); //Outputs 3194.419 km, 3194.419 km, 4487.348 km
c.ECEF.Set_GeoDetic_Height(c, new Distance(1000, DistanceType.Meters));
c.ECEF.ToString(); //3194.919 km, 3194.919 km, 4488.056 km
Getting the GeoDetic height after converting from ECEF to Lat/Long:
ECEF ecef = new ECEF(1333.97, -4653.936, 4138.431);
Coordinate c = ECEF.ECEFToLatLong(ecef);
c.ECEF.GeoDetic_Height.Meters; //Outputs 1000.2
The GeoDetic
height will need to be set if creating a new Coordinate
based on an existing Coordinate
. These
fundementals may become applicible if working with EagerLoading
.
Distance geoHeight = c.ECEF.GeoDetic_Height;
Coordinate newCoordinate = new Coordinate(c.Latitude.ToDouble(), c.Longitude.ToDouble());
newCoordinate.ECEF.Set_GeoDetic_Height(newCoordinate, geoHeight);
Celestial Information
Accessing Celestial Data
Solar and lunar information is made available by passing a date to a Coordinate
.
You may initialize a Coordinate
object with a date or pass it later.
CoordinateSharp operates in UTC by default, so all dates will be assumed in UTC regardless of the specified DateTimeKind
.
You may however operate in local time by specifying the Coordinate
object's Offset
value should you choose.
Accessing celestial information example (all times will be in UTC).
//UTC Date 21-MAR-2019 @ 11:00 AM
DateTime d = new DateTime(2017,3,21,11,0,0);
Coordinate c = new Coordinate(40.57682, -70.75678, d);
c.CelestialInfo.SunRise.ToString(); //Outputs 3/21/2017 10:45:00 AM
Local time operation example.
//EST Date 21-MAR-2019 @ 07:00 AM
DateTime d = new DateTime(2017,3,21,7,0,0);
Coordinate c = new Coordinate(40.57682, -70.75678, d);
//Coordinate still assumes the date is UTC, so we must specify the local offset hours.
c.Offset = -4; //EST is UTC -4 hours
c.CelestialInfo.SunRise.ToString(); //Outputs 3/21/2017 06:45:00 AM
Available Celestial Data
The following pieces of celestial information are currently available:
DATA TYPE |
SUN |
MOON |
Rise |
* |
* |
Set |
* |
* |
Altitude |
* |
* |
Azimuth |
* |
* |
Distance |
|
* |
Illumination |
|
* |
Perigee |
|
* |
Apogee |
|
* |
Dawns |
* |
|
Dusks |
* |
|
Eclipse |
* |
* |
Zodiac |
* |
* |
Checking if Celestial Body Is Up
You may check if the Sun or Moon is currently "up" by using the IsSunUp
or IsMoonUp
boolean properties.
The value returned is based on the provided location, GeoDate
and Offset
hours provided.
The Sun and Moon are considered "Up" based on the body's rise/set times.
c.CelestialInfo.IsSunUp; //returns true or false
Checking Celestial Body Conditions
IMPORTANT: Sun/Moon Set and Rise DateTimes are nullable. If a null value is returned the Sun or Moon Condition needs to be viewed to see why. It
is recommended that you always check this.
Coordinate c = new Coordinate(85.57682, -70.75678, new DateTime(2017,8,21));
c.CelestialInfo.SunRise; //Outputs null
c.CelestialInfo.SunCondition; //Outputs UpAllDay
It is also IMPORTANT to note that during the spring months sun cycles are greater then 24 hours. This
means the potential for a no rise or set day is high when working in UTC (even though it may occur in local time).
Moon Illumination and Phase
Moon Illumination returns a value from 0.0 to 1.0. The table shown is a basic break down. You may determine Waxing and Waning types between the values shown using Celestial.MoonIllum.Phase
or you may get the phase name from the Celestial.MoonIllum.PhaseName
property.
Value |
Phase |
0.0 |
New Moon |
0.25 |
First Quarter |
0.5 |
Full Moon |
0.75 |
Third Quarter |
It should be noted that when working in local time, the moons "phase name" may change if the UTC day is the previous or next day. There will also be times when the phase name
does not match the news or certain websites. This normally occurs when the source is using the following morning's phase name. CoordinateSharp works in the exact
time passed to capture phase name, not the phase name on a "certain night".
If you are unsure or do not prefer this behavior, you may tap into the Phase
property to determine your own phase name.
Static Retrieval of Celestial Data
You may also grab celestial data through static functions if you do not wish to create a Coordinate object.
//UTC EXAMPLE
Celestial cel = Celestial.CalculateCelestialTimes(45.57682, -70.75678, new DateTime(2017,8,21));
cel.SunRise.Value.ToString();
//LOCAL TIME (EST) EXAMPLE
double utcOffsetHours = -4;
Celestial cel = Celestial.CalculateCelestialTimes(45.57682, -70.75678, new DateTime(2017,8,21), utcOffsetHours);
cel.SunRise.Value.ToString();
Lunar Perigee and Apogee
Perigee and Apogee information is available in the Celestial
class but may be called specifically as it is not location dependent.
Perigee p = Celestial.GetPerigee(date);
p.LastPerigee.Date;
p.LastPerigee.Distance.Kilometers;
Eclipses
Solar and Lunar Eclipse.
Coordinate seattle = new Coordinate(47.6062, -122.3321, DateTime.Now);
//Solar
SolarEclipse se = seattle.CelestialInfo.SolarEclipse;
se.LastEclipse.Date;
se.LastEclipse.Type;
//Lunar
LunarEclipse le = seattle.CelestialInfo.LunarEclipse;
se.NextEclipse.Date;
se.NextEclipse.Type;
You may also grab a list of eclipse data based on the century for the location's date.
List<SolarEclipseDetails> events = Celestial.Get_Solar_Eclipse_Table(seattle.Latitude.ToDouble(), seattle.Longitude.ToDouble(), DateTime.Now);
Celestial Data Notes
NOTE REGARDING ECLIPSE DATA: Eclipse data can only be obtained from the years 1601-2600. Thas range will be expanded with future updates.
NOTE REGARDING SOLAR/LUNAR ECLIPSE PROPERTIES: The Date
property for both the Lunar and Solar eclipse classes will only return the date of the event. Other properties such as PartialEclipseBegin
will give more exact timing for event parts.
Solar eclipses sometimes occur during sunrise/sunset. Eclipse times account for this and will not start or end while the sun is below the horizon.
Properties will return 0001/1/1 12:00:00
if the referenced event didn't occur. For example if a solar eclipse is not a Total or Annular eclipse, the AorTEclipseBegin
property won't return a populated DateTime.
NOTE REGARDING CALCULATIONS: The formulas used take into account the locations altitude. Currently all calculations for eclipse timing are set with an altitude of 100 meters. Slight deviations in actual eclipse timing may occur based on the locations actual altitude. Deviations are very minimal and should suffice for most applications.
NOTE REGARDING REFRACTION: Averages are used to calculate refraction. You may see slight deviations in actual event occurance depending on actual atmospheric conditions. Furthmore, you will see deviations in times near circumpolar regions if a celestial body spends a large quantity of time near the event horizon. For example, if the events Civil Dusk & Civil Dawn are with an hour or two from eachother, you will see deviations in time as the solar disc maintains position at the event horizon.
Time Zones
Getting Time Zone at Location
CoordinateSharp does not contain the ability by itself to acquire time zones for offsetting a UTC DateTime
. This is a complicated process that involves keeping up with
ever changing map data and time zone rules. With that said, it is understood that users of this library often have the need for this. The goal of this section is to assist with methods of accomplishing that goal.
The Two Part Process
Gathering time zone information based solely on a coordinate is a two part process.
- Acquire the IANA time zone ID using either a web service or a library.
- Determine the UTC offset using an IANA compliant date tool such as NodaTime.
1. Acquire the Time Zone ID
There are many tools that can grab a time zone ID based on a provided coordinate, but all have issues. For instance, implementing a library is great in that
you do not rely on a web service to provide that data for you. The problem with this method however is that time zones change globally. Every time there is a change
you must not only update the library you are using, but hope the developers maintaining the library get the change out in time.
Web services like Google or Bing Maps on the other hand are great in that they are usually up to date. The problem with web services however is that they will rate limit you
unless you pay money. Furthermore, they require an internet connection to work. It's really a "pick your poison" type situation. Check out this Stack Overflow
post for a great list of services and libraries that can help you decide which tool works best for you.
For the purposes of this very basic example, we'll be using the Google Maps API. You will most likely need an API key to use this. It can be
obtained from the Google Developer Console
First we need a data model to handle the Google Map Request.
public class GoogleTimeZone
{
public double dstOffset { get; set; }
public double rawOffset { get; set; }
public string status { get; set; }
public string timeZoneId { get; set; }
public string timeZoneName { get; set; }
}
Next we need a DateTime
extension method to handle Google's time stamp requirements.
public static class ExtensionMethods
{
public static double ToTimestamp(this DateTime date)
{
DateTime origin = new DateTime(1970, 1, 1, 0, 0, 0, 0);
TimeSpan diff = date.ToUniversalTime() - origin;
return Math.Floor(diff.TotalSeconds);
}
}
Lastly we add a method to handle the RESTful API request to Google. This example is very basic. It is up to you to handle any
errors or failed/denied requests.
using RestSharp; //RestSharp can be downloaded via Nuget.
public static string GetTimeZone(double latitude, double longitude)
{
string ianaID;
string key = "<your secret key>"; //MAP API KEY. Get from Google Developer Console.
var client = new RestClient("https://maps.googleapis.com"); //Set the client
var request = new RestRequest("maps/api/timezone/json", Method.GET); //Set the request type (timezone)
//Add required parameters
request.AddParameter("location", latitude + "," + longitude);
request.AddParameter("timestamp", DateTime.Now.ToTimestamp());
request.AddParameter("key", key);
//Send the request to Google and await response
var response = client.Execute<GoogleTimeZone>(request);
return ianaID = response.Data.timeZoneId;
}
Ok now we are set up to grab a time zone ID based on our Lat / Long.
Coordinate c = new Coordinate(42, -112, DateTime.Now);
string timezoneID = GetTimeZone(c.Latitude.ToDouble(), c.Longitude.ToDouble());
Console.WriteLine(timezoneID); //America/Boise
2. Determine the UTC Offset.
Luckily hard part is over. Thanks to the master of C# John Skeet, we can get the offset of the time zone we just
acquired using his awesome library NodaTime.
using NodaTime; //Download from Nuget
DateTimeZone zone = DateTimeZoneProviders.Tzdb[tz];
DateTime d = DateTime.Now.ToUniversalTime(); //Date must have DateTimeKind of UTC
Instant instant = Instant.FromDateTimeUtc(Convert.ToDateTime(DateTime.Now.ToUniversalTime()));
Offset offset = zone.GetUtcOffset(instant);
Distances, Bearings and Moving Coordinates
Calculating Distance
Distance is calculated with 2 methods based on how you define the shape of the earth.
If you pass the shape as a Sphere
calculations will be more efficient, but less accurate.
The other option is to pass the shape as an Ellipsoid
. Ellipsoid calculations have a higher accuracy.
The default ellipsoid of a coordinate is WGS84, but can be changed using the Coordinate.SetDatum
function.
Distance can be calculated between two Coordinates. Various distance values are stored in the Distance object.
Distance d = new Distance(coord1, coord2); //Default. Uses Haversine (Spherical Earth)
//OR
Distance d = new Distance(coord1, coord2, Shape.Ellipsoid);
d.Kilometers;
d.Bearing;
You may also grab a distance by passing a second Coordinate to an existing Coordinate.
coord1.Get_Distance_From_Coordinate(coord2).Miles;
Moving Coordinates
If you wish to move a coordinate based on a known distance and bearing you can do so with the Move
function.
Distance must be passed in meters. The coordinate values will update in place.
//1000 Meters
//270 degree bearing
coord1.Move(1000, 270, Shape.Ellipsoid);
You may also move a specified distance toward a target coordinate if you do not have a bearing toward it.
//Move coordinate 1 10,000 meters toward coordinate 2
coord1.Move(coord2, 10000, Shape.Ellipsoid);
The option to create a Distance
for conversion purposes only also exists.
Distance d = new Distance(20, DistanceType.NauticalMiles);
d.Meters; //Convert to meters.
Binding
Binding and MVVM
The properties in CoordinateSharp implement INotifyPropertyChanged
and may be bound.
If you wish to bind to the entire CoordinatePart
bind to the Display
property.
This property can be notified of changes, unlike the overridden ToString()
.
The Display
will reflect the formats previously specified for the Coordinate
object in the code-behind.
Output Example:
<TextBlock Text="{Binding Latitude.Display, UpdateSourceTrigger=PropertyChanged}"/>
Input Example:
<ComboBox Name="latPosBox" VerticalAlignment="Center" SelectedItem="{Binding Path=DataContext.Latitude.Position, UpdateSourceTrigger=LostFocus, Mode=TwoWay}"/>
<TextBox Text="{Binding Latitude.Degrees, UpdateSourceTrigger=LostFocus, Mode=TwoWay, ValidatesOnExceptions=True}"/>
<TextBox Text="{Binding Latitude.Minutes, UpdateSourceTrigger=LostFocus, Mode=TwoWay, ValidatesOnExceptions=True}"/>
<TextBox Text="{Binding Latitude.Seconds, StringFormat={}{0:0.####}, UpdateSourceTrigger=LostFocus, Mode=TwoWay, ValidatesOnExceptions=True}"/>
NOTE: It is important that input boxes be set with 'ValidatesOnExceptions=True'.
This will ensure UIElements
display input errors when incorrect values are passed.
Julian Dates
Julian Date Conversions
The Julian date converters used by the library have been exposed for use. The converters account for both Julian and Gregorian calendars.
//To Julian
double jul = JulianConversions.GetJulian(date);
//From Julian
DateTime date = JulianConversions.GetDate_FromJulian(jul));
//Epoch options also exist
JulianConversions.GetJulian_Epoch2000(date);
Geo-Fencing
Creating Geo-Fences
Both line and polygon boundaries may be specified using the GeoFence
class. Once Points
have been specified you may
compare them to a Coordinate
to determine if it is within bounds.
List<GeoFence.Point> points = new List<GeoFence.Point>();
//Points specified manually to create a square in the USA.
//First and last points should be identical if creating a polygon boundary.
points.Add(new GeoFence.Point(31.65, -106.52));
points.Add(new GeoFence.Point(31.65, -84.02));
points.Add(new GeoFence.Point(42.03, -84.02));
points.Add(new GeoFence.Point(42.03, -106.52));
points.Add(new GeoFence.Point(31.65, -106.52));
GeoFence gf = new GeoFence(points);
Coordinate c = new Coordinate(36.67, -101.51);
//Determine if Coordinate is within polygon
gf.IsPointInPolygon(c);
//Determine if Coordinate is within specific range of shapes line.
gf.IsPointInRangeOfLine(c1, 1000); //Method 1 specify meters.
Distance d = new Distance(1, DistanceType.Kilometers);
gf.IsPointInRangeOfLine(c1, d); //Method 2 specify Distance object.
Eager Loading
Eager Loading Basics
CoordinateSharp values are all eager loaded upon initialization of a Coordinate
.
Anytime a Coordinate
property changes, everything is recalculated.
You may wish to turn off eager loading if you are trying to maximize performance.
This will allow you to specify when certain calculations take place.
EagerLoad eagerLoad = new EagerLoad();
eagerLoad.Celestial = false;
Coordinate c = new Coordinate(40.0352, -74.5844, DateTime.Now, eagerLoad);
//To load Celestial data when ready
c.LoadCelestialInfo();
The above example initializes a Coordinate with eager loading in place.
You may however turn it on or off after initialization.
c.EagerLoadSettings.Celestial = false;
You may also turn EagerLoading on/off for all available settings at once.
//Sets EagerLoading off for all properties (CelestialInfo, MGRS, UTM, Cartesian, ECEF)
EagerLoad eagerLoad = new EagerLoad(false);
Coordinate c = new Coordinate(40.0352, -74.5844, DateTime.Now, eagerLoad);
Enum flags with a declared object or static function may be used. Only the passed flags will EagerLoad.
EagerLoadType et = EagerLoadType.Celestial | EagerLoadType.Cartesian;
EagerLoad eagerLoad = new EagerLoad(et);
//OR
EagerLoad eagerLoad = EagerLoad.Create(et); //Returns new EagerLoad
A more in depth look at eager loading can be found in our Performance Tips page.
Benchmarks
Benchmark Results
The following Coordinate
procedures were benchmarked as follows.
Method |
i7-8550U 1.80GHz 1.99 GHz (x64) |
Standard Initialization |
8 ms |
TryParse() Initialization |
6-35 ms |
Secondary Initialization |
30 ms |
Initialization w/EagerLoad off |
< 1 ms |
Property Change |
7 ms |
Total Celestial (Local/UTC) |
8 ms |
Solar Cycle Only (Local/UTC) |
< 1 ms |
Lunar Cycle Only (Local/UTC) |
2 ms |
Credit
Acknowledgements
Most celestial calculations are based on "Astronomical Algorithms" 2nd edition by Jean Meeus (Willmann-Bell, Richmond) 1998.
Certain solar algorithms were adapted from NOAA and Zacky Pickholz 2008 "C# Class for Calculating Sunrise and Sunset Times"
NOAA
The Zacky Pickholz project
Certain lunar calculations were adapted from the mourner / suncalc project (c) 2011-2015, Vladimir Agafonkin suncalc
& These Formulas by Dr. Louis Strous
Calculations for illumination parameters of the moon based on NASA Formulas and Chapter 48 of "Astronomical Algorithms" 2nd edition by Jean Meeus (Willmann-Bell, Richmond) 1998.
UTM & MGRS Conversions were referenced from Sami Salkosuo's j-coordconvert library & Steven Dutch, Natural and Applied Sciences,University of Wisconsin - Green Bay
ECEF Conversions were referenced from works by James R. Clynch
Solar and Lunar Eclipse calculations were adapted from NASA's Eclipse Calculator created by Chris O'Byrne and Fred Espenak.
Aspects of distance calculations referenced worked by Ed Williams Great Circle Calculator
Graphic and logo design work was donated by area55.
All GitHub users who contribute code and/or create issues!