1Writing Datasets
2=================
3
4.. todo::
5
6    * appending to existing data
7    * context manager
8    * write 3d vs write 2d
9    * document issues with writing compressed files (per #77)
10    * discuss and refer to topics
11        * creation options
12        * transforms
13        * dtypes
14        * block windows
15
16Opening a file in writing mode is a little more complicated than opening
17a text file in Python. The dimensions of the raster dataset, the
18data types, and the specific format must be specified.
19
20Here's an example of basic rasterio functionality.
21An array is written to a new single band TIFF.
22
23.. code-block:: python
24
25    # Register GDAL format drivers and configuration options with a
26    # context manager.
27    with rasterio.Env():
28
29        # Write an array as a raster band to a new 8-bit file. For
30        # the new file's profile, we start with the profile of the source
31        profile = src.profile
32
33        # And then change the band count to 1, set the
34        # dtype to uint8, and specify LZW compression.
35        profile.update(
36            dtype=rasterio.uint8,
37            count=1,
38            compress='lzw')
39
40        with rasterio.open('example.tif', 'w', **profile) as dst:
41            dst.write(array.astype(rasterio.uint8), 1)
42
43    # At the end of the ``with rasterio.Env()`` block, context
44    # manager exits and all drivers are de-registered.
45
46Writing data mostly works as with a Python file. There are a few format-
47specific differences.
48
49Supported Drivers
50-----------------
51``GTiff`` is the only driver that supports writing directly to disk.
52GeoTiffs use the ``RasterUpdater`` and leverage the full capabilities
53of the ``GDALCreate`` function. We highly recommend using GeoTiff
54driver for writing as it is the best-tested and best-supported format.
55
56Some other formats that are writable by GDAL can also be written by
57Rasterio. These use an ``IndirectRasterUpdater`` which does not create
58directly but uses a temporary in-memory dataset and ``GDALCreateCopy``
59to produce the final output.
60
61Some formats are known to produce invalid results using the
62``IndirectRasterUpdater``. These formats will raise a ``RasterioIOError``
63if you attempt to write to the. Currently this applies to the ``netCDF``
64driver but please let us know if you experience problems writing other formats.
65