1Vector Features
2===============
3
4Rasterio's ``features`` module provides functions to extract shapes of raster
5features and to create new features by "burning" shapes into rasters:
6``shapes()`` and ``rasterize()``. These functions expose GDAL functions in
7a general way, using iterators over GeoJSON-like Python objects instead of
8GIS layers.
9
10Extracting shapes of raster features
11------------------------------------
12
13Consider the Python logo.
14
15.. image:: https://farm8.staticflickr.com/7018/13547682814_f2e459f7a5_o_d.png
16
17The shapes of the foreground features can be extracted like this:
18
19.. code-block:: python
20
21    import pprint
22    import rasterio
23    from rasterio import features
24
25    with rasterio.open('13547682814_f2e459f7a5_o_d.png') as src:
26        blue = src.read(3)
27
28    mask = blue != 255
29    shapes = features.shapes(blue, mask=mask)
30    pprint.pprint(next(shapes))
31
32    # Output
33    # pprint.pprint(next(shapes))
34    # ({'coordinates': [[(71.0, 6.0),
35    #                    (71.0, 7.0),
36    #                    (72.0, 7.0),
37    #                    (72.0, 6.0),
38    #                    (71.0, 6.0)]],
39    #   'type': 'Polygon'},
40    # 253)
41
42The shapes iterator yields ``geometry, value`` pairs. The second item is the
43value of the raster feature corresponding to the shape and the first is its
44geometry.  The coordinates of the geometries in this case are in pixel units
45with origin at the upper left of the image. If the source dataset was
46georeferenced, you would get similarly georeferenced geometries like this:
47
48.. code-block:: python
49
50    shapes = features.shapes(blue, mask=mask, transform=src.transform)
51
52Burning shapes into a raster
53----------------------------
54
55To go the other direction, use ``rasterize()`` to burn values into the pixels
56intersecting with geometries.
57
58.. code-block:: python
59
60    image = features.rasterize(
61                ((g, 255) for g, v in shapes),
62                out_shape=src.shape)
63
64By default, only pixels whose center is within the polygon or that
65are selected by Bresenham's line algorithm will be burned in.
66You can specify ``all_touched=True`` to burn in all pixels touched by the geometry.
67The geometries will be rasterized by the "painter's algorithm" -
68geometries are handled in order and later geometries will overwrite earlier values.
69
70Again, to burn in georeferenced shapes, pass an appropriate transform for the
71image to be created.
72
73.. code-block:: python
74
75    image = features.rasterize(
76                ((g, 255) for g, v in shapes),
77                out_shape=src.shape,
78                transform=src.transform)
79
80The values for the input shapes are replaced with ``255`` in a generator
81expression. Areas not covered by input geometries are replaced with an
82optional ``fill`` value, which defaults to ``0``. The resulting image,
83written to disk like this,
84
85.. code-block:: python
86
87    with rasterio.open(
88            '/tmp/rasterized-results.tif', 'w',
89            driver='GTiff',
90            dtype=rasterio.uint8,
91            count=1,
92            width=src.width,
93            height=src.height) as dst:
94        dst.write(image, indexes=1)
95
96has a black background and white foreground features.
97
98.. image:: https://farm4.staticflickr.com/3728/13547425455_79bdb5eaeb_o_d.png
99
100