Jules Verne Voyager: Advanced Help

Advanced Help Index:


For more information about our Voyager map tool, contact: Lou Estey
(louunavco.org)
Last modified: 15 Apr 2005

Overview     The Jules Verne Voyager is a precision interactive mapping tool for the World Wide Web, based on GMT and Java functionality, presently featuring:

Voyager can be used on Earth datasets or digital models of other planets; see Solar System Portal or the jules homepage and explore the world of your choice. The basic interactive Voyager functionality is the same for each.

Becoming familiar with the full functionality of Voyager outlined on this page is strongly suggested to make complete use of Voyager; otherwise you are just scratching the surface of its capability. First, make sure you are familiar with the basic functionality presented on the Getting Started help page.

In addition to using the buttons on your mouse, you should also know about using other buttons on the Voyager tool, as well as buttons on your browser and your keyboard. For all of the Voyager documentation, the following syntax is used:

  • [Item]: Item is a button on Voyager
  • {Item}: Item is a button on your browser
  • <Item>: Item is a key on your keyboard
As usual, pressing your mouse button is described as a "click".

A few centimeters down from the top of the Voyager page there is a horizontal line going all the way across the page. If your browser is Java-enabled, then below this is where a Java applet — the main part of Voyager with which you will be interacting — will be running. The top part of the Voyager Java applet should display a line of buttonss, which for Earth looks like:

    [Features:] [GPS/other:] [Index] [Up] [Redraw] [Down] [URL:]
Below the buttons, there may be a line of text telling you what is currently selected from the [Features:] and [GPS/other:]. If this line appears blank or chopped off, click on the space just below the [Features:] button and just above the map border at any time to activate the current selected list.

