[Geoserver-devel] Raster Legend labeling behaviour

Wayne_Fang · July 24, 2008, 11:22pm

I was looking into the Legend feature and came across some behaviour that strikes me as odd. According to the GetLegendGraphic Improvements document (http://geoserver.org/display/GEOSDOC/GetLegendGraphic+Improvements) in section 5:

If there’s just one Rule for a legend, no label is supplied
If there is more than one Rule for a legend, labels are supplied
I’m not clear what the use case is for a legend with a single item with no label attached to it; it seems to defeat the purpose of a legend. There’s a forceLabels option to force labels on or off, but I would think the following behaviour is more intuitive:
Draw labels by default.
If forceLabels is set to ‘on’, then draw labels.
If forceLabels is set to ‘off’, then don’t draw labels.

Can somebody explain the reasoning behind this to me? If not, I’d like to change it.

Thanks,
Wayne

···

-- 
Refractions Research
Suite 300 - 1207 Douglas St
Victoria, BC, V8W 2E7, Canada
ph: (250) 383-3022
fax:(250) 383-2140

Justin_Deoliveira · July 25, 2008, 1:42am

Hi Wayne,

Your reasoning makes sense. I believe these exact semantics were implemented because that is the way MapServer does its legend graphic generation.

I would not be against including labels by default. It might be good to see what some of the other folks on this list think.

-Justin

Wayne Fang wrote:

I was looking into the Legend feature and came across some behaviour that strikes me as odd. According to the GetLegendGraphic Improvements document (http://geoserver.org/display/GEOSDOC/GetLegendGraphic+Improvements) in section 5:

    * If there's just one Rule for a legend, no label is supplied
    * If there is more than one Rule for a legend, labels are supplied

I'm not clear what the use case is for a legend with a single item with no label attached to it; it seems to defeat the purpose of a legend. There's a forceLabels option to force labels on or off, but I would think the following behaviour is more intuitive:

    * Draw labels by default.
    * If forceLabels is set to 'on', then draw labels.
    * If forceLabels is set to 'off', then don't draw labels.

Can somebody explain the reasoning behind this to me? If not, I'd like to change it.

Thanks,
Wayne

--
Refractions Research
Suite 300 - 1207 Douglas St
Victoria, BC, V8W 2E7, Canada
ph: (250) 383-3022
fax:(250) 383-2140

!DSPAM:4007,48890ed616885210051143!

------------------------------------------------------------------------

-------------------------------------------------------------------------
This SF.Net email is sponsored by the Moblin Your Move Developer's challenge
Build the coolest Linux based applications with Moblin SDK & win great prizes
Grand prize is a trip for two to an Open Source event anywhere in the world
http://moblin-contest.org/redirect.php?banner_id=100&url=/

!DSPAM:4007,48890ed616885210051143!

------------------------------------------------------------------------

_______________________________________________
Geoserver-devel mailing list
Geoserver-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/geoserver-devel

!DSPAM:4007,48890ed616885210051143!

--
Justin Deoliveira
The Open Planning Project
jdeolive@anonymised.com

jive · July 26, 2008, 12:54am

Can I ask if this is legend graphics generated from the SLD definition - ie what is returned by the get legend graphics operation? Or is this something specific to KML generation?

There is a bit of a conflict of meaning here on the legend graphic operation side:
- A client like uDig expects to see some kind of glyph, symbology or example indicating what the layer looks like; the layer already has a nice human readable name - so there is no reason to include that in the returned image.

My understanding is map server starts to try and show a massive legend graphic when the SLD has several rules; on the assumption that the rules are defining categories of data (all of which are displayed in a single layer).

We have gone to some trouble in udig to sort out the confusion when dealing with mapserver; trying to figure out a good area of the produced image to sample etc...

Jody

Justin Deoliveira wrote:

Hi Wayne,

Your reasoning makes sense. I believe these exact semantics were implemented because that is the way MapServer does its legend graphic generation.

I would not be against including labels by default. It might be good to see what some of the other folks on this list think.

-Justin

Gabriel_Roldan2 · July 26, 2008, 1:22am

Hi Wayne,

off the top of my head, I guess the thing is more or less like this:

The GetLegendGraphic operation is meant to produce a "representative enough"
graphic for the styling of a layer OR a rule, depending on the RULE parameter
being present or not. It is not meant to produce a full legend for the whole
map, as you can do with, say, ArcIMS.
Now, the spec does not mention those "representative graphics" including rule
names as labels. Moreover, it suggests (if it does not explicitly tell) that
no label shall be produced, since the client has access to the style
information and thus the rule titles are available to it. Hence the client
could compose the legend as it likes getting the graphic from the server and
the rule titles from the style document.

But things are not actually that easy: geoserver does not implement the
GetLegend operation, it is optional, and most clients can't manage the
complexity of grabbing the raw style in xml, figuring out the rule names,
deciding when a given rule is visible or not depending on the min/max scale
settings, and making sure exactly the same scale is computed by it and the
server to avoid confusing legends.

So in practice almost every client application just makes a single per layer
GetLegendGraphic call instead of one per applicable rule. This means the
server, to return a "representative enough" legend graphic needs to compute
which rules are applicable and stack a graphic of each one in the returned
image. That is also why the WIDTH and HEIGHT arguments for the
GetLegendGraphic operations are just _hints_ about the desired dimension of
the returned graphic, but the server is free to return a different sized
image (one way of doing that is respecting the WIDTH argument and stacking as
many images of the required HEIGHT as rules apply)

All in all, whether to return the label at the right of the image for each
rule or not is an open question, the spec does not mandate anything about it,
and hence the custom parameters to force the labels on or off. One can even
say I want the labels at the left of the image because that's the natural way
in my locale. We can't currently do that, but is equally reasonable.

Now, whether labels should be on by default or not is still open to
discussion, and there gonna be arguments in favor and against, equally valid.
Which, the the sake of flexibility, and given the SLD 1.0 spec is closed, we
could only add more custom parameters and default values for users to
configure the legends as they better fit them. Just be sure there won't be a
default configuration that fits all client needs.

Sorry for the rant, hope it helps clarify a bit the situation though.

Cheers,

Gabriel

On Thursday 24 July 2008 10:42:27 pm Justin Deoliveira wrote:

Hi Wayne,

Your reasoning makes sense. I believe these exact semantics were
implemented because that is the way MapServer does its legend graphic
generation.

I would not be against including labels by default. It might be good to
see what some of the other folks on this list think.

-Justin

Wayne Fang wrote:
> I was looking into the Legend feature and came across some behaviour
> that strikes me as odd. According to the GetLegendGraphic Improvements
> document
> (http://geoserver.org/display/GEOSDOC/GetLegendGraphic+Improvements) in
> section 5:
>
> * If there's just one Rule for a legend, no label is supplied
> * If there is more than one Rule for a legend, labels are supplied
>
> I'm not clear what the use case is for a legend with a single item with
> no label attached to it; it seems to defeat the purpose of a legend.
> There's a forceLabels option to force labels on or off, but I would
> think the following behaviour is more intuitive:
>
> * Draw labels by default.
> * If forceLabels is set to 'on', then draw labels.
> * If forceLabels is set to 'off', then don't draw labels.
>
> Can somebody explain the reasoning behind this to me? If not, I'd like
> to change it.
>
> Thanks,
> Wayne
>
> --
> Refractions Research
> Suite 300 - 1207 Douglas St
> Victoria, BC, V8W 2E7, Canada
> ph: (250) 383-3022
> fax:(250) 383-2140
>
>
>
>
> ------------------------------------------------------------------------
>
> -------------------------------------------------------------------------
> This SF.Net email is sponsored by the Moblin Your Move Developer's
> challenge Build the coolest Linux based applications with Moblin SDK &
> win great prizes Grand prize is a trip for two to an Open Source event
> anywhere in the world
> http://moblin-contest.org/redirect.php?banner_id=100&url=/
>
> !DSPAM:4007,48890ed616885210051143!
>
>
> ------------------------------------------------------------------------
>
> _______________________________________________
> Geoserver-devel mailing list
> Geoserver-devel@lists.sourceforge.net
> https://lists.sourceforge.net/lists/listinfo/geoserver-devel
>
>
> !DSPAM:4007,48890ed616885210051143!

Wayne_Fang · July 28, 2008, 5:01pm

Hi Gabriel,

Thanks for the explanation. The main issue, though, is that behaviour is inconsistent between the one and many cases. It wouldn't matter if the labels are on or off by default, as long as it was the same for all cases. We have a client thinking this is a bug (not a 'feature' ).

Thanks,
Wayne

Gabriel Roldán wrote:

Hi Wayne,

off the top of my head, I guess the thing is more or less like this:

The GetLegendGraphic operation is meant to produce a "representative enough" graphic for the styling of a layer OR a rule, depending on the RULE parameter being present or not. It is not meant to produce a full legend for the whole map, as you can do with, say, ArcIMS.
Now, the spec does not mention those "representative graphics" including rule names as labels. Moreover, it suggests (if it does not explicitly tell) that no label shall be produced, since the client has access to the style information and thus the rule titles are available to it. Hence the client could compose the legend as it likes getting the graphic from the server and the rule titles from the style document.

But things are not actually that easy: geoserver does not implement the GetLegend operation, it is optional, and most clients can't manage the complexity of grabbing the raw style in xml, figuring out the rule names, deciding when a given rule is visible or not depending on the min/max scale settings, and making sure exactly the same scale is computed by it and the server to avoid confusing legends.

So in practice almost every client application just makes a single per layer GetLegendGraphic call instead of one per applicable rule. This means the server, to return a "representative enough" legend graphic needs to compute which rules are applicable and stack a graphic of each one in the returned image. That is also why the WIDTH and HEIGHT arguments for the GetLegendGraphic operations are just _hints_ about the desired dimension of the returned graphic, but the server is free to return a different sized image (one way of doing that is respecting the WIDTH argument and stacking as many images of the required HEIGHT as rules apply)

All in all, whether to return the label at the right of the image for each rule or not is an open question, the spec does not mandate anything about it, and hence the custom parameters to force the labels on or off. One can even say I want the labels at the left of the image because that's the natural way in my locale. We can't currently do that, but is equally reasonable.

Now, whether labels should be on by default or not is still open to discussion, and there gonna be arguments in favor and against, equally valid. Which, the the sake of flexibility, and given the SLD 1.0 spec is closed, we could only add more custom parameters and default values for users to configure the legends as they better fit them. Just be sure there won't be a default configuration that fits all client needs.

Sorry for the rant, hope it helps clarify a bit the situation though.

Cheers,

Gabriel

--
Refractions Research
Suite 300 - 1207 Douglas St
Victoria, BC, V8W 2E7, Canada
ph: (250) 383-3022
fax:(250) 383-2140

Andrea_Aime3 · July 29, 2008, 7:58am

Wayne Fang ha scritto:

Hi Gabriel,

Thanks for the explanation. The main issue, though, is that behaviour is inconsistent between the one and many cases. It wouldn't matter if the labels are on or off by default, as long as it was the same for all cases. We have a client thinking this is a bug (not a 'feature' ).

Mumble, the first silly question I have is why the client cannot just
add the parameter to force labels on and off and get over it

More seriously, that behaviour was there before me joining GeoServer crew and I don't know why it was setup, but I'm usually weary of
dismissing past decisions just because I don't understand them.
Maybe it has something to do with the way uDig uses the GetLegendGraphic
call to build the layer icons (if any)?

Jody, Gabriel, Chris, do you know any reason why this setup the way
it is?

Thinking about it, the call is indeed thought to allow a client
build its own legend, but without the presence of a RULE parameter
and with multiple rules, not having labels would make the result
unreadable.

So what about
* avoiding the usage of labels if the RULE parameter has been provided
* always adding labels otherwise

If the client is able to actually build its own legend, it should
know about the rules. If the client is dumber, it's probably expecting
an ArcIMS like behaviour... no?

I know we're introducing a different sort of magic, the trouble
here are the client softwares that only work with the standard
part of the protocol, we should have a decent behaviour for those.
Everyone else making up a custom client or using a customizable
one can use the vendor parameters we came up with and get what
they want anyways.

Cheers
Andrea

Wayne_Fang · August 5, 2008, 5:28pm

Talking about the legend_options and forceLabels, does it work for anybody? I've tried using it, but it seems to be getting lost before the GetLegendGraphic request. I just want to confirm it is broken before I submit a patch for it.

http://localhost:8080/geoserver/wms?service=WMS&request=GetMap&format=application/vnd.google-earth.kml+XML&width=1024&height=1024&srs=EPSG:4326&layers=topp:states&styles=population&bbox=-180,-90,180,90&format_options=LEGEND:true;KMSCORE:0;KMATTR:true;&legend_options=forceLabels:off

Thanks,
Wayne

--
Refractions Research
Suite 300 - 1207 Douglas St
Victoria, BC, V8W 2E7, Canada
ph: (250) 383-3022
fax:(250) 383-2140

Wayne_Fang · August 6, 2008, 11:57pm

After investigating this further, I was going to create an issue in jira proposing to change the way KMLLegendTransformer works. Currently, it relies on a GetLegendGraphic request to produce a full-fledged legend, despite that being contrary to its spec. The KMLLegendTransformer should figure out what rules apply and create the “representative enough” legend graphic and produce appropriate KML for Google Earth to display. As it is, it generates a GetLegendGraphic request in KML.

Feedback is more than welcome. A coworker is looking into getting possibly funding for this.

Thanks,
Wayne

Wayne Fang wrote:

···

-- 
Refractions Research
Suite 300 - 1207 Douglas St
Victoria, BC, V8W 2E7, Canada
ph: (250) 383-3022
fax:(250) 383-2140

Andrea_Aime3 · August 7, 2008, 8:25am

Wayne Fang ha scritto:

After investigating this further, I was going to create an issue in jira proposing to change the way KMLLegendTransformer works. Currently, it relies on a GetLegendGraphic request to produce a full-fledged legend, despite that being contrary to its spec. The KMLLegendTransformer should figure out what rules apply and create the "representative enough" legend graphic and produce appropriate KML for Google Earth to display. As it is, it generates a GetLegendGraphic request in KML.

Yeah, that was the easiest way to get a legend out of our existing code.
How would you create one in KML? Moreover, the way KML is done means
we switch from raster rendering to KML rendering, probably the legend
should do the same, since the KML rendering is similar, but not equal,
to the raster one?

Cheers
Andrea

Wayne_Fang · August 7, 2008, 4:21pm

Andrea Aime wrote:

Wayne Fang ha scritto:

After investigating this further, I was going to create an issue in jira proposing to change the way KMLLegendTransformer works. Currently, it relies on a GetLegendGraphic request to produce a full-fledged legend, despite that being contrary to its spec. The KMLLegendTransformer should figure out what rules apply and create the "representative enough" legend graphic and produce appropriate KML for Google Earth to display. As it is, it generates a GetLegendGraphic request in KML.

Yeah, that was the easiest way to get a legend out of our existing code.
How would you create one in KML? Moreover, the way KML is done means
we switch from raster rendering to KML rendering, probably the legend
should do the same, since the KML rendering is similar, but not equal,
to the raster one?
Cheers
Andrea

Perhaps I should have said "create an issue to document that this change should be done". I won't be able to move this forward without getting the funding to do it.

As for how it's done, that hasn't been thought through yet. I wonder if we could return an inline png in the kml/kmz, instead of a GLG request in KML that then gets the legend graphic? The KMLLegendTransformer would effectively make internal requests to get the icons for each applicable rule, or maybe just make a call to the appropriate *LegendGraphicProducer, and serve that up?

Cheers,
Wayne

--
Refractions Research
Suite 300 - 1207 Douglas St
Victoria, BC, V8W 2E7, Canada
ph: (250) 383-3022
fax:(250) 383-2140

Andrea_Aime3 · August 7, 2008, 4:28pm

Wayne Fang ha scritto:
...

Perhaps I should have said "create an issue to document that this change should be done". I won't be able to move this forward without getting the funding to do it.

As for how it's done, that hasn't been thought through yet. I wonder if we could return an inline png in the kml/kmz, instead of a GLG request in KML that then gets the legend graphic?

How would this improve things?

The KMLLegendTransformer would effectively make internal requests to get the icons for each applicable rule, or maybe just make a call to the appropriate *LegendGraphicProducer, and serve that up?

But... I don't understad. The legend producer would just produce
a legend graphics like today, unless you write one that's customized
for KML. What am I missing?

Cheers
Andrea

Wayne_Fang · August 7, 2008, 6:00pm

Andrea Aime wrote:

Wayne Fang ha scritto:

As for how it's done, that hasn't been thought through yet. I wonder if we could return an inline png in the kml/kmz, instead of a GLG request in KML that then gets the legend graphic?

How would this improve things?

The main thing is that, for KML at least, it would be using GetLegendGraphic (GLG) according to its spec. It would also be one less client request.

The KMLLegendTransformer would effectively make internal requests to get the icons for each applicable rule, or maybe just make a call to the appropriate *LegendGraphicProducer, and serve that up?

But... I don't understad. The legend producer would just produce
a legend graphics like today, unless you write one that's customized
for KML. What am I missing?

The idea was to leave the existing behaviour for other requests for now, in case other clients are depending on the current legend behaviour. The KMLLegendTransformer would be beefed up so that it created the full legend, complete with labels. The legend would then be stylable in KML. So yes, this will likely replicate some of the functionality of the GLG processor. But the aim will be to eventually scale back the GLG processor to conform to the spec (returning a single representative icon with no labels).

Cheers,
Wayne

--
Refractions Research
Suite 300 - 1207 Douglas St
Victoria, BC, V8W 2E7, Canada
ph: (250) 383-3022
fax:(250) 383-2140