Skip to content

Commit 022c539

Browse files
rouaultrouault
authored
Merge pull request #960 from rouault/rfc139
Add RFC-139: Raster labeling (CONNECTIONTYPE RASTERLABEL)
2 parents ea8241e + b3633df commit 022c539

File tree

6 files changed

+233
-3
lines changed

6 files changed

+233
-3
lines changed

‎conf.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -425,7 +425,7 @@ class WKTLexer(RegexLexer):
425425
r'OPACITY|OUTLINECOLOR|OUTLINEWIDTH|OUTPUTFORMAT|OVERLAYBACKGROUNDCOLOR|'
426426
r'OVERLAYCOLOR|OVERLAYMAXSIZE|OVERLAYMINSIZE|OVERLAYOUTLINECOLOR|'
427427
r'OVERLAYSIZE|OVERLAYSYMBOL|PARTIALS|PATTERN|POINTS|POLAROFFSET|POSITION|POSTLABELCACHE|'
428-
r'PRIORITY|PROCESSING|PROJECTION|QUERYFORMAT|QUERYMAP|REFERENCE|REGION|'
428+
r'PRIORITY|PROCESSING|PROJECTION|QUERYFORMAT|QUERYMAP|RASTERLABEL|REFERENCE|REGION|'
429429
r'RELATIVETO|REQUIRES|RESOLUTION|SCALE|SCALEDENOM|SCALETOKEN|SHADOWCOLOR|SHADOWSIZE|'
430430
r'SHAPEPATH|SIZE|SIZEUNITS|STATUS|STYLE|STYLEITEM|SYMBOL|SYMBOLSCALE|'
431431
r'SYMBOLSCALEDENOM|SYMBOLSET|TABLE|TEMPLATE|TEMPLATEPATTERN|TEXT|'

‎en/development/rfc/index.txt‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -149,4 +149,5 @@ the project.
149149
ms-rfc-135
150150
ms-rfc-136
151151
ms-rfc-137
152-
ms-rfc-138
152+
ms-rfc-138
153+
ms-rfc-139

‎en/development/rfc/ms-rfc-139.txt‎

