Cartoscript Functions

:Associate with "Line Style Functions" More...

Functions
int	MlabelPlaceAddRect (LABELHANDLE handle, DRECT2D *Label, INT32 ElemNum, DOUBLE Rank)
int	MlabelPlaceAddRectAtAnchor (LABELHANDLE handle, DRECT2D *Label, INT32 ElemNum, DOUBLE Rank, DPOINT2D *Anchor)
int	MlabelPlaceAddRectAtPosition (LABELHANDLE handle, DRECT2D *Label, INT32 ElemNum, DOUBLE Rank, int PosIndex)
int	MlabelPlaceFree (LABELHANDLE handle)
int	MlabelPlaceGetLabelPosition (LABELHANDLE handle, INT32 ElemNum, DRECT2D *rect)
int	MlabelPlaceGetPositionFactors (LABELHANDLE handle, DOUBLE *PosWeight, UINT8 startentry, UINT8 numentries)
int	MlabelPlaceInit (LABELHANDLE *handle, const DRECT2D *space, INT32 NumLabelsInit)
int	MlabelPlaceOptimize (LABELHANDLE handle, int DoOptimize, int DoDelete, INT32 *NumObscured)
int	MlabelPlaceSetPositionFactors (LABELHANDLE handle, DOUBLE *PosWeight, UINT8 startentry, UINT8 numentries)

---

Detailed Description

:Associate with "Line Style Functions"

---

Function Documentation

int MlabelPlaceAddRect (  LABELHANDLE  handle, DRECT2D *  Label, INT32  ElemNum, DOUBLE  Rank )

Add rectangular area (or label) to optimizer. Based on some tests it's not recomended to use continious variables as a rank value. Use categorical variables instead. For example: using population for ranking cities produces worst results compared to using categorical cities rank derived from population. Example of Categorical Variable: if (population < 1000) rank = 1 if (population > 1000 && population < 10000) rank = 2 if (population > 10000) rank = 3 Parameters: handle  Handle returned by MlabelPlaceInit Label  Rectangle that defines area covered by label ElemNum  Some unique ID-number for label Rank  Label's rank (any number), the greater is this rank - more important is this label.

int MlabelPlaceAddRectAtAnchor (  LABELHANDLE  handle, DRECT2D *  Label, INT32  ElemNum, DOUBLE  Rank, DPOINT2D *  Anchor )

Add rectangular area (or label) to optimizer. "Anchor" point is used to determine an internal position of rectangle around attachment point. The closest internal position will be used, so Anchor point that you pass will not be a real attachment point in all 100% of possible cases. If you Anchor point is situated at one of the 17 possible positions, it will be equal to attachment point of the label. For more info see MlabelPlaceInit() and MlabelPlaceAddRectAtPosition(). Based on some tests it's not recomended to use continious variables as a rank value. Use categorical variables instead. For example: using population for ranking cities produces worst results compared to using categorical cities rank derived from population. Example of Categorical Variable: if (population < 1000) rank = 1 if (population > 1000 && population < 10000) rank = 2 if (population > 10000) rank = 3 Parameters: handle  Handle returned by MlabelPlaceInit Label  Rectangle that defines area covered by label ElemNum  Some unique ID-number for label Rank  Label's rank (any number), the greater is this rank - more important is this label Anchor  "Attachment" point of the rectangle

int MlabelPlaceAddRectAtPosition (  LABELHANDLE  handle, DRECT2D *  Label, INT32  ElemNum, DOUBLE  Rank, int  PosIndex )

Add rectangular area (or label) to optimizer. PosNum defines relationship between rectangle that defines a label and "attachment" point. Rectangle will be moved arround attachment point at predefined positions. For example: POSITION_1 is a bottom left corner of the rectangle, POSITION_17 or POSITION_CENTER is a center of the rectangle and etc. See mstyle.h for the list of positions and constants. Based on some tests it's not recomended to use continious variables as a rank value. Use categorical variables instead. For example: using population for ranking cities produces worst results compared to using categorical cities rank derived from population. Example of Categorical Variable: if (population < 1000) rank = 1 if (population > 1000 && population < 10000) rank = 2 if (population > 10000) rank = 3 Parameters: handle  Handle returned by MlabelPlaceInit Label  Rectangle that defines area covered by label ElemNum  Some unique ID-number for label Rank  Label's rank (any number), the greater is this rank - more important is this label. PosIndex  Initial position number (see MlabelPlaceInit())

int MlabelPlaceFree (  LABELHANDLE  handle  )

Free resources associated with optimizer. Parameters: handle  Handle returned by MlabelPlaceInit

int MlabelPlaceGetLabelPosition (  LABELHANDLE  handle, INT32  ElemNum, DRECT2D *  rect )

Retrieve labels position. Returns: TRUE if label is not discarded during optimization, rect contains label's position, FALSE if label was removed, error code < 0 on error. Parameters: handle  Handle returned by MlabelPlaceInit ElemNum  Label's unique ID number rect  Label's position

int MlabelPlaceGetPositionFactors (  LABELHANDLE  handle, DOUBLE *  PosWeight, UINT8  startentry, UINT8  numentries )

Get position "preferability" factors. This functions fills out PosWeight array with internal "preferability" factors. Programmer is responsible for allocating PosWeight array. Parameters: handle  Handle returned by MlabelPlaceInit PosWeight  Array of position "preferability" factors, all numbers should be positive. The smaller is a preferability factor designate more desirible position of the label. startentry  Starting internal position number 1...POSITION_LAST numentries  Number of elements to get, number of entries in PosWeight[]

int MlabelPlaceInit (  LABELHANDLE *  handle, const DRECT2D *  space, INT32  NumLabelsInit )

Initialize label placement toolkit. Explanation of the label placement toolkit basics: Label placement toolkit deals with the rectangles that represent some features that should be arranged with minimum number of collisions. There are 17 fixed positions arround the points: Label positions relative to center point (+): [2] [1] [6] + [7]+[5] and 8 additional positions are similar to first 8 but shifted on 0.25 of width/height [4] [3] [8] It's kind of hard to draw a picture of positions 9-16 using characters. Position 17 is when point is right in the center of the rectangle. Each position has preferability factor assigned to it, so each rectangle will try to occupy position with highest preferablity factor and minimum number of collisions. Use MlabelPlaceGet/SetPositionFactors() to get/set preferability levels to positions. Initially preferability factor is equal to position number, i.e. position number 1 is most desirable. Parameters: handle  Handle returned space  Bounding rectangle of input labels NumLabelsInit  Initial number od labels to optimize

int MlabelPlaceOptimize (  LABELHANDLE  handle, int  DoOptimize, int  DoDelete, INT32 *  NumObscured )

Run optimization procedure. NOTE: This procedure in it's current implementation is always doing some amount of optimization even if DoOptimize == FALSE. When DoOptimize is TRUE full optimization is invoked, that might be time consuming process depending on number of input labels. Parameters: handle  Handle returned by MlabelPlaceInit DoOptimize  Flag for doing full optimization DoDelete  Flag for deleting overlaping labels NumObscured  Number of labels deleted by the process returned

int MlabelPlaceSetPositionFactors (  LABELHANDLE  handle, DOUBLE *  PosWeight, UINT8  startentry, UINT8  numentries )

Set position "preferability" factors. Parameters: handle  handle returned by MlabelPlaceInit PosWeight  Array of position "preferability" factors, all numbers should be positive. The smaller is a preferability factor designate more desirable position of the label. startentry  Starting internal position number 1...POSITION_LAST numentries  Number of elements to set, number of entries in PosWeight[]

---