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.

File Menu

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

Edit Menu

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.

Analysis Menu

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

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 steps:

1. Load the original image and convert to RGB from indexed color if necessary.
2. Trim off any border areas that you don't want to be shown in the program.  Make borders transparent if possible.
   
3. Scale the original image by 50%.
4. 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 be "SunriseM1.gif".
5. Now scale the image down by 50% again (or even better scale the original down to 25% of the original size).
6. Save the scaled down image with the same name (and type) as the original but with "M2" appended to the name.  For example:  "SunriseM2.gif".
7. Keep scaling down and incrementing the "M" number until the width and height of the  scaled image is less than 512 pixels.

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.

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.

View Menu

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.

The Pencil:
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 (right now).

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.

Pop-Up Menu

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 tool.
• Zoom Out: Just like shift-clicking with the magnifying glass tool.
• 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 vary.

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