Lines changed: 147 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,147 @@
1+
.. _rfc139:
2+
3+
=========================================================================
4+
MS RFC 139: Raster labeling (CONNECTIONTYPE RASTERLABEL)
5+
=========================================================================
6+
7+
:Date: 2024/08/14
8+
:Author: Even Rouault
9+
:Contact: even.rouault at spatialys.com
10+
:Status: Adopted
11+
:Version: MapServer 8.4
12+
13+
1. Overview
14+
-----------
15+
16+
This is a proposal to add the ability to render labels from raster pixel values,
17+
as an alternative or complement to other typical raster rendering (grayscale,
18+
classification, etc.). Typical applications are for temperature, wind, humidity,
19+
slopes, altitude, noise, pollution, etc.
20+
21+
Visual example (rendered with MapServer):
22+
23+
.. image:: ../../images/rasterlabel.png
24+
25+
2. The proposed solution
26+
------------------------
27+
28+
This RFC proposes the addition of a new type of layer in MapServer:
29+
CONNECTIONTYPE RASTERLABEL.
30+
The code is strongly based on the UVRASTER capabilities, but will be kept separate
31+
as some likely potential evolutions of UVRASTER (such as modifying u,v values
32+
during reprojection operations) will make both implementation diverge.
33+
34+
The new type is a hybrid layer, which has a raster data source as input and
35+
vector features as output. Only the point representation of those
36+
vector features will be supported. Values at nodata will be ignored.
37+
38+
Since the data source is a raster, all raster processing options can be
39+
used (e.g. RESAMPLE). A default value of RESAMPLE=AVERAGE will be used, if it
40+
is not explicitly defined.
41+
42+
To render a vector field layer, we need to define a layer in the mapfile
43+
with the following options:
44+
45+
* Set the layer TYPE to POINT.
46+
* Set CONNECTIONTYPE to RASTERLABEL.
47+
* Set the DATA to the raster file.
48+
* If the raster file has more than one bands, add a PROCESSING "BANDS=<num>" option
49+
* Specify a CLASS with a LABEL object to label the points, using the [value]
50+
attribute binding.
51+
52+
Optional "PROCESSING" settings:
53+
54+
* BANDS=<num>: Specify the band to label. Not needed if there is a single band.
55+
* LABEL_SPACING=<num>: The spacing is simply the distance, in pixels, between points
56+
to be displayed in the vector field. Default is 32.
57+
* RESAMPLE=NEAREST/AVERAGE/BILINEAR: Defaults to AVERAGE.
58+
* ALLOW_OVERSAMPLE=YES/NO: Whether it is allowed to oversample the raster at
59+
a resolution higher than its nominal resolution. Default is NO, meaning that
60+
when zooming in beyond the nominal resolution of the raster, at most one
61+
point will be generated for each source pixel. This gives to the user a sense
62+
of the resolution of the data it displays.
63+
64+
The UVRASTER layer has one attribute bindings that can be used in the layer
65+
definition and/or class expressions:
66+
67+
* [value]: the raw raster value
68+
69+
Example of a layer definition:
70+
71+
::
72+
73+
LAYER
74+
NAME "temperature"
75+
TYPE POINT
76+
CONNECTIONTYPE RASTERLABEL
77+
PROJECTION
78+
"init=epsg:4326"
79+
END
80+
DATA data/temperature.tif
81+
# PROCESSING "BANDS=1"
82+
# PROCESSING "LABEL_SPACING=32"
83+
# PROCESSING "RESAMPLE=AVERAGE"
84+
# PROCESSING "ALLOW_OVERSAMPLE=NO"
85+
CLASS
86+
TEXT (tostring([value],"%.1f")+"°")
87+
LABEL
88+
TYPE TRUETYPE
89+
SIZE 7
90+
END # label
91+
END # class
92+
END
93+
94+
95+
3. Implementation Details
96+
-------------------------
97+
98+
Internally, a RASTERLABEL layer will have its own renderer/driver code. It's a
99+
hybrid layer because it reads the raster source as a normal raster
100+
layer does, but all other functions behave like a vector layer. The
101+
layer can be drawn as a normal point layer using whichShape, GetShape
102+
etc.
103+
104+
Basic internal draw process of a RASTERLABEL layer:
105+
106+
1. whichShape() is called: the raster data source is read using the
107+
internal GDAL functions, resample and all other raster options are applied
108+
and the pixels result is stored in the internal layer structure.
109+
110+
2. getShape() is called: loop through the raster pixels and returns a
111+
shapeObj (Point) created with the pixel location.
112+
113+
3. MapServer draws its point feature as any other vector layer.
114+
115+
3.1 Files affected
116+
------------------
117+
118+
The following files will be modified/created by this RFC:
119+
120+
::
121+
122+
mapserver.h/mapfile.c (Connection type RASTERLABEL support in the mapfile)
123+
maprasterlabel.cpp (new file for the RASTERLABEL renderer)
124+
mapuvraster.cpp (renamed from mapuvraster.c, not strictly correlated with this development, but was the opportunity to make an optimization to make getShape() faster when requesting increasing feature index, that is also used by maprasterlabel.cpp)
125+
maplayer.c (new layer type handling, virtual tables init etc.)
126+
maplexer.l (add additional RASTERLABEL keyword)
127+
128+
3.2 MapScript
129+
-------------
130+
131+
No issue for any MapScript bindings. The RASTERLABEL layer is handled/rendered internally as
132+
any other layer..
133+
134+
3.4 Backwards Compatibility Issues
135+
----------------------------------
136+
137+
This change provides a new functionality with no backwards compatibility issues being considered.
138+
139+
4. Candidate implementation
140+
---------------------------
141+
142+
* https://github.com/MapServer/MapServer/pull/7135
143+
144+
5. Voting history
145+
-----------------
146+
147+
+1 from PSC members EvenR, TomK, JukkaR, SethG, MikeS, DanielM, JeromeB, SteveL, JeffM

‎en/images/rasterlabel.png‎

14.6 KB
Loading

‎en/input/raster.txt‎

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -634,6 +634,85 @@ are supported in MapServer 4.0 and newer.
634634
.. index::
635635
pair: Raster; Query
636636

