G.Projector User's Guide

(Updated: July 2, 2018)

G.Projector is a tool for exploring map projections. It takes an input map image, typically in Equirectangular form (also called Cylindrical Equidistant or Plate Carré) and transforms it to one of over 140 other projections. Additionally, outlines and/or symbols can be drawn overlaying the projected map image.

Input Map Images

When you first start G.Projector, you are presented with a file dialog asking you to select a source input map. The bitmapped image formats that you can use include BMP, GIF, JPG, and PNG. On some platforms you may also be able to open TIFF images. Furthermore, you can open ground overlay images that are identified within many OpenGIS KML and KMZ files.

What other constraints are there on your choice?

First, you don't have to select an input map at this time. You could click the cancel button in the file dialog and just work on a map projection window that shows only a longitude-latitude grid and continental outlines. At some later time, you could then import a map image.

If you select a bitmapped input map image at the start, the image must be of a map projection that G.Projector is able to read and use for input. After the image file has been selected, a dialog will appear like that in Fig. 1, asking you to identify what the input projection is and to specify any\ parameter values needed to interpret that projection.

Image showing the input map options dialog

Figure 1: The input map options dialog, shown for an Equirectangular map projection.

Although G.Projector is capable of creating maps in 180+ projections, it is currently only able to use just six map projections for input. In addition to the standard Equirectangular form, it can also work with a Aitoff, Cylindrical Equal-Area, Hammer, Robinson, or Winkel Tripel input map image. (Please note that implementations of the Robinson vary, so G.Projector may not handle any particular input Robinson map as well as one would like.) Whatever the input image's map projection, it should have no border or extra margins around the edges.

If you instead select a KML or KMZ file to use as input, G.Projector will parse the information in the file that identifies the input image by looking for the "GroundOverlay" tag. The longitude and latitude bounds of the image are also obtained from this tag. But please note that G.Projector does not understand rotated ground overlay images.

The G.Projector distribution includes a folder called sample_maps that contains four sample input maps: two global map images of Earth and one of Mars, plus a KMZ file that includes a topographic image of just the United States. These are relatively small image files, the largest being 1800×900 pixels and size about 350 kB. The maximum image size that G.Projector will accept for input is dependent on the amount of memory on your computer. If you use larger input images — maps 5000×2500 pixels or larger — from other sources, please be aware that G.Projector may encounter memory problems. Memory constraints could also become an issue if you have more than one map window open at the same time. The program may hang or report a "heap space" error if such memory problems arise.

Map Windows

After that first open-file and input map options dialogs, G.Projector will displays a window showing the map, with a lower tabbed panel that contains various controls to manipulate the output map projection and appearance. An example window showing an Orthographic projection, centered on New York City, is shown in Fig. 2.

Image of sample Orthographic map and the projection controls tab

Figure 2: The map display window, showing the controls set to the projection tab, with the Orthographic projection selected.

The first tab of controls manages the map projection and its parameters. First is a pop-up menu to choose from the available projections. Below are one or two text fields for entering the coordinates at which the map is be centered. Most of the available projections allow you to specify the central longitude, and many also allow for specifying the latitude. If the projection does not accept a latitude — likely because it is a global projection that is always centered on the equator — then the latitude field will be disabled.

Several of the projections may have an additional parameter or two. When one of these projections is chosen, additional text input fields, checkboxes, and/or pop-up menus appear in a third line of the projection tab controls. For example, in Fig. 2 above, the Orthographic projection controls include a text field for specifying its "Edge Radius", which is the angular distance between the map center and the top or bottom edge.

Fig. 3 below shows another example; the Equirectangular projection has an extra parameter called the "Standard Parallel", the latitude at which east-west distances are correctly scaled. A text field for entering that value appears in the controls when that projection is chosen.

Image of sample Equirectangular map and the projection controls tab

Figure 3: A map window showing the Equirectangular map projection, with the standard parallel (the latitude of true scale) set at 30°.

The second tab of plot controls manages how the graticule — the longitude-latitude grid — is drawn, or if it is to be drawn at all. You may specify the spacing of the grid lines and their style, color, and weight. For cylindrical projections, you may also indicate whether you would like the longitude and latitude values of the lines labeled.

