diff --git a/conf.py b/conf.py index 2911429db52..ff9d4ab6269 100644 --- a/conf.py +++ b/conf.py @@ -425,7 +425,7 @@ class WKTLexer(RegexLexer): r'OPACITY|OUTLINECOLOR|OUTLINEWIDTH|OUTPUTFORMAT|OVERLAYBACKGROUNDCOLOR|' r'OVERLAYCOLOR|OVERLAYMAXSIZE|OVERLAYMINSIZE|OVERLAYOUTLINECOLOR|' r'OVERLAYSIZE|OVERLAYSYMBOL|PARTIALS|PATTERN|POINTS|POLAROFFSET|POSITION|POSTLABELCACHE|' - r'PRIORITY|PROCESSING|PROJECTION|QUERYFORMAT|QUERYMAP|REFERENCE|REGION|' + r'PRIORITY|PROCESSING|PROJECTION|QUERYFORMAT|QUERYMAP|RASTERLABEL|REFERENCE|REGION|' r'RELATIVETO|REQUIRES|RESOLUTION|SCALE|SCALEDENOM|SCALETOKEN|SHADOWCOLOR|SHADOWSIZE|' r'SHAPEPATH|SIZE|SIZEUNITS|STATUS|STYLE|STYLEITEM|SYMBOL|SYMBOLSCALE|' r'SYMBOLSCALEDENOM|SYMBOLSET|TABLE|TEMPLATE|TEMPLATEPATTERN|TEXT|' diff --git a/en/development/rfc/index.txt b/en/development/rfc/index.txt index 14ce982bfe0..6f2912319b8 100644 --- a/en/development/rfc/index.txt +++ b/en/development/rfc/index.txt @@ -149,4 +149,5 @@ the project. ms-rfc-135 ms-rfc-136 ms-rfc-137 - ms-rfc-138 \ No newline at end of file + ms-rfc-138 + ms-rfc-139 diff --git a/en/development/rfc/ms-rfc-139.txt b/en/development/rfc/ms-rfc-139.txt new file mode 100644 index 00000000000..3714232940a --- /dev/null +++ b/en/development/rfc/ms-rfc-139.txt @@ -0,0 +1,147 @@ +.. _rfc139: + +========================================================================= +MS RFC 139: Raster labeling (CONNECTIONTYPE RASTERLABEL) +========================================================================= + +:Date: 2024/08/14 +:Author: Even Rouault +:Contact: even.rouault at spatialys.com +:Status: Adopted +:Version: MapServer 8.4 + +1. Overview +----------- + +This is a proposal to add the ability to render labels from raster pixel values, +as an alternative or complement to other typical raster rendering (grayscale, +classification, etc.). Typical applications are for temperature, wind, humidity, +slopes, altitude, noise, pollution, etc. + +Visual example (rendered with MapServer): + + .. image:: ../../images/rasterlabel.png + +2. The proposed solution +------------------------ + +This RFC proposes the addition of a new type of layer in MapServer: +CONNECTIONTYPE RASTERLABEL. +The code is strongly based on the UVRASTER capabilities, but will be kept separate +as some likely potential evolutions of UVRASTER (such as modifying u,v values +during reprojection operations) will make both implementation diverge. + +The new type is a hybrid layer, which has a raster data source as input and +vector features as output. Only the point representation of those +vector features will be supported. Values at nodata will be ignored. + +Since the data source is a raster, all raster processing options can be +used (e.g. RESAMPLE). A default value of RESAMPLE=AVERAGE will be used, if it +is not explicitly defined. + +To render a vector field layer, we need to define a layer in the mapfile +with the following options: + + * Set the layer TYPE to POINT. + * Set CONNECTIONTYPE to RASTERLABEL. + * Set the DATA to the raster file. + * If the raster file has more than one bands, add a PROCESSING "BANDS=" option + * Specify a CLASS with a LABEL object to label the points, using the [value] + attribute binding. + +Optional "PROCESSING" settings: + + * BANDS=: Specify the band to label. Not needed if there is a single band. + * LABEL_SPACING=: The spacing is simply the distance, in pixels, between points + to be displayed in the vector field. Default is 32. + * RESAMPLE=NEAREST/AVERAGE/BILINEAR: Defaults to AVERAGE. + * ALLOW_OVERSAMPLE=YES/NO: Whether it is allowed to oversample the raster at + a resolution higher than its nominal resolution. Default is NO, meaning that + when zooming in beyond the nominal resolution of the raster, at most one + point will be generated for each source pixel. This gives to the user a sense + of the resolution of the data it displays. + +The UVRASTER layer has one attribute bindings that can be used in the layer +definition and/or class expressions: + + * [value]: the raw raster value + +Example of a layer definition: + +:: + + LAYER + NAME "temperature" + TYPE POINT + CONNECTIONTYPE RASTERLABEL + PROJECTION + "init=epsg:4326" + END + DATA data/temperature.tif + # PROCESSING "BANDS=1" + # PROCESSING "LABEL_SPACING=32" + # PROCESSING "RESAMPLE=AVERAGE" + # PROCESSING "ALLOW_OVERSAMPLE=NO" + CLASS + TEXT (tostring([value],"%.1f")+"°") + LABEL + TYPE TRUETYPE + SIZE 7 + END # label + END # class + END + + +3. Implementation Details +------------------------- + +Internally, a RASTERLABEL layer will have its own renderer/driver code. It's a +hybrid layer because it reads the raster source as a normal raster +layer does, but all other functions behave like a vector layer. The +layer can be drawn as a normal point layer using whichShape, GetShape +etc. + +Basic internal draw process of a RASTERLABEL layer: + + 1. whichShape() is called: the raster data source is read using the + internal GDAL functions, resample and all other raster options are applied + and the pixels result is stored in the internal layer structure. + + 2. getShape() is called: loop through the raster pixels and returns a + shapeObj (Point) created with the pixel location. + + 3. MapServer draws its point feature as any other vector layer. + +3.1 Files affected +------------------ + +The following files will be modified/created by this RFC: + +:: + + mapserver.h/mapfile.c (Connection type RASTERLABEL support in the mapfile) + maprasterlabel.cpp (new file for the RASTERLABEL renderer) + 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) + maplayer.c (new layer type handling, virtual tables init etc.) + maplexer.l (add additional RASTERLABEL keyword) + +3.2 MapScript +------------- + +No issue for any MapScript bindings. The RASTERLABEL layer is handled/rendered internally as +any other layer.. + +3.4 Backwards Compatibility Issues +---------------------------------- + +This change provides a new functionality with no backwards compatibility issues being considered. + +4. Candidate implementation +--------------------------- + + * https://github.com/MapServer/MapServer/pull/7135 + +5. Voting history +----------------- + ++1 from PSC members EvenR, TomK, JukkaR, SethG, MikeS, DanielM, JeromeB, SteveL, JeffM diff --git a/en/images/rasterlabel.png b/en/images/rasterlabel.png new file mode 100644 index 00000000000..94ac7165be1 Binary files /dev/null and b/en/images/rasterlabel.png differ diff --git a/en/input/raster.txt b/en/input/raster.txt index 9746c56f6bd..bf2f18172f5 100644 --- a/en/input/raster.txt +++ b/en/input/raster.txt @@ -634,6 +634,85 @@ are supported in MapServer 4.0 and newer. .. index:: pair: Raster; Query +.. _rasterlabel: + +Raster Labelling +================ + +.. versionadded:: 8.4 + +This is the ability to render labels from raster pixel values, +as an alternative or complement to other typical raster rendering (grayscale, +classification, etc.). Typical applications are for temperature, wind, humidity, +slopes, altitude, noise, pollution, etc. + +Visual example: + + .. image:: ../images/rasterlabel.png + +LAYER Description +----------------- + +A raster labelling layer :ref:`LAYER` is a hybrid layer, which has a raster data +source as input and vector features as output. The output features +are represented as points. Queries are not supported. + +Since the data source is a raster, all raster processing options can +be used (e.g. RESAMPLE). RESAMPLE=AVERAGE generally gives a good +result, and the default. This can be overridden by explicitly +specifying the type of resampling. + +Vector field layers are of `TYPE` `point`, and have `CONNECTIONTYPE` +`rasterlabel`. The raster data set is specified in `DATA`. The band to label +is set through the `PROCESSING` `BANDS` option. + +LAYER Attributes +---------------- + +The rasterlabel connection type offers the following attribute: + +* [value]: the raw value + +Optional `PROCESSING` Settings +------------------------------ + +* `BANDS=`: Specify the band to label. Not needed if there is a single band. +* `LABEL_SPACING=`: The spacing is simply the distance, in pixels, between points + to be displayed in the vector field. Default is 32. +* `RESAMPLE=NEAREST/AVERAGE/BILINEAR`: Defaults to AVERAGE. +* `ALLOW_OVERSAMPLE=YES/NO`: Whether it is allowed to oversample the raster at + a resolution higher than its nominal resolution. Default is NO, meaning that + when zooming in beyond the nominal resolution of the raster, at most one + point will be generated for each source pixel. This gives to the user a sense + of the resolution of the data it displays. + +Example of a layer definition +----------------------------- + +.. code-block:: mapfile + + LAYER + NAME "temperature" + TYPE POINT + CONNECTIONTYPE RASTERLABEL + PROJECTION + "init=epsg:4326" + END + DATA "data/temperature.tif" + # PROCESSING "BANDS=1" + # PROCESSING "LABEL_SPACING=32" + # PROCESSING "RESAMPLE=AVERAGE" + # PROCESSING "ALLOW_OVERSAMPLE=NO" + CLASS + TEXT (tostring([value],"%.1f")+"°") + LABEL + TYPE TRUETYPE + SIZE 7 + END # label + END # class + END + + Raster Query ============ diff --git a/en/mapfile/layer.txt b/en/mapfile/layer.txt index 8b0b82f3854..c2db1f55001 100644 --- a/en/mapfile/layer.txt +++ b/en/mapfile/layer.txt @@ -194,6 +194,9 @@ CONNECTIONOPTIONS .. index:: triple: LAYER; CONNECTIONTYPE; postgis +.. index:: + triple: LAYER; CONNECTIONTYPE; rasterlabel + .. index:: triple: LAYER; CONNECTIONTYPE; sde @@ -209,7 +212,7 @@ CONNECTIONOPTIONS .. index:: triple: LAYER; CONNECTIONTYPE; wms -CONNECTIONTYPE [contour|kerneldensity|idw|local|ogr|oraclespatial|plugin|postgis|sde|union|uvraster|wfs|wms] +CONNECTIONTYPE [contour|kerneldensity|idw|local|ogr|oraclespatial|plugin|postgis|rasterlabel|sde|union|uvraster|wfs|wms] Type of connection. Default is local. See additional documentation for any other type.