Most used projections implemented

  • Mercator
  • Transverse Mercator
  • Lambert Conformal Conic.
  • Miller
  • Eqc


Coordinates reference systems (crs) linked to these projections are available within python API using epsg id or name.

Four main grids are available:

  • Universal Transverse Mercator
  • Military Grid Reference System
  • British National Grid
  • Irish National Grid.

Raster map interpolation

Gryd.Crs provides functions for raster map coordinates interpolation using calibration Points (two minimum are required).

Geodesic object

See Gryd.geodesy module



Return list of tuples (name and epsg reference) available in the sqlite database.


  • cls Gryd.Epsg - Epsg instance


(str, int) list

Geocentric Objects

class Geocentric(ctypes.Structure)

ctypes structure for geocentric coordinates. This reference is generaly used as a transition for datum conversion.


  • x float - X-axis value
  • y float - Y-axis value
  • z float - Z-axis value
>>> Gryd.Geocentric(4457584, 429216, 4526544)
<X=4457584.000 Y=429216.000 Z=4526544.000>
>>> Gryd.Geocentric(x=4457584, y=429216, z=4526544)
<X=4457584.000 Y=429216.000 Z=4526544.000>

Point Objects

class Point(ctypes.Structure)

ctypes structure for calibration point. It is used for coordinates interpolation on a raster image. Two points minimum are required.


  • px float - pixel column position
  • py float - pixel row position
  • lla Gryd.Geodesic - geodesic coordinates associated to the pixel coordinates
  • xya Gryd.Geographic - geographic coordinates associated to the pixel coordinates

Vincenty_dist Objects

class Vincenty_dist(ctypes.Structure)

Great circle distance computation result using Vincenty formulae. Vincenty_dist structures are returned by Gryd.Ellipsoid.distance function.


  • distance float - great circle distance in meters
  • initial_bearing float - initial bearing in degrees
  • final_bearing float - final bearing in degrees

Vincenty_dest Objects

class Vincenty_dest(ctypes.Structure)

Great circle destination computation result using Vincenty formulae. Vincenty_dist structures are returned by Gryd.Ellipsoid.destination function.


  • longitude float - destination longitude in degrees
  • latitude float - destination latitude in degrees
  • destination_bearing float - destination bearing in degrees

Dms Objects

class Dms(ctypes.Structure)

Degrees Minutes Seconde value of a float value. Dms structure are returned by Gryd.dms function.

>>> d = Gryd.dms(-60.42286847222222)
>>> d
>>> float(d)


  • sign int - 1 if positive, -1 if negative
  • degree float - integer parts of value
  • minute float - 1/60 fractions of value
  • second float - 1/3600 fractions of value

Dmm Objects

class Dmm(ctypes.Structure)

Degrees Minutes value of a float value. Dmm structure are returned by Gryd.dmm function.

>>> d = Gryd.dmm(-60.42286847222222)
>>> d
>>> float(d)


  • sign int - 1 if positive, -1 if negative
  • degree float - integer parts of value
  • minute float - 1/60 fractions of value

Epsg Objects

class Epsg(ctypes.Structure)

ctypes structure with a sqlite connection to EPSG database for initialization purpose.


Shared sqlite database to be linked with


The table database name where __init__ will find data


 | __init__(*args, **pairs)

If list of values is given as *args, structure members are initialized in the order of the field definition. If *args only contains one value:

  • it is a dict then it is used as a reccord
  • it is an int then try to get a record from database using epsg id
  • it is a str then try to get a record from database using epsg name

All values in **pairs are merged in the record before attributes initialization.

if an attribute is not defined in the _fields_ list, it is set to the python part of the class, not the ctypes structure.

Unit Objects

class Unit(Epsg)

Unit ratio relative to meter.

>>> Gryd.Unit(9001)
<Unit epsg=9001 ratio=1.0>
>>> Gryd.Unit(epsg=9001).name
>>> Gryd.Unit(name="foot")
<Unit epsg=9002 ratio=3.2808693302666354>
>>> float(Gryd.Unit(name="foot"))


  • epsg int - EPSG reference
  • ratio float - coeficient to apply for metter conversion

Prime Objects

class Prime(Epsg)

Prime meridian.

>>> prime = Gryd.Prime(epsg=8902)
>>> prime
<Prime meridian epsg=8902 longitude=-009°07'54.862''>


  • epsg int - EPSG reference
  • longitude float - latitude value

Ellipsoid Objects

class Ellipsoid(Epsg)

Ellipsoid model. If initialized with no args nor keyword args, it is a 6378137-meters-radius sphere.

