Add 3D raster (volume) support to d.legend

[wenzeslaus]

It is not possible to show a legend for 3D raster map.

I have a patch to add support for 3D rasters into d.legend module. It is created in the same way as r3.colors, i.e. main.c is turned to the normal C file and there are two new C files with int main functions which calls the same function but with different parameter.

I used the names d.legend and d.rast3d.legend.

I'm not sure about non-floating point 3D rasters. There are no integers but categories are supported? There is actually no documentation about data types in 3D (see ​user and ​programming manuals).

The documentation and some comments are still missing but I will add them. Some basic test would be nice too. The wxGUI support for this will be added later.

To test the legend use:

# generate data
r3.mapcalc "test_1 = "
# set some color table
r3.colors map=test_1 color=elevation
# use non-gui monitor
d.mon png out=legend.png
# try some legends
d.rast3.legend map=test_1 at=10,50,10,20
d.rast3.legend map=test_1 at=10,50,30,40 use=10,20,50

[wenzeslaus]

Patch to add support of 3D raster into d.legend (d.rast3.legend) module

[wenzeslaus]

The name of 3D raster legend module is d.rast3.legend not d.rast3d.legend. I misspelled the name in the ticket because I'm really tired of all rast3/g3dcell/raster3d/...

[hamish]

Hi,

I don't think this needs a separate module, rather we could add a -3 flag to the main d.legend module to tell it that it should expect a 3d raster for the map name. Or if the parser can't be convinced to deal with that, add a new rast3d= option and check that one or the other has been given (sort of like g.copy et al.). --> At some point I'd like to have d.legend support vector maps and arbitrary color rules text files too.

A simple/quick wrapper script way for a linear color scale is to make a dummy 10x10 cell raster map with both the max and min values from r3.info put in to some cells with r.mapcalc. Then use d.legend with the dummy 2D raster map as the input not the real 3D raster cube. fwiw this is why the v.colors shell script for G6 allows to make a dummy raster map with the placeholder= option.

see also the r.stack addon module for G6, which was written to allow 'r.colors -e' to work with a series of input maps, in the original case a 3D raster cube split up into individual depth horizons, but a constant colorbar for all steps in a time series is another common reason to use it.

​http://grasswiki.osgeo.org/wiki/AddOns/GRASS_6#r.stack

regards, Hamish

ps- trac wants keywords to be comma separated

[hamish]

by the way, was the basis for this an idea to show the result of d.legend on top of the wxgui 3D nviz display? or to be able to screenshot-crop and paste later for a hardcopy?

[huhabla]

Replying to hamish:

Hi,

I don't think this needs a separate module, rather we could add a -3 flag to the main d.legend module to tell it that it should expect a 3d raster for the map name. Or if the parser can't be convinced to deal with that, add a new rast3d= option and check that one or the other has been given (sort of like g.copy et al.). --> At some point I'd like to have d.legend support vector maps and arbitrary color rules text files too.

+1 for a single d.legend module with rast3d=, vect= and colrule= options.

Btw: The color rules for raster maps can also be set from a single 3D raster map using r.colors.

[wenzeslaus]

version of d.legend with 3D raster support, compatibility broken, GUI fixed

[wenzeslaus]

New patch for G7:d.legend added. It adds new option rast3d to d.legend and renames option map to rast. Tested with:

• d.mon png
• d.mon wx0
• g.gui (2D and 3D)

Patch breaks API (backwards compatibility), so I fixed also wxGUI and d.rast.leg (which I didn't test). wxGUI 2D works the same way as before including the case of wrong legend parameters (both dialog and legend disappears but it is possible to show dialog by re-hiding and re-showing legend). wxGUI 3D works also in the same way (wrong parameters cause segmentation fault). No explicit support for 3D raster added to GUI, this would be nice in the future.

GUI section with rast and rast3d is called Input, is that correct?

Please review the patch.

 > d.legend --help
Description:
 Displays a legend for a raster or 3D raster map.


Usage:
 d.legend [-vcnsfs] [rast=name] [rast3d=name] [color=name]
   [lines=value] [thin=value] [labelnum=value] [at=bottom,top,left,right]
   [use=value[,value,...]] [range=min,max] [font=string] [fontscale=value]
   [path=name] [charset=string] [--help] [--verbose] [--quiet]
...
Parameters:
       rast   Name of raster map
               Either this option or rast3d option must be specified
     rast3d   Name of 3D raster map
               Either this option or rast option must be specified
...

I did not tested new legend with other GUI tools. User documentation not updated yet. To test basic case, use:

# generate data
r3.mapcalc "test_2 = row()"

# set some color table
r3.colors map=test_2 color=elevation

# use non-gui monitor
d.mon png out=legend_3d.png

# try some legends
d.legend rast3d=test_2 at=10,50,10,20
d.legend rast3d=test_2 at=10,50,30,40 use=10,20,50

Question: How to get nice error message for 3D raster?

 > d.legend rast=xxxx
ERROR: Raster map <xxxx> not found
 > d.legend rast3d=xxxx
WARNING: Unable to open range file for [xxxx in ]
WARNING: color support for [xxxx] in mapset [] missing
ERROR: Color file for <xxxx> not available

[wenzeslaus]

Please review the patch, interface and tests here and/or test the new functionality (you can use GUI if you want). I would like to apply the patch soon and not to risk that some changes in GUI will break it.

Other issue is that it is API break, since I'm replacing map by rast. This would be concern if this change would not be applied also to release branch. Some compatibility options would be possible too if we don't want to apply this to release branch. (This wouldn't be a problem for the previous patch which adds completely new module.)

[hamish]

Replying to wenzeslaus:

Please review the patch, interface and tests here and/or test the new functionality (you can use GUI if you want). I would like to apply the patch soon and not to risk that some changes in GUI will break it.

Hi,

it's pretty good, I'll look at merging it ASAP.

Other issue is that it is API break, since I'm replacing map by rast. This would be concern if this change would not be applied also to release branch.

it's only for grass 7 which isn't released yet, so no problem to change the module options as long as a grep is done on scripts/, gui/, and grass-addons/ + html docs to make sure everything else is in sync. The module command line options for G7 are only hard frozen the day 7.0.0 ships. And then existing options will be completely frozen for many many years...

thanks, Hamish

[hamish]

ok, done in trunk, try >= r60104.

I reworked most of the C code in the patch, but the python stuff was applied verbatim.

some minor feedback/notes:

• changed enum defines to be less like official ones in include/*.h. Also moved them into local_proto.h.

• to help code readability used TRUE and FALSE for boolean ints. (defined in gis.h)

• no need to use {curly} brackets if the statement which follows is a short one liner.

• if $(RASTER3DLIB) is added to the Makefile, $(RASTER3DDEP) needs to be added too.

• still need to figure out the trick to launch the GUI when no options are required but some option is required without asking the user to type '--ui'.

• I added a new -c flag to r3.stats so that the new d.legend '-d' histogram distribution flag will work for raster3d maps too.

please test.

Hamish

[wenzeslaus]

Seems to work well (including GUI) in both trunk and 7.0. Closing.

For reference: there was several commits and backports but see for example r60104, r60379, r60395 and #2303.