BC Consulting

Home

  1-band raster colour table
V0.7.4 - 8 November 2010

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

version 0.7.4 - This version will only fully work with QGIS development versions 1.6.R14026 ! It will work on QGIS 1.5 but with limited functionality.

Please note: this plugin has been replaced with '1-band raster colour table V1.x' plugin. Please see here for latest 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 or you can add your own, see here how) and a colouring scheme (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 bcccoltbl plugin can be found in the 'Plugins/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, this can be a very long process so have a coffee break or a good night sleep!

After the raster is read into the plugin, it is displayed in the plugin window using the default colour palette (grey colours) and the default colouring scheme (equal).

bcccoltbl main window

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.

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

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! As from version 0.6.0, you can also select a colour table you've created from the drop-down list 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 (from V0.7.0)

Editing the colour table filename:
Select a palette, method and modifications (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 0.7.4

  • Bug fixing: remove debug info left in V0.7.3
  • Bug fixing: correct version number.

New in Version 0.7.2

  • Bug fixing: when raster has same X and Y dimensions and they are greater than 256 pixels (Thanks Agus!)

New in Version 0.7.1

  • Bug fixing: correct the behaviour of the plugin when a ColorBrewer is selected and the type of palettes is changed.
  • Bug fixing: correct the behaviour of the plugin when the default ColorBrewer is selected and the colouring method is changed.

New in Version 0.7.0

  • Augustin Lobo suggested the following enhancements (see section above on how to use those new features):
    1. Can change the file name of the created colour table.
    2. Use a ColorBrewer (http://colorbrewer2.org/) RGB palette directly into the plugin.
    3. Add the 'Categorical layer' colour method for rasters having a type of byte or int16.

New in Version 0.6.3

  • Changed deprecated call to GDAL libraries (Thanks Giuseppe!).

New in Version 0.6.2

  • Changed deprecated call to current call in plugin initialisation.

New in Version 0.6.1

  • Correct a bug preventing plugin removal from the plugin menu.
  • Added a online sample dataset: here. Very simple 1 band SRTM data as an ArcGIS ASCII file (.asc) in Latitude, Longitude WGS84 coord system.

New in Version 0.6.0

  • This version needs a QGIS development version greater or equal to 1.6.R14026 in order to function.
  • On MS Windows machines you will need to setup GDAL 1.7 manually. See how to do that here (thanks to Duarte Carreira for the tip).
  • The help button now points to the online help file (this file).
  • The layout of the user interface has changed to accommodate the following addition.
  • On closing the plugin you have the choice to select one of the colour tables you have created for the selected plugin and apply it to the raster: the raster will automatically be coloured and the legend will be updated when the plugin closes.
       To do that, simply select the desired colour table in the drop-down list and click Close.

bcccoltbl 0.6.0

New in Version 0.5.0

  • The plugin is now located under the 'Raster Colours' menu of the main 'Plugin' menu.
     
    location of bcc plugins
     
  • Change the progress bar on loading rasters to allow for abort of the process.
  • Few internal changes due to a better comprehension of Qt!

New in Version 0.4.0

  • Add colour palettes thumbnail to the colour palettes combobox (from Giovanni's suggestion).
    Note that all the thumbnails are created in your TEMP folder when the plugin is launched. If you do not delete that folder, the next time the plugin launches it will save some milliseconds (hopefully not minutes...)

colour palettes combobox

New in Version 0.3.0

Following comments and suggestions from QGIS users the following additions have been implemented in V0.3.0:

  • Add progress bars to update the user on long processes: reading the raster in and doing the colour table.
  • Allow for the grouping of the colour palettes under several classes. The classes defined at present are:
    • All palettes: allow selection amongst all colour palettes.
    • Grey: allow selection of grey scale palettes only.
    • Multicolour: allow selection of multicolor palettes.
    • Gradient 1col: for selection of colour palettes based on a gredient of one colour (colour to white, or colour to black).
    • Gradient 2col: for selection of colour palettes based on gradient between two colours.
    • Gradient 3col: for selection of colour palettes based on gradient between three colours.
    • Repeat colours: for selected palettes based on repeat of a given set of colours.
    • DEM [topo]: for selection of palettes for use in DEM/SRTM/topography representations.
    • Special palettes: they are the two GRASS palettes for use the the GRASS colouring methods.
    • HSV colour space: colour palettes based on the HSV colour space. They do not redenr well on screen.

See screenshots below for visual changes:

progress bar
new in version 0.3.0

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

How to load GDAL 1.7 on MS Windows machine?

Please note this section is deprecated as OSGeo4W now includes Python bindings for GDAL 1.7 (mid-September 2010).

On Monday, 09 August 2010, Duarte Carreira wrote:
   "You can get GDAL 1.7 python bindings from the binaries here:
   http://vbkto.dyndns.org/sdk/release-1310-gdal-1-7-mapserver-5-6.zip
   Just copy bin\gdal\python folder to OSGeo4W\apps\gdal-17\pymod."
--------------------------------------------------------------------

Make sure to install GDAL 1.7 from OSGeo4W before the step above.

I do not know what the status is for the standalone version of QGIS, please see at
http://kcubeconsulting.com/download.php for the content of the package.