Next you should see a world map (global map of Earth if you launched the default Earth URL), or a specialized initial zoom view, e.g. if you launched a URL of the form: ../Voyager/Earth?see=XXXXX or some other specialized URL. An easy way to always tell whether you are on a global map or a zoomed-in map:

    [Up] is in dark lettering = you are on the global map (you can't go 'up' any more)
    [Up] is in light lettering = you are on some zoomed-in map (you can go 'up' by clicking on [Up])

If you use your browser scroll bar to scroll down, you will see a second terminating horizontal line near the bottom of the page indicating the bottom of your applet 'map' space, and underneath that will be your own unique user session ID. (If your browser is not Java-enabled, then the second horizontal line will be just a short distance below the first, with the message "Sorry, your browser appears not to be Java-enabled." in between.)

You should be able to rubberband box (click down, drag, and release a "box") in any (local) map area and obtain a zoom on that boxed area. Clicking on a point in any (local) map area will result in a new map being created centered at that point, resulting in a pan. Each new zoomed and panned image is being created especially for you on our map server jules — these are not pre-canned images! Be patient, especially when:

  • viewing texture underlays (GMT "grids"), e.g. grey or color topography, and so on
  • requesting polar views
  • requesting velocity vectors or focal mechanisms (Earth only)
  • viewing a texture underlay grid on the index map (which is very CPU intensive)

Map specifics     GMT (Generic Mapping Tools, developed and maintained by Paul Wessel and Walter H. F. Smith) programs are used to create the maps, using a variety of map projections:

  • The default "level 0" map is a global view using a Plate Carrée projection, bounded in latitude at 90° S and 90° N; the default map is centered on:
    • for Earth, 11° E (meridian split at 169° W = 191° E, forming the left and right edges of the map)
    • for all other worlds, 0° E (meridian split at 180° W = 180° E, forming the left and right edges of the map)
  • Each zoom creates an Lambert azimuthal equal-area projection (the "local" map), and
  • an Orthographic azimuthal projection (the "index" map) centered on the local map, and highlighting the boundary of the local map.
An equal-area projection was selected for the zoomed-in local maps to minimize areal distortion; what you see on each zoomed-in local map (down from the global map) is pretty close to what you would see if you looked at a globe.

You can toggle between the local map and the index map by clicking [Index] when on the local map to go to the index map, and clicking [Local] when on the index map to go back to the local map. Note: There is no index map for the global Plate Carrée map! On the index map, you should find a near-rectangular region indicated:

    This magenta boundary region identifies on a global view what region is being shown on the corresponding local map. If you have zoomed to point where the local map covers only a small area, it may appear that there is no magenta boundary on the index map, but look carefully ... it's there in the center.

Which way is north? (or south?) In general, about the only thing that can be stated for certain is that due north is directly up from the exact center and due south is directly down from the exact center (of any local or index map). Of course for the global Plate Carrée map, north and south are directly up and down, respectively, from any point on the map not exactly at 90° N or 90° S.

The map space assigned by default to the Voyager Java applet is 720 pixels in horizontal width and 940 pixels in vertical height (aspect ratio of about 3:4), plus a small amount of fixed boundary padding. Any local map is scaled to fill either the full horizontal width or the full vertical height allotted for the applet. Thus, if your selected local map has an aspect ratio of 1:3 or 1:4 (i.e. very tall and skinny), the full height of the applet will be used, and you may need to use your browser scroll bar to view the lower portion of the local map. You can presently only reduce either the width and/or the height from these default settings by appending CGI name/value pairs to the end of the Earth or other world URL and relaunching it from your browser. For example, to assign the original default size of 600 pixels in width and 780 pixels in height (aspect ratio of 3:4, plus the padding) — which will result in faster processing of each image, try:

Rubberband box zoom     Rubberband box an area (down, drag, and release a mouse button) on any local map; zoom on the selected box.

For the global Plate Carrée map, you can create a split box on the meridian split (by default at 169° W on Earth, 180° W on other worlds), for example, by starting a rubberband box corner near the left side of the map and then dragging the mouse to the opposite corner of the desired box near the right side of the map. (As you stretch the box to the right, it will break into two pieces when it becomes more than 180° in longitude wide.) For example, on Earth, try getting Alaska and western Siberia. Or, try getting the main Hawaiian islands on the left side along with the Northwestern Hawaiian Islands on the right side (which extend to the northwest from the main islands).

For each zoom level, you can only zoom on a local map (not on a index map — at least not yet).

The largest box you can get on the global Plate Carrée local map is a hemisphere. This will be reduced slightly on the actual level 1 map that is generated, since the maximum corner-to-opposite corner region that can predictably be shown on the GMT Lambert azimuthal equal-area projection we are using has a span of 180 great-circle degrees.

Poles: There are two ways to obtain local maps that include a pole (North or South) when starting from the global Plate Carrée map:

  • To obtain a local map with a pole at the center of the map, start the rubberband box in the small frame square in the upper-left to "capture" the North Pole or in the lower-left to "capture" the South Pole and then continue the zoom box to the latitude of your choice. If you drag this zoom latitude line towards the other pole, you will be zooming on that other pole. (In other words, you zoom on whatever pole the zoom latitude line is closest to.) You can also initiate these polar zooms from any of the frame corners.


  • To obtain a local map with a pole towards one extreme of the map (toward the top if the North Pole, or toward the bottom if the South Pole), start the rubberband box in the long horizontal frame border either just above the global map to "capture" the North Pole or just below the global map to "capture" the South Pole; for example, try starting a rubberband zoom box in the frame border above the upper-left of Greenland and drag the zoom box to the SE corner of Iceland. After you get the local map, examine the index map.
From the resulting polar projection local map you can view the corresponding index map, continue zooming on the local map, return to the global map using [Up], and so on.

Click-on-a-point pan     On any local map, you can "pan" to a new location with the center of the new map at the point you click on (i.e. don't draw a box — because doing so will be interpreted as a zoom). The scale and aspect ratio of the new region will be the same as the old region — just recentered. Panning on the global Plate Carrée map recenters it on the longitude selected (rounded to the nearest degree); the central latitude will remain the equator in this case.

To distinguish between a pan and a zoom, any "box" where the pixel dimensions are less than a 2x2 area is considered a pan, and anything else — even if a 2x2 box — is considered the next zoom region.

Return to previous zoom regions     After you have zoomed in one or more levels, you can go back to the global Plate Carrée map (i.e. un-zoom) by hitting [Up] (zoom up) one or more times. At any point you can go back to your previous zoomed regions (i.e re-zoom) by then hitting [Down] (zoom down) one or more times.

At present, there is no applet button to return you to a previous panned region.

At any time you can do a new zoom or pan on any local map.

To add/delete features     Click and hold on [Features:] (or any other [XXXXXX:] menu button on the left) and then click on an item. (On some browsers, clicking on these buttons results in a scroll-down menu. In that case, click-and-release on the menu, use the scroll bar to find the feature you are interested in, and then click-and-release on that item.) If the item was unselected, it will now be selected. If it was selected, it will now be unselected. The accumulative items that are currently selected should be displayed in text immediately below the menus. The lines:

  • [--texture underlays--]
  • [--image overlays--]
serve as menu subheaders, and do not select or deselect any items.

Immediately under [--texture underlays--] is a listing of all available continuous (global or near global) texture underlay grids which can serve as an underlay for other data sets. Only one texture underlay grid can be selected at a time: picking a new texture underlay selects that one, and picking the texture underlay already selected "deselects" it (e.g. no texture underlay grid now selected).

Immediately under [--image overlays--] should always be the generic options:

[lat/lon lines]  http://jules.unavco.org/Earth?opt=32 opt =
32		   latitude and longitude lines; link is to Earth with lat/lon lines turned on
[lat/lon grid]  http://jules.unavco.org/Earth?opt=64 opt =
64		   latitude and longitude intersection grid; link is to Earth with lat/lon grid turned on
[lat/lon labels]  no thumbnail image opt =
128		   latitude and longitude line or grid labeling; link is to Earth with labeled lat/lon lines
[distance scale]  no thumbnail image opt =
256		   distance scale added to zoomed-in local maps, which will be in metric units (kilometers, meters, ...); link is to Earth with distance scale turned on, though this will not show up until you do a zoom


Any combination of the image overlay datasets can be selected/deselected at a time. For specifics on what each item is in the [Features:] or other menu, go to the Features Help page for that world.

After selecting (adding) or unselecting (deleting) various items, you can then continue to zoom, pan, or click any button [Index], [Up], [Redraw], or [Down] if in light lettering. The accumulative items now selected will be shown on the next image.

Note: All labels are (presently) excluded from the index maps and the global Plate Carrée map.

[URL:] menu:     The right-most [URL:] menu lists options which bring up other browser windows for:

  • Saving map images     Click the [Save] menu option when you have a map (local or index) that you want to save. You will have the option of saving the current GIF map image (what is directly displayed with the Voyager applet), or the PostScript file generated by GMT, or both. Instructions are provided on that page for saving the GIF or PostScript. This page also provides you with a Voyager URL which can be used to directly recreate the image, if that becomes necessary sometime in the future.

    Also, please read the caveats for further image use on that page, especially image acknowledgements.


  • Ancillary information     Click the [anc] menu option to get to extra information concerning the items that you currently have selected on the map, which (if appropriate to your current selections) will include a legend of the base image for the current map. Selecting this option may bring up more than one browser window! Additional links to investigate may occur on the ancillary pages.


  • Views of the Solar System     Click the [VSS] menu option to get directly to Calvin Hamilton's Views of the Solar System (English) page for the world you are exploring.


  • The Nine Planets     Click the [9-P] menu option to get directly to Bill Arnett's The Nine Planets page for the world you are exploring.


  • Planetary Data System: Welcome to the Planets     Click the [PDS] menu option to get directly to Caltech/JPL's Planetary Data System Welcome to the Planets page for the world you are exploring (except moons, which link to the home world page).

URL extensions     One of the more powerful features of the Jules Verne Voyager map tool is that you, the user, can be in direct control on how the initial map image comes up. For example, the Voyager URL can be modified to adjust the central meridian of the global Plate Carrée map or initiate a zoom in on a specific region. Items that can be selected:

  • e=<central longitude in degrees>
  • n=<central latitude in degrees>
  • de=<half width of east-west extent of region in great-circle degrees>
  • dn=<half height of north-south extent of region in great-circle degrees>
  • kme=<half width of east-west extent of region in kilometers>
  • kmn=<half height of north-sorth extent of region in kilometers>
To illustrate this feature, view Antarctica with the map centered at the South pole: which puts 10° W at the top of the map. Selecting just e=X will create a global Plate Carrée map centered at X° longitude, e.g. centers the map on 170° W longitude.

With the de and dn specified (because these use great circle degrees, and not local lon/lat degrees), you can use a certain de/dn window to view the same size area for any spot on the world, just by changing the central e/n values on the URL.

For comparitive planetology, you can use an equivalent kme and kmn to specify the half-window dimensions in kilometers instead of great circle degrees. So if you want to compare Hawaii with Olympus Mons at 1:1 window comparison:

(where the additional opt=256 puts on the distance scale, which is off by default; see below). Click on both the above links, and then use the {< Back} and {Forward >} browser buttons to compare these two volcanoes at the same scale.

Retrieving lost image maps     Occasionally, you may have a zoom stack in Voyager where you wanted a particular zoomed-in map, when up the zoom stack using [Up], and then accidentally zoomed or panned on a map which wipes out the zoom stack below the new local map. This design feature is a risk which is balanced by the ease by which you can zoom and pan around. For example, it probably will not be too difficult for you to recreate whatever zoomed in image you had created before (and now is "lost"). However, you do have two other options.

First, your browser may be have a Java console option:

  • if using Netscape Communicator, go to the {Communicator} menu and select {Tools} and then {Java Console}
  • if using Internet Explorer, go to the {View} menu and select {Java Console}.
In the Java console window, you will see a history of return values from the jules server to the Voyager applet running on your browser. Look for a line that starts like:
    back: &level=2&e=-61.4374264751226&n=15.6831784275976&de=1.26686338431184
         &dn=1.1828056631888&x_mn=7&x_mx=374&y_mn=52&y_mx=393&xoff=0
This is a parameter name/value pair string. In particular, notice the e=, n=, de=, and dn= parameters and values. You can use these to launch Voyager and bring up a specific zoomed-in image matching one that you created earlier. For example, suppose the above was for the Earth, you would try: which will bring up an initial zoomed-in map with a scale and aspect ration identical to one that you had produced earlier. This does not set the options as you might have had them, but go through the selection/deselection process to get your option list and then click on [Redraw]. Now, when you've gotten back to what you had before, save your image! You don't want to lose it again!

Second, you can browse through the image files in your session space on our server. Scroll down to the bottom of the Voyager page and find your session user ID. Then launch:

    http://jules.unavco.org/voyager/map/...
where you substitute your complete user ID for the ellipsis (...) above. We presently allow you to do a directory listing on this space, so the complete URL will list all the image files and so on associated with your session. Click on the various *.gif links for GIF, or *.ps for PostScript, to find what you lost. Save any image in the usual way using your browser. There no way to extract the e=, n=, de=, and dn= parameters for your maps using this method, but you can (with work) extract the option settings you had set from the filename.

URL customizing     You may wish to customize the launching of the Voyager URL with certain non-default features, rather doing this later using the applet buttons. Or if you find you are using a browser where the applet buttons don't seem to work, but the mouse rubberband box zoom on the map does work, you can still recover some functionality by invoking the URL with specific label/value pairs, e.g. gmt, geo, vel, lbl, mon, grd, plus e, n, de or kme, dn or kmn, and so on. The following opt options apply to any world map in Voyager, and are bit-coded: 

	opt = 0x00020 = 32     latitude/longitude continuous lines
	opt = 0x00040 = 64     latitude/longitude intersection grid
	opt = 0x00080 = 128     labeling for latitude/longitude lines or grid
	opt = 0x00100 = 256     distance scale
Thus, to launch the Venus map with labeled latitude/longitude lines, use ../Voyager/Venus?opt=160. (Note: 0x20 + 0x80 = 32 + 128 = 160.) The other world-specific label/value pairs can be found at the end of the Features Help page for that specific world.

Common user errors    

Don't click on a point to zoom. On some other interactive map tools out there on the Web, you click on the point you want to zoom in on, and you zoom in by a factor of 2 (or 5, or whatever). On Voyager clicking on a point is a pan. To zoom, rubberband box an area. Then to "un-zoom" (go back to previous zoom levels), click on [Up] one or more times, stopping at whatever previous level you want, all the way back to the global (Plate Carrée) map.

Don't try to use your browser {< Back} button to return to a previous zoom level. Instead, use the applet [Up] button. All states of your 'voyage of exploration' for a particular world are stored on the one browser page. This feature, for example, makes comparative planetology easier, because you can then use the browser's {< Back} and {Forward >} buttons to quickly switch back and forth between views of different worlds.

Don't get over-exuberant with mouse clicking. After you drag any rubberband zoom box, or click on any point to pan: wait patiently until the next image is completely loaded before going on to the next task. (While you're waiting, just enjoy the image you already have.) It may take a while to create the map and return it to your browser, especially for complex ' view from space' index maps.

There is no index map when viewing the global Plate Carrée map, so don't expect anything if you click on [Index] when you are on that map. (The [Index] button will appear in dark lettering to remind you that it doesn't do anything when you are viewing the global map.)

