<html><head><meta name="color-scheme" content="light dark"></head><body><pre style="word-wrap: break-word; white-space: pre-wrap;">\section{Background Region Images}
%=================================================================

In both \app{pMarineViewer} and \app{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 \ref{fig_img_samples}. The
user provides these images from whatever source they wish. Options for
obtaining images and proper format are discussed below in the section
{\em Obtaining Image Files}.

\vspace{0.1in}
\begin{figure}[H]
  \centering 
  \includegraphics[width=0.92\textwidth]{figs_help/img_samples.png}
  \caption{{\bf Example Background Region Images}: The example images
    downloaded from freely available tile servers that may be utilized
    in either \app{pMarineViewer} or \app{alogview}.}
\label{fig_img_samples}
\end{figure}

%=================================================================
\subsection{Default Packaged Images}
%=================================================================

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:

\begin{packed_itemize}
\item \var{MIT\_SP.tif}
\item \var{forrest19.tif}
\end{packed_itemize}

\vspace{0.1in}
\noindent
Both are distributed with MOOS-IvP and can be found in
\var{moos-ivp/ivp/data}. When \app{pMarineViewer} or \app{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 {\em Loading Images at Run Time}.

%=================================================================
\subsection{Image File Format and Meta Data (Info Files)}
%=================================================================

Images loaded into \app{pMarineViewer} and \app{alogview} are in the
format of \var{"Tiff"} files. These files have the suffix
\var{".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 \app{pMarineViewer} and \app{alogview}
primarily due to the availability of the \var{libtiff} library,
readily available through package managers on both the MacOS and Linux
platforms.

\vspace{0.1in}
\noindent
Each \var{.tif} file used in \app{pMarineViewer} and \app{alogview}
has a corresponding \var{.info} file, containing (a) the latitude
and longitude coordinates of the image edges, and (b) the datum, or
\var{(0,0)} coordinate, on the image. For example, the \var{MIT\_SP.tif}
file has a corresonding \var{MIT\_SP.info} file found in the same
directory.

\vspace{0.1in}
\begin{fileverb}
lat_north = 42.360264
lat_south = 42.35415
lon_east  = -71.080058
lon_west  = -71.094214
datum_lat = 42.358436
datum_lon = -71.087448
\end{fileverb}
\vspace{0.1in}

%=================================================================
\subsection{Obtaining Image Files}
\label{sec_anaxi}
%=================================================================

Image files may be obtained and used in \app{pMarineViewer} and
\app{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 \var{.info} file.

\vspace{0.1in}
\noindent
There are several open {\em 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:

\vspace{0.1in}
\noindent

\urlx{https://github.com/HeroCC/AnaxiMap}

\vspace{0.1in}
\noindent
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 \ref{fig_img_samples}.

\vspace{0.1in}
\noindent
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:

\vspace{0.1in}
\begin{consoleverb}
$ convert region.jpg region.tif
\end{consoleverb}
\vspace{0.1in}

%=================================================================
\subsection{Loading Images at Run Time}
\label{sec_img_load}
%=================================================================

Post Release 22.8, both \app{pMarineViewer} and \app{alogview} support
operation with multiple background images. Toggling between images at
run time is done by selecting the \var{BackView} pull-down menu and
selcting \var{tiff\_type toggle}, or by simply hitting the \var{`}
(back-tick) key.

\vspace{0.1in}
\noindent
In \app{pMarineViewer}, the multiple background images may be
specified with multiple configuration lines, for example:

\vspace{0.1in}
\begin{fileverb}
 tiff_file  = MIT_SP.tif
 tiff_file  = mit_sp_osm18.tif
\end{fileverb}
\vspace{0.1in}

\vspace{0.1in}
\noindent
In \app{alogview}, the multiple background images may be specified
on the command line:

\vspace{0.1in}
\begin{consoleverb}
 $ alogview --bg=MIT_SP.tif --bg=mit_sp_osm18.tif file.alog
\end{consoleverb}
\vspace{0.1in}

%=================================================================
\subsection{Automatic alogview Detection of Background Image}
\label{sec_alv_auto}
%=================================================================

When launching \app{alogview} typically the user wants to use the same
background region image used by \app{pMarineViewer} during the course
of the mission that generated the alog file.  In a new feature, post
Release 22.8, \app{alogview} will automatically attempt to detect the
image file used by \app{pMarineViewer}. The name name of region image
is now published by \app{pMarineViewer} during the execution of the
mission. This information is contained in the variable
\mvar{REGION\_INFO}. For example:

\prevgreen
\begin{verbatim}                                                                
  REGION_INFO = lat_datum=42.358436, lon_datum=-71.087448, img_file=MIT_SP.tif,\
                zoom=2.5, pan_x=129, pan_y=-364
\end{verbatim}
\postverb

\vspace{0.1in}
\noindent
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 \app{alogview} for use upon startup.  The images found in
\mvar{REGION\_INFO} in the \var{alog} file will be loaded, as well as
any images specified on the command line with the \var{--bg} options.

%=================================================================
\subsection{Background Image Path}
\label{sec_image_load}
%=================================================================

Support for the \var{IVP\_IMAGE\_DIRS} shell path is a new feature,
post Release 22.8, relevant to both \app{pMarineViewer} and
\app{alogview}. This is explained below.

\vspace{0.1in}
\noindent
Image files are named in either the \app{pMarineViewer} config block
of the \var{.moos} mission file, or named on the command line when
launching \app{alogview}, as specified in Section {\em Loading Images
  at Run Time}.  For \app{alogview}, the file may also be named in the
\mvar{REGION\_INFO} logged variable as discussed above.

\vspace{0.1in}
\noindent
Both apps need to {\em find} the named \var{.tif} file. When found,
it looks for the corresponding \var{.info} file in the same
directory. There are four options for making this work:

\begin{packed_itemize}
\item The image file is in the same directory as the mission file.
\item The image file is in the special directory \var{moos-ivp/ivp/data}.
\item The full or relative path name of the file is specified.
\item The file exists in a directory on your \var{IVP\_IMAGE\_DIRS}
  path.
\end{packed_itemize}

\vspace{0.1in}
\noindent
The first option has the drawback of duplicating the image file in
potentially many places. The second option has the drawback that the
directory \var{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.

\vspace{0.1in}
\noindent
The \var{IVP\_IMAGE\_DIRS} is shell (e.g., bash) environment
variable. It contains a list of one or more directories on your local
computer where \app{pMarineViewer} or \app{alogview} will look when
attempting to load image files. Shell environment variables are already
common settings that users will customize on their particular machine.

\vspace{0.1in}
\noindent
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 \var{IVP\_IMAGE\_DIRS} shell variable to
contain the one or more directories where your image files reside.

\vspace{0.1in}
\noindent
For example, if you have a folder of image files with the following structure:

\vspace{0.1in}
\begin{fileverb}
  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    
\end{fileverb}
\vspace{0.1in}

\vspace{0.1in}
\noindent
If this folder is installed on your machine in the home dirctory folder
call \var{"project"}, then you would set your \var{IVP\_IMAGE\_DIRS} path
in your shell configuration file, e.g., \var{.bashrc}, as follows:

\vspace{0.1in}
\begin{fileverb}
  IVP_IMAGE_DIRS=~/project/napa_bay
  IVP_IMAGE_DIRS+=:~/project/happy_harbor
\end{fileverb}
\vspace{0.1in}

\noindent
To verify which file has been loaded, the appcasing output of
\app{pMarineViewer} shows the full path name of the loaded file(s).
And when \app{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
\app{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 \var{IVP\_IMG\_DIR=~/project}, the parent directory
of all image folders. Each image folder must be named.


%=================================================================
\subsection{Troubleshooting}

%-----------------------------------------------------------------
\subsubsection{pMarineViewer fails to load the image (see only gray screen)}

\begin{packed_enumerate}

\item Check the appcasting output of \app{pMarineViewer}. The top few
  lines should show which image file is loaded. Is this a file you
  recognize?

\item Does this file exist on your computer? Verify it is where you think it is.

\item How are you specifying this file in your \app{pMarineViewer} config block?
  If it is specified as a relative path, e.g., \var{../my\_images/napa\_bay.tif},
  make sure that relative path location is correct.

\item If you are specifying the image file with just the file name (no
  path information), then check you have your \var{IVP\_IMAGE\_DIRS}
  variable set properly. Run \var{echo \$IVP\_IMAGE\_DIRS} on the command line.

\item Simplest but most common: Make sure your image file name (configuration and actual
  name) end in the suffix \var{.tif} and not \var{.tiff}.

\end{packed_enumerate}

  
%-----------------------------------------------------------------
\subsubsection{pMarineViewer or alogview image is fine but no vehicles}

\begin{packed_enumerate}

\item Check the \var{.info} file. Make sure the lat/lon values sanity check, e.g.,
  rough magnitude, relative values.

\item Make sure the \var{datum\_lat} and \var{datum\_lon} values are in the range
  of the image.

\item Make sure the \var{datum\_lat} and \var{datum\_lon} values match the datum
  set at the top of the vehicle and shoreside mission files.

\end{packed_enumerate}

%-----------------------------------------------------------------
\subsubsection{alogview fails to load the image (see only gray screen)}

In the newer version of \app{alogview}, when launching it will attempt
to read the name of the image file used by \app{pMarineViewer}. So if
\app{pMarineViewer} launched ok, chanches are good \app{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


\begin{packed_enumerate}

\item Does this file exist on your computer? Verify it is where you think it is.
  It is possible that you are trying to run \app{alogview} on your computer with
  alog files generated on someone else's computer. Make sure you have the image
  file.
  
\item Check the terminal output of \app{alogview} as it is loading. To
  demonstrate the below output from an \app{alogview} launch purposely
  use the the file \var{dforrest19.tif} instead of
  \var{forrest19.tif}. Note the sequences of folders searched in the
  attempt to find the image file. The first attempt is the in the
  \var{moos-ivp/ivp/data} directory. The next attempts are based on the
  value of \var{IVP\_IMAGE\_DIRS}. The final attempt is in the current
  working directory where \app{alogview} was launched. Does this match up
  with your expectations?

\vspace{0.1in}
\begin{consoleverb}

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!!!!!!!!!
\end{consoleverb}
\vspace{0.1in}
  
\item Simplest but most common: Make sure your image file name
  (configuration and actual name) end in the suffix \var{.tif} and not
  \var{.tiff}.

\end{packed_enumerate}

\normalsize
</pre></body></html>