1-band raster colour table   
V1.1.2 - 14 April 2012

This QGIS plugin is used to create a colour table for a one-band raster file.

NEW: version 1.1.0 - This version will only fully work with QGIS development versions 1.6.R14026 and above!
                                                                  It will NOT work on QGIS 1.5 and lower

If you've installed a version lower than 1.0.0 you will have two 1-band raster colour table menus. Select the one with the little 1 in the icon to launch this plugin.

Distributed under the GPL licence
 

What this plugin does

After selection of a single band raster (1-band raster) in the QGIS legend, launch this plugin to generate a colour table for the raster. The colour table is made of the combibation of a colour palette (a few are provided with the plugin and you can add your own, see here how) and a colouring method (the way to relate a colour index in the palette to a real value in the raster). While the plugin is on, you can generate as many colour tables as you want for the selected raster. On closing the plugin you can also apply one of the colour tables to the raster.

Once installed the bcccoltbl1 plugin can be found in the 'Raster/Raster Colours' menu.

The raster file must be selected in the QGIS legend and it must be a one-band raster, otherwise the plug in will not even launch!

Please be aware that the plugin needs to read the entire content of the raster to generate statistics and histogram, this can be a very long process when QGIS computes the stats on a large raster, so have a coffee break!

The plugin displays a copy of the selected raster in the main QGIS canvas using the plugin default colour palette (grey colours) and the default colouring method (equal).

You then have to select a colour palette from the dropdown list and a colouring schem from the dropdown list. The selected colour palette is displayed for you to evaluate it.

Then to apply the colour palette and colouring method to the raster, click the 'Create' button.

Each time you click on the 'Create' button a colour palette file is generated in the raster folder and the display is updated accordingly. The name of the created colour table has the following format:
                                 rastername_palettename_ColouringmethodFlag.txt
where rastername is the name of the loaded raster (e.g. SRTM), palettename is the name of the selected palette (e.g. 032_grey) Colouringmethod is the name of the selected colouring method (EQ, LI, NO, GE, DM, GR or CL) and Flag is one of ('', 'i', 'r', 'ir') for the state of the "Reverse colour" and "Invert palette" check boxes, so that in our example the filename will be SRTM_032_grey_EQ.txt. This will help you if you create many coulour tables for a single raster.

You can modify the output colour table name to a name more meaningful to you. But you can only do that just before clicking on the 'Create' button. If you change the colour table name and later change any of its parts, you changes will be lost!

After closing the plugin you will have all the colour tables you've created ready to be used. Open the properties window of the raster, select 'colormap' from the "Color map" single band properties in the "Symbology" tab. Then go to the "Colormap" tab and click the "Load color map from file" button, navigate to one of the colour table files and open it, click 'Apply' and voilà, your raster in coloured!

You can also select a colour table you've created from the drop-down list, at the bottom of the plugin window, then click the 'Close' button. The selected raster will automatically be displayed with that colour table.

Please report any bug/problem/wish to the QGIS User mailing list [mailto: qgis - user at lists dot osgeo dot org].

Notes

• The first time a raster is read, the plugin will save its stats/histo info to disk, in the same folder as the raster, and use that image for subsequent uses. This has the advantage of speeding up subsequent loads of the same raster; but has the disadvantage of having to create a file in the same folder as the raster file.
• The computation of the statistics on the QGIS layer are done using QGIS itself and the process is quite slow on large rasters.
• You can add your own colour palettes. See below.

Buttons

• 'Create' button to create the colour table file after selection of the colour palette and colouring method.
• 'Cancel' button to close the plugin.
• 'Close' button to close the plugin and issue a warning if colour tables have not been created. It also shows the list of the colour tables you've created if there is no selected colour table in the drop-down list, or it will apply the colour table to the raster if there is a selected colour table in the drop-down list.
• 'Help' button displays this page.
• 'About' displays a plugin information message.

Guided tour:
 

Other features

Editing the colour table filename:
Select a palette, method and modifiers (invert and/or revert): the default filename of the colour table is created. Now, before clicking on 'Create' you can modify the filename of the palette. WARNING: you can only modify the filename of the table just before clicking 'Create'. If you modify the filename and later change either the palette, the method or invert or revert then your modifications will be lost!

How to use a ColorBrewer (http://colorbrewer2.org/) RGB palette. Only RGB palettes are understood by the plugin!

1)           select the Color Brewer palette. Then go to the colorbrewer web site.

2)          

3)          

4)          

5) After clicking 'OK' the ColorBrewer palette is imported into the plugin and can be used to create a colour table.

How to use the 'Categorical layer' colour method (this method is only displayed if your raster is of type byte or int16)

It works by fixing the number of classes to the number of colours available in the selected palette. It also assumes that the raster values are equal to the colour index values (very important): e.g. raster values are 1, 2, 3,..., N. N = number of colours in selected palette.

So, if the selected palette has more colours than raster values, the last colour entries will not be represented in the table. Similarly, if the selected palette has less colours than raster values then the last raster values will default to black.

New in Version 1.1.2

• Maintenance release: add metadata.txt to comply with latest plugin requirements.

New in Version 1.1.0

• Added Log and Exp colour methods, at Agus' request.
• The statistics textbox also displays the current colour table values.

New in Version 1.0.0

• Brand new user interface that uses QGIS and GDAL native functions.
• Generally a huge speed improvement on large rasters. The speed bottleneck is now when QGIS compute the stats on the selected raster. Internally the plugin uses GDAL to source stats and histogram because GDAL is able to rapidly compute those on a representative subset of the raster.
• Code cleaning and commenting in view of converting to C++ by a C++ guru!
• Changes in the bcccoltbl.xml file: the colouring methods are no longer included because they cannot be changed without reprogramming their logic or adding new code.

