1Profiles and Writing Files
2==========================
3
4How to use profiles when opening files.
5
6Like Python's built-in ``open()`` function, :func:`rasterio.open()` has two primary
7arguments: a path (or URL) and an optional mode (``'r'``, ``'w'``, ``'r+'``, or
8``'w+'``). In addition there are a number of keyword arguments, several of
9which are required when creating a new dataset:
10
11- driver
12- width, height
13- count
14- dtype
15- crs
16- transform
17
18These same parameters surface in a dataset's ``profile`` property. Exploiting
19the symmetry between a profile and dataset opening keyword arguments is
20good Rasterio usage.
21
22.. code-block:: python
23
24   with rasterio.open('first.jp2') as src_dataset:
25
26       # Get a copy of the source dataset's profile. Thus our
27       # destination dataset will have the same dimensions,
28       # number of bands, data type, and georeferencing as the
29       # source dataset.
30       kwds = src_dataset.profile
31
32       # Change the format driver for the destination dataset to
33       # 'GTiff', short for GeoTIFF.
34       kwds['driver'] = 'GTiff'
35
36       # Add GeoTIFF-specific keyword arguments.
37       kwds['tiled'] = True
38       kwds['blockxsize'] = 256
39       kwds['blockysize'] = 256
40       kwds['photometric'] = 'YCbCr'
41       kwds['compress'] = 'JPEG'
42
43       with rasterio.open('second.tif', 'w', **kwds) as dst_dataset:
44           # Write data to the destination dataset.
45
46The :mod:`rasterio.profiles` module contains an example of a named profile that
47may be useful in applications:
48
49.. code-block:: python
50
51    class DefaultGTiffProfile(Profile):
52        """Tiled, band-interleaved, LZW-compressed, 8-bit GTiff."""
53
54        defaults = {
55            'driver': 'GTiff',
56            'interleave': 'band',
57            'tiled': True,
58            'blockxsize': 256,
59            'blockysize': 256,
60            'compress': 'lzw',
61            'nodata': 0,
62            'dtype': uint8
63        }
64
65It can be used to create new datasets. Note that it doesn't count bands and
66that a ``count`` keyword argument needs to be passed when creating a profile.
67
68.. code-block:: python
69
70   from rasterio.profiles import DefaultGTiffProfile
71
72   with rasterio.open(
73           'output.tif', 'w', **DefaultGTiffProfile(count=3)) as dst_dataset:
74       # Write data to the destination dataset.
75
76
77