: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) |
:Associate with "Line Style Functions"
| 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
| 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
| 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
| 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.
| handle | Handle returned by MlabelPlaceInit |
| int MlabelPlaceGetLabelPosition | ( | LABELHANDLE | handle, | |
| INT32 | ElemNum, | |||
| DRECT2D * | rect | |||
| ) |
Retrieve labels position.
| 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.
| 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.
| 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.
| 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.
| 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[] |
1.6.1