>>> wgs84 = Gryd.Ellipsoid("WGS 84")
>>> wgs84
<Ellispoid epsg=7030 a=6378137.000000 1/f=298.25722356>


  • epsg int - EPSG reference
  • a float - semi major axis
  • b float - semi minor axis
  • e float - exentricity
  • f float - flattening


 | distance(lla0, lla1)

Return Vincenty distance between two geodesic points.

>>> london = Gryd.Geodesic(-0.127005, 51.518602, 0.)
>>> dublin = Gryd.Geodesic(-6.259437, 53.350765, 0.)
>>> wgs84.distance(dublin, london)
<Dist 464.025km initial bearing=113.6 final bearing=118.5°>


  • lla0 Gryd.Geodesic - point A
  • lla1 Gryd.Geodesic - point B


Gryd.Vincenty_dist structure


 | destination(lla, bearing, distance)

Return Vincenty destination from geodesic start point following specific bearing with a determined distance.

>>> wgs84.destination(
...     london, math.degrees(vdist.final_bearing) + 180, vdist.distance
... )
<Dest lon=-006°15'33.973'' lat=+053°21'2.754'' end bearing=-66.4°>
>>> dublin
<lon=-006°15'33.973'' lat=+053°21'2.754'' alt=0.000>


  • lla Gryd.Geodesic - start point
  • bearing float - start bearing in degrees
  • distance float - distance in meters


Gryd.Vincenty_dest structure


 | npoints(lla0, lla1, n)

Return number of intermediary geodesic coordinates points between two points using Vincenty formulae.

>>> for p in wgs84.npoints(dublin, londre, 4): print(p)
<Dest lon=-006°15'33.973'' lat=+053°21'2.754'' end bearing=113.6>
<Dest lon=-004°59'32.422'' lat=+053°00'36.687'' end bearing=114.6>
<Dest lon=-003°44'43.501'' lat=+052°39'22.715'' end bearing=115.6>
<Dest lon=-002°31'7.792'' lat=+052°17'22.201'' end bearing=116.6>
<Dest lon=-001°18'45.650'' lat=+051°54'36.502'' end bearing=117.5>
<Dest lon=-000°07'37.218'' lat=+051°31'6.967'' end bearing=118.5>


  • lla0 Gryd.Geodesic - start point
  • lla1 Gryd.Geodesic - end point
  • n int - number uf intermediary points


list of Gryd.Vincenty_dest (start, *intermediaries, end)

Datum Objects

class Datum(Epsg)

Datum is defined by an ellipsoid, a prime meridian and a set of seven parameters to convert geodesic coordinates to wgs84.

>>> Gryd.Datum(epsg=4326)
<Datum epsg=4326:
<Ellispoid epsg=7030 a=6378137.000000 1/f=298.25722356>
<Prime meridian epsg=8901 longitude=0.000000>
to wgs84: 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0>


  • epsg int - EPSG reference
  • prime Gryd.Prime - prime meridian
  • ellispoid Gryd.Ellipsoid - ellipsoid
  • ds float - expansion coef
  • dx float - x-axis translation coef
  • dy float - y-axis translation coef
  • dz float - z-axis translation coef
  • rx float - x-axis rotation coef
  • ry float - y-axis rotation coef
  • rz float - z-axis rotation coef


 | xyz(lla)

Convert geodesic coordinates to geocentric coordinates.

<X=3977018.848 Y=-8815.695 Z=4969650.564>


  • lla Gryd.Geodesic - geodesic coordinates


Gryd.Geocentric coordinates


 | lla(xyz)

Convert geocentric coordinates to geodesic coordinates.

