Commit 5ed66d00 authored by Sergi Hernandez's avatar Sergi Hernandez
Browse files

Added a dedicated documentation page for the dijkstra, gradient and g2_spline classes.

parent d45047be
Dijktra algorithm
=================
## Description
This library provide a C++ implementation of the [Dijkstra algorithm](https://en.wikipedia.org/wiki/Dijkstra%27s_algorithm) to find the lowest cost path between two points.
The function to compute the klowest cost path is called *find_shortest_path* and has the following prototype:
```
double find_shortest_path(Eigen::MatrixXd &graph,unsigned int start_node,unsigned int end_node,std::vector<unsigned int> &path)
```
where:
* **graph**: is a 2D square matrix which represents the general connectivity of the nodes. That is, each row represents the connectivity of the corresponding node with all other nodes. The nodes that are not connected must be represented by a 0 value in the corresponding row and column. Any other value represent the cost of the connection.
* **start_node**: the index of the starting node.
* **end_node**: the index of the target node.
* **path**: If a path is found, this vector has the sequence of nodes to reach the target node with lowest cost.
If a path to the target node is found, this function will return the total cost and also the sequence of nodes to reach it. If the path to the target node can not be found, this function returns the path to the last reachable node, and its cost.
## How to use it.
* Create an object of this class.
* Generate a 2D square matrix representing the connectivity and cost of the desired problem.
* Select a start and target nodes. With the current implementation, the start node msut always be the first one.
* Call the *find_shortest_path()* function to get the desired path, if it exists.
An example is provided for a simple case.
\ No newline at end of file
G2 Splines implementation
=========================
## Description
This library provides a C++ implementation of the G2 Splines (Quintic splines).These splines are 2D parametric cuves defined by independant x and y 5th order polynomials in therms of the parameter *u*, in the range [0,length]. The curve can be completelly defined by fixing the initial and final states as well as a set of internal parameters (n1,n2,n3,n4). The state of a G2 splines is defined as
* 2D position (x,y)
* Heading
* Curvature
In the code the information of the state of a spline is defined as the *TPoint* data structure.
In this implementation, the internal parameters are set such that the curve is symmetric (n1=n2 and n3=-n4). The remaining parameters ara adjusted when the curve is generated to maximize its smoothness.
These type of splines have several interesting properties that make them suitable to be used to describe possible paths of a car-like robot.
The main features of this library are:
* The start and ending states can be defined by the user (*set_start_point()* and *set_end_point()*) and modified at any time. When these states are set or modified, the spline has to be re-generated.
* To reduce the computational cost, the spline is only generated when necesary or when the *generate()* function is explicitly called. The resolution can be selected by the user.
* Provides functions to evaluate the spline (get the state information) at any a single point or at all points.
* It uses the [gradient library](docs/gradient.md) to compute the maximum curvature and maximum curvature derivative (*get_max_curvature()* and *get_max_curvature_der()*).
* It also uses the [gradient library](docs/gradient.md) to find the closest point on the curve to a given point. These functions always return the distance of the closest point from the start of the spline, and, optionally, the state of this point.
* Provides a function to get a new spline which is a part of the original one (*get_part()*).
The functions that use the gradinet descent algorithm can set the maximum error (*max_error*) and maximum number of iterations (*max_iter*). If not set, the default values are used:
* **max_error**: 0.001
* **max_iter**: 10
Keep also in mind that extensive use of these functions may increase considerably the computational cost.
gradient descent library
========================
## Description
This library has a simple C++ implementation of the simple [gradient descent algorithm](https://en.wikipedia.org/wiki/Gradient_descent).
The main features of this library are:
* Provides a function pointer to evaluate the desired function at a given point which can be set by the user (*set_function()*).
* Provides a function pointer to evaluate the derivative of the desired function at a given point which can be set by the user (*set_function_der()*).
* The user can set the coordinate range (maximum and minimum) of convergence of the algorithm as well as the maximum coordinate increment at each iteration (*set_coord_constraints()* and *set_max_coord_inc()*).
The function to compute the gradient algorithm is called *compute* and has the following prototype:
```
bool compute(double max_func_error,unsigned int max_iter,double start_point,bool &beyond_limits,bool max);
```
where:
* **max_func_error**: is the maximum difference with the previous iteration to consider that the algorithm has found a solution.
* **max_iter**: is the maximum number of iterations allowed to the algorihtm. If the solution is found before reacing this limit, the function will return immediatelly.
* **start_point**: is the start point of the algorithm. It may be usefull to avoid local minima of the desired function.
* **beyond_limits**: an output flag that indicates that the solution found is one of the convergence limits set by the user.
* **max**: an input flag to indicate whetehr to find the maximum (true) of the minimum (false) of the function. If not set, the default value is true.
The convergence algorithm can end in several different ways:
* The algorithm can not find a solution with the given maximum error and number of iterations. In this case the *compute()* function returns false;
* The algorithm finds a valid solution but it is one of the convergence limits set by the user. In this case the *compute()* function returns true, but the *beyond_limits* flag is set.
* The algorithm finds a valid solution inside the convergence limits. In this case the *compute()* function return true.
## How to use it
To us this class:
* Create an object of this class.
* Set the maximum coordinate increment at each iteration with the *set_max_coord_inc()* function. Is not set, the default value is 0.1.
* Set the desired coordinate range with the *set_coord_constraints()* function. If not set, the default values are max=double_max and min=double_min.
* Set the function evaluation function with the *set_function()* function. If not set, the algorithm will not work.
* Set the function derivative evaluation function with the *set_function_der()* function. If not set, the algorithm will not work.
* Execute the algorithm with the *compute()* function.
An example is provided for a simple sinus function.
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment