rasterio package

Subpackages

Submodules

Module contents

Rasterio

class rasterio.CRS(initialdata=None, **kwargs)

Bases: object

A geographic or projected coordinate reference system.

CRS objects may be created by passing PROJ parameters as keyword arguments to the standard constructor or by passing EPSG codes, PROJ mappings, PROJ strings, or WKT strings to the from_epsg, from_dict, from_string, or from_wkt static methods.

Examples

The from_dict method takes PROJ parameters as keyword arguments.

>>> crs = CRS.from_dict(proj="aea")

EPSG codes may be used with the from_epsg method.

>>> crs = CRS.from_epsg(3005)

The from_string method takes a variety of input.

>>> crs = CRS.from_string("EPSG:3005")
data

A PROJ4 dict representation of the CRS.

static from_authority(auth_name, code)

Make a CRS from an authority name and code.

New in version 1.1.7.

Parameters

  • auth_name (str) – The name of the authority.

  • code (int or str) – The code used by the authority.

Return type

CRS

Raises

CRSError –

static from_dict(initialdata=None, **kwargs)

Make a CRS from a dict of PROJ parameters or PROJ JSON.

Parameters

  • initialdata (mapping, optional) – A dictionary or other mapping

  • kwargs (mapping, optional) – Another mapping. Will be overlaid on the initialdata.

Return type

CRS

Raises

CRSError –

static from_epsg(code)

Make a CRS from an EPSG code.

Parameters

code (int or str) – An EPSG code. Strings will be converted to integers.

Notes

The input code is not validated against an EPSG database.

Return type

CRS

Raises

CRSError –

static from_proj4(proj)

Make a CRS from a PROJ4 string.

Parameters

proj (str) – A PROJ4 string like “+proj=longlat …”

Return type

CRS

Raises

CRSError –

static from_string(value, morph_from_esri_dialect=False)

Make a CRS from an EPSG, PROJ, or WKT string

Parameters

  • value (str) – An EPSG, PROJ, or WKT string.

  • morph_from_esri_dialect (bool, optional) – If True, items in the input using Esri’s dialect of WKT will be replaced by OGC standard equivalents.

Return type

CRS

Raises

CRSError –

static from_user_input(value, morph_from_esri_dialect=False)

Make a CRS from a variety of inputs.

Parameters

  • value (object) – User input of many different kinds.

  • morph_from_esri_dialect (bool, optional) – If True, items in the input using Esri’s dialect of WKT will be replaced by OGC standard equivalents.

Return type

CRS

Raises

CRSError –

static from_wkt(wkt, morph_from_esri_dialect=False)

Make a CRS from a WKT string.

Parameters

  • wkt (str) – A WKT string.

  • morph_from_esri_dialect (bool, optional) – If True, items in the input using Esri’s dialect of WKT will be replaced by OGC standard equivalents.

Return type

CRS

Raises

CRSError –

get(self, item)
is_epsg_code

Test if the CRS is defined by an EPSG code.

Return type

bool

is_geographic

Test if the CRS is a geographic coordinate reference system.

Return type

bool

Raises

CRSError –

is_projected

Test if the CRS is a projected coordinate reference system.

Return type

bool

Raises

CRSError –

is_valid

Test that the CRS is a geographic or projected CRS.

Return type

bool

items(self)
linear_units

Get a short name for the linear units of the CRS.

Returns

units – “m”, “ft”, etc.

Return type

str

Raises

CRSError –

linear_units_factor

Get linear units and the conversion factor to meters of the CRS.

Returns

  • units (str) – “m”, “ft”, etc.

  • factor (float) – Ratio of one unit to one meter.

Raises

CRSError –

to_authority(self, confidence_threshold=70)

Convert to the best match authority name and code.

For a CRS created using an EPSG code, that same value is returned. For other CRS, including custom CRS, an attempt is made to match it to definitions in authority files. Matches with a confidence below the threshold are discarded.

Parameters

confidence_threshold (int) – Percent match confidence threshold (0-100).

Returns

  • name (str) – Authority name.

  • code (str) – Code from the authority file.

  • or None

to_dict(self, projjson=False)

