1Color
2=====
3
4Color interpretation
5--------------------
6
7Color interpretation of raster bands can be read from the dataset
8
9.. code-block:: python
10
11    >>> import rasterio
12    >>> src = rasterio.open("tests/data/RGB.byte.tif")
13    >>> src.colorinterp[0]
14    <ColorInterp.red: 3>
15
16GDAL builds the color interpretation based on the driver and creation options.
17With the ``GTiff`` driver, rasters with exactly 3 bands of uint8 type will be RGB,
184 bands of uint8 will be RGBA by default.
19
20Color interpretation can be set when creating a new datasource with the
21``photometric`` creation option:
22
23.. code:: python
24
25    >>> profile = src.profile
26    >>> profile['photometric'] = "RGB"
27    >>> with rasterio.open("/tmp/rgb.tif", 'w', **profile) as dst:
28    ...     dst.write(src.read())
29
30or via the ``colorinterp`` property when a datasource is opened in
31update mode:
32
33.. code:: python
34
35    >>> from rasterio.enums import ColorInterp
36    >>> with rasterio.open('/tmp/rgb.tif', 'r+', **profile) as src:
37    ...     src.colorinterp = [
38    ...         ColorInterp.red, ColorInterp.green, ColorInterp.blue]
39
40And the resulting raster will be interpretted as RGB.
41
42.. code:: python
43
44    >>> with rasterio.open("/tmp/rgb.tif") as src2:
45    ...     src2.colorinterp[1]
46    <ColorInterp.green: 4>
47
48Writing colormaps
49-----------------
50
51Mappings from 8-bit (rasterio.uint8) pixel values to RGBA values can be attached
52to bands using the ``write_colormap()`` method.
53
54.. code-block:: python
55
56    import rasterio
57
58    with rasterio.Env():
59
60        with rasterio.open('tests/data/shade.tif') as src:
61            shade = src.read(1)
62            meta = src.meta
63
64        with rasterio.open('/tmp/colormap.tif', 'w', **meta) as dst:
65            dst.write(shade, indexes=1)
66            dst.write_colormap(
67                1, {
68                    0: (255, 0, 0, 255),
69                    255: (0, 0, 255, 255) })
70            cmap = dst.colormap(1)
71            # True
72            assert cmap[0] == (255, 0, 0, 255)
73            # True
74            assert cmap[255] == (0, 0, 255, 255)
75
76    subprocess.call(['open', '/tmp/colormap.tif'])
77
78The program above (on OS X, another viewer is needed with a different OS)
79yields the image below:
80
81.. image:: http://farm8.staticflickr.com/7391/12443115173_80ecca89db_d.jpg
82   :width: 500
83   :height: 500
84
85Reading colormaps
86-----------------
87
88As shown above, the ``colormap()`` returns a dict holding the colormap for the
89given band index. For TIFF format files, the colormap will have 256 items, and
90all but two of those would map to (0, 0, 0, 0) in the example above.
91