= Using RT-SLAM =

== Configuration ==

There are no configuration files yet. All the constant variables in capital letters defined at the beginning of the file $JAFAR_DIR/modules/rtslam/demo_suite/demo_slam.cpp are open to tuning. Some important ones are described with more details below.

=== Camera calibration ===

You have to modify the following lines in order to setup the camera calibration: {{{#!highlight cpp
const unsigned IMG_WIDTH = 640;
const unsigned IMG_HEIGHT = 480;
const double INTRINSIC[4] = { 306.2969,   264.7741,   499.9177,   494.4829 };
const double DISTORTION[3] = { -0.2293129, 0.08793152, -0.01349877 };
}}}


== Running the demo ==

{{{#!highlight sh
cd $JAFAR_DIR/build/modules/rtslam
demo_suite/<platform>/demo_slam <options>
}}}

Control options:
 * '''--disp-2d'''=0/1 use 2D display
 * '''--disp-3d'''=0/1 use 3D display
 * '''--render-all'''=0/1 (needs --replay 1)
 * '''--data-path'''=/mnt/ram/rtslam
 * '''--replay'''=0/1 (needs --data-path and having dumped here an online demo first)
 * '''--dump'''=0/1 dump the images (--replay=0) or the rendered views (--replay=1) (needs --data-path). If --replay=0, --data-path should be in a ram disk.
 * '''--log'''=0/1 log result in text file
 * '''--rand-seed'''=0/1/n. 0=generate new one, 1=in replay use the saved one, n=use seed n
 * '''--pause'''=0/n. 0=don't, n=pause for frames>n (needs --replay 1)
 * '''--verbose'''=0/1/2/3/4/5. Off/Trace/Warning/Debug/VerboseDebug/VeryVerboseDebug (if compiled in debug only)
 * '''--help'''
 * '''--usage'''

Slam options:
 * '''--robot''' 0=constant vel, 1=inertial
 * '''--trigger''' 0=internal, 1=external with MTI control, 2=external without control
 * '''--simu''' 0/1
 * '''--freq''' camera frequency in double Hz (with trigger==0/1)
 * '''--shutter''' shutter time in double seconds (with trigger==1)

== Controlling the demo ==

When doing a replay, you can control how slam is running by interacting with the 2D viewer:
 * '''Press "[space]"''' to switch between play and pause mode.
 * '''Press "N"''' to process one image when in pause mode.
 * '''Press "F"''' to switch between render-all mode and fast mode.
 * '''Press "Q"''' to quit.
 * '''Click on an observation''' to get textual and visual information about the observation and associated landmark.
 * '''Click on an empty part of the image''' to get information about the sensor and the associated robot.

== Interpreting the demo ==

Color code:
 * '''magenta:''' !InitialParametrization landmarks that were observed this frame
 * '''dark red:''' !InitialParametrization landmarks that were not observed this frame
 * '''cyan:''' !ConvergedParametrization landmarks that were observed this frame
 * '''dark blue:''' !ConvergedParametrization landmarks that were not observed this frame

2D landmark representation:
 * '''a colored + cross:''' the predicted position of the landmark
 * '''a colored ellipse:''' the 3-sigma prediction uncertainty
 * '''an orange x cross:''' the measured position of the landmark
 * '''a colored label:''' the id of the landmark, followed by the matching score (/100)

Reasons for a landmark not being observed:
 * outside of the sensor frame (you can still see them in the 3D view)
 * matching failed (you can see the matching score that is below the threshold)
 * the observation was inconsistent (the measure is out of the uncertainty ellipse)
 * too many landmarks are in the sensor frame and we didn't try to observe some of them (no matching score is present)