Convert CRS to a PROJ dict.

Note

If there is a corresponding EPSG code, it will be used when returning PROJ parameter dict.

New in version 1.3.0.

Parameters

projjson (bool, default=False) – If True, will convert to PROJ JSON dict (Requites GDAL 3.1+ and PROJ 6.2+). If False, will convert to PROJ parameter dict.

Return type

dict

to_epsg(self, confidence_threshold=70)

Convert to the best match EPSG code.

For a CRS created using an EPSG code, that same value is returned. For other CRS, including custom CRS, an attempt is made to match it to definitions in the EPSG authority file. Matches with a confidence below the threshold are discarded.

Parameters

confidence_threshold (int) – Percent match confidence threshold (0-100).

Return type

int or None

Raises

CRSError –

to_proj4(self)

Convert to a PROJ4 representation.

Return type

str

to_string(self)

Convert to a PROJ4 or WKT string.

The output will be reduced as much as possible by attempting a match to CRS defined in authority files.

Notes

Mapping keys are tested against the all_proj_keys list. Values of True are omitted, leaving the key bare: {‘no_defs’: True} -> “+no_defs” and items where the value is otherwise not a str, int, or float are omitted.

Return type

str

Raises

CRSError –

to_wkt(self, morph_to_esri_dialect=False, version=None)

Convert to a OGC WKT representation.

New in version 1.3.0: version

Parameters

  • morph_to_esri_dialect (bool, optional) – Whether or not to morph to the Esri dialect of WKT Only applies to GDAL versions < 3. This parameter will be removed in a future version of rasterio.

  • version (WktVersion or str, optional) – The version of the WKT output. Only works with GDAL 3+. Default is WKT1_GDAL.

Return type

str

Raises

CRSError –

units_factor

Get units and the conversion factor of the CRS.

Returns

  • units (str) – “m”, “ft”, etc.

  • factor (float) – Ratio of one unit to one radian if the CRS is geographic otherwise, it is to one meter.

Raises

CRSError –

wkt

An OGC WKT representation of the CRS

Return type

str

class rasterio.Env(session=None, aws_unsigned=False, profile_name=None, session_class=<function Session.aws_or_dummy>, **options)

Bases: object

Abstraction for GDAL and AWS configuration

The GDAL library is stateful: it has a registry of format drivers, an error stack, and dozens of configuration options.

