[MapServer-dev] SCALEBAR "TRANSPARENT" option was supposed to have been removed on 8.0?

[Mateus Medeiros]

Hello!

I've been configuring a bunch of Mapserver 8.0 mapfiles for a WMS server
that was served with GeoServer before. I had almost equivalent
configurations but for the past two days struggled quite a bit to find a
way to have an embedded scalebar box in the corner of the output of a
GetMap request.

Generating the scale itself on top was super easy, but it was always
floating on top of the layers, making it quite hard to read in some cases.

The OUTPUTFORMAT was configured to be a PNG with IMAGEMODE set to RGBA and
TRANSPARENT set to ON. This is because I have a raster layer and a bunch of
vector layers on top of it, but either of them can contain some holes and
the vector styles are mostly outline colors, so I need the GetMap to output
an image that can potentially have transparent areas.

I saw a TRANSPARENT option in the SCALEBAR section in the docs that said
"Should the background color for the scalebar be transparent." which sounds
like just what I needed, but it said "Removed in version 8.0." and "This
flag is now deprecated in favor of declaring transparency within
OUTPUTFORMAT declarations. Default is off.". Unfortunately, setting
transparency to OFF within the OUTPUTFORMAT declaration didn't work because
then the resulting PNG had no transparency at all, including in the layers.

I tried a bunch of different things with IMAGECOLOR and BACKGROUNDCOLOR,
including setting different "alpha" values in the colors ("#FFFFFFDD"), but
it seemed to make no difference. I was already accepting that I would have
to render the box and then the label as separate repeated layers or maybe
overlay that from outside Mapserver, but decided to take a look at the
source code (which was surprisingly easy thankfully because the codebase is
quite well-organized for a project this size made mostly in C) to see why
IMAGECOLOR was not working the way I expected and/or if I could find
anything useful in there about how to achieve what I wanted now that the
TRANSPARENT option was removed.

Then I found the function `msDrawScalebar` in the file `src/mapscale.c`,
and in there I realized that the TRANSPARENT option seemed to still be
accounted (
https://github.com/MapServer/MapServer/blob/24d36f842c243f96eba88ff896db1bf34d8a687a/src/mapscale.c#L240-L248).
To my surprise, after simply setting "TRANSPARENT" to "OFF" in my SCALEBAR
section, lo and behold, it worked flawlessly (I could even control the
opacity by including a color with the alpha part as IMAGECOLOR).

So I went to the documentation repo and tried to find when the "Removed in
8.0" part was added and found the original change referencing RFC #133 (
https://mapserver.org/development/rfc/ms-rfc-133.html). It seems the RFC
explicitly lists the TRANSPARENT option of SCALEBAR as one that needed to
be removed.

For me it seemed like an error in the documentation, as I couldn't easily
find a way to add a non-transparent background box on my SCALEBAR only and
therefore it made more sense to me that the setting still existed instead
of being removed or deprecated. Unfortunately I ended up using all the time
I had to spare trying to identify if the intention was to keep the
TRANSPARENT option and adding the removal comment was a mistake or if the
comment was ok and the option should have been removed, but couldn't reach
a conclusion.

So I think there's either a bug in the documentation or a bug in Mapserver
itself. If indeed the TRANSPARENT option inside the SCALEBAR section was
supposed to be removed, then how would I go about achieving this
non-transparent scalebar box within a transparent output in a GetMap WMS
request? And if it's just the documentation that is wrong, should I just
open a PR correcting that in the Mapserver docs repo? Or are there other
steps I should take before as part of the process of contributing a change
like that in the docs?

Thanks for the help!
Mateus Medeiros
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.osgeo.org/pipermail/mapserver-dev/attachments/20231021/2043d936/attachment.htm>