src/pathplan/map.h

   1 #ifndef __MAP_H
   2 #define __MAP_H
   3
   4 #include <stdbool.h>
   5
   6 /**
   7  * @defgroup maplib     Library to manage the map
   8  * This libary implements a discrete map use wich can be use in robotics.
   9  * The features are:
  10  * - Shared map memory (@ref shmap) : the map memory is shared using
  11      interprocess comunication methods.
  12  * - Discrete Space (@ref discrete_map): the real space is divided
  13      into cells of variable size. Each cell has its own propieties.
  14  *
  15  * @section shmap Shared Memory Map
  16
  17  * There are two important methods to acces to the shared map. Before
  18  * using shmap, it should be init by the function ShmapInit(). After
  19  * finishing using it the shmap should be clear by ShmapFree().
  20  *
  21  * @warning If the program exit without a ShmapFree(), the memory will
  22  * stay in Linux SHM. You can verify it with command "ipcs -m". For
  23  * further details, read shm documentation.
  24  *
  25  * @section the_map The map
  26  * @subsection real_map The real space
  27  *
  28  * The map size is (#MAP_PLAYGROUND_WIDTH_MM
  29  * x #MAP_PLAYGROUND_HEIGHT_MM). This space discretization is
  30  * explained in section @ref discrete_map .
  31  *
  32  * @code
  33  *                              0                                       MAP_PLAYGROUND_WIDTH_MM
  34  * MAP_PLAYGROUND_HEIGHT_MM     +---------------------------------------+
  35  *                              |                                       |
  36  *                              |                                       |
  37  *                              |                                       |
  38  *                              |                                       |
  39  *                              |                                       |
  40  *                              |                                       |
  41  *                              |                                       |
  42  *                              |                                       |
  43  *                              |                                       |
  44  *                              |                                       |
  45  *                              |                                       |
  46  *                              |                                       |
  47  *                              |                                       |
  48  *                              |                                       |
  49  *                              |                                       |
  50  *                         y=0  +---------------------------------------+ 0
  51  *                             x=0                                      MAP_PLAYGROUND_WIDTH_MM
  52  * @endcode
  53  * @subsection discrete_map The discrete Map
  54  *
  55  * Map library uses a discrete representation of the space. This
  56  * representation has been implemented as a cell grid (matrix). Each
  57  * cell (pixel) is represents #MAP_CELL_SIZE mm square. We can
  58  * consider a cell as a set of points. All the points of a cell have
  59  * the same value that the cell. The origin is located in up left
  60  * corner.
  61  *
  62  * There are only a coordonates difference between points and
  63  * cells. Cell which cordonates [0,0] represents all the points
  64  * contained in a square sited up left corner.
  65  *
  66  * @code
  67  *                              X 0   1   2   3   4   5   6   7   8   MAP_WIDTH-1
  68  *                            Y +---+---+---+---+---+---+---+---+---+---+
  69  *                            0 |0,0|   |   |   |   |   |   |   |   |   |
  70  *                              +---+---+---+---+---+---+---+---+---+---+
  71  *                            1 |   |   |   |   |   |   |   |   |   |   |
  72  *                              +---+---+---+---+---+---+---+---+---+---+
  73  *                              |   |   |   |   |   |   |   |   |   |   |
  74  *                              +---+---+---+---+---+---+---+---+---+---+
  75  *                              |   |   |   |   |   |   |   |   |   |   |
  76  *                              +---+---+---+---+---+---+---+---+---+---+
  77  *                              |   |   |   |   |   |   |   |   |   |   |
  78  *                              +---+---+---+---+---+---+---+---+---+---+
  79  *                              |   |   |   |   |   |   |   |   |   |   |
  80  *                              +---+---+---+---+---+---+---+---+---+---+
  81  *                              |   |   |   |   |   |   |   |   |   |   |
  82  *                              +---+---+---+---+---+---+---+---+---+---+
  83  *                              |   |   |   |   |   |   |   |   |   |   |
  84  *                              +---+---+---+---+---+---+---+---+---+---+
  85  *                              MAP_HEIGHT-1
  86  * @endcode
  87  *
  88  * @note Matrix convention is usally (row, column). In this program
  89  * the convention will be (column, row) in order to keep real
  90  * coordonates relation. C language stockes matrix in rows, so a cell
  91  * coordonate (x,y) will be in a C matrix [y][x].
  92  *
  93  * @section map_content Map Content
  94  * Each cell/point of the map (::MapCell) contains two types of information:
  95  * - Value (::MapCellValue) : It determins the type of cell. It is the
  96      information used by A* algorithm.
  97  * - Flag (::MapCellFlag) : It is extra information.
  98  *
  99  * @subsection cell_values      Map Values
 100  *
 101  * This information is of the type ::MapCellValue.The value that the
 102  * map contains can be:
 103  * - #MAP_WALL: Wall of the map. A fixed obstacle.
 104  * - #MAP_WALL_CSPACE : Configuration Space of a wall.
 105  * - #MAP_PATH:  A part of path.
 106  * - #MAP_START: The Start
 107  * - #MAP_GOAL: The Goal
 108  * - #MAP_NEW_OBSTACLE: New obstacle. This type is set when the
 109       sensors found an obstacle. It can be view as a moving obstacle.
 110  * - #MAP_NEW_OBSTACLE_CSPACE: Configuration Space of the obstacle .
 111  * - #MAP_FREE: Free space.
 112  *
 113  * One special type is #MAP_NOT_IN_MAP. It is a error code return when
 114  * we try to acces to a space wich is not in the map. (i.e. the
 115  * request cell/point exceeds map dimensions.)
 116  *
 117  * @note The configuration space is a special obstacle type that
 118  * depends on the geometry of the robot. For more information, read
 119  * a book about robotics.
 120  *
 121  * @subsection cell_flags       Cell Flags
 122  * The possible cell flags are:
 123  * - #MAP_FLAG_NO_FLAG
 124  * - #MAP_FLAG_WALL
 125  * - #MAP_FLAG_PATH
 126  * - #MAP_FLAG_START
 127  * - #MAP_FLAG_GOAL
 128
 129  * One special type is #MAP_FLAG_ERROR. It is a error code return when
 130  * we try to acces to a space wich is not in the map. (i.e. the
 131  * request cell/point exceeds map dimensions.)
 132
 133  * @subsection map_func Accessing to map information
 134  *
 135  * To read and write cell values, use functions ShmapGetCellValue()
 136  * and ShmapSetCellValue(). If you want to acces directly to points,
 137  * you can also use ShmapGetPointValue() and ShmapSetPointValue().
 138  *
 139  * There are similar functions to get and set flags:
 140  * ShmapGetCellFlag() and ShmapSetCellFlag(), ShmapGetPointValue() and
 141  * ShmapSetPointFlag().
 142  *
 143  * It can be possible also to edit more than a point at the same time
 144  * with function ShmapSetRectangleType().
 145  *
 146  * If you want to know if a cell is free see ShmapIsFreeCell() and
 147  * ShmapIsFreePoint().
 148  *
 149  * ShmapUpdateTmpObstacles() is a specific function created for
 150  * Eurobot Project.  Please, see an example in testmap.c file
 151  *
 152  * @example testmap.c
 153  * Example how to use Shmap library.
 154  */
 155 /**
 156  * @addtogroup maplib
 157  * @{*/
 158
 159 /** @name Map constaints */
 160 /**@{*/
 161 #define MAP_WIDTH               30      /**< Field width*/
 162 #define MAP_HEIGHT              21      /**< Field height*/
 163 #define MAP_CELL_SIZE_MM        100     /**< Size of a cell in mm. The cell is a square. */
 164 #define MAP_CELL_SIZE_M         (MAP_CELL_SIZE_MM/1000.0)
 165 #define MAP_PLAYGROUND_WIDTH_MM (MAP_WIDTH*MAP_CELL_SIZE_MM)    /**< Playground width depends on width and cell size. */
 166 #define MAP_PLAYGROUND_WIDTH_M  (MAP_PLAYGROUND_WIDTH_MM/1000.0)
 167 #define MAP_PLAYGROUND_HEIGHT_MM        (MAP_HEIGHT*MAP_CELL_SIZE_MM)   /**< Playground width depends on height and cell size. */
 168 #define MAP_PLAYGROUND_HEIGHT_M         (MAP_PLAYGROUND_HEIGHT_MM/1000.0)
 169 /**@}*/
 170
 171 /**
 172  * @name Cell Flags
 173  * @{
 174  */
 175 #define MAP_FLAG_WALL           1 /**< Known wall */
 176 #define MAP_FLAG_PATH           2
 177 #define MAP_FLAG_START          4
 178 #define MAP_FLAG_GOAL           8
 179 #define MAP_FLAG_DET_OBST       16 /**< Set when an obstacle is detected, cleard on every "map forget cycle" */
 180 #define MAP_FLAG_SIMULATED_WALL 32 /**< Used by robomon to simulate obstacles */
 181 #define MAP_FLAG_IGNORE_OBST    64 /**< If obstacle is detected here, ignore it */
 182
 183 /** @}*/
 184 /** @name Shared Memory macros */
 185 /**@{*/
 186 #define SHM_MAP_KEY     555             /**< Key use to share the memory SHM*/
 187 /**@}*/
 188
 189 /**@}*/
 190
 191 #ifdef __cplusplus
 192 extern "C" {
 193 #endif
 194
 195 typedef unsigned char map_cell_detobst_t;
 196 typedef unsigned char map_cell_flag_t;
 197
 198 typedef struct map_cell {
 199     map_cell_flag_t flags;
 200     map_cell_detobst_t detected_obstacle; /**< 0 = no obstacle, 255 = new obstacle */
 201 } MapCell;
 202
 203 #define MAP_NEW_OBSTACLE 255
 204 #define MAP_NO_OBSTACLE 0
 205
 206 struct map {
 207         MapCell cells[MAP_HEIGHT][MAP_WIDTH];
 208
 209 }; /**< The main structure.*/
 210
 211 /** See ShmapCellAtPoint(). */
 212 extern struct map_cell ShmapNoCell;
 213
 214 void ShmapAllFreeSpace(void);
 215 struct map *ShmapInit(int init_flag);
 216 void ShmapFree(void);
 217 void ShmapDt(void);
 218 struct map * ShmapIsMapInit(void);
 219
 220 void ShmapPoint2Cell(double x, double y, int *cx, int *cy, bool *valid);
 221
 222 int ShmapCell2Point(int ix, int iy, double *x, double *y);
 223
 224 /**
 225  * Gives information about a cell
 226  *
 227  * @param       x       Coordinate of a cell
 228  * @param       y       Coordinate of a cell
 229  * @return              1 if cell is in map, 0 otherwise
 230  */
 231 static inline int ShmapIsCellInMap(int x, int y){
 232         if( ( x < MAP_WIDTH ) && (y < MAP_HEIGHT) && ( x >= 0 ) && ( y >= 0) ) return 1;
 233         return 0;
 234 }
 235
 236 /**
 237  * @brief Give information about if a point is in map
 238  * @param x_m   Coordonate X (in m) of a point
 239  * @param y_m   Coordonate Y (in m) of a point
 240  * @return      1 if point is in map, 0 otherwise
 241  */
 242 static inline int ShampIsPointInMap(double x_m, double y_m){
 243         int x, y;
 244         bool valid;
 245         ShmapPoint2Cell(x_m, y_m, &x, &y, &valid);
 246         return ShmapIsCellInMap(x, y);
 247 }
 248
 249 int ShampIsPointInMap(double x_m, double y_m);
 250
 251 void ShmapUpdateTmpObstacles(map_cell_detobst_t val);
 252
 253 int ShmapIsFreeCell(int x, int y);
 254 int ShmapIsFreePoint(double x_m, double y_m);
 255
 256 int ShmapSetRectangleFlag(double x1, double y1, double x2, double y2, map_cell_flag_t set_flags, map_cell_flag_t clear_flags);
 257
 258 #ifdef __cplusplus
 259 }
 260 #endif
 261
 262 #endif //__MAP_H_
 263