d.legend: add option to output legend definition as text

[wenzeslaus]

It would be nice if d.legend provides a textual output instead of drawing the legend on the monitor/display. Then the legend definition can be used to create a GRASS-generated legend in some other context such as interactive GUI legend or HTML web site.

Output format should be easily parsable. However, I haven't considered all the possibilities of d.legend output. For category maps, it is seems to be easy, only the category labels can make it harder:

green forest
blue lakes
black roads

The gradient legends are bigger problem. The gradient itself might be simple, e.g. CSS syntax is:

red 10%, green 90%, blue 95%

However, how the color breaks are defined and is this compatible between different environments? And How to define labels which might be placed at different positions than color breaks?

The output should be file or stdout. I'm not sure about option name; it should not be confused with output of an image to the file (which is not possible).

I guess that it is possible to create this functionality using library or maybe even other modules but d.legend already has the functionality to generate legend and it has the interface to control it with all the fine tuning.

This ticket is related to #89 which requests the definition as an input for drawing. Implementing both will cause that d.legend looses its core and becomes just a converter of one legend definition to another. However, I hope that d.legend can handle this loss of identity.

[hamish]

Hi,

see r.colors.out (which does most of you are asking for in this ticket I think) and the approach taken by various grass6 addon modules: r.colors.out_sld (Mapserver), r.colors.out_vtk (Paraview/VisIt), r.out.gmt (also creates the GMT color table), and r.out.gdal.

.. or for something local/custom just parse the $MAPSET/colr/ file directly.

I haven't looked at it in a while, but I imagine the HTML display driver might have some web-friendly code in it too?

Do you have specific plans on how you'd use the output? or is this more a general idea?

As the primary author of the current d.legend I'm not exactly enthusiastic about messing too much with what is already working well. It's a complicated monolith, and I'd appreciate anyone thinking about changing it to please contact me first for advice. (or the change will risk be dropped like the fontscale option soon will be)

I could be sold on renaming it to d.rast.legend, renaming the d.rast.leg script something else, and coming up with a new separate d.vect.legend module to make display driver vector legends similar to what ps.map has. Some parts of the current d.legend could share library functions with d.vect.legend, but since much of it is just drawing rectangles and much of the rest is heuristics, I'm not sure how much is actually reusable.

enhancements to d.vect in taking size, rotation, color, etc. from attribute columns has made much of the thematic legend code redundant AFAIK, so those can be simplified to a wrapper around d.vect and v.univar.

The 747 cockpit approach of 'd.vect --help' is a big reason why I'd favour two separate d.rast.legend and d.vect.legend modules instead of combining two code objects into a common frontend. That distinction would be invisible to the GUI users and not overwhelming to the command line users.

regards, Hamish

[hamish]

ps- since cpt-city (​http://soliton.vm.bytemark.co.uk/pub/cpt-city/) was mentioned, it is worth noting that without clear license we can't distribute anything from the site directly. But users can use as they see fit, and there is already grass6 addon in raster/r.colors.tools/r.cpt2grass for converting CPT color rules into GRASS color rules format.

wrt to an interval editor (and I freely admit my bias in that IMHO much of the use of color intervals for continuous-gradient data is statistically unsound and scientifically counter-productive), for categorical maps anyway an interactive GUI tool making use of ColorBrewer's color maps would be a really nice thing (and it is license friendly ta boot). see mention of it here:

​http://grasswiki.osgeo.org/wiki/GRASS_SoC_Ideas_2013#Symbology_.2F_Cartography

[wenzeslaus]

Replying to hamish:

see r.colors.out (which does most of you are asking for in this ticket I think) and the approach taken by various grass6 addon modules: r.colors.out_sld (Mapserver), r.colors.out_vtk (Paraview/VisIt), r.out.gmt (also creates the GMT color table), and r.out.gdal.

.. or for something local/custom just parse the $MAPSET/colr/ file directly.

I was not testing these but it seems to me that I would end up in re-implementing d.legend, e.g. when putting there labels or when forcing other types of legend than the map would use by default.

I haven't looked at it in a while, but I imagine the HTML display driver might have some web-friendly code in it too?

Last time when I was testing HTML driver I got the impression that it supports only HTML tag map and that even this is not finished. Probably the big issue is what HTML driver is supposed to do anyway? Legend rendered as what in HTML and how this fits together with HTML tag map. But this is different topic.

Do you have specific plans on how you'd use the output? or is this more a general idea?

The motivation was the ability to create legend for HTML pages, or alternatively LaTeX reports. But the idea is general, e.g. font and generally handling of labels could be important for any output which is trying to be something more than an raster image.

As the primary author of the current d.legend I'm not exactly enthusiastic about messing too much with what is already working well. It's a complicated monolith, and I'd appreciate anyone thinking about changing it to please contact me first for advice. (or the change will risk be dropped like the fontscale option soon will be)

Adding there text output is actually trying to avoid the need for bigger changes in d.legend (some super visualizations can be then done outside).

The other things are related to wiki:GSoC/2014, so they should be discussed at mailing list, or the ideas should be updated directly when it is clear.

[hamish]

I was not testing these but it seems to me that I would end up in re-implementing d.legend,

do you mean merging those GMT,Mapserver,VTK output tasks into d.legend? or rewriting a new d.legend from scratch?

d.legend is for drawing objects on the screen. r.colors.out & friends are for exporting color tables in ascii or other software's color table format, r.what.color and 'r.what -r' are two more modules that can help with that.

the closest a d.* module conceptually comes to providing data output not display output is d.info or the interactive d.what.* modules.

color table != legend rendering, and color table has its own management tools already.

e.g. when putting there labels

? I don't understand, d.legend already supports labels for categorical legends.

the one thing it doesn't do currently is make adding data units text from r.support easy (ps.map can do that), so you have to use d.text instead. the code for that is easy, the hard part (and why I haven't done it yet) is deciding about the best placement.

