BC Consulting

Home

  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.

version 1.1.0 - This version will only fully work with QGIS 1.6 and 1.7. It will work on QGIS 1.5 and lower, and on QGIS 1.8 and above.

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.

different plugin versions menus

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 or 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!

select a 1-band raster before launching the plugin

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).

default palette

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

bcccoltbl main window

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!

bcccoltbl coloured raster

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.

the coloured raster in QGIS

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

Notes

Buttons


Guided tour:

Main window

 

Please Note: If you've selected a colour table from the dropdown list before clicking on Close that colour table will be applied to your raster only if you have a QGIS version later than V1.6 R14026.

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 palette are understood by the plugin!

  1. Select the Color Brewer palette. Then go to the colorbrewer web site. select colorbrewer palette
  2. select colorbrewer palette
  3. copy palette
  4. paste into plugin
  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)

categorical layer

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.


History

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.

Some Examples

Equal colouring method
equal distribution
equal distribution
Linear colouring method
linear distribution
linear distribution
Normal colouring method (only for 8 colour palettes)
normal distribution
N/A
Normal colouring method, Geosoft© style
geosoft normal
geosoft normal

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:

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
It is that simple!

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 not pythonic at all. 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 is generally very slow! Raster reading is painfully slow
            (see oneBandRaster.py for more comments about it). And, creation of
            the colour table is also a slowish process...
  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 entry 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.

cdlgRST.py
  Display a progress bar while importing the raster data into the onebandraster
  object.
  Note: reading of a moderate size raster takes ages with the current
        implementation. Optimisation is much needed here (call to gurus....)
        In order to work-around this problem, the app saves a oneBandRaster object
        to the same folder as the original raster (rrr.bccPAL) rrr = original 
        raster name. When the app is about to read a raster file it checks for the
        bccPAL file and, if it exists, opens it instead of the original file,
        resulting in a huge speed boost.

cdlgTBL.py
  This is the dialog window where user see the selected 1-band raster name,
  the name of the colour table that will be created (no user inter-action, it
  is fixed ny the system).
  The user actions are:
       - 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.
  - A preview of the generated colour table is also displayed.
  - 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.

  Technically the script starts by selecting a default palette (32 grey) and
  displays it.
  It then "compresses" the original raster into a display box of defined size and
  uses the pixels on that display box (stored in a 2D 'array') to compute the
  histogram of the colours in the raster.
  It then uses the default colouring method (equal-area) and the histogram to
  create a colour table and applies it to the raster and shows the results in
  the display box.
  Then it waits for the user to select a colour palette or/and colouring mode and
  change the display box to reflect the new selection and save the generated
  colour table to disk.
  When user clicks 'Cancel' the window closes immediately.
  When user clicks 'Close' the window also closes, but if no colour table has
  been saved a confirmation message is issued, and user can cancel closing.

DoColorTable.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 and Duarte Carreira 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.