======= Rasterio

Rasterio 是一款用于读写地理空间栅格数据的工具库。

.. image:: https://github.com/rasterio/rasterio/actions/workflows/tests.yaml/badge.svg :target: https://github.com/rasterio/rasterio/actions/workflows/tests.yaml

.. image:: https://github.com/rasterio/rasterio/actions/workflows/test_gdal_latest.yaml/badge.svg :target: https://github.com/rasterio/rasterio/actions/workflows/test_gdal_latest.yaml

.. image:: https://github.com/rasterio/rasterio/actions/workflows/test_gdal_tags.yaml/badge.svg :target: https://github.com/rasterio/rasterio/actions/workflows/test_gdal_tags.yaml

.. image:: https://img.shields.io/pypi/v/rasterio :target: https://pypi.org/project/rasterio/

地理信息系统使用 GeoTIFF 等格式组织和存储网格化（栅格）数据集。Rasterio 不仅能读写这些格式，还提供了基于 N 维数组的 Python 接口。

Rasterio 1.4 支持 Python >= 3.9、Numpy >= 1.24 和 GDAL >= 3.5。官方发布的 Linux、macOS 和 Windows 二进制包已内置多数格式驱动，并额外支持 HDF5、netCDF 和 OpenJPEG2000，可通过 PyPI 获取。

详情请查阅文档：https://rasterio.readthedocs.io/。

示例

以下示例展示了 Rasterio 的基础功能。程序从图像中读取三个波段数据，计算平均值生成类似全色波段的影像，并将结果写入新的单波段 TIFF 文件。

.. code-block:: python

import numpy as np
import rasterio

# 将栅格波段直接读取为 Numpy 数组
with rasterio.open('tests/data/RGB.byte.tif') as src:
    r, g, b = src.read()

# 原地合并数组。考虑到总和可能暂时超出 8 位整数范围，
# 初始化为 64 位浮点数组（numpy 默认类型）。
# 通过原地相加其他数组会自动提升类型，保持总数组的数据类型。
total = np.zeros(r.shape)

for band in r, g, b:
    total += band

total /= 3

# 将结果作为栅格波段写入新的 8 位文件。
# 新文件的配置参数继承自源文件，但修改了波段数为 1，
# 数据类型为 uint8，并指定 LZW 压缩。
profile = src.profile
profile.update(dtype=rasterio.uint8, count=1, compress='lzw')

with rasterio.open('example-total.tif', 'w', **profile) as dst:
    dst.write(total.astype(rasterio.uint8), 1)

输出效果：

.. image:: http://farm6.staticflickr.com/5501/11393054644_74f54484d9_z_d.jpg :width: 640 :height: 581

API 概览

Rasterio 可访问地理空间栅格文件的属性信息。

.. code-block:: python

with rasterio.open('tests/data/RGB.byte.tif') as src:
    print(src.width, src.height)
    print(src.crs)
    print(src.transform)
    print(src.count)
    print(src.indexes)

# 输出示例：
# (791, 718)
# {u'units': u'm', u'no_defs': True, u'ellps': u'WGS84', u'proj': u'utm', u'zone': 18}
# Affine(300.0379266750948, 0.0, 101985.0,
#        0.0, -300.041782729805, 2826915.0)
# 3
# [1, 2, 3]

数据集还提供基于地理坐标生成读写窗口（类似扩展数组切片）的方法。

.. code-block:: python

with rasterio.open('tests/data/RGB.byte.tif') as src:
    window = src.window(*src.bounds)
    print(window)
    print(src.read(window=window).shape)

# 输出示例：
# Window(col_off=0.0, row_off=0.0, width=791.0000000000002, height=718.0)
# (3, 718, 791)

命令行工具

Rasterio 的命令行工具 "rio" 文档详见 cli.rst <https://github.com/rasterio/rasterio/blob/master/docs/cli.rst>__。其中 rio insp 命令可交互式查看任意栅格数据集。

.. code-block:: pycon

$ rio insp tests/data/RGB.byte.tif
Rasterio 0.10 Interactive Inspector (Python 3.4.1)
Type "src.meta", "src.read(1)", or "help(src)" for more information.
>>> src.name
'tests/data/RGB.byte.tif'
>>> src.closed
False
>>> src.shape
(718, 791)
>>> src.crs
{'init': 'epsg:32618'}
>>> b, g, r = src.read()
>>> b
masked_array(data =
 [[-- -- -- ..., -- -- --]
 [-- -- -- ..., -- -- --]
 [-- -- -- ..., -- -- --]
 ...,
 [-- -- -- ..., -- -- --]
 [-- -- -- ..., -- -- --]
 [-- -- -- ..., -- -- --]],
             mask =
 [[ True  True  True ...,  True  True  True]
 [ True  True  True ...,  True  True  True]
 [ True  True  True ...,  True  True  True]
 ...,
 [ True  True  True ...,  True  True  True]
 [ True  True  True ...,  True  True  True]
 [ True  True  True ...,  True  True  True]],
       fill_value = 0)

>>> np.nanmin(b), np.nanmax(b), np.nanmean(b)
(0, 255, 29.94772668847656)

插件系统

Rio 支持通过插件扩展子命令功能。插件开发指南详见 cli.rst。

可用插件列表请查阅 插件注册表。

安装指南

详见 docs/installation.rst

技术支持

Rasterio 的安装使用问题请优先提交至 https://rasterio.groups.io/g/main 论坛。开发者和社区用户会在专业领域内及时解答。请确保问题描述清晰明确，并保持耐心等待回复。

为避免混淆，请勿将此类问题提交至项目 issue 跟踪系统，该渠道仅用于处理缺陷报告等可执行事项。

开发与测试

详见 CONTRIBUTING.rst。

文档资源

详见 docs/。

许可协议

详见 LICENSE.txt。

开发团队

rasterio 项目始于 Mapbox，于 2021 年 10 月转移至 rasterio Github 组织。

贡献者名单详见 AUTHORS.txt。

版本更新

详见 CHANGES.txt。

谁在使用 Rasterio？

参见 使用统计。