work on docs

MRPT · Nov 20, 2015 · c40094f · c40094f
1 parent de22952
commit c40094f
Show file tree

Hide file tree

Showing 7 changed files with 136 additions and 44 deletions.
diff --git a/README.md b/README.md
@@ -5,6 +5,7 @@ TL;DR: **Sparser Relative Bundle Adjustment (SRBA)** is a header-only C++ librar
 Related papers: 
 * Moreno, F.A. and Blanco, J.L. and Gonzalez, J. **A constant-time SLAM back-end in the continuum between global mapping and submapping: application to visual stereo SLAM**, International Journal of Robotics Research, 2016. (In Press)
 * Blanco, J.L. and Gonzalez, J. and Fernandez-Madrigal, J.A. **Sparser Relative Bundle Adjustment (SRBA): constant-time maintenance and local optimization of arbitrarily large maps**, IEEE International Conference of Robotics and Automation (ICRA), 2013. ([PDF](http://ingmec.ual.es/~jlblanco/papers/blanco2013rba.pdf)), ICRA slides ([PDF](http://ingmec.ual.es/~jlblanco/papers/blanco2013rba_ICRA_slides.pdf)), [BibTeX](http://ingmec.ual.es/aigaion2/index.php/export/publication/233/bibtex)
+* Blanco, J.L. **User guide for libsrba: A generic C++ framework for Relative Bundle Adjustment (RBA)** ([PDF](http://mrpt.github.io/srba/srba-guide.pdf))
 
 # 1. Compile
 
@@ -13,7 +14,7 @@ Requisites:
 * gcc or clang (any version supported by Eigen 3) or MS Visual C++ 2008 or newer.
 * CMake >=2.8
 
-In Ubuntu, install requisites with:  
+In Ubuntu, install requisites with:
 ```
 sudo apt-get install build-essential cmake libmrpt-dev
 ```
@@ -41,9 +42,8 @@ The framework of Relative Bundle Adjustment (RBA) was introduced in a series of
 
 # 3. Programming guide and documentation
 
-* The official [user guide](http://reference.mrpt.org/devel/srba-guide.pdf)
-* Doxygen C++ [API reference](http://mrpt.github.io/srba/)
-* `srba-slam` [command-line reference](http://www.mrpt.org/Application%3Asrba-slam)
+* The official [user guide](http://mrpt.github.io/srba/srba-guide.pdf)
+* Doxygen C++ [API reference](http://mrpt.github.io/srba/), including explained examples.
 
 # 4. Run sample datasets
 

diff --git a/docs/Doxyfile b/docs/Doxyfile
@@ -699,7 +699,7 @@ WARNINGS               = YES
 # will automatically be disabled.
 # The default value is: YES.
 
-WARN_IF_UNDOCUMENTED   = YES
+WARN_IF_UNDOCUMENTED   = NO
 
 # If the WARN_IF_DOC_ERROR tag is set to YES, doxygen will generate warnings for
 # potential errors in the documentation, such as not documenting some parameters
@@ -743,7 +743,7 @@ WARN_LOGFILE           =
 # spaces.
 # Note: If this tag is empty the current directory is searched.
 
-INPUT                  = "../include/" "mainpage_dox.h"
+INPUT                  = "../include/" "." "../examples/cpp/"
 
 # This tag can be used to specify the character encoding of the source files
 # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses
@@ -811,7 +811,7 @@ EXCLUDE_SYMBOLS        =
 # that contain example code fragments that are included (see the \include
 # command).
 
-EXAMPLE_PATH           =
+EXAMPLE_PATH           = ../examples/
 
 # If the value of the EXAMPLE_PATH tag contains directories, you can use the
 # EXAMPLE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp and
@@ -825,7 +825,7 @@ EXAMPLE_PATTERNS       =
 # irrespective of the value of the RECURSIVE tag.
 # The default value is: NO.
 
-EXAMPLE_RECURSIVE      = NO
+EXAMPLE_RECURSIVE      = YES
 
 # The IMAGE_PATH tag can be used to specify one or more files or directories
 # that contain images that are to be included in the documentation (see the
@@ -892,7 +892,7 @@ USE_MDFILE_AS_MAINPAGE =
 # also VERBATIM_HEADERS is set to NO.
 # The default value is: NO.
 
-SOURCE_BROWSER         = NO
+SOURCE_BROWSER         = YES
 
 # Setting the INLINE_SOURCES tag to YES will include the body of functions,
 # classes and enums directly into the documentation.
@@ -1045,7 +1045,7 @@ HTML_HEADER            =
 # that doxygen normally uses.
 # This tag requires that the tag GENERATE_HTML is set to YES.
 
-HTML_FOOTER            =
+HTML_FOOTER            = dox_footer.html
 
 # The HTML_STYLESHEET tag can be used to specify a user-defined cascading style
 # sheet that is used by each HTML page. It can be used to fine-tune the look of

diff --git a/docs/dox_footer.html b/docs/dox_footer.html
@@ -0,0 +1,38 @@
+<!-- HTML footer for doxygen 1.8.6-->
+<!-- start footer part -->
+<!--BEGIN GENERATE_TREEVIEW-->
+<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
+  <ul>
+    $navpath
+    <li class="footer">$generatedby
+    <a href="http://www.doxygen.org/index.html">
+    <img class="footer" src="$relpath^doxygen.png" alt="doxygen"/></a> $doxygenversion </li>
+  </ul>
+</div>
+<!--END GENERATE_TREEVIEW-->
+<!--BEGIN !GENERATE_TREEVIEW-->
+<hr class="footer"/><address class="footer"><small>
+$generatedby &#160;<a href="http://www.doxygen.org/index.html">
+<img class="footer" src="$relpath^doxygen.png" alt="doxygen"/>
+</a> $doxygenversion
+</small></address>
+<!--END !GENERATE_TREEVIEW-->
+
+<script type="text/javascript">
+var sc_project=10707328; 
+var sc_invisible=1; 
+var sc_security="34dd40cf"; 
+var scJsHost = (("https:" == document.location.protocol) ?
+"https://secure." : "http://www.");
+document.write("<sc"+"ript type='text/javascript' src='" +
+scJsHost+
+"statcounter.com/counter/counter.js'></"+"script>");
+</script>
+<noscript><div class="statcounter"><a title="web statistics"
+href="http://statcounter.com/" target="_blank"><img
+class="statcounter"
+src="http://c.statcounter.com/10707328/0/34dd40cf/1/"
+alt="web statistics"></a></div></noscript>
+
+</body>
+</html>
diff --git a/docs/mainpage_dox.h b/docs/mainpage_dox.h
@@ -1,22 +1,65 @@
 /** \mainpage SRBA
 
-# Description
+\section description 1. Description
 
 Sparser Relative Bundle Adjustment (SRBA): a C++ framework for relative SLAM: 
 
-See https://github.com/MRPT/srba for papers and further theoretical information.
+See https://github.com/MRPT/srba and "<i>The SRBA guide</i>" (<a href="srba-guide.pdf" >PDF</a>) for references and further theoretical and coding information.
 
-# API reference
+\section api_ref 2. API reference
 
 The main classes are:
 
 - srba::RbaEngine
 
-C++ Examples: 
+\section cpp_ex 3. C++ Examples
 
-- See demos under https://github.com/MRPT/srba/tree/master/examples/cpp
+All demos can be found under the directory `examples/cpp`. Compile them by enabling the CMake flag `BUILD_EXAMPLES`.
+
+- Range-Bearing 2D SLAM: cpp/tutorial-srba-range-bearing-se2.cpp
+- Range-Bearing 3D SLAM: cpp/tutorial-srba-range-bearing-se3.cpp
+- Cartesian sensor 2D SLAM: cpp/tutorial-srba-cartesian2d-se2.cpp
+- Cartesian sensor 3D SLAM: cpp/tutorial-srba-cartesian2d-se2.cpp
+- Relative graph-SLAM 2D: cpp/tutorial-srba-relative-graph-slam-se2.cpp
+- Relative graph-SLAM 3D: cpp/tutorial-srba-relative-graph-slam-se3.cpp
+- Stereo visual SLAM 2D: cpp/tutorial-srba-stereo-se2.cpp
+- Stereo visual SLAM 3D: cpp/tutorial-srba-stereo-se3.cpp
+- How to recover the global map: cpp/tutorial-srba-how-to-recover-global-map.cpp
+
+\section ex1 4. Example SLAM code explained
+
+- See full source code in: cpp/tutorial-srba-range-bearing-se2.cpp
+
+First, include SRBA headers and declare the intention to use symbols under namespace `srba`:
+
+\snippet cpp/tutorial-srba-range-bearing-se2.cpp includes_namespaces
+
+Now, configure your SLAM problem by defining all the required template arguments:
+
+\snippet cpp/tutorial-srba-range-bearing-se2.cpp srba_typedef
+
+Next, declare the SRBA object instance and set up the main algorithm parameters:
+
+\snippet cpp/tutorial-srba-range-bearing-se2.cpp srba_setup
+
+Once you want to create a new Keyframe, first create the corresponding sensory observations:
+
+\snippet cpp/tutorial-srba-range-bearing-se2.cpp srba_fill_observation
+
+then call srba::RbaEngine::define_new_keyframe() to create the new KeyFrame and optimize the local area:
+
+\snippet cpp/tutorial-srba-range-bearing-se2.cpp srba_define_kf0
+
+Repeat the last two steps (create observations, define keyframes) for each new Keyframe. 
+
+At any moment you can create a 3D view of the SLAM state: 
+
+\snippet cpp/tutorial-srba-range-bearing-se2.cpp srba_3dview
+
+or save the graph in Graphviz DOT format for debugging: 
+
+\snippet cpp/tutorial-srba-range-bearing-se2.cpp srba_save_dot
 
- 
 */
 
 

diff --git a/examples/cpp/tutorial-srba-range-bearing-se2.cpp b/examples/cpp/tutorial-srba-range-bearing-se2.cpp
@@ -7,16 +7,18 @@
    | Released under BSD License. See details in http://www.mrpt.org/License    |
    +---------------------------------------------------------------------------+ */
 
+//! [includes_namespaces]
 #include <srba.h>
 #include <mrpt/gui.h>  // For rendering results as a 3D scene
 #include <mrpt/random.h>
 
 using namespace srba;
 using namespace mrpt::random;
 using namespace std;
+//! [includes_namespaces]
 
 
-
+//! [srba_typedef]
 struct RBA_OPTIONS : public RBA_OPTIONS_DEFAULT
 {
 //	typedef ecps::local_areas_fixed_size            edge_creation_policy_t;  //!< One of the most important choices: how to construct the relative coordinates graph problem
@@ -31,6 +33,7 @@ typedef RbaEngine<
 	observations::RangeBearing_2D, // Type of observations
 	RBA_OPTIONS
 	>  my_srba_t;
+//! [srba_typedef]
 
 // --------------------------------------------------------------------------------
 // A test dataset. Generated with https://github.com/jlblancoc/recursive-world-toolkit 
@@ -77,6 +80,7 @@ basic_range_bearing_dataset_entry_t  observations_10[] = {
 
 int main(int argc, char**argv)
 {
+//! [srba_setup]
 	my_srba_t rba;     //  Create an empty RBA problem
 
 	// --------------------------------------------------------------------------------
@@ -89,9 +93,10 @@ int main(int argc, char**argv)
 	rba.parameters.obs_noise.std_noise_observations = 0.05; //SENSOR_NOISE_STD;
 
 	// =========== Topology parameters ===========
-	rba.parameters.srba.max_tree_depth       = 3;
+	rba.parameters.srba.max_tree_depth       =
 	rba.parameters.srba.max_optimize_depth   = 3;
 	// ===========================================
+//! [srba_setup]
 
 	// Set sensors parameters:
 	// rba.sensor_params has no parameters for the "Cartesian" sensor.
@@ -106,6 +111,7 @@ int main(int argc, char**argv)
 	//cout << "RBA parameters:\n-----------------\n";
 	//rba.parameters.dumpToConsole();
 
+//! [srba_fill_observation]
 	// --------------------------------------------------------------------------------
 	// Define observations of KF #0:
 	// --------------------------------------------------------------------------------
@@ -122,8 +128,10 @@ int main(int argc, char**argv)
 		obs_field.obs.obs_data.yaw = observations_0[i].yaw + randomGenerator.drawGaussian1D(0,SENSOR_NOISE_STD);
 		list_obs.push_back( obs_field );
 	}
+//! [srba_fill_observation]
 
 
+//! [srba_define_kf0]
 	//  Here happens the main stuff: create Key-frames, build structures, run optimization, etc.
 	//  ============================================================================================
 	my_srba_t::TNewKeyFrameInfo new_kf_info;
@@ -137,6 +145,7 @@ int main(int argc, char**argv)
 		<< " | # kf-to-kf edges created:" <<  new_kf_info.created_edge_ids.size()  << endl
 		<< "Optimization error: " << new_kf_info.optimize_results.total_sqr_error_init << " -> " << new_kf_info.optimize_results.total_sqr_error_final << endl
 		<< "-------------------------------------------------------" << endl;
+//! [srba_define_kf0]
 
 
 	// --------------------------------------------------------------------------------
@@ -174,14 +183,17 @@ int main(int argc, char**argv)
 	cout << "Ground truth: relative pose of KF#1 wrt KF#0: \n" << mrpt::poses::CPose3D(GT_pose10-GT_pose0) << endl;
 
 
+//! [srba_save_dot]
 	// --------------------------------------------------------------------------------
 	// Saving RBA graph as a DOT file:
 	// --------------------------------------------------------------------------------
 	const string sFil = "graph.dot";
 	cout << "Saving final graph of KFs and LMs to: " << sFil << endl;
 	rba.save_graph_as_dot(sFil, true /* LMs=save */);
 	cout << "Done.\n";
+//! [srba_save_dot]
 
+//! [srba_3dview]
 	// --------------------------------------------------------------------------------
 	// Show 3D view of the resulting map:
 	// --------------------------------------------------------------------------------
@@ -208,6 +220,7 @@ int main(int argc, char**argv)
 	cout << "Press any key or close window to exit.\n";
 	win.waitForKey();
 #endif
+//! [srba_3dview]
 
 	return 0; // All ok
 }

diff --git a/include/srba/RbaEngine.h b/include/srba/RbaEngine.h
@@ -56,7 +56,7 @@ namespace srba
 	  *		- Optional sensor parameters (e.g. camera calibration)
 	  *		- Optionally, the relative positions of a subset of landmarks wrt to their base frame (these are the "fixed" or "known" landmarks).
 	  *
-	  *  See http://www.mrpt.org/srba and the `srba-guide.pdf` therein for a list of possible template arguments, code examples, etc.
+	  *  See http://mrpt.github.io/srba/ and <a href="http://mrpt.github.io/srba/srba-guide.pdf" >`srba-guide`</a> therein for a list of possible template arguments, code examples, etc.
 	  *
 	  * \tparam KF2KF_POSE_TYPE The parameterization of keyframe-to-keyframe relative poses (edges, problem unknowns).
 	  * \tparam LM_TYPE The parameterization of relative positions of landmarks relative poses (edges).
@@ -660,35 +660,34 @@ namespace srba
 		};
 
 
-		/** ====================================================================
-		                         j,i                    lm_id,base_id
-		             \partial  h            \partial  h
-		                         l                      obs_frame_id
-		   dh_dp = ------------------ = ---------------------------------
-		                         d+1                    cur_id
-		             \partial  p            \partial  p
-		                         d                      stp.next_node
-
-		    See tech report:
-		     "A tutorial on SE(3) transformation parameterizations and
-		      on-manifold optimization", Jose-Luis Blanco, 2010.
-		   ==================================================================== */
+		/** \verbatim
+		  *                      j,i                    lm_id,base_id
+		  *          \partial  h            \partial  h
+		  *                      l                      obs_frame_id
+		  * dh_dp = ------------------ = ---------------------------------
+		  *                      d+1                    cur_id
+		  *          \partial  p            \partial  p
+		  *                      d                      stp.next_node
+		  * \endverbatim
+		  * See tech report:
+		  *  "A tutorial on SE(3) transformation parameterizations and on-manifold optimization", Jose-Luis Blanco, 2010
+		  */
 		void compute_jacobian_dh_dp(
 			typename TSparseBlocksJacobians_dh_dAp::TEntry  &jacob,
 			const k2f_edge_t & observation,
 			const k2k_edges_deque_t  &k2k_edges,
 			std::vector<const pose_flag_t*>    *out_list_of_required_num_poses) const;
 
-		/** ====================================================================
-		                         j,i                    lm_id,base_id
-		             \partial  h            \partial  h
-		                         l                      obs_frame_id
-		   dh_df = ------------------ = ---------------------------------
-
-		             \partial  f            \partial  f
-
-		     Note: f=relative position of landmark with respect to its base kf
-		   ==================================================================== */
+		/** \verbatim
+		 *                       j,i                    lm_id,base_id
+		 *           \partial  h            \partial  h
+		 *                       l                      obs_frame_id
+		 * dh_df = ------------------ = ---------------------------------
+		 *
+		 *            \partial  f            \partial  f
+		 * \endverbatim
+		 * Note: f=relative position of landmark with respect to its base kf
+		 */
 		void compute_jacobian_dh_df(
 			typename TSparseBlocksJacobians_dh_df::TEntry  &jacob,
 			const k2f_edge_t & observation,

diff --git a/include/srba/srba_edge_creation_policies.h b/include/srba/srba_edge_creation_policies.h
@@ -9,8 +9,7 @@
 
 #pragma once
 
-/** \defgroup mrpt_srba_ecps Edge creation policies
-	* \ingroup mrpt_srba_ecps */
+/** \defgroup mrpt_srba_ecps Edge creation policies */
 
 #include "ecps/local_areas_fixed_size.h"
 #include "ecps/classic_linear_rba.h"