diff --git a/docs/api/index.rst b/docs/api/index.rst index a7c673d3..53177860 100644 --- a/docs/api/index.rst +++ b/docs/api/index.rst @@ -1,37 +1,6 @@ -rasterio package -================ - -Submodules ----------- +Python API Reference +==================== .. toctree:: - rasterio.compat - rasterio.coords - rasterio.crs - rasterio.drivers - rasterio.dtypes - rasterio.enums - rasterio.env - rasterio.errors - rasterio.features - rasterio.fill - rasterio.io - rasterio.mask - rasterio.merge - rasterio.plot - rasterio.profiles - rasterio.sample - rasterio.transform - rasterio.vfs - rasterio.vrt - rasterio.warp - rasterio.windows - -Module contents ---------------- - -.. automodule:: rasterio - :members: - :undoc-members: - :show-inheritance: + rasterio diff --git a/docs/api/modules.rst b/docs/api/modules.rst new file mode 100644 index 00000000..e7356de9 --- /dev/null +++ b/docs/api/modules.rst @@ -0,0 +1,7 @@ +rasterio +======== + +.. toctree:: + :maxdepth: 4 + + rasterio diff --git a/docs/api/rasterio._base.rst b/docs/api/rasterio._base.rst new file mode 100644 index 00000000..3b49f32d --- /dev/null +++ b/docs/api/rasterio._base.rst @@ -0,0 +1,7 @@ +rasterio.\_base module +====================== + +.. automodule:: rasterio._base + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/api/rasterio._crs.rst b/docs/api/rasterio._crs.rst new file mode 100644 index 00000000..d8bacbd8 --- /dev/null +++ b/docs/api/rasterio._crs.rst @@ -0,0 +1,7 @@ +rasterio.\_crs module +===================== + +.. automodule:: rasterio._crs + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/api/rasterio._env.rst b/docs/api/rasterio._env.rst new file mode 100644 index 00000000..8b80e145 --- /dev/null +++ b/docs/api/rasterio._env.rst @@ -0,0 +1,7 @@ +rasterio.\_env module +===================== + +.. automodule:: rasterio._env + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/api/rasterio._err.rst b/docs/api/rasterio._err.rst new file mode 100644 index 00000000..5a725929 --- /dev/null +++ b/docs/api/rasterio._err.rst @@ -0,0 +1,7 @@ +rasterio.\_err module +===================== + +.. automodule:: rasterio._err + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/api/rasterio._example.rst b/docs/api/rasterio._example.rst new file mode 100644 index 00000000..932ea330 --- /dev/null +++ b/docs/api/rasterio._example.rst @@ -0,0 +1,7 @@ +rasterio.\_example module +========================= + +.. automodule:: rasterio._example + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/api/rasterio._features.rst b/docs/api/rasterio._features.rst new file mode 100644 index 00000000..70b78079 --- /dev/null +++ b/docs/api/rasterio._features.rst @@ -0,0 +1,7 @@ +rasterio.\_features module +========================== + +.. automodule:: rasterio._features + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/api/rasterio._fill.rst b/docs/api/rasterio._fill.rst new file mode 100644 index 00000000..05067e3b --- /dev/null +++ b/docs/api/rasterio._fill.rst @@ -0,0 +1,7 @@ +rasterio.\_fill module +====================== + +.. automodule:: rasterio._fill + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/api/rasterio._gdal1.rst b/docs/api/rasterio._gdal1.rst new file mode 100644 index 00000000..4a6d4036 --- /dev/null +++ b/docs/api/rasterio._gdal1.rst @@ -0,0 +1,7 @@ +rasterio.\_gdal1 module +======================= + +.. automodule:: rasterio._gdal1 + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/api/rasterio._io.rst b/docs/api/rasterio._io.rst new file mode 100644 index 00000000..15478542 --- /dev/null +++ b/docs/api/rasterio._io.rst @@ -0,0 +1,7 @@ +rasterio.\_io module +==================== + +.. automodule:: rasterio._io + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/api/rasterio._shim.rst b/docs/api/rasterio._shim.rst new file mode 100644 index 00000000..b93c0de2 --- /dev/null +++ b/docs/api/rasterio._shim.rst @@ -0,0 +1,7 @@ +rasterio.\_shim module +====================== + +.. automodule:: rasterio._shim + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/api/rasterio._shim1.rst b/docs/api/rasterio._shim1.rst new file mode 100644 index 00000000..200455c4 --- /dev/null +++ b/docs/api/rasterio._shim1.rst @@ -0,0 +1,7 @@ +rasterio.\_shim1 module +======================= + +.. automodule:: rasterio._shim1 + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/api/rasterio._shim20.rst b/docs/api/rasterio._shim20.rst new file mode 100644 index 00000000..e773426a --- /dev/null +++ b/docs/api/rasterio._shim20.rst @@ -0,0 +1,7 @@ +rasterio.\_shim20 module +======================== + +.. automodule:: rasterio._shim20 + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/api/rasterio._shim21.rst b/docs/api/rasterio._shim21.rst new file mode 100644 index 00000000..55c7a841 --- /dev/null +++ b/docs/api/rasterio._shim21.rst @@ -0,0 +1,7 @@ +rasterio.\_shim21 module +======================== + +.. automodule:: rasterio._shim21 + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/api/rasterio._warp.rst b/docs/api/rasterio._warp.rst new file mode 100644 index 00000000..3e4376bb --- /dev/null +++ b/docs/api/rasterio._warp.rst @@ -0,0 +1,7 @@ +rasterio.\_warp module +====================== + +.. automodule:: rasterio._warp + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/api/rasterio.control.rst b/docs/api/rasterio.control.rst new file mode 100644 index 00000000..ad2bbf97 --- /dev/null +++ b/docs/api/rasterio.control.rst @@ -0,0 +1,7 @@ +rasterio.control module +======================= + +.. automodule:: rasterio.control + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/api/rasterio.rio.blocks.rst b/docs/api/rasterio.rio.blocks.rst new file mode 100644 index 00000000..cd201411 --- /dev/null +++ b/docs/api/rasterio.rio.blocks.rst @@ -0,0 +1,7 @@ +rasterio.rio.blocks module +========================== + +.. automodule:: rasterio.rio.blocks + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/api/rasterio.rio.bounds.rst b/docs/api/rasterio.rio.bounds.rst new file mode 100644 index 00000000..567c00d7 --- /dev/null +++ b/docs/api/rasterio.rio.bounds.rst @@ -0,0 +1,7 @@ +rasterio.rio.bounds module +========================== + +.. automodule:: rasterio.rio.bounds + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/api/rasterio.rio.calc.rst b/docs/api/rasterio.rio.calc.rst new file mode 100644 index 00000000..c6f7c64f --- /dev/null +++ b/docs/api/rasterio.rio.calc.rst @@ -0,0 +1,7 @@ +rasterio.rio.calc module +======================== + +.. automodule:: rasterio.rio.calc + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/api/rasterio.rio.clip.rst b/docs/api/rasterio.rio.clip.rst new file mode 100644 index 00000000..9819a3de --- /dev/null +++ b/docs/api/rasterio.rio.clip.rst @@ -0,0 +1,7 @@ +rasterio.rio.clip module +======================== + +.. automodule:: rasterio.rio.clip + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/api/rasterio.rio.convert.rst b/docs/api/rasterio.rio.convert.rst new file mode 100644 index 00000000..1a1c75b3 --- /dev/null +++ b/docs/api/rasterio.rio.convert.rst @@ -0,0 +1,7 @@ +rasterio.rio.convert module +=========================== + +.. automodule:: rasterio.rio.convert + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/api/rasterio.rio.edit_info.rst b/docs/api/rasterio.rio.edit_info.rst new file mode 100644 index 00000000..f0ca8162 --- /dev/null +++ b/docs/api/rasterio.rio.edit_info.rst @@ -0,0 +1,7 @@ +rasterio.rio.edit\_info module +============================== + +.. automodule:: rasterio.rio.edit_info + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/api/rasterio.rio.env.rst b/docs/api/rasterio.rio.env.rst new file mode 100644 index 00000000..3fa931b4 --- /dev/null +++ b/docs/api/rasterio.rio.env.rst @@ -0,0 +1,7 @@ +rasterio.rio.env module +======================= + +.. automodule:: rasterio.rio.env + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/api/rasterio.rio.gcps.rst b/docs/api/rasterio.rio.gcps.rst new file mode 100644 index 00000000..30267590 --- /dev/null +++ b/docs/api/rasterio.rio.gcps.rst @@ -0,0 +1,7 @@ +rasterio.rio.gcps module +======================== + +.. automodule:: rasterio.rio.gcps + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/api/rasterio.rio.helpers.rst b/docs/api/rasterio.rio.helpers.rst new file mode 100644 index 00000000..a0660a47 --- /dev/null +++ b/docs/api/rasterio.rio.helpers.rst @@ -0,0 +1,7 @@ +rasterio.rio.helpers module +=========================== + +.. automodule:: rasterio.rio.helpers + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/api/rasterio.rio.info.rst b/docs/api/rasterio.rio.info.rst new file mode 100644 index 00000000..e756f1f1 --- /dev/null +++ b/docs/api/rasterio.rio.info.rst @@ -0,0 +1,7 @@ +rasterio.rio.info module +======================== + +.. automodule:: rasterio.rio.info + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/api/rasterio.rio.insp.rst b/docs/api/rasterio.rio.insp.rst new file mode 100644 index 00000000..606d8b64 --- /dev/null +++ b/docs/api/rasterio.rio.insp.rst @@ -0,0 +1,7 @@ +rasterio.rio.insp module +======================== + +.. automodule:: rasterio.rio.insp + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/api/rasterio.rio.main.rst b/docs/api/rasterio.rio.main.rst new file mode 100644 index 00000000..d36de33e --- /dev/null +++ b/docs/api/rasterio.rio.main.rst @@ -0,0 +1,7 @@ +rasterio.rio.main module +======================== + +.. automodule:: rasterio.rio.main + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/api/rasterio.rio.mask.rst b/docs/api/rasterio.rio.mask.rst new file mode 100644 index 00000000..0443a432 --- /dev/null +++ b/docs/api/rasterio.rio.mask.rst @@ -0,0 +1,7 @@ +rasterio.rio.mask module +======================== + +.. automodule:: rasterio.rio.mask + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/api/rasterio.rio.merge.rst b/docs/api/rasterio.rio.merge.rst new file mode 100644 index 00000000..43585ffe --- /dev/null +++ b/docs/api/rasterio.rio.merge.rst @@ -0,0 +1,7 @@ +rasterio.rio.merge module +========================= + +.. automodule:: rasterio.rio.merge + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/api/rasterio.rio.options.rst b/docs/api/rasterio.rio.options.rst new file mode 100644 index 00000000..330c50e8 --- /dev/null +++ b/docs/api/rasterio.rio.options.rst @@ -0,0 +1,7 @@ +rasterio.rio.options module +=========================== + +.. automodule:: rasterio.rio.options + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/api/rasterio.rio.overview.rst b/docs/api/rasterio.rio.overview.rst new file mode 100644 index 00000000..66f61601 --- /dev/null +++ b/docs/api/rasterio.rio.overview.rst @@ -0,0 +1,7 @@ +rasterio.rio.overview module +============================ + +.. automodule:: rasterio.rio.overview + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/api/rasterio.rio.rasterize.rst b/docs/api/rasterio.rio.rasterize.rst new file mode 100644 index 00000000..050f841d --- /dev/null +++ b/docs/api/rasterio.rio.rasterize.rst @@ -0,0 +1,7 @@ +rasterio.rio.rasterize module +============================= + +.. automodule:: rasterio.rio.rasterize + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/api/rasterio.rio.rm.rst b/docs/api/rasterio.rio.rm.rst new file mode 100644 index 00000000..6f9c3503 --- /dev/null +++ b/docs/api/rasterio.rio.rm.rst @@ -0,0 +1,7 @@ +rasterio.rio.rm module +====================== + +.. automodule:: rasterio.rio.rm + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/api/rasterio.rio.rst b/docs/api/rasterio.rio.rst new file mode 100644 index 00000000..684a360e --- /dev/null +++ b/docs/api/rasterio.rio.rst @@ -0,0 +1,39 @@ +rasterio.rio package +==================== + +Submodules +---------- + +.. toctree:: + + rasterio.rio.blocks + rasterio.rio.bounds + rasterio.rio.calc + rasterio.rio.clip + rasterio.rio.convert + rasterio.rio.edit_info + rasterio.rio.env + rasterio.rio.gcps + rasterio.rio.helpers + rasterio.rio.info + rasterio.rio.insp + rasterio.rio.main + rasterio.rio.mask + rasterio.rio.merge + rasterio.rio.options + rasterio.rio.overview + rasterio.rio.rasterize + rasterio.rio.rm + rasterio.rio.sample + rasterio.rio.shapes + rasterio.rio.stack + rasterio.rio.transform + rasterio.rio.warp + +Module contents +--------------- + +.. automodule:: rasterio.rio + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/api/rasterio.rio.sample.rst b/docs/api/rasterio.rio.sample.rst new file mode 100644 index 00000000..24614921 --- /dev/null +++ b/docs/api/rasterio.rio.sample.rst @@ -0,0 +1,7 @@ +rasterio.rio.sample module +========================== + +.. automodule:: rasterio.rio.sample + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/api/rasterio.rio.shapes.rst b/docs/api/rasterio.rio.shapes.rst new file mode 100644 index 00000000..6dd674d4 --- /dev/null +++ b/docs/api/rasterio.rio.shapes.rst @@ -0,0 +1,7 @@ +rasterio.rio.shapes module +========================== + +.. automodule:: rasterio.rio.shapes + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/api/rasterio.rio.stack.rst b/docs/api/rasterio.rio.stack.rst new file mode 100644 index 00000000..db977b34 --- /dev/null +++ b/docs/api/rasterio.rio.stack.rst @@ -0,0 +1,7 @@ +rasterio.rio.stack module +========================= + +.. automodule:: rasterio.rio.stack + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/api/rasterio.rio.transform.rst b/docs/api/rasterio.rio.transform.rst new file mode 100644 index 00000000..9c856265 --- /dev/null +++ b/docs/api/rasterio.rio.transform.rst @@ -0,0 +1,7 @@ +rasterio.rio.transform module +============================= + +.. automodule:: rasterio.rio.transform + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/api/rasterio.rio.warp.rst b/docs/api/rasterio.rio.warp.rst new file mode 100644 index 00000000..c0762a36 --- /dev/null +++ b/docs/api/rasterio.rio.warp.rst @@ -0,0 +1,7 @@ +rasterio.rio.warp module +======================== + +.. automodule:: rasterio.rio.warp + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/api/rasterio.rst b/docs/api/rasterio.rst new file mode 100644 index 00000000..629b6cec --- /dev/null +++ b/docs/api/rasterio.rst @@ -0,0 +1,61 @@ +rasterio package +================ + +Subpackages +----------- + +.. toctree:: + + rasterio.rio + +Submodules +---------- + +.. toctree:: + + rasterio._base + rasterio._crs + rasterio._env + rasterio._err + rasterio._example + rasterio._features + rasterio._fill + rasterio._gdal1 + rasterio._io + rasterio._shim + rasterio._shim1 + rasterio._shim20 + rasterio._shim21 + rasterio._warp + rasterio.compat + rasterio.control + rasterio.coords + rasterio.crs + rasterio.drivers + rasterio.dtypes + rasterio.enums + rasterio.env + rasterio.errors + rasterio.features + rasterio.fill + rasterio.io + rasterio.mask + rasterio.merge + rasterio.plot + rasterio.profiles + rasterio.sample + rasterio.shutil + rasterio.tools + rasterio.transform + rasterio.vfs + rasterio.vrt + rasterio.warp + rasterio.windows + +Module contents +--------------- + +.. automodule:: rasterio + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/api/rasterio.shutil.rst b/docs/api/rasterio.shutil.rst new file mode 100644 index 00000000..d38c0b5d --- /dev/null +++ b/docs/api/rasterio.shutil.rst @@ -0,0 +1,7 @@ +rasterio.shutil module +====================== + +.. automodule:: rasterio.shutil + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/api/rasterio.tools.rst b/docs/api/rasterio.tools.rst new file mode 100644 index 00000000..d678f020 --- /dev/null +++ b/docs/api/rasterio.tools.rst @@ -0,0 +1,7 @@ +rasterio.tools module +===================== + +.. automodule:: rasterio.tools + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/api/rasterio.vrt.rst b/docs/api/rasterio.vrt.rst new file mode 100644 index 00000000..dfea71fc --- /dev/null +++ b/docs/api/rasterio.vrt.rst @@ -0,0 +1,7 @@ +rasterio.vrt module +=================== + +.. automodule:: rasterio.vrt + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/cli.rst b/docs/cli.rst index f801cc63..3b7fc209 100644 --- a/docs/cli.rst +++ b/docs/cli.rst @@ -1,18 +1,17 @@ -======================== -Command Line Users Guide -======================== +Command Line User Guide +======================= -Rasterio's command line interface is a program named ``rio``. +Rasterio's command line interface (CLI) is a program named "rio" [#]_. -``rio`` allows you to build workflows using shell commands, either -interactively at the command prompt or with a script. Most common -cases are covered by ``rio`` commands and it is often more convenient +The CLI allows you to build workflows using shell commands, either +interactively at the command prompt or with a script. Many common +cases are covered by CLI sub-commands and it is often more convenient to use a ready-made command as opposed to implementing similar functionality as a python script. -``rio`` is developed using the `Click `__ architecture. -Its plugin system allows external modules to share a common namespace and -handling of context variables. +The rio program is developed using the `Click `__ +framwork. Its plugin system allows external modules to share a common +namespace and handling of context variables. .. code-block:: console @@ -171,10 +170,6 @@ The command above is also an example of a calculation that is far beyond the design of the calc command and something that could be done much more efficiently in Python. -.. toctree:: - - calc - clip ---- @@ -689,3 +684,7 @@ Other commands? --------------- Suggestions for other commands are welcome! + +.. [#] In some Linux distributions "rio" may instead refer to the command line + Diamond Rio MP3 player controller. This conflict can be avoided by + installing Rasterio in an isolated Python environment. diff --git a/docs/contributing.rst b/docs/contributing.rst index 9cb816d4..1f30ede4 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -5,10 +5,11 @@ Contributing Additional Information ---------------------- - More technical information lives on the wiki. - * https://github.com/mapbox/rasterio/wiki/Development-Guide - * https://github.com/mapbox/rasterio/wiki/Exposing-GDAL-Functionality - * https://github.com/mapbox/rasterio/wiki/Cython-and-GDAL +More technical information lives on the wiki. - The long term goal is to consolidate into this document. +* https://github.com/mapbox/rasterio/wiki/Development-Guide +* https://github.com/mapbox/rasterio/wiki/Exposing-GDAL-Functionality +* https://github.com/mapbox/rasterio/wiki/Cython-and-GDAL + +The long term goal is to consolidate into this document. diff --git a/docs/index.rst b/docs/index.rst index 63c6611f..5ee3fbf8 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -41,73 +41,18 @@ The output of the program: 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 intro installation quickstart - switch - -Advanced topics -=============== - -.. toctree:: - :maxdepth: 2 - - topics/color - topics/concurrency - topics/errors - topics/features - topics/fillnodata - topics/georeferencing - topics/image_options - topics/image_processing - topics/masking-by-shapefile - topics/masks - topics/memory-files - topics/migrating-to-v1 - topics/nodata - topics/overviews - topics/plotting - topics/reproject - topics/resampling - topics/tags - topics/virtual-warping - topics/vsi - topics/windowed-rw - -API documentation -================= - -.. toctree:: - :maxdepth: 2 - - api/index - -CLI guide -========= - -.. toctree:: - :maxdepth: 2 - cli - -Contributor Guide -================= - -.. toctree:: - :maxdepth: 2 - + topics/index + api/index contributing -Indices and tables +Indices and Tables ================== * :ref:`genindex` diff --git a/docs/installation.rst b/docs/installation.rst index cc387a00..5e6c003f 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -1,9 +1,8 @@ -============ Installation ============ Dependencies -============ +------------ Rasterio has one C library dependency: ``GDAL >=1.11``. GDAL itself depends on many of other libraries provided by most major operating systems and also @@ -15,10 +14,10 @@ click, enum34, numpy``. Development also requires (see requirements-dev.txt) Cython and other packages. Installing from binaries -======================== +------------------------ OS X ----- +**** Binary wheels with the GDAL, GEOS, and PROJ4 libraries included are available for OS X versions 10.7+ starting with Rasterio version 0.17. To install, @@ -34,7 +33,7 @@ Binary wheels for other operating systems will be available in a future release. Windows -------- +******* Binary wheels for rasterio and GDAL are created by Christoph Gohlke and are available from his website. @@ -52,7 +51,7 @@ 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 @@ -60,7 +59,7 @@ 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 @@ -71,7 +70,7 @@ Travis `configuration guidance. Linux ------ +***** The following commands are adapted from Rasterio's Travis-CI configuration. @@ -85,7 +84,7 @@ The following commands are adapted from Rasterio's Travis-CI configuration. Adapt them as necessary for your Linux system. OS X ----- +**** For a Homebrew based Python environment, do the following. @@ -95,7 +94,7 @@ For a Homebrew based Python environment, do the following. $ pip install rasterio Windows -------- +******* You can download a binary distribution of GDAL from `here `__. You will also need to download diff --git a/docs/intro.rst b/docs/intro.rst index a5ebfc1e..d8006672 100644 --- a/docs/intro.rst +++ b/docs/intro.rst @@ -1,4 +1,3 @@ -============ Introduction ============ diff --git a/docs/python_manual.rst b/docs/python_manual.rst deleted file mode 100644 index 8db54aec..00000000 --- a/docs/python_manual.rst +++ /dev/null @@ -1,23 +0,0 @@ -================================= -``rasterio`` Python User's Manual -================================= - -This user's manual is for Python developers who want a clean API for accessing raster data. - -.. todo:: - - What does it do, narrative examples - - What it does NOT do - - For command line tools look to CLI users manual - -.. toctree:: - :maxdepth: 2 - - installation - reading - working_with_datasets - writing - topics - osgeo_gdal_migration diff --git a/docs/quickstart.rst b/docs/quickstart.rst index a44f060d..91e7772c 100644 --- a/docs/quickstart.rst +++ b/docs/quickstart.rst @@ -1,6 +1,5 @@ -========== -Quickstart -========== +Python Quickstart +================= Reading and writing data files is a spatial data analyst's bread and butter. This document explains how to use Rasterio to read existing files and to create @@ -10,7 +9,7 @@ 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 @@ -46,7 +45,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 +86,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 +182,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 +206,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 @@ -238,7 +237,7 @@ below. 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 +288,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. diff --git a/docs/topics/color.rst b/docs/topics/color.rst index 586c640e..210176e9 100644 --- a/docs/topics/color.rst +++ b/docs/topics/color.rst @@ -1,12 +1,11 @@ Color -***** +===== Color interpretation -^^^^^^^^^^^^^^^^^^^^^ +-------------------- Color interpretation of raster bands can be read from the dataset - .. code-block:: python >>> import rasterio @@ -46,10 +45,6 @@ And the resulting raster will be interpretted as RGB. ... src2.colorinterp[1] - -Colormaps -^^^^^^^^^ - Writing colormaps ----------------- @@ -93,4 +88,3 @@ Reading colormaps As shown above, the ``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. - diff --git a/docs/topics/concurrency.rst b/docs/topics/concurrency.rst index d120b4d6..1633a195 100644 --- a/docs/topics/concurrency.rst +++ b/docs/topics/concurrency.rst @@ -1,5 +1,5 @@ Concurrent processing -********************* +===================== Rasterio affords concurrent processing of raster data. The Python GIL is released when calling GDAL's ``GDALRasterIO()`` function, which means that diff --git a/docs/topics/errors.rst b/docs/topics/errors.rst index f821ce19..3c901480 100644 --- a/docs/topics/errors.rst +++ b/docs/topics/errors.rst @@ -1,5 +1,5 @@ Error Handling -************** +============== .. todo:: diff --git a/docs/topics/features.rst b/docs/topics/features.rst index 7a0bb138..80cbbc66 100644 --- a/docs/topics/features.rst +++ b/docs/topics/features.rst @@ -1,5 +1,5 @@ Vector Features -*************** +=============== Rasterio's ``features`` module provides functions to extract shapes of raster features and to create new features by "burning" shapes into rasters: diff --git a/docs/topics/fillnodata.rst b/docs/topics/fillnodata.rst index 8f1c8ead..e54287ef 100644 --- a/docs/topics/fillnodata.rst +++ b/docs/topics/fillnodata.rst @@ -1,5 +1,5 @@ Filling nodata areas -******************** +==================== .. todo:: diff --git a/docs/topics/georeferencing.rst b/docs/topics/georeferencing.rst index 150235ad..da9e7471 100644 --- a/docs/topics/georeferencing.rst +++ b/docs/topics/georeferencing.rst @@ -1,5 +1,5 @@ Georeferencing -************** +============== There are two parts to the georeferencing of raster datasets: the definition of the local, regional, or global system in which a raster's pixels are diff --git a/docs/topics/image_options.rst b/docs/topics/image_options.rst index e249a92e..dd3d7325 100644 --- a/docs/topics/image_options.rst +++ b/docs/topics/image_options.rst @@ -1,5 +1,5 @@ Options -******* +======= GDAL's format drivers have many `configuration options`_. These options come in two flavors: diff --git a/docs/topics/image_processing.rst b/docs/topics/image_processing.rst index 2895bf8b..7f8253d2 100644 --- a/docs/topics/image_processing.rst +++ b/docs/topics/image_processing.rst @@ -1,5 +1,5 @@ Interoperability -**************** +================ .. _imageorder: diff --git a/docs/topics/index.rst b/docs/topics/index.rst index a5e56013..4a6b0ff0 100644 --- a/docs/topics/index.rst +++ b/docs/topics/index.rst @@ -1,8 +1,8 @@ -General Concepts -================ +Advanced Topics +=============== .. toctree:: - :maxdepth: 2 + :maxdepth: 1 color concurrency diff --git a/docs/topics/masks.rst b/docs/topics/masks.rst index bf912091..926f3dfe 100644 --- a/docs/topics/masks.rst +++ b/docs/topics/masks.rst @@ -1,5 +1,5 @@ Nodata Masks -************ +============ Nodata masks allow you to identify regions of valid data values. In using Rasterio, you'll encounter two different kinds of masks. diff --git a/docs/topics/overviews.rst b/docs/topics/overviews.rst index a30ffa04..d01dd68b 100644 --- a/docs/topics/overviews.rst +++ b/docs/topics/overviews.rst @@ -1,5 +1,5 @@ Overviews -********* +========= Overviews are reduced resolution versions of your dataset that can speed up rendering when you don't need full resolution. By precomputing the upsampled diff --git a/docs/topics/plotting.rst b/docs/topics/plotting.rst index ab4d6751..934d62b7 100644 --- a/docs/topics/plotting.rst +++ b/docs/topics/plotting.rst @@ -1,5 +1,5 @@ Plotting -******** +======== Rasterio reads raster data into numpy arrays so plotting a single band as two dimensional data can be accomplished directly with ``pyplot``. diff --git a/docs/topics/reading.rst b/docs/topics/reading.rst index 39a8dc62..ce396a2f 100644 --- a/docs/topics/reading.rst +++ b/docs/topics/reading.rst @@ -1,5 +1,5 @@ Reading Datasets -===================== +================ .. todo:: diff --git a/docs/topics/reproject.rst b/docs/topics/reproject.rst index ecf5845e..106c194f 100644 --- a/docs/topics/reproject.rst +++ b/docs/topics/reproject.rst @@ -1,5 +1,5 @@ Reprojection -************ +============ Rasterio can map the pixels of a destination raster with an associated coordinate reference system and transform to the pixels of a source image with diff --git a/docs/topics/resampling.rst b/docs/topics/resampling.rst index 8afb67be..67bd880f 100644 --- a/docs/topics/resampling.rst +++ b/docs/topics/resampling.rst @@ -1,11 +1,11 @@ Resampling -********** - - For details on changing coordinate reference systems, see `Reprojection`. +========== +For details on changing coordinate reference systems, see `Reprojection`. Up and Downsampling ------------------- + *Resampling* refers to changing the cell values due to changes in the raster cell grid. This can occur during reprojection. Even if the crs is not changing, we may want to change the effective cell size of an existing dataset. *Upsampling* refers to cases where we are converting to higher resolution/smaller cells. @@ -14,7 +14,8 @@ Up and Downsampling There are three potential ways to perform up/downsampling. Use reproject -~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~ +~ If you use ``reproject`` but keep the same CRS, you can utilize the underlying GDAL algorithms to resample your data. @@ -44,7 +45,7 @@ by ``x``, you need to *divide* the affine parameters defining the cell size by ` Use scipy -~~~~~~~~~~~~~ +~~~~~~~~~ You can also use `scipy.ndimage.interpolation.zoom`_ to "zoom" with a configurable spline interpolation that differs from the resampling methods available in GDAL. This may not be appropriate for all data so check the results carefully. You must adjust the affine transform just as we did above. diff --git a/docs/switch.rst b/docs/topics/switch.rst similarity index 96% rename from docs/switch.rst rename to docs/topics/switch.rst index 09c32d3c..08b87630 100644 --- a/docs/switch.rst +++ b/docs/topics/switch.rst @@ -1,4 +1,3 @@ -===================================== Switching from GDAL's Python bindings ===================================== @@ -10,7 +9,7 @@ between these two Python packages and highlights the features of Rasterio that can help in switching. Mutual Incompatibilities -======================== +------------------------ Rasterio and GDAL's bindings can contend for global GDAL objects. Unless you have deep knowledge about both packages, choose exactly one of ``import @@ -32,7 +31,7 @@ writes like C while ``rasterio`` is more Pythonic – and don't complement each other well. The GDAL Environment -==================== +-------------------- GDAL library functions are excuted in a context of format drivers, error handlers, and format-specific configuration options that this document will @@ -127,7 +126,7 @@ Rasterio achieves this with a single Python statement. 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 @@ -140,7 +139,7 @@ functions like ``rasterio.open()``. Rasterio uses the same format driver names as GDAL does. Dataset Identifiers -=================== +------------------- Rasterio uses URIs to identify datasets, with schemes for different protocols. The GDAL bindings have their own special syntax. @@ -171,7 +170,7 @@ format-specific connection strings, too, and dispatch them to the proper format drivers and protocols. 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 @@ -184,7 +183,7 @@ the ``close()`` method that ``gdal`` lacks so that you can actively close dataset connections. Bands -===== +----- ``gdal`` has band objects. Rasterio does not and thus never has objects with dangling dataset pointers. With Rasterio, bands are represented by a numerical @@ -236,7 +235,7 @@ Namedtuples are like lightweight classes. 3 Geotransforms -============= +------------- The ``transform`` attribute of a Rasterio dataset object is comparable to the ``GeoTransform`` attribute of a GDAL dataset, but Rasterio's has more power. @@ -271,7 +270,7 @@ converted to the sequences used by ``gdal``. (101985.0, 300.0379266750948, 0.0, 2826915.0, 0.0, -300.041782729805) Coordinate Reference Systems -============================ +---------------------------- The ``crs`` attribute of a Rasterio dataset object is an instance of Rasterio's ``CRS`` class and works well with ``pyproj``. @@ -284,7 +283,7 @@ The ``crs`` attribute of a Rasterio dataset object is an instance of Rasterio's (-8789636.707871985, 2938035.238323653) Tags -==== +---- GDAL metadata items are called "tags" in Rasterio. The tag set for a given GDAL metadata namespace is represented as a dict. @@ -302,7 +301,7 @@ several namespaces of its own: ``rio_creation_kwds`` and ``rio_overviews``, each with their own semantics. Offsets and Windows -=================== +------------------- Rasterio adds an abstraction for subsets or windows of a raster array that GDAL does not have. A window is a pair of tuples, the first of the pair being @@ -320,7 +319,7 @@ four subset parameters used with ``gdal`` to the class constructor. subset = src.read(1, window=Window(xoff, yoff, xsize, ysize)) Valid Data Masks -================ +---------------- Rasterio provides an array for every dataset representing its valid data mask using the same indicators as GDAL: ``0`` for invalid data and ``255`` for valid @@ -328,7 +327,7 @@ data. .. code-block:: pycon - >>> src = rasterio.open('example.tif') + >>> src - rasterio.open('example.tif') >>> src.dataset_mask() array([[0, 0, 0, ..., 0, 0, 0], [0, 0, 0, ..., 0, 0, 0], @@ -336,14 +335,14 @@ data. ..., [0, 0, 0, ..., 0, 0, 0], [0, 0, 0, ..., 0, 0, 0], - [0, 0, 0, ..., 0, 0, 0]], dtype=uint8) + [0, 0, 0, ..., 0, 0, 0]], dtype-uint8) Arrays for dataset bands can also be had as a Numpy ``masked_array``. .. code-block:: pycon - >>> src.read(1, masked=True) - masked_array(data = + >>> src.read(1, masked-True) + masked_array(data - [[-- -- -- ..., -- -- --] [-- -- -- ..., -- -- --] [-- -- -- ..., -- -- --] @@ -351,7 +350,7 @@ Arrays for dataset bands can also be had as a Numpy ``masked_array``. [-- -- -- ..., -- -- --] [-- -- -- ..., -- -- --] [-- -- -- ..., -- -- --]], - mask = + mask - [[ True True True ..., True True True] [ True True True ..., True True True] [ True True True ..., True True True] @@ -359,13 +358,13 @@ Arrays for dataset bands can also be had as a Numpy ``masked_array``. [ True True True ..., True True True] [ True True True ..., True True True] [ True True True ..., True True True]], - fill_value = 0) + fill_value - 0) Where the masked array's ``mask`` is ``True``, the data is invalid and has been masked "out" in the opposite sense of GDAL's mask. Errors and Exceptions -===================== +--------------------- Rasterio always raises Python exceptions when an error occurs and never returns an error code or ``None`` to indicate an error. ``gdal`` takes the opposite diff --git a/docs/topics/tags.rst b/docs/topics/tags.rst index d3ef1dce..b5eb6261 100644 --- a/docs/topics/tags.rst +++ b/docs/topics/tags.rst @@ -1,5 +1,5 @@ Tagging datasets and bands -************************** +========================== GDAL's `data model `__ includes collections of key, value pairs for major classes. In that model, these are diff --git a/docs/topics/virtual-warping.rst b/docs/topics/virtual-warping.rst index 58ce8c97..87fac621 100644 --- a/docs/topics/virtual-warping.rst +++ b/docs/topics/virtual-warping.rst @@ -56,7 +56,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 projections, bounds, cell sizes, or dimensions against a regular grid diff --git a/docs/topics/vsi.rst b/docs/topics/vsi.rst index 33bc0e8d..64d87743 100644 --- a/docs/topics/vsi.rst +++ b/docs/topics/vsi.rst @@ -1,5 +1,5 @@ Virtual Files -************* +============= .. todo:: @@ -7,7 +7,7 @@ Virtual Files Relationship to GDAL vsicurl, vsis3 et al. AWS S3 -====== +------ .. note:: Requires GDAL 2.1.0 diff --git a/docs/topics/windowed-rw.rst b/docs/topics/windowed-rw.rst index 4a4a0dbb..ce0f1437 100644 --- a/docs/topics/windowed-rw.rst +++ b/docs/topics/windowed-rw.rst @@ -1,7 +1,5 @@ - .. _windowrw: -============================ Windowed reading and writing ============================ @@ -9,9 +7,8 @@ Beginning in rasterio 0.3, you can read and write "windows" of raster files. This feature allows you to work on rasters that are larger than your 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 described in rasterio by column and row offsets and width and height @@ -42,7 +39,7 @@ and open-ended slices may be used. Reading -======= +------- Here is an example of reading a 256 row x 512 column subset of the rasterio test file. @@ -57,7 +54,7 @@ test file. (256, 512) Writing -======= +------- Writing works similarly. The following creates a blank 500 column x 300 row GeoTIFF and plops 37,500 pixels with value 127 into a window 30 pixels down from @@ -80,7 +77,7 @@ The result: :height: 300 Decimation -========== +---------- If the write window is smaller than the data, the data will be decimated. Below, the window is scaled to one third of the source image. @@ -108,7 +105,7 @@ And the result: :height: 300 Data windows -============ +------------ Sometimes it is desirable to crop off an outer boundary of NODATA values around a dataset: @@ -118,21 +115,21 @@ a dataset: from rasterio.windows import get_data_window with rasterio.open('tests/data/RGB.byte.tif') as src: - window = get_data_window(src.read(1, masked=True)) - # window = Window(col_off=13, row_off=3, width=757, height=711) + window - get_data_window(src.read(1, masked-True)) + # window - Window(col_off-13, row_off-3, width-757, height-711) - kwargs = src.meta.copy() + kwargs - src.meta.copy() kwargs.update({ 'height': window.height, 'width': window.width, 'transform': rasterio.windows.transform(window, src.transform)}) with rasterio.open('/tmp/cropped.tif', 'w', **kwargs) as dst: - dst.write(src.read(window=window)) + dst.write(src.read(window-window)) Window utilities -================ +---------------- Basic union and intersection operations are available for windows, to streamline operations across dynamically created windows for a series of bands @@ -151,7 +148,7 @@ or datasets with the same full extent. Blocks -====== +------ Raster datasets are generally composed of multiple blocks of data and windowed reads and writes are most efficient when the windows match the