[QGIS Commit] r14026 - in docs/trunk/english_us/developer_cookbook: . source

[svn_qgis at osgeo.org]

Author: wonder
Date: 2010-08-07 22:05:59 +0000 (Sat, 07 Aug 2010)
New Revision: 14026

Modified:
   docs/trunk/english_us/developer_cookbook/
   docs/trunk/english_us/developer_cookbook/source/raster.rst
Log:
Added some text and code for raster layers



Property changes on: docs/trunk/english_us/developer_cookbook
___________________________________________________________________
Added: svn:ignore
   + build



Modified: docs/trunk/english_us/developer_cookbook/source/raster.rst
===================================================================
--- docs/trunk/english_us/developer_cookbook/source/raster.rst	2010-08-07 19:34:00 UTC (rev 14025)
+++ docs/trunk/english_us/developer_cookbook/source/raster.rst	2010-08-07 22:05:59 UTC (rev 14026)
@@ -6,6 +6,105 @@
 
 This sections lists various operations you can do with raster layers.
 
+Layer Details
+-------------
+
+A raster layer consists of one or more raster bands - it is referred to as either single band or multi band raster.
+One band represents a matrix of values. Usual color image (e.g. aerial photo) is a raster consisting of red, blue and green band.
+Single band layers typically represent either continuous variables (e.g. elevation) or discrete variables (e.g. land use).
+In some cases, a raster layer comes with a palette and raster values refer to colors stored in the palette.
+
+  >>> rlayer.width(), rlayer.height()
+  (812, 301)
+  >>> rlayer.extent().toString()
+  PyQt4.QtCore.QString(u'12.095833,48.552777 : 18.863888,51.056944')
+  >>> rlayer.rasterType()
+  2  # 0 = GrayOrUndefined (single band), 1 = Palette (single band), 2 = Multiband
+  >>> rlayer.bandCount()
+  3
+  >>> rlayer.metadata()
+  PyQt4.QtCore.QString(u'<p class="glossy">Driver:</p>...')
+  >>> rlayer.hasPyramids()
+  False
+
+
+Drawing Style
+-------------
+
+When a raster layer is loaded, it gets a default drawing style based on its type. It can be altered either in raster layer properties or programmatically.
+The following drawing styles exist:
+
+====== =============================== ===============================================================================================
+Index   Constant: QgsRasterLater.X     Comment
+====== =============================== ===============================================================================================
+  1     SingleBandGray                 Single band image drawn as a range of gray colors
+  2     SingleBandPseudoColor          Single band image drawn using a pseudocolor algorithm
+  3     PalettedColor                  "Palette" image drawn using color table
+  4     PalettedSingleBandGray         "Palette" layer drawn in gray scale
+  5     PalettedSingleBandPseudoColor  "Palette" layerdrawn using a pseudocolor algorithm
+  7     MultiBandSingleGandGray        Layer containing 2 or more bands, but a single band drawn as a range of gray colors
+  8     MultiBandSingleBandPseudoColor Layer containing 2 or more bands, but a single band drawn using a pseudocolor algorithm
+  9     MultiBandColor                 Layer containing 2 or more bands, mapped to RGB color space.
+====== =============================== ===============================================================================================
+
+To query the current drawing style:
+
+  >>> rlayer.drawingStyle()
+  9
+
+Single band raster layers can be drawn either in gray colors (low values = black, high values = white) or with a pseudocolor algorithm
+that assigns colors for values from the single band. Single band rasters with a palette can be additionally drawn using their palette.
+Multiband layers are typically drawn by mapping the bands to RGB colors. Other possibility is to use just one band for gray or pseudocolor
+drawing.
+
+.. todo:: contrast enhancements, transparency (no data), user defined min/max, band statistics
+
+Single Band Rasters
+-------------------
+
+They are rendered in gray colors by default. To change the drawing style to pseudocolor:
+
+  >>> rlayer.setDrawingStyle(QgsRasterLayer.SingleBandPseudoColor)
+  >>> rlayer.setColorShadingAlgorithm(QgsRasterLayer.PseudoColorShader)
+
+The ``PseudoColorShader`` is a basic shader that highlighs low values in blue and high values in red. Another, ``FreakOutShader`` uses
+more fancy colors and according to the documentation, it will frighten your granny and make your dogs howl.
+
+There is also ``ColorRampShader`` which maps the colors as specified by its color map. It has three modes of interpolation of values:
+
+* linear (``INTERPOLATED``): resulting color is linearly interpolated from the color map entries above and below the actual pixel value
+* discrete (``DISCRETE``): color is used from the color map entry with equal or higher value
+* exact (``EXACT``): color is not interpolated, only the pixels with value equal to color map entries are drawn
+
+To set an interpolated color ramp shader ranging from green to yellow color (for pixel values from 0 to 255)::
+
+  >>> rlayer.setColorShadingAlgorithm(QgsRasterLayer.ColorRampShader)
+  >>> lst = [ QgsColorRampShader.ColorRampItem(0, QColor(0,255,0)), QgsColorRampShader.ColorRampItem(255, QColor(255,255,0)) ]
+  >>> fcn = rlayer.rasterShader().rasterShaderFunction()
+  >>> fcn.setColorRampType(QgsColorRampShader.INTERPOLATED)
+  >>> fcn.setColorRampItemList(lst)
+
+To return back to default gray levels, use:
+
+  >>> rlayer.setDrawingStyle(QgsRasterLayer.SingleBandGray)
+
+Multi Band Rasters
+------------------
+
+By default, QGIS maps the first three bands to red, green and blue values to create a color image (this is the ``MultiBandColor`` drawing style.
+In some cases you might want to override these setting. The following code interchanges red band (1) and green band (2):
+
+  >>> rlayer.setGreenBandName(rlayer.bandName(1))
+  >>> rlayer.setRedBandName(rlayer.bandName(2))
+
+In case only one band is necessary for visualization of the raster, single band drawing can be chosen - either gray levels or pseudocolor,
+see previous section::
+
+  >>> rlayer.setDrawingStyle(QgsRasterLayer.MultiBandSingleBandPseudoColor)
+  >>> rlayer.setGrayBandName(rlayer.bandName(1))
+  >>> rlayer.setColorShadingAlgorithm(QgsRasterLayer.PseudoColorShader)
+  >>> # now set the shader
+
 Query Values
 ------------