637+
.. _rasterlabel:
638+
639+
Raster Labelling
640+
================
641+
642+
.. versionadded:: 8.4
643+
644+
This is the ability to render labels from raster pixel values,
645+
as an alternative or complement to other typical raster rendering (grayscale,
646+
classification, etc.). Typical applications are for temperature, wind, humidity,
647+
slopes, altitude, noise, pollution, etc.
648+
649+
Visual example:
650+
651+
.. image:: ../images/rasterlabel.png
652+
653+
LAYER Description
654+
-----------------
655+
656+
A raster labelling layer :ref:`LAYER` is a hybrid layer, which has a raster data
657+
source as input and vector features as output. The output features
658+
are represented as points. Queries are not supported.
659+
660+
Since the data source is a raster, all raster processing options can
661+
be used (e.g. RESAMPLE). RESAMPLE=AVERAGE generally gives a good
662+
result, and the default. This can be overridden by explicitly
663+
specifying the type of resampling.
664+
665+
Vector field layers are of `TYPE` `point`, and have `CONNECTIONTYPE`
666+
`rasterlabel`. The raster data set is specified in `DATA`. The band to label
667+
is set through the `PROCESSING` `BANDS` option.
668+
669+
LAYER Attributes
670+
----------------
671+
672+
The rasterlabel connection type offers the following attribute:
673+
674+
* [value]: the raw value
675+
676+
Optional `PROCESSING` Settings
677+
------------------------------
678+
679+
* `BANDS=<num>`: Specify the band to label. Not needed if there is a single band.
680+
* `LABEL_SPACING=<num>`: The spacing is simply the distance, in pixels, between points
681+
to be displayed in the vector field. Default is 32.
682+
* `RESAMPLE=NEAREST/AVERAGE/BILINEAR`: Defaults to AVERAGE.
683+
* `ALLOW_OVERSAMPLE=YES/NO`: Whether it is allowed to oversample the raster at
684+
a resolution higher than its nominal resolution. Default is NO, meaning that
685+
when zooming in beyond the nominal resolution of the raster, at most one
686+
point will be generated for each source pixel. This gives to the user a sense
687+
of the resolution of the data it displays.
688+
689+
Example of a layer definition
690+
-----------------------------
691+
692+
.. code-block:: mapfile
693+
694+
LAYER
695+
NAME "temperature"
696+
TYPE POINT
697+
CONNECTIONTYPE RASTERLABEL
698+
PROJECTION
699+
"init=epsg:4326"
700+
END
701+
DATA "data/temperature.tif"
702+
# PROCESSING "BANDS=1"
703+
# PROCESSING "LABEL_SPACING=32"
704+
# PROCESSING "RESAMPLE=AVERAGE"
705+
# PROCESSING "ALLOW_OVERSAMPLE=NO"
706+
CLASS
707+
TEXT (tostring([value],"%.1f")+"°")
708+
LABEL
709+
TYPE TRUETYPE
710+
SIZE 7
711+
END # label
712+
END # class
713+
END
714+
715+
637716
Raster Query
638717
============
639718

‎en/mapfile/layer.txt‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -194,6 +194,9 @@ CONNECTIONOPTIONS
194194
.. index::
195195
triple: LAYER; CONNECTIONTYPE; postgis
196196

197+
.. index::
198+
triple: LAYER; CONNECTIONTYPE; rasterlabel
199+
197200
.. index::
198201
triple: LAYER; CONNECTIONTYPE; sde
199202

@@ -209,7 +212,7 @@ CONNECTIONOPTIONS
209212
.. index::
210213
triple: LAYER; CONNECTIONTYPE; wms
211214

212-
CONNECTIONTYPE [contour|kerneldensity|idw|local|ogr|oraclespatial|plugin|postgis|sde|union|uvraster|wfs|wms]
215+
CONNECTIONTYPE [contour|kerneldensity|idw|local|ogr|oraclespatial|plugin|postgis|rasterlabel|sde|union|uvraster|wfs|wms]
213216
Type of connection. Default is local. See additional documentation for
214217
any other type.
215218

0 commit comments

Comments
 (0)