Skip to content

Commit

Permalink
documentation improvments
Browse files Browse the repository at this point in the history
  • Loading branch information
@goldbattle
goldbattle committed May 9, 2023
1 parent 9d499db commit a824660
Show file tree
Hide file tree
Showing 10 changed files with 354 additions and 19 deletions.
11 changes: 6 additions & 5 deletions docs/dev-docs.dox
View file
Original file line number Diff line number Diff line change
Expand Up @@ -53,22 +53,23 @@
2. You will need to install python3.6
- `sudo add-apt-repository ppa:deadsnakes/ppa`
- `sudo apt-get update`
- `sudo apt-get install python3.6`
- `curl https://bootstrap.pypa.io/get-pip.py | sudo python3.6`
- `sudo apt-get install python3.6 python3.6-distutils`
- `curl https://bootstrap.pypa.io/pip/3.6/get-pip.py | sudo python3.6`
- `sudo -H pip3.6 install jinja2 Pygments`
- `sudo apt install texlive-base texlive-latex-extra texlive-fonts-extra texlive-fonts-recommended`
3. To use the bibtex citing you need to have
- bibtex executable in search path
- perl executable in search path
- `bibtex` and `perl` executable in search path
- These should be installed through the texlive installation
- http://www.doxygen.nl/manual/commands.html#cmdcite
4. Go into the documentation folder and build
- `cd m.css/documentation/`
- `python3.6 doxygen.py <path_to_Doxyfile-mcss>`
- `python3.6 doxygen.py ~/catkin_ws/src/open_vins/Doxyfile-mcss`
5. If you run into errors, ensure your python path is set to use the 3.6 libraries
- ` export PYTHONPATH=/usr/local/lib/python3.6/dist-packages/`
6. You might need to comment out the `enable_async=True` flag in the doxygen.py file
7. This should then build the documentation website
8. Open the html page `/open_vins/doxgen_generated/html/index.html` to view documentation
8. Open the html page `~/catkin_ws/src/open_vins/doxgen_generated/html/index.html` to view documentation


@section developers-theme Custom m.css Theme
Expand Down
6 changes: 4 additions & 2 deletions docs/dev-index.dox
View file
Original file line number Diff line number Diff line change
Expand Up @@ -36,14 +36,16 @@ The error state needs to be a vector and thus a type will need to define the map

To show the power of this type-based indexing system, we will go through how we compute the EKF update.
The specific method we will be looking at is the @ref ov_msckf::StateHelper::EKFUpdate() which takes in the state, vector of types, Jacobian, residual, and measurement covariance.
As compared to passing a Jacobian matrix that is the full size of state wide, we instead leverage this type system by passing a "small" Jacobian that has only the state elements that the measurements are a function of.
As compared to passing a "big" Jacobian matrix that is the full size of state wide, we instead leverage this type system by passing a "small" Jacobian that has only the state elements that the measurements are a function of.

@image html hxorder.png width=40%


For example, if we have a global 3D SLAM feature update (implemented in @ref ov_msckf::UpdaterSLAM) our Jacobian will only be a function of the newest clone and the feature.
This means that our Jacobian is only of size 9 as compared to the size our state.
In addition to the matrix containing the Jacobian elements, we need to know what order this Jacobian is in, thus we pass a vector of types which correspond to the state elements our Jacobian is a function of.
Thus in our example, it would contain two types: our newest clone @ref ov_type::PoseJPL and current landmark feature @ref ov_type::Landmark with our Jacobian being the type size of the pose plus the type size of the landmark in width.

In the above figure the orientation and position would correspond to the x1 and x2 states, while the feature is the x5 state.



Expand Down
11 changes: 9 additions & 2 deletions docs/dev-ros1-to-ros2.dox
View file
Original file line number Diff line number Diff line change
Expand Up @@ -13,11 +13,17 @@ This is what was used to generate the converted ROS2 bag files for standard data
To do a conversion of a bag file we can do the following:

