Help Topic: Background Region Images
Maintained by: mikerb@mit.edu 
Get PDF
Background Region Images
In both pMarineViewer and alogview, typical use involves a background region image upon which vehicles and other geometric objects are overlayed. Both utilies can be configured to use images of their own choosing. See examples in Figure 1.1. The user provides these images from whatever source they wish. Options for obtaining images and proper format are discussed below in the section Obtaining Image Files.
Figure 1.1: Example Background Region Images: The example images downloaded from freely available tile servers that may be utilized in either pMarineViewer or alogview.
Default Packaged Images [top]
Image files can be large, and of course there are endless possibilities depending on where you are operarating and which kind of background images you prefer. That being said, a couple images are distributed with MOOS-IvP. This allows example missions distributed with the MOOS-IvP code to having working images out-of-the-box without requiring the new user to fetch images. These two images are for (a) the MIT Sailing Pavilion, and (b) Forest Lake in Gray Maine, the site of some of the earliest in-water experiments circa 2004. This files are:
- MIT_SP.tif
- forrest19.tif
Both are distributed with MOOS-IvP and can be found in moos-ivp/ivp/data. When pMarineViewer or alogview is launched, this directory will be examined for the specified image file. Instructions for loading user-provided images is are given below in section Loading Images at Run Time.
Image File Format and Meta Data (Info Files) [top]
Images loaded into pMarineViewer and alogview are in the format of "Tiff" files. These files have the suffix ".tif". Tiff files have been around since the eighties, use lossless compression, are typically high quality, but are not as common as formats such as jpeg. There are many freely available tools for converting back and forth between tiff and jpeg and other formats. Tiff files are used in pMarineViewer and alogview primarily due to the availability of the libtiff library, readily available through package managers on both the MacOS and Linux platforms.
Each .tif file used in pMarineViewer and alogview has a corresponding .info file, containing (a) the latitude and longitude coordinates of the image edges, and (b) the datum, or (0,0) coordinate, on the image. For example, the MIT_SP.tif file has a corresonding MIT_SP.info file found in the same directory.
lat_north = 42.360264 lat_south = 42.35415 lon_east = -71.080058 lon_west = -71.094214 datum_lat = 42.358436 datum_lon = -71.087448
Obtaining Image Files [top]
Image files may be obtained and used in pMarineViewer and alogview from any source convenient to the user. This includes opening an image in say Google Maps on a web browser and performing a screen grab. The drawback of this method however is that it may be hard to precisely determine the lat/lon coordinates of the edges used in the corresponding .info file.
There are several open tile servers which allow a user to download an image tile, or set of tiles, provided with a range of lat/lon coordinates. These tiles can then be stitched together to make a single image. Although this sounds cumbersome, this process can be automated in a script. One such script is Anaxi Map, written by Conlan Cesar:
https://github.com/HeroCC/AnaxiMap
This utility is capable of using one of several tile servers with various background styles, such as Google Maps, maps with terrain or bathymetry information, or maps with street data. See Figure 1.1.
AnaxiMap, or similar utilities, may produce images in jpeg or png format. MacOS and Linux provide native utilities for converting the format, or "exporting" the file, to tiff format. On MacOS or Linux, if the free ImageMagick package is installed, you can use the "convert" utility:
$ convert region.jpg region.tif
Loading Images at Run Time [top]
Post Release 22.8, both pMarineViewer and alogview support operation with multiple background images. Toggling between images at run time is done by selecting the BackView pull-down menu and selcting tiff_type toggle, or by simply hitting the ` (back-tick) key.
In pMarineViewer, the multiple background images may be specified with multiple configuration lines, for example:
tiff_file = MIT_SP.tif tiff_file = mit_sp_osm18.tif
In alogview, the multiple background images may be specified on the command line:
$ alogview --bg=MIT_SP.tif --bg=mit_sp_osm18.tif file.alog
Automatic alogview Detection of Background Image [top]
When launching alogview typically the user wants to use the same background region image used by pMarineViewer during the course of the mission that generated the alog file. In a new feature, post Release 22.8, alogview will automatically attempt to detect the image file used by pMarineViewer. The name name of region image is now published by pMarineViewer during the execution of the mission. This information is contained in the variable REGION_INFO. For example:
REGION_INFO = lat_datum=42.358436, lon_datum=-71.087448, img_file=MIT_SP.tif,\
zoom=2.5, pan_x=129, pan_y=-364
The region info contains the name of the image (tiff) file used during the course of the mission, as well as the pan and zoom information as hints for alogview for use upon startup. The images found in REGION_INFO in the alog file will be loaded, as well as any images specified on the command line with the --bg options.
Background Image Path [top]
Support for the IVP_IMAGE_DIRS shell path is a new feature, post Release 22.8, relevant to both pMarineViewer and alogview. This is explained below.
Image files are named in either the pMarineViewer config block of the .moos mission file, or named on the command line when launching alogview, as specified in Section Loading Images at Run Time. For alogview, the file may also be named in the REGION_INFO logged variable as discussed above.
Both apps need to find the named .tif file. When found, it looks for the corresponding .info file in the same directory. There are four options for making this work:
- The image file is in the same directory as the mission file.
- The image file is in the special directory moos-ivp/ivp/data.
- The full or relative path name of the file is specified.
- The file exists in a directory on your IVP_IMAGE_DIRS path.
The first option has the drawback of duplicating the image file in potentially many places. The second option has the drawback that the directory moos-ivp/ivp/data is part of the MOOS-IvP code distribution which users otherwise consider to be read-only. A fresh check out of MOOS-IvP would reset this directory and users would need to take care to migrate files to a new checkout. The third option is that full or relative path name may not be the same between different users or machines. The fourth option is the newest option and arguably has the least downside.
The IVP_IMAGE_DIRS is shell (e.g., bash) environment variable. It contains a list of one or more directories on your local computer where pMarineViewer or alogview will look when attempting to load image files. Shell environment variables are already common settings that users will customize on their particular machine.
The recommended way for users to use a set of custom image files is to (a) organize them in one or more directories, preferably under version control, (b) install them at a convenient location on your local machine, (c) configure the IVP_IMAGE_DIRS shell variable to contain the one or more directories where your image files reside.
For example, if you have a folder of image files with the following structure:
my_images/
napa_bay/
napa_bay_gmaps.tif
napa_bay_gmaps.info
napa_bay_osm.tif
napa_bay_osm.info
happy_harbor/
happy_harbor_gmaps.tif
happy_harbor_gmaps.info
happy_harbor_osm.tif
happy_harbor_osm.info
If this folder is installed on your machine in the home dirctory folder call "project", then you would set your IVP_IMAGE_DIRS path in your shell configuration file, e.g., .bashrc, as follows:
IVP_IMAGE_DIRS=~/project/napa_bay IVP_IMAGE_DIRS+=:~/project/happy_harbor
To verify which file has been loaded, the appcasing output of pMarineViewer shows the full path name of the loaded file(s). And when alogview is launched, the terminal output indicates which directories are being searched, in order, for the image files. This information may be obscured however when the alogview window pops up, but you can find it if you go back to it and perhaps scroll up. Note: It is not sufficient, in the example above, to simply set IVP_IMG_DIR=~/project, the parent directory of all image folders. Each image folder must be named.
Troubleshooting [top]
pMarineViewer fails to load the image (see only gray screen) [top]
- Check the appcasting output of pMarineViewer. The top few lines should show which image file is loaded. Is this a file you recognize?
- Does this file exist on your computer? Verify it is where you think it is.
- How are you specifying this file in your pMarineViewer config block? If it is specified as a relative path, e.g., ../my_images/napa_bay.tif, make sure that relative path location is correct.
- If you are specifying the image file with just the file name (no path information), then check you have your IVP_IMAGE_DIRS variable set properly. Run echo $IVP_IMAGE_DIRS on the command line.
- Simplest but most common: Make sure your image file name (configuration and actual name) end in the suffix .tif and not .tiff.
pMarineViewer or alogview image is fine but no vehicles [top]
- Check the .info file. Make sure the lat/lon values sanity check, e.g., rough magnitude, relative values.
- Make sure the datum_lat and datum_lon values are in the range of the image.
- Make sure the datum_lat and datum_lon values match the datum set at the top of the vehicle and shoreside mission files.
alogview fails to load the image (see only gray screen) [top]
In the newer version of alogview, when launching it will attempt to read the name of the image file used by pMarineViewer. So if pMarineViewer launched ok, chanches are good alogview will also launch with the same image. However, it could be the case that (a) the mission was run on some other computer that contained the image file and your current computer does not. The image file is not logged. (b) the mission was named
- Does this file exist on your computer? Verify it is where you think it is. It is possible that you are trying to run alogview on your computer with alog files generated on someone else's computer. Make sure you have the image file.
- Check the terminal output of alogview as it is loading. To demonstrate the below output from an alogview launch purposely use the the file dforrest19.tif instead of forrest19.tif. Note the sequences of folders searched in the attempt to find the image file. The first attempt is the in the moos-ivp/ivp/data directory. The next attempts are based on the value of IVP_IMAGE_DIRS. The final attempt is in the current working directory where alogview was launched. Does this match up with your expectations?
TIFF FILES COUNT:1 [1] Looking for dforrest19.tif and dforrest19.info in: Dir: [/Users/james/moos-ivp/ivp/data] Not found. [2] Looking for dforrest19.tif and dforrest19.info in: Dir: [/Users/james/pavlab_map_images/popolopen] [3] Looking for dforrest19.tif and dforrest19.info in: Dir: [/Users/james/pavlab_map_images/mit] [4] Looking for dforrest19.tif and dforrest19.info in: Dir: [/Users/james/moos-ivp/ivp/datax] [5] Looking for dforrest19.tif and dforrest19.info in: Dir: [/Users/james/moos-ivp/ivp/data-local] [6] Looking for dforrest19.tif and dforrest19.info in: Dir: [/Users/james/moos-ivp/ivp/data] [*] Looking for dforrest19.tif and dforrest19.info in: Dir: [./] Not found. Could not find the pair of files: dforrest19.tif and dforrest19.info Opening Tiff: TIFFOpen: : No such file or directory. Failed!!!!!!!!!
- Simplest but most common: Make sure your image file name (configuration and actual name) end in the suffix .tif and not .tiff.
Page built from LaTeX source using texwiki, developed at MIT. Errata to issues@moos-ivp.org. Get PDF