Image show the map graticule controls tab

Figure 4: The tabbed panel of map graticule (gridline) controls.

The third controls tab allows you to specify whether and how any line or symbol overlays should should also be drawn overlaying the map. Line overlays will most likely be outlines of continents, rivers, and/or political boundaries. When you first start working with G.Projector, it will offer you seven choices of such outline overlays, including a mix of continental coastlines, national borders, and inland water bodies. These seven choices are "built-in" to the G.Projector application.

Image showing the map overlays controls tab

Figure 5: The tabbed panel of map overlay controls.

If you have opted to use a multipoint shapefile overlay as an overlay (see below regarding use of external overlay files), then the overlay symbol control will be enabled and you can use it to indicate how the points are marked on the map.

The fourth controls tab allows you to specify that night-side shading be applied to the map, and if so, how dark that shading should be. The placement of the shadow is controlled by specifying the subsolar point, i.e., the point directly below the sun. All points more than 90° from that point will be in shadow. Note that Earth's obliquity is 23.44°, so setting a subsolar latitude greaterr than 23.44° or less than -23.44° would not be realistic. If you are using an input map that evidences the time of year, then there are further limitations on a realistic setting for the subsolar latitude.

Image showing the map night-side shading controls tab

Figure 6: The tabbed panel of map night-side shading controls.

The fifth and final controls tab provides controls for setting the background color filling the outside areas of the map, and the color and weight of the map's border.

Image showing the map border and background controls tab

Figure 7: The tabbed panel of map border and background controls.

Importing Overlay Files

G.Projector also allows you to open and use an overlay file of your own, using the "Import Overlay..." command in the File menu. The types of files recognized are CNO and CNOB line overlays and also the more common SHP shapefiles. The content of a shapefile varies; it could be a line overlay or it could be a multipoint file.

When you import an external overlay file, G.Projector will also ask if you want to save it for future use so that it is always available without having to use the import command every time you want to use it.

Image of future-use dialog that appears when importiung an overlay

Figure 8: The "save for future use" dialog that appears when you import an overlay.

If you have imported an overlay and also indicated that it should be saved for future use, but later decide that you no longer need it, you can remove it from the library of saved overlays. Open the Preferences window via the menu command and click on the "Overlay Lib" tab at the top of the window. Select the overlay in the list, as demonstrated in Fig. 9, then click the "minus sign" button just below the left side of the list.

Image of the overlays library panel in the preferences controls

Figure 9: The overlays library panel in the preferences window. The "minus sign" delete button is enabled when you select an imported overlay.

Please note that if you want to import a shapefile overlay with more than a couple hundred thousand points, G.Projector's performance redndering that overlay will be poor.

Importing Map Image Files

After a map window has been created, it is still possible to apply a different input map image than your initial choice. To do so, select the "Import Map Image..." item in the File menu.

Unlike overlays, when you import a map image, it is only available for use in the current map window. It cannot be saved to a library for easy future use, nor can it be used in another map in the same session without importing the image again in the second (or later) map.

If you decide to remove the input image being used in a map window but not (yet) replace it with another input image, select the "Remove Source Map Image" item in the Edit menu.

Click Options

When viewing a map, there are some special mouse click options you can use:

An alt-click, i.e., clicking while also holding down the "alt" or "option" key, on the map will cause a box to appear that shows the longitude and latitude of the point where you clicked. This box remains visible until you move or click the mouse again.

A shift-click on the map will cause most map types to be re-centered. Azimuthal and other oblique projections are re-centered on the click point, while others are re-centered on the longitude of the click point. Some maps, such as interrupted maps, cannot be re-centered at all.

For some but not all map projections, you can also use mouse clicks to zoom in and out. On macOS, use command-click and alt-command-click; on Windows and Linux, use control-click and alt-control-click. This option is available for the Equirectangular projection and also most azimuthal and conic projectios. Note that when you zoom in/out, the controls below the map should update to indicate the map parameters affected by zooning in or out.


If you have questions about G.Projector that are not answered above, please contact the author:

Robert Schmunk
NASA Goddard Institute for Space Studies
2880 Broadway
New York, NY 10025 USA