Rasterio’s approach to working with GDAL is to wrap all the state up using a Python context manager (see PEP 343, https://www.python.org/dev/peps/pep-0343/). When the context is entered GDAL drivers are registered, error handlers are configured, and configuration options are set. When the context is exited, drivers are removed from the registry and other configurations are removed.

Example

with rasterio.Env(GDAL_CACHEMAX=128000000) as env:
    # All drivers are registered, GDAL's raster block cache
    # size is set to 128 MB.
    # Commence processing...
    ...
    # End of processing.

# At this point, configuration options are set to their
# previous (possible unset) values.

A boto3 session or boto3 session constructor arguments aws_access_key_id, aws_secret_access_key, aws_session_token may be passed to Env’s constructor. In the latter case, a session will be created as soon as needed. AWS credentials are configured for GDAL as needed.

credentialize()

Get credentials and configure GDAL

Note well: this method is a no-op if the GDAL environment already has credentials, unless session is not None.

Return type

None

classmethod default_options()

Default configuration options

Parameters

None –

Return type

dict

drivers()

Return a mapping of registered drivers.

classmethod from_defaults(*args, **kwargs)

Create an environment with default config options

Parameters

  • args (optional) – Positional arguments for Env()

  • kwargs (optional) – Keyword arguments for Env()

Return type

Env

Notes

The items in kwargs will be overlaid on the default values.

rasterio.band(ds, bidx)

A dataset and one or more of its bands

Parameters

  • ds (dataset object) – An opened rasterio dataset object.

  • bidx (int or sequence of ints) – Band number(s), index starting at 1.

Return type

rasterio.Band

rasterio.open(fp, mode='r', driver=None, width=None, height=None, count=None, crs=None, transform=None, dtype=None, nodata=None, sharing=False, **kwargs)

Open a dataset for reading or writing.

The dataset may be located in a local file, in a resource located by a URL, or contained within a stream of bytes.

In read (‘r’) or read/write (‘r+’) mode, no keyword arguments are required: these attributes are supplied by the opened dataset.

In write (‘w’ or ‘w+’) mode, the driver, width, height, count, and dtype keywords are strictly required.

Parameters

  • fp (str, file object, PathLike object, FilePath, or MemoryFile) – A filename or URL, a file object opened in binary (‘rb’) mode, a Path object, or one of the rasterio classes that provides the dataset-opening interface (has an open method that returns a dataset).

  • mode (str, optional) – ‘r’ (read, the default), ‘r+’ (read/write), ‘w’ (write), or ‘w+’ (write/read).

  • driver (str, optional) – A short format driver name (e.g. “GTiff” or “JPEG”) or a list of such names (see GDAL docs at https://gdal.org/drivers/raster/index.html). In ‘w’ or ‘w+’ modes a single name is required. In ‘r’ or ‘r+’ modes the driver can usually be omitted. Registered drivers will be tried sequentially until a match is found. When multiple drivers are available for a format such as JPEG2000, one of them can be selected by using this keyword argument.

  • width (int, optional) – The number of columns of the raster dataset. Required in ‘w’ or ‘w+’ modes, it is ignored in ‘r’ or ‘r+’ modes.

  • height (int, optional) – The number of rows of the raster dataset. Required in ‘w’ or ‘w+’ modes, it is ignored in ‘r’ or ‘r+’ modes.

  • count (int, optional) – The count of dataset bands. Required in ‘w’ or ‘w+’ modes, it is ignored in ‘r’ or ‘r+’ modes.

  • crs (str, dict, or CRS; optional) – The coordinate reference system. Required in ‘w’ or ‘w+’ modes, it is ignored in ‘r’ or ‘r+’ modes.

  • transform (Affine instance, optional) – 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) – 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.

  • nodata (int, float, or nan; optional) – Defines the pixel value to be interpreted as not valid data. Required in ‘w’ or ‘w+’ modes, it is ignored in ‘r’ or ‘r+’ modes.

  • sharing (bool; optional) – To reduce overhead and prevent programs from running out of file descriptors, rasterio maintains a pool of shared low level dataset handles. When True this function will use a shared handle if one is available. Multithreaded programs must avoid sharing and should set sharing to False.

  • kwargs (optional) – These are passed to format drivers as directives for creating or interpreting datasets. For example: in ‘w’ or ‘w+’ modes a tiled=True keyword argument will direct the GeoTIFF format driver to create a tiled, rather than striped, TIFF.

Return type

A DatasetReader or DatasetWriter object.

Examples

To open a GeoTIFF for reading using standard driver discovery and no directives:

>>> import rasterio
>>> with rasterio.open('example.tif') as dataset:
...     print(dataset.profile)

To open a JPEG2000 using only the JP2OpenJPEG driver:

>>> with rasterio.open(
...         'example.jp2', driver='JP2OpenJPEG') as dataset:
...     print(dataset.profile)

To create a new 8-band, 16-bit unsigned, tiled, and LZW-compressed GeoTIFF with a global extent and 0.5 degree resolution:

>>> from rasterio.transform import from_origin
>>> with rasterio.open(
...         'example.tif', 'w', driver='GTiff', dtype='uint16',
...         width=720, height=360, count=8, crs='EPSG:4326',
...         transform=from_origin(-180.0, 90.0, 0.5, 0.5),
...         nodata=0, tiled=True, compress='lzw') as dataset:
...     dataset.write(...)
rasterio.pad(array, transform, pad_width, mode=None, **kwargs)

pad array and adjust affine transform matrix.

Parameters

  • array (ndarray) – Numpy ndarray, for best results a 2D array

  • transform (Affine transform) – transform object mapping pixel space to coordinates

  • pad_width (int) – number of pixels to pad array on all four

  • mode (str or function) – define the method for determining padded values

Returns

(array, transform) – Tuple of new array and affine transform

Return type

tuple

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