Likewise, clicking on [Up] when viewing the global Plate Carrée map doesn't do anything, because you are already at the top of the Voyager zoom stack and looking at a global image. (You are as far 'up' as you are going to go. Again, the [Up] button will appear in dark lettering to help you remember this.)

Clicking on [Down] will only do something after zooming one or more times and after moving back [Up] the zoom stack. Only then can you move [Down] the zoom stack to a previously defined zoom level.

You can't zoom or pan when on any index map. Click on the [Local] button to return to the corresponding 'local' map, and then continue to zoom or pan.

As explained above in the gory details, some selected items only show up on zoomed local maps, for example:

  • the distance scale
  • most labels (e.g. cities, country names, GPS site labels, planetary mission info, etc.)

On Voyager: Earth, trying to view a place on land only but having [Land, white] or [Land, black] set when requesting a background texture underlay grid (e.g. [Face of the Earth, relief], [Topography, color, relief], etc.) with land filling set, rather than outlining, result is seeing just white or black land. You want the land "transparent" (which normally allows you to see back to the background) in order to see the underlying continuous surface grid, so both [Land, white] and [Land, black] must be deselected in this case, or click on on [Land: outline/fill] to switch to just land outlining (coastal borders). (This is a bit of confusion we are trying to sort out without giving up user functionality.)

