Wolfram Language & System 11.0 (2016)|Legacy Documentation

This is documentation for an earlier version of the Wolfram Language.View current documentation (Version 11.2)

GeoGraphics

Since Version 10.0 of the Wolfram Language, GeoGraphics allows a simple and general way of constructing maps of the surface of the Earth and other celestial bodies. GeoGraphics combines the powerful Graphics functionality with fast and highly precise geodetic computations and also direct access to the Wolfram Knowledgebase through the Entity framework.

The fundamental new ingredient in GeoGraphics with respect to standard 2D Graphics is the fact that the surface of the Earth is curved and therefore must be distorted to produce a flat map (on a piece of paper or the computer screen). This always requires a choice of a cartographic projection, a function that determines how points on the curved surface are mapped to points on the flat map. The GeoProjectionData paclet provides a large collection of projections.

GeoGraphics also introduces new graphical primitives like GeoPath, GeoDisk, and GeoHemisphere, adapted to the Earth's curvature, and even time-dependent geo primitives like DayHemisphere and DayNightTerminator.

The GeoGraphics functionality can easily access the Wolfram Knowledgebase to obtain geographical information using the Entity framework, providing homogeneous access to a large number of properties about dozens of types of objects, from countries and cities to bridges, earthquakes, and artificial satellites.

GeoGraphics is also fully integrated with the geodesy functionality of the Wolfram Language, extensively updated for Version 10.0. This functionality is now much faster and precise to millimeters on the surface of the ellipsoidal Earth. GeoPosition allows specification of any position on the Earth, in any of the large collection of ellipsoids of GeodesyDatafor example, the WGS84 reference used by GPS satellites.

This tutorial provides an introduction to GeoGraphics and its associated functions. The tutorial starts by showing how to easily construct maps of arbitrary regions or geographical entities, letting GeoGraphics choose appropriate coordinate ranges, projections, etc. for you. Then it explains how you can choose all those options to fine-tune the maps to your needs.

Basic Mapping

The simplest and most important operation is obtaining a map of a given region of interest. The Entity framework provides a fast and homogeneous way to obtain the required positional information. GeoGraphics will then choose an adequate projection, generally the "Mercator" projection for small to medium scales (under 2000 km diagonally, approximately).

GeoGraphics[primitives,options]draw a map

Main mapping command.

A map of France. Type CTRL= and then the word "France" to get the entity.
In[1]:=
Click for copyable input
Out[1]=
A map of New York City.
In[2]:=
Click for copyable input
Out[2]=

With no argument specification, GeoGraphics gives by default a map of your local area, as determined by $GeoLocation, with a radius of around 10 miles.

The current $GeoLocation, returned as a GeoPosition[{lat,lon}] object.
In[3]:=
Click for copyable input
Out[3]=
A map around that geo location.
In[4]:=
Click for copyable input
Out[4]=

Maps of the whole world are obtained by using the option value GeoRange->"World". Such maps are given by default using the so-called "Equirectangular" projection, in which the horizontal axis is exactly longitude and the vertical axis is exactly latitude. Similarly, GeoRange->"Country" gives a map of your country, and GeoGraphics will choose a projection that minimizes distortion of the map.

A map of the world.
In[5]:=
Click for copyable input
Out[5]=
A map of your country, again as determined by $GeoLocation.
In[6]:=
Click for copyable input
Out[6]=
Discover which projection was used.
In[7]:=
Click for copyable input
Out[7]=
Or which ranges of latitude and longitude (in degrees) were selected.
In[8]:=
Click for copyable input
Out[8]=

The options GeoRange, GeoRangePadding, GeoCenter, and GeoZoomLevel allow multiple ways of specifying the regions of interest. They will be studied in detail later on in this tutorial.

Give explicitly the ranges of latitude and longitude.
In[9]:=
Click for copyable input
Out[9]=
Add 10 kilometers of padding in all directions.
In[10]:=
Click for copyable input
Out[10]=
Specify a center and a zoom level.
In[11]:=
Click for copyable input
Out[11]=
You can also change the zoom level of an image without changing its geo range. This results in increasingly more detail.
In[12]:=
Click for copyable input
Out[12]=
But then maps are increasingly larger in size.
In[13]:=
Click for copyable input
Out[13]=

So far maps have been produced showing the geo background image corresponding to a given region. The GeoGraphics language provides a variety of objects, called geo primitives, that can be placed on the map. These geo primitives can be point-like (Point or GeoMarker), line-like (GeoPath, GeoCircle, Line, ...), or area-like (GeoDisk, GeoHemisphere, Polygon, ...).

Place markers at the capitals of South America.
In[14]:=
Click for copyable input
Out[14]=
The geodesic curve from Santiago de Chile to Madrid. It is not a straight line in this projection.
In[15]:=
Click for copyable input
Out[15]=
A disk of 60 miles around Chicago, by default with low opacity so that it can be seen through.
In[16]:=
Click for copyable input
Out[16]=
A polygon covering the United States, again with default low opacity.
In[17]:=
Click for copyable input
Out[17]=

There are multiple ways to stylize a map. You can add parallels and meridians, a scale bar, or change the geo background to depict a relief map of elevation data or a contour plot. You can change colors and opacities, or even place images inside 2D geo primitives like geo disks or polygonsand many more options.

A map of Spain and Portugal with latitude and longitude lines separated 1 degree and a scale bar in kilometers.
In[18]:=
Click for copyable input
Out[18]=
A relief map of the same area showing geo elevation data.
In[19]:=
Click for copyable input
Out[19]=
Place the Spanish flag over the country.
In[20]:=
Click for copyable input
Out[20]=

Maps of other celestial bodies (planets and moons) are also possible.

The near side of the Moon (longitude 0 is defined to be oriented toward Earth).
In[21]:=
Click for copyable input
Out[21]=
A map of the area around Olympus Mons on Mars.
In[22]:=
Click for copyable input
Out[22]=

