archive-gh-me/rasterio
1
0
Fork 0
mirror of https://github.com/rasterio/rasterio.git synced 2025-12-08 17:36:12 +00:00
Code Issues Projects Releases Wiki Activity

DOC: Add intersphinx for matplotlib & numpy (#2527)

Browse Source
This commit is contained in:
Alan D. Snow 2022-07-21 17:52:22 -05:00 committed by GitHub
parent f1ad179d63
commit c17bc35a80
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
17 changed files with 60 additions and 64 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
docs/conf.py
View File

@ -367,4 +367,6 @@ epub_exclude_files = ['search.html']
intersphinx_mapping = {
"python": ("https://docs.python.org/", None),
"gdal": ("https://gdal.org/", None),
"numpy": ("https://numpy.org/doc/stable", None),
"matplotlib": ("https://matplotlib.org/stable/", None),
}

2
docs/quickstart.rst
View File

@ -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 Numpy N-D array.
The :meth:`~rasterio.io.DatasetReader.read` method returns a :class:`numpy.ndarray`.
.. code-block:: pycon

8
docs/topics/masks.rst
View File

@ -9,7 +9,7 @@ rows and columns as the dataset in which non-zero elements (typically 255) indic
corresponding data elements are valid. Other elements are invalid, or *nodata*
elements.
The other kind of mask is Numpy's `masked array <http://docs.scipy.org/doc/numpy/reference/maskedarray.generic.html>`__
The other kind of mask is a :class:`numpy.ma.MaskedArray`
which has the inverse sense: `True` values in a masked array's mask indicate
that the corresponding data elements are invalid. With care, you can safely
navigate convert between the two mask types.
@ -78,7 +78,7 @@ array shows the ``255`` values that indicate *valid data* regions.
[255, 255, 255, 255, 255],
[255, 255, 255, 255, 255]], dtype=uint8)
Displayed using Matplotlib's `imshow()`, the mask looks like this:
Displayed using :func:`matplotlib.pyplot.imshow`, the mask looks like this:
.. image:: ../img/mask_band.png
@ -140,7 +140,7 @@ certainly can. Consider a fresh copy of that file.
This time we'll read all 3 band masks
(based on the nodata values, not a .msk GeoTIFF) and show them
as an RGB image (with the help of `numpy.dstack()`):
as an RGB image (with the help of :func:`numpy.dstack`):
.. code-block:: python
@ -185,7 +185,7 @@ considered valid.
Numpy masked arrays
-------------------
If you want, you can read dataset bands as numpy masked arrays.
If you want, you can read dataset bands as a :class:`numpy.ma.MaskedArray`.
.. code-block:: python

2
docs/topics/migrating-to-v1.rst
View File

@ -127,7 +127,7 @@ Removed: ``src.read_band()``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The ``read_band()`` method has been replaced by ``read()``, which allows for
faster I/O and reading multiple bands into a single ``numpy.ndarray()``.
faster I/O and reading multiple bands into a single :class:`numpy.ndarray`.
For example:

2
docs/topics/plotting.rst
View File

@ -24,7 +24,7 @@ The first argument to :func:`~rasterio.plot.show` represent the data source to b
* A dataset object opened in 'r' mode
* A single band of a source, represented by a ``(src, band_index)`` tuple
* A numpy ndarray, 2D or 3D. If the array is 3D, ensure that it is in rasterio band order.
* A :class:`numpy.ndarray`, 2D or 3D. If the array is 3D, ensure that it is in rasterio band order.
Thus the following operations for 3-band RGB data are equivalent. Note that when passing arrays,
you can pass in a transform in order to get extent labels.

2
docs/topics/reading.rst
View File

@ -55,7 +55,7 @@ a file can be read like this:
>>> array.shape
(718, 791)
The returned object is a 2-dimensional Numpy ndarray. The representation of
The returned object is a 2-dimensional :class:`numpy.ndarray`. The representation of
that array at the Python prompt is a summary; the GeoTIFF file that
Rasterio uses for testing has 0 values in the corners, but has nonzero values
elsewhere.

4
docs/topics/switch.rst
View File