>>> wgs84.lla(
<lon=-000°07'37.218'' lat=+051°31'6.967'' alt=0.000>
>>> london
<lon=-000°07'37.218'' lat=+051°31'6.967'' alt=0.000>


  • xyz Gryd.Geodesic - geocentric coordinates


Gryd.Geodesic coordinates


 | transform(dst, lla)

Transform geodesic coordinates to another datum.

>>> airy = Gryd.Datum(epsg=4277)
>>> wgs84.transform(airy, london)
<lon=-000°07'31.431'' lat=+051°31'5.137'' alt=-46.118>


  • dst Gryd.Datum - destination datum
  • lla Gryd.Geodesic - geodesic coordinates to transform


Gryd.Geodesic coordinates

Crs Objects

class Crs(Epsg)

Coordinate reference system object allowing projection of geodesic coordinates to flat map (geographic coordinates).

>>> pvs = Gryd.Crs(epsg=3785)
>>> osgb36 = Gryd.Crs(epsg=27700)
<X=3976632.017 Y=-8814.837 Z=4969286.446>
>>> osgb36.datum.ellipsoid.distance(dublin, london)
<Dist 463.981km initial bearing=113.6° final bearing=118.5°>
>>> osgb36
<Crs epsg=27700:
<Datum epsg=4277:
<Ellispoid epsg=7001 a=6377563.396000 1/f=299.32496460>
<Prime meridian epsg=8901 longitude=0.000000>
to wgs84 446.45,-125.16,542.06,-20.49,0.15,0.25,0.84>
<Unit epsg=9001 ratio=1.0>
Projection 'tmerc'>


  • epsg int - EPSG reference
  • datum Gryd.Datum - prime used in crs
  • unit Gryd.Unit - unit used in crs
  • lambda0 float - tmerc projection coef
  • phi0 float - tmerc and omerc projection coef
  • phi1 float - lcc projection coef
  • phi2 float - lcc projection coef
  • k0 float - tmerc projection coef
  • x0 float - false northing
  • y0 float - false easting
  • azimut float - omerc projection coef


 | __reduce__()

special method that allows Gryd.Crs instance to be pickled


 | __call__(element)

Heuristic transformation according to crs properties.

>>> osgb36(london)  # projection of Geodesic point
<X=529939.106 Y=181680.962s alt=0.000>
>>> osgb36(osgb36(london))  # deprojection of Geographic point
<lon=-000°07'37.218'' lat=+051°31'6.967'' alt=0.000>


  • element Gryd.Geodesic or Gryd.Geographic - coordinates to be transformed


Gryd.Geographic or Gryd.Geodesic coordinates


 | transform(dst, xya)

Transform geographical coordinates to another coordinate reference system.

>>> london_pvs = osgb36.transform(pvs, osgb36(london))
>>> london_pvs
<X=-14317.072 Y=6680144.273s alt=-13015.770>
>>> pvs.transform(osgb36, london_pvs)
<X=529939.101 Y=181680.963s alt=0.012>
>>> osgb36(london)
<X=529939.106 Y=181680.962s alt=0.000>


  • dst Gryd.Crs - destination coordinate reference system
  • xya Gryd.Geographic - geographic coordinates to transform


Gryd.Geographic coordinates


 | add_map_point(px, py, point)

Add a calibration point to coordinate reference system. Calibration points maps a specific pixel coordinates from a raster image (top left reference) to a geodesic coordinates and its associated geographic ones.

>>> # 512x512 pixel web map mercator
>>> pvs.add_map_point(0,0, Gryd.Geodesic(-179.999, 85))
>>> pvs.add_map_point(512,512, Gryd.Geodesic(179.999, -85))
>>> pvs.map_points
[<px=0 py=0
<lon=-179°59'56.400'' lat=+085°00'0.000'' alt=0.000>
<X=-20037397.023 Y=19971868.880s alt=0.000>
>, <px=512 py=512
<lon=+179°59'56.400'' lat=-085°00'0.000'' alt=0.000>
<X=20037397.023 Y=-19971868.880s alt=0.000>


  • px float - pixel column position
  • py float - pixel row position
  • point Gryd.Geodesic or Gryd.Geographic - geodesic or geographic coordinates


 | delete_map_point(*points_or_indexes)

Delete multiple calibration points using index (starting with 1) or Gryd.Point reference.

[<px=512 py=512
<lon=+179°59'56.400'' lat=-085°00'0.000'' alt=0.000>
<X=20037397.023 Y=-19971868.880s alt=0.000>
>>> pvs.delete_map_point(pvs.map_points[0])
[<px=0 py=0
<lon=-179°59'56.400'' lat=+085°00'0.000'' alt=0.000>
<X=-20037397.023 Y=19971868.880s alt=0.000>
>>> pvs.map_points


  • *points_or_indexes int or Gryd.Point - index (starting with 1) or point reference


list of deleted Gryd.Point


 | map2crs(px, py, geographic=False)

Geodesic or geographic interpolation on raster image from pixel coordinates.

>>> pvs.map2crs(256+128, 256+128)
<lon=+089°59'58.20'' lat=-066°23'43.74'' alt=0.000>
>>> pvs.map2crs(256-128, 256+128, geographic=True)
<point X=-10018698.512 Y=-9985934.440s alt=0.000>


  • px float - pixel column position
  • py float - pixel row position
  • geographic bool - determine coordinates type returned


Gryd.Geographic if geographic is True else Gryd.Geodesic


 | crs2map(point)

Pixel interpolation on raster image from geodesic point.

>>> pvs.crs2map(london)
<px=256 py=170
<lon=-000°07'37.218'' lat=+051°31'6.967'' alt=0.000>
<X=-14138.132 Y=6713546.215s alt=0.000>
>>> pvs.crs2map(dublin)
<px=247 py=166
<lon=-006°15'33.973'' lat=+053°21'2.754'' alt=0.000>
<X=-696797.339 Y=7048145.354s alt=0.000>


  • point Gryd.Geodesic or Gryd.Geographic - geodesic or geographic coordinates