Add ITRF Datum & Add reference epoch (#14)

* Add ITRF Datum & Add reference epoch

* Apply suggestions

* Apply suggestions

* Apply suggestions

src/Cartography.jl

@@ -29,11 +29,14 @@ export
   Datum,
   NoDatum,
   WGS84,
-  WIII,
+  WGS84Latest,
+  ITRF,
+  ITRFLatest,
   ellipsoid,
   latitudeₒ,
   longitudeₒ,
   altitudeₒ,
+  epoch,
 
   # coordinates
   CRS,

src/codes.jl

@@ -31,13 +31,13 @@ function crs end
 # IMPLEMENTATIONS
 # ----------------
 
-crs(::Type{EPSG{3395}}) = Mercator{WGS84}
-crs(::Type{EPSG{3857}}) = WebMercator{WGS84}
-crs(::Type{EPSG{4326}}) = LatLon{WGS84}
-crs(::Type{EPSG{32662}}) = PlateCarree{WGS84}
-crs(::Type{ESRI{54017}}) = Behrmann{WGS84}
-crs(::Type{ESRI{54030}}) = Robinson{WGS84}
-crs(::Type{ESRI{54034}}) = Lambert{WGS84}
-crs(::Type{ESRI{54042}}) = WinkelTripel{WGS84}
-crs(::Type{ESRI{102035}}) = Orthographic{90.0u"°",0.0u"°",true,WGS84}
-crs(::Type{ESRI{102037}}) = Orthographic{-90.0u"°",0.0u"°",true,WGS84}
+crs(::Type{EPSG{3395}}) = Mercator{WGS84Latest}
+crs(::Type{EPSG{3857}}) = WebMercator{WGS84Latest}
+crs(::Type{EPSG{4326}}) = LatLon{WGS84Latest}
+crs(::Type{EPSG{32662}}) = PlateCarree{WGS84Latest}
+crs(::Type{ESRI{54017}}) = Behrmann{WGS84Latest}
+crs(::Type{ESRI{54030}}) = Robinson{WGS84Latest}
+crs(::Type{ESRI{54034}}) = Lambert{WGS84Latest}
+crs(::Type{ESRI{54042}}) = WinkelTripel{WGS84Latest}
+crs(::Type{ESRI{102035}}) = Orthographic{90.0u"°",0.0u"°",true,WGS84Latest}
+crs(::Type{ESRI{102037}}) = Orthographic{-90.0u"°",0.0u"°",true,WGS84Latest}

src/crs/basic.jl

@@ -23,7 +23,7 @@ The first 3 coordinates can be accessed with the properties `x`, `y` and `z`, re
 Cartesian(1, 1) # add default units
 Cartesian(1u"m", 1u"m") # integers are converted converted to floats
 Cartesian(1.0u"km", 1.0u"km", 1.0u"km")
-Cartesian{WGS84}(1.0u"m", 1.0u"m")
+Cartesian{WGS84Latest}(1.0u"m", 1.0u"m")
 ```
 
 ## References
@@ -110,7 +110,7 @@ Polar(1, π/4) # add default units
 Polar(1u"m", (π/4)u"rad") # integers are converted converted to floats
 Polar(1.0u"m", 45u"°") # degrees are converted to radians
 Polar(1.0u"km", (π/4)u"rad")
-Polar{WGS84}(1.0u"m", (π/4)u"rad")
+Polar{WGS84Latest}(1.0u"m", (π/4)u"rad")
 ```
 
 ## References
@@ -146,7 +146,7 @@ Cylindrical(1, π/4, 1) # add default units
 Cylindrical(1u"m", (π/4)u"rad", 1u"m") # integers are converted converted to floats
 Cylindrical(1.0u"m", 45u"°", 1.0u"m") # degrees are converted to radians
 Cylindrical(1.0u"km", (π/4)u"rad", 1.0u"km")
-Cylindrical{WGS84}(1.0u"m", (π/4)u"rad", 1.0u"m")
+Cylindrical{WGS84Latest}(1.0u"m", (π/4)u"rad", 1.0u"m")
 ```
 
 ## References
@@ -187,7 +187,7 @@ Spherical(1, π/4, π/4) # add default units
 Spherical(1u"m", (π/4)u"rad", (π/4)u"rad") # integers are converted converted to floats
 Spherical(1.0u"m", 45u"°", 45u"°") # degrees are converted to radians
 Spherical(1.0u"km", (π/4)u"rad", (π/4)u"rad")
-Spherical{WGS84}(1.0u"m", (π/4)u"rad", (π/4)u"rad")
+Spherical{WGS84Latest}(1.0u"m", (π/4)u"rad", (π/4)u"rad")
 ```
 
 ## References

src/crs/geographic.jl

@@ -27,7 +27,7 @@ LatLon(45, 45) # add default units
 LatLon(45u"°", 45u"°") # integers are converted converted to floats
 LatLon((π/4)u"rad", (π/4)u"rad") # radians are converted to degrees
 LatLon(45.0u"°", 45.0u"°")
-LatLon{WGS84}(45.0u"°", 45.0u"°")
+LatLon{WGS84Latest}(45.0u"°", 45.0u"°")
 ```
 
 See [EPSG:4326](https://epsg.io/4326).
@@ -43,7 +43,7 @@ GeodeticLatLon{Datum}(lat::Rad, lon::Rad) where {Datum} = GeodeticLatLon{Datum}(
 GeodeticLatLon{Datum}(lat::Number, lon::Number) where {Datum} =
   GeodeticLatLon{Datum}(addunit(lat, u"°"), addunit(lon, u"°"))
 
-GeodeticLatLon(args...) = GeodeticLatLon{WGS84}(args...)
+GeodeticLatLon(args...) = GeodeticLatLon{WGS84Latest}(args...)
 
 const LatLon = GeodeticLatLon
 
@@ -66,7 +66,7 @@ LatLonAlt(45u"°", 45u"°", 1u"m") # integers are converted converted to floats
 LatLonAlt((π/4)u"rad", (π/4)u"rad") # radians are converted to degrees
 LatLonAlt(45.0u"°", 45.0u"°", 1.0u"km") # length quantities are converted to meters
 LatLonAlt(45.0u"°", 45.0u"°", 1.0u"m")
-LatLonAlt{WGS84}(45.0u"°", 45.0u"°", 1.0u"m")
+LatLonAlt{WGS84Latest}(45.0u"°", 45.0u"°", 1.0u"m")
 ```
 """
 struct GeodeticLatLonAlt{Datum,D<:Deg,M<:Met} <: Geographic{Datum}
@@ -86,7 +86,7 @@ GeodeticLatLonAlt{Datum}(lat::Rad, lon::Rad, alt::Len) where {Datum} =
 GeodeticLatLonAlt{Datum}(lat::Number, lon::Number, alt::Number) where {Datum} =
   GeodeticLatLonAlt{Datum}(addunit(lat, u"°"), addunit(lon, u"°"), addunit(alt, u"m"))
 
-GeodeticLatLonAlt(args...) = GeodeticLatLonAlt{WGS84}(args...)
+GeodeticLatLonAlt(args...) = GeodeticLatLonAlt{WGS84Latest}(args...)
 
 const LatLonAlt = GeodeticLatLonAlt
 
@@ -104,7 +104,7 @@ GeocentricLatLon(45, 45) # add default units
 GeocentricLatLon(45u"°", 45u"°") # integers are converted converted to floats
 GeocentricLatLon((π/4)u"rad", (π/4)u"rad") # radians are converted to degrees
 GeocentricLatLon(45.0u"°", 45.0u"°")
-GeocentricLatLon{WGS84}(45.0u"°", 45.0u"°")
+GeocentricLatLon{WGS84Latest}(45.0u"°", 45.0u"°")
 ```
 """
 struct GeocentricLatLon{Datum,D<:Deg} <: Geographic{Datum}
@@ -118,7 +118,7 @@ GeocentricLatLon{Datum}(lat::Rad, lon::Rad) where {Datum} = GeocentricLatLon{Dat
 GeocentricLatLon{Datum}(lat::Number, lon::Number) where {Datum} =
   GeocentricLatLon{Datum}(addunit(lat, u"°"), addunit(lon, u"°"))
 
-GeocentricLatLon(args...) = GeocentricLatLon{WGS84}(args...)
+GeocentricLatLon(args...) = GeocentricLatLon{WGS84Latest}(args...)
 
 """
     AuthalicLatLon(lat, lon)
@@ -134,7 +134,7 @@ AuthalicLatLon(45, 45) # add default units
 AuthalicLatLon(45u"°", 45u"°") # integers are converted converted to floats
 AuthalicLatLon((π/4)u"rad", (π/4)u"rad") # radians are converted to degrees
 AuthalicLatLon(45.0u"°", 45.0u"°")
-AuthalicLatLon{WGS84}(45.0u"°", 45.0u"°")
+AuthalicLatLon{WGS84Latest}(45.0u"°", 45.0u"°")
 ```
 """
 struct AuthalicLatLon{Datum,D<:Deg} <: Geographic{Datum}
@@ -148,7 +148,7 @@ AuthalicLatLon{Datum}(lat::Rad, lon::Rad) where {Datum} = AuthalicLatLon{Datum}(
 AuthalicLatLon{Datum}(lat::Number, lon::Number) where {Datum} =
   AuthalicLatLon{Datum}(addunit(lat, u"°"), addunit(lon, u"°"))
 
-AuthalicLatLon(args...) = AuthalicLatLon{WGS84}(args...)
+AuthalicLatLon(args...) = AuthalicLatLon{WGS84Latest}(args...)
 
 # ------------
 # CONVERSIONS

src/crs/projected/eqareacylindrical.jl

@@ -20,7 +20,7 @@ EqualAreaCylindrical{latₜₛ,Datum}(x::Len, y::Len) where {latₜₛ,Datum} =
 EqualAreaCylindrical{latₜₛ,Datum}(x::Number, y::Number) where {latₜₛ,Datum} =
   EqualAreaCylindrical{latₜₛ,Datum}(addunit(x, u"m"), addunit(y, u"m"))
 
-EqualAreaCylindrical{latₜₛ}(args...) where {latₜₛ} = EqualAreaCylindrical{latₜₛ,WGS84}(args...)
+EqualAreaCylindrical{latₜₛ}(args...) where {latₜₛ} = EqualAreaCylindrical{latₜₛ,WGS84Latest}(args...)
 
 """
     Lambert(x, y)
@@ -36,7 +36,7 @@ Lambert(1, 1) # add default units
 Lambert(1u"m", 1u"m") # integers are converted converted to floats
 Lambert(1.0u"km", 1.0u"km") # length quantities are converted to meters
 Lambert(1.0u"m", 1.0u"m")
-Lambert{WGS84}(1.0u"m", 1.0u"m")
+Lambert{WGS84Latest}(1.0u"m", 1.0u"m")
 ```
 
 See [ESRI:54034](https://epsg.io/54034).
@@ -57,7 +57,7 @@ Behrmann(1, 1) # add default units
 Behrmann(1u"m", 1u"m") # integers are converted converted to floats
 Behrmann(1.0u"km", 1.0u"km") # length quantities are converted to meters
 Behrmann(1.0u"m", 1.0u"m")
-Behrmann{WGS84}(1.0u"m", 1.0u"m")
+Behrmann{WGS84Latest}(1.0u"m", 1.0u"m")
 ```
 
 See [ESRI:54017](https://epsg.io/54017).
@@ -78,7 +78,7 @@ GallPeters(1, 1) # add default units
 GallPeters(1u"m", 1u"m") # integers are converted converted to floats
 GallPeters(1.0u"km", 1.0u"km") # length quantities are converted to meters
 GallPeters(1.0u"m", 1.0u"m")
-GallPeters{WGS84}(1.0u"m", 1.0u"m")
+GallPeters{WGS84Latest}(1.0u"m", 1.0u"m")
 ```
 """
 const GallPeters{Datum} = EqualAreaCylindrical{45.0u"°",Datum}

src/crs/projected/eqdistcylindrical.jl

@@ -20,7 +20,7 @@ EquidistantCylindrical{latₜₛ,Datum}(x::Len, y::Len) where {latₜₛ,Datum}
 EquidistantCylindrical{latₜₛ,Datum}(x::Number, y::Number) where {latₜₛ,Datum} =
   EquidistantCylindrical{latₜₛ,Datum}(addunit(x, u"m"), addunit(y, u"m"))
 
-EquidistantCylindrical{latₜₛ}(args...) where {latₜₛ} = EquidistantCylindrical{latₜₛ,WGS84}(args...)
+EquidistantCylindrical{latₜₛ}(args...) where {latₜₛ} = EquidistantCylindrical{latₜₛ,WGS84Latest}(args...)
 
 """
     PlateCarree(x, y)
@@ -36,7 +36,7 @@ PlateCarree(1, 1) # add default units
 PlateCarree(1u"m", 1u"m") # integers are converted converted to floats
 PlateCarree(1.0u"km", 1.0u"km") # length quantities are converted to meters
 PlateCarree(1.0u"m", 1.0u"m")
-PlateCarree{WGS84}(1.0u"m", 1.0u"m")
+PlateCarree{WGS84Latest}(1.0u"m", 1.0u"m")
 ```
 
 See [EPSG:32662](https://epsg.io/32662).

src/crs/projected/mercator.jl

@@ -16,7 +16,7 @@ Mercator(1, 1) # add default units
 Mercator(1u"m", 1u"m") # integers are converted converted to floats
 Mercator(1.0u"km", 1.0u"km") # length quantities are converted to meters
 Mercator(1.0u"m", 1.0u"m")
-Mercator{WGS84}(1.0u"m", 1.0u"m")
+Mercator{WGS84Latest}(1.0u"m", 1.0u"m")
 ```
 
 See [EPSG:3395](https://epsg.io/3395).
@@ -31,7 +31,7 @@ Mercator{Datum}(x::Met, y::Met) where {Datum} = Mercator{Datum}(promote(x, y)...
 Mercator{Datum}(x::Len, y::Len) where {Datum} = Mercator{Datum}(uconvert(u"m", x), uconvert(u"m", y))
 Mercator{Datum}(x::Number, y::Number) where {Datum} = Mercator{Datum}(addunit(x, u"m"), addunit(y, u"m"))
 
-Mercator(args...) = Mercator{WGS84}(args...)
+Mercator(args...) = Mercator{WGS84Latest}(args...)
 
 # ------------
 # CONVERSIONS

src/crs/projected/orthographic.jl

@@ -21,7 +21,7 @@ Orthographic{lat₀,lon₀,S,Datum}(x::Len, y::Len) where {lat₀,lon₀,S,Datum
 Orthographic{lat₀,lon₀,S,Datum}(x::Number, y::Number) where {lat₀,lon₀,S,Datum} =
   Orthographic{lat₀,lon₀,S,Datum}(addunit(x, u"m"), addunit(y, u"m"))
 
-Orthographic{lat₀,lon₀,S}(args...) where {lat₀,lon₀,S} = Orthographic{lat₀,lon₀,S,WGS84}(args...)
+Orthographic{lat₀,lon₀,S}(args...) where {lat₀,lon₀,S} = Orthographic{lat₀,lon₀,S,WGS84Latest}(args...)
 
 """
     OrthoNorth(x, y)
@@ -37,7 +37,7 @@ OrthoNorth(1, 1) # add default units
 OrthoNorth(1u"m", 1u"m") # integers are converted converted to floats
 OrthoNorth(1.0u"km", 1.0u"km") # length quantities are converted to meters
 OrthoNorth(1.0u"m", 1.0u"m")
-OrthoNorth{WGS84}(1.0u"m", 1.0u"m")
+OrthoNorth{WGS84Latest}(1.0u"m", 1.0u"m")
 ```
 """
 const OrthoNorth{Datum} = Orthographic{90.0u"°",0.0u"°",false,Datum}
@@ -56,7 +56,7 @@ OrthoSouth(1, 1) # add default units
 OrthoSouth(1u"m", 1u"m") # integers are converted converted to floats
 OrthoSouth(1.0u"km", 1.0u"km") # length quantities are converted to meters
 OrthoSouth(1.0u"m", 1.0u"m")
-OrthoSouth{WGS84}(1.0u"m", 1.0u"m")
+OrthoSouth{WGS84Latest}(1.0u"m", 1.0u"m")
 ```
 """
 const OrthoSouth{Datum} = Orthographic{-90.0u"°",0.0u"°",false,Datum}

src/crs/projected/robinson.jl

@@ -16,7 +16,7 @@ Robinson(1, 1) # add default units
 Robinson(1u"m", 1u"m") # integers are converted converted to floats
 Robinson(1.0u"km", 1.0u"km") # length quantities are converted to meters
 Robinson(1.0u"m", 1.0u"m")
-Robinson{WGS84}(1.0u"m", 1.0u"m")
+Robinson{WGS84Latest}(1.0u"m", 1.0u"m")
 ```
 
 See [ESRI:54030](https://epsg.io/54030).
@@ -31,7 +31,7 @@ Robinson{Datum}(x::Met, y::Met) where {Datum} = Robinson{Datum}(promote(x, y)...
 Robinson{Datum}(x::Len, y::Len) where {Datum} = Robinson{Datum}(uconvert(u"m", x), uconvert(u"m", y))
 Robinson{Datum}(x::Number, y::Number) where {Datum} = Robinson{Datum}(addunit(x, u"m"), addunit(y, u"m"))
 
-Robinson(args...) = Robinson{WGS84}(args...)
+Robinson(args...) = Robinson{WGS84Latest}(args...)
 
 # ------------
 # CONVERSIONS

src/crs/projected/webmercator.jl

@@ -16,7 +16,7 @@ WebMercator(1, 1) # add default units
 WebMercator(1u"m", 1u"m") # integers are converted converted to floats
 WebMercator(1.0u"km", 1.0u"km") # length quantities are converted to meters
 WebMercator(1.0u"m", 1.0u"m")
-WebMercator{WGS84}(1.0u"m", 1.0u"m")
+WebMercator{WGS84Latest}(1.0u"m", 1.0u"m")
 ```
 
 See [EPSG:3857](https://epsg.io/3857).
@@ -31,7 +31,7 @@ WebMercator{Datum}(x::Met, y::Met) where {Datum} = WebMercator{Datum}(promote(x,
 WebMercator{Datum}(x::Len, y::Len) where {Datum} = WebMercator{Datum}(uconvert(u"m", x), uconvert(u"m", y))
 WebMercator{Datum}(x::Number, y::Number) where {Datum} = WebMercator{Datum}(addunit(x, u"m"), addunit(y, u"m"))
 
-WebMercator(args...) = WebMercator{WGS84}(args...)
+WebMercator(args...) = WebMercator{WGS84Latest}(args...)
 
 # ------------
 # CONVERSIONS

src/crs/projected/winkeltripel.jl

@@ -12,7 +12,7 @@ Winkel{lat₁,Datum}(x::Met, y::Met) where {lat₁,Datum} = Winkel{lat₁,Datum}
 Winkel{lat₁,Datum}(x::Len, y::Len) where {lat₁,Datum} = Winkel{lat₁,Datum}(uconvert(u"m", x), uconvert(u"m", y))
 Winkel{lat₁,Datum}(x::Number, y::Number) where {lat₁,Datum} = Winkel{lat₁,Datum}(addunit(x, u"m"), addunit(y, u"m"))
 
-Winkel{lat₁}(args...) where {lat₁} = Winkel{lat₁,WGS84}(args...)
+Winkel{lat₁}(args...) where {lat₁} = Winkel{lat₁,WGS84Latest}(args...)
 
 """
     WinkelTripel(x, y)
@@ -28,7 +28,7 @@ WinkelTripel(1, 1) # add default units
 WinkelTripel(1u"m", 1u"m") # integers are converted converted to floats
 WinkelTripel(1.0u"km", 1.0u"km") # length quantities are converted to meters
 WinkelTripel(1.0u"m", 1.0u"m")
-WinkelTripel{WGS84}(1.0u"m", 1.0u"m")
+WinkelTripel{WGS84Latest}(1.0u"m", 1.0u"m")
 ```
 
 See [ESRI:54042](https://epsg.io/54042).

src/datums.jl

@@ -37,6 +37,13 @@ Returns the altitude origin of the datum type `D`.
 """
 function altitudeₒ end
 
+"""
+    epoch(D)
+
+Returns the reference epoch of the datum type `D`.
+"""
+function epoch end
+
 """
     NoDatum
 
@@ -48,17 +55,63 @@ ellipsoid(::Type{NoDatum}) = nothing
 latitudeₒ(::Type{NoDatum}) = nothing
 longitudeₒ(::Type{NoDatum}) = nothing
 altitudeₒ(::Type{NoDatum}) = nothing
+epoch(::Type{NoDatum}) = nothing
 
 """
-    WGS84
+    WGS84{GPSWeek}
 
-WGS84 (World Geodetic System) datum.
+WGS84 (World Geodetic System) datum with a given realization `GPSWeek` (default to 1762).
+Currentry, WGS84 has six realizations in the following GPS weeks:
+0, 730, 873, 1150, 1674 and 1762.
 
-See [World Geodetic System](https://en.wikipedia.org/wiki/World_Geodetic_System)
+`WGS84Latest` is an alias to `WGS84{2020}`.
+
+See [NGA - WORLD GEODETIC SYSTEM 1984](https://nsgreg.nga.mil/doc/view?i=4085)
 """
-abstract type WGS84 <: Datum end
+abstract type WGS84{GPSWeek} <: Datum end
+
+const WGS84Latest = WGS84{1762}
+
+ellipsoid(::Type{<:WGS84}) = WGS84🌎
+latitudeₒ(::Type{<:WGS84}) = 0.0u"°"
+longitudeₒ(::Type{<:WGS84}) = 0.0u"°"
+altitudeₒ(::Type{<:WGS84}) = 0.0u"m"
 
-ellipsoid(::Type{WGS84}) = WGS84🌎
-latitudeₒ(::Type{WGS84}) = 0.0u"°"
-longitudeₒ(::Type{WGS84}) = 0.0u"°"
-altitudeₒ(::Type{WGS84}) = 0.0u"m"
+epoch(::Type{WGS84{0}}) = nothing
+epoch(::Type{WGS84{730}}) = 1994.0
+epoch(::Type{WGS84{873}}) = 1997.0
+epoch(::Type{WGS84{1150}}) = 2001.0
+epoch(::Type{WGS84{1674}}) = 2005.0
+epoch(::Type{WGS84{1762}}) = 2005.0
+
+"""
+    ITRF{Year}
+
+ITRF (International Terrestrial Reference Frame) datum with a given realization `Year` (default to 2020).
+Currentry, ITRF has eleven realizations in the following years:
+1991, 1992, 1993, 1994, 1996, 1997, 2000, 2005, 2008, 2014 and 2020.
+
+`ITRFLatest` is an alias to `ITRF{2020}`.
+
+See [The International Terrestrial Reference Frame (ITRF)](https://www.iers.org/IERS/EN/DataProducts/ITRF/itrf.html)
+"""
+abstract type ITRF{Year} end
+
+const ITRFLatest = ITRF{2020}
+
+ellipsoid(::Type{<:ITRF}) = GRS80🌎
+latitudeₒ(::Type{<:ITRF}) = 0.0u"°"
+longitudeₒ(::Type{<:ITRF}) = 0.0u"°"
+altitudeₒ(::Type{<:ITRF}) = 0.0u"m"
+
+epoch(::Type{ITRF{1991}}) = 1988.0
+epoch(::Type{ITRF{1992}}) = 1988.0
+epoch(::Type{ITRF{1993}}) = 1988.0
+epoch(::Type{ITRF{1994}}) = 1993.0
+epoch(::Type{ITRF{1996}}) = 1997.0
+epoch(::Type{ITRF{1997}}) = 1997.0
+epoch(::Type{ITRF{2000}}) = 1997.0
+epoch(::Type{ITRF{2005}}) = 2000.0
+epoch(::Type{ITRF{2008}}) = 2005.0
+epoch(::Type{ITRF{2014}}) = 2010.0
+epoch(::Type{ITRF{2020}}) = 2015.0