or when forcing other types of legend than the map would use by default.

can you provide an example? I'm not sure what you mean.

The main part of the HTML driver is that it creates a html page with mouse-over hot-link zones, a less popular web feature now than back in the 90s. I was just wondering aloud if it also had some rrr:ggg:bbb to #aabbcc conversion code in it, but that's trivial to reimplement so never mind.

Do you have specific plans on how you'd use the output? or is this more a general idea?

The motivation was the ability to create legend for HTML pages, or alternatively LaTeX reports.

so SVG and PostScript output, not rasterized output? (doing it as a small PNG file is already possible) Don't the d.* + PNG/Cairo driver and ps.map + eps2{foo} already allow this? Some examples would help as I still don't understand what is wanted.

But the idea is general, e.g. font and generally handling of labels could be important for any output which is trying to be something more than an raster image.

Do you mean arbitrary labels (d.labels and d.text) or the text which is drawn along with the legend itself? We already have some controls for that via d.font and enviro variables like GRASS_FONTSIZE and GRASS_FONT. Things that don't respect those arguably should, and wrapper scripts or custom GUI menus would allow them to be used from the GUI. What specifically is missing?

n.b. putting those enviro variables in the library fns is problematic as you may want to do something complicated with d.text or d.grid using multiple font sizes or styles within the same module run.

regards, Hamish

[neteler]

Replying to hamish:

ps- since cpt-city (​http://soliton.vm.bytemark.co.uk/pub/cpt-city/) was mentioned, it is worth noting that without clear license we can't distribute anything from the site directly.

Perhaps take from QGIS then which is GPL 2:

​https://github.com/qgis/QGIS/tree/master/resources/cpt-city-qgis-min

[hamish]

Replying to neteler:

Replying to hamish:

ps- since cpt-city (​http://soliton.vm.bytemark.co.uk/pub/cpt-city/) was mentioned, it is worth noting that without clear license we can't distribute anything from the site directly.

Perhaps take from QGIS then which is GPL 2:

​https://github.com/qgis/QGIS/tree/master/resources/cpt-city-qgis-min

feel free to audit all the COPYING.xml files within.. :)

for the color tables there which have a GPL2-compatible license and are nice enough to keep, I suggest to put into addons, see existing ones in:

​https://trac.osgeo.org/grass/browser/grass-addons/grass6/raster/r.colors.tools/palettes/

those are easy to use with 'r.colors rules=', I just keep a symlink to the checkout'd palettes dir at an easy to reach place.

otherwise, if the license isn't clear or it's just another minor derivation of "red-blue #17", the user can always use r.cpt2grass themselves.

Hamish

[hamish]

the functionality asked for in this wish, as I understand it, seems already covered by r.colors.out and r.category, amongst others.

ok to close it?

Hamish