mirror of
https://github.com/rasterio/rasterio.git
synced 2025-12-08 17:36:12 +00:00
DOC: Improve links & add Band to docs (#2537)
This commit is contained in:
Alan D. Snow
GitHub
parent
f5218740bc
commit
125340b74b
@ -44,5 +44,6 @@ Module contents
|
||||
|
||||
.. automodule:: rasterio
|
||||
:members:
|
||||
:exclude-members: CRS, Env
|
||||
:undoc-members:
|
||||
:show-inheritance:
|
||||
|
||||
@ -74,8 +74,8 @@ values is 7731 columns wide and 7871 rows high.
|
||||
Some dataset attributes expose the properties of all dataset bands via a tuple
|
||||
of values, one per band. To get a mapping of band indexes to variable data
|
||||
types, apply a dictionary comprehension to the :func:`zip` product of a
|
||||
dataset's :attr:`~rasterio.io.DatasetReader.indexes` and
|
||||
:attr:`~rasterio.io.DatasetReader.dtypes` attributes.
|
||||
dataset's :attr:`.DatasetReader.indexes` and
|
||||
:attr:`.DatasetReader.dtypes` attributes.
|
||||
|
||||
.. code-block:: pycon
|
||||
|
||||
@ -102,7 +102,7 @@ Our example covers the world from
|
||||
meters to 4265115 meters bottom to top. It covers a region 231.93 kilometers
|
||||
wide by 236.13 kilometers high.
|
||||
|
||||
The value of :attr:`~rasterio.io.DatasetReader.bounds` attribute is derived
|
||||
The value of :attr:`.DatasetReader.bounds` attribute is derived
|
||||
from a more fundamental attribute: the dataset's geospatial transform.
|
||||
|
||||
.. code-block:: pycon
|
||||
@ -111,7 +111,7 @@ from a more fundamental attribute: the dataset's geospatial transform.
|
||||
Affine(30.0, 0.0, 358485.0,
|
||||
0.0, -30.0, 4265115.0)
|
||||
|
||||
A dataset's :attr:`~rasterio.io.DatasetReader.transform` is an affine
|
||||
A dataset's :attr:`.DatasetReader.transform` is an affine
|
||||
transformation matrix that maps pixel locations in (row, col) coordinates to
|
||||
(x, y) spatial positions. The product of this matrix and ``(0, 0)``, the row
|
||||
and column coordinates of the upper left corner of the dataset, is the spatial
|
||||
@ -138,16 +138,16 @@ values are relative to the origin of the dataset's coordinate reference system
|
||||
>>> dataset.crs
|
||||
CRS.from_epsg(32612)
|
||||
|
||||
"EPSG 32612" identifies a particular coordinate reference system: `UTM
|
||||
`EPSG:32612 <https://epsg.org/crs_32612/WGS-84-UTM-zone-12N.html>`__ identifies a particular coordinate reference system: `UTM
|
||||
<https://en.wikipedia.org/wiki/Universal_Transverse_Mercator_coordinate_system>`__
|
||||
zone 12N. This system is used for mapping areas in the Northern Hemisphere
|
||||
between 108 and 114 degrees west. The upper left corner of the example dataset,
|
||||
``(358485.0, 4265115.0)``, is 141.5 kilometers west of zone 12's central
|
||||
meridian (111 degrees west) and 4265 kilometers north of the equator.
|
||||
|
||||
Between the :attr:`~rasterio.io.DatasetReader.crs` attribute and ``transform``
|
||||
the georeferencing of a raster dataset is described and the dataset can
|
||||
compared to other GIS datasets.
|
||||
Between the :attr:`.DatasetReader.crs` and
|
||||
:attr:`.DatasetReader.transform` attributes, the georeferencing
|
||||
of a raster dataset is described and the dataset can compared to other GIS datasets.
|
||||
|
||||
Reading raster data
|
||||
-------------------
|
||||
@ -161,7 +161,7 @@ the GDAL convention, bands are indexed from 1.
|
||||
(1,)
|
||||
>>> band1 = dataset.read(1)
|
||||
|
||||
The :meth:`~rasterio.io.DatasetReader.read` method returns a :class:`numpy.ndarray`.
|
||||
The :meth:`.DatasetReader.read` method returns a :class:`numpy.ndarray`.
|
||||
|
||||
.. code-block:: pycon
|
||||
|
||||
@ -184,7 +184,7 @@ Values from the array can be addressed by their row, column index.
|
||||
Spatial indexing
|
||||
----------------
|
||||
|
||||
Datasets have an :meth:`~rasterio.io.DatasetReader.index` method for getting
|
||||
Datasets have an :meth:`.DatasetReader.index` method for getting
|
||||
the array indices corresponding to points in georeferenced space. To get the
|
||||
value for the pixel 100 kilometers east and 50 kilometers south of the
|
||||
dataset's upper left corner, do the following.
|
||||
@ -198,7 +198,7 @@ dataset's upper left corner, do the following.
|
||||
>>> band1[row, col]
|
||||
7566
|
||||
|
||||
To get the spatial coordinates of a pixel, use the dataset's :meth:`~rasterio.io.DatasetReader.xy` method.
|
||||
To get the spatial coordinates of a pixel, use the dataset's :meth:`.DatasetReader.xy` method.
|
||||
The coordinates of the center of the image can be computed like this.
|
||||
|
||||
.. code-block:: pycon
|
||||
@ -299,14 +299,14 @@ Saving raster data
|
||||
------------------
|
||||
|
||||
To copy the grid to the opened dataset, call the new dataset's
|
||||
:meth:`~rasterio.io.DatasetWriter.write` method with the grid and target band
|
||||
:meth:`.DatasetWriter.write` method with the grid and target band
|
||||
number as arguments.
|
||||
|
||||
.. code-block:: pycon
|
||||
|
||||
>>> new_dataset.write(Z, 1)
|
||||
|
||||
Then call the :meth:`~rasterio.io.DatasetWriter.close` method to sync data to
|
||||
Then call the :meth:`.DatasetWriter.close` method to sync data to
|
||||
disk and finish.
|
||||
|
||||
.. code-block:: pycon
|
||||
|
||||
@ -27,7 +27,7 @@ Color interpretation can be set when creating a new datasource with the
|
||||
>>> with rasterio.open("/tmp/rgb.tif", 'w', **profile) as dst:
|
||||
... dst.write(src.read())
|
||||
|
||||
or via the ``colorinterp`` property when a datasource is opened in
|
||||
or via the :attr:`~.DatasetWriter.colorinterp` property when a datasource is opened in
|
||||
update mode:
|
||||
|
||||
.. code:: python
|
||||
@ -49,7 +49,7 @@ Writing colormaps
|
||||
-----------------
|
||||
|
||||
Mappings from 8-bit (rasterio.uint8) pixel values to RGBA values can be attached
|
||||
to bands using the ``write_colormap()`` method.
|
||||
to bands using the :meth:`~.DatasetWriter.write_colormap` method.
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
@ -85,6 +85,6 @@ yields the image below:
|
||||
Reading colormaps
|
||||
-----------------
|
||||
|
||||
As shown above, the ``colormap()`` returns a dict holding the colormap for the
|
||||
As shown above, the :meth:`~.DatasetReader.colormap` returns a dict holding the colormap for the
|
||||
given band index. For TIFF format files, the colormap will have 256 items, and
|
||||
all but two of those would map to (0, 0, 0, 0) in the example above.
|
||||
|
||||
@ -127,9 +127,8 @@ threads simultaneously.
|
||||
executor.map(process, windows)
|
||||
|
||||
The code above simulates a CPU-intensive calculation that runs faster when
|
||||
spread over multiple cores using the ``ThreadPoolExecutor`` from Python 3's
|
||||
``concurrent.futures`` module. Compared to the case of one concurrent job
|
||||
(``-j 1``),
|
||||
spread over multiple cores using :class:`concurrent.futures.ThreadPoolExecutor`
|
||||
compared to the case of one concurrent job (``-j 1``),
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
@ -150,8 +149,9 @@ we get over 3x speed up with four concurrent jobs.
|
||||
sys 0m0.168s
|
||||
|
||||
If the function that you'd like to map over raster windows doesn't release the
|
||||
GIL, you unfortunately cannot simply replace ``ThreadPoolExecutor`` with
|
||||
``ProcessPoolExecutor``, the DatasetReader/Writer cannot be shared by multiple
|
||||
GIL, you unfortunately cannot simply replace :class:`~concurrent.futures.ThreadPoolExecutor` with
|
||||
:class:`~concurrent.futures.ProcessPoolExecutor`,
|
||||
the :class:`.DatasetReader`/:class:`.DatasetWriter` cannot be shared by multiple
|
||||
processes, which means that each process needs to open the file seperately,
|
||||
or you can do all the reading and writing from the main thread, as shown in
|
||||
this next example. This is much less efficient memory wise, however.
|
||||
|
||||
@ -58,7 +58,7 @@ Rasterio
|
||||
with rasterio.open('data/stefan_full_greyalpha.tif') as dataset:
|
||||
# Suite of code accessing dataset ``ds`` follows...
|
||||
|
||||
The object returned when you call :class:`rasterio.Env()` is a context manager. It
|
||||
The object returned when you call :class:`rasterio.Env` is a context manager. It
|
||||
handles the GDAL configuration for a specific block of code and resets the
|
||||
configuration when the block exits for any reason, success or failure. The
|
||||
Rasterio ``with rasterio.Env()`` pattern organizes GDAL configuration into single
|
||||
@ -80,11 +80,11 @@ to a name like so.
|
||||
When to use rasterio.Env()
|
||||
--------------------------
|
||||
|
||||
Rasterio code is often without the use of an ``Env`` context block. For instance,
|
||||
you could use ``rasterio.open()`` directly without explicity creating an ``Env``.
|
||||
In that case, the ``open`` function will initialize a default environment in
|
||||
Rasterio code is often without the use of an :class:`.Env` context block. For instance,
|
||||
you could use :func:`rasterio.open` directly without explicity creating an :class:`.Env`.
|
||||
In that case, the :func:`~rasterio.open` function will initialize a default environment in
|
||||
which to execute the code. Often this default environment is sufficient for most
|
||||
use cases and you only need to create an explicit ``Env`` if you are customizing
|
||||
use cases and you only need to create an explicit :class:`.Env` if you are customizing
|
||||
the default GDAL or format options.
|
||||
|
||||
|
||||
|
||||
@ -3,7 +3,7 @@ Advanced Datasets
|
||||
|
||||
The analogy of Python file objects influences the design of Rasterio dataset
|
||||
objects. Datasets of a few different kinds exist and the canonical way to
|
||||
obtain one is to call ``rasterio.open`` with a path-like object or URI-like
|
||||
obtain one is to call :func:`rasterio.open` with a path-like object or URI-like
|
||||
identifier, a mode (such as "r" or "w"), and other keyword arguments.
|
||||
|
||||
Dataset Identifiers
|
||||
|
||||
@ -3,7 +3,7 @@ Vector Features
|
||||
|
||||
Rasterio's ``features`` module provides functions to extract shapes of raster
|
||||
features and to create new features by "burning" shapes into rasters:
|
||||
``shapes()`` and ``rasterize()``. These functions expose GDAL functions in
|
||||
:func:`.shapes` and :func:`.rasterize`. These functions expose GDAL functions in
|
||||
a general way, using iterators over GeoJSON-like Python objects instead of
|
||||
GIS layers.
|
||||
|
||||
@ -52,7 +52,7 @@ georeferenced, you would get similarly georeferenced geometries like this:
|
||||
Burning shapes into a raster
|
||||
----------------------------
|
||||
|
||||
To go the other direction, use ``rasterize()`` to burn values into the pixels
|
||||
To go the other direction, use :func:`.rasterize` to burn values into the pixels
|
||||
intersecting with geometries.
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
@ -3,4 +3,4 @@ Filling nodata areas
|
||||
|
||||
.. todo::
|
||||
|
||||
fillnodata()
|
||||
:func:`.fillnodata`
|
||||
|
||||
@ -9,7 +9,7 @@ coordinates in that system.
|
||||
Coordinate Reference System
|
||||
---------------------------
|
||||
|
||||
The coordinate reference system of a dataset is accessed from its ``crs``
|
||||
The coordinate reference system of a dataset is accessed from its :attr:`.DatasetReader.crs`
|
||||
attribute.
|
||||
|
||||
.. code-block:: python
|
||||
@ -20,12 +20,11 @@ attribute.
|
||||
CRS({'init': 'epsg:32618'})
|
||||
|
||||
Rasterio follows pyproj and uses PROJ.4 syntax in dict form as its native
|
||||
CRS syntax. If you want a WKT representation of the CRS, see the CRS
|
||||
class's ``wkt`` attribute.
|
||||
CRS syntax. If you want a WKT representation of the CRS, see: :meth:`.CRS.to_wkt`:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
>>> src.crs.wkt
|
||||
>>> src.crs.to_wkt()
|
||||
'PROJCS["WGS 84 / UTM zone 18N",GEOGCS["WGS 84",DATUM["WGS_1984",SPHEROID["WGS 84",6378137,298.257223563,AUTHORITY["EPSG","7030"]],AUTHORITY["EPSG","6326"]],PRIMEM["Greenwich",0,AUTHORITY["EPSG","8901"]],UNIT["degree",0.0174532925199433,AUTHORITY["EPSG","9122"]],AUTHORITY["EPSG","4326"]],PROJECTION["Transverse_Mercator"],PARAMETER["latitude_of_origin",0],PARAMETER["central_meridian",-75],PARAMETER["scale_factor",0.9996],PARAMETER["false_easting",500000],PARAMETER["false_northing",0],UNIT["metre",1,AUTHORITY["EPSG","9001"]],AXIS["Easting",EAST],AXIS["Northing",NORTH],AUTHORITY["EPSG","32618"]]'
|
||||
|
||||
When opening a new file for writing, you may also use a CRS string as an
|
||||
@ -79,7 +78,7 @@ Ground Control Points
|
||||
A ground control point (GCP) is the mapping of a dataset's row and pixel coordinate to a
|
||||
single world x, y, and optionally z coordinate. Typically a dataset will have multiple
|
||||
GCPs distributed across the image. Rasterio can calculate an affine transformation matrix
|
||||
from a collection of GCPs using the ``rasterio.transform.from_gcps`` method. Alternatively
|
||||
from a collection of GCPs using the :func:`rasterio.transform.from_gcps` method. Alternatively
|
||||
GCP interpolation can also be used for coordinate transforms.
|
||||
|
||||
Rational Polynomial Coefficients
|
||||
@ -98,5 +97,4 @@ results. Datasets with low terrain variation may use an average height over the
|
||||
the image, while datasets with higher terrain variation should use a digital elevation
|
||||
model to sample height values.The coordinate transformation from world to pixel
|
||||
coordinates is exact while the reverse is not, and must be computed iteratively. For more
|
||||
details on coordinate transformations using RPCs see
|
||||
https://gdal.org/api/gdal_alg.html#_CPPv424GDALCreateRPCTransformerP11GDALRPCInfoidPPc
|
||||
details on coordinate transformations using RPCs see :cpp:func:`GDALCreateRPCTransformerV2`.
|
||||
@ -6,7 +6,7 @@ These options come in two flavors:
|
||||
|
||||
* **Configuration options** are used to alter the default behavior of GDAL
|
||||
and OGR and are generally treated as global environment variables by GDAL. These
|
||||
are set through a :class:`rasterio.Env()` context block in Python.
|
||||
are set through a :class:`rasterio.Env` context block in Python.
|
||||
|
||||
* **Creation options** are passed into the driver at dataset creation time as
|
||||
keyword arguments to ``rasterio.open(mode='w')``.
|
||||
@ -18,7 +18,7 @@ GDAL options are typically set as environment variables. While
|
||||
environment variables will influence the behavior of ``rasterio``, we
|
||||
highly recommended avoiding them in favor of defining behavior programatically.
|
||||
|
||||
The preferred way to set options for rasterio is via :class:`rasterio.Env()`.
|
||||
The preferred way to set options for rasterio is via :class:`rasterio.Env`.
|
||||
Options set on entering the context are deleted on exit.
|
||||
|
||||
.. code-block:: python
|
||||
@ -51,7 +51,7 @@ Some of the common GeoTIFF creation options include:
|
||||
* ``PHOTOMETRIC`` to define the band's color interpretation
|
||||
|
||||
To specify these creation options in python code, you pass them as keyword arguments
|
||||
to the :func:`rasterio.open()` command in write mode.
|
||||
to the :func:`rasterio.open` command in write mode.
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
|
||||
@ -19,7 +19,7 @@ This shapefile contains a single polygon, a box near the center of the raster, s
|
||||
out_image, out_transform = rasterio.mask.mask(src, shapes, crop=True)
|
||||
out_meta = src.meta
|
||||
|
||||
Using ``plot`` and ``imshow`` from ``matplotlib``, we can see the region defined by the shapefile in red overlaid on the original raster.
|
||||
Using :func:`matplotlib.pyplot.plot` and :func:`matplotlib.pyplot.imshow`, we can see the region defined by the shapefile in red overlaid on the original raster.
|
||||
|
||||
.. image:: ../img/box_rgb.png
|
||||
|
||||
|
||||
@ -47,7 +47,7 @@ Reading dataset masks
|
||||
---------------------
|
||||
|
||||
For every band of a dataset there is a mask. These masks can be had as arrays
|
||||
using the dataset's `read_masks()`` method. Below, ``msk`` is the valid data
|
||||
using the dataset's :meth:`~.DatasetReader.read_masks` method. Below, ``msk`` is the valid data
|
||||
mask corresponding to the first dataset band.
|
||||
|
||||
.. code-block:: python
|
||||
@ -85,7 +85,7 @@ Displayed using :func:`matplotlib.pyplot.imshow`, the mask looks like this:
|
||||
Wait, what are these 0 values in the mask interior? This is an example of
|
||||
a problem inherent in 8-bit raster data: lack of dynamic range. The dataset
|
||||
creator has said that 0 values represent missing data (see the
|
||||
``nodatavals`` property in the first code block of this document), but some of
|
||||
:attr:`~.DatasetReader.nodatavals` property in the first code block of this document), but some of
|
||||
the valid data have values so low they've been rounded during processing to
|
||||
zero. This can happen in scaling 16-bit data to 8 bits. There's
|
||||
no magic nodata value bullet for this. Using 16 bits per band helps, but you
|
||||
@ -96,8 +96,8 @@ Writing masks
|
||||
|
||||
Writing a mask that applies to all dataset bands is just as straightforward:
|
||||
pass an ndarray with ``True`` (or values that evaluate to ``True`` to indicate
|
||||
valid data and ``False`` to indicate no data to ``write_mask()``. Consider a
|
||||
copy of the test data opened in "r+" (update) mode.
|
||||
valid data and ``False`` to indicate no data to :meth:`~.DatasetWriter.write_mask`.
|
||||
Consider a copy of the test data opened in "r+" (update) mode.
|
||||
|
||||
|
||||
.. code-block:: python
|
||||
@ -161,7 +161,7 @@ masks we've read.
|
||||
|
||||
.. image:: ../img/mask_conj.png
|
||||
|
||||
Now we'll use `sieve()` to shake out the small buggy regions of the mask. I've
|
||||
Now we'll use :func:`~rasterio.features.sieve` to shake out the small buggy regions of the mask. I've
|
||||
found the right value for the ``size`` argument empirically.
|
||||
|
||||
.. code-block:: python
|
||||
@ -221,7 +221,7 @@ Dataset masks
|
||||
|
||||
Sometimes a per-band mask is not appropriate. In this case you can either
|
||||
construct a mask out of the component bands (or other auxillary data) manually
|
||||
*or* use the Rasterio dataset's ``src.dataset_mask()`` function. This returns
|
||||
*or* use the Rasterio dataset's :meth:`~.DatasetReader.dataset_mask` function. This returns
|
||||
a 2D array with a GDAL-style mask determined by the following criteria,
|
||||
in order of precedence:
|
||||
|
||||
@ -244,7 +244,7 @@ and configuration options. While Rasterio provides an abstraction for those
|
||||
details when reading, it's often important to understand the differences when
|
||||
creating, manipulating and writing raster data.
|
||||
|
||||
* **Nodata values**: the ``src.nodata`` value is used to define which pixels should be masked.
|
||||
* **Nodata values**: the :attr:`~.DatasetReader.nodata` value is used to define which pixels should be masked.
|
||||
* **Alpha band**: with RGB imagery, an additional 4th band (containing a GDAL-style 8-bit mask) is sometimes provided to explictly define the mask.
|
||||
* **Internal mask band**: GDAL provides the ability to store an additional boolean 1-bit mask that is stored internally to the dataset. This option relies on a GDAL environment with ``GDAL_TIFF_INTERNAL_MASK=True``. Otherwise the mask will be written externally.
|
||||
* **External mask band**: Same as above but the mask band is stored in a sidecar ``.msk`` file (default).
|
||||
|
||||
@ -25,14 +25,14 @@ One is the use of a temporary file on disk.
|
||||
with rasterio.open(tmpfile.name) as dataset:
|
||||
data_array = dataset.read()
|
||||
|
||||
Another is Rasterio's ``MemoryFile``, an abstraction for objects in GDAL's
|
||||
Another is Rasterio's :class:`.MemoryFile`, an abstraction for objects in GDAL's
|
||||
in-memory filesystem.
|
||||
|
||||
MemoryFile: BytesIO meets NamedTemporaryFile
|
||||
--------------------------------------------
|
||||
|
||||
The ``MemoryFile`` class behaves a bit like ``BytesIO`` and
|
||||
``NamedTemporaryFile``. A GeoTIFF file in a sequence of ``data`` bytes can be
|
||||
The :class:`.MemoryFile` class behaves a bit like :class:`~io.BytesIO` and
|
||||
:func:`~tempfile.NamedTemporaryFile`. A GeoTIFF file in a sequence of ``data`` bytes can be
|
||||
opened in memory as shown below.
|
||||
|
||||
.. code-block:: python
|
||||
@ -45,12 +45,12 @@ opened in memory as shown below.
|
||||
data_array = dataset.read()
|
||||
|
||||
This code can be several times faster than the code using
|
||||
``NamedTemporaryFile`` at roughly double the price in memory.
|
||||
:func:`~tempfile.NamedTemporaryFile` at roughly double the price in memory.
|
||||
|
||||
Writing MemoryFiles
|
||||
-------------------
|
||||
|
||||
Incremental writes to an empty ``MemoryFile`` are also possible.
|
||||
Incremental writes to an empty :class:`.MemoryFile` are also possible.
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
@ -63,10 +63,10 @@ Incremental writes to an empty ``MemoryFile`` are also possible.
|
||||
with memfile.open() as dataset:
|
||||
data_array = dataset.read()
|
||||
|
||||
These two modes are incompatible: a ``MemoryFile`` initialized with a sequence
|
||||
These two modes are incompatible: a :class:`.MemoryFile` initialized with a sequence
|
||||
of bytes cannot be extended.
|
||||
|
||||
An empty ``MemoryFile`` can also be written to using dataset API methods.
|
||||
An empty :class:`.MemoryFile` can also be written to using dataset API methods.
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
@ -77,9 +77,10 @@ An empty ``MemoryFile`` can also be written to using dataset API methods.
|
||||
Reading MemoryFiles
|
||||
-------------------
|
||||
|
||||
Like ``BytesIO``, ``MemoryFile`` implements the Python file protocol and
|
||||
provides ``read()``, ``seek()``, and ``tell()`` methods. Instances are thus suitable
|
||||
as arguments for methods like `requests.post() <https://requests.readthedocs.io/en/latest/api/#requests.post>`__.
|
||||
Like :class:`~io.BytesIO`, :class:`.MemoryFile` implements the Python file protocol and
|
||||
provides :meth:`~.MemoryFile.read`, :meth:`~.MemoryFile.seek`, and :meth:`~.MemoryFile.tell`
|
||||
methods. Instances are thus suitable as arguments for methods like
|
||||
`requests.post() <https://requests.readthedocs.io/en/latest/api/#requests.post>`__.
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
|
||||
@ -25,7 +25,7 @@ these are exponents of 2
|
||||
|
||||
To control the visual quality of the overviews, the 'nearest', 'cubic',
|
||||
'average', 'mode', and 'gauss' resampling alogrithms are available. These are
|
||||
available through the ``Resampling`` enum
|
||||
available through the :class:`.Resampling` enum
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
|
||||
@ -3,7 +3,7 @@ Profiles and Writing Files
|
||||
|
||||
How to use profiles when opening files.
|
||||
|
||||
Like Python's built-in ``open()`` function, :func:`rasterio.open()` has two primary
|
||||
Like Python's built-in :func:`open` function, :func:`rasterio.open` has two primary
|
||||
arguments: a path (or URL) and an optional mode (``'r'``, ``'w'``, ``'r+'``, or
|
||||
``'w+'``). In addition there are a number of keyword arguments, several of
|
||||
which are required when creating a new dataset:
|
||||
|
||||
@ -14,8 +14,8 @@ Reading Datasets
|
||||
|
||||
|
||||
Dataset objects provide read, read-write, and write access to raster data files
|
||||
and are obtained by calling ``rasterio.open()``. That function mimics Python's
|
||||
built-in ``open()`` and the dataset objects it returns mimic Python ``file``
|
||||
and are obtained by calling :func:`rasterio.open`. That function mimics Python's
|
||||
built-in :func:`open` and the dataset objects it returns mimic Python ``file``
|
||||
objects.
|
||||
|
||||
.. code-block:: python
|
||||
@ -31,8 +31,8 @@ objects.
|
||||
>>> src.closed
|
||||
False
|
||||
|
||||
If you try to access a nonexistent path, ``rasterio.open()`` does the same
|
||||
thing as ``open()``, raising an exception immediately.
|
||||
If you try to access a nonexistent path, :func:`rasterio.open` does the same
|
||||
thing as :func:`open`, raising an exception immediately.
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
@ -87,7 +87,8 @@ In order to read smaller chunks of the dataset, refer to :ref:`windowrw`.
|
||||
|
||||
|
||||
The indexes, Numpy data types, and nodata values of all a dataset's bands can
|
||||
be had from its ``indexes``, ``dtypes``, and ``nodatavals`` attributes.
|
||||
be had from its :attr:`~.DatasetReader.indexes`, :attr:`~.DatasetReader.dtypes`,
|
||||
and :attr:`~.DatasetReader.nodatavals` attributes.
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
@ -98,7 +99,7 @@ be had from its ``indexes``, ``dtypes``, and ``nodatavals`` attributes.
|
||||
2 uint8 0.0
|
||||
3 uint8 0.0
|
||||
|
||||
To close a dataset, call its ``close()`` method.
|
||||
To close a dataset, call its :meth:`~.DatasetReader.close` method.
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
|
||||
@ -6,11 +6,11 @@ coordinate reference system and transform to the pixels of a source image with
|
||||
a different coordinate reference system and transform. This process is known as
|
||||
reprojection.
|
||||
|
||||
Rasterio's :func:`rasterio.warp.reproject()` is a geospatial-specific analog
|
||||
Rasterio's :func:`rasterio.warp.reproject` is a geospatial-specific analog
|
||||
to SciPy's ``scipy.ndimage.interpolation.geometric_transform()`` [1]_.
|
||||
|
||||
The code below reprojects between two arrays, using no pre-existing GIS
|
||||
datasets. :func:`rasterio.warp.reproject()` has two positional arguments: source
|
||||
datasets. :func:`rasterio.warp.reproject` has two positional arguments: source
|
||||
and destination. The remaining keyword arguments parameterize the reprojection
|
||||
transform.
|
||||
|
||||
@ -62,7 +62,7 @@ correct: https://a.tiles.mapbox.com/v3/sgillies.hfek2oko/page.html?secure=1#6/0.
|
||||
Estimating optimal output shape
|
||||
-------------------------------
|
||||
|
||||
Rasterio provides a :func:`rasterio.warp.calculate_default_transform()` function to
|
||||
Rasterio provides a :func:`rasterio.warp.calculate_default_transform` function to
|
||||
determine the optimal resolution and transform for the destination raster.
|
||||
Given a source dataset in a known coordinate reference system, this
|
||||
function will return a ``transform, width, height`` tuple which is calculated
|
||||
@ -74,13 +74,13 @@ Reprojecting a GeoTIFF dataset
|
||||
Reprojecting a GeoTIFF dataset from one coordinate reference system is a common
|
||||
use case. Rasterio provides a few utilities to make this even easier:
|
||||
|
||||
:func:`~rasterio.warp.transform_bounds()`
|
||||
:func:`~rasterio.warp.transform_bounds`
|
||||
transforms the bounding coordinates of the source raster to the target
|
||||
coordinate reference system, densifiying points along the edges to account
|
||||
for non-linear transformations of the edges.
|
||||
|
||||
|
||||
:func:`~rasterio.warp.calculate_default_transform()`
|
||||
:func:`~rasterio.warp.calculate_default_transform`
|
||||
transforms bounds to target coordinate system, calculates resolution if not
|
||||
provided, and returns destination transform and dimensions.
|
||||
|
||||
@ -120,7 +120,7 @@ See ``rasterio/rio/warp.py`` for more complex examples of reprojection based on
|
||||
new bounds, dimensions, and resolution (as well as a command-line interface
|
||||
described :ref:`here <warp>`).
|
||||
|
||||
It is also possible to use :func:`~rasterio.warp.reproject()` to create an output dataset zoomed
|
||||
It is also possible to use :func:`~rasterio.warp.reproject` to create an output dataset zoomed
|
||||
out by a factor of 2. Methods of the :class:`rasterio.Affine` class help us generate
|
||||
the output dataset's transform matrix and, thereby, its spatial extent.
|
||||
|
||||
|
||||
@ -57,7 +57,7 @@ When you change the raster cell grid, you must recalculate the pixel values.
|
||||
There is no "correct" way to do this as all methods involve some interpolation.
|
||||
|
||||
The current resampling methods can be found in the
|
||||
:class:`rasterio.enums.Resampling()` class.
|
||||
:class:`rasterio.enums.Resampling` class.
|
||||
|
||||
Of note, the default :attr:`~rasterio.enums.Resampling.nearest` method may not
|
||||
be suitable for continuous data. In those cases,
|
||||
|
||||
@ -46,11 +46,11 @@ for the environment, but it can be modified using functions like
|
||||
``gdal.SetErrorHandler()`` and ``gdal.UseExceptions()``.
|
||||
|
||||
Rasterio has modules that don't require complete initialization and
|
||||
configuration of GDAL (``rasterio.dtypes``, ``rasterio.profiles``, and
|
||||
``rasterio.windows``, for example) and in the interest of reducing overhead
|
||||
configuration of GDAL (:mod:`rasterio.dtypes`, :mod:`rasterio.profiles`, and
|
||||
:mod:`rasterio.windows`, for example) and in the interest of reducing overhead
|
||||
doesn't register format drivers and error handlers until they are needed. The
|
||||
functions that do need fully initialized GDAL environments will ensure that
|
||||
they exist. ``rasterio.open()`` is the foremost of this category of functions.
|
||||
they exist. :func:`rasterio.open` is the foremost of this category of functions.
|
||||
Consider the example code below.
|
||||
|
||||
.. code-block:: python
|
||||
@ -64,10 +64,10 @@ Consider the example code below.
|
||||
# open() executes.
|
||||
|
||||
Importing ``rasterio`` does not initialize the GDAL environment. Calling
|
||||
``rasterio.open()`` does. This is different from ``gdal`` where ``import
|
||||
:func:`rasterio.open` does. This is different from ``gdal`` where ``import
|
||||
osgeo.gdal``, not ``osgeo.gdal.Open()``, initializes the GDAL environment.
|
||||
|
||||
Rasterio has an abstraction for the GDAL environment, ``rasterio.Env``, that
|
||||
Rasterio has an abstraction for the GDAL environment, :class:`rasterio.Env`, that
|
||||
can be invoked explicitly for more control over the configuration of GDAL as
|
||||
shown below.
|
||||
|
||||
@ -131,7 +131,7 @@ Format Drivers
|
||||
|
||||
``gdal`` provides objects for each of the GDAL format drivers. With Rasterio,
|
||||
format drivers are represented by strings and are used only as arguments to
|
||||
functions like ``rasterio.open()``.
|
||||
functions like :func:`rasterio.open`.
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
@ -175,12 +175,12 @@ Dataset Objects
|
||||
|
||||
Rasterio and ``gdal`` each have dataset objects. Not the same classes, of
|
||||
course, but not radically different ones. In each case, you generally get
|
||||
dataset objects through an "opener" function: ``rasterio.open()`` or
|
||||
dataset objects through an "opener" function: :func:`rasterio.open` or
|
||||
``gdal.Open()``.
|
||||
|
||||
So that Python developers can spend less time reading docs, the dataset object
|
||||
returned by ``rasterio.open()`` is modeled on Python's file object. It even has
|
||||
the ``close()`` method that ``gdal`` lacks so that you can actively close
|
||||
returned by :func:`rasterio.open` is modeled on Python's file object. It even has
|
||||
the :meth:`~.DatasetReader.close` method that ``gdal`` lacks so that you can actively close
|
||||
dataset connections.
|
||||
|
||||
Bands
|
||||
@ -249,12 +249,12 @@ Namedtuples are like lightweight classes.
|
||||
Geotransforms
|
||||
-------------
|
||||
|
||||
The ``transform`` attribute of a Rasterio dataset object is comparable to the
|
||||
The :attr:`.DatasetReader.transform` attribute is comparable to the
|
||||
``GeoTransform`` attribute of a GDAL dataset, but Rasterio's has more power.
|
||||
It's not just an array of affine transformation matrix elements, it's an
|
||||
instance of an ``Affine`` class and has many handy methods. For example, the
|
||||
spatial coordinates of the upper left corner of any raster element is the
|
||||
product of the dataset's ``transform`` matrix and the ``(column, row)`` index
|
||||
product of the :attr:`.DatasetReader.transform` matrix and the ``(column, row)`` index
|
||||
of the element.
|
||||
|
||||
.. code-block:: pycon
|
||||
@ -284,14 +284,15 @@ converted to the sequences used by ``gdal``.
|
||||
Coordinate Reference Systems
|
||||
----------------------------
|
||||
|
||||
The ``crs`` attribute of a Rasterio dataset object is an instance of Rasterio's
|
||||
``CRS`` class and works well with ``pyproj``.
|
||||
The :attr:`.DatasetReader.crs` attribute is an instance of Rasterio's
|
||||
:meth:`.CRS` class and works well with ``pyproj``.
|
||||
|
||||
.. code-block:: pycon
|
||||
|
||||
>>> from pyproj import Proj, transform
|
||||
>>> from pyproj import Transformer
|
||||
>>> src = rasterio.open('example.tif')
|
||||
>>> transform(Proj(src.crs), Proj('+init=epsg:3857'), 101985.0, 2826915.0)
|
||||
>>> transformer = Transformer.from_crs(src.crs, "EPSG:3857", always_xy=True)
|
||||
>>> transformer.transfform(101985.0, 2826915.0)
|
||||
(-8789636.707871985, 2938035.238323653)
|
||||
|
||||
Tags
|
||||
|
||||
@ -19,7 +19,7 @@ I'm going to use the rasterio interactive inspector in these examples below.
|
||||
>>>
|
||||
|
||||
Tags belong to namespaces. To get a copy of a dataset's tags from the default
|
||||
namespace, call ``tags()`` with no arguments.
|
||||
namespace, call :meth:`~.DatasetReader.tags` with no arguments.
|
||||
|
||||
.. code-block:: pycon
|
||||
|
||||
@ -29,7 +29,7 @@ namespace, call ``tags()`` with no arguments.
|
||||
{'AREA_OR_POINT': 'Area'}
|
||||
|
||||
A dataset's bands may have tags, too. Here are the tags from the default namespace
|
||||
for the first band, accessed using the positional band index argument of ``tags()``.
|
||||
for the first band, accessed using the positional band index argument of :meth:`~.DatasetReader.tags`.
|
||||
|
||||
.. code-block:: pycon
|
||||
|
||||
@ -42,7 +42,7 @@ update of the tags when the band's image data changes.
|
||||
|
||||
The 3 standard, non-default GDAL tag namespaces are 'SUBDATASETS', 'IMAGE_STRUCTURE',
|
||||
and 'RPC'. You can get the tags from these namespaces using the `ns` keyword of
|
||||
``tags()``.
|
||||
:meth:`~.DatasetReader.tags`.
|
||||
|
||||
.. code-block:: pycon
|
||||
|
||||
@ -62,7 +62,7 @@ Writing tags
|
||||
------------
|
||||
|
||||
You can add new tags to a dataset or band, in the default or another namespace,
|
||||
using the ``update_tags()`` method. Unicode tag values, too, at least for TIFF
|
||||
using the :meth:`~.DatasetWriter.update_tags` method. Unicode tag values, too, at least for TIFF
|
||||
files.
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
@ -4,14 +4,15 @@ Transforms
|
||||
Rasterio supports three primary methods for transforming of coordinates from
|
||||
image pixel (row, col) to and from geographic/projected (x, y) coordinates.
|
||||
The interface for performing these coordinate transformations is available
|
||||
in ``rasterio.transforms`` through one of ``AffineTransformer``,
|
||||
``GCPTransformer``, or ``RPCTransformer``. The methods ``xy`` and ``rowcol``
|
||||
in :mod:`rasterio.transform` through one of :class:`.AffineTransformer`,
|
||||
:class:`.GCPTransformer`, or :class:`.RPCTransformer`.
|
||||
The methods :meth:`~.DatasetReader.xy` and :meth:`~rasterio.transform.rowcol`
|
||||
are responsible for converting between (row, col) -> (x, y) and (x, y) ->
|
||||
(row, col), respectively.
|
||||
|
||||
Using Affine transformation matrix
|
||||
-----------------------------------
|
||||
``rasterio.transform.AffineTransformer`` takes care of coordinate transformations
|
||||
:class:`.AffineTransformer` takes care of coordinate transformations
|
||||
given an Affine transformation matrix. For example
|
||||
|
||||
.. code-block:: python
|
||||
@ -35,7 +36,7 @@ This is approximately equivalent to
|
||||
>>> ~transform * (102135.01896333754, 2826764.979108635)
|
||||
(0.5, 0.5)
|
||||
|
||||
The dataset methods ``xy`` and ``index`` use ``rasterio.transform`` under the hood
|
||||
The dataset methods :meth:`~.DatasetReader.xy` and :meth:`~.DatasetReader.index` use :mod:`rasterio.transform` under the hood
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
@ -58,7 +59,7 @@ Using Ground Control Points
|
||||
|
||||
Using Rational Polynomial Coefficients
|
||||
---------------------------------------
|
||||
For accuracy a height value is typically required when using ``RPCTransformer``. By default,
|
||||
For accuracy a height value is typically required when using :class:`.RPCTransformer`. By default,
|
||||
a value of 0 is assumed.
|
||||
|
||||
.. code-block:: python
|
||||
@ -78,7 +79,7 @@ A first order correction would be to use a mean elevation value for the image
|
||||
(-123.48096552376548, 49.528097381526386)
|
||||
|
||||
Better yet is to sample height values from a digital elevation model (DEM).
|
||||
``RPCTransformer`` allows for options to be passed to ``GDALCreateRPCTransformer``
|
||||
:class:`.RPCTransformer` allows for options to be passed to :cpp:func:`GDALCreateRPCTransformerV2`
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
@ -87,13 +88,10 @@ Better yet is to sample height values from a digital elevation model (DEM).
|
||||
transformer.xy(0, 0)
|
||||
(-123.47954729595642, 49.5279448909449)
|
||||
|
||||
See https://gdal.org/api/gdal_alg.html?highlight=gdalcreaterpctransformer#_CPPv426GDALCreateRPCTransformerV2PK13GDALRPCInfoV2idPPc
|
||||
for more details.
|
||||
|
||||
Transformer Resources
|
||||
----------------------
|
||||
The ``AffineTransformer`` is a pure Python class, however ``GCPTransformer``
|
||||
and ``RPCTransformer`` make use of C/C++ GDAL objects. Explicit control of
|
||||
The :class:`.AffineTransformer` is a pure Python class, however :class:`.GCPTransformer`
|
||||
and :class:`.RPCTransformer` make use of C/C++ GDAL objects. Explicit control of
|
||||
the transformer object can be achieved by use within a context manager or
|
||||
by calling ``close()`` method e.g.
|
||||
|
||||
|
||||
@ -1,9 +1,9 @@
|
||||
Virtual Warping
|
||||
===============
|
||||
|
||||
Rasterio has a ``WarpedVRT`` class that abstracts many of the details of raster
|
||||
Rasterio has a :class:`.WarpedVRT` class that abstracts many of the details of raster
|
||||
warping by using an in-memory `Warped VRT
|
||||
<http://www.gdal.org/gdal_vrttut.html#gdal_vrttut_warped>`__. A ``WarpedVRT`` can
|
||||
<http://www.gdal.org/gdal_vrttut.html#gdal_vrttut_warped>`__. A :class:`.WarpedVRT` can
|
||||
be the easiest solution for tiling large datasets.
|
||||
|
||||
For example, to virtually warp the ``RGB.byte.tif`` test dataset from its
|
||||
@ -58,7 +58,7 @@ extract pixels corresponding to its central zoom 9 tile, do the following.
|
||||
Normalizing Data to a Consistent Grid
|
||||
-------------------------------------
|
||||
|
||||
A ``WarpedVRT`` can be used to normalize a stack of images with differing
|
||||
A :class:`.WarpedVRT` can be used to normalize a stack of images with differing
|
||||
projections, bounds, cell sizes, or dimensions against a regular grid
|
||||
in a defined bounding box.
|
||||
|
||||
|
||||
@ -10,7 +10,7 @@ computers RAM or process chunks of large rasters in parallel.
|
||||
Windows
|
||||
-------
|
||||
|
||||
A window is a view onto a rectangular subset of a raster dataset and is
|
||||
A :class:`.Window` is a view onto a rectangular subset of a raster dataset and is
|
||||
described in rasterio by column and row offsets and width and height
|
||||
in pixels. These may be ints or floats.
|
||||
|
||||
@ -28,7 +28,7 @@ Only int values are permitted in these cases.
|
||||
Window.from_slices((row_start, row_stop), (col_start, col_stop))
|
||||
Window.from_slices(slice(row_start, row_stop), slice(col_start, col_stop))
|
||||
|
||||
If height and width keyword arguments are passed to ``from_slices``, relative
|
||||
If height and width keyword arguments are passed to :meth:`~.Window.from_slices`, relative
|
||||
and open-ended slices may be used.
|
||||
|
||||
.. code-block:: python
|
||||
@ -109,7 +109,7 @@ Data windows
|
||||
------------
|
||||
|
||||
Sometimes it is desirable to crop off an outer boundary of NODATA values around
|
||||
a dataset:
|
||||
a dataset. You can do this with :func:`.get_data_window`:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
@ -132,7 +132,7 @@ Window transforms
|
||||
-----------------
|
||||
|
||||
The affine transform of a window can be accessed using a dataset's
|
||||
``window_transform`` method:
|
||||
:meth:`~.DatasetReader.window_transform` method:
|
||||
|
||||
.. code-block:: pycon
|
||||
|
||||
@ -203,9 +203,9 @@ The block windows themselves can be had from the block_windows function.
|
||||
...
|
||||
|
||||
This function returns an iterator that yields a pair of values. The second is
|
||||
a window tuple that can be used in calls to `read` or `write`. The first
|
||||
is the pair of row and column indexes of this block within all blocks of the
|
||||
dataset.
|
||||
a window tuple that can be used in calls to :meth:`~.DatasetReader.read`
|
||||
or :meth:`~.DatasetWriter.write`. The first is the pair of row and column
|
||||
indexes of this block within all blocks of the dataset.
|
||||
|
||||
You may read windows of data from a file block-by-block like this.
|
||||
|
||||
|
||||
@ -50,15 +50,15 @@ Supported Drivers
|
||||
-----------------
|
||||
``GTiff`` is the only driver that supports writing directly to disk.
|
||||
GeoTiffs use the ``RasterUpdater`` and leverage the full capabilities
|
||||
of the ``GDALCreate`` function. We highly recommend using GeoTiff
|
||||
of the :cpp:func:`GDALCreate` function. We highly recommend using GeoTiff
|
||||
driver for writing as it is the best-tested and best-supported format.
|
||||
|
||||
Some other formats that are writable by GDAL can also be written by
|
||||
Rasterio. These use an ``IndirectRasterUpdater`` which does not create
|
||||
directly but uses a temporary in-memory dataset and ``GDALCreateCopy``
|
||||
directly but uses a temporary in-memory dataset and :cpp:func:`GDALCreateCopy`
|
||||
to produce the final output.
|
||||
|
||||
Some formats are known to produce invalid results using the
|
||||
``IndirectRasterUpdater``. These formats will raise a ``RasterioIOError``
|
||||
``IndirectRasterUpdater``. These formats will raise a :class:`.RasterioIOError`
|
||||
if you attempt to write to the. Currently this applies to the ``netCDF``
|
||||
driver but please let us know if you experience problems writing other formats.
|
||||
|
||||
@ -54,7 +54,7 @@ with rasterio._loading.add_gdal_dll_directories():
|
||||
pass
|
||||
have_vsi_plugin = False
|
||||
|
||||
__all__ = ['band', 'open', 'pad', 'Env', 'CRS']
|
||||
__all__ = ['band', 'open', 'pad', 'Band', 'Env', 'CRS']
|
||||
__version__ = "1.4dev"
|
||||
__gdal_version__ = gdal_version()
|
||||
__proj_version__ = ".".join([str(version) for version in get_proj_version()])
|
||||
@ -310,6 +310,20 @@ def open(fp, mode='r', driver=None, width=None, height=None, count=None,
|
||||
|
||||
|
||||
Band = namedtuple('Band', ['ds', 'bidx', 'dtype', 'shape'])
|
||||
Band.__doc__ = """
|
||||
Band of a Dataset.
|
||||
|
||||
Parameters
|
||||
----------
|
||||
ds: dataset object
|
||||
An opened rasterio dataset object.
|
||||
bidx: int or sequence of ints
|
||||
Band number(s), index starting at 1.
|
||||
dtype: str
|
||||
rasterio data type of the data.
|
||||
shape: tuple
|
||||
Width, height of band.
|
||||
"""
|
||||
|
||||
|
||||
def band(ds, bidx):
|
||||
@ -324,7 +338,7 @@ def band(ds, bidx):
|
||||
|
||||
Returns
|
||||
-------
|
||||
rasterio.Band
|
||||
Band
|
||||
"""
|
||||
return Band(ds, bidx, set(ds.dtypes).pop(), ds.shape)
|
||||
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user