Known map image problems     We have noticed a few problems with the map images on occasion. Some of these are produced by bugs in our GMT-driver (i.e. our GMT-driver may send the GMT programs what they consider nonsense, a la garbage in, garbage out), a few seem to be due to bugs in one or more GMT programs, and so on. Known items are:

  • any world:
    • When viewing a global surface grid (e.g. topography), there may be a thin black band at some line of longitude (usually 180°W = 180°E) for some zoom levels. This is the wrap-around longitude for the GMT texture underlay grid being used. (The line is most likely a GMT processing artifact.)
    • The zoom box generated by the Voyager Java applet is a little difficult to see if the underlying image is a greytone. (Java related; probably nothing can easily be done to correct this.)
  • Earth (associated with the GMT pscoast routine):
    • When the land colorization is not black (or not transparent, in which case the land also looks black since we are using a black page background), there may be faint lines parallel certain latitude and longitude lines on the map, either on the land or on the water. The root cause of this is a latitude-longitude block "paneling" that is done by pscoast to fill in the water or land color. Pscoast is not the culprit, however (or at least not directly). The problem seems to do with imprecise antialiasing when converting the PostScript image to a pixel format such as GIF. Thus the faint lat/lon lines are not present in the PostScript file, but show up in the GIF file used by Voyager. So if you get the PostScript file and use it directly, you won't get the faint lines.
    • The ocean colorization for some resolutions has large longitude/latitude bounded miscolorizations in certain reproducable areas. (For those of you who have GMT-savvy, this occurs most often when using the -Dl resolution, which will be used when trying to display a hemisphere or some other large corner-to-corner span with Voyager.)
    • At certain extreme zooms with topography turned off, the water areas go white, and the land areas go black — but the land-water outlines are still OK. (This is a GMT quirk.)
  • Moon, Io, and a few other texture underlay grids:
    • The Moon's Clementine greytone texture underlay was constructed from a JPEG image, resulting in the black band at 180°W = 180°E, which was the left and right border of the JPEG image; Io's Galileo (USGS) texture underlay has the same problem at 0°W = 0°W. This problem often occurs on texture maps if we started from a JPEG (which is a lossy format), and sometimes if we started from a GIF. (We could easily correct this problem if we had access to an equivalent TIFF image.) A similiar-looking gap on Jupiter's Cassini texture underlay is due to an actual 0.2° gap of data in the image we used.