See other history steps here.

Some Examples (based on plugin version < 1.0.0, but same meaning)

Equal colouring method
Linear colouring method
Normal colouring method (only for 8 colour palettes)
	N/A
Normal colouring method, Geosoft© style

Colour palettes

Colour palettes can be added to the plugin following your needs.

The palettes provided by default have been created from material freely, well, I think, available from the Internet during the first half of 2010.

If any of those palettes infringes a copyright, please let me know and I will gladly remove it from the palette folder.

Creating your own colour palettes

This is a two steps process:

1. Create the colour palette file.
2. Add the file to the xml descriptor.

1 - The colour palette file

Custom colour palette files must be placed in the cTBLs folder living in the plugin directory.

Colour palettes can be defined in different colour spaces:
The first non-blank line of the file has one of the following formats:

  { hue    sat   val }          # for HSV colour space
  { red   green   blu }         # for RGB colour space
  { blk   cyn   mag   yel }     # for CMYK colour space
  { cyn   mag   yel }           # form CMY colour space

Notes:
- The end of line should be just after } on the lines above.
- The order of the colour codes cannot be changed! They must be as one of the above formats.
- The alpha channel is always set to 255 although provision is made to read it from the colour palette file.

This is the format GEOSOFT© is using to define their colour palettes.

For example:

002_BW.tbl is defined as:

  {  blk   cyn   mag   yel }        : we are using the CMYK colour space
     000   000   000   000          :  B, C, M & Y values of the first colour
     000   255   255   255          :  B, C, M & Y values of the last colour

The palette filename should be named as follows: NNN_PaletteName.tbl

Where:
     NNN is the number of colours in the palette.
     PaletteName is the name of your palette.
     The extension must be 'tbl'.

2 - the bcccoltbl.xml file

In order for your palette to be recognised by the plugin, an entry pointing to it must be defined in the bcccoltbl.xml file.

Simply add a line of the following format in the <ColPal> section:

<cp value="the_name_of_your_palete" id="Unique_Number" class="ColPalClasses"/>

Where:
     the_name_of_your_palete, well, is the file name of the palette to be added without extension.
     Unique_Number is a unique number. Use one more than the latest number in the file.
     ColPalClasses is the code of the class the palette belong to.

The palette classes are defined as:

        Grey             : for grey palettes (gradient from white to black)
        Multicolour      : for multi-colour palettes
        Gradient 1col    : for gradient of one-colour palette (colour to white to black) 
        Gradient 2col    : for gradient between two colours
        Gradient 3col    : for gradient between three colours
        Repeat colours   : for palettes that repeat colours
        Special palettes : any other palettes (used for the GRASS colouring methods)
        DEM [topo]       : for representing topography
        HSV colour space : palettes defined in HSV colour space

This list can also be extended with your own entries. The format is:

           <cl id="code"    value="Name" />

Where:
   - code is the code of the entry used in the definition of the palette (ColPalClasses)
   - Name is the name of the entry used in the palette class dropdown list

About the plugin:

    bcccoltbl: a 1-Band Raster Colour Table plugin for QGIS 1.6 and above.

    bcccoltbl is free software: you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation, either version 3 of the License, or
    (at your option) any later version.

    bcccoltbl is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with bcccoltbl.  If not, see <http://www.gnu.org/licenses/>.

===============================================================================
 WARNING: this code is still not very pythonic.
          I'm in no way a python programmer!
          Corrections are more than welcome, if properly explained.
          (trying to learn by mistakes!)
===============================================================================
 WARNING 2: this app can still be very slow! Raster statistics computing is 
            painfully slow on large rasters.
  Really, be patient with this app or, better, help to improve it !!!!
===============================================================================

  bcccoltbl is made of the following files:

__init__.py
  loader for the plugin

bcccoltbl.py
  This is the main module. It sets up the dialog window and open it with the
  name of the selected 1-band raster layer and the placeholder-name of the
  colour table that will be created for that raster.

  It also displays the dialog window where user see the selected 1-band raster name,
  the name of the colour table that will be created and the action buttons.
  The user actions are:
       - Select the type of palettes to use
       - Select the colour palette to use from a dropdown list (combobox)
       - Select the colouring method to use from a combobox
       - Click the 'Create' button to generate the colour table

  - The selected colour palette is shown on screen, so that user can see what
    are the colours that will be used.
  - The colour table is also applied to a copy of the selected taster in the QGIS main window.
  - Each time the 'Create' button is clicked with a different palette a new file
    is saved to disk so that many colour tables can be created for one raster.

ColorTable.py
  A class where all the hard work of creating a colour table is done.

info.py
  Information about the plugin

loadManually.py
  This is a plan-b routine in case the bcccoltbl.xml cannot be read. It loads
  the original colouring methods and original colour palettes names.
  This does not mean that the colour palettes are still present on disk...

Palette.py
  class to handle reading a colour palette into an array

utils.py
  Some objects to hold raster info: the oneBandRaster and Stats objects.

vscbar.py
  Vertical scale bar for raster legend.

Furthermore, the folder cTBLs contains the distributed colour palettes.
 See README in that folder.

 If you plan to add your own palette, see the palette format in the README file
 in folder cTBLs for its format. You will also have to add an entry into the 
 bcccoltbl.xml file.

Acknowledgements

I would like to sincerely thanks the following QGIS developers and users for their help and encouragement in the development of this QGIS plugin:

• Peter Ersts, Martin Dobias, Borys Jurgiel, Duarte Carreira and Tim Sutton for their very helpful insight on the QGIS mechanics.
• Giovanni Manghi, Paolo Cavallini, Giuseppe Sucameli and Augustin Lobo for encouragements and ideas on how to improve the plugin.
• And all other users of the plugin that provided feedback.