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 GeodesyData—for 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.

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

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.

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.

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.

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, ...).

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 polygons—and many more options.

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

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

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.

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.

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

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.

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

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

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

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.

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.

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 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. When the value of $GeoLocation is set, the variables $GeoLocationCity and $GeoLocationCountry are automatically assigned to the city and country containing $GeoLocation, or the nearest possible city and country. Note that changing your $GeoLocation does not automatically change $TimeZone.

The most general way of specifying the region covered by a map in latitude and longitude coordinates is using the option GeoRange{{lat_min,lat_max},{lon_min,lon_max}}. 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.

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.

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.

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.

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.

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.

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.

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.

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

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.

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

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.

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

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.

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.

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

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.

You have seen examples of geo paths between pairs of points. GeoPath[{p₁,p₂,…,p_n},type] gives a continuous line formed by segments of the given type between consecutive points p_i, but the complete line is not of that type in general.

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

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.

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

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.

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.

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.

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.

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.

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

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.

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.

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

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.

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.

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.

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.

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.