TNTsdk: Cartoscript 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

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[]

Cartoscript Functions

Functions

Detailed Description

Function Documentation


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)