Using VH Editor
VH Editor User's Guide
This serves as a brief user's guide for VH Editor. VH
Editor was originally written to convert map data between various raw
formats and a format that can be used by Virtual Hiker. It has since
grown into more of a software technology demonstrator for Virtual Hiker and
to a lesser extent is a map editor.
VH Editor is not difficult to use, but there are a few things that
should be explained. These notes cover each feature of VH Editor
and is organized according to the menu where that feature can be found.
New: If you choose "New" from the File menu,
a new blank map window will be created. You can have as many map
windows open as you want (until you run out of memory).
Open...: If you choose "Open..." from the File
menu and select a valid map file, that file will be opened in the current
window (if that window is blank) or a new window (if the current window
has something in it).
Open Database...: If you choose "Open Database..."
from the File menu, you can open an XML format file that contains information
linking DLG map elements to HTML files containing descriptions of those
items. This feature is extremely immature at this point. Right
now, the HTML files must all be in a directory named "data" which is at
the same location as the program executable.
Merge...: If you choose "Merge..." from the File menu
and select a valid map file, the program will attempt to load the new
map data into the same window as the currently loaded map data. It
will check to make sure that the new map is either overlapping or adjacent
to the current map data before loading it up. If the new map is not overlapping
or adjacent, it will be opened in a new window (just like Open...).
This allows you to read multiple map layers into a single window as well
as the ability to load up adjacent maps so that they are tiled together
in the 2D view. You can load up as many different map layers as you
have RAM for or until you have loaded 256 MB worth (I can expand that arbitrary
limit at any time). You can accomplish the same thing using the "Open..."
menu item if you open a merge list file (*.mlst -- see the file format descriptions).
Close: If you choose "Close" from the File menu,
the current map window will be closed (if changes have been made, it
will ask if you want to save them). The exact same thing happens
if you click on the "close" widget for the window. On Microsoft
Windows or Linux, when you close the last map window, the program will
exit. On MacOS X, when you close the last map window, the program
will not exit, but will remain running as a menu bar without any open
windows. This is consistent with Macintosh user expectations.
Save As...: If you choose "Save As..." from the
File menu, you can save the map data in the current window to a "mapz"
file (a binary file containing the object structure for the map window's
contents serialized and compressed). The "mapz" format is the native
file format for Virtual Hiker. You will be asked to pick a map layer.
One of the options is "All Map Layers". So, you can save only a single
layer or all the layers together. You can not save DRG layers to
mapz files at this time (only DEM & DLG layers).
There is currently no printing capability. It is desperately
needed, but I haven't had time to implement it yet. It's on my Feature
Remove Layer...: If you choose "Remove Layer..."
from the Edit menu, you will be asked to select a single layer to be removed.
If that layer has unsaved changes, you will be asked if you want
to save them first.
Arrange Layers...: If you choose "Arrange Layers..."
from the Edit menu, a dialog will be presented where the order of the currently
loaded map layers from front to back can be changed.
Sadly, there is currently no undo/redo functionality.
Get Info...: If you choose "Get Info..." from
the Analysis menu, you can get information on any map layer that is loaded
into the current window. This information includes the quadrangle
boundaries, the number of data points in the rows and columns of a DEM,
the minimum and maximum altitude in a DEM, and lists of all the nodes, lines
and areas in a DLG and the attributes assigned to them.
Find Contours...: If you choose "Find Contours..."
from the Analysis menu, you can generate a custom DLG hypsography map
layer (contour map) from any loaded DEM map layer. There is one
known issue where, especially for 10m resolution DEMs, the Java stack
space can be exceeded and an error will be reported. To use this
feature with such high resolution DEMs will require using a different contour
line generation algorithm.
Tile Image File...: If you choose "Tile Image
File..." from the Analysis menu, you can choose any GIF, JPEG, or PNG image,
then specify an output filename and the selected image will be converted
to the Virtual Hiker specific Tiled Image (TIz) format. This format
is vastly more efficient for rendering DRG map layers at high resolution
than using a huge GIF image. Using this file format, you can have
literally dozens of DRG map layers open at a time without running out of
The tiling process may take a very long time depending on the size
of the original image and the speed of your computer. Java's image
processing performance is pretty poor. The time it takes to tile
an image can be greatly decreased by doing the image scaling in another
more efficient program such as PhotoShop or gimp. To do this, use the following
Once you have done this, run the Tile Image File... option in VH Editor
and it will use your pre-scaled images rather than scaling them in Java.
- Load the original image and convert to RGB from indexed
color if necessary.
- Trim off any border areas that you don't want to be
shown in the program. Make borders transparent if possible.
- Scale the original image by 50%.
- Save the scaled image with he same name (and type) as
the original but with "M1" appended to the filename. For example,
if the original image was "Sunrise.gif". Then the scaled image would
- Now scale the image down by 50% again (or even better
scale the original down to 25% of the original size).
- Save the scaled down image with the same name (and type)
as the original but with "M2" appended to the name. For example:
- Keep scaling down and incrementing the "M" number until
the width and height of the scaled image is less than 512
Texture from DRG...: If you choose "Texture from
DRG..." from the Analysis menu, you can create a texture map for use
in the 3D view from all the DRG map layers and associated DEM layers.
Just load in all the DEM layers that you want to display in 3D, then load
in the DRGs that are associated with those layers, then execute this
command. It will ask for a name for the texture file (textures are
saved in PNG format and can be edited with most graphic editing programs)
and it will ask for the size of the texture in pixels (texture maps are
square and I recommend either using 512 or 1024 -- anything larger will
likely choke off your video card). Then it will generate the texture
map and save it. This texture map can then be used with the 3D view.
Note that anything that you can coerce into loading as a DRG can be
turned into a texture map this way. For example map rectified aerial
photographs or satellite photos. You can also use any image at all
as a texture for the 3D view by saving it in PNG format.
Under the View menu you can hide/show whole layers at a
time or the individual element types in the DLG layers.
The Tool Bar
Along the right edge of the window is a tool bar.
The tools in this tool bar are defined as follows:
The Cross Hair:
Used to pick a point on the map. The latitude, longitude,
altitude (if a DEM is loaded), and magnetic offset from true north of
the selected point are reported at the bottom of the screen.
The Magnifying Glass:
Used to zoom in or out. Click on the map to zoom in.
Hold in the Shift key and click on the map to zoom out. Either way,
the window will be re-centered about the point where you click.
The Pointing Hand:
If you have a DLG loaded, you can use this tool to pick DLG
items. Information about those items will be displayed (a bit primitively
right now). In addition, if you have an XML database loaded that refers
to the selected DLG item, more information will be displayed and a web page
may be opened in your default web browser for the item.
This allows you to trace out your own custom lines on the map.
If the line is drawn over a DEM, then you will get an altitude vs. distance
profile for the path. Right now this is about all you can do with
this tool, but eventually it will be a more functional editing tool (so
you can set attributes for the line traced out, etc). I also plan
to add the ability to do way-points and join trails together, break apart,
etc. You can save custom trails to their own files if you want, but
there is really no reason to do so since you can't interact with them later
The 3D View:
If at least one DEM map layer is loaded, this button will bring
up a 3D view of the adjacent loaded DEM(s). It may take a minute
(or two) to prepare the 3D view if a lot of DEM layers are loaded, so be
patient. A progress bar will be displayed.
The 2D map window has a pop-up menu that will appear of
you right-click (control-click on single button mouse systems) the mouse
on the map window. This menu current has the following items:
- Zoom In: Just like clicking with the magnifying glass
- Zoom Out: Just like shift-clicking with the magnifying glass
- Zoom to 1:24k: Zoom's the map scale to 1:24000 (standard
USGS topo-map scale).
- Move 3D Viewpoint Here: If a 3D view of the current map
window is open, this will move the 3D viewpoint to the specified location.
This is handy for rapidly transporting the 3D viewpoint to any location
on the 2D map without having to actually "fly" there.
3D View Window
By default, the 3D view comes up with a simple random stipple
pattern (in green) for a texture map. You can change the texture map by choosing
an option from the "Texture" menu. The options are "Fractal", "Altitude
Based", and "From Disk". The Fractal is currently the random stipple
(so it isn't really a fractal yet). The "Altitude Based" uses shades
of gray representing altitude (just like the DEM in the 2D view). This
option only works if you have a single DEM loaded. The "From Disk" option
lets you pick an arbitrary (but square) PNG (Portable Network Graphic) format
image file from disk. You can create an appropriate PNG file for use
as a texture map from the main map window's "Texture from DRG..." item under
Analysis, or you can create your own with any graphic editor. Or, you
can start with the one generated from a DRG and edit it to look any way you
like. The only limitation is that the texture map must be square and
most graphics cards have difficulty if the texture map is to large.
How large is to large? That depends on your graphics card. Mine
is limited to 1024x1024, but it is over 5 years old. Your mileage may
At the top of the 3D view window are 3 buttons. "Fly", "Drive",
and "Orbit". By default, the fly option is chosen. This lets
you fly around in 3D space. You can not penetrate the ground nor
fly much beyond the boundaries of the map. If you choose the "Drive"
option, your position is constrained to being a few meters above ground
at all times. If you choose the "Orbit" option, you are put into drive
mode and then sent on a pre-defined path around the terrain (an ellipse
fit within the bounds of the map) and you always look towards the center
of the map. I plan on adding more options for following preset paths
in the future. This is just a proof of concept right now.
On the left hand side of the 3D view is a slider that can be used
to control speed. You can fly or drive forward or backward up to
500 meters per second (about 1100 mph). The velocity is always relative
to the current view direction. So, you always fly or drive the
direction you are looking. You have no inertia and there are no
flight dynamics. So, you can do some pretty wild stunts. :-)
Below the speed slider is a stop sign that will stop any forward or backward
motion (sets your speed to zero).
Above the Speed Slider are two arrows. These are used when
you are stationary to step you forward or back by 5 meters at a time.
The up arrow steps you forward, the down arrow steps you back.
Above the 3D view area, but below the fly, drive, and orbit buttons,
is a horizontal slider that sets the level of detail used when rendering
the terrain. If you move this slider more to the right, you get
more detail (triangles) drawn on each frame, but the rendering takes longer
(you get lower frame rates and things become jumpy). If you move it
to the left, you get less detail on each frame and the rendering is much
faster (you get higher frame rates and things animate more smoothly).
The setting that works best for you depends on your computer's performance.
In the future, I'd like to replace this slider with a method that automatically
sets the level of detail to maintain a decent frame rate.
To the left of the level-of-detail slider is a text field that reports
on how many triangles are being rendered for each frame. This is
just a hold-over from when I was debugging the terrain rendering algorithms.
Since my computer is old and slow, I will typically use a lower detail setting
to fly around. Then, once I get a spot that I like, I stop moving
and crank up the detail to get a final view. On a newer fast computer,
you can keep the level of detail pretty high all the time.
Below the level-of-detail slider is the instrument panel.
On this display you will find a compass that indicates the direction you
are looking. Right above the compass is a pair of toggle buttons that
let you switch from true heading to magnetic heading on the compass display.
There is also an artificial horizon that gives an indication of how much
you are looking up or down. Finally, there is a text box that displays