rasterio.crs module
Coordinate reference systems, the CRS class and supporting functions.
A coordinate reference system (CRS) defines how a dataset’s pixels map to locations on, for example, a globe or the Earth. A CRS may be local or global. The GIS field shares a number of authority files that define CRS. “EPSG:32618” is the name of a regional CRS from the European Petroleum Survey Group authority file. “OGC:CRS84” is the name of a global CRS from the Open Geospatial Consortium authority. Custom CRS can be described in text using several formats. Rasterio’s CRS class is our abstraction for coordinate reference systems.
A rasterio dataset’s crs property is an instance of CRS. CRS are also used to define transformations between coordinate reference systems. These transformations are performed by the PROJ library. Rasterio does not call PROJ functions directly, but invokes them via calls to GDAL’s “OSR*” functions.
- class rasterio.crs.CRS(initialdata=None, **kwargs)
Bases:
objectA 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.
Added in version 1.1.7.
- static from_dict(initialdata=None, **kwargs)
Make a CRS from a dict of PROJ parameters or PROJ JSON.
- static from_epsg(code)
Make a CRS from an EPSG code.
Notes
The input code is not validated against an EPSG database.
- static from_proj4(proj)
Make a CRS from a PROJ4 string.
- static from_string(value, morph_from_esri_dialect=False)
Make a CRS from an EPSG, PROJ, or WKT string
- static from_user_input(value, morph_from_esri_dialect=False)
Make a CRS from a variety of inputs.
- static from_wkt(wkt, morph_from_esri_dialect=False)
Make a CRS from a WKT string.
- get(self, item)
- is_geographic
Test if the CRS is a geographic coordinate reference system.
- is_projected
Test if the CRS is a projected coordinate reference system.
- is_valid
Test that the CRS is a geographic or projected CRS.
Deprecated since version 1.4.0: This property is not useful and will be removed in 2.0.0.
- Return type:
- items(self)
- linear_units
Get a short name for the linear units of the CRS.
- 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.
Added in version 1.3.0.
- 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.
- 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_keyslist. Values ofTrueare 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.
- to_wkt(self, morph_to_esri_dialect=False, version=None)
Convert to a OGC WKT representation.
Added 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:
- Raises:
CRSError –
- rasterio.crs.epsg_treats_as_latlong(input_crs)
Test if the CRS is in latlon order
From GDAL docs:
> This method returns TRUE if EPSG feels this geographic coordinate system should be treated as having lat/long coordinate ordering.
> Currently this returns TRUE for all geographic coordinate systems with an EPSG code set, and axes set defining it as lat, long.
> FALSE will be returned for all coordinate systems that are not geographic, or that do not have an EPSG code set.
> Note
> Important change of behavior since GDAL 3.0. In previous versions, geographic CRS imported with importFromEPSG() would cause this method to return FALSE on them, whereas now it returns TRUE, since importFromEPSG() is now equivalent to importFromEPSGA().
- rasterio.crs.epsg_treats_as_northingeasting(input_crs)
Test if the CRS should be treated as having northing/easting coordinate ordering
From GDAL docs:
> This method returns TRUE if EPSG feels this projected coordinate system should be treated as having northing/easting coordinate ordering.
> Currently this returns TRUE for all projected coordinate systems with an EPSG code set, and axes set defining it as northing, easting.
> FALSE will be returned for all coordinate systems that are not projected, or that do not have an EPSG code set.
> Note
> Important change of behavior since GDAL 3.0. In previous versions, projected CRS with northing, easting axis order imported with importFromEPSG() would cause this method to return FALSE on them, whereas now it returns TRUE, since importFromEPSG() is now equivalent to importFromEPSGA().