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.
NEW: version 0.7.4 - This version will only fully work with QGIS development versions 1.6.R14026 and above!
It will work on QGIS 1.5 but with limited functionality.
Please note: with the imminent release of QGIS 1.6 this plugin will be retired and replaced with
'1-band raster colour table V1.x' plugin.
This means support for the plugin will stop.
Distributed under the GPL licence
ContentsWhat this plugin does What's new? Colour palettes and how to create them Return to BC-Consulting plugins page |
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).
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.
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.
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 a compressed image of it 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.
- 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 the colour table has 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 message.
- 'About' display plugin information.
Guided tour:
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.
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 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):
- Can change the file name of the created colour table.
- Use a ColorBrewer (http://colorbrewer2.org/) RGB palette directly into the plugin.
- 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.
New in Version 0.5.0
- The plugin is now located under the 'Raster Colours' menu of the main 'Plugin' menu.
- 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...)
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:
 |
 |
Some Examples
| 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:
- Create the colour palette file.
- 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.