Geographical Locations and Computations

GeoPosition and Geo Entities

Specific locations on the Earth are given as GeoPosition[{lat,lon}] objects, with latitude and longitude coordinates given in degrees, with standard conventions. GeoPosition can also convert other forms of input into that notation for convenience, including geographical Entity and EntityClass objects.

GeoPosition[{lat,lon}]position on the surface of the Earth
Entity["type",name]entity of a given type
EntityClass["type",name]class of entities of a given type, equivalent to a list of entities

Location specification.

The coordinates of the North Pole.
In[23]:=
Click for copyable input
Out[23]=
They can also be obtained as follows.
In[24]:=
Click for copyable input
Out[24]=
Coordinates can also be provided in degree-minute-second (DMS) string form.
In[25]:=
Click for copyable input
Out[25]=
In[26]:=
Click for copyable input
Out[26]=
Give angles as Quantity objects, in any unit.
In[27]:=
Click for copyable input
Out[27]=
Convert geographical Entity data into numeric coordinates.
In[28]:=
Click for copyable input
Out[28]=
In[29]:=
Click for copyable input
Out[29]=
Internally, GeoPosition calls EntityValue to get that information.
In[30]:=
Click for copyable input
Out[30]=

GeoPosition can also handle arrays of coordinates. This is useful for working efficiently with many points at the same time. Points of the array can be given in different notations, and GeoPosition will convert them all to numeric coordinates.

Convert a list of entities.
In[31]:=
Click for copyable input
Out[31]=
In[32]:=
Click for copyable input
Out[32]=
In[33]:=
Click for copyable input
Out[33]=
An EntityClass object is interpreted as representing the list of its members.
In[34]:=
Click for copyable input
Out[34]=
Extract geo location EXIF information from a picture.
In[35]:=
Click for copyable input
Out[35]=
Convert different types of objects simultaneously.
In[36]:=
Click for copyable input
Out[36]=

Distances and Bearings (Angles)

Together with the coordinate positions of given locations, it is generally important to know distances between any two of them, as well as the compass direction you need to follow to go from one to another. Distances are computed along geodesics, i.e. basically the shortest curve between two positions. Angles are given as bearings, namely the angle from the north to that geodesic line, measured clockwise in degrees. In the Wolfram Language, distances on the surface of the Earth are measured with GeoDistance, and bearings are computed with GeoDirection.

GeoDistance[loc1,loc2]geodesic distance between two locations
GeoDirection[loc1,loc2]angle from north at loc1 of the geodesic from loc1 to loc2
GeoDisplacement[loc1,loc2]distance and angle at loc1 of the geodesic from loc1 to loc2
GeoDestination[loc1,displ]end position of the geodesic given by displ starting at loc1

Geodesic displacements.

Take the approximate center positions of two cities.
In[37]:=
Click for copyable input
Out[37]=
Out[38]=
This is the geodesic between those points.
In[39]:=
Click for copyable input
Out[39]=
Distance between them.
In[40]:=
Click for copyable input
Out[40]=
The result is given as a Quantity object with units determined by your $UnitSystem.
In[41]:=
Click for copyable input
Out[41]=
To change to any other unit, use UnitConvert.
In[42]:=
Click for copyable input
Out[42]=
You can also modify the unit system required in the GeoDistance call itself.
In[43]:=
Click for copyable input
Out[43]=

You can use the Entity objects directly to compute distances, but then the Wolfram Language functions try to use polygonal information, when available, rather than purely point-like positions. That means that GeoDistance will return the smallest possible distance when considering all points of the polygons.

Distance between the borders of New York and Paris.
In[44]:=
Click for copyable input
Out[44]=
It is smaller than the distance obtained before from center to center.
In[45]:=
Click for copyable input
Out[45]=
The distance between centers can also be computed using the DistanceFunction option of GeoDistance.
In[46]:=
Click for copyable input
Out[46]=
This map shows the position of the center with respect to the polygon of the city.
In[47]:=
Click for copyable input
Out[47]=

Bearings are computed with GeoDirection. Currently this function does not handle polygonal information, only positional information. A warning message is issued when appropriate.

This is the bearing of the geodesic from New York to Paris, measured at New York.
In[48]:=
Click for copyable input
Out[48]=
Express the result in DMS form.
In[49]:=
Click for copyable input
Out[49]=
GeoDirection always uses center positions; hence, the previous result equals the following.
In[50]:=
Click for copyable input
Out[50]=
This is the bearing of the same geodesic, but now from Paris to New York.
In[51]:=
Click for copyable input
Out[51]=
GeoDisplacement reports both distance (in meters) and bearing (in degrees).
In[52]:=
Click for copyable input
Out[52]=
Knowing the geo displacement and the initial position, it is possible to recover the final position.
In[53]:=
Click for copyable input
Out[53]=
In[54]:=
Click for copyable input
Out[54]=

Relational Positioning

Given a location, it is frequently important to know instances of a particular type of entity that are at a short distance from it. This is the role of the function GeoNearest. If the locations or entities are extended, you may also be interested in inclusion relations.

GeoNearest[enttype,loc]entities of type enttype closest to loc
GeoIdentify[enttype,loc]entities of type enttype that contain loc
GeoEntities[reg,enttype]entities of type enttype contained in the region reg
GeoWithinQ[reg,loc]check whether loc is contained in the region reg

Distance relations among entities and locations.

Find the nearest ocean or sea to your current location.
In[55]:=
Click for copyable input
Out[55]=
Find the four nearest countries to a given location, sorted by distance to the border.
In[56]:=
Click for copyable input
Out[56]=
Find all cities within 10 miles around Bath, UK, also sorted by distance.
In[57]:=
Click for copyable input
Out[57]=

Other relations are essentially derivates of GeoNearest. For example, GeoIdentify returns all entities containing a given location, by default your current geo location.