@ -192,7 +192,7 @@ band index and some other band properties.
Thus Rasterio never has objects with dangling dataset pointers.
With Rasterio, bands are represented by a numerical
index, starting from 1 (as GDAL does), and are used as arguments to dataset
methods. To read the first band of a dataset as a Numpy ``ndarray``, do this.
methods. To read the first band of a dataset as a :class:`numpy.ndarray`, do this.
.. code-block:: python
@ -349,7 +349,7 @@ data.
[0, 0, 0, ..., 0, 0, 0],
[0, 0, 0, ..., 0, 0, 0]], dtype-uint8)
Arrays for dataset bands can also be had as a Numpy ``masked_array``.
Arrays for dataset bands can also be had as a :class:`numpy.ma.MaskedArray`.
.. code-block:: pycon

9
rasterio/__init__.py
View File

@ -128,9 +128,9 @@ def open(fp, mode='r', driver=None, width=None, height=None, count=None,
Affine transformation mapping the pixel space to geographic
space. Required in 'w' or 'w+' modes, it is ignored in 'r' or
'r+' modes.
dtype : str or numpy dtype
dtype : str or numpy.dtype
The data type for bands. For example: 'uint8' or
``rasterio.uint16``. Required in 'w' or 'w+' modes, it is
:attr:`rasterio.uint16`. Required in 'w' or 'w+' modes, it is
ignored in 'r' or 'r+' modes.
nodata : int, float, or nan; optional
Defines the pixel value to be interpreted as not valid data.
@ -334,7 +334,7 @@ def pad(array, transform, pad_width, mode=None, **kwargs):
Parameters
----------
array: ndarray
array: numpy.ndarray
Numpy ndarray, for best results a 2D array
transform: Affine transform
transform object mapping pixel space to coordinates
@ -350,8 +350,7 @@ def pad(array, transform, pad_width, mode=None, **kwargs):
Notes
-----
See numpy docs for details on mode and other kwargs:
http://docs.scipy.org/doc/numpy-1.10.0/reference/generated/numpy.pad.html
See :func:`numpy.pad` for details on mode and other kwargs.
"""
import numpy as np
transform = guard_transform(transform)

8
rasterio/_features.pyx
View File

@ -25,7 +25,7 @@ def _shapes(image, mask, connectivity, transform):
image : array or dataset object opened in 'r' mode or Band or tuple(dataset, bidx)
Data type must be one of rasterio.int16, rasterio.int32,
rasterio.uint8, rasterio.uint16, or rasterio.float32.
mask : numpy ndarray or rasterio Band object
mask : numpy.ndarray or rasterio Band object
Values of False or 0 will be excluded from feature generation
Must evaluate to bool (rasterio.bool_ or rasterio.uint8)
connectivity : int
@ -160,9 +160,9 @@ def _sieve(image, size, out, mask, connectivity):
rasterio.uint16, or rasterio.float32.
size : int
minimum polygon size (number of pixels) to retain.
out : numpy ndarray
out : numpy.ndarray
Array of same shape and data type as `image` in which to store results.
mask : numpy ndarray or rasterio Band object
mask : numpy.ndarray or rasterio Band object
Values of False or 0 will be excluded from feature generation.
Must evaluate to bool (rasterio.bool_ or rasterio.uint8)
connectivity : int
@ -267,7 +267,7 @@ def _rasterize(shapes, image, transform, all_touched, merge_alg):
----------
shapes : iterable of (geometry, value) pairs
`geometry` is a GeoJSON-like object.
image : numpy ndarray
image : numpy.ndarray
Array in which to store results.
transform : Affine transformation object, optional
Transformation from pixel coordinates of `image` to the

18
rasterio/_io.pyx
View File

@ -318,7 +318,7 @@ cdef bint in_dtype_range(value, dtype):
cdef int io_auto(data, GDALRasterBandH band, bint write, int resampling=0) except -1:
"""Convenience function to handle IO with a GDAL band.
:param data: a numpy ndarray
:param data: a numpy.ndarray
:param band: an instance of GDALGetRasterBand
:param write: 1 (True) uses write mode (writes data into band),
0 (False) uses read mode (reads band into data)
@ -405,7 +405,7 @@ cdef class DatasetReaderBase(DatasetBase):
indexes : int or list, optional
If `indexes` is a list, the result is a 3D array, but is
a 2D array if it is a band index number.
out : numpy ndarray, optional
out : numpy.ndarray, optional
As with Numpy ufuncs, this is an optional reference to an
output array into which data will be placed. If the height
and width of `out` differ from that of the specified
@ -416,7 +416,7 @@ cdef class DatasetReaderBase(DatasetBase):
*Note*: the method's return value may be a view on this
array. In other words, `out` is likely to be an
incomplete representation of the method's results.
out_dtype : str or numpy dtype
out_dtype : str or numpy.dtype
The desired output data type. For example: 'uint8' or
rasterio.uint16.
out_shape : tuple, optional
@ -442,7 +442,7 @@ cdef class DatasetReaderBase(DatasetBase):
are not cached.
fill_value : scalar
Fill value applied in the `boundless=True` case only. Like
the fill_value of numpy.ma.MaskedArray, should be value
the fill_value of :class:`numpy.ma.MaskedArray`, should be value
valid for the dataset's data type.
Returns
@ -708,7 +708,7 @@ cdef class DatasetReaderBase(DatasetBase):
indexes : int or list, optional
If `indexes` is a list, the result is a 3D array, but is
a 2D array if it is a band index number.
out : numpy ndarray, optional
out : numpy.ndarray, optional
As with Numpy ufuncs, this is an optional reference to an
output array into which data will be placed. If the height
and width of `out` differ from that of the specified
@ -944,7 +944,7 @@ cdef class DatasetReaderBase(DatasetBase):
Parameters
----------
out : numpy ndarray, optional
out : numpy.ndarray, optional
As with Numpy ufuncs, this is an optional reference to an
output array with the same dimensions and shape into which
data will be placed.
@ -1327,7 +1327,7 @@ cdef class DatasetWriterBase(DatasetReaderBase):
Affine transformation mapping the pixel space to geographic
space. Required in 'w' or 'w+' modes, it is ignored in 'r' or
'r+' modes.
dtype : str or numpy dtype
dtype : str or numpy.dtype
The data type for bands. For example: 'uint8' or
``rasterio.uint16``. Required in 'w' or 'w+' modes, it is
ignored in 'r' or 'r+' modes.
@ -1640,7 +1640,7 @@ cdef class DatasetWriterBase(DatasetReaderBase):
Parameters
----------
arr : array-like
This may be a numpy MaskedArray.
This may be a :class:`numpy.ma.MaskedArray`.
indexes : int or list, optional
Which bands of the dataset to write to. The default is all.
window : Window, optional
@ -2137,7 +2137,7 @@ cdef class BufferedDatasetWriterBase(DatasetWriterBase):
Affine transformation mapping the pixel space to geographic
space. Required in 'w' or 'w+' modes, it is ignored in 'r' or
'r+' modes.
dtype : str or numpy dtype
dtype : str or numpy.dtype
The data type for bands. For example: 'uint8' or
``rasterio.uint16``. Required in 'w' or 'w+' modes, it is
ignored in 'r' or 'r+' modes.

6
rasterio/_warp.pyx
View File

@ -1168,7 +1168,7 @@ cdef class WarpedVRTReaderBase(DatasetReaderBase):
If `indexes` is a list, the result is a 3D array, but is
a 2D array if it is a band index number.
out : numpy ndarray, optional
out : numpy.ndarray, optional
As with Numpy ufuncs, this is an optional reference to an
output array into which data will be placed. If the height
and width of `out` differ from that of the specified
@ -1182,7 +1182,7 @@ cdef class WarpedVRTReaderBase(DatasetReaderBase):
This parameter cannot be combined with `out_shape`.
out_dtype : str or numpy dtype
out_dtype : str or numpy.dtype
The desired output data type. For example: 'uint8' or
rasterio.uint16.
@ -1222,7 +1222,7 @@ cdef class WarpedVRTReaderBase(DatasetReaderBase):
Returns
-------
Numpy ndarray or a view on a Numpy ndarray
numpy.ndarray or a view on a numpy.ndarray
Note: as with Numpy ufuncs, an object is returned even if you
use the optional `out` argument and the return value shall be

2
rasterio/dtypes.py
View File

@ -186,7 +186,7 @@ def can_cast_dtype(values, dtype):
Parameters
----------
values: list-like
dtype: numpy dtype or string
dtype: numpy.dtype or string
Returns
-------

26
rasterio/features.py
View File

@ -41,7 +41,7 @@ def geometry_mask(
----------
geometries : iterable over geometries (GeoJSON-like objects)
out_shape : tuple or list
Shape of output numpy ndarray.
Shape of output :class:`numpy.ndarray`.
transform : Affine transformation object
Transformation from pixel coordinates of `source` to the
coordinate system of the input `shapes`. See the `transform`
@ -56,8 +56,8 @@ def geometry_mask(
Returns
-------
numpy ndarray of type 'bool'
Result
numpy.ndarray :
Type is :class:`numpy.bool_`
Notes
-----
@ -81,15 +81,15 @@ def shapes(source, mask=None, connectivity=4, transform=IDENTITY):
Parameters
----------
source : array, dataset object, Band, or tuple(dataset, bidx)
source : numpy.ndarray, dataset object, Band, or tuple(dataset, bidx)
Data type must be one of rasterio.int16, rasterio.int32,
rasterio.uint8, rasterio.uint16, or rasterio.float32.
mask : numpy ndarray or rasterio Band object, optional
mask : numpy.ndarray or rasterio Band object, optional
Must evaluate to bool (rasterio.bool_ or rasterio.uint8). Values
of False or 0 will be excluded from feature generation. Note
well that this is the inverse sense from Numpy's, where a mask
value of True indicates invalid data in an array. If `source` is
a Numpy masked array and `mask` is None, the source's mask will
a :class:`numpy.ma.MaskedArray` and `mask` is None, the source's mask will
be inverted and used in place of `mask`.
connectivity : int, optional
Use 4 or 8 pixel connectivity for grouping pixels into features
@ -142,9 +142,9 @@ def sieve(source, size, out=None, mask=None, connectivity=4):
rasterio.uint16, or rasterio.float32
size : int
minimum polygon size (number of pixels) to retain.
out : numpy ndarray, optional
out : numpy.ndarray, optional
Array of same shape and data type as `source` in which to store results.
mask : numpy ndarray or rasterio Band object, optional
mask : numpy.ndarray or rasterio Band object, optional
Values of False or 0 will be excluded from feature generation
Must evaluate to bool (rasterio.bool_ or rasterio.uint8)
connectivity : int, optional
@ -152,7 +152,7 @@ def sieve(source, size, out=None, mask=None, connectivity=4):
Returns
-------
out : numpy ndarray
out : numpy.ndarray
Result
Notes
@ -199,11 +199,11 @@ def rasterize(
the `default_value` will be used. If `value` is `None` the
`fill` value will be used.
out_shape : tuple or list with 2 integers
Shape of output numpy ndarray.
Shape of output :class:`numpy.ndarray`.
fill : int or float, optional
Used as fill value for all areas not covered by input
geometries.
out : numpy ndarray, optional
out : numpy.ndarray, optional
Array of same shape and data type as `source` in which to store
results.
transform : Affine transformation object, optional
@ -222,12 +222,12 @@ def rasterize(
the new value will be added to the existing raster.
default_value : int or float, optional
Used as value for all geometries, if not provided in `shapes`.
dtype : rasterio or numpy data type, optional
dtype : rasterio or numpy.dtype, optional
Used as data type for results, if `out` is not provided.
Returns
-------
numpy ndarray
numpy.ndarray :
If `out` was not None then `out` is returned, it will have been
modified in-place. If `out` was None, this will be a new array.

6
rasterio/fill.py
View File

@ -35,11 +35,11 @@ def fillnodata(
Parameters
----------
image : numpy ndarray
image : numpy.ndarray
The source image with holes to be filled. If a MaskedArray, the
inverse of its mask will define the pixels to be filled --
unless the ``mask`` argument is not None (see below).`
mask : numpy ndarray or None
mask : numpy.ndarray, optional
A mask band indicating which pixels to interpolate. Pixels to
interpolate into are indicated by the value 0. Values
> 0 indicate areas to use during interpolation. Must be same
@ -55,7 +55,7 @@ def fillnodata(
Returns
-------
out : numpy ndarray
numpy.ndarray :
The filled raster array.
"""
if mask is None and isinstance(image, MaskedArray):

2
rasterio/mask.py
View File

@ -156,7 +156,7 @@ def mask(dataset, shapes, all_touched=False, invert=False, nodata=None,
Two elements:
masked : numpy ndarray or numpy.ma.MaskedArray
masked : numpy.ndarray or numpy.ma.MaskedArray
Data contained in the raster after applying the mask. If
`filled` is `True` and `invert` is `False`, the return will be
an array where pixels outside shapes are set to the nodata value

4
rasterio/merge.py
View File

@ -133,7 +133,7 @@ def merge(
nodata: float, optional
nodata value to use in output file. If not set, uses the nodata value
in the first input raster.
dtype: numpy dtype or string
dtype: numpy.dtype or string
dtype to use in outputfile. If not set, uses the dtype value in the
first input raster.
precision: int, optional
@ -185,7 +185,7 @@ def merge(
Two elements:
dest: numpy ndarray
dest: numpy.ndarray
Contents of all input rasters in single array
out_transform: affine.Affine()

21
rasterio/plot.py
View File

@ -53,7 +53,7 @@ def show(source, with_bounds=True, contour=False, contour_label_kws=None,
contour_label_kws : dictionary (opt)
Keyword arguments for labeling the contours,
empty dictionary for no labels.
ax : matplotlib axes (opt)
ax : matplotlib.axes.Axes, optional
Axes to plot on, otherwise uses current axes.
title : str, optional
Title for the figure.
@ -65,16 +65,12 @@ def show(source, with_bounds=True, contour=False, contour_label_kws=None,
True, values will be adjusted by the min / max of each band. If
False, no adjustment will be applied.
**kwargs : key, value pairings optional
These will be passed to the matplotlib imshow or contour method
depending on contour argument.
See full lists at:
https://matplotlib.org/stable/api/_as_gen/matplotlib.pyplot.imshow.html
or
https://matplotlib.org/stable/api/_as_gen/matplotlib.pyplot.contour.html
These will be passed to the :func:`matplotlib.pyplot.imshow` or
:func:`matplotlib.pyplot.contour` contour method depending on contour argument.
Returns
-------
ax : matplotlib Axes
ax : matplotlib.axes.Axes
Axes with plot.
"""
plt = get_plt()
@ -158,12 +154,12 @@ def show(source, with_bounds=True, contour=False, contour_label_kws=None,
def plotting_extent(source, transform=None):
"""Returns an extent in the format needed
for matplotlib's imshow (left, right, bottom, top)
for :func:`matplotlib.pyplot.imshow` (left, right, bottom, top)
instead of rasterio's bounds (left, bottom, right, top)
Parameters
----------
source : array or dataset object opened in 'r' mode
source : numpy.ndarray or dataset object opened in 'r' mode
If array, data in the order rows, columns and optionally bands. If array
is band order (bands in the first dimension), use arr[0]
transform: Affine, required if source is array
@ -238,14 +234,13 @@ def show_hist(source, bins=10, masked=True, title='Histogram', ax=None, label=No
should be masked on read.
title : str, optional
Title for the figure.
ax : matplotlib axes (opt)
ax : matplotlib.axes.Axes, optional
The raster will be added to this axes if passed.
label : matplotlib labels (opt)
If passed, matplotlib will use this label list.
Otherwise, a default label list will be automatically created
**kwargs : optional keyword arguments
These will be passed to the matplotlib hist method. See full list at:
http://matplotlib.org/api/axes_api.html?highlight=imshow#matplotlib.axes.Axes.hist
These will be passed to the :meth:`matplotlib.axes.Axes.hist` method.
"""
plt = get_plt()