Expand the theia doc (#386)

* Expand the Theia doc

* More Theia tweaks

Author: oleg-alexandrov

localization/sparse_mapping/theia_map.md

@@ -2,18 +2,23 @@
 
 Theia (https://github.com/sweeneychris/TheiaSfM) is a package for
 global structure-from-motion (SfM). It may be faster and require less
-user effort than the method used in Astrobee which consists of
-creating submaps using incremental SfM on sequences of images that
-overlap with their immediate neighbors, followed by merging the
-submaps. Theia uses "cascade matching" to handle non-sequential image
-acquisitions.
+user effort than the method used in Astrobee (see \ref map_building)
+which consists of creating submaps using incremental SfM on sequences
+of images that overlap with their immediate neighbors, followed by
+merging the submaps. Theia uses "cascade matching" to handle
+non-sequential image acquisitions.
 
 The Theia approach was tested on about 700 images acquired at
 different times and it did well. It is currently studied as an
 alternative to Astrobee's approach.
 
 # Install Theia's prerequisites
 
+It is suggested to use ``conda`` to install Theia's dependencies. The
+conda toolset does not require root access and creates a set of
+consistent libraries at a custom location in your home directory,
+which are largely independent of your particular Linux system.
+
 Fetch and install ``conda`` from:
 
     https://docs.conda.io/projects/conda/en/latest/user-guide/install/linux.html
@@ -34,7 +39,7 @@ Run the following command to install some packages and GCC 11:
       ceres-solver=1.14.0=h0948850_10
 
 The Ceres package can be quite particular about the version of Eigen
-it uses, and some versions of Ceres are not built with suitesparse
+it uses, and some versions of Ceres are not built with ``suitesparse``,
 which is a sparse solver that is needed for best performance, so some
 care is needed with choosing the versions of the packages.
 
@@ -53,42 +58,122 @@ view_reconstruction. That visualizer logic is not easy to compile
 and is not needed.
 
 Run ``which cmake`` to ensure its version in the ``theia`` environemnt
-installed earlier is used. Otherwise run again ``conda activate
-theia``.  Do:
+installed earlier is used. Otherwise run again:
+
+    conda activate theia
+
+Do:
 
     mkdir build
     cd build
     cmake ..
     make -j 20
 
 This will create the executables ``build_reconstruction`` and
-``export_to_nvm_file`` in the ``bin`` subdirectory of ``build``. That
-directory needs to be added to the PATH.
+``export_to_nvm_file`` in the ``bin`` subdirectory of ``build``. 
 
-# Run the Astrobee wrapper around the Theia tools
+# Hide the conda environment
 
 The conda environment set up earlier will confuse the lookup the
-dependencies for the Astrobee libraries. Hence the lines ``conda`` added
-to one's ``.bashrc`` should be removed, the bash shell restarted, and
-one should ensure that the ``env`` command has no mentions of conda.
+dependencies for the Astrobee libraries. Hence remove the block of
+lines starting and ending with ``conda initialize`` which conda added
+to your ~/.bashrc, then close and reopen your terminal. Ensure that
+the ``env`` command shows no mention of conda.
 
-Set the environment. The following lines should be adjusted as needed,
-especially the robot name:
+# Set up the environment for Theia and Astrobee
 
-    export ASTROBEE_SOURCE_PATH=$HOME/projects/astrobee/src
-    source $ASTROBEE_SOURCE_PATH/../devel/setup.bash
+Add the Theia tools to your path as:
+
+    export PATH=/path/to/TheiaSfM/build/bin:$PATH
+
+Set up the environment for Astrobee, including the robot name. These
+should be adjusted as needed:
+
+    export ASTROBEE_BUILD_PATH=$HOME/astrobee
+    export ASTROBEE_SOURCE_PATH=$ASTROBEE_BUILD_PATH/src
+    source $ASTROBEE_BUILD_PATH/devel/setup.bash
     export ASTROBEE_RESOURCE_DIR=$ASTROBEE_SOURCE_PATH/astrobee/resources
     export ASTROBEE_CONFIG_DIR=$ASTROBEE_SOURCE_PATH/astrobee/config
     export ASTROBEE_WORLD=iss
     export ASTROBEE_ROBOT=bumble
 
+Add some Astrobee tools to the path as well:
+
+    export PATH=$ASTROBEE_BUILD_PATH/devel/lib/sparse_mapping:$PATH
+
+Please note that if the robot name, as specified in
+``ASTROBEE_ROBOT``, is incorrect, you will get poor results.
+
+# Prepare the data
+
+The data preparation is the same as used with the usual Astrobee
+map-building software documented in \ref map_building. To summarize,
+the steps are as follows.
+
+Extract the data from the bag:
+
+    $ASTROBEE_BUILD_PATH/devel/lib/localization_node/extract_image_bag \
+      bagfile.bag -use_timestamp_as_image_name                         \
+      -image_topic /hw/cam_nav -output_directory image_dir
+
+If the images were recorded with the image sampler, the nav_cam image
+topic needs to be changed to:
+
+    /mgt/img_sampler/nav_cam/image_record
+
+The ``-use_timestamp_as_image_name`` option is not strictly necessary,
+but it is helpful if a lot of datasets needs to be processed
+jointly. With it, the image filename is the timestamp (in
+double-precision seconds since epoch), which provides for a rather
+unique name, as compared to using the image index in the bag without
+that option.
+
+Select a subset of the images:
+
+    select_images -density_factor 1.4 image_dir/*.jpg
+
+This will delete a lot of similar images from that directory. This is
+not a foolproof process, and sometimes too many images are deleted but
+most of the time too many are left.  It is suggested to open the
+remaining images with ``eog`` as:
+
+    eog image_dir/*.jpg
+
+and use the ``Delete`` key to remove redundant ones. The
+``nvm_visualize`` tool (see \ref sparsemapping) can be used exactly as
+``eog``, and it has the advantage that it echoes the current image
+name in the terminal, which can be useful in some occasions.
+
+A good rule of thumb is for each image to have a 4/5 overlap with the
+next one. Too much or too little overlap will cause Theia to fail.
+
+It is suggested to avoid images with pure camera rotation, or at least
+to have in the mix additional images of the same environemnt without
+such rotations.
+
+Put the selected images in a list:
+
+  ls image_dir/*jpg > image_list.txt
+ 
+# Run the Astrobee wrapper around the Theia tools
+
     python $ASTROBEE_SOURCE_PATH/localization/sparse_mapping/tools/build_theia_map.py \
        --output_map theia.map --work_dir theia_work --image_list image_list.txt
 
 This will take care of preparing everything Theia needs, will run it,
-and will export the resulting map to Astrobee's expected format. This
-map will need to be registered and visualized as described in other
-documentation. The work directory can be deleted later.
+and will export the resulting map to Astrobee's expected format. 
+
+It is suggested to first run this tool on a small subset of the data,
+perhaps made up of 10 images. A 700-image dataset may take perhaps 6
+hours on a machine with a couple of dozen cores and use up perhaps 20
+GB of RAM.
+
+The obtained map can be examined with ``nvm_visualize``, as described
+in \ref sparsemapping.
+
+The work directory can be deleted later.
+
+# Command line options
 
 This tool has the following command-line options:
 
@@ -106,6 +191,15 @@ This tool has the following command-line options:
       imported from Theia. This is for testing purposes.
     --help: Show this help message and exit.
 
+# Next steps
+
+This map will need to be registered and visualized as described in
+\ref map_building.
+
+That page also has information for how the map can be rebuilt to use
+BRISK features, and how it can be validated for localization by
+playing a bag against it.
+
 # Auxiliary import_map tool
 
 This tool is used to import a map from the NVM format, which Theia