2
* libpal - Automated Placement of Labels Library
4
* Copyright (C) 2008 Maxence Laurent, MIS-TIC, HEIG-VD
5
* University of Applied Sciences, Western Switzerland
9
* maxence.laurent <at> heig-vd <dot> ch
11
* eric.taillard <at> heig-vd <dot> ch
13
* This file is part of libpal.
15
* libpal is free software: you can redistribute it and/or modify
16
* it under the terms of the GNU General Public License as published by
17
* the Free Software Foundation, either version 3 of the License, or
18
* (at your option) any later version.
20
* libpal is distributed in the hope that it will be useful,
21
* but WITHOUT ANY WARRANTY; without even the implied warranty of
22
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
23
* GNU General Public License for more details.
25
* You should have received a copy of the GNU General Public License
26
* along with libpal. If not, see <http://www.gnu.org/licenses/>.
42
// TODO ${MAJOR} ${MINOR} etc instead of 0.2
45
* \mainpage Pal Libray
47
* \section intro_sec Introduction
49
* Pal is a labelling library released under the GPLv3 license
56
template <class Type> class LinkedList;
65
/** Units for label sizes and distlabel */
68
PIXEL = 0, /**< pixel [px]*/
69
METER, /**< meter [m]*/
70
FOOT, /**< foot [ft]*/
71
DEGREE /**< degree [°] */
74
/** Typedef for _Units enumeration */
75
typedef enum _Units Units;
77
/** Search method to use */
80
CHAIN = 0, /**< is the worst but fastest method */
81
POPMUSIC_TABU_CHAIN = 1, /**< is the best but slowest */
82
POPMUSIC_TABU = 2, /**< is a little bit better than CHAIN but slower*/
83
POPMUSIC_CHAIN = 3, /**< is slower and best than TABU, worse and faster than TABU_CHAIN */
84
FALP = 4 /** only initial solution */
87
/** Typedef for _Units enumeration */
88
typedef enum _searchMethod SearchMethod;
90
/** The way to arrange labels against spatial entities
92
* \image html arrangement.png "Arrangement modes" width=7cm
96
P_POINT = 0, /**< arranges candidates around a point (centroid for polygon)*/
97
P_POINT_OVER, /** arranges candidates over a point (centroid for polygon)*/
98
P_LINE, /**< Only for lines and polygons, arranges candidates over the line or the polygon perimeter */
99
P_CURVED, /** Only for lines, labels along the line */
100
P_HORIZ, /**< Only for polygon, arranges candidates horizontaly */
101
P_FREE /**< Only for polygon, arranges candidates with respect of polygon orientation */
104
/** typedef for _arrangement enumeration */
105
typedef enum _arrangement Arrangement;
107
/** enumeration line arrangement flags. Flags can be combined. */
108
enum LineArrangementFlags
113
FLAG_MAP_ORIENTATION = 8
117
* \brief Pal main class.
119
* A pal object will contains layers and global informations such as which search method
120
* will be used, the map resolution (dpi) ....
122
* \author Maxence Laurent <maxence _dot_ laurent _at_ heig-vd _dot_ ch>
124
class CORE_EXPORT Pal
126
friend class Problem;
127
friend class FeaturePart;
130
std::list<Layer*> * layers;
132
SimpleMutex *lyrsMutex;
134
// TODO remove after tests !!!
140
* \brief maximum # candidates for a point
145
* \brief maximum # candidates for a line
150
* \brief maximum # candidates for a polygon
154
SearchMethod searchMethod;
171
* \brief Problem factory
172
* Extract features to label and generates candidates for them,
173
* respects to a bounding box and a map scale
175
* @param nbLayers number of layers to extract
176
* @param layersName layers name to be extracted
177
* @param layersFactor layer's factor (priority between layers, 0 is the best, 1 the worst)
178
* @param lambda_min xMin bounding-box
179
* @param phi_min yMin bounding-box
180
* @param lambda_max xMax bounding-box
181
* @param phi_max yMax bounding-box
182
* @param scale the scale (1:scale)
183
* @param svgmap stream to wrtie the svg map (need _EXPORT_MAP_ #defined to work)
185
Problem* extract( int nbLayers, char **layersName, double *layersFactor,
186
double lambda_min, double phi_min,
187
double lambda_max, double phi_max,
188
double scale, std::ofstream *svgmap );
192
* \brief Choose the size of popmusic subpart's
193
* @param r subpart size
195
void setPopmusicR( int r );
200
* \brief minimum # of iteration for search method POPMUSIC_TABU, POPMUSIC_CHAIN and POPMUSIC_TABU_CHAIN
201
* @param min_it Sub part optimization min # of iteration
203
void setMinIt( int min_it );
206
* \brief maximum \# of iteration for search method POPMUSIC_TABU, POPMUSIC_CHAIN and POPMUSIC_TABU_CHAIN
207
* @param max_it Sub part optimization max # of iteration
209
void setMaxIt( int max_it );
212
* \brief For tabu search : how many iteration a feature will be tabu
213
* @param tenure consiser a feature as tabu for tenure iteration after updating feature in solution
215
void setTenure( int tenure );
218
* \brief For *CHAIN, select the max size of a transformation chain
219
* @param degree maximum soze of a transformation chain
221
void setEjChainDeg( int degree );
224
* \brief How many candidates will be tested by a tabu iteration
225
* @param fact the ration (0..1) of candidates to test
227
void setCandListSize( double fact );
231
* \brief Get the minimum # of iteration doing in POPMUSIC_TABU, POPMUSIC_CHAIN and POPMUSIC_TABU_CHAIN
232
* @return minimum # of iteration
236
* \brief Get the maximum # of iteration doing in POPMUSIC_TABU, POPMUSIC_CHAIN and POPMUSIC_TABU_CHAIN
237
* @return maximum # of iteration
245
* \brief Create an new pal instance
250
* \brief delete an instance
255
* \brief add a new layer
257
* @param lyrName layer's name
258
* @param min_scale bellow this scale: no labelling (-1 to disable)
259
* @param max_scale above this scale: no labelling (-1 to disable)
260
* @param arrangement Howto place candidates
261
* @param label_unit Unit for labels sizes
262
* @param defaultPriority layer's prioriry (0 is the best, 1 the worst)
263
* @param obstacle 'true' will discourage other label to be placed above features of this layer
264
* @param active is the layer is active (currently displayed)
265
* @param toLabel the layer will be labeled only if toLablel is true
267
* @throws PalException::LayerExists
269
* @todo add symbolUnit
271
Layer * addLayer( const char *lyrName, double min_scale, double max_scale, Arrangement arrangement, Units label_unit, double defaultPriority, bool obstacle, bool active, bool toLabel );
274
* \brief Look for a layer
276
* @param lyrName name of layer to search
278
* @throws PalException::UnkownLayer
280
* @return a pointer on layer or NULL if layer not exist
282
Layer *getLayer( const char *lyrName );
285
* \brief get all layers
287
* @return a list of all layers
289
std::list<Layer*> *getLayers();
292
* \brief remove a layer
294
* @param layer layer to remove
296
void removeLayer( Layer *layer );
299
* \brief the labeling machine
300
* Will extract all active layers
302
* @param scale map scale is 1:scale
303
* @param bbox map extent
304
* @param stats A PalStat object (can be NULL)
305
* @param displayAll if true, all feature will be labelled evan though overlaps occurs
307
* @return A list of label to display on map
309
std::list<LabelPosition*> *labeller( double scale, double bbox[4], PalStat **stats, bool displayAll );
313
* \brief the labeling machine
314
* Active layers are specifiend through layersName array
315
* @todo add obstacles and tolabel arrays
317
* @param nbLayers # layers
318
* @param layersName names of layers to label
319
* @param layersFactor layers priorities array
320
* @param scale map scale is '1:scale'
321
* @param bbox map extent
322
* @param stat will be filled with labelling process statistics, can be NULL
323
* @param displayAll if true, all feature will be labelled evan though overlaps occurs
325
* @todo UnknownLayer will be ignored ? should throw exception or not ???
327
* @return A list of label to display on map
329
std::list<LabelPosition*> *labeller( int nbLayers,
331
double *layersFactor,
332
double scale, double bbox[4],
337
Problem* extractProblem( double scale, double bbox[4] );
339
std::list<LabelPosition*>* solveProblem( Problem* prob, bool displayAll );
342
* \brief Set map resolution
344
* @param dpi map resolution (dot per inch)
346
void setDpi( int dpi );
349
* \brief get map resolution
351
* @return map resolution (dot per inch)
358
* \brief set # candidates to generate for points features
359
* Higher the value is, longer Pal::labeller will spend time
361
* @param point_p # candidates for a point
363
void setPointP( int point_p );
366
* \brief set maximum # candidates to generate for lines features
367
* Higher the value is, longer Pal::labeller will spend time
369
* @param line_p maximum # candidates for a line
371
void setLineP( int line_p );
374
* \brief set maximum # candidates to generate for polygon features
375
* Higher the value is, longer Pal::labeller will spend time
377
* @param poly_p maximum # candidate for a polygon
379
void setPolyP( int poly_p );
382
* \brief get # candidates to generate for point features
387
* \brief get maximum # candidates to generate for line features
392
* \brief get maximum # candidates to generate for polygon features
397
* \brief get current map unit
402
* \brief set map unit
404
void setMapUnit( Units map_unit );
407
* \brief Select the search method to use.
409
* For interactive mapping using CHAIN is a good
410
* idea because it is the fastest. Other methods, ordered by speedness, are POPMUSIC_TABU,
411
* POPMUSIC_CHAIN and POPMUSIC_TABU_CHAIN, defined in pal::_searchMethod enumeration
412
* @param method the method to use
414
void setSearch( SearchMethod method );
417
* \brief get the search method in use
419
* @return the search method
421
SearchMethod getSearch();
423
} // end namespace pal
added
removed
src/core/pal/pal.h