All available entities containing the current geo location.
In[58]:=
Click for copyable input
Out[58]=
They are entities of various types.
In[59]:=
Click for copyable input
Out[59]=
All administrative divisions containing Rome.
In[60]:=
Click for copyable input
Out[60]=

Vice versa, GeoEntities lists the entities contained in a given extended entity.

Level 2 administrative divisions of an administrative division of level 1.
In[61]:=
Click for copyable input
Out[61]=
Famous buildings in Dallas.
In[62]:=
Click for copyable input
Out[62]=

The function GeoWithinQ checks inclusion of a geographical location (extended or not) inside a geographical region.

Check that Chicago is inside the state of Illinois.
In[63]:=
Click for copyable input
Out[63]=
The island of Tenerife is in the Atlantic Ocean, not in the Mediterranean Sea.
In[64]:=
Click for copyable input
Out[64]=
In[65]:=
Click for copyable input
Out[65]=

All these computations are sent to the Wolfram geo server, and results are then downloaded from it. In some cases it is possible to perform the operations locally using Nearest.

This variable reports your current country.
In[66]:=
Click for copyable input
Out[66]=
Take the points of the boundary of its polygon.
In[67]:=
Click for copyable input
Out[67]=
Find out which of those points is closest to your current location.
In[68]:=
Click for copyable input
Out[68]=
Draw the geodesic as an arrow.
In[69]:=
Click for copyable input
Out[69]=

Geo Entity Variants

Sometimes you want a map of the main area of a country, without including smaller islands or dependencies that may be very far away. Or you may need a map including all territories. In those cases, the Wolfram Language specifies the additional information using the head GeoVariant.

GeoVariant[entity,variant]a geographical variant of an entity

Geo entity variants.

The default map of the US only includes the conterminous states.
In[70]:=
Click for copyable input
Out[70]=
This map includes all areas.
In[71]:=
Click for copyable input
Out[71]=
Something intermediate is given by the variant "PrincipalArea" and its downsampled form "SimplifiedArea". In this case the US map includes Alaska and Hawaii.
In[72]:=
Click for copyable input
Out[72]=
The variant used by default in the maps is called "DefaultMapArea".
In[73]:=
Click for copyable input
Out[73]=

Other geo functions can also handle geo entity variants. However, the defaults are not necessarily the same. For example, the default variants for GeoNearest are sometimes larger than the corresponding defaults in GeoGraphics.

The default geo variant in GeoNearest is "PrincipalArea".
In[74]:=
Click for copyable input
Out[74]=
Therefore, the result is different when you change the variant.
In[75]:=
Click for copyable input
Out[75]=

$GeoLocation and FindGeoLocation

The Wolfram Language can determine your approximate location using GeoIP information. This is done with FindGeoLocation, and the result is stored in the global variable $GeoLocation. The variable Here is an alternative way of accessing the current geo location. Many of the functions related to GeoGraphics will default to that position when location information is not provided. You can manually set $GeoLocation to any other position you want, and then your Wolfram Language session will behave as if you were at that position. Note that changing your $GeoLocation does not automatically change $TimeZone.

$GeoLocationresettable variable containing your current geo location
Herea simpler way to obtain your current geo location
FindGeoLocation[]find your current geo location using GeoIP information

Current location.

The current $GeoLocation.
In[76]:=
Click for copyable input
Out[76]=
This is an equivalent object.
In[77]:=
Click for copyable input
Out[77]=
Therefore, GeoGraphics[] defaults to that position.
In[78]:=
Click for copyable input
Out[78]=
Change $GeoLocation to some other position.
In[79]:=
Click for copyable input
Out[79]=
Now local maps are maps of New York.
In[80]:=
Click for copyable input
Out[80]=
Change back to your current location.
In[81]:=
Click for copyable input
Out[81]=
Use FindGeoLocation to find approximate locations for addresses.
In[82]:=
Click for copyable input
Out[82]=
In[83]:=
Click for copyable input
Out[83]=

Ranges of Coordinates and Projections

Latitude and Longitude: GeoRange

The most general way of specifying the region covered by a map in latitude and longitude coordinates is using the option GeoRange{{latmin,latmax},{lonmin,lonmax}}. As usual, the angles are given in degrees, with standard conventions. Any other specification of a geo region is eventually converted internally into one such range specification, perhaps extended as determined by the GeoRangePadding option.

GeoRangeoption of GeoGraphics that specifies the ranges of the map

Geo range specification.

GeoBounds computes the latitude and longitude ranges of any geographical region.
In[84]:=
Click for copyable input
Out[84]=
A map using the "Equirectangular" projection will show that region with axes corresponding to those coordinate ranges. When using a specific numerical geo range, there is no padding added.
In[85]:=
Click for copyable input
Out[85]=
The "World" geo range corresponds to the whole world, by default {{-90,90},{-180,180}}.
In[86]:=
Click for copyable input
Out[86]=
The two halves of the world.
In[87]:=
Click for copyable input
Out[87]=
Longitudes {lonmin,lonmax} can be given in any determination. lonmax is adjusted modulo 360 to be larger than lonmin.
In[88]:=
Click for copyable input
Out[88]=
The determination used in the longitude range is preserved in the result, though only for cylindrical projections (see types of projections below).
In[89]:=
Click for copyable input
Out[89]=

GeoCenter

An alternative way to provide a geo range is to give a center point and a distance radius, defining a geo disk on the Earth's surface. The geo range is then the rectangle in {lat,lon} coordinates that fully encloses that geo disk. This is done by using the options GeoCenter and GeoRange, the latter now containing only the distance radius.

GeoCenteroption of GeoGraphics that specifies the center of the map

Geo center specification.

A map of the area 100 miles around Dublin.
In[90]:=
Click for copyable input
Out[90]=

The GeoCenter option can also be used to select the center point of a map whose GeoRange was automatically obtained from the input. If the option GeoRange explicitly specifies a region, it will always override any other information provided by GeoCenter.

