mirror of
https://github.com/rasterio/rasterio.git
synced 2025-12-08 17:36:12 +00:00
Better structure for docs
Plus a more compelling example. Resolves #846
This commit is contained in:
Sean Gillies
parent
749f3d7bba
commit
2103f8048d
@ -1,44 +1,59 @@
|
||||
======================
|
||||
Rasterio Documentation
|
||||
======================
|
||||
==========================================
|
||||
Rasterio: access to geospatial raster data
|
||||
==========================================
|
||||
|
||||
Rasterio reads and writes geospatial raster data.
|
||||
Geographic information systems use GeoTIFF and other formats to organize and
|
||||
store gridded raster datasets such as satellite imagery and terrain models.
|
||||
Rasterio reads and writes these formats and provides a Python API based on
|
||||
Numpy N-dimensional arrays and GeoJSON.
|
||||
|
||||
Geographic information systems use GeoTIFF and other formats to organize
|
||||
and store gridded raster datasets. Rasterio reads and writes these
|
||||
formats and provides a Python API based on Numpy N-dimensional arrays.
|
||||
Here's an example program that extracts the GeoJSON shapes of a raster's valid
|
||||
data footprint.
|
||||
|
||||
Rasterio supports Python 2.7 and 3.3-3.5 on Linux and Mac OS X.
|
||||
.. code:: python
|
||||
|
||||
.. code:: pycon
|
||||
import rasterio
|
||||
import rasterio.features
|
||||
import rasterio.warp
|
||||
|
||||
>>> dataset = rasterio.open('example.tif')
|
||||
>>> dataset.driver
|
||||
'GTiff'
|
||||
>>> dataset.count
|
||||
1
|
||||
>>> dataset.dtypes
|
||||
('uint16',)
|
||||
>>> dataset.shape
|
||||
(7871, 7731)
|
||||
>>> dataset.crs
|
||||
CRS({'init': 'epsg:32612'})
|
||||
>>> dataset.bounds
|
||||
BoundingBox(left=358485.0, bottom=4028985.0, right=59
|
||||
with rasterio.open('example.tif') as dataset:
|
||||
|
||||
# Read the dataset's valid data mask as a ndarray.
|
||||
mask = dataset.dataset_mask()
|
||||
|
||||
# Extract feature shapes and values from the array.
|
||||
for geom, val in rasterio.features.shapes(
|
||||
mask, transform=dataset.transform):
|
||||
|
||||
# Transform shapes from the dataset's own coordinate
|
||||
# reference system to CRS84 (EPSG:4326).
|
||||
geom = rasterio.warp.transform_geom(
|
||||
dataset.crs, 'EPSG:4326', geom, precision=6)
|
||||
|
||||
# Print GeoJSON shapes to stdout.
|
||||
print(geom)
|
||||
|
||||
The output of the program:
|
||||
|
||||
.. code:: python
|
||||
|
||||
{'type': 'Polygon', 'coordinates': [[(-77.730817, 25.282335), ...]]}
|
||||
|
||||
Rasterio supports Python versions 2.7 and 3.3 or higher.
|
||||
|
||||
User guide
|
||||
==========
|
||||
|
||||
Start here with some background about the project and an introduction to
|
||||
reading and writing raster datasets.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
user/intro
|
||||
user/installation
|
||||
user/quickstart
|
||||
user/reading
|
||||
user/working_with_datasets
|
||||
user/writing
|
||||
user/osgeo_gdal_migration
|
||||
intro
|
||||
installation
|
||||
quickstart
|
||||
migration
|
||||
|
||||
Advanced topics
|
||||
===============
|
||||
|
||||
@ -1,19 +1,21 @@
|
||||
============
|
||||
Installation
|
||||
============
|
||||
|
||||
Dependencies
|
||||
************************
|
||||
============
|
||||
|
||||
Rasterio has one C library dependency: ``GDAL >=1.9``. GDAL itself depends on
|
||||
many of other libraries provided by most major operating systems and also
|
||||
depends on the non standard GEOS and PROJ4 libraries.
|
||||
|
||||
Python package dependencies (see also requirements.txt): ``affine, cligj, click, enum34, numpy``.
|
||||
Python package dependencies (see also requirements.txt): ``affine, cligj,
|
||||
click, enum34, numpy``.
|
||||
|
||||
Development also requires (see requirements-dev.txt) Cython and other packages.
|
||||
|
||||
Installing from binaries
|
||||
************************
|
||||
========================
|
||||
|
||||
OS X
|
||||
----
|
||||
@ -50,14 +52,15 @@ this from the downloads folder:
|
||||
|
||||
|
||||
Installing with Anaconda
|
||||
*************************
|
||||
=========================
|
||||
|
||||
To install rasterio on the Anaconda Python distribution, please visit the
|
||||
`rasterio conda-forge`_ page for install instructions. This build is maintained
|
||||
separately from the rasterio distribution on PyPi and packaging issues should
|
||||
be addressed on the `rasterio conda-forge`_ issue tracker.
|
||||
|
||||
Installing from the source distribution
|
||||
***************************************
|
||||
=======================================
|
||||
|
||||
Rasterio is a Python C extension and to build you'll need a working compiler
|
||||
(XCode on OS X etc). You'll also need Numpy preinstalled; the Numpy headers are
|
||||
@ -118,50 +121,4 @@ versions used `here
|
||||
Note: The GDAL dll (gdal111.dll) and gdal-data directory need to be in your
|
||||
Windows PATH otherwise rasterio will fail to work.
|
||||
|
||||
Testing
|
||||
***************************************
|
||||
|
||||
From the repo directory, run py.test
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ py.test
|
||||
|
||||
Note: some tests do not succeed on Windows (see
|
||||
`#66
|
||||
<https://github.com/mapbox/rasterio/issues/66>`__.).
|
||||
|
||||
|
||||
Downstream testing
|
||||
------------------
|
||||
|
||||
If your project depends on Rasterio and uses Travis-CI, you can speed up your
|
||||
builds by fetching Rasterio and its dependencies as a set of wheels from
|
||||
GitHub as done in `rio-plugin-example
|
||||
<https://github.com/sgillies/rio-plugin-example/blob/master/.travis.yml>`__.
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
language: python
|
||||
env:
|
||||
- RASTERIO_VERSION=0.26
|
||||
python:
|
||||
- "2.7"
|
||||
- "3.4"
|
||||
cache:
|
||||
directories:
|
||||
- $HOME/.pip-cache/
|
||||
- $HOME/wheelhouse
|
||||
before_install:
|
||||
- sudo add-apt-repository -y ppa:ubuntugis/ppa
|
||||
- sudo apt-get update -qq
|
||||
- sudo apt-get install -y libgdal-dev gdal-bin
|
||||
- curl -L https://github.com/mapbox/rasterio/releases/download/$RASTERIO_VERSION/rasterio-travis-wheels-$TRAVIS_PYTHON_VERSION.tar.gz > /tmp/wheelhouse.tar.gz
|
||||
- tar -xzvf /tmp/wheelhouse.tar.gz -C $HOME
|
||||
install:
|
||||
- pip install --use-wheel --find-links=$HOME/wheelhouse -e .[test] --cache-dir $HOME/.pip-cache
|
||||
script:
|
||||
- py.test
|
||||
|
||||
|
||||
.. _rasterio conda-forge: https://github.com/conda-forge/rasterio-feedstock
|
||||
@ -10,14 +10,14 @@ but the examples do apply to other raster data formats. It is presumed that
|
||||
Rasterio has been `installed <./installation>`__.
|
||||
|
||||
Opening a dataset in reading mode
|
||||
---------------------------------
|
||||
=================================
|
||||
|
||||
Consider an "example.tif" file with 16-bit Landsat 8 imagery covering a part
|
||||
of the United States's Colorado Plateau [#]_. Because the imagery is large (70
|
||||
MB) and has a wide dynamic range it is difficult to display it in a browser.
|
||||
A rescaled and dynamically squashed version is shown below.
|
||||
|
||||
.. image:: img/example.png
|
||||
.. image:: ../img/example.png
|
||||
|
||||
Import rasterio to begin.
|
||||
|
||||
@ -46,7 +46,7 @@ attributes as Python file objects.
|
||||
False
|
||||
|
||||
Dataset attributes
|
||||
------------------
|
||||
==================
|
||||
|
||||
Properties of the raster data stored in "example.tif" can be accessed through
|
||||
attributes of the ``dataset`` object. Dataset objects have bands and this
|
||||
@ -87,7 +87,7 @@ The "example.tif" file's sole band contains unsigned 16-bit integer values. The
|
||||
GeoTIFF format also supports signed integers and floats of different size.
|
||||
|
||||
Dataset georeferencing
|
||||
----------------------
|
||||
======================
|
||||
|
||||
A GIS raster dataset is different from an ordinary image; its elements (or
|
||||
"pixels") are mapped to regions on the earth's surface. Every pixels of a
|
||||
@ -183,7 +183,7 @@ Values from the array can be had by their row, column index.
|
||||
17491
|
||||
|
||||
Spatial indexing
|
||||
----------------
|
||||
================
|
||||
|
||||
Datasets have a method of getting array indices for spatial points. To get the
|
||||
value for the pixel 100 kilometers east and 50 kilometers south of the
|
||||
@ -207,7 +207,7 @@ The coordinates of the center of the image can be computed like this.
|
||||
(476550.0, 4149150.0)
|
||||
|
||||
Creating data
|
||||
-------------
|
||||
=============
|
||||
|
||||
Reading data is only half the story. Using Rasterio dataset objects, arrays of
|
||||
values can be written to a raster data file and thus shared with other GIS
|
||||
@ -234,11 +234,11 @@ The fictional field for this example consists of the difference of two Gaussian
|
||||
distributions and is represented by the array ``Z``. Its contours are shown
|
||||
below.
|
||||
|
||||
.. image:: img/field.png
|
||||
.. image:: ../img/field.png
|
||||
|
||||
|
||||
Opening a dataset in writing mode
|
||||
---------------------------------
|
||||
=================================
|
||||
|
||||
To save this array along with georeferencing information to a new raster data
|
||||
file, call ``rasterio.open()`` with a path to the new file to be created,
|
||||
@ -289,7 +289,7 @@ directly from attributes of the 2-D array, ``Z``. Not all raster formats can
|
||||
support the 64-bit float values in ``Z``, but the GeoTIFF format can.
|
||||
|
||||
Saving raster data
|
||||
------------------
|
||||
==================
|
||||
|
||||
To save the grid, call the new dataset's ``write()`` method with the grid and
|
||||
target band number as arguments.
|
||||
@ -1,79 +0,0 @@
|
||||
Working with Datasets
|
||||
======================
|
||||
|
||||
Attributes
|
||||
----------
|
||||
|
||||
Besides the file-like attributes shown above, a dataset has some other
|
||||
read-only attributes that help explain its role in spatial information systems.
|
||||
The ``driver`` attribute gives you the name of the GDAL format driver used. The
|
||||
``height`` and ``width`` are the number of rows and columns of the raster
|
||||
dataset and ``shape`` is a ``height, width`` tuple as used by Numpy. The
|
||||
``count`` attribute tells you the number of bands in the dataset.
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
>>> import rasterio
|
||||
>>> src = rasterio.open("tests/data/RGB.byte.tif")
|
||||
>>> src.driver
|
||||
'GTiff'
|
||||
>>> src.height, src.width
|
||||
(718, 791)
|
||||
>>> src.shape
|
||||
(718, 791)
|
||||
>>> src.count
|
||||
3
|
||||
|
||||
What makes geospatial raster datasets different from other raster files is
|
||||
that their pixels map to regions of the Earth. A dataset has a coordinate
|
||||
reference system and an affine transformation matrix that maps pixel
|
||||
coordinates to coordinates in that reference system.
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
>>> src.crs
|
||||
CRS({'init': 'epsg:32618'})
|
||||
>>> src.transform
|
||||
Affine(300.0379266750948, 0.0, 101985.0,
|
||||
0.0, -300.041782729805, 2826915.0)
|
||||
|
||||
To get the ``x, y`` world coordinates for the upper left corner of any pixel,
|
||||
take the product of the affine transformation matrix and the tuple ``(col,
|
||||
row)``.
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
>>> col, row = 0, 0
|
||||
>>> src.transform * (col, row)
|
||||
(101985.0, 2826915.0)
|
||||
>>> col, row = src.width, src.height
|
||||
>>> src.transform * (col, row)
|
||||
(339315.0, 2611485.0)
|
||||
|
||||
|
||||
Profile
|
||||
-------
|
||||
The ``src.profile`` property is the union of meta, creation options saved as tags, and tiling options.
|
||||
The primary use of profile is to provide a canonical way of creating a dataset clone,
|
||||
encapsulating all the necessary metadata required to recreate a dataset::
|
||||
|
||||
with rasterio.open('example.tif') as src:
|
||||
with rasterio.open('clone.tif', 'w', **src.profile) as dst:
|
||||
dst.write(src.read())
|
||||
|
||||
A common pattern for using the profile is to copy a source profile, update it slightly
|
||||
to reflect any changes, and use the updated copy to create the output::
|
||||
|
||||
# we start with the profile of the source file
|
||||
profile = src.profile.copy()
|
||||
|
||||
# but then change the band count to 1, set the
|
||||
# dtype to uint8, and specify LZW compression.
|
||||
profile.update(
|
||||
dtype=rasterio.uint8,
|
||||
count=1,
|
||||
compress='lzw')
|
||||
|
||||
# And use the updated profile as kwargs for our destination file
|
||||
with open('destination.tif', 'w', **profile) as dst:
|
||||
...
|
||||
Loading…
x
Reference in New Issue
Block a user