If your browser has a Java console, send us the "back:" line that occurred plus as detailed a description as possible of what you did for any strange result not covered here.

Java shortcomings     Unfortunately, the types of graphics widgets available under Java 1.0 or 1.1 in the AWT (Abstract Window Toolkit) leave quite a bit to be desired. What is really needed here for the widget menus (like [Features:]) are checkbox menus — so that the user can see what has been selected/deselected. However, the only checkbox menus in the Java AWT are only available on menu bars, which cannot be present in applets. So we have sort of cooked our own here (using a Choice option menu). Using this, however, there is nothing that can be dynamically changed for each individual item to indicate whether it has been selected or not. Hence, we have added a text display below the two menus to show what is currently selected. (Better solutions are available under Java 1.2, with the Swing user interface classes which replace the AWT. We'll be working on redoing the Java component of Voyager using Java 1.2.)

Also, if you use your browser {< Back} or {Forward >} buttons, use bookmarks, etc. to go to other Web pages and then return to Voyager, the Java applet buttons may no longer function. In this case, see reload the Voyager applet.

To restart Voyager Java applet     If you think you might need to reload/restart the Voyager Java applet, hold down <Shift> on your keyboard and click the {Reload} or {Refresh} button on your browser, though this does not work with all browsers. If this doesn't work, you may have to kill your browser, restart it, and reload Voyager.

What we're working on     Here's a quick list of items we're working on (please don't contact us about these items — unless about some specific detail):

  • migrating to GMT 3.4 for added functionality and bugs fixes presently at 3.3.6
  • optional length/area scale added 7 May 2001
  • optional longitude/latitude lines w/ labeling added 7 May 2001
  • additional Earth features:
    • additional velocity solutions always in progress
    • additional texture underlay grids always in progress
  • low resolution (2-4 pixels/degree) surface images of planetary bodies from Maps of the Solar System or elsewhere
  • adding feature names on planetary bodies
And here's what we're looking for...

Comments, questions, problems about Jules Verne Voyager? Send mail to Lou Estey
(louunavco.org)

UNAVCO | Support | About Us | Contact Us | Search
jules homepage     Voyager: About Voyager | What's New | Information Sources


  Comments: webmasterunavco.org
  Jules Verne Voyager: Advanced Help last modified on Fri, 15 Apr 2005 18:59:54 UTC
  © Copyright