
## Embedding CSM in your programs ##

### Linking to CSM ###

When CSM is installed, a [pkgconfig] ``csm.pc`` file is installed as well.
This makes it easy to link to CSM. 

[pkgconfig]: http://pkg-config.freedesktop.org/wiki/

For example, on my system, after installing CSM, I can run ``pkgconfig`` to
get the C preprocessors and linker flags.

This is what I get on my system (on yours, paths will be different, of course).

     $ pkg-config --cflags csm  
       -I/sw/include -I/Users/andrea/svn/cds/csm/deploy/include/cairo
       -I/Users/andrea/svn/cds/csm/deploy/include

     $ pkg-config --libs csm 
       -L/sw/lib -L/Users/andrea/svn/cds/csm/deploy/lib 
       -lcsm-static -lgsl -lgslcblas -lm

If you use GNU Make, a basic Makefile for your program linking to CSM
would be something like:

	CSM_FLAGS=`pkg-config --libs --cflags csm`

	myprogram: myprogram.c
		gcc $(CSM_FLAGS) -o myprogram myprogram.c

You can download the sources for this example in the repository (directory `docs/example-linking-make`).

If you use [CMake] --- and you should! --- it is reccomended that 
you use something like the following in your ``CMakeLists.txt``.

	cmake_minimum_required(VERSION 2.4)
	project(myproject)

	# Require we have pkgconfig installed
	find_package(PkgConfig REQUIRED)
	# Tell pkgconfig to look for CSM
	pkg_check_modules(CSM REQUIRED csm)

	IF(${CSM_FOUND})
		MESSAGE("CSM_LIBRARY_DIRS: ${CSM_LIBRARY_DIRS}")
		MESSAGE("CSM_LIBRARIES: ${CSM_LIBRARIES}")
		MESSAGE("CSM_INCLUDE_DIRS: ${CSM_INCLUDE_DIRS}")

		INCLUDE_DIRECTORIES(${CSM_INCLUDE_DIRS}) # important! 
		LINK_DIRECTORIES(${CSM_LIBRARY_DIRS})    # important! 
	ELSE(${CSM_FOUND})	
		MESSAGE(FATAL_ERROR "CSM not found. Check that the environment \
		variable PKG_CONFIG_PATH includes the path containing the file 'csm.pc'.")
	ENDIF(${CSM_FOUND})		

	add_executable(myprogram myprogram.c)

	target_link_libraries(myprogram ${CSM_LIBRARIES}) # important! 

You can download the sources for this example in the repository (directory `docs/example-linking-cmake`).

[CMake]: http://www.cmake.org/


### Accessing CSM functions from your applications ###

All functions that you would be interested in using are accessible by including one header:

	#include <csm/csm_all.h>

If you are linking from C++, as opposed to C, all functions are enclosed
in the `CSM` namespace. Therefore, you need something like the following.

	#include <csm/csm_all.h>
	using namespace CSM;


### Orienting oneself in the source code ###

The main function to call is the following:

	void sm_icp(struct sm_params*params, struct sm_result*result);

This implements matching between two laser scans.
All the applications discussed above (``sm1``, ``sm2``, etc.) are essentially
wrapper of ``sm_icp``: they fill in the ``params`` structure, and read from the ``result`` structure.

The ``sm_params`` structure is described in the ``<csm/algos.h>`` header file.
It contains parameters for both ICP and other algorithms (like HSM; however, only (PL)ICP is considered stable in CSM)

Note that many of the parameters greatly influence the behavior of PLICP, so it
is worth reading them all. If you run ``sm2 -help`` you will see the default
values, which are reasonable as a starting point.

We now briefly discuss the main parameters.
	
* ``params->laser_ref``:  pointer of a structure of type ``laser_data`` (described before in this document) representing
   the "ref"erence scan (first scan).
* ``params->laser_sens``:  pointer of a structure of type ``laser_data`` representing
   the second scan.
* ``params->first_guess``: first guess (x,y,theta).
* ``use_point_to_line_distance``: 1 for PLICP, 0 for ICP.
* ``use_corr_tricks``: use the tricks described in the PLICP paper.

Parameters that influence stopping and restarting:

* ``max_iterations``: maximum number of iterations
* ``epsilon_xy``, ``epsilon_theta``: stop if change below these thresholds
* ``restart*``: whether to add some noise and restart if the match
  is not satisfactory. Useful for getting out of local minima but
  expensive.

Parameters that influence correspondence establishment:

* ``max_angular_correction_deg``, ``max_linear_correction``.
* ``max_correspondence_dist``

Parameters that influence correspondence pruning:

* ``outliers_maxPerc``
* ``outliers_adaptive_*``
* ``outliers_remove_doubles``

See the file ``<csm/algos.h>`` for a description of the above parameters,
and the other minor parameters.