@code{.shell-session}
pip install rosbags
rosbags-convert V1_01_easy.bag
pip3 install rosbags>=0.9.11
rosbags-convert V1_01_easy.bag --dst <ros2_bag_folder>
@endcode

If you need to create a bag from images, then we recommend using the [Kalibr bagcreater](https://github.com/ethz-asl/kalibr/wiki/bag-format#bagcreater) utility.
To convert a ROS2 bag recorded to a ROS1 bag one which can then be processed by Kalibr or a ROS1 codebase, the following can be run:

@code{.shell-session}
pip3 install rosbags>=0.9.12
rosbags-convert <ros2_bag_folder> --dst calib_01.bag --exclude-topic <non_img_and_imu_topics>
@endcode


@section dev-ros1-to-ros2-option-2 rosbag2 play
Expand All @@ -42,6 +48,7 @@ source_ros2
ros2 bag play -s rosbag_v2 V1_01_easy.bag
@endcode

We don't recommend this method and instead suggest using the [rosbags](https://gitlab.com/ternaris/rosbags) utility as standalone.



Expand Down
318 changes: 318 additions & 0 deletions docs/img/hxorder.ipe
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,318 @@
<?xml version="1.0"?>
<!DOCTYPE ipe SYSTEM "ipe.dtd">
<ipe version="70206" creator="Ipe 7.2.7">
<info created="D:20230509184157" modified="D:20230509184725"/>
<ipestyle name="basic">
<symbol name="arrow/arc(spx)">
<path stroke="sym-stroke" fill="sym-stroke" pen="sym-pen">
0 0 m
-1 0.333 l
-1 -0.333 l
h
</path>
</symbol>
<symbol name="arrow/farc(spx)">
<path stroke="sym-stroke" fill="white" pen="sym-pen">
0 0 m
-1 0.333 l
-1 -0.333 l
h
</path>
</symbol>
<symbol name="arrow/ptarc(spx)">
<path stroke="sym-stroke" fill="sym-stroke" pen="sym-pen">
0 0 m
-1 0.333 l
-0.8 0 l
-1 -0.333 l
h
</path>
</symbol>
<symbol name="arrow/fptarc(spx)">
<path stroke="sym-stroke" fill="white" pen="sym-pen">
0 0 m
-1 0.333 l
-0.8 0 l
-1 -0.333 l
h
</path>
</symbol>
<symbol name="mark/circle(sx)" transformations="translations">
<path fill="sym-stroke">
0.6 0 0 0.6 0 0 e
0.4 0 0 0.4 0 0 e
</path>
</symbol>
<symbol name="mark/disk(sx)" transformations="translations">
<path fill="sym-stroke">
0.6 0 0 0.6 0 0 e
</path>
</symbol>
<symbol name="mark/fdisk(sfx)" transformations="translations">
<group>
<path fill="sym-fill">
0.5 0 0 0.5 0 0 e
</path>
<path fill="sym-stroke" fillrule="eofill">
0.6 0 0 0.6 0 0 e
0.4 0 0 0.4 0 0 e
</path>
</group>
</symbol>
<symbol name="mark/box(sx)" transformations="translations">
<path fill="sym-stroke" fillrule="eofill">
-0.6 -0.6 m
0.6 -0.6 l
0.6 0.6 l
-0.6 0.6 l
h
-0.4 -0.4 m
0.4 -0.4 l
0.4 0.4 l
-0.4 0.4 l
h
</path>
</symbol>
<symbol name="mark/square(sx)" transformations="translations">
<path fill="sym-stroke">
-0.6 -0.6 m
0.6 -0.6 l
0.6 0.6 l
-0.6 0.6 l
h
</path>
</symbol>
<symbol name="mark/fsquare(sfx)" transformations="translations">
<group>
<path fill="sym-fill">
-0.5 -0.5 m
0.5 -0.5 l
0.5 0.5 l
-0.5 0.5 l
h
</path>
<path fill="sym-stroke" fillrule="eofill">
-0.6 -0.6 m
0.6 -0.6 l
0.6 0.6 l
-0.6 0.6 l
h
-0.4 -0.4 m
0.4 -0.4 l
0.4 0.4 l
-0.4 0.4 l
h
</path>
</group>
</symbol>
<symbol name="mark/cross(sx)" transformations="translations">
<group>
<path fill="sym-stroke">
-0.43 -0.57 m
0.57 0.43 l
0.43 0.57 l
-0.57 -0.43 l
h
</path>
<path fill="sym-stroke">
-0.43 0.57 m
0.57 -0.43 l
0.43 -0.57 l
-0.57 0.43 l
h
</path>
</group>
</symbol>
<symbol name="arrow/fnormal(spx)">
<path stroke="sym-stroke" fill="white" pen="sym-pen">
0 0 m
-1 0.333 l
-1 -0.333 l
h
</path>
</symbol>
<symbol name="arrow/pointed(spx)">
<path stroke="sym-stroke" fill="sym-stroke" pen="sym-pen">
0 0 m
-1 0.333 l
-0.8 0 l
-1 -0.333 l
h
</path>
</symbol>
<symbol name="arrow/fpointed(spx)">
<path stroke="sym-stroke" fill="white" pen="sym-pen">
0 0 m
-1 0.333 l
-0.8 0 l
-1 -0.333 l
h
</path>
</symbol>
<symbol name="arrow/linear(spx)">
<path stroke="sym-stroke" pen="sym-pen">
-1 0.333 m
0 0 l
-1 -0.333 l
</path>
</symbol>
<symbol name="arrow/fdouble(spx)">
<path stroke="sym-stroke" fill="white" pen="sym-pen">
0 0 m
-1 0.333 l
-1 -0.333 l
h
-1 0 m
-2 0.333 l
-2 -0.333 l
h
</path>
</symbol>
<symbol name="arrow/double(spx)">
<path stroke="sym-stroke" fill="sym-stroke" pen="sym-pen">
0 0 m
-1 0.333 l
-1 -0.333 l
h
-1 0 m
-2 0.333 l
-2 -0.333 l
h
</path>
</symbol>
<pen name="heavier" value="0.8"/>
<pen name="fat" value="1.2"/>
<pen name="ultrafat" value="2"/>
<symbolsize name="large" value="5"/>
<symbolsize name="small" value="2"/>
<symbolsize name="tiny" value="1.1"/>
<arrowsize name="large" value="10"/>
<arrowsize name="small" value="5"/>
<arrowsize name="tiny" value="3"/>
<color name="red" value="1 0 0"/>
<color name="green" value="0 1 0"/>
<color name="blue" value="0 0 1"/>
<color name="yellow" value="1 1 0"/>
<color name="orange" value="1 0.647 0"/>
<color name="gold" value="1 0.843 0"/>
<color name="purple" value="0.627 0.125 0.941"/>
<color name="gray" value="0.745"/>
<color name="brown" value="0.647 0.165 0.165"/>
<color name="navy" value="0 0 0.502"/>
<color name="pink" value="1 0.753 0.796"/>
<color name="seagreen" value="0.18 0.545 0.341"/>
<color name="turquoise" value="0.251 0.878 0.816"/>
<color name="violet" value="0.933 0.51 0.933"/>
<color name="darkblue" value="0 0 0.545"/>
<color name="darkcyan" value="0 0.545 0.545"/>
<color name="darkgray" value="0.663"/>
<color name="darkgreen" value="0 0.392 0"/>
<color name="darkmagenta" value="0.545 0 0.545"/>
<color name="darkorange" value="1 0.549 0"/>
<color name="darkred" value="0.545 0 0"/>
<color name="lightblue" value="0.678 0.847 0.902"/>
<color name="lightcyan" value="0.878 1 1"/>
<color name="lightgray" value="0.827"/>
<color name="lightgreen" value="0.565 0.933 0.565"/>
<color name="lightyellow" value="1 1 0.878"/>
<dashstyle name="dashed" value="[4] 0"/>
<dashstyle name="dotted" value="[1 3] 0"/>
<dashstyle name="dash dotted" value="[4 2 1 2] 0"/>
<dashstyle name="dash dot dotted" value="[4 2 1 2 1 2] 0"/>
<textsize name="large" value="\large"/>
<textsize name="Large" value="\Large"/>
<textsize name="LARGE" value="\LARGE"/>
<textsize name="huge" value="\huge"/>
<textsize name="Huge" value="\Huge"/>
<textsize name="small" value="\small"/>
<textsize name="footnote" value="\footnotesize"/>
<textsize name="tiny" value="\tiny"/>
<textstyle name="center" begin="\begin{center}" end="\end{center}"/>
<textstyle name="itemize" begin="\begin{itemize}" end="\end{itemize}"/>
<textstyle name="item" begin="\begin{itemize}\item{}" end="\end{itemize}"/>
<gridsize name="4 pts" value="4"/>
<gridsize name="8 pts (~3 mm)" value="8"/>
<gridsize name="16 pts (~6 mm)" value="16"/>
<gridsize name="32 pts (~12 mm)" value="32"/>
<gridsize name="10 pts (~3.5 mm)" value="10"/>
<gridsize name="20 pts (~7 mm)" value="20"/>
<gridsize name="14 pts (~5 mm)" value="14"/>
<gridsize name="28 pts (~10 mm)" value="28"/>
<gridsize name="56 pts (~20 mm)" value="56"/>
<anglesize name="90 deg" value="90"/>
<anglesize name="60 deg" value="60"/>
<anglesize name="45 deg" value="45"/>
<anglesize name="30 deg" value="30"/>
<anglesize name="22.5 deg" value="22.5"/>
<opacity name="10%" value="0.1"/>
<opacity name="30%" value="0.3"/>
<opacity name="50%" value="0.5"/>
<opacity name="75%" value="0.75"/>
<tiling name="falling" angle="-60" step="4" width="1"/>
<tiling name="rising" angle="30" step="4" width="1"/>
</ipestyle>
<page>
<layer name="alpha"/>
<view layers="alpha" active="alpha"/>
<path layer="alpha" matrix="0.425 0 0 0.416667 73.6 410.667" stroke="black" pen="ultrafat">
128 704 m
128 608 l
448 608 l
448 704 l
h
</path>
<path stroke="black">
160 704 m
160 664 l
</path>
<path stroke="black">
192 704 m
192 664 l
</path>
<path stroke="black">
224 704 m
224 664 l
</path>
<path stroke="black">
240 704 m
240 664 l
</path>
<text matrix="1 0 0 1 -7.28616 -83.0031" transformations="translations" pos="144 736" stroke="black" type="label" width="13.462" height="6.179" depth="2.15" valign="baseline" size="Large" style="math">x_1</text>
<text matrix="1 0 0 1 24.7138 -83.0031" transformations="translations" pos="144 736" stroke="black" type="label" width="13.462" height="6.179" depth="2.15" valign="baseline" size="Large" style="math">x_2
</text>
<text matrix="1 0 0 1 58.1415 -83.0031" transformations="translations" pos="144 736" stroke="black" type="label" width="13.462" height="6.179" depth="2.15" valign="baseline" size="Large" style="math">x_3</text>
<text matrix="1 0 0 1 81.4277 -83.0031" transformations="translations" pos="144 736" stroke="black" type="label" width="13.462" height="6.179" depth="2.15" valign="baseline" size="Large" style="math">x_4
</text>
<text matrix="1 0 0 1 101.502 -83.0031" transformations="translations" pos="144 736" stroke="black" type="label" width="13.462" height="6.179" depth="2.15" valign="baseline" size="Large" style="math">x_5</text>
<text matrix="1 0 0 1 -8.53538 -56.1785" transformations="translations" pos="144 736" stroke="black" type="label" width="18.099" height="9.845" depth="2.15" valign="baseline" size="Large" style="math">\mathbf{H}_1</text>
<text matrix="1 0 0 1 -56 -55.1077" transformations="translations" pos="144 736" stroke="black" type="label" width="25.935" height="9.842" depth="4.09" valign="baseline" size="Large" style="math">\mathbf{H}_{big}</text>
<text matrix="1 0 0 1 23.6431 -56" transformations="translations" pos="144 736" stroke="black" type="label" width="18.099" height="9.845" depth="2.15" valign="baseline" size="Large" style="math">\mathbf{H}_2</text>
<text matrix="1 0 0 1 99.36 -56" transformations="translations" pos="144 736" stroke="black" type="label" width="18.099" height="9.845" depth="2.15" valign="baseline" size="Large" style="math">\mathbf{H}_5</text>
<text matrix="1 0 0 1 60.2523 -55.8215" transformations="translations" pos="144 736" stroke="black" type="label" width="8.07" height="9.245" depth="0" valign="baseline" size="Large" style="math">\mathbf{0}</text>
<text matrix="1 0 0 1 84.1046 -56.1785" transformations="translations" pos="144 736" stroke="black" type="label" width="8.07" height="9.245" depth="0" valign="baseline" size="Large" style="math">\mathbf{0}</text>
<path matrix="0.275 0 0 0.416667 102.794 337.418" stroke="black" pen="ultrafat">
128 704 m
128 608 l
448 608 l
448 704 l
h
</path>
<path matrix="1 0 0 1 9.99378 -73.2492" stroke="black">
160 704 m
160 664 l
</path>
<path matrix="1 0 0 1 9.99378 -73.2492" stroke="black">
192 704 m
192 664 l
</path>
<text matrix="1 0 0 1 62.7815 -158.215" transformations="translations" pos="144 736" stroke="black" type="label" width="13.462" height="6.179" depth="2.15" valign="baseline" size="Large" style="math">x_5</text>
<text matrix="1 0 0 1 34.3507 -158.068" transformations="translations" pos="144 736" stroke="black" type="label" width="13.462" height="6.179" depth="2.15" valign="baseline" size="Large" style="math">x_2
</text>
<text matrix="1 0 0 1 3.77838 -158.215" transformations="translations" pos="144 736" stroke="black" type="label" width="13.462" height="6.179" depth="2.15" valign="baseline" size="Large" style="math">x_1</text>
<text matrix="1 0 0 1 -52.1046 -130.142" transformations="translations" pos="144 736" stroke="black" type="label" width="38.138" height="9.845" depth="2.15" valign="baseline" size="Large" style="math">\mathbf{H}_{small}</text>
<text matrix="1 0 0 1 20.5229 -171.865" transformations="translations" pos="144 736" stroke="black" type="label" width="39.065" height="6.918" depth="0" valign="baseline" style="math">\mathrm{Hx\_order}</text>
<text matrix="1 0 0 1 1.99378 -129.249" transformations="translations" pos="144 736" stroke="black" type="label" width="18.099" height="9.845" depth="2.15" valign="baseline" size="Large" style="math">\mathbf{H}_1</text>
<text matrix="1 0 0 1 33.9938 -129.249" transformations="translations" pos="144 736" stroke="black" type="label" width="18.099" height="9.845" depth="2.15" valign="baseline" size="Large" style="math">\mathbf{H}_2</text>
<text matrix="1 0 0 1 60.9969 -129.249" transformations="translations" pos="144 736" stroke="black" type="label" width="18.099" height="9.845" depth="2.15" valign="baseline" size="Large" style="math">\mathbf{H}_5</text>
</page>
</ipe>
Binary file added docs/img/hxorder.png
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading

0 comments on commit a824660

Please sign in to comment.