/
ms-rfc-27.txt
141 lines (100 loc) · 4 KB
/
ms-rfc-27.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
.. _rfc27:
======================================================================
MS RFC 27: Label Priority
======================================================================
:Date: 2007/05/22
:Author: Daniel Morissette
:Contact: dmorissette at mapgears.com
:Last Edited: 2007/06/29
:Status: Adopted (2007/05/25) - Implementation completed (2007/07/05)
:Version: MapServer 5.0
Overview
--------
MapServer 4.10 and older used a last in first out (LIFO) mechanism to plot
labels on a map. This resulted in excessive use of ANNOTATION layers to make
certain labels more prominent. This RFC introduces a new PRIORITY parameter
on the LABEL object to control the order in which labels are rendered.
Technical Solution
------------------
PRIORITY is a new LABEL parameter that takes an integer value between 1
(lowest) and MS_MAX_LABEL_PRIORITY (highest). The default value is 1.
MS_MAX_LABEL_PRIORITY is defined and can be altered in map.h, its default
value is 10.
The prioritization is handled by maintaining an array of MS_MAX_LABEL_PRIORITY
cache lists in the label cache. When a label is added to the label cache,
its priority index is used to decide in which cache list it should be added.
Then at rendering time, we loop through the cache lists, starting with the
highest priority list.
Specifying an out of range PRIORITY value inside a map file will result in a
parsing error. An out of range value set via MapScript or coming from a shape
attribute will be clamped to the min/max values in msAddLabel().
There is no expected impact on performance for using label priorities.
Support for attribute binding
-----------------------------
The PRIORITY parameter can also be bound to an attribute using the attribute
bindings mechanism defined in RFC-19. This means two ways to set LABEL
PRIORITY:
::
...
LABEL
PRIORITY 5
...
END
...
or
::
...
LABEL
PRIORITY [someattribute]
...
END
...
Modifications to the source code
--------------------------------
* PRIORITY will be added to the LABEL object in map.h, in the mapfile
parser/writer (mapfile.c) and in MapScript
* A MS_IS_VALID_LABEL_PRIORITY() macro will be defined to validate
priority ranges in a consistent way everywhere.
* The label cache code (maplabel.c) will be modified to work with an
array of MS_MAX_LABEL_PRIORITY cache lists instead of a single list
* The various msDrawLabelCacheXX() functions will be modified to replace the
current loop on cache items with two nested loops: the outer loop will
iterate on cache lists (from highest to lowest), and the inner loop will
iterate on the cache items inside each list.
* msBindLayerToShape() will be updated to support binding PRIORITY to a
shape attribute field.
MapScript Implications
----------------------
The labelObj will have a new priority property of type integer.
Files affected
--------------
::
map.h
mapfile.c
maplabel.c
maputil.c
mapgd.c (msDrawLabelCacheGD)
mapimagemap.c (msDrawLabelCacheIM)
mappdf.c (msDrawLabelCachePDF)
mapsvg.c (msDrawLabelCacheSVG)
mapswf.c (msDrawLabelCacheSWF)
mapagg.cpp (msDrawLabelCacheAGG)
Backwards compatibility issues
------------------------------
None.
Bug ID
------
* 1619: https://github.com/mapserver/mapserver/issues/1619
* Bug 206 also made mention of label priority but has been closed as
duplicate of 1619: https://github.com/mapserver/mapserver/issues/206
Voting history
--------------
Vote completed on 2007-05-25:
+1 from DanielM, SteveW, SteveL, YAssefa, UmbertoN and FrankW
Questions/Comments from the review period
-----------------------------------------
* Q: Why use an array of cache lists instead of doing a quicksort on all
cache entries?
A: Mainly for performance reason, but it was also pointed out that
quicksort is not stable and could result in different orderings
depending on the set of labels.