A map of Germany centered at Munich.
In[91]:=
Click for copyable input
Out[91]=
If the GeoRange option is explicit, then GeoCenter will be ignored.
In[92]:=
Click for copyable input
Out[92]=
GeoCenter also allows you to choose the center longitude for the "World" geo range.
In[93]:=
Click for copyable input
Out[93]=

Other Specifications of the Map Region

GeoGraphics accepts location information in input, not inside geo primitives. That information contributes to the specification of the ranges of the map, but nothing is rendered on the map associated to it. Again, when only center information is available, the default scale of the map is approximately 10 miles in radius.

A map around a given position. Nothing is drawn on the map.
In[94]:=
Click for copyable input
Out[94]=
This shows the scale of the map.
In[95]:=
Click for copyable input
Out[95]=
You can change the default range to anything you want.
In[96]:=
Click for copyable input
Out[96]=

When using an Entity object, GeoGraphics consults with EntityValue about whether position and polygon information exists. If a geo polygon can be obtained, then that means there is also a clear sense of scale. If a polygon cannot be obtained, then you proceed with the center position and the default scale as before.

This is the polygon surrounding San Francisco. It contains a GeoPosition object with multiple {lat,lon} pairs inside.
In[97]:=
Click for copyable input
Out[97]=
This map is scaled to contain that polygon.
In[98]:=
Click for copyable input
Out[98]=
But this other map has the standard scale of about 10 miles.
In[99]:=
Click for copyable input
Out[99]=
Currently there is no polygon information for Rome, and hence these two maps cover identical ranges.
In[100]:=
Click for copyable input
Out[100]=

Projected Coordinates

For large areas of the world, the default projection is "Equirectangular", in which the map coordinates are directly longitude and latitude. However, for smaller areas of the world it is more convenient to choose other projections, to decrease distortion. The map coordinates do not then have immediate angular meaning. For example, for low scales (approximately under 2000 km diagonally) the default projection is "Mercator", which preserves shapes. In this case, the horizontal axis still represents longitude, but the vertical axis is not latitude anymore.

The Mercator projection is frequently used in map services on the internet. However, it highly distorts distances and areas near the poles. In fact, the poles are mapped at infinite distance along the vertical axes, and therefore the Mercator projection cannot show the whole world in a map. GeoGraphics allows you to choose the projection needed, and the paclet GeoProjectionData provides one of the most extensive collections of projections available. When no explicit projection is indicated, GeoGraphics will choose an appropriate projection for you, based on the scale and center of the map.

GeoProjectionoption of GeoGraphics that specifies the cartographic projection

Geo projection specification.

These are the latitude and longitude coordinates of Berlin.
In[101]:=
Click for copyable input
Out[101]=
However, a map of Germany in the "Mercator" projection shows Berlin with different coordinates.
In[102]:=
Click for copyable input
Out[102]=
This is the projection used in the map, a "Mercator" projection, with adapted "Centering" and "GridOrigin" parameters so that the horizontal axis still represents true longitude.
In[103]:=
Click for copyable input
Out[103]=
GeoGridPosition will give you the exact coordinates in the projection chosen.
In[104]:=
Click for copyable input
Out[104]=
You can now force that projection in the same map, obtaining the same result.
In[105]:=
Click for copyable input
Out[105]=
Or in another map, whose default projection would be quite different.
In[106]:=
Click for copyable input
Out[106]=

For intermediate-scale maps, the default projection is "LambertAzimuthal". The coordinate values do not then have an immediate meaning in terms of latitude or longitude angles.

A map of the United States. Note how the northern boundary (approximately parallel 49) is curved.
In[107]:=
Click for copyable input
Out[107]=
In[108]:=
Click for copyable input
Out[108]=
In that projection, neither parallels nor meridians are straight lines.
In[109]:=
Click for copyable input
Out[109]=
Compare to a "Mercator" map of the United States, displaying the same parallels and meridians.
In[110]:=
Click for copyable input
Out[110]=

Introduction to Geo Projections

There are many functions and parameters to control cartographic projections and projected coordinates in the Wolfram Language. This subsection gives a brief summary of them. See the documentation of GeoProjection and GeoProjectionData for more detailed information.

Cartographic projections are functions of points on the surface of the Earth onto points on the surface of a flat map, a process that always involves some form of distortion. There are many possible choices of such functions, and the actual choice must be determined by the practical and aesthetic properties of the result, like minimizing distortion in some sense. This leads to several possible classifications of projections.

Many projections are defined using geometric methods of mapping points on a sphere to points on a tangent plane ("azimuthal" projections), a tangent cylinder ("cylindrical" projections), or a tangent cone ("conic" projections). Formulas can be easily generalized for the respective secant cases. In their basic cases, the axes of cylinders and cones are aligned with the polar axis of the sphere.

Cartographic projections are relevant at all scales, but their differences are clearer when using world maps. This subsection will only use examples of world maps.

Available cylindrical projections.
In[111]:=
Click for copyable input
Out[111]=
In cylindrical projections, parallels and meridians are straight orthogonal lines.
In[112]:=
Click for copyable input
Out[112]=
In[113]:=
Click for copyable input
Out[113]=
In[114]:=
Click for copyable input
Out[114]=
Available conic projections.
In[115]:=
Click for copyable input
Out[115]=
In conic projections, meridians are straight lines and parallels are circle arcs.
In[116]:=
Click for copyable input
Out[116]=
In[117]:=
Click for copyable input
Out[117]=
In[118]:=
Click for copyable input
Out[118]=
Available azimuthal projections.
In[119]:=
Click for copyable input
Out[119]=
Examples of azimuthal projections, centered at various points by default.
In[120]:=
Click for copyable input
Out[120]=
In[121]:=
Click for copyable input
Out[121]=
In[122]:=
Click for copyable input
Out[122]=

There are multiple variations of those basic types of projections. For example, if parallels are kept as horizontal straight lines but meridians are allowed to be arbitrary curves, the result is the family of "pseudo-cylindrical" projections. Projections that do not naturally have a particular type are usually classified as "miscellaneous".

Available pseudo-cylindrical projections.
In[123]:=
Click for copyable input
Out[123]=
In[124]:=
Click for copyable input
Out[124]=
In[125]:=
Click for copyable input
Out[125]=
In[126]:=
Click for copyable input
Out[126]=
An example of a miscellaneous projection.
In[127]:=
Click for copyable input
Out[127]=

Another important way of classifying projections is by using the geometric properties they preserve, mainly angles ("conformal" projections), distances ("equidistant" projections), or areas ("equal-area" or "equivalent" or "eumorphic" projections). No projection can preserve everything simultaneously.

The Mercator projection is the only cylindrical and conformal projection.
In[128]:=
Click for copyable input
Out[128]=
The Albers projection is conic and equal area.
In[129]:=
Click for copyable input
Out[129]=
The stereographic projection is azimuthal and conformal and is also constructed via perspective mapping.
In[130]:=
Click for copyable input
Out[130]=

Geo projections have parameters. GeoProjectionData[projname] gives the default values of the projection parameters.

Choose the centering point of a projection.
In[131]:=
Click for copyable input
Out[131]=
Choose the secant parallels in a conic projection.
In[132]:=
Click for copyable input
Out[132]=
Change the default map scale to use kilometers (true distance only on the equator for the Mercator projection).
In[133]:=
Click for copyable input
Out[133]=

Padding

The GeoRange option with explicit numeric values of latitude and longitude ranges returns a map of exactly the region requested. If the projection is not cylindrical, then the borders of the map will be curved lines, corresponding to the specified parallels and meridians.

GeoRangePaddingoption of GeoGraphics that specifies geo range padding

Geo range padding specification.

These are the latitude and longitude limits of the mainland United States.
In[134]:=
Click for copyable input
Out[134]=
In[135]:=
Click for copyable input
Out[135]=
Use GeoRangePadding->Full to complete the rectangular map.
In[136]:=
Click for copyable input
Out[136]=

A map specified by a geographical Entity or EntityClass object is constructed by first computing the latitude and longitude bounds of the object with GeoBounds, adding a small amount of padding, and finally completing the rectangular plot range, effectively using GeoRangePadding->Full.

The map of Australia.
In[137]:=
Click for copyable input
Out[137]=
This is the geo range chosen by GeoGraphics.
In[138]:=
Click for copyable input
Out[138]=
The latitude and longitude limits of Australia are actually smaller.
In[139]:=
Click for copyable input
Out[139]=
In[140]:=
Click for copyable input
Out[140]=
In[141]:=
Click for copyable input
Out[141]=
To obtain the limits above, you need to extend by 5%.
In[142]:=
Click for copyable input
Out[142]=
In[143]:=
Click for copyable input
Out[143]=
Finally, to obtain the original map, combine the padding specification with Full.
In[144]:=
Click for copyable input
Out[144]=

The GeoRangePadding option is very flexible. It allows you to specify independent paddings for the four different sides of the map, and also allows different ways of specifying the actual padding: distances, angles, or scaled fractions of the total map. Click the link on its name to explore all the possibilities.

GeoZoomLevel and ImageSize

Yet another way of providing a geo range is by selecting a point (for example, using GeoCenter or giving a point-like object in the first argument of GeoGraphics) and a zoom level. GeoGraphics will then choose a geo range radius so that the geo background image is constructed with a small number (generally around 10) tiles of 256×256 pixels. It is possible to get larger geo ranges by increasing the ImageSize option of the map.

GeoZoomLeveloption of GeoGraphics that specifies the zoom level
ImageSizeoption that specifies the size in pixels of the final map

Zoom and image size specification.

A map around Paris at zoom level 5.
In[145]:=
Click for copyable input
Out[145]=
This was the associated geo range selected.
In[146]:=
Click for copyable input
Out[146]=
You can get larger images of the same area (also with correspondingly increased zooms) as follows.
In[147]:=
Click for copyable input
Out[147]=
In[148]:=
Click for copyable input
Out[148]=
In[149]:=
Click for copyable input
Out[149]=
In[150]:=
Click for copyable input
Out[150]=

Geo Primitives

Points and Markers

The simplest primitive to use is Point. It will represent a point on the map, with the standard flexibility in Graphics to control its size, color, opacity, etc.

GeoMarker[loc,icon]marker primitive at location loc using the given icon
Point[loc]point primitive at location loc

Zero-dimensional geo primitives.

Take the list of supervolcanoes.
In[151]:=
Click for copyable input
Out[151]=
These are their respective positions.
In[152]:=
Click for copyable input
Out[152]=
Draw a point at each position.
In[153]:=
Click for copyable input
Out[153]=
Draw larger points, with a different color. Note that you can also use Point without mapping it over the list of positions.
In[154]:=
Click for copyable input
Out[154]=
The use of GeoPosition inside Point guarantees that the points will be properly placed in the map for any projection.
In[155]:=
Click for copyable input
Out[155]=
You can also use the list of entities directly. GeoGraphics will internally use EntityValue to get their positions.
In[156]:=
Click for copyable input
Out[156]=
You can even use the EntityClass object itself, because it represents the list of its members.
In[157]:=
Click for copyable input
Out[157]=

The GeoMarker primitive adds the flexibility of placing anything at the given position.

This is the default geo marker.
In[158]:=
Click for copyable input
Out[158]=
Take this image of a volcano.
In[159]:=
Click for copyable input
Out[159]=
Use it at each location. You could have used the image itself instead of the icon Entity object.
In[160]:=
Click for copyable input
Out[160]=

Paths

The GeoPath primitive represents any line on the surface of the Earth before it is projected onto the flat map. That is, a GeoPath object is a trajectory that has geometric meaning on the curved surface of the Earth. Currently three types of such lines are supported: "Geodesic" (shortest path between any two given points), "Loxodrome" (curve that crosses all meridians with the same bearing or angle), and "GreatCircle" (curve obtained by cutting the Earth by a plane through its center). Meridians are always both loxodromes and great circles. Parallels are always loxodromes but not necessarily great circles. The equator is the only parallel that is also a great circle.

GeoPath[locs,pathtype]primitive joining the given locations with a path of type pathtype

One-dimensional geo primitives.

The default type of a GeoPath object is "Geodesic". This is a geodesic.
In[161]:=
Click for copyable input
Out[161]=
The "LambertAzimuthal" projection represents the geodesic as nearly straight. Compare to the "Equirectangular" and "Mercator" projections for the same map.
In[162]:=
Click for copyable input
Out[162]=
In[163]:=
Click for copyable input
Out[163]=
This is the loxodrome curve, or rhumb line, from Buenos Aires to Lisbon.
In[164]:=
Click for copyable input
Out[164]=
It crosses all meridians with this angle, measured on the surface of the Earth, not on the map.
In[165]:=
Click for copyable input
Out[165]=
Compare the three types of GeoPath between two given points.
In[166]:=
Click for copyable input
In[168]:=
Click for copyable input
Out[168]=
The geodesic and the great circle are nearly identical, but not exactly, due to the Earth being ellipsoidal. Zoom in near Iceland.
In[169]:=
Click for copyable input
Out[169]=
It may seem strange that the red curve above is shorter than the green curve. The "Orthographic" projection explains the difference.
In[170]:=
Click for copyable input
Out[170]=

You have seen examples of geo paths between pairs of points. GeoPath[{p1,p2,,pn},type] gives a continuous line formed by segments of the given type between consecutive points pi, but the complete line is not of that type in general.

Draw the shortest route between several cities. The whole line is not a geodesic between the initial and final points.
In[171]:=
Click for copyable input
Out[171]=
Join the final point to the initial point with an additional segment of the same type.
In[172]:=
Click for copyable input
Out[172]=

There are named types of geo paths, including {"Parallel",lat}, {"Meridian",lon}, and particular cases like "Equator", "PrimeMeridian", or "DateLineMeridian".

Draw several parallels.
In[173]:=
Click for copyable input
Out[173]=
Draw parts of parallels, from west to east or from east to west. Use Arrow to add the arrowhead to a geo path.
In[174]:=
Click for copyable input
Out[174]=
Important named geo lines.
In[175]:=
Click for copyable input
Out[175]=
Draw the international date line.
In[176]:=
Click for copyable input
Out[176]=

Circles and Disks

A geo circle with center p and radius r is a closed line surrounding p whose points are all at geo distance r from p. Due to the curvature of the Earth, the total length of the geo circle will be smaller than 2π r, and in fact if r keeps growing, the geo circle will start decreasing in size and focus around the antipode of p.

GeoDisk[loc,r]geodesic disk centered at loc, with radius r
GeoCircle[loc,r]geodesic circle centered at loc, with radius r

Disk-like geo primitives.

A geo circle of 500 kilometers of radius around Chicago.
In[177]:=
Click for copyable input
Out[177]=
A geo circle of 5000 kilometers around the same place. It does not look circular in the "Equirectangular" projection.
In[178]:=
Click for copyable input
Out[178]=
If the geo circle crosses the pole, it will look like this.
In[179]:=
Click for copyable input
Out[179]=
And if it gets even bigger, it will start focusing around the antipodal point.
In[180]:=
Click for copyable input
Out[180]=
All together, in steps of 1000 kilometers.
In[181]:=
Click for copyable input
Out[181]=
Due to the Earth being ellipsoidal, the last geo circle in that sequence is as follows.
In[182]:=
Click for copyable input
Out[182]=

A geo disk is the 2D interior of a geo circle. A geo circle (like any closed curve) separates the surface of the Earth into two finite parts. The interior is the part containing the center point, not necessarily smaller in area than the exterior.

A geo disk of 500 kilometers of radius around Chicago.
In[183]:=
Click for copyable input
Out[183]=
A geo disk of 5000 kilometers around the same place.
In[184]:=
Click for copyable input
Out[184]=
If the geo disk crosses the pole, it will look like this.
In[185]:=
Click for copyable input
Out[185]=
And if it gets even bigger, it will cover most of the Earth, except for a small region around the antipodal point.
In[186]:=
Click for copyable input
Out[186]=

Hemispheres

A hemisphere covers exactly half of the Earth's surface, as divided by a plane passing through the Earth's center. Hence the boundary of a hemisphere is a great circle (actually a great ellipse because an ellipsoidal model of the Earth is being used). The Wolfram Language provides two types of geo primitives to work with hemispheres: on the one hand is the hemisphere GeoHemisphere[p] around a point p of the surface, and on the other hand are the especially important hemispheres DayHemisphere[date] and NightHemisphere[date], determined by the position of the Sun at the given date. The boundary of GeoHemisphere[p] is the line GeoHemisphereBoundary[p]. The boundary of the day and night hemispheres is DayNightTerminator[date].

GeoHemisphere[loc]hemisphere centered at loc
DayHemisphere[date]daylight hemisphere at the given date
NightHemisphere[date]night hemisphere at the given date
GeoHemisphereBoundary[loc]boundary of the hemisphere centered at loc
DayNightTerminator[date]terminator line between the day and night hemisphere on date

Hemisphere-related geo primitives.

The hemisphere around Tokyo.
In[187]:=
Click for copyable input
Out[187]=
Superimpose its boundary line.
In[188]:=
Click for copyable input
Out[188]=
Use an azimuthal projection centered at Tokyo.
In[189]:=
Click for copyable input
Out[189]=
The Northern Hemisphere.
In[190]:=
Click for copyable input
Out[190]=

The day and night hemispheres are just an application of GeoHemisphere for the projection of the position of the Sun on the Earth's surface, or its antipodal point. To avoid ambiguities, dates must be specified with explicit TimeZone specifications.

The daylight and night parts of the Earth at a northern winter solstice.
In[191]:=
Click for copyable input
Out[191]=
The daylight and night parts of the Earth at a spring equinox.
In[192]:=
Click for copyable input
Out[192]=

Region of Visibility from a Height

A geo hemisphere can be considered the part of the Earth that would be visible from very far (actually infinite distance) along some direction. Here the generalization of that concept when the viewing point is at finite height over the surface of the ellipsoidal Earth is introduced. The region obtained is then always smaller than a hemisphere. The geometric construction is very similar though: the region of visibility is also determined by a secant plane, but now it does not pass through the center of the Earth.

GeoVisibleRegion[loc]visible region from the elevated position loc
GeoVisibleRegionBoundary[loc]boundary of the visible region from the elevated position loc

Regions of visibility.

The region currently viewable from the International Space Station.
In[193]:=
Click for copyable input
Out[193]=
In[194]:=
Click for copyable input
Out[194]=
The boundary of the visible region from geostationary orbit over the point {0,0}.
In[195]:=
Click for copyable input
Out[195]=

Line, Polygon, and Other Standard Graphics Primitives

The standard, non-geo graphical primitives, like Line, Polygon, Circle, etc. can also be used in GeoGraphics, but are interpreted as primitives on the flat map, not on the surface of the Earth as their geo counterparts are. They have the same standard properties they have in Graphics; in particular, the segments in Line and Polygon between any two consecutive points are straight lines.

Take four geo positions.
In[196]:=
Click for copyable input
The Line primitive connecting those four points always has straight sides, in every projection, but the GeoPath connecting them has generically curved sides.
In[200]:=
Click for copyable input
Out[200]=
On the other hand, the points of the geodesics are uniquely defined, while the Line points are not. For some projections, the black line passes through Brazil, but not for others.
In[201]:=
Click for copyable input
Out[201]=
In all cases, one geodesic segment passes between Mozambique and Madagascar, but the corresponding Line segment crosses different countries of Africa for different projections.
In[202]:=
Click for copyable input
Out[202]=

It is possible to use directly projected coordinates in the standard non-geo primitives, but this requires taking into account which projection is being used. This is useful for adding additional graphical elements to the map, not directly related to elements existing on the surface of the Earth. In fact, you can use coordinates that do not even correspond to any point on the surface of the Earth. When this is done, it is highly recommended that the projection being used be made explicit in the input, to avoid GeoGraphics selecting a different projection when more primitives are added.

Add arrows and texts to a map in the "Bonne" projection. Note how GeoPosition specifications are mixed with projected coordinates in some Line primitives.
In[203]:=
Click for copyable input
Out[203]=
Using a different projection will automatically modify the positions specified with GeoGraphics, but not the positions given with projected coordinates.
In[204]:=
Click for copyable input
Out[204]=
PlotRange and GeoRange are completely independent options. Typically GeoRange is specified and GeoGraphics is allowed to choose an appropriate PlotRange, but you can always specify both. GridLines and GeoGridLines are also independent.
In[205]:=
Click for copyable input
Out[205]=

Advanced: The Structure of a GeoGraphics Result

The output of a GeoGraphics input expression also has head GeoGraphics, but its first argument is now a Graphics object, the actual graphics object that is displayed as the map. This output GeoGraphics also contains a sequence of options with absolute values, both options that were given in input and options that were decided by GeoGraphics.

Analyze the structure of GeoGraphics in output.
In[206]:=
Click for copyable input
Out[206]=
The output still has head GeoGraphics.
In[207]:=
Click for copyable input
Out[207]=
The first argument is a Graphics object, and then there is a sequence of options.
In[208]:=
Click for copyable input
Out[208]=
In[209]:=
Click for copyable input
Out[209]=
In particular, there is information about the projection and its parameters.
In[210]:=
Click for copyable input
Out[210]=
The zoom level selected.
In[211]:=
Click for copyable input
Out[211]=
Or the geo range and center chosen.
In[212]:=
Click for copyable input
Out[212]=
In[213]:=
Click for copyable input
Out[213]=
You also see the ellipsoidal model chosen for the Earth, the default "ITRF00".
In[214]:=
Click for copyable input
Out[214]=
An important option contained in the Graphics object itself is PlotRange.
In[215]:=
Click for copyable input
Out[215]=
To extract the images in the result (in this case just the background image), use the following.
In[216]:=
Click for copyable input
Out[216]=
In[217]:=
Click for copyable input
Out[217]=

Advanced: Geo Evaluation of Geo Primitives

The geo primitives are converted into standard primitives in the "Equirectangular" projection so that they can be easily displayed using Graphics.

Use Geographics`GeoEvaluate on a GeoCircle, converting it into a Line object containing a list of {lon,lat} pairs.
In[218]:=
Click for copyable input
Out[218]//Short=
In[219]:=
Click for copyable input
Out[219]=

A second argument of GeoGraphics`GeoEvaluate specifies the model of the spheroid being used, either a number in meters or a Quantity distance representing a sphere of that radius, or a pair {a,b} of semiaxes of an ellipsoid of revolution, also given as numbers in meters or Quantity lengths. The result is now different.

The same geo circle but now on a sphere of 2000 kilometers of radius. The result is different.
In[220]:=
Click for copyable input
Out[220]//Short=
In[221]:=
Click for copyable input
Out[221]=

A third argument of GeoGraphics`GeoEvaluate specifies the resolution distance required, in meters. When this number is smaller, then the geo primitives are resolved with more points, to guarantee that neighbors are closer than that distance.

Use a resolution of only 1000 meters. The same geo circle is now resolved with many more points.
In[222]:=
Click for copyable input
Out[222]//Short=
In[223]:=
Click for copyable input
Out[223]=

Geo Styling

Map Stylings

GeoGraphics inherits from Graphics a large variety of directives that can be used to stylize a map, including colors, opacities, textures, and many more. It also adds new elements that are characteristic of maps, which automatically respond to the projection being used. The most important new element is GeoStyling[mapstyle,directive], which specifies how to stylize an arbitrary area of the map; that could be in particular the geo background.

GeoGraphics provides several predefined map styles, like "StreetMap", "ReliefMap", or "ContourMap", and only allows you to place arbitrary images on a polygon.

GeoStyling[mapstyle]stylize the interior of 2D geo primitives using mapstyle
GeoBackgroundoption of GeoGraphics that specifies the background map style

Map styling.

The default style map is "StreetMap".
In[224]:=
Click for copyable input
Out[224]=
Show the same area, but without labels.
In[225]:=
Click for copyable input
Out[225]=
Show a relief map of elevations.
In[226]:=
Click for copyable input
Out[226]=
Or the corresponding contour map. Use options to control the result.
In[227]:=
Click for copyable input
Out[227]=

GeoStyling effectively works like Texture, specifying what to place inside the following 2D primitives, like geo disks or polygons. In that sense, the GeoBackground option can be considered as the particular case of specifying what to place in the whole map.

A relief map of Peru over a map with default style.
In[228]:=
Click for copyable input
Out[228]=
GeoStyling can be used to show a map confined to the borders of a given area.
In[229]:=
Click for copyable input
Out[229]=
In[230]:=
Click for copyable input
Out[230]=

There are two flexible map styles that allow you to place arbitrary images and graphics on a map, namely {"Image",image} and {"GeoImage",image}. The difference is that in the first case the image will be placed in the given area with no transformation (perhaps only a change in aspect ratio), while in the latter case the image will be projected along the map area. Therefore "GeoImage" is adapted to place pieces of maps over other maps.

Take a picture of Gauss.
In[231]:=
Click for copyable input
Out[231]=
Place it over Germany, in the default "Mercator" projection.
In[232]:=
Click for copyable input
Out[232]=
With the "Image" map style, the image will preserve its orientation in any projection.
In[233]:=
Click for copyable input
Out[233]=
Take this nice old map of Brazil and cut its borders.
In[234]:=
Click for copyable input
Out[234]=
Using the "GeoImage" map style, it will be projected appropriately in any map.
In[235]:=
Click for copyable input
Out[235]=

Opacity and Color

The Graphics 2D primitives are opaque by default because the background is typically empty, so it can be covered. However, GeoGraphics usually contains a map image as geo background, which should not be fully covered by the primitives over it. Therefore, the default opacity of 2D primitives is small: 0.2. This throws in a slight twist in how opacities are handled in GeoGraphics, because the opacities of the 2D primitives need to be distinguished from the opacities of the rest of the primitives (points and lines), which are still opaque by default. This can be done by using GeoStyling again.

A geo disk around Ottawa, with a thick blue border. The geo circle is opaque, but the disk is not.
In[236]:=
Click for copyable input
Out[236]=
Standard opacity specifications will affect all primitives except for the 2D primitives.
In[237]:=
Click for copyable input
Out[237]=
To change the opacity of the disk, use GeoStyling[opacity], which will not affect the thick geo circle.
In[238]:=
Click for copyable input
Out[238]=
Colors will affect all primitives normally.
In[239]:=
Click for copyable input
Out[239]=
But colors placed inside GeoStyling take precedence for 2D primitives, even over colors that are given afterward.
In[240]:=
Click for copyable input
Out[240]=
GeoStyling[Automatic] undoes the action of any previous GeoStyling specification and recovers the defaults.
In[241]:=
Click for copyable input
Out[241]=

Geo Grid Lines and Scale Bar

Drawing parallels and meridians is always very useful for understanding the orientation of the elements on a map, even more so when using a noncylindrical projection. The option GeoGridLines and its styling counterpart GeoGridLinesStyle provide a flexible interface to drawing the so-called graticule of lines.

GeoScaleBaroption of GeoGraphics that turns on the use of a scale bar
GeoGridLinesoption of GeoGraphics that turns on the use of a lines graticule
GeoGridLinesStyleoption of GeoGraphics that specifies the style of geo grid lines

Other map styling options.

In the "Equirectangular" projection, the parallels and meridians are straight lines (as in all cylindrical projections) and are equally spaced. Let the system choose the lines.
In[242]:=
Click for copyable input
Out[242]=
These are the latitude and longitude lines used, multiples of "nice" integer angles.
In[243]:=
Click for copyable input
Out[243]=
Specify respective approximate numbers of lines to use, in any projection.
In[244]:=
Click for copyable input
Out[244]=
Specify the graticule subdivision size as Quantity angles.
In[245]:=
Click for copyable input
Out[245]=

To read scale in a map, you can use the GeoScaleBar option. For large-scale maps, the distance scale factor may vary from point to point, and therefore the scale bar will only represent an average.

Use a scale bar with metric units in a map of France.
In[246]:=
Click for copyable input
Out[246]=

Other Celestial Bodies

All of the above has been presented for the Earth, but can be applied to other celestial bodies for which satellite images exist, like Mars, Pluto, or the Moon. GeoGraphics uses appropriate background tiles as determined by the value of the option GeoModel.

GeoModeloption of GeoGraphics that specifies a datum or celestial globe

Geo model specification.

A map of the Moon in the Mollweide projection.
In[247]:=
Click for copyable input
Out[247]=
A shallow valley on the Moon.
In[248]:=
Click for copyable input
Out[248]=
The Copernicus crater.
In[249]:=
Click for copyable input
Out[249]=
A map of Mars in the Bonne projection.
In[250]:=
Click for copyable input
Out[250]=
Show the landing position of a space probe.
In[251]:=
Click for copyable input
Out[251]=
Another interesting area on Mars.
In[252]:=
Click for copyable input
Out[252]=
A view of Pluto using the orthographic projection.
In[253]:=
Click for copyable input
Out[253]=