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

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.

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.

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.

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.

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.

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.

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.

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.

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.

Contact