+"""
+Utility methods to print system info for debugging
+
+adapted from :func:`sklearn.utils._show_versions`
+which was adapted from :func:`pandas.show_versions`
+"""
+
+import importlib.metadata
+import platform
+import sys
+
+
+def _get_sys_info():
+ """System information
+ Return
+ ------
+ sys_info : dict
+ system and Python version information
+ """
+ blob = [
+ ("python", sys.version.replace("\n", " ")),
+ ("executable", sys.executable),
+ ("machine", platform.platform()),
+ ]
+
+ return dict(blob)
+
+
+def _get_proj_info():
+ """Information on system PROJ
+
+ Returns
+ -------
+ proj_info: dict
+ system PROJ information
+ """
+ # pylint: disable=import-outside-toplevel
+ import pyproj
+ from pyproj.database import get_database_metadata
+ from pyproj.exceptions import DataDirError
+
+ try:
+ data_dir = pyproj.datadir.get_data_dir()
+ except DataDirError:
+ data_dir = None
+
+ blob = [
+ ("pyproj", pyproj.__version__),
+ ("PROJ (runtime)", pyproj.__proj_version__),
+ ("PROJ (compiled)", pyproj.__proj_compiled_version__),
+ ("data dir", data_dir),
+ ("user_data_dir", pyproj.datadir.get_user_data_dir()),
+ ("PROJ DATA (recommended version)", get_database_metadata("PROJ_DATA.VERSION")),
+ (
+ "PROJ Database",
+ f"{get_database_metadata('DATABASE.LAYOUT.VERSION.MAJOR')}."
+ f"{get_database_metadata('DATABASE.LAYOUT.VERSION.MINOR')}",
+ ),
+ (
+ "EPSG Database",
+ f"{get_database_metadata('EPSG.VERSION')} "
+ f"[{get_database_metadata('EPSG.DATE')}]",
+ ),
+ (
+ "ESRI Database",
+ f"{get_database_metadata('ESRI.VERSION')} "
+ f"[{get_database_metadata('ESRI.DATE')}]",
+ ),
+ (
+ "IGNF Database",
+ f"{get_database_metadata('IGNF.VERSION')} "
+ f"[{get_database_metadata('IGNF.DATE')}]",
+ ),
+ ]
+
+ return dict(blob)
+
+
+def _get_deps_info():
+ """Overview of the installed version of main dependencies
+ Returns
+ -------
+ deps_info: dict
+ version information on relevant Python libraries
+ """
+ deps = ["certifi", "Cython", "setuptools", "pip"]
+
+ def get_version(module):
+ try:
+ return importlib.metadata.version(module)
+ except importlib.metadata.PackageNotFoundError:
+ return None
+
+ return {dep: get_version(dep) for dep in deps}
+
+
+def _print_info_dict(info_dict):
+ """Print the information dictionary"""
+ for key, stat in info_dict.items():
+ print(f"{key:>10}: {stat}")
+
+
+
+[docs]
+def show_versions():
+ """
+ .. versionadded:: 2.2.1
+
+ Print useful debugging information
+
+ Example
+ -------
+ > python -c "import pyproj; pyproj.show_versions()"
+
+ """
+ print("pyproj info:")
+ _print_info_dict(_get_proj_info())
+ print("\nSystem:")
+ _print_info_dict(_get_sys_info())
+ print("\nPython deps:")
+ _print_info_dict(_get_deps_info())
+
+
+"""
+This module contains the structures related to areas of interest.
+"""
+
+from dataclasses import dataclass
+from typing import NamedTuple, Union
+
+from pyproj.utils import is_null
+
+
+
+[docs]
+@dataclass(frozen=True)
+class AreaOfInterest:
+ """
+ .. versionadded:: 2.3.0
+
+ This is the area of interest for:
+
+ - Transformations
+ - Querying for CRS data.
+ """
+
+ #: The west bound in degrees of the area of interest.
+ west_lon_degree: float
+ #: The south bound in degrees of the area of interest.
+ south_lat_degree: float
+ #: The east bound in degrees of the area of interest.
+ east_lon_degree: float
+ #: The north bound in degrees of the area of interest.
+ north_lat_degree: float
+
+ def __post_init__(self):
+ if (
+ is_null(self.west_lon_degree)
+ or is_null(self.south_lat_degree)
+ or is_null(self.east_lon_degree)
+ or is_null(self.north_lat_degree)
+ ):
+ raise ValueError("NaN or None values are not allowed.")
+
+
+
+
+[docs]
+class AreaOfUse(NamedTuple):
+ """
+ .. versionadded:: 2.0.0
+
+ Area of Use for CRS, CoordinateOperation, or a Transformer.
+ """
+
+ #: West bound of area of use.
+ west: float
+ #: South bound of area of use.
+ south: float
+ #: East bound of area of use.
+ east: float
+ #: North bound of area of use.
+ north: float
+ #: Name of area of use.
+ name: str | None = None
+
+ @property
+ def bounds(self) -> tuple[float, float, float, float]:
+ """
+ The bounds of the area of use.
+
+ Returns
+ -------
+ tuple[float, float, float, float]
+ west, south, east, and north bounds.
+ """
+ return self.west, self.south, self.east, self.north
+
+ def __str__(self) -> str:
+ return f"- name: {self.name}\n" f"- bounds: {self.bounds}"
+
+
+
+
+[docs]
+@dataclass
+class BBox:
+ """
+ Bounding box to check if data intersects/contains other
+ bounding boxes.
+
+ .. versionadded:: 3.0.0
+
+ """
+
+ #: West bound of bounding box.
+ west: float
+ #: South bound of bounding box.
+ south: float
+ #: East bound of bounding box.
+ east: float
+ #: North bound of bounding box.
+ north: float
+
+ def __post_init__(self):
+ if (
+ is_null(self.west)
+ or is_null(self.south)
+ or is_null(self.east)
+ or is_null(self.north)
+ ):
+ raise ValueError("NaN or None values are not allowed.")
+
+
+[docs]
+ def intersects(self, other: Union["BBox", AreaOfUse]) -> bool:
+ """
+ Parameters
+ ----------
+ other: BBox
+ The other BBox to use to check.
+
+ Returns
+ -------
+ bool:
+ True if this BBox intersects the other bbox.
+ """
+ return (
+ self.west < other.east
+ and other.west < self.east
+ and self.south < other.north
+ and other.south < self.north
+ )
+
+
+
+[docs]
+ def contains(self, other: Union["BBox", AreaOfUse]) -> bool:
+ """
+ Parameters
+ ----------
+ other: Union["BBox", AreaOfUse]
+ The other BBox to use to check.
+
+ Returns
+ -------
+ bool:
+ True if this BBox contains the other bbox.
+ """
+ return (
+ other.west >= self.west
+ and other.east <= self.east
+ and other.south >= self.south
+ and other.north <= self.north
+ )
+
+
+
+"""
+This module is for building operations to be used when
+building a CRS.
+
+:ref:`operations`
+"""
+
+# pylint: disable=too-many-lines
+import warnings
+from typing import Any, Optional
+
+from pyproj._crs import CoordinateOperation
+from pyproj._version import PROJ_VERSION
+from pyproj.exceptions import CRSError
+
+
+
+[docs]
+class AlbersEqualAreaConversion(CoordinateOperation):
+ """
+ .. versionadded:: 2.5.0
+
+ Class for constructing the Albers Equal Area Conversion.
+
+ :ref:`PROJ docs <aea>`
+ """
+
+
+[docs]
+ def __new__(
+ cls,
+ latitude_first_parallel: float,
+ latitude_second_parallel: float,
+ latitude_false_origin: float = 0.0,
+ longitude_false_origin: float = 0.0,
+ easting_false_origin: float = 0.0,
+ northing_false_origin: float = 0.0,
+ ):
+ """
+ Parameters
+ ----------
+ latitude_first_parallel: float
+ First standard parallel (lat_1).
+ latitude_second_parallel: float
+ Second standard parallel (lat_2).
+ latitude_false_origin: float, default=0.0
+ Latitude of projection center (lat_0).
+ longitude_false_origin: float, default=0.0
+ Longitude of projection center (lon_0).
+ easting_false_origin: float, default=0.0
+ False easting (x_0).
+ northing_false_origin: float, default=0.0
+ False northing (y_0).
+ """
+ aea_json = {
+ "$schema": "https://proj.org/schemas/v0.2/projjson.schema.json",
+ "type": "Conversion",
+ "name": "unknown",
+ "method": {
+ "name": "Albers Equal Area",
+ "id": {"authority": "EPSG", "code": 9822},
+ },
+ "parameters": [
+ {
+ "name": "Latitude of false origin",
+ "value": latitude_false_origin,
+ "unit": "degree",
+ "id": {"authority": "EPSG", "code": 8821},
+ },
+ {
+ "name": "Longitude of false origin",
+ "value": longitude_false_origin,
+ "unit": "degree",
+ "id": {"authority": "EPSG", "code": 8822},
+ },
+ {
+ "name": "Latitude of 1st standard parallel",
+ "value": latitude_first_parallel,
+ "unit": "degree",
+ "id": {"authority": "EPSG", "code": 8823},
+ },
+ {
+ "name": "Latitude of 2nd standard parallel",
+ "value": latitude_second_parallel,
+ "unit": "degree",
+ "id": {"authority": "EPSG", "code": 8824},
+ },
+ {
+ "name": "Easting at false origin",
+ "value": easting_false_origin,
+ "unit": {
+ "type": "LinearUnit",
+ "name": "Metre",
+ "conversion_factor": 1,
+ },
+ "id": {"authority": "EPSG", "code": 8826},
+ },
+ {
+ "name": "Northing at false origin",
+ "value": northing_false_origin,
+ "unit": {
+ "type": "LinearUnit",
+ "name": "Metre",
+ "conversion_factor": 1,
+ },
+ "id": {"authority": "EPSG", "code": 8827},
+ },
+ ],
+ }
+ return cls.from_json_dict(aea_json)
+
+
+
+
+
+[docs]
+class AzimuthalEquidistantConversion(CoordinateOperation):
+ """
+ .. versionadded:: 2.5.0 AzumuthalEquidistantConversion
+ .. versionadded:: 3.2.0 AzimuthalEquidistantConversion
+
+ Class for constructing the Modified Azimuthal Equidistant conversion.
+
+ :ref:`PROJ docs <aeqd>`
+ """
+
+
+[docs]
+ def __new__(
+ cls,
+ latitude_natural_origin: float = 0.0,
+ longitude_natural_origin: float = 0.0,
+ false_easting: float = 0.0,
+ false_northing: float = 0.0,
+ ):
+ """
+ Parameters
+ ----------
+ latitude_natural_origin: float, default=0.0
+ Latitude of projection center (lat_0).
+ longitude_natural_origin: float, default=0.0
+ Longitude of projection center (lon_0).
+ false_easting: float, default=0.0
+ False easting (x_0).
+ false_northing: float, default=0.0
+ False northing (y_0).
+
+ """
+ aeqd_json = {
+ "$schema": "https://proj.org/schemas/v0.2/projjson.schema.json",
+ "type": "Conversion",
+ "name": "unknown",
+ "method": {
+ "name": "Modified Azimuthal Equidistant",
+ "id": {"authority": "EPSG", "code": 9832},
+ },
+ "parameters": [
+ {
+ "name": "Latitude of natural origin",
+ "value": latitude_natural_origin,
+ "unit": "degree",
+ "id": {"authority": "EPSG", "code": 8801},
+ },
+ {
+ "name": "Longitude of natural origin",
+ "value": longitude_natural_origin,
+ "unit": "degree",
+ "id": {"authority": "EPSG", "code": 8802},
+ },
+ {
+ "name": "False easting",
+ "value": false_easting,
+ "unit": "metre",
+ "id": {"authority": "EPSG", "code": 8806},
+ },
+ {
+ "name": "False northing",
+ "value": false_northing,
+ "unit": "metre",
+ "id": {"authority": "EPSG", "code": 8807},
+ },
+ ],
+ }
+ return cls.from_json_dict(aeqd_json)
+
+
+
+
+
+[docs]
+class GeostationarySatelliteConversion(CoordinateOperation):
+ """
+ .. versionadded:: 2.5.0
+
+ Class for constructing the Geostationary Satellite conversion.
+
+ :ref:`PROJ docs <geos>`
+ """
+
+
+[docs]
+ def __new__(
+ cls,
+ sweep_angle_axis: str,
+ satellite_height: float,
+ latitude_natural_origin: float = 0.0,
+ longitude_natural_origin: float = 0.0,
+ false_easting: float = 0.0,
+ false_northing: float = 0.0,
+ ):
+ """
+ Parameters
+ ----------
+ sweep_angle_axis: str
+ Sweep angle axis of the viewing instrument. Valid options are “X” and “Y”.
+ satellite_height: float
+ Satellite height.
+ latitude_natural_origin: float, default=0.0
+ Latitude of projection center (lat_0).
+ longitude_natural_origin: float, default=0.0
+ Longitude of projection center (lon_0).
+ false_easting: float, default=0.0
+ False easting (x_0).
+ false_northing: float, default=0.0
+ False northing (y_0).
+
+ """
+ sweep_angle_axis = sweep_angle_axis.strip().upper()
+ valid_sweep_axis = ("X", "Y")
+ if sweep_angle_axis not in valid_sweep_axis:
+ raise CRSError(f"sweep_angle_axis only supports {valid_sweep_axis}")
+
+ if latitude_natural_origin != 0:
+ warnings.warn(
+ "The latitude of natural origin (lat_0) is not used "
+ "within PROJ. It is only supported for exporting to "
+ "the WKT or PROJ JSON formats."
+ )
+
+ geos_json = {
+ "$schema": "https://proj.org/schemas/v0.2/projjson.schema.json",
+ "type": "Conversion",
+ "name": "unknown",
+ "method": {"name": f"Geostationary Satellite (Sweep {sweep_angle_axis})"},
+ "parameters": [
+ {
+ "name": "Satellite height",
+ "value": satellite_height,
+ "unit": "metre",
+ },
+ {
+ "name": "Latitude of natural origin",
+ "value": latitude_natural_origin,
+ "unit": "degree",
+ "id": {"authority": "EPSG", "code": 8801},
+ },
+ {
+ "name": "Longitude of natural origin",
+ "value": longitude_natural_origin,
+ "unit": "degree",
+ "id": {"authority": "EPSG", "code": 8802},
+ },
+ {
+ "name": "False easting",
+ "value": false_easting,
+ "unit": "metre",
+ "id": {"authority": "EPSG", "code": 8806},
+ },
+ {
+ "name": "False northing",
+ "value": false_northing,
+ "unit": "metre",
+ "id": {"authority": "EPSG", "code": 8807},
+ },
+ ],
+ }
+ return cls.from_json_dict(geos_json)
+
+
+
+
+
+[docs]
+class LambertAzimuthalEqualAreaConversion(CoordinateOperation):
+ """
+ .. versionadded:: 2.5.0 LambertAzumuthalEqualAreaConversion
+ .. versionadded:: 3.2.0 LambertAzimuthalEqualAreaConversion
+
+ Class for constructing the Lambert Azimuthal Equal Area conversion.
+
+ :ref:`PROJ docs <laea>`
+ """
+
+
+[docs]
+ def __new__(
+ cls,
+ latitude_natural_origin: float = 0.0,
+ longitude_natural_origin: float = 0.0,
+ false_easting: float = 0.0,
+ false_northing: float = 0.0,
+ ):
+ """
+ Parameters
+ ----------
+ latitude_natural_origin: float, default=0.0
+ Latitude of projection center (lat_0).
+ longitude_natural_origin: float, default=0.0
+ Longitude of projection center (lon_0).
+ false_easting: float, default=0.0
+ False easting (x_0).
+ false_northing: float, default=0.0
+ False northing (y_0).
+
+ """
+ laea_json = {
+ "$schema": "https://proj.org/schemas/v0.2/projjson.schema.json",
+ "type": "Conversion",
+ "name": "unknown",
+ "method": {
+ "name": "Lambert Azimuthal Equal Area",
+ "id": {"authority": "EPSG", "code": 9820},
+ },
+ "parameters": [
+ {
+ "name": "Latitude of natural origin",
+ "value": latitude_natural_origin,
+ "unit": "degree",
+ "id": {"authority": "EPSG", "code": 8801},
+ },
+ {
+ "name": "Longitude of natural origin",
+ "value": longitude_natural_origin,
+ "unit": "degree",
+ "id": {"authority": "EPSG", "code": 8802},
+ },
+ {
+ "name": "False easting",
+ "value": false_easting,
+ "unit": "metre",
+ "id": {"authority": "EPSG", "code": 8806},
+ },
+ {
+ "name": "False northing",
+ "value": false_northing,
+ "unit": "metre",
+ "id": {"authority": "EPSG", "code": 8807},
+ },
+ ],
+ }
+ return cls.from_json_dict(laea_json)
+
+
+
+
+
+[docs]
+class LambertConformalConic2SPConversion(CoordinateOperation):
+ """
+ .. versionadded:: 2.5.0
+
+ Class for constructing the Lambert Conformal Conic 2SP conversion.
+
+ :ref:`PROJ docs <lcc>`
+ """
+
+
+[docs]
+ def __new__(
+ cls,
+ latitude_first_parallel: float,
+ latitude_second_parallel: float,
+ latitude_false_origin: float = 0.0,
+ longitude_false_origin: float = 0.0,
+ easting_false_origin: float = 0.0,
+ northing_false_origin: float = 0.0,
+ ):
+ """
+ Parameters
+ ----------
+ latitude_first_parallel: float
+ Latitude of 1st standard parallel (lat_1).
+ latitude_second_parallel: float
+ Latitude of 2nd standard parallel (lat_2).
+ latitude_false_origin: float, default=0.0
+ Latitude of projection center (lat_0).
+ longitude_false_origin: float, default=0.0
+ Longitude of projection center (lon_0).
+ easting_false_origin: float, default=0.0
+ False easting (x_0).
+ northing_false_origin: float, default=0.0
+ False northing (y_0).
+
+ """
+ lcc_json = {
+ "$schema": "https://proj.org/schemas/v0.2/projjson.schema.json",
+ "type": "Conversion",
+ "name": "unknown",
+ "method": {
+ "name": "Lambert Conic Conformal (2SP)",
+ "id": {"authority": "EPSG", "code": 9802},
+ },
+ "parameters": [
+ {
+ "name": "Latitude of 1st standard parallel",
+ "value": latitude_first_parallel,
+ "unit": "degree",
+ "id": {"authority": "EPSG", "code": 8823},
+ },
+ {
+ "name": "Latitude of 2nd standard parallel",
+ "value": latitude_second_parallel,
+ "unit": "degree",
+ "id": {"authority": "EPSG", "code": 8824},
+ },
+ {
+ "name": "Latitude of false origin",
+ "value": latitude_false_origin,
+ "unit": "degree",
+ "id": {"authority": "EPSG", "code": 8821},
+ },
+ {
+ "name": "Longitude of false origin",
+ "value": longitude_false_origin,
+ "unit": "degree",
+ "id": {"authority": "EPSG", "code": 8822},
+ },
+ {
+ "name": "Easting at false origin",
+ "value": easting_false_origin,
+ "unit": "metre",
+ "id": {"authority": "EPSG", "code": 8826},
+ },
+ {
+ "name": "Northing at false origin",
+ "value": northing_false_origin,
+ "unit": "metre",
+ "id": {"authority": "EPSG", "code": 8827},
+ },
+ ],
+ }
+ return cls.from_json_dict(lcc_json)
+
+
+
+
+
+[docs]
+class LambertConformalConic1SPConversion(CoordinateOperation):
+ """
+ .. versionadded:: 2.5.0
+
+ Class for constructing the Lambert Conformal Conic 1SP conversion.
+
+ :ref:`PROJ docs <lcc>`
+ """
+
+
+[docs]
+ def __new__(
+ cls,
+ latitude_natural_origin: float = 0.0,
+ longitude_natural_origin: float = 0.0,
+ false_easting: float = 0.0,
+ false_northing: float = 0.0,
+ scale_factor_natural_origin: float = 1.0,
+ ):
+ """
+ Parameters
+ ----------
+ latitude_natural_origin: float, default=0.0
+ Latitude of projection center (lat_0).
+ longitude_natural_origin: float, default=0.0
+ Longitude of projection center (lon_0).
+ false_easting: float, default=0.0
+ False easting (x_0).
+ false_northing: float, default=0.0
+ False northing (y_0).
+ scale_factor_natural_origin: float, default=1.0
+ Scale factor at natural origin (k_0).
+
+ """
+ lcc_json = {
+ "$schema": "https://proj.org/schemas/v0.2/projjson.schema.json",
+ "type": "Conversion",
+ "name": "unknown",
+ "method": {
+ "name": "Lambert Conic Conformal (1SP)",
+ "id": {"authority": "EPSG", "code": 9801},
+ },
+ "parameters": [
+ {
+ "name": "Latitude of natural origin",
+ "value": latitude_natural_origin,
+ "unit": "degree",
+ "id": {"authority": "EPSG", "code": 8801},
+ },
+ {
+ "name": "Longitude of natural origin",
+ "value": longitude_natural_origin,
+ "unit": "degree",
+ "id": {"authority": "EPSG", "code": 8802},
+ },
+ {
+ "name": "Scale factor at natural origin",
+ "value": scale_factor_natural_origin,
+ "unit": "unity",
+ "id": {"authority": "EPSG", "code": 8805},
+ },
+ {
+ "name": "False easting",
+ "value": false_easting,
+ "unit": "metre",
+ "id": {"authority": "EPSG", "code": 8806},
+ },
+ {
+ "name": "False northing",
+ "value": false_northing,
+ "unit": "metre",
+ "id": {"authority": "EPSG", "code": 8807},
+ },
+ ],
+ }
+ return cls.from_json_dict(lcc_json)
+
+
+
+
+
+[docs]
+class LambertCylindricalEqualAreaConversion(CoordinateOperation):
+ """
+ .. versionadded:: 2.5.0
+
+ Class for constructing the Lambert Cylindrical Equal Area conversion.
+
+ :ref:`PROJ docs <cea>`
+ """
+
+
+[docs]
+ def __new__(
+ cls,
+ latitude_first_parallel: float = 0.0,
+ longitude_natural_origin: float = 0.0,
+ false_easting: float = 0.0,
+ false_northing: float = 0.0,
+ ):
+ """
+ Parameters
+ ----------
+ latitude_first_parallel: float, default=0.0
+ Latitude of 1st standard parallel (lat_ts).
+ longitude_natural_origin: float, default=0.0
+ Longitude of projection center (lon_0).
+ false_easting: float, default=0.0
+ False easting (x_0).
+ false_northing: float, default=0.0
+ False northing (y_0).
+
+ """
+ cea_json = {
+ "$schema": "https://proj.org/schemas/v0.2/projjson.schema.json",
+ "type": "Conversion",
+ "name": "unknown",
+ "method": {
+ "name": "Lambert Cylindrical Equal Area",
+ "id": {"authority": "EPSG", "code": 9835},
+ },
+ "parameters": [
+ {
+ "name": "Latitude of 1st standard parallel",
+ "value": latitude_first_parallel,
+ "unit": "degree",
+ "id": {"authority": "EPSG", "code": 8823},
+ },
+ {
+ "name": "Longitude of natural origin",
+ "value": longitude_natural_origin,
+ "unit": "degree",
+ "id": {"authority": "EPSG", "code": 8802},
+ },
+ {
+ "name": "False easting",
+ "value": false_easting,
+ "unit": "metre",
+ "id": {"authority": "EPSG", "code": 8806},
+ },
+ {
+ "name": "False northing",
+ "value": false_northing,
+ "unit": "metre",
+ "id": {"authority": "EPSG", "code": 8807},
+ },
+ ],
+ }
+ return cls.from_json_dict(cea_json)
+
+
+
+
+
+[docs]
+class LambertCylindricalEqualAreaScaleConversion(CoordinateOperation):
+ """
+ .. versionadded:: 2.5.0
+
+ Class for constructing the Lambert Cylindrical Equal Area conversion.
+
+ This version uses the scale factor and differs from the official version.
+
+ The scale factor will be converted to the Latitude of 1st standard parallel (lat_ts)
+ when exporting to WKT in PROJ>=7.0.0. Previous version will export it as a
+ PROJ-based coordinate operation in the WKT.
+
+ :ref:`PROJ docs <cea>`
+ """
+
+ def __new__(
+ cls,
+ longitude_natural_origin: float = 0.0,
+ false_easting: float = 0.0,
+ false_northing: float = 0.0,
+ scale_factor_natural_origin: float = 1.0,
+ ):
+ """
+ Parameters
+ ----------
+ longitude_natural_origin: float, default=0.0
+ Longitude of projection center (lon_0).
+ false_easting: float, default=0.0
+ False easting (x_0).
+ false_northing: float, default=0.0
+ False northing (y_0).
+ scale_factor_natural_origin: float, default=1.0
+ Scale factor at natural origin (k or k_0).
+
+ """
+ # pylint: disable=import-outside-toplevel
+ from pyproj.crs import CRS
+
+ # hack due to: https://github.com/OSGeo/PROJ/issues/1881
+ proj_string = (
+ "+proj=cea "
+ f"+lon_0={longitude_natural_origin} "
+ f"+x_0={false_easting} "
+ f"+y_0={false_northing} "
+ f"+k_0={scale_factor_natural_origin}"
+ )
+ return cls.from_json(
+ CRS(proj_string).coordinate_operation.to_json() # type: ignore
+ )
+
+
+
+
+[docs]
+class MercatorAConversion(CoordinateOperation):
+ """
+ .. versionadded:: 2.5.0
+
+ Class for constructing the Mercator (variant A) conversion.
+
+ :ref:`PROJ docs <merc>`
+ """
+
+
+[docs]
+ def __new__(
+ cls,
+ latitude_natural_origin: float = 0.0,
+ longitude_natural_origin: float = 0.0,
+ false_easting: float = 0.0,
+ false_northing: float = 0.0,
+ scale_factor_natural_origin: float = 1.0,
+ ):
+ """
+ Parameters
+ ----------
+ latitude_natural_origin: float, default=0.0
+ Latitude of natural origin (lat_0). Must be 0 by `this conversion's
+ definition
+ <https://epsg.org/coord-operation-method_9804/Mercator-variant-A.html>`_.
+ longitude_natural_origin: float, default=0.0
+ Longitude of natural origin (lon_0).
+ false_easting: float, default=0.0
+ False easting (x_0).
+ false_northing: float, default=0.0
+ False northing (y_0).
+ scale_factor_natural_origin: float, default=1.0
+ Scale factor at natural origin (k or k_0).
+
+ """
+ if latitude_natural_origin != 0:
+ raise CRSError(
+ "This conversion is defined for only latitude_natural_origin = 0."
+ )
+ merc_json = {
+ "$schema": "https://proj.org/schemas/v0.2/projjson.schema.json",
+ "type": "Conversion",
+ "name": "unknown",
+ "method": {
+ "name": "Mercator (variant A)",
+ "id": {"authority": "EPSG", "code": 9804},
+ },
+ "parameters": [
+ {
+ "name": "Latitude of natural origin",
+ "value": latitude_natural_origin,
+ "unit": "degree",
+ "id": {"authority": "EPSG", "code": 8801},
+ },
+ {
+ "name": "Longitude of natural origin",
+ "value": longitude_natural_origin,
+ "unit": "degree",
+ "id": {"authority": "EPSG", "code": 8802},
+ },
+ {
+ "name": "Scale factor at natural origin",
+ "value": scale_factor_natural_origin,
+ "unit": "unity",
+ "id": {"authority": "EPSG", "code": 8805},
+ },
+ {
+ "name": "False easting",
+ "value": false_easting,
+ "unit": "metre",
+ "id": {"authority": "EPSG", "code": 8806},
+ },
+ {
+ "name": "False northing",
+ "value": false_northing,
+ "unit": "metre",
+ "id": {"authority": "EPSG", "code": 8807},
+ },
+ ],
+ }
+ return cls.from_json_dict(merc_json)
+
+
+
+
+
+[docs]
+class MercatorBConversion(CoordinateOperation):
+ """
+ .. versionadded:: 2.5.0
+
+ Class for constructing the Mercator (variant B) conversion.
+
+ :ref:`PROJ docs <merc>`
+ """
+
+
+[docs]
+ def __new__(
+ cls,
+ latitude_first_parallel: float = 0.0,
+ longitude_natural_origin: float = 0.0,
+ false_easting: float = 0.0,
+ false_northing: float = 0.0,
+ ):
+ """
+ Parameters
+ ----------
+ latitude_first_parallel: float, default=0.0
+ Latitude of 1st standard parallel (lat_ts).
+ longitude_natural_origin: float, default=0.0
+ Longitude of projection center (lon_0).
+ false_easting: float, default=0.0
+ False easting (x_0).
+ false_northing: float, default=0.0
+ False northing (y_0).
+
+ """
+ merc_json = {
+ "$schema": "https://proj.org/schemas/v0.2/projjson.schema.json",
+ "type": "Conversion",
+ "name": "unknown",
+ "method": {
+ "name": "Mercator (variant B)",
+ "id": {"authority": "EPSG", "code": 9805},
+ },
+ "parameters": [
+ {
+ "name": "Latitude of 1st standard parallel",
+ "value": latitude_first_parallel,
+ "unit": "degree",
+ "id": {"authority": "EPSG", "code": 8823},
+ },
+ {
+ "name": "Longitude of natural origin",
+ "value": longitude_natural_origin,
+ "unit": "degree",
+ "id": {"authority": "EPSG", "code": 8802},
+ },
+ {
+ "name": "False easting",
+ "value": false_easting,
+ "unit": "metre",
+ "id": {"authority": "EPSG", "code": 8806},
+ },
+ {
+ "name": "False northing",
+ "value": false_northing,
+ "unit": "metre",
+ "id": {"authority": "EPSG", "code": 8807},
+ },
+ ],
+ }
+ return cls.from_json_dict(merc_json)
+
+
+
+
+
+[docs]
+class HotineObliqueMercatorBConversion(CoordinateOperation):
+ """
+ .. versionadded:: 2.5.0
+ .. versionadded:: 3.7.0 azimuth_projection_centre, scale_factor_projection_centre
+
+ Class for constructing the Hotine Oblique Mercator (variant B) conversion.
+
+ :ref:`PROJ docs <omerc>`
+ """
+
+
+[docs]
+ def __new__(
+ cls,
+ latitude_projection_centre: float,
+ longitude_projection_centre: float,
+ angle_from_rectified_to_skew_grid: float,
+ easting_projection_centre: float = 0.0,
+ northing_projection_centre: float = 0.0,
+ azimuth_projection_centre: Optional[float] = None,
+ scale_factor_projection_centre: Optional[float] = None,
+ azimuth_initial_line: Optional[float] = None,
+ scale_factor_on_initial_line: Optional[float] = None,
+ ):
+ """
+ Parameters
+ ----------
+ latitude_projection_centre: float
+ Latitude of projection centre (lat_0).
+ longitude_projection_centre: float
+ Longitude of projection centre (lonc).
+ azimuth_projection_centre: float
+ Azimuth of initial line (alpha).
+ angle_from_rectified_to_skew_grid: float
+ Angle from Rectified to Skew Grid (gamma).
+ scale_factor_projection_centre: float, default=1.0
+ Scale factor on initial line (k or k_0).
+ easting_projection_centre: float, default=0.0
+ Easting at projection centre (x_0).
+ northing_projection_centre: float, default=0.0
+ Northing at projection centre (y_0).
+ azimuth_initial_line: float
+ Deprecated alias for azimuth_projection_centre,
+ scale_factor_on_initial_line: float
+ Deprecated alias for scale_factor_projection_centre.
+ """
+ if scale_factor_on_initial_line is not None:
+ if scale_factor_projection_centre is not None:
+ raise ValueError(
+ "scale_factor_projection_centre and scale_factor_on_initial_line "
+ "cannot be provided together."
+ )
+ warnings.warn(
+ "scale_factor_on_initial_line is deprecated. "
+ "Use scale_factor_projection_centre instead.",
+ FutureWarning,
+ stacklevel=2,
+ )
+ scale_factor_projection_centre = scale_factor_on_initial_line
+ elif scale_factor_projection_centre is None:
+ scale_factor_projection_centre = 1.0
+
+ if azimuth_projection_centre is None and azimuth_initial_line is None:
+ raise ValueError(
+ "azimuth_projection_centre or azimuth_initial_line must be provided."
+ )
+ if azimuth_initial_line is not None:
+ if azimuth_projection_centre is not None:
+ raise ValueError(
+ "azimuth_projection_centre and azimuth_initial_line cannot be "
+ "provided together."
+ )
+ warnings.warn(
+ "azimuth_initial_line is deprecated. "
+ "Use azimuth_projection_centre instead.",
+ FutureWarning,
+ stacklevel=2,
+ )
+ azimuth_projection_centre = azimuth_initial_line
+
+ omerc_json = {
+ "$schema": "https://proj.org/schemas/v0.2/projjson.schema.json",
+ "type": "Conversion",
+ "name": "unknown",
+ "method": {
+ "name": "Hotine Oblique Mercator (variant B)",
+ "id": {"authority": "EPSG", "code": 9815},
+ },
+ "parameters": [
+ {
+ "name": "Latitude of projection centre",
+ "value": latitude_projection_centre,
+ "unit": "degree",
+ "id": {"authority": "EPSG", "code": 8811},
+ },
+ {
+ "name": "Longitude of projection centre",
+ "value": longitude_projection_centre,
+ "unit": "degree",
+ "id": {"authority": "EPSG", "code": 8812},
+ },
+ {
+ "name": (
+ "Azimuth at projection centre"
+ if PROJ_VERSION >= (9, 5, 0)
+ else "Azimuth of initial line"
+ ),
+ "value": azimuth_projection_centre,
+ "unit": "degree",
+ "id": {"authority": "EPSG", "code": 8813},
+ },
+ {
+ "name": "Angle from Rectified to Skew Grid",
+ "value": angle_from_rectified_to_skew_grid,
+ "unit": "degree",
+ "id": {"authority": "EPSG", "code": 8814},
+ },
+ {
+ "name": (
+ "Scale factor at projection centre"
+ if PROJ_VERSION >= (9, 5, 0)
+ else "Scale factor on initial line"
+ ),
+ "value": scale_factor_projection_centre,
+ "unit": "unity",
+ "id": {"authority": "EPSG", "code": 8815},
+ },
+ {
+ "name": "Easting at projection centre",
+ "value": easting_projection_centre,
+ "unit": "metre",
+ "id": {"authority": "EPSG", "code": 8816},
+ },
+ {
+ "name": "Northing at projection centre",
+ "value": northing_projection_centre,
+ "unit": "metre",
+ "id": {"authority": "EPSG", "code": 8817},
+ },
+ ],
+ }
+ return cls.from_json_dict(omerc_json)
+
+
+
+
+
+[docs]
+class OrthographicConversion(CoordinateOperation):
+ """
+ .. versionadded:: 2.5.0
+
+ Class for constructing the Orthographic conversion.
+
+ :ref:`PROJ docs <ortho>`
+ """
+
+
+[docs]
+ def __new__(
+ cls,
+ latitude_natural_origin: float = 0.0,
+ longitude_natural_origin: float = 0.0,
+ false_easting: float = 0.0,
+ false_northing: float = 0.0,
+ ):
+ """
+ Parameters
+ ----------
+ latitude_natural_origin: float, default=0.0
+ Latitude of projection center (lat_0).
+ longitude_natural_origin: float, default=0.0
+ Longitude of projection center (lon_0).
+ false_easting: float, default=0.0
+ False easting (x_0).
+ false_northing: float, default=0.0
+ False northing (y_0).
+
+ """
+ ortho_json = {
+ "$schema": "https://proj.org/schemas/v0.2/projjson.schema.json",
+ "type": "Conversion",
+ "name": "unknown",
+ "method": {
+ "name": "Orthographic",
+ "id": {"authority": "EPSG", "code": 9840},
+ },
+ "parameters": [
+ {
+ "name": "Latitude of natural origin",
+ "value": latitude_natural_origin,
+ "unit": "degree",
+ "id": {"authority": "EPSG", "code": 8801},
+ },
+ {
+ "name": "Longitude of natural origin",
+ "value": longitude_natural_origin,
+ "unit": "degree",
+ "id": {"authority": "EPSG", "code": 8802},
+ },
+ {
+ "name": "False easting",
+ "value": false_easting,
+ "unit": "metre",
+ "id": {"authority": "EPSG", "code": 8806},
+ },
+ {
+ "name": "False northing",
+ "value": false_northing,
+ "unit": "metre",
+ "id": {"authority": "EPSG", "code": 8807},
+ },
+ ],
+ }
+ return cls.from_json_dict(ortho_json)
+
+
+
+
+
+[docs]
+class PolarStereographicAConversion(CoordinateOperation):
+ """
+ .. versionadded:: 2.5.0
+
+ Class for constructing the Polar Stereographic A conversion.
+
+ :ref:`PROJ docs <stere>`
+ """
+
+
+[docs]
+ def __new__(
+ cls,
+ latitude_natural_origin: float,
+ longitude_natural_origin: float = 0.0,
+ false_easting: float = 0.0,
+ false_northing: float = 0.0,
+ scale_factor_natural_origin: float = 1.0,
+ ):
+ """
+ Parameters
+ ----------
+ latitude_natural_origin: float
+ Latitude of natural origin (lat_0). Either +90 or -90.
+ longitude_natural_origin: float, default=0.0
+ Longitude of natural origin (lon_0).
+ false_easting: float, default=0.0
+ False easting (x_0).
+ false_northing: float, default=0.0
+ False northing (y_0).
+ scale_factor_natural_origin: float, default=0.0
+ Scale factor at natural origin (k or k_0).
+
+ """
+
+ stere_json = {
+ "$schema": "https://proj.org/schemas/v0.2/projjson.schema.json",
+ "type": "Conversion",
+ "name": "unknown",
+ "method": {
+ "name": "Polar Stereographic (variant A)",
+ "id": {"authority": "EPSG", "code": 9810},
+ },
+ "parameters": [
+ {
+ "name": "Latitude of natural origin",
+ "value": latitude_natural_origin,
+ "unit": "degree",
+ "id": {"authority": "EPSG", "code": 8801},
+ },
+ {
+ "name": "Longitude of natural origin",
+ "value": longitude_natural_origin,
+ "unit": "degree",
+ "id": {"authority": "EPSG", "code": 8802},
+ },
+ {
+ "name": "Scale factor at natural origin",
+ "value": scale_factor_natural_origin,
+ "unit": "unity",
+ "id": {"authority": "EPSG", "code": 8805},
+ },
+ {
+ "name": "False easting",
+ "value": false_easting,
+ "unit": "metre",
+ "id": {"authority": "EPSG", "code": 8806},
+ },
+ {
+ "name": "False northing",
+ "value": false_northing,
+ "unit": "metre",
+ "id": {"authority": "EPSG", "code": 8807},
+ },
+ ],
+ }
+ return cls.from_json_dict(stere_json)
+
+
+
+
+
+[docs]
+class PolarStereographicBConversion(CoordinateOperation):
+ """
+ .. versionadded:: 2.5.0
+
+ Class for constructing the Polar Stereographic B conversion.
+
+ :ref:`PROJ docs <stere>`
+ """
+
+
+[docs]
+ def __new__(
+ cls,
+ latitude_standard_parallel: float = 0.0,
+ longitude_origin: float = 0.0,
+ false_easting: float = 0.0,
+ false_northing: float = 0.0,
+ ):
+ """
+ Parameters
+ ----------
+ latitude_standard_parallel: float, default=0.0
+ Latitude of standard parallel (lat_ts).
+ longitude_origin: float, default=0.0
+ Longitude of origin (lon_0).
+ false_easting: float, default=0.0
+ False easting (x_0).
+ false_northing: float, default=0.0
+ False northing (y_0).
+
+ """
+ stere_json = {
+ "$schema": "https://proj.org/schemas/v0.2/projjson.schema.json",
+ "type": "Conversion",
+ "name": "unknown",
+ "method": {
+ "name": "Polar Stereographic (variant B)",
+ "id": {"authority": "EPSG", "code": 9829},
+ },
+ "parameters": [
+ {
+ "name": "Latitude of standard parallel",
+ "value": latitude_standard_parallel,
+ "unit": "degree",
+ "id": {"authority": "EPSG", "code": 8832},
+ },
+ {
+ "name": "Longitude of origin",
+ "value": longitude_origin,
+ "unit": "degree",
+ "id": {"authority": "EPSG", "code": 8833},
+ },
+ {
+ "name": "False easting",
+ "value": false_easting,
+ "unit": "metre",
+ "id": {"authority": "EPSG", "code": 8806},
+ },
+ {
+ "name": "False northing",
+ "value": false_northing,
+ "unit": "metre",
+ "id": {"authority": "EPSG", "code": 8807},
+ },
+ ],
+ }
+ return cls.from_json_dict(stere_json)
+
+
+
+
+
+[docs]
+class SinusoidalConversion(CoordinateOperation):
+ """
+ .. versionadded:: 2.5.0
+
+ Class for constructing the Sinusoidal conversion.
+
+ :ref:`PROJ docs <sinu>`
+ """
+
+
+[docs]
+ def __new__(
+ cls,
+ longitude_natural_origin: float = 0.0,
+ false_easting: float = 0.0,
+ false_northing: float = 0.0,
+ ):
+ """
+ Parameters
+ ----------
+ longitude_natural_origin: float, default=0.0
+ Longitude of projection center (lon_0).
+ false_easting: float, default=0.0
+ False easting (x_0).
+ false_northing: float, default=0.0
+ False northing (y_0).
+
+ """
+ sinu_json = {
+ "$schema": "https://proj.org/schemas/v0.2/projjson.schema.json",
+ "type": "Conversion",
+ "name": "unknown",
+ "method": {"name": "Sinusoidal"},
+ "parameters": [
+ {
+ "name": "Longitude of natural origin",
+ "value": longitude_natural_origin,
+ "unit": "degree",
+ "id": {"authority": "EPSG", "code": 8802},
+ },
+ {
+ "name": "False easting",
+ "value": false_easting,
+ "unit": "metre",
+ "id": {"authority": "EPSG", "code": 8806},
+ },
+ {
+ "name": "False northing",
+ "value": false_northing,
+ "unit": "metre",
+ "id": {"authority": "EPSG", "code": 8807},
+ },
+ ],
+ }
+ return cls.from_json_dict(sinu_json)
+
+
+
+
+
+[docs]
+class StereographicConversion(CoordinateOperation):
+ """
+ .. versionadded:: 2.5.0
+
+ Class for constructing the Stereographic conversion.
+
+ :ref:`PROJ docs <stere>`
+ """
+
+
+[docs]
+ def __new__(
+ cls,
+ latitude_natural_origin: float = 0.0,
+ longitude_natural_origin: float = 0.0,
+ false_easting: float = 0.0,
+ false_northing: float = 0.0,
+ scale_factor_natural_origin: float = 1.0,
+ ):
+ """
+ Parameters
+ ----------
+ latitude_natural_origin: float, default=0.0
+ Latitude of natural origin (lat_0).
+ longitude_natural_origin: float, default=0.0
+ Longitude of natural origin (lon_0).
+ false_easting: float, default=0.0
+ False easting (x_0).
+ false_northing: float, default=0.0
+ False northing (y_0).
+ scale_factor_natural_origin: float, default=1.0
+ Scale factor at natural origin (k or k_0).
+
+ """
+
+ stere_json = {
+ "$schema": "https://proj.org/schemas/v0.2/projjson.schema.json",
+ "type": "Conversion",
+ "name": "unknown",
+ "method": {"name": "Stereographic"},
+ "parameters": [
+ {
+ "name": "Latitude of natural origin",
+ "value": latitude_natural_origin,
+ "unit": "degree",
+ "id": {"authority": "EPSG", "code": 8801},
+ },
+ {
+ "name": "Longitude of natural origin",
+ "value": longitude_natural_origin,
+ "unit": "degree",
+ "id": {"authority": "EPSG", "code": 8802},
+ },
+ {
+ "name": "Scale factor at natural origin",
+ "value": scale_factor_natural_origin,
+ "unit": "unity",
+ "id": {"authority": "EPSG", "code": 8805},
+ },
+ {
+ "name": "False easting",
+ "value": false_easting,
+ "unit": "metre",
+ "id": {"authority": "EPSG", "code": 8806},
+ },
+ {
+ "name": "False northing",
+ "value": false_northing,
+ "unit": "metre",
+ "id": {"authority": "EPSG", "code": 8807},
+ },
+ ],
+ }
+ return cls.from_json_dict(stere_json)
+
+
+
+
+
+[docs]
+class UTMConversion(CoordinateOperation):
+ """
+ .. versionadded:: 2.5.0
+
+ Class for constructing the UTM conversion.
+
+ :ref:`PROJ docs <utm>`
+ """
+
+
+[docs]
+ def __new__(cls, zone: str, hemisphere: str = "N"):
+ """
+ Parameters
+ ----------
+ zone: int
+ UTM Zone between 1-60.
+ hemisphere: str, default="N"
+ Either N for North or S for South.
+ """
+ return cls.from_name(f"UTM zone {zone}{hemisphere}")
+
+
+
+
+
+[docs]
+class TransverseMercatorConversion(CoordinateOperation):
+ """
+ .. versionadded:: 2.5.0
+
+ Class for constructing the Transverse Mercator conversion.
+
+ :ref:`PROJ docs <tmerc>`
+ """
+
+
+[docs]
+ def __new__(
+ cls,
+ latitude_natural_origin: float = 0.0,
+ longitude_natural_origin: float = 0.0,
+ false_easting: float = 0.0,
+ false_northing: float = 0.0,
+ scale_factor_natural_origin: float = 1.0,
+ ):
+ """
+ Parameters
+ ----------
+ latitude_natural_origin: float, default=0.0
+ Latitude of projection center (lat_0).
+ longitude_natural_origin: float, default=0.0
+ Longitude of projection center (lon_0).
+ false_easting: float, default=0.0
+ False easting (x_0).
+ false_northing: float, default=0.0
+ False northing (y_0).
+ scale_factor_natural_origin: float, default=1.0
+ Scale factor at natural origin (k or k_0).
+
+ """
+ tmerc_json = {
+ "$schema": "https://proj.org/schemas/v0.2/projjson.schema.json",
+ "type": "Conversion",
+ "name": "unknown",
+ "method": {
+ "name": "Transverse Mercator",
+ "id": {"authority": "EPSG", "code": 9807},
+ },
+ "parameters": [
+ {
+ "name": "Latitude of natural origin",
+ "value": latitude_natural_origin,
+ "unit": "degree",
+ "id": {"authority": "EPSG", "code": 8801},
+ },
+ {
+ "name": "Longitude of natural origin",
+ "value": longitude_natural_origin,
+ "unit": "degree",
+ "id": {"authority": "EPSG", "code": 8802},
+ },
+ {
+ "name": "Scale factor at natural origin",
+ "value": scale_factor_natural_origin,
+ "unit": "unity",
+ "id": {"authority": "EPSG", "code": 8805},
+ },
+ {
+ "name": "False easting",
+ "value": false_easting,
+ "unit": "metre",
+ "id": {"authority": "EPSG", "code": 8806},
+ },
+ {
+ "name": "False northing",
+ "value": false_northing,
+ "unit": "metre",
+ "id": {"authority": "EPSG", "code": 8807},
+ },
+ ],
+ }
+ return cls.from_json_dict(tmerc_json)
+
+
+
+
+
+[docs]
+class VerticalPerspectiveConversion(CoordinateOperation):
+ """
+ .. versionadded:: 2.5.0
+
+ Class for constructing the Vertical Perspective conversion.
+
+ :ref:`PROJ docs <nsper>`
+ """
+
+
+[docs]
+ def __new__(
+ cls,
+ viewpoint_height: float,
+ latitude_topocentric_origin: float = 0.0,
+ longitude_topocentric_origin: float = 0.0,
+ ellipsoidal_height_topocentric_origin: float = 0.0,
+ false_easting: float = 0.0,
+ false_northing: float = 0.0,
+ ):
+ """
+ Parameters
+ ----------
+ viewpoint_height: float
+ Viewpoint height (h).
+ latitude_topocentric_origin: float, default=0.0
+ Latitude of topocentric origin (lat_0).
+ longitude_topocentric_origin: float, default=0.0
+ Longitude of topocentric origin (lon_0).
+ ellipsoidal_height_topocentric_origin: float, default=0.0
+ Ellipsoidal height of topocentric origin.
+ false_easting: float, default=0.0
+ False easting (x_0).
+ false_northing: float, default=0.0
+ False northing (y_0).
+
+ """
+ nsper_json = {
+ "$schema": "https://proj.org/schemas/v0.2/projjson.schema.json",
+ "type": "Conversion",
+ "name": "unknown",
+ "method": {
+ "name": "Vertical Perspective",
+ "id": {"authority": "EPSG", "code": 9838},
+ },
+ "parameters": [
+ {
+ "name": "Latitude of topocentric origin",
+ "value": latitude_topocentric_origin,
+ "unit": "degree",
+ "id": {"authority": "EPSG", "code": 8834},
+ },
+ {
+ "name": "Longitude of topocentric origin",
+ "value": longitude_topocentric_origin,
+ "unit": "degree",
+ "id": {"authority": "EPSG", "code": 8835},
+ },
+ {
+ "name": "Ellipsoidal height of topocentric origin",
+ "value": ellipsoidal_height_topocentric_origin,
+ "unit": "metre",
+ "id": {"authority": "EPSG", "code": 8836},
+ },
+ {
+ "name": "Viewpoint height",
+ "value": viewpoint_height,
+ "unit": "metre",
+ "id": {"authority": "EPSG", "code": 8840},
+ },
+ {
+ "name": "False easting",
+ "value": false_easting,
+ "unit": "metre",
+ "id": {"authority": "EPSG", "code": 8806},
+ },
+ {
+ "name": "False northing",
+ "value": false_northing,
+ "unit": "metre",
+ "id": {"authority": "EPSG", "code": 8807},
+ },
+ ],
+ }
+ return cls.from_json_dict(nsper_json)
+
+
+
+
+
+[docs]
+class RotatedLatitudeLongitudeConversion(CoordinateOperation):
+ """
+ .. versionadded:: 2.5.0
+
+ Class for constructing the Rotated Latitude Longitude conversion.
+
+ :ref:`PROJ docs <ob_tran>`
+ """
+
+
+[docs]
+ def __new__(cls, o_lat_p: float, o_lon_p: float, lon_0: float = 0.0):
+ """
+ Parameters
+ ----------
+ o_lat_p: float
+ Latitude of the North pole of the unrotated source CRS,
+ expressed in the rotated geographic CRS.
+ o_lon_p: float
+ Longitude of the North pole of the unrotated source CRS,
+ expressed in the rotated geographic CRS.
+ lon_0: float, default=0.0
+ Longitude of projection center.
+
+ """
+ rot_latlon_json = {
+ "$schema": "https://proj.org/schemas/v0.2/projjson.schema.json",
+ "type": "Conversion",
+ "name": "unknown",
+ "method": {"name": "PROJ ob_tran o_proj=longlat"},
+ "parameters": [
+ {"name": "o_lat_p", "value": o_lat_p, "unit": "degree"},
+ {"name": "o_lon_p", "value": o_lon_p, "unit": "degree"},
+ {"name": "lon_0", "value": lon_0, "unit": "degree"},
+ ],
+ }
+ return cls.from_json_dict(rot_latlon_json)
+
+
+
+
+
+[docs]
+class PoleRotationNetCDFCFConversion(CoordinateOperation):
+ """
+ .. versionadded:: 3.3.0
+
+ Class for constructing the Pole rotation (netCDF CF convention) conversion.
+
+ http://cfconventions.org/cf-conventions/cf-conventions.html#_rotated_pole
+
+ :ref:`PROJ docs <ob_tran>`
+ """
+
+
+[docs]
+ def __new__(
+ cls,
+ grid_north_pole_latitude: float,
+ grid_north_pole_longitude: float,
+ north_pole_grid_longitude: float = 0.0,
+ ):
+ """
+ Parameters
+ ----------
+ grid_north_pole_latitude: float
+ Latitude of the North pole of the unrotated source CRS,
+ expressed in the rotated geographic CRS (o_lat_p)
+ grid_north_pole_longitude: float
+ Longitude of projection center (lon_0 - 180).
+ north_pole_grid_longitude: float, default=0.0
+ Longitude of the North pole of the unrotated source CRS,
+ expressed in the rotated geographic CRS (o_lon_p).
+ """
+ rot_latlon_json = {
+ "$schema": "https://proj.org/schemas/v0.4/projjson.schema.json",
+ "type": "Conversion",
+ "name": "Pole rotation (netCDF CF convention)",
+ "method": {"name": "Pole rotation (netCDF CF convention)"},
+ "parameters": [
+ {
+ "name": "Grid north pole latitude (netCDF CF convention)",
+ "value": grid_north_pole_latitude,
+ "unit": "degree",
+ },
+ {
+ "name": "Grid north pole longitude (netCDF CF convention)",
+ "value": grid_north_pole_longitude,
+ "unit": "degree",
+ },
+ {
+ "name": "North pole grid longitude (netCDF CF convention)",
+ "value": north_pole_grid_longitude,
+ "unit": "degree",
+ },
+ ],
+ }
+ return cls.from_json_dict(rot_latlon_json)
+
+
+
+
+
+[docs]
+class EquidistantCylindricalConversion(CoordinateOperation):
+ """
+ .. versionadded:: 2.5.0
+
+ Class for constructing the Equidistant Cylintrical (Plate Carrée) conversion.
+
+ :ref:`PROJ docs <eqc>`
+ """
+
+
+[docs]
+ def __new__(
+ cls,
+ latitude_first_parallel: float = 0.0,
+ latitude_natural_origin: float = 0.0,
+ longitude_natural_origin: float = 0.0,
+ false_easting: float = 0.0,
+ false_northing: float = 0.0,
+ ):
+ """
+ Parameters
+ ----------
+ latitude_first_parallel: float, default=0.0
+ Latitude of 1st standard parallel (lat_ts).
+ latitude_natural_origin: float, default=0.0
+ Longitude of projection center (lon_0).
+ longitude_natural_origin: float, default=0.0
+ Longitude of projection center (lon_0).
+ false_easting: float, default=0.0
+ False easting (x_0).
+ false_northing: float, default=0.0
+ False northing (y_0).
+ """
+ eqc_json = {
+ "$schema": "https://proj.org/schemas/v0.2/projjson.schema.json",
+ "type": "Conversion",
+ "name": "unknown",
+ "method": {
+ "name": "Equidistant Cylindrical",
+ "id": {"authority": "EPSG", "code": 1028},
+ },
+ "parameters": [
+ {
+ "name": "Latitude of 1st standard parallel",
+ "value": latitude_first_parallel,
+ "unit": "degree",
+ "id": {"authority": "EPSG", "code": 8823},
+ },
+ {
+ "name": "Latitude of natural origin",
+ "value": latitude_natural_origin,
+ "unit": "degree",
+ "id": {"authority": "EPSG", "code": 8801},
+ },
+ {
+ "name": "Longitude of natural origin",
+ "value": longitude_natural_origin,
+ "unit": "degree",
+ "id": {"authority": "EPSG", "code": 8802},
+ },
+ {
+ "name": "False easting",
+ "value": false_easting,
+ "unit": "metre",
+ "id": {"authority": "EPSG", "code": 8806},
+ },
+ {
+ "name": "False northing",
+ "value": false_northing,
+ "unit": "metre",
+ "id": {"authority": "EPSG", "code": 8807},
+ },
+ ],
+ }
+ return cls.from_json_dict(eqc_json)
+
+
+
+
+# Add an alias for PlateCarree
+PlateCarreeConversion = EquidistantCylindricalConversion
+
+
+
+[docs]
+class ToWGS84Transformation(CoordinateOperation):
+ """
+ .. versionadded:: 2.5.0
+
+ Class for constructing the ToWGS84 Transformation.
+ """
+
+
+[docs]
+ def __new__(
+ cls,
+ source_crs: Any,
+ x_axis_translation: float = 0,
+ y_axis_translation: float = 0,
+ z_axis_translation: float = 0,
+ x_axis_rotation: float = 0,
+ y_axis_rotation: float = 0,
+ z_axis_rotation: float = 0,
+ scale_difference: float = 0,
+ ):
+ """
+ Parameters
+ ----------
+ source_crs: Any
+ Input to create the Source CRS.
+ x_axis_translation: float, default=0.0
+ X-axis translation.
+ y_axis_translation: float, default=0.0
+ Y-axis translation.
+ z_axis_translation: float, default=0.0
+ Z-axis translation.
+ x_axis_rotation: float, default=0.0
+ X-axis rotation.
+ y_axis_rotation: float, default=0.0
+ Y-axis rotation.
+ z_axis_rotation: float, default=0.0
+ Z-axis rotation.
+ scale_difference: float, default=0.0
+ Scale difference.
+ """
+ # pylint: disable=import-outside-toplevel
+ from pyproj.crs import CRS
+
+ towgs84_json = {
+ "$schema": "https://proj.org/schemas/v0.2/projjson.schema.json",
+ "type": "Transformation",
+ "name": "Transformation from unknown to WGS84",
+ "source_crs": CRS.from_user_input(source_crs).to_json_dict(),
+ "target_crs": {
+ "type": "GeographicCRS",
+ "name": "WGS 84",
+ "datum": {
+ "type": "GeodeticReferenceFrame",
+ "name": "World Geodetic System 1984",
+ "ellipsoid": {
+ "name": "WGS 84",
+ "semi_major_axis": 6378137,
+ "inverse_flattening": 298.257223563,
+ },
+ },
+ "coordinate_system": {
+ "subtype": "ellipsoidal",
+ "axis": [
+ {
+ "name": "Latitude",
+ "abbreviation": "lat",
+ "direction": "north",
+ "unit": "degree",
+ },
+ {
+ "name": "Longitude",
+ "abbreviation": "lon",
+ "direction": "east",
+ "unit": "degree",
+ },
+ ],
+ },
+ "id": {"authority": "EPSG", "code": 4326},
+ },
+ "method": {
+ "name": "Position Vector transformation (geog2D domain)",
+ "id": {"authority": "EPSG", "code": 9606},
+ },
+ "parameters": [
+ {
+ "name": "X-axis translation",
+ "value": x_axis_translation,
+ "unit": "metre",
+ "id": {"authority": "EPSG", "code": 8605},
+ },
+ {
+ "name": "Y-axis translation",
+ "value": y_axis_translation,
+ "unit": "metre",
+ "id": {"authority": "EPSG", "code": 8606},
+ },
+ {
+ "name": "Z-axis translation",
+ "value": z_axis_translation,
+ "unit": "metre",
+ "id": {"authority": "EPSG", "code": 8607},
+ },
+ {
+ "name": "X-axis rotation",
+ "value": x_axis_rotation,
+ "unit": {
+ "type": "AngularUnit",
+ "name": "arc-second",
+ "conversion_factor": 4.84813681109536e-06,
+ },
+ "id": {"authority": "EPSG", "code": 8608},
+ },
+ {
+ "name": "Y-axis rotation",
+ "value": y_axis_rotation,
+ "unit": {
+ "type": "AngularUnit",
+ "name": "arc-second",
+ "conversion_factor": 4.84813681109536e-06,
+ },
+ "id": {"authority": "EPSG", "code": 8609},
+ },
+ {
+ "name": "Z-axis rotation",
+ "value": z_axis_rotation,
+ "unit": {
+ "type": "AngularUnit",
+ "name": "arc-second",
+ "conversion_factor": 4.84813681109536e-06,
+ },
+ "id": {"authority": "EPSG", "code": 8610},
+ },
+ {
+ "name": "Scale difference",
+ "value": scale_difference,
+ "unit": {
+ "type": "ScaleUnit",
+ "name": "parts per million",
+ "conversion_factor": 1e-06,
+ },
+ "id": {"authority": "EPSG", "code": 8611},
+ },
+ ],
+ }
+
+ return cls.from_json_dict(towgs84_json)
+
+
+
+"""
+This module is for building coordinate systems to be used when
+building a CRS.
+"""
+
+from pyproj._crs import CoordinateSystem
+from pyproj.crs.enums import (
+ Cartesian2DCSAxis,
+ Ellipsoidal2DCSAxis,
+ Ellipsoidal3DCSAxis,
+ VerticalCSAxis,
+)
+
+# useful constants to use when setting PROJ JSON units
+UNIT_METRE = "metre"
+UNIT_DEGREE = "degree"
+UNIT_FT = {"type": "LinearUnit", "name": "foot", "conversion_factor": 0.3048}
+UNIT_US_FT = {
+ "type": "LinearUnit",
+ "name": "US survey foot",
+ "conversion_factor": 0.304800609601219,
+}
+
+_ELLIPSOIDAL_2D_AXIS_MAP = {
+ Ellipsoidal2DCSAxis.LONGITUDE_LATITUDE: [
+ {
+ "name": "Longitude",
+ "abbreviation": "lon",
+ "direction": "east",
+ "unit": UNIT_DEGREE,
+ },
+ {
+ "name": "Latitude",
+ "abbreviation": "lat",
+ "direction": "north",
+ "unit": UNIT_DEGREE,
+ },
+ ],
+ Ellipsoidal2DCSAxis.LATITUDE_LONGITUDE: [
+ {
+ "name": "Latitude",
+ "abbreviation": "lat",
+ "direction": "north",
+ "unit": UNIT_DEGREE,
+ },
+ {
+ "name": "Longitude",
+ "abbreviation": "lon",
+ "direction": "east",
+ "unit": UNIT_DEGREE,
+ },
+ ],
+}
+
+
+
+[docs]
+class Ellipsoidal2DCS(CoordinateSystem):
+ """
+ .. versionadded:: 2.5.0
+
+ This generates an Ellipsoidal 2D Coordinate System
+ """
+
+
+[docs]
+ def __new__(
+ cls,
+ axis: Ellipsoidal2DCSAxis | str = Ellipsoidal2DCSAxis.LONGITUDE_LATITUDE,
+ ):
+ """
+ Parameters
+ ----------
+ axis: :class:`pyproj.crs.enums.Ellipsoidal2DCSAxis` or str, optional
+ This is the axis order of the coordinate system. Default is
+ :attr:`pyproj.crs.enums.Ellipsoidal2DCSAxis.LONGITUDE_LATITUDE`.
+ """
+ return cls.from_json_dict(
+ {
+ "type": "CoordinateSystem",
+ "subtype": "ellipsoidal",
+ "axis": _ELLIPSOIDAL_2D_AXIS_MAP[Ellipsoidal2DCSAxis.create(axis)],
+ }
+ )
+
+
+
+
+_ELLIPSOIDAL_3D_AXIS_MAP = {
+ Ellipsoidal3DCSAxis.LONGITUDE_LATITUDE_HEIGHT: [
+ {
+ "name": "Longitude",
+ "abbreviation": "lon",
+ "direction": "east",
+ "unit": UNIT_DEGREE,
+ },
+ {
+ "name": "Latitude",
+ "abbreviation": "lat",
+ "direction": "north",
+ "unit": UNIT_DEGREE,
+ },
+ {
+ "name": "Ellipsoidal height",
+ "abbreviation": "h",
+ "direction": "up",
+ "unit": UNIT_METRE,
+ },
+ ],
+ Ellipsoidal3DCSAxis.LATITUDE_LONGITUDE_HEIGHT: [
+ {
+ "name": "Latitude",
+ "abbreviation": "lat",
+ "direction": "north",
+ "unit": UNIT_DEGREE,
+ },
+ {
+ "name": "Longitude",
+ "abbreviation": "lon",
+ "direction": "east",
+ "unit": UNIT_DEGREE,
+ },
+ {
+ "name": "Ellipsoidal height",
+ "abbreviation": "h",
+ "direction": "up",
+ "unit": UNIT_METRE,
+ },
+ ],
+}
+
+
+
+[docs]
+class Ellipsoidal3DCS(CoordinateSystem):
+ """
+ .. versionadded:: 2.5.0
+
+ This generates an Ellipsoidal 3D Coordinate System
+ """
+
+
+[docs]
+ def __new__(
+ cls,
+ axis: Ellipsoidal3DCSAxis | str = Ellipsoidal3DCSAxis.LONGITUDE_LATITUDE_HEIGHT,
+ ):
+ """
+ Parameters
+ ----------
+ axis: :class:`pyproj.crs.enums.Ellipsoidal3DCSAxis` or str, optional
+ This is the axis order of the coordinate system. Default is
+ :attr:`pyproj.crs.enums.Ellipsoidal3DCSAxis.LONGITUDE_LATITUDE_HEIGHT`.
+ """
+ return cls.from_json_dict(
+ {
+ "type": "CoordinateSystem",
+ "subtype": "ellipsoidal",
+ "axis": _ELLIPSOIDAL_3D_AXIS_MAP[Ellipsoidal3DCSAxis.create(axis)],
+ }
+ )
+
+
+
+
+_CARTESIAN_2D_AXIS_MAP = {
+ Cartesian2DCSAxis.EASTING_NORTHING: [
+ {
+ "name": "Easting",
+ "abbreviation": "E",
+ "direction": "east",
+ "unit": UNIT_METRE,
+ },
+ {
+ "name": "Northing",
+ "abbreviation": "N",
+ "direction": "north",
+ "unit": UNIT_METRE,
+ },
+ ],
+ Cartesian2DCSAxis.NORTHING_EASTING: [
+ {
+ "name": "Northing",
+ "abbreviation": "N",
+ "direction": "north",
+ "unit": UNIT_METRE,
+ },
+ {
+ "name": "Easting",
+ "abbreviation": "E",
+ "direction": "east",
+ "unit": UNIT_METRE,
+ },
+ ],
+ Cartesian2DCSAxis.EASTING_NORTHING_FT: [
+ {"name": "Easting", "abbreviation": "X", "direction": "east", "unit": UNIT_FT},
+ {
+ "name": "Northing",
+ "abbreviation": "Y",
+ "direction": "north",
+ "unit": UNIT_FT,
+ },
+ ],
+ Cartesian2DCSAxis.NORTHING_EASTING_FT: [
+ {
+ "name": "Northing",
+ "abbreviation": "Y",
+ "direction": "north",
+ "unit": UNIT_FT,
+ },
+ {"name": "Easting", "abbreviation": "X", "direction": "east", "unit": UNIT_FT},
+ ],
+ Cartesian2DCSAxis.EASTING_NORTHING_US_FT: [
+ {
+ "name": "Easting",
+ "abbreviation": "X",
+ "direction": "east",
+ "unit": UNIT_US_FT,
+ },
+ {
+ "name": "Northing",
+ "abbreviation": "Y",
+ "direction": "north",
+ "unit": UNIT_US_FT,
+ },
+ ],
+ Cartesian2DCSAxis.NORTHING_EASTING_US_FT: [
+ {
+ "name": "Northing",
+ "abbreviation": "Y",
+ "direction": "north",
+ "unit": UNIT_US_FT,
+ },
+ {
+ "name": "Easting",
+ "abbreviation": "X",
+ "direction": "east",
+ "unit": UNIT_US_FT,
+ },
+ ],
+ Cartesian2DCSAxis.NORTH_POLE_EASTING_SOUTH_NORTHING_SOUTH: [
+ {
+ "name": "Easting",
+ "abbreviation": "E",
+ "direction": "south",
+ "unit": UNIT_METRE,
+ },
+ {
+ "name": "Northing",
+ "abbreviation": "N",
+ "direction": "south",
+ "unit": UNIT_METRE,
+ },
+ ],
+ Cartesian2DCSAxis.SOUTH_POLE_EASTING_NORTH_NORTHING_NORTH: [
+ {
+ "name": "Easting",
+ "abbreviation": "E",
+ "direction": "north",
+ "unit": UNIT_METRE,
+ },
+ {
+ "name": "Northing",
+ "abbreviation": "N",
+ "direction": "north",
+ "unit": UNIT_METRE,
+ },
+ ],
+ Cartesian2DCSAxis.WESTING_SOUTHING: [
+ {
+ "name": "Easting",
+ "abbreviation": "Y",
+ "direction": "west",
+ "unit": UNIT_METRE,
+ },
+ {
+ "name": "Northing",
+ "abbreviation": "X",
+ "direction": "south",
+ "unit": UNIT_METRE,
+ },
+ ],
+}
+
+
+
+[docs]
+class Cartesian2DCS(CoordinateSystem):
+ """
+ .. versionadded:: 2.5.0
+
+ This generates an Cartesian 2D Coordinate System
+ """
+
+
+[docs]
+ def __new__(
+ cls, axis: Cartesian2DCSAxis | str = Cartesian2DCSAxis.EASTING_NORTHING
+ ):
+ """
+ Parameters
+ ----------
+ axis: :class:`pyproj.crs.enums.Cartesian2DCSAxis` or str, optional
+ This is the axis order of the coordinate system.
+ Default is :attr:`pyproj.crs.enums.Cartesian2DCSAxis.EASTING_NORTHING`.
+ """
+ return cls.from_json_dict(
+ {
+ "type": "CoordinateSystem",
+ "subtype": "Cartesian",
+ "axis": _CARTESIAN_2D_AXIS_MAP[Cartesian2DCSAxis.create(axis)],
+ }
+ )
+
+
+
+
+_VERTICAL_AXIS_MAP = {
+ VerticalCSAxis.GRAVITY_HEIGHT: {
+ "name": "Gravity-related height",
+ "abbreviation": "H",
+ "direction": "up",
+ "unit": UNIT_METRE,
+ },
+ VerticalCSAxis.GRAVITY_HEIGHT_US_FT: {
+ "name": "Gravity-related height",
+ "abbreviation": "H",
+ "direction": "up",
+ "unit": UNIT_US_FT,
+ },
+ VerticalCSAxis.GRAVITY_HEIGHT_FT: {
+ "name": "Gravity-related height",
+ "abbreviation": "H",
+ "direction": "up",
+ "unit": UNIT_FT,
+ },
+ VerticalCSAxis.DEPTH: {
+ "name": "Depth",
+ "abbreviation": "D",
+ "direction": "down",
+ "unit": UNIT_METRE,
+ },
+ VerticalCSAxis.DEPTH_US_FT: {
+ "name": "Depth",
+ "abbreviation": "D",
+ "direction": "down",
+ "unit": UNIT_US_FT,
+ },
+ VerticalCSAxis.DEPTH_FT: {
+ "name": "Depth",
+ "abbreviation": "D",
+ "direction": "down",
+ "unit": UNIT_FT,
+ },
+ VerticalCSAxis.UP: {
+ "name": "up",
+ "abbreviation": "H",
+ "direction": "up",
+ "unit": UNIT_METRE,
+ },
+ VerticalCSAxis.UP_FT: {
+ "name": "up",
+ "abbreviation": "H",
+ "direction": "up",
+ "unit": UNIT_FT,
+ },
+ VerticalCSAxis.UP_US_FT: {
+ "name": "up",
+ "abbreviation": "H",
+ "direction": "up",
+ "unit": UNIT_US_FT,
+ },
+}
+
+
+
+[docs]
+class VerticalCS(CoordinateSystem):
+ """
+ .. versionadded:: 2.5.0
+
+ This generates an Vertical Coordinate System
+ """
+
+
+[docs]
+ def __new__(cls, axis: VerticalCSAxis | str = VerticalCSAxis.GRAVITY_HEIGHT):
+ """
+ Parameters
+ ----------
+ axis: :class:`pyproj.crs.enums.VerticalCSAxis` or str, optional
+ This is the axis direction of the coordinate system.
+ Default is :attr:`pyproj.crs.enums.VerticalCSAxis.GRAVITY_HEIGHT`.
+ """
+ return cls.from_json_dict(
+ {
+ "type": "CoordinateSystem",
+ "subtype": "vertical",
+ "axis": [_VERTICAL_AXIS_MAP[VerticalCSAxis.create(axis)]],
+ }
+ )
+
+
+
+"""
+This module interfaces with PROJ to produce a pythonic interface
+to the coordinate reference system (CRS) information.
+"""
+
+# pylint: disable=too-many-lines
+import json
+import re
+import threading
+import warnings
+from collections.abc import Callable
+from typing import Any, Optional
+
+from pyproj._crs import (
+ _CRS,
+ AreaOfUse,
+ AuthorityMatchInfo,
+ Axis,
+ CoordinateOperation,
+ CoordinateSystem,
+ Datum,
+ Ellipsoid,
+ PrimeMeridian,
+ _load_proj_json,
+ is_proj,
+ is_wkt,
+)
+from pyproj.crs._cf1x8 import (
+ _GEOGRAPHIC_GRID_MAPPING_NAME_MAP,
+ _GRID_MAPPING_NAME_MAP,
+ _INVERSE_GEOGRAPHIC_GRID_MAPPING_NAME_MAP,
+ _INVERSE_GRID_MAPPING_NAME_MAP,
+ _horizontal_datum_from_params,
+ _try_list_if_string,
+)
+from pyproj.crs.coordinate_operation import ToWGS84Transformation
+from pyproj.crs.coordinate_system import Cartesian2DCS, Ellipsoidal2DCS, VerticalCS
+from pyproj.enums import ProjVersion, WktVersion
+from pyproj.exceptions import CRSError
+from pyproj.geod import Geod
+
+_RE_PROJ_PARAM = re.compile(
+ r"""
+ \+ # parameter starts with '+' character
+ (?P<param>\w+) # capture parameter name
+ \=? # match both key only and key-value parameters
+ (?P<value>\S+)? # capture all characters up to next space (None if no value)
+ \s*? # consume remaining whitespace, if any
+""",
+ re.X,
+)
+
+
+class CRSLocal(threading.local):
+ """
+ Threading local instance for cython CRS class.
+
+ For more details, see:
+ https://github.com/pyproj4/pyproj/issues/782
+ """
+
+ def __init__(self):
+ self.crs = None # Initialises in each thread
+ super().__init__()
+
+
+def _prepare_from_dict(projparams: dict, allow_json: bool = True) -> str:
+ if not isinstance(projparams, dict):
+ raise CRSError("CRS input is not a dict")
+ # check if it is a PROJ JSON dict
+ if "proj" not in projparams and "init" not in projparams and allow_json:
+ return json.dumps(projparams)
+ # convert a dict to a proj string.
+ pjargs = []
+ for key, value in projparams.items():
+ # the towgs84 as list
+ if isinstance(value, (list, tuple)):
+ value = ",".join([str(val) for val in value])
+ # issue 183 (+ no_rot)
+ if value is None or str(value) == "True":
+ pjargs.append(f"+{key}")
+ elif str(value) == "False":
+ pass
+ else:
+ pjargs.append(f"+{key}={value}")
+ return _prepare_from_string(" ".join(pjargs))
+
+
+def _prepare_from_proj_string(in_crs_string: str) -> str:
+ in_crs_string = re.sub(r"[\s+]?=[\s+]?", "=", in_crs_string.lstrip())
+ # make sure the projection starts with +proj or +init
+ starting_params = ("+init", "+proj", "init", "proj")
+ if not in_crs_string.startswith(starting_params):
+ kvpairs: list[str] = []
+ first_item_inserted = False
+ for kvpair in in_crs_string.split():
+ if not first_item_inserted and (kvpair.startswith(starting_params)):
+ kvpairs.insert(0, kvpair)
+ first_item_inserted = True
+ else:
+ kvpairs.append(kvpair)
+ in_crs_string = " ".join(kvpairs)
+
+ # make sure it is the CRS type
+ if "type=crs" not in in_crs_string:
+ if "+" in in_crs_string:
+ in_crs_string += " +type=crs"
+ else:
+ in_crs_string += " type=crs"
+
+ # look for EPSG, replace with epsg (EPSG only works
+ # on case-insensitive filesystems).
+ in_crs_string = in_crs_string.replace("+init=EPSG", "+init=epsg").strip()
+ if in_crs_string.startswith(("+init", "init")):
+ warnings.warn(
+ "'+init=<authority>:<code>' syntax is deprecated. "
+ "'<authority>:<code>' is the preferred initialization method. "
+ "When making the change, be mindful of axis order changes: "
+ "https://pyproj4.github.io/pyproj/stable/gotchas.html"
+ "#axis-order-changes-in-proj-6",
+ FutureWarning,
+ stacklevel=2,
+ )
+ return in_crs_string
+
+
+def _prepare_from_string(in_crs_string: str) -> str:
+ if not isinstance(in_crs_string, str):
+ raise CRSError("CRS input is not a string")
+ if not in_crs_string:
+ raise CRSError(f"CRS string is empty or invalid: {in_crs_string!r}")
+ if "{" in in_crs_string:
+ # may be json, try to decode it
+ try:
+ crs_dict = json.loads(in_crs_string, strict=False)
+ except ValueError as err:
+ raise CRSError("CRS appears to be JSON but is not valid") from err
+
+ if not crs_dict:
+ raise CRSError("CRS is empty JSON")
+ in_crs_string = _prepare_from_dict(crs_dict)
+ elif is_proj(in_crs_string):
+ in_crs_string = _prepare_from_proj_string(in_crs_string)
+ return in_crs_string
+
+
+def _prepare_from_authority(auth_name: str, auth_code: str | int):
+ return f"{auth_name}:{auth_code}"
+
+
+def _prepare_from_epsg(auth_code: str | int):
+ return _prepare_from_authority("EPSG", auth_code)
+
+
+def _is_epsg_code(auth_code: Any) -> bool:
+ if isinstance(auth_code, int):
+ return True
+ if isinstance(auth_code, str) and auth_code.isnumeric():
+ return True
+ if hasattr(auth_code, "shape") and auth_code.shape == ():
+ return True
+ return False
+
+
+
+[docs]
+class CRS:
+ """
+ A pythonic Coordinate Reference System manager.
+
+ .. versionadded:: 2.0.0
+
+ See: :c:func:`proj_create`
+
+ The functionality is based on other fantastic projects:
+
+ * `rasterio <https://github.com/mapbox/rasterio/blob/c13f0943b95c0eaa36ff3f620bd91107aa67b381/rasterio/_crs.pyx>`_ # noqa: E501
+ * `opendatacube <https://github.com/opendatacube/datacube-core/blob/83bae20d2a2469a6417097168fd4ede37fd2abe5/datacube/utils/geometry/_base.py>`_ # noqa: E501
+
+ Attributes
+ ----------
+ srs: str
+ The string form of the user input used to create the CRS.
+
+ """
+
+
+[docs]
+ def __init__(self, projparams: Any | None = None, **kwargs) -> None:
+ """
+ Initialize a CRS class instance with:
+ - PROJ string
+ - Dictionary of PROJ parameters
+ - PROJ keyword arguments for parameters
+ - JSON string with PROJ parameters
+ - CRS WKT string
+ - An authority string [i.e. 'epsg:4326']
+ - An EPSG integer code [i.e. 4326]
+ - A tuple of ("auth_name": "auth_code") [i.e ('epsg', '4326')]
+ - An object with a `to_wkt` method.
+ - A :class:`pyproj.crs.CRS` class
+
+ Example usage:
+
+ >>> from pyproj import CRS
+ >>> crs_utm = CRS.from_user_input(26915)
+ >>> crs_utm
+ <Projected CRS: EPSG:26915>
+ Name: NAD83 / UTM zone 15N
+ Axis Info [cartesian]:
+ - E[east]: Easting (metre)
+ - N[north]: Northing (metre)
+ Area of Use:
+ - name: North America - 96°W to 90°W and NAD83 by country
+ - bounds: (-96.0, 25.61, -90.0, 84.0)
+ Coordinate Operation:
+ - name: UTM zone 15N
+ - method: Transverse Mercator
+ Datum: North American Datum 1983
+ - Ellipsoid: GRS 1980
+ - Prime Meridian: Greenwich
+ <BLANKLINE>
+ >>> crs_utm.area_of_use.bounds
+ (-96.0, 25.61, -90.0, 84.0)
+ >>> crs_utm.ellipsoid
+ ELLIPSOID["GRS 1980",6378137,298.257222101,
+ LENGTHUNIT["metre",1],
+ ID["EPSG",7019]]
+ >>> crs_utm.ellipsoid.inverse_flattening
+ 298.257222101
+ >>> crs_utm.ellipsoid.semi_major_metre
+ 6378137.0
+ >>> crs_utm.ellipsoid.semi_minor_metre
+ 6356752.314140356
+ >>> crs_utm.prime_meridian
+ PRIMEM["Greenwich",0,
+ ANGLEUNIT["degree",0.0174532925199433],
+ ID["EPSG",8901]]
+ >>> crs_utm.prime_meridian.unit_name
+ 'degree'
+ >>> crs_utm.prime_meridian.unit_conversion_factor
+ 0.017453292519943295
+ >>> crs_utm.prime_meridian.longitude
+ 0.0
+ >>> crs_utm.datum
+ DATUM["North American Datum 1983",
+ ELLIPSOID["GRS 1980",6378137,298.257222101,
+ LENGTHUNIT["metre",1]],
+ ID["EPSG",6269]]
+ >>> crs_utm.coordinate_system
+ CS[Cartesian,2],
+ AXIS["(E)",east,
+ ORDER[1],
+ LENGTHUNIT["metre",1,
+ ID["EPSG",9001]]],
+ AXIS["(N)",north,
+ ORDER[2],
+ LENGTHUNIT["metre",1,
+ ID["EPSG",9001]]]
+ >>> print(crs_utm.coordinate_operation.to_wkt(pretty=True))
+ CONVERSION["UTM zone 15N",
+ METHOD["Transverse Mercator",
+ ID["EPSG",9807]],
+ PARAMETER["Latitude of natural origin",0,
+ ANGLEUNIT["degree",0.0174532925199433],
+ ID["EPSG",8801]],
+ PARAMETER["Longitude of natural origin",-93,
+ ANGLEUNIT["degree",0.0174532925199433],
+ ID["EPSG",8802]],
+ PARAMETER["Scale factor at natural origin",0.9996,
+ SCALEUNIT["unity",1],
+ ID["EPSG",8805]],
+ PARAMETER["False easting",500000,
+ LENGTHUNIT["metre",1],
+ ID["EPSG",8806]],
+ PARAMETER["False northing",0,
+ LENGTHUNIT["metre",1],
+ ID["EPSG",8807]],
+ ID["EPSG",16015]]
+ >>> crs = CRS(proj='utm', zone=10, ellps='WGS84')
+ >>> print(crs.to_wkt(pretty=True))
+ PROJCRS["unknown",
+ BASEGEOGCRS["unknown",
+ DATUM["Unknown based on WGS84 ellipsoid",
+ ELLIPSOID["WGS 84",6378137,298.257223563,
+ LENGTHUNIT["metre",1],
+ ID["EPSG",7030]]],
+ PRIMEM["Greenwich",0,
+ ANGLEUNIT["degree",0.0174532925199433],
+ ID["EPSG",8901]]],
+ CONVERSION["UTM zone 10N",
+ METHOD["Transverse Mercator",
+ ID["EPSG",9807]],
+ PARAMETER["Latitude of natural origin",0,
+ ANGLEUNIT["degree",0.0174532925199433],
+ ID["EPSG",8801]],
+ PARAMETER["Longitude of natural origin",-123,
+ ANGLEUNIT["degree",0.0174532925199433],
+ ID["EPSG",8802]],
+ PARAMETER["Scale factor at natural origin",0.9996,
+ SCALEUNIT["unity",1],
+ ID["EPSG",8805]],
+ PARAMETER["False easting",500000,
+ LENGTHUNIT["metre",1],
+ ID["EPSG",8806]],
+ PARAMETER["False northing",0,
+ LENGTHUNIT["metre",1],
+ ID["EPSG",8807]],
+ ID["EPSG",16010]],
+ CS[Cartesian,2],
+ AXIS["(E)",east,
+ ORDER[1],
+ LENGTHUNIT["metre",1,
+ ID["EPSG",9001]]],
+ AXIS["(N)",north,
+ ORDER[2],
+ LENGTHUNIT["metre",1,
+ ID["EPSG",9001]]]]
+ >>> geod = crs.get_geod()
+ >>> f"+a={geod.a:.0f} +f={geod.f:.8f}"
+ '+a=6378137 +f=0.00335281'
+ >>> crs.is_projected
+ True
+ >>> crs.is_geographic
+ False
+ """
+ projstring = ""
+
+ if projparams:
+ if isinstance(projparams, _CRS):
+ projstring = projparams.srs
+ elif _is_epsg_code(projparams):
+ projstring = _prepare_from_epsg(projparams)
+ elif isinstance(projparams, str):
+ projstring = _prepare_from_string(projparams)
+ elif isinstance(projparams, dict):
+ projstring = _prepare_from_dict(projparams)
+ elif isinstance(projparams, (list, tuple)) and len(projparams) == 2:
+ projstring = _prepare_from_authority(*projparams)
+ elif hasattr(projparams, "to_wkt"):
+ projstring = projparams.to_wkt() # type: ignore
+ else:
+ raise CRSError(f"Invalid CRS input: {projparams!r}")
+
+ if kwargs:
+ projkwargs = _prepare_from_dict(kwargs, allow_json=False)
+ projstring = _prepare_from_string(" ".join((projstring, projkwargs)))
+
+ self.srs = projstring
+ self._local = CRSLocal()
+ if isinstance(projparams, _CRS):
+ self._local.crs = projparams
+ else:
+ self._local.crs = _CRS(self.srs)
+
+
+ @property
+ def _crs(self):
+ """
+ Retrieve the Cython based _CRS object for this thread.
+ """
+ if self._local.crs is None:
+ self._local.crs = _CRS(self.srs)
+ return self._local.crs
+
+
+[docs]
+ @classmethod
+ def from_authority(cls, auth_name: str, code: str | int) -> "CRS":
+ """
+ .. versionadded:: 2.2.0
+
+ Make a CRS from an authority name and authority code
+
+ Parameters
+ ----------
+ auth_name: str
+ The name of the authority.
+ code : int or str
+ The code used by the authority.
+
+ Returns
+ -------
+ CRS
+ """
+ return cls.from_user_input(_prepare_from_authority(auth_name, code))
+
+
+
+[docs]
+ @classmethod
+ def from_epsg(cls, code: str | int) -> "CRS":
+ """Make a CRS from an EPSG code
+
+ Parameters
+ ----------
+ code : int or str
+ An EPSG code.
+
+ Returns
+ -------
+ CRS
+ """
+ return cls.from_user_input(_prepare_from_epsg(code))
+
+
+
+[docs]
+ @classmethod
+ def from_proj4(cls, in_proj_string: str) -> "CRS":
+ """
+ .. versionadded:: 2.2.0
+
+ Make a CRS from a PROJ string
+
+ Parameters
+ ----------
+ in_proj_string : str
+ A PROJ string.
+
+ Returns
+ -------
+ CRS
+ """
+ if not is_proj(in_proj_string):
+ raise CRSError(f"Invalid PROJ string: {in_proj_string}")
+ return cls.from_user_input(_prepare_from_proj_string(in_proj_string))
+
+
+
+[docs]
+ @classmethod
+ def from_wkt(cls, in_wkt_string: str) -> "CRS":
+ """
+ .. versionadded:: 2.2.0
+
+ Make a CRS from a WKT string
+
+ Parameters
+ ----------
+ in_wkt_string : str
+ A WKT string.
+
+ Returns
+ -------
+ CRS
+ """
+ if not is_wkt(in_wkt_string):
+ raise CRSError(f"Invalid WKT string: {in_wkt_string}")
+ return cls.from_user_input(_prepare_from_string(in_wkt_string))
+
+
+
+[docs]
+ @classmethod
+ def from_string(cls, in_crs_string: str) -> "CRS":
+ """
+ Make a CRS from:
+
+ Initialize a CRS class instance with:
+ - PROJ string
+ - JSON string with PROJ parameters
+ - CRS WKT string
+ - An authority string [i.e. 'epsg:4326']
+
+ Parameters
+ ----------
+ in_crs_string : str
+ An EPSG, PROJ, or WKT string.
+
+ Returns
+ -------
+ CRS
+ """
+ return cls.from_user_input(_prepare_from_string(in_crs_string))
+
+
+
+[docs]
+ def to_string(self) -> str:
+ """
+ .. versionadded:: 2.2.0
+
+ Convert the CRS to a string.
+
+ It attempts to convert it to the authority string.
+ Otherwise, it uses the string format of the user
+ input to create the CRS.
+
+ Returns
+ -------
+ str
+ """
+ auth_info = self.to_authority(min_confidence=100)
+ if auth_info:
+ return ":".join(auth_info)
+ return self.srs
+
+
+
+[docs]
+ @classmethod
+ def from_user_input(cls, value: Any, **kwargs) -> "CRS":
+ """
+ Initialize a CRS class instance with:
+ - PROJ string
+ - Dictionary of PROJ parameters
+ - PROJ keyword arguments for parameters
+ - JSON string with PROJ parameters
+ - CRS WKT string
+ - An authority string [i.e. 'epsg:4326']
+ - An EPSG integer code [i.e. 4326]
+ - A tuple of ("auth_name": "auth_code") [i.e ('epsg', '4326')]
+ - An object with a `to_wkt` method.
+ - A :class:`pyproj.crs.CRS` class
+
+ Parameters
+ ----------
+ value : obj
+ A Python int, dict, or str.
+
+ Returns
+ -------
+ CRS
+ """
+ if isinstance(value, cls):
+ return value
+ return cls(value, **kwargs)
+
+
+
+[docs]
+ def get_geod(self) -> Geod | None:
+ """
+ Returns
+ -------
+ pyproj.geod.Geod:
+ Geod object based on the ellipsoid.
+ """
+ if self.ellipsoid is None:
+ return None
+ return Geod(
+ a=self.ellipsoid.semi_major_metre,
+ rf=self.ellipsoid.inverse_flattening,
+ b=self.ellipsoid.semi_minor_metre,
+ )
+
+
+
+[docs]
+ @classmethod
+ def from_dict(cls, proj_dict: dict) -> "CRS":
+ """
+ .. versionadded:: 2.2.0
+
+ Make a CRS from a dictionary of PROJ parameters.
+
+ Parameters
+ ----------
+ proj_dict : str
+ PROJ params in dict format.
+
+ Returns
+ -------
+ CRS
+ """
+ return cls.from_user_input(_prepare_from_dict(proj_dict))
+
+
+
+[docs]
+ @classmethod
+ def from_json(cls, crs_json: str) -> "CRS":
+ """
+ .. versionadded:: 2.4.0
+
+ Create CRS from a CRS JSON string.
+
+ Parameters
+ ----------
+ crs_json: str
+ CRS JSON string.
+
+ Returns
+ -------
+ CRS
+ """
+ return cls.from_user_input(_load_proj_json(crs_json))
+
+
+
+[docs]
+ @classmethod
+ def from_json_dict(cls, crs_dict: dict) -> "CRS":
+ """
+ .. versionadded:: 2.4.0
+
+ Create CRS from a JSON dictionary.
+
+ Parameters
+ ----------
+ crs_dict: dict
+ CRS dictionary.
+
+ Returns
+ -------
+ CRS
+ """
+ return cls.from_user_input(json.dumps(crs_dict))
+
+
+
+[docs]
+ def to_dict(self) -> dict:
+ """
+ .. versionadded:: 2.2.0
+
+ Converts the CRS to dictionary of PROJ parameters.
+
+ .. warning:: You will likely lose important projection
+ information when converting to a PROJ string from
+ another format. See: https://proj.org/faq.html#what-is-the-best-format-for-describing-coordinate-reference-systems # noqa: E501
+
+ Returns
+ -------
+ dict:
+ PROJ params in dict format.
+
+ """
+
+ proj_string = self.to_proj4()
+ if proj_string is None:
+ return {}
+
+ def _parse(val):
+ if val.lower() == "true":
+ return True
+ if val.lower() == "false":
+ return False
+ try:
+ return int(val)
+ except ValueError:
+ pass
+ try:
+ return float(val)
+ except ValueError:
+ pass
+ return _try_list_if_string(val)
+
+ proj_dict = {}
+ for param in _RE_PROJ_PARAM.finditer(proj_string):
+ key, value = param.groups()
+ if value is not None:
+ value = _parse(value)
+ if value is not False:
+ proj_dict[key] = value
+
+ return proj_dict
+
+
+
+[docs]
+ def to_cf(
+ self,
+ wkt_version: WktVersion | str = WktVersion.WKT2_2019,
+ errcheck: bool = False,
+ ) -> dict:
+ """
+ .. versionadded:: 2.2.0
+
+ This converts a :obj:`pyproj.crs.CRS` object
+ to a Climate and Forecast (CF) Grid Mapping Version 1.8 dict.
+
+ :ref:`build_crs_cf`
+
+ Parameters
+ ----------
+ wkt_version: str or pyproj.enums.WktVersion
+ Version of WKT supported by CRS.to_wkt.
+ Default is :attr:`pyproj.enums.WktVersion.WKT2_2019`.
+ errcheck: bool, default=False
+ If True, will warn when parameters are ignored.
+
+ Returns
+ -------
+ dict:
+ CF-1.8 version of the projection.
+
+ """
+ # pylint: disable=too-many-branches,too-many-return-statements
+ cf_dict: dict[str, Any] = {"crs_wkt": self.to_wkt(wkt_version)}
+
+ # handle bound CRS
+ if (
+ self.is_bound
+ and self.coordinate_operation
+ and self.coordinate_operation.towgs84
+ and self.source_crs
+ ):
+ sub_cf: dict[str, Any] = self.source_crs.to_cf(
+ wkt_version=wkt_version,
+ errcheck=errcheck,
+ )
+ sub_cf.pop("crs_wkt")
+ cf_dict.update(sub_cf)
+ cf_dict["towgs84"] = self.coordinate_operation.towgs84
+ return cf_dict
+
+ # handle compound CRS
+ if self.is_compound:
+ for sub_crs in self.sub_crs_list:
+ sub_cf = sub_crs.to_cf(wkt_version=wkt_version, errcheck=errcheck)
+ sub_cf.pop("crs_wkt")
+ cf_dict.update(sub_cf)
+ return cf_dict
+
+ # handle vertical CRS
+ if self.is_vertical:
+ vert_json = self.to_json_dict()
+ if "geoid_model" in vert_json:
+ cf_dict["geoid_name"] = vert_json["geoid_model"]["name"]
+ if self.datum:
+ cf_dict["geopotential_datum_name"] = self.datum.name
+ return cf_dict
+
+ # write out datum parameters
+ if self.ellipsoid:
+ cf_dict.update(
+ semi_major_axis=self.ellipsoid.semi_major_metre,
+ semi_minor_axis=self.ellipsoid.semi_minor_metre,
+ inverse_flattening=self.ellipsoid.inverse_flattening,
+ )
+ cf_dict["reference_ellipsoid_name"] = self.ellipsoid.name
+ if self.prime_meridian:
+ cf_dict["longitude_of_prime_meridian"] = self.prime_meridian.longitude
+ cf_dict["prime_meridian_name"] = self.prime_meridian.name
+
+ # handle geographic CRS
+ if self.geodetic_crs:
+ cf_dict["geographic_crs_name"] = self.geodetic_crs.name
+ if self.geodetic_crs.datum:
+ cf_dict["horizontal_datum_name"] = self.geodetic_crs.datum.name
+
+ if self.is_geographic:
+ if self.coordinate_operation:
+ if (
+ self.coordinate_operation.method_name.lower()
+ not in _INVERSE_GEOGRAPHIC_GRID_MAPPING_NAME_MAP
+ ):
+ if errcheck:
+ warnings.warn(
+ "Unsupported coordinate operation: "
+ f"{self.coordinate_operation.method_name}"
+ )
+ return {"crs_wkt": cf_dict["crs_wkt"]}
+ cf_dict.update(
+ _INVERSE_GEOGRAPHIC_GRID_MAPPING_NAME_MAP[
+ self.coordinate_operation.method_name.lower()
+ ](self.coordinate_operation)
+ )
+ else:
+ cf_dict["grid_mapping_name"] = "latitude_longitude"
+ return cf_dict
+
+ # handle projected CRS
+ coordinate_operation = None
+ if not self.is_bound and self.is_projected:
+ coordinate_operation = self.coordinate_operation
+ cf_dict["projected_crs_name"] = self.name
+ coordinate_operation_name = (
+ None
+ if not coordinate_operation
+ else coordinate_operation.method_name.lower().replace(" ", "_")
+ )
+ if coordinate_operation_name not in _INVERSE_GRID_MAPPING_NAME_MAP:
+ if errcheck:
+ if coordinate_operation:
+ warnings.warn(
+ "Unsupported coordinate operation: "
+ f"{coordinate_operation.method_name}"
+ )
+ else:
+ warnings.warn("Coordinate operation not found.")
+
+ return {"crs_wkt": cf_dict["crs_wkt"]}
+
+ cf_dict.update(
+ _INVERSE_GRID_MAPPING_NAME_MAP[coordinate_operation_name](
+ coordinate_operation
+ )
+ )
+ return cf_dict
+
+
+
+[docs]
+ @staticmethod
+ def from_cf(
+ in_cf: dict,
+ ellipsoidal_cs: Any | None = None,
+ cartesian_cs: Any | None = None,
+ vertical_cs: Any | None = None,
+ ) -> "CRS":
+ """
+ .. versionadded:: 2.2.0
+
+ .. versionadded:: 3.0.0 ellipsoidal_cs, cartesian_cs, vertical_cs
+
+ This converts a Climate and Forecast (CF) Grid Mapping Version 1.8
+ dict to a :obj:`pyproj.crs.CRS` object.
+
+ :ref:`build_crs_cf`
+
+ Parameters
+ ----------
+ in_cf: dict
+ CF version of the projection.
+ ellipsoidal_cs: Any, optional
+ Input to create an Ellipsoidal Coordinate System.
+ Anything accepted by :meth:`pyproj.crs.CoordinateSystem.from_user_input`
+ or an Ellipsoidal Coordinate System created from :ref:`coordinate_system`.
+ cartesian_cs: Any, optional
+ Input to create a Cartesian Coordinate System.
+ Anything accepted by :meth:`pyproj.crs.CoordinateSystem.from_user_input`
+ or :class:`pyproj.crs.coordinate_system.Cartesian2DCS`.
+ vertical_cs: Any, optional
+ Input to create a Vertical Coordinate System accepted by
+ :meth:`pyproj.crs.CoordinateSystem.from_user_input`
+ or :class:`pyproj.crs.coordinate_system.VerticalCS`
+
+ Returns
+ -------
+ CRS
+ """
+ # pylint: disable=too-many-branches
+
+ unknown_names = ("unknown", "undefined")
+ if "crs_wkt" in in_cf:
+ return CRS(in_cf["crs_wkt"])
+ if "spatial_ref" in in_cf: # for previous supported WKT key
+ return CRS(in_cf["spatial_ref"])
+
+ grid_mapping_name = in_cf.get("grid_mapping_name")
+ if grid_mapping_name is None:
+ raise CRSError("CF projection parameters missing 'grid_mapping_name'")
+
+ # build datum if possible
+ datum = _horizontal_datum_from_params(in_cf)
+
+ # build geographic CRS
+ try:
+ geographic_conversion_method: None | Callable = (
+ _GEOGRAPHIC_GRID_MAPPING_NAME_MAP[grid_mapping_name]
+ )
+ except KeyError:
+ geographic_conversion_method = None
+
+ geographic_crs_name = in_cf.get("geographic_crs_name")
+ if datum:
+ geographic_crs: CRS = GeographicCRS(
+ name=geographic_crs_name or "undefined",
+ datum=datum,
+ ellipsoidal_cs=ellipsoidal_cs,
+ )
+ elif geographic_crs_name and geographic_crs_name not in unknown_names:
+ geographic_crs = CRS(geographic_crs_name)
+ if ellipsoidal_cs is not None:
+ geographic_crs_json = geographic_crs.to_json_dict()
+ geographic_crs_json["coordinate_system"] = (
+ CoordinateSystem.from_user_input(ellipsoidal_cs).to_json_dict()
+ )
+ geographic_crs = CRS(geographic_crs_json)
+ else:
+ geographic_crs = GeographicCRS(ellipsoidal_cs=ellipsoidal_cs)
+ if grid_mapping_name == "latitude_longitude":
+ return geographic_crs
+ if geographic_conversion_method is not None:
+ return DerivedGeographicCRS(
+ base_crs=geographic_crs,
+ conversion=geographic_conversion_method(in_cf),
+ ellipsoidal_cs=ellipsoidal_cs,
+ )
+
+ # build projected CRS
+ try:
+ conversion_method = _GRID_MAPPING_NAME_MAP[grid_mapping_name]
+ except KeyError:
+ raise CRSError(
+ f"Unsupported grid mapping name: {grid_mapping_name}"
+ ) from None
+ projected_crs = ProjectedCRS(
+ name=in_cf.get("projected_crs_name", "undefined"),
+ conversion=conversion_method(in_cf),
+ geodetic_crs=geographic_crs,
+ cartesian_cs=cartesian_cs,
+ )
+
+ # build bound CRS if exists
+ bound_crs = None
+ if "towgs84" in in_cf:
+ bound_crs = BoundCRS(
+ source_crs=projected_crs,
+ target_crs="WGS 84",
+ transformation=ToWGS84Transformation(
+ projected_crs.geodetic_crs, *_try_list_if_string(in_cf["towgs84"])
+ ),
+ )
+ if "geopotential_datum_name" not in in_cf:
+ return bound_crs or projected_crs
+
+ # build Vertical CRS
+ vertical_crs = VerticalCRS(
+ name="undefined",
+ datum=in_cf["geopotential_datum_name"],
+ geoid_model=in_cf.get("geoid_name"),
+ vertical_cs=vertical_cs,
+ )
+
+ # build compound CRS
+ return CompoundCRS(
+ name="undefined", components=[bound_crs or projected_crs, vertical_crs]
+ )
+
+
+
+[docs]
+ def cs_to_cf(self) -> list[dict]:
+ """
+ .. versionadded:: 3.0.0
+
+ This converts all coordinate systems (cs) in the CRS
+ to a list of Climate and Forecast (CF) Version 1.8 dicts.
+
+ :ref:`build_crs_cf`
+
+ Returns
+ -------
+ list[dict]:
+ CF-1.8 version of the coordinate systems.
+ """
+ cf_axis_list = []
+
+ def rotated_pole(crs):
+ try:
+ return (
+ crs.coordinate_operation
+ and crs.coordinate_operation.method_name.lower()
+ in _INVERSE_GEOGRAPHIC_GRID_MAPPING_NAME_MAP
+ )
+ except KeyError:
+ return False
+
+ if self.type_name == "Temporal CRS" and self.datum:
+ datum_json = self.datum.to_json_dict()
+ origin = datum_json.get("time_origin", "1875-05-20").strip().rstrip("zZ")
+ if len(origin) == 4:
+ origin = f"{origin}-01-01"
+ axis = self.axis_info[0]
+ cf_temporal_axis = {
+ "standard_name": "time",
+ "long_name": "time",
+ "calendar": (
+ datum_json.get("calendar", "proleptic_gregorian")
+ .lower()
+ .replace(" ", "_")
+ ),
+ "axis": "T",
+ }
+ unit_name = axis.unit_name.lower().replace("calendar", "").strip()
+ # no units for TemporalDateTime
+ if unit_name:
+ cf_temporal_axis["units"] = f"{unit_name} since {origin}"
+ cf_axis_list.append(cf_temporal_axis)
+ if self.coordinate_system:
+ cf_axis_list.extend(
+ self.coordinate_system.to_cf(rotated_pole=rotated_pole(self))
+ )
+ elif self.is_bound and self.source_crs and self.source_crs.coordinate_system:
+ cf_axis_list.extend(
+ self.source_crs.coordinate_system.to_cf(
+ rotated_pole=rotated_pole(self.source_crs)
+ )
+ )
+ else:
+ for sub_crs in self.sub_crs_list:
+ cf_axis_list.extend(sub_crs.cs_to_cf())
+ return cf_axis_list
+
+
+
+[docs]
+ def is_exact_same(self, other: Any) -> bool:
+ """
+ Check if the CRS objects are the exact same.
+
+ Parameters
+ ----------
+ other: Any
+ Check if the other CRS is the exact same to this object.
+ If the other object is not a CRS, it will try to create one.
+ On Failure, it will return False.
+
+ Returns
+ -------
+ bool
+ """
+ try:
+ other = CRS.from_user_input(other)
+ except CRSError:
+ return False
+ return self._crs.is_exact_same(other._crs)
+
+
+
+[docs]
+ def equals(self, other: Any, ignore_axis_order: bool = False) -> bool:
+ """
+
+ .. versionadded:: 2.5.0
+
+ Check if the CRS objects are equivalent.
+
+ Parameters
+ ----------
+ other: Any
+ Check if the other object is equivalent to this object.
+ If the other object is not a CRS, it will try to create one.
+ On Failure, it will return False.
+ ignore_axis_order: bool, default=False
+ If True, it will compare the CRS class and ignore the axis order.
+
+ Returns
+ -------
+ bool
+ """
+ try:
+ other = CRS.from_user_input(other)
+ except CRSError:
+ return False
+ return self._crs.equals(other._crs, ignore_axis_order=ignore_axis_order)
+
+
+ @property
+ def geodetic_crs(self) -> Optional["CRS"]:
+ """
+ .. versionadded:: 2.2.0
+
+ Returns
+ -------
+ CRS:
+ The geodeticCRS / geographicCRS from the CRS.
+
+ """
+ return (
+ None
+ if self._crs.geodetic_crs is None
+ else self.__class__(self._crs.geodetic_crs)
+ )
+
+ @property
+ def source_crs(self) -> Optional["CRS"]:
+ """
+ The base CRS of a BoundCRS or a DerivedCRS/ProjectedCRS,
+ or the source CRS of a CoordinateOperation.
+
+ Returns
+ -------
+ CRS
+ """
+ return (
+ None
+ if self._crs.source_crs is None
+ else self.__class__(self._crs.source_crs)
+ )
+
+ @property
+ def target_crs(self) -> Optional["CRS"]:
+ """
+ .. versionadded:: 2.2.0
+
+ Returns
+ -------
+ CRS:
+ The hub CRS of a BoundCRS or the target CRS of a CoordinateOperation.
+
+ """
+ return (
+ None
+ if self._crs.target_crs is None
+ else self.__class__(self._crs.target_crs)
+ )
+
+ @property
+ def sub_crs_list(self) -> list["CRS"]:
+ """
+ If the CRS is a compound CRS, it will return a list of sub CRS objects.
+
+ Returns
+ -------
+ list[CRS]
+ """
+ return [self.__class__(sub_crs) for sub_crs in self._crs.sub_crs_list]
+
+ @property
+ def utm_zone(self) -> str | None:
+ """
+ .. versionadded:: 2.6.0
+
+ Finds the UTM zone in a Projected CRS, Bound CRS, or Compound CRS
+
+ Returns
+ -------
+ str | None:
+ The UTM zone number and letter if applicable.
+ """
+ if self.is_bound and self.source_crs:
+ return self.source_crs.utm_zone
+ if self.sub_crs_list:
+ for sub_crs in self.sub_crs_list:
+ if sub_crs.utm_zone:
+ return sub_crs.utm_zone
+ elif (
+ self.coordinate_operation
+ and "UTM ZONE" in self.coordinate_operation.name.upper()
+ ):
+ return self.coordinate_operation.name.upper().split("UTM ZONE ")[-1]
+ return None
+
+ @property
+ def name(self) -> str:
+ """
+ Returns
+ -------
+ str:
+ The name of the CRS (from :cpp:func:`proj_get_name`).
+ """
+ return self._crs.name
+
+ @property
+ def type_name(self) -> str:
+ """
+ Returns
+ -------
+ str:
+ The name of the type of the CRS object.
+ """
+ return self._crs.type_name
+
+ @property
+ def axis_info(self) -> list[Axis]:
+ """
+ Retrieves all relevant axis information in the CRS.
+ If it is a Bound CRS, it gets the axis list from the Source CRS.
+ If it is a Compound CRS, it gets the axis list from the Sub CRS list.
+
+ Returns
+ -------
+ list[Axis]:
+ The list of axis information.
+ """
+ return self._crs.axis_info
+
+ @property
+ def area_of_use(self) -> AreaOfUse | None:
+ """
+ Returns
+ -------
+ AreaOfUse:
+ The area of use object with associated attributes.
+ """
+ return self._crs.area_of_use
+
+ @property
+ def ellipsoid(self) -> Ellipsoid | None:
+ """
+ .. versionadded:: 2.2.0
+
+ Returns
+ -------
+ Ellipsoid:
+ The ellipsoid object with associated attributes.
+ """
+ return self._crs.ellipsoid
+
+ @property
+ def prime_meridian(self) -> PrimeMeridian | None:
+ """
+ .. versionadded:: 2.2.0
+
+ Returns
+ -------
+ PrimeMeridian:
+ The prime meridian object with associated attributes.
+ """
+ return self._crs.prime_meridian
+
+ @property
+ def datum(self) -> Datum | None:
+ """
+ .. versionadded:: 2.2.0
+
+ Returns
+ -------
+ Datum
+ """
+ return self._crs.datum
+
+ @property
+ def coordinate_system(self) -> CoordinateSystem | None:
+ """
+ .. versionadded:: 2.2.0
+
+ Returns
+ -------
+ CoordinateSystem
+ """
+ return self._crs.coordinate_system
+
+ @property
+ def coordinate_operation(self) -> CoordinateOperation | None:
+ """
+ .. versionadded:: 2.2.0
+
+ Returns
+ -------
+ CoordinateOperation
+ """
+ return self._crs.coordinate_operation
+
+ @property
+ def remarks(self) -> str:
+ """
+ .. versionadded:: 2.4.0
+
+ Returns
+ -------
+ str:
+ Remarks about object.
+ """
+ return self._crs.remarks
+
+ @property
+ def scope(self) -> str:
+ """
+ .. versionadded:: 2.4.0
+
+ Returns
+ -------
+ str:
+ Scope of object.
+ """
+ return self._crs.scope
+
+
+[docs]
+ def to_wkt(
+ self,
+ version: WktVersion | str = WktVersion.WKT2_2019,
+ pretty: bool = False,
+ output_axis_rule: bool | None = None,
+ ) -> str:
+ """
+ Convert the projection to a WKT string.
+
+ Version options:
+ - WKT2_2015
+ - WKT2_2015_SIMPLIFIED
+ - WKT2_2019
+ - WKT2_2019_SIMPLIFIED
+ - WKT1_GDAL
+ - WKT1_ESRI
+
+ .. versionadded:: 3.6.0 output_axis_rule
+
+ Parameters
+ ----------
+ version: pyproj.enums.WktVersion, optional
+ The version of the WKT output.
+ Default is :attr:`pyproj.enums.WktVersion.WKT2_2019`.
+ pretty: bool, default=False
+ If True, it will set the output to be a multiline string.
+ output_axis_rule: bool, optional, default=None
+ If True, it will set the axis rule on any case. If false, never.
+ None for AUTO, that depends on the CRS and version.
+
+ Returns
+ -------
+ str
+ """
+ wkt = self._crs.to_wkt(
+ version=version, pretty=pretty, output_axis_rule=output_axis_rule
+ )
+ if wkt is None:
+ raise CRSError(
+ f"CRS cannot be converted to a WKT string of a '{version}' version. "
+ "Select a different version of a WKT string or edit your CRS."
+ )
+ return wkt
+
+
+
+[docs]
+ def to_json(self, pretty: bool = False, indentation: int = 2) -> str:
+ """
+ .. versionadded:: 2.4.0
+
+ Convert the object to a JSON string.
+
+ Parameters
+ ----------
+ pretty: bool, default=False
+ If True, it will set the output to be a multiline string.
+ indentation: int, default=2
+ If pretty is True, it will set the width of the indentation.
+
+ Returns
+ -------
+ str
+ """
+ proj_json = self._crs.to_json(pretty=pretty, indentation=indentation)
+ if proj_json is None:
+ raise CRSError("CRS cannot be converted to a PROJ JSON string.")
+ return proj_json
+
+
+
+[docs]
+ def to_json_dict(self) -> dict:
+ """
+ .. versionadded:: 2.4.0
+
+ Convert the object to a JSON dictionary.
+
+ Returns
+ -------
+ dict
+ """
+ return self._crs.to_json_dict()
+
+
+
+[docs]
+ def to_proj4(self, version: ProjVersion | int = ProjVersion.PROJ_5) -> str:
+ """
+ Convert the projection to a PROJ string.
+
+ .. warning:: You will likely lose important projection
+ information when converting to a PROJ string from
+ another format. See:
+ https://proj.org/faq.html#what-is-the-best-format-for-describing-coordinate-reference-systems # noqa: E501
+
+ Parameters
+ ----------
+ version: pyproj.enums.ProjVersion
+ The version of the PROJ string output.
+ Default is :attr:`pyproj.enums.ProjVersion.PROJ_4`.
+
+ Returns
+ -------
+ str
+ """
+ proj = self._crs.to_proj4(version=version)
+ if proj is None:
+ raise CRSError("CRS cannot be converted to a PROJ string.")
+ return proj
+
+
+
+[docs]
+ def to_epsg(self, min_confidence: int = 70) -> int | None:
+ """
+ Return the EPSG code best matching the CRS
+ or None if it a match is not found.
+
+ Example:
+
+ >>> from pyproj import CRS
+ >>> ccs = CRS("EPSG:4328")
+ >>> ccs.to_epsg()
+ 4328
+
+ If the CRS is bound, you can attempt to get an epsg code from
+ the source CRS:
+
+ >>> from pyproj import CRS
+ >>> ccs = CRS("+proj=geocent +datum=WGS84 +towgs84=0,0,0")
+ >>> ccs.to_epsg()
+ >>> ccs.source_crs.to_epsg()
+ 4978
+ >>> ccs == CRS.from_epsg(4978)
+ False
+
+ Parameters
+ ----------
+ min_confidence: int, default=70
+ A value between 0-100 where 100 is the most confident.
+ :ref:`min_confidence`
+
+
+ Returns
+ -------
+ int | None:
+ The best matching EPSG code matching the confidence level.
+ """
+ return self._crs.to_epsg(min_confidence=min_confidence)
+
+
+
+[docs]
+ def to_authority(self, auth_name: str | None = None, min_confidence: int = 70):
+ """
+ .. versionadded:: 2.2.0
+
+ Return the authority name and code best matching the CRS
+ or None if it a match is not found.
+
+ Example:
+
+ >>> from pyproj import CRS
+ >>> ccs = CRS("EPSG:4328")
+ >>> ccs.to_authority()
+ ('EPSG', '4328')
+
+ If the CRS is bound, you can get an authority from
+ the source CRS:
+
+ >>> from pyproj import CRS
+ >>> ccs = CRS("+proj=geocent +datum=WGS84 +towgs84=0,0,0")
+ >>> ccs.to_authority()
+ >>> ccs.source_crs.to_authority()
+ ('EPSG', '4978')
+ >>> ccs == CRS.from_authorty('EPSG', '4978')
+ False
+
+ Parameters
+ ----------
+ auth_name: str, optional
+ The name of the authority to filter by.
+ min_confidence: int, default=70
+ A value between 0-100 where 100 is the most confident.
+ :ref:`min_confidence`
+
+ Returns
+ -------
+ tuple(str, str) or None:
+ The best matching (<auth_name>, <code>) for the confidence level.
+ """
+ return self._crs.to_authority(
+ auth_name=auth_name, min_confidence=min_confidence
+ )
+
+
+
+[docs]
+ def list_authority(
+ self, auth_name: str | None = None, min_confidence: int = 70
+ ) -> list[AuthorityMatchInfo]:
+ """
+ .. versionadded:: 3.2.0
+
+ Return the authority names and codes best matching the CRS.
+
+ Example:
+
+ >>> from pyproj import CRS
+ >>> ccs = CRS("EPSG:4328")
+ >>> ccs.list_authority()
+ [AuthorityMatchInfo(auth_name='EPSG', code='4326', confidence=100)]
+
+ If the CRS is bound, you can get an authority from
+ the source CRS:
+
+ >>> from pyproj import CRS
+ >>> ccs = CRS("+proj=geocent +datum=WGS84 +towgs84=0,0,0")
+ >>> ccs.list_authority()
+ []
+ >>> ccs.source_crs.list_authority()
+ [AuthorityMatchInfo(auth_name='EPSG', code='4978', confidence=70)]
+ >>> ccs == CRS.from_authorty('EPSG', '4978')
+ False
+
+ Parameters
+ ----------
+ auth_name: str, optional
+ The name of the authority to filter by.
+ min_confidence: int, default=70
+ A value between 0-100 where 100 is the most confident.
+ :ref:`min_confidence`
+
+ Returns
+ -------
+ list[AuthorityMatchInfo]:
+ List of authority matches for the CRS.
+ """
+ return self._crs.list_authority(
+ auth_name=auth_name, min_confidence=min_confidence
+ )
+
+
+
+[docs]
+ def to_3d(self, name: str | None = None) -> "CRS":
+ """
+ .. versionadded:: 3.1.0
+
+ Convert the current CRS to the 3D version if it makes sense.
+
+ New vertical axis attributes:
+ - ellipsoidal height
+ - oriented upwards
+ - metre units
+
+ Parameters
+ ----------
+ name: str, optional
+ CRS name. Defaults to use the name of the original CRS.
+
+ Returns
+ -------
+ CRS
+ """
+ return self.__class__(self._crs.to_3d(name=name))
+
+
+
+[docs]
+ def to_2d(self, name: str | None = None) -> "CRS":
+ """
+ .. versionadded:: 3.6.0
+
+ Convert the current CRS to the 2D version if it makes sense.
+
+ Parameters
+ ----------
+ name: str, optional
+ CRS name. Defaults to use the name of the original CRS.
+
+ Returns
+ -------
+ CRS
+ """
+ return self.__class__(self._crs.to_2d(name=name))
+
+
+ @property
+ def is_geographic(self) -> bool:
+ """
+ This checks if the CRS is geographic.
+ It will check if it has a geographic CRS
+ in the sub CRS if it is a compound CRS and will check if
+ the source CRS is geographic if it is a bound CRS.
+
+ Returns
+ -------
+ bool:
+ True if the CRS is in geographic (lon/lat) coordinates.
+ """
+ return self._crs.is_geographic
+
+ @property
+ def is_projected(self) -> bool:
+ """
+ This checks if the CRS is projected.
+ It will check if it has a projected CRS
+ in the sub CRS if it is a compound CRS and will check if
+ the source CRS is projected if it is a bound CRS.
+
+ Returns
+ -------
+ bool:
+ True if CRS is projected.
+ """
+ return self._crs.is_projected
+
+ @property
+ def is_vertical(self) -> bool:
+ """
+ .. versionadded:: 2.2.0
+
+ This checks if the CRS is vertical.
+ It will check if it has a vertical CRS
+ in the sub CRS if it is a compound CRS and will check if
+ the source CRS is vertical if it is a bound CRS.
+
+ Returns
+ -------
+ bool:
+ True if CRS is vertical.
+ """
+ return self._crs.is_vertical
+
+ @property
+ def is_bound(self) -> bool:
+ """
+ Returns
+ -------
+ bool:
+ True if CRS is bound.
+ """
+ return self._crs.is_bound
+
+ @property
+ def is_compound(self) -> bool:
+ """
+ .. versionadded:: 3.1.0
+
+ Returns
+ -------
+ bool:
+ True if CRS is compound.
+ """
+ return self._crs.is_compound
+
+ @property
+ def is_engineering(self) -> bool:
+ """
+ .. versionadded:: 2.2.0
+
+ Returns
+ -------
+ bool:
+ True if CRS is local/engineering.
+ """
+ return self._crs.is_engineering
+
+ @property
+ def is_geocentric(self) -> bool:
+ """
+ This checks if the CRS is geocentric and
+ takes into account if the CRS is bound.
+
+ Returns
+ -------
+ bool:
+ True if CRS is in geocentric (x/y) coordinates.
+ """
+ return self._crs.is_geocentric
+
+ @property
+ def is_derived(self):
+ """
+ .. versionadded:: 3.2.0
+
+ Returns
+ -------
+ bool:
+ True if CRS is a Derived CRS.
+ """
+ return self._crs.is_derived
+
+ @property
+ def is_deprecated(self) -> bool:
+ """
+ .. versionadded:: 3.7.0
+
+ Check if the CRS is deprecated
+
+ Returns
+ -------
+ bool
+ """
+ return self._crs.is_deprecated
+
+
+[docs]
+ def get_non_deprecated(self) -> list["CRS"]:
+ """
+ .. versionadded:: 3.7.0
+
+ Return a list of non-deprecated objects related to this.
+
+ Returns
+ -------
+ list[CRS]
+ """
+ return self._crs.get_non_deprecated()
+
+
+ def __eq__(self, other: Any) -> bool:
+ return self.equals(other)
+
+ def __getstate__(self) -> dict[str, str]:
+ return {"srs": self.srs}
+
+ def __setstate__(self, state: dict[str, Any]):
+ self.__dict__.update(state)
+ self._local = CRSLocal()
+
+ def __hash__(self) -> int:
+ return hash(self.to_wkt())
+
+ def __str__(self) -> str:
+ return self.srs
+
+ def __repr__(self) -> str:
+ # get axis information
+ axis_info_list: list[str] = []
+ for axis in self.axis_info:
+ axis_info_list.extend(["- ", str(axis), "\n"])
+ axis_info_str = "".join(axis_info_list)
+
+ # get coordinate system & sub CRS info
+ source_crs_repr = ""
+ sub_crs_repr = ""
+ if self.coordinate_system and self.coordinate_system.axis_list:
+ coordinate_system_name = str(self.coordinate_system)
+ elif self.is_bound and self.source_crs:
+ coordinate_system_name = str(self.source_crs.coordinate_system)
+ source_crs_repr = f"Source CRS: {self.source_crs.name}\n"
+ else:
+ coordinate_system_names = []
+ sub_crs_repr_list = ["Sub CRS:\n"]
+ for sub_crs in self.sub_crs_list:
+ coordinate_system_names.append(str(sub_crs.coordinate_system))
+ sub_crs_repr_list.extend(["- ", sub_crs.name, "\n"])
+ coordinate_system_name = "|".join(coordinate_system_names)
+ sub_crs_repr = "".join(sub_crs_repr_list)
+
+ # get coordinate operation repr
+ coordinate_operation = ""
+ if self.coordinate_operation:
+ coordinate_operation = "".join(
+ [
+ "Coordinate Operation:\n",
+ "- name: ",
+ str(self.coordinate_operation),
+ "\n- method: ",
+ self.coordinate_operation.method_name,
+ "\n",
+ ]
+ )
+
+ # get SRS representation
+ srs_repr = self.to_string()
+ srs_repr = srs_repr if len(srs_repr) <= 50 else " ".join([srs_repr[:50], "..."])
+ axis_info_str = axis_info_str or "- undefined\n"
+ return (
+ f"<{self.type_name}: {srs_repr}>\n"
+ f"Name: {self.name}\n"
+ f"Axis Info [{coordinate_system_name or 'undefined'}]:\n"
+ f"{axis_info_str}"
+ "Area of Use:\n"
+ f"{self.area_of_use or '- undefined'}\n"
+ f"{coordinate_operation}"
+ f"Datum: {self.datum}\n"
+ f"- Ellipsoid: {self.ellipsoid or 'undefined'}\n"
+ f"- Prime Meridian: {self.prime_meridian or 'undefined'}\n"
+ f"{source_crs_repr}"
+ f"{sub_crs_repr}"
+ )
+
+
+
+
+[docs]
+class CustomConstructorCRS(CRS):
+ """
+ This class is a base class for CRS classes
+ that use a different constructor than the main CRS class.
+
+ .. versionadded:: 3.2.0
+
+ See: https://github.com/pyproj4/pyproj/issues/847
+ """
+
+ @property
+ def _expected_types(self) -> tuple[str, ...]:
+ """
+ These are the type names of the CRS class
+ that are expected when using the from_* methods.
+ """
+ raise NotImplementedError
+
+ def _check_type(self):
+ """
+ This validates that the type of the CRS is expected
+ when using the from_* methods.
+ """
+ if self.type_name not in self._expected_types:
+ raise CRSError(
+ f"Invalid type {self.type_name}. Expected {self._expected_types}."
+ )
+
+
+[docs]
+ @classmethod
+ def from_user_input(cls, value: Any, **kwargs) -> "CRS":
+ """
+ Initialize a CRS class instance with:
+ - PROJ string
+ - Dictionary of PROJ parameters
+ - PROJ keyword arguments for parameters
+ - JSON string with PROJ parameters
+ - CRS WKT string
+ - An authority string [i.e. 'epsg:4326']
+ - An EPSG integer code [i.e. 4326]
+ - A tuple of ("auth_name": "auth_code") [i.e ('epsg', '4326')]
+ - An object with a `to_wkt` method.
+ - A :class:`pyproj.crs.CRS` class
+
+ Parameters
+ ----------
+ value : obj
+ A Python int, dict, or str.
+
+ Returns
+ -------
+ CRS
+ """
+ if isinstance(value, cls):
+ return value
+ crs = cls.__new__(cls)
+ super(CustomConstructorCRS, crs).__init__(value, **kwargs)
+ crs._check_type()
+ return crs
+
+
+ @property
+ def geodetic_crs(self) -> Optional["CRS"]:
+ """
+ .. versionadded:: 2.2.0
+
+ Returns
+ -------
+ CRS:
+ The geodeticCRS / geographicCRS from the CRS.
+
+ """
+ return None if self._crs.geodetic_crs is None else CRS(self._crs.geodetic_crs)
+
+ @property
+ def source_crs(self) -> Optional["CRS"]:
+ """
+ The base CRS of a BoundCRS or a DerivedCRS/ProjectedCRS,
+ or the source CRS of a CoordinateOperation.
+
+ Returns
+ -------
+ CRS
+ """
+ return None if self._crs.source_crs is None else CRS(self._crs.source_crs)
+
+ @property
+ def target_crs(self) -> Optional["CRS"]:
+ """
+ .. versionadded:: 2.2.0
+
+ Returns
+ -------
+ CRS:
+ The hub CRS of a BoundCRS or the target CRS of a CoordinateOperation.
+
+ """
+ return None if self._crs.target_crs is None else CRS(self._crs.target_crs)
+
+ @property
+ def sub_crs_list(self) -> list["CRS"]:
+ """
+ If the CRS is a compound CRS, it will return a list of sub CRS objects.
+
+ Returns
+ -------
+ list[CRS]
+ """
+ return [CRS(sub_crs) for sub_crs in self._crs.sub_crs_list]
+
+
+[docs]
+ def to_3d(self, name: str | None = None) -> "CRS":
+ """
+ .. versionadded:: 3.1.0
+
+ Convert the current CRS to the 3D version if it makes sense.
+
+ New vertical axis attributes:
+ - ellipsoidal height
+ - oriented upwards
+ - metre units
+
+ Parameters
+ ----------
+ name: str, optional
+ CRS name. Defaults to use the name of the original CRS.
+
+ Returns
+ -------
+ CRS
+ """
+ return CRS(self._crs.to_3d(name=name))
+
+
+
+
+
+[docs]
+class GeographicCRS(CustomConstructorCRS):
+ """
+ .. versionadded:: 2.5.0
+
+ This class is for building a Geographic CRS
+ """
+
+ _expected_types = ("Geographic CRS", "Geographic 2D CRS", "Geographic 3D CRS")
+
+
+[docs]
+ def __init__(
+ self,
+ name: str = "undefined",
+ datum: Any = "urn:ogc:def:ensemble:EPSG::6326",
+ ellipsoidal_cs: Any | None = None,
+ ) -> None:
+ """
+ Parameters
+ ----------
+ name: str, default="undefined"
+ Name of the CRS.
+ datum: Any, default="urn:ogc:def:ensemble:EPSG::6326"
+ Anything accepted by :meth:`pyproj.crs.Datum.from_user_input` or
+ a :class:`pyproj.crs.datum.CustomDatum`.
+ ellipsoidal_cs: Any, optional
+ Input to create an Ellipsoidal Coordinate System.
+ Anything accepted by :meth:`pyproj.crs.CoordinateSystem.from_user_input`
+ or an Ellipsoidal Coordinate System created from :ref:`coordinate_system`.
+ """
+ datum = Datum.from_user_input(datum).to_json_dict()
+ geographic_crs_json = {
+ "$schema": "https://proj.org/schemas/v0.2/projjson.schema.json",
+ "type": "GeographicCRS",
+ "name": name,
+ "coordinate_system": CoordinateSystem.from_user_input(
+ ellipsoidal_cs or Ellipsoidal2DCS()
+ ).to_json_dict(),
+ }
+ if datum["type"] == "DatumEnsemble":
+ geographic_crs_json["datum_ensemble"] = datum
+ else:
+ geographic_crs_json["datum"] = datum
+ super().__init__(geographic_crs_json)
+
+
+
+
+
+[docs]
+class DerivedGeographicCRS(CustomConstructorCRS):
+ """
+ .. versionadded:: 2.5.0
+
+ This class is for building a Derived Geographic CRS
+ """
+
+ _expected_types = (
+ "Derived Geographic CRS",
+ "Derived Geographic 2D CRS",
+ "Derived Geographic 3D CRS",
+ )
+
+
+[docs]
+ def __init__(
+ self,
+ base_crs: Any,
+ conversion: Any,
+ ellipsoidal_cs: Any | None = None,
+ name: str = "undefined",
+ ) -> None:
+ """
+ Parameters
+ ----------
+ base_crs: Any
+ Input to create the Geodetic CRS, a :class:`GeographicCRS` or
+ anything accepted by :meth:`pyproj.crs.CRS.from_user_input`.
+ conversion: Any
+ Anything accepted by :meth:`pyproj.crs.CoordinateSystem.from_user_input`
+ or a conversion from :ref:`coordinate_operation`.
+ ellipsoidal_cs: Any, optional
+ Input to create an Ellipsoidal Coordinate System.
+ Anything accepted by :meth:`pyproj.crs.CoordinateSystem.from_user_input`
+ or an Ellipsoidal Coordinate System created from :ref:`coordinate_system`.
+ name: str, default="undefined"
+ Name of the CRS.
+ """
+ derived_geographic_crs_json = {
+ "$schema": "https://proj.org/schemas/v0.2/projjson.schema.json",
+ "type": "DerivedGeographicCRS",
+ "name": name,
+ "base_crs": CRS.from_user_input(base_crs).to_json_dict(),
+ "conversion": CoordinateOperation.from_user_input(
+ conversion
+ ).to_json_dict(),
+ "coordinate_system": CoordinateSystem.from_user_input(
+ ellipsoidal_cs or Ellipsoidal2DCS()
+ ).to_json_dict(),
+ }
+ super().__init__(derived_geographic_crs_json)
+
+
+
+
+
+[docs]
+class GeocentricCRS(CustomConstructorCRS):
+ """
+ .. versionadded:: 3.2.0
+
+ This class is for building a Geocentric CRS
+ """
+
+ _expected_types = ("Geocentric CRS",)
+
+
+[docs]
+ def __init__(
+ self,
+ name: str = "undefined",
+ datum: Any = "urn:ogc:def:datum:EPSG::6326",
+ ) -> None:
+ """
+ Parameters
+ ----------
+ name: str, default="undefined"
+ Name of the CRS.
+ datum: Any, default="urn:ogc:def:datum:EPSG::6326"
+ Anything accepted by :meth:`pyproj.crs.Datum.from_user_input` or
+ a :class:`pyproj.crs.datum.CustomDatum`.
+ """
+ geocentric_crs_json = {
+ "$schema": ("https://proj.org/schemas/v0.2/projjson.schema.json"),
+ "type": "GeodeticCRS",
+ "name": name,
+ "datum": Datum.from_user_input(datum).to_json_dict(),
+ "coordinate_system": {
+ "subtype": "Cartesian",
+ "axis": [
+ {
+ "name": "Geocentric X",
+ "abbreviation": "X",
+ "direction": "geocentricX",
+ "unit": "metre",
+ },
+ {
+ "name": "Geocentric Y",
+ "abbreviation": "Y",
+ "direction": "geocentricY",
+ "unit": "metre",
+ },
+ {
+ "name": "Geocentric Z",
+ "abbreviation": "Z",
+ "direction": "geocentricZ",
+ "unit": "metre",
+ },
+ ],
+ },
+ }
+ super().__init__(geocentric_crs_json)
+
+
+
+
+
+[docs]
+class ProjectedCRS(CustomConstructorCRS):
+ """
+ .. versionadded:: 2.5.0
+
+ This class is for building a Projected CRS.
+ """
+
+ _expected_types = ("Projected CRS", "Derived Projected CRS")
+
+
+[docs]
+ def __init__(
+ self,
+ conversion: Any,
+ name: str = "undefined",
+ cartesian_cs: Any | None = None,
+ geodetic_crs: Any | None = None,
+ ) -> None:
+ """
+ Parameters
+ ----------
+ conversion: Any
+ Anything accepted by :meth:`pyproj.crs.CoordinateSystem.from_user_input`
+ or a conversion from :ref:`coordinate_operation`.
+ name: str, optional
+ The name of the Projected CRS. Default is undefined.
+ cartesian_cs: Any, optional
+ Input to create a Cartesian Coordinate System.
+ Anything accepted by :meth:`pyproj.crs.CoordinateSystem.from_user_input`
+ or :class:`pyproj.crs.coordinate_system.Cartesian2DCS`.
+ geodetic_crs: Any, optional
+ Input to create the Geodetic CRS, a :class:`GeographicCRS` or
+ anything accepted by :meth:`pyproj.crs.CRS.from_user_input`.
+ """
+ proj_crs_json = {
+ "$schema": "https://proj.org/schemas/v0.2/projjson.schema.json",
+ "type": "ProjectedCRS",
+ "name": name,
+ "base_crs": CRS.from_user_input(
+ geodetic_crs or GeographicCRS()
+ ).to_json_dict(),
+ "conversion": CoordinateOperation.from_user_input(
+ conversion
+ ).to_json_dict(),
+ "coordinate_system": CoordinateSystem.from_user_input(
+ cartesian_cs or Cartesian2DCS()
+ ).to_json_dict(),
+ }
+ super().__init__(proj_crs_json)
+
+
+
+
+
+[docs]
+class VerticalCRS(CustomConstructorCRS):
+ """
+ .. versionadded:: 2.5.0
+
+ This class is for building a Vertical CRS.
+
+ .. warning:: geoid_model support only exists in PROJ >= 6.3.0
+
+ """
+
+ _expected_types = ("Vertical CRS",)
+
+
+[docs]
+ def __init__(
+ self,
+ name: str,
+ datum: Any,
+ vertical_cs: Any | None = None,
+ geoid_model: str | None = None,
+ ) -> None:
+ """
+ Parameters
+ ----------
+ name: str
+ The name of the Vertical CRS (e.g. NAVD88 height).
+ datum: Any
+ Anything accepted by :meth:`pyproj.crs.Datum.from_user_input`
+ vertical_cs: Any, optional
+ Input to create a Vertical Coordinate System accepted by
+ :meth:`pyproj.crs.CoordinateSystem.from_user_input`
+ or :class:`pyproj.crs.coordinate_system.VerticalCS`
+ geoid_model: str, optional
+ The name of the GEOID Model (e.g. GEOID12B).
+ """
+ vert_crs_json = {
+ "$schema": "https://proj.org/schemas/v0.2/projjson.schema.json",
+ "type": "VerticalCRS",
+ "name": name,
+ "datum": Datum.from_user_input(datum).to_json_dict(),
+ "coordinate_system": CoordinateSystem.from_user_input(
+ vertical_cs or VerticalCS()
+ ).to_json_dict(),
+ }
+ if geoid_model is not None:
+ vert_crs_json["geoid_model"] = {"name": geoid_model}
+
+ super().__init__(vert_crs_json)
+
+
+
+
+
+[docs]
+class CompoundCRS(CustomConstructorCRS):
+ """
+ .. versionadded:: 2.5.0
+
+ This class is for building a Compound CRS.
+ """
+
+ _expected_types = ("Compound CRS",)
+
+
+[docs]
+ def __init__(self, name: str, components: list[Any]) -> None:
+ """
+ Parameters
+ ----------
+ name: str
+ The name of the Compound CRS.
+ components: list[Any], optional
+ List of CRS to create a Compound Coordinate System.
+ List of anything accepted by :meth:`pyproj.crs.CRS.from_user_input`
+ """
+ compound_crs_json = {
+ "$schema": "https://proj.org/schemas/v0.2/projjson.schema.json",
+ "type": "CompoundCRS",
+ "name": name,
+ "components": [
+ CRS.from_user_input(component).to_json_dict()
+ for component in components
+ ],
+ }
+
+ super().__init__(compound_crs_json)
+
+
+
+
+
+[docs]
+class BoundCRS(CustomConstructorCRS):
+ """
+ .. versionadded:: 2.5.0
+
+ This class is for building a Bound CRS.
+ """
+
+ _expected_types = ("Bound CRS",)
+
+
+[docs]
+ def __init__(self, source_crs: Any, target_crs: Any, transformation: Any) -> None:
+ """
+ Parameters
+ ----------
+ source_crs: Any
+ Input to create a source CRS.
+ target_crs: Any
+ Input to create the target CRS.
+ transformation: Any
+ Input to create the transformation.
+ """
+ bound_crs_json = {
+ "$schema": "https://proj.org/schemas/v0.2/projjson.schema.json",
+ "type": "BoundCRS",
+ "source_crs": CRS.from_user_input(source_crs).to_json_dict(),
+ "target_crs": CRS.from_user_input(target_crs).to_json_dict(),
+ "transformation": CoordinateOperation.from_user_input(
+ transformation
+ ).to_json_dict(),
+ }
+
+ super().__init__(bound_crs_json)
+
+
+
+"""
+This module is for building datums to be used when
+building a CRS.
+"""
+
+from typing import Any
+
+from pyproj._crs import Datum, Ellipsoid, PrimeMeridian
+
+
+
+[docs]
+class CustomDatum(Datum):
+ """
+ .. versionadded:: 2.5.0
+
+ Class to build a datum based on an ellipsoid and prime meridian.
+ """
+
+
+[docs]
+ def __new__(
+ cls,
+ name: str = "undefined",
+ ellipsoid: Any = "WGS 84",
+ prime_meridian: Any = "Greenwich",
+ ):
+ """
+ Parameters
+ ----------
+ name: str, default="undefined"
+ Name of the datum.
+ ellipsoid: Any, default="WGS 84"
+ Anything accepted by :meth:`pyproj.crs.Ellipsoid.from_user_input`
+ or a :class:`pyproj.crs.datum.CustomEllipsoid`.
+ prime_meridian: Any, default="Greenwich"
+ Anything accepted by :meth:`pyproj.crs.PrimeMeridian.from_user_input`.
+ """
+ datum_json = {
+ "$schema": "https://proj.org/schemas/v0.2/projjson.schema.json",
+ "type": "GeodeticReferenceFrame",
+ "name": name,
+ "ellipsoid": Ellipsoid.from_user_input(ellipsoid).to_json_dict(),
+ "prime_meridian": PrimeMeridian.from_user_input(
+ prime_meridian
+ ).to_json_dict(),
+ }
+ return cls.from_json_dict(datum_json)
+
+
+
+
+
+[docs]
+class CustomEllipsoid(Ellipsoid):
+ """
+ .. versionadded:: 2.5.0
+
+ Class to build a custom ellipsoid.
+ """
+
+
+[docs]
+ def __new__(
+ cls,
+ name: str = "undefined",
+ semi_major_axis: float | None = None,
+ inverse_flattening: float | None = None,
+ semi_minor_axis: float | None = None,
+ radius: float | None = None,
+ ):
+ """
+ Parameters
+ ----------
+ name: str, default="undefined"
+ Name of the ellipsoid.
+ semi_major_axis: float, optional
+ The semi major axis in meters. Required if missing radius.
+ inverse_flattening: float, optional
+ The inverse flattening in meters.
+ Required if missing semi_minor_axis and radius.
+ semi_minor_axis: float, optional
+ The semi minor axis in meters.
+ Required if missing inverse_flattening and radius.
+ radius: float, optional
+ The radius in meters. Can only be used alone.
+ Cannot be mixed with other parameters.
+ """
+ ellipsoid_json: dict[str, float | str] = {
+ "$schema": "https://proj.org/schemas/v0.2/projjson.schema.json",
+ "type": "Ellipsoid",
+ "name": name,
+ }
+ if semi_major_axis is not None:
+ ellipsoid_json["semi_major_axis"] = semi_major_axis
+ if inverse_flattening is not None:
+ ellipsoid_json["inverse_flattening"] = inverse_flattening
+ if semi_minor_axis is not None:
+ ellipsoid_json["semi_minor_axis"] = semi_minor_axis
+ if radius is not None:
+ ellipsoid_json["radius"] = radius
+ return cls.from_json_dict(ellipsoid_json)
+
+
+
+
+
+[docs]
+class CustomPrimeMeridian(PrimeMeridian):
+ """
+ .. versionadded:: 2.5.0
+
+ Class to build a prime meridian based on a longitude.
+ """
+
+
+[docs]
+ def __new__(cls, longitude: float, name: str = "undefined"):
+ """
+ Parameters
+ ----------
+ longitude: float
+ Longitude of prime meridian.
+ name: str, optional
+ Name of the prime meridian.
+ """
+ datum_json = {
+ "$schema": "https://proj.org/schemas/v0.2/projjson.schema.json",
+ "type": "PrimeMeridian",
+ "name": name,
+ "longitude": longitude,
+ }
+ return cls.from_json_dict(datum_json)
+
+
+
+"""
+This module contains enumerations used in pyproj.crs.
+"""
+
+from pyproj.enums import BaseEnum
+
+
+
+[docs]
+class DatumType(BaseEnum):
+ """
+ .. versionadded:: 2.5.0
+
+ Datum Types for creating datum with :meth:`pyproj.crs.Datum.from_name`
+
+ Attributes
+ ----------
+ GEODETIC_REFERENCE_FRAME
+ DYNAMIC_GEODETIC_REFERENCE_FRAME
+ VERTICAL_REFERENCE_FRAME
+ DYNAMIC_VERTICAL_REFERENCE_FRAME
+ DATUM_ENSEMBLE
+ """
+
+ GEODETIC_REFERENCE_FRAME = "GEODETIC_REFERENCE_FRAME"
+ DYNAMIC_GEODETIC_REFERENCE_FRAME = "DYNAMIC_GEODETIC_REFERENCE_FRAME"
+ VERTICAL_REFERENCE_FRAME = "VERTICAL_REFERENCE_FRAME"
+ DYNAMIC_VERTICAL_REFERENCE_FRAME = "DYNAMIC_VERTICAL_REFERENCE_FRAME"
+ DATUM_ENSEMBLE = "DATUM_ENSEMBLE"
+
+
+
+
+[docs]
+class CoordinateOperationType(BaseEnum):
+ """
+ .. versionadded:: 2.5.0
+
+ Coordinate Operation Types for creating operation
+ with :meth:`pyproj.crs.CoordinateOperation.from_name`
+
+ Attributes
+ ----------
+ CONVERSION
+ TRANSFORMATION
+ CONCATENATED_OPERATION
+ OTHER_COORDINATE_OPERATION
+ """
+
+ CONVERSION = "CONVERSION"
+ TRANSFORMATION = "TRANSFORMATION"
+ CONCATENATED_OPERATION = "CONCATENATED_OPERATION"
+ OTHER_COORDINATE_OPERATION = "OTHER_COORDINATE_OPERATION"
+
+
+
+
+[docs]
+class Cartesian2DCSAxis(BaseEnum):
+ """
+ .. versionadded:: 2.5.0
+
+ Cartesian 2D Coordinate System Axis for creating axis with
+ with :class:`pyproj.crs.coordinate_system.Cartesian2DCS`
+
+ Attributes
+ ----------
+ EASTING_NORTHING
+ NORTHING_EASTING
+ EASTING_NORTHING_FT
+ NORTHING_EASTING_FT
+ EASTING_NORTHING_US_FT
+ NORTHING_EASTING_US_FT
+ NORTH_POLE_EASTING_SOUTH_NORTHING_SOUTH
+ SOUTH_POLE_EASTING_NORTH_NORTHING_NORTH
+ WESTING_SOUTHING
+ """
+
+ EASTING_NORTHING = "EASTING_NORTHING"
+ NORTHING_EASTING = "NORTHING_EASTING"
+ EASTING_NORTHING_FT = "EASTING_NORTHING_FT"
+ NORTHING_EASTING_FT = "NORTHING_EASTING_FT"
+ EASTING_NORTHING_US_FT = "EASTING_NORTHING_US_FT"
+ NORTHING_EASTING_US_FT = "NORTHING_EASTING_US_FT"
+ NORTH_POLE_EASTING_SOUTH_NORTHING_SOUTH = "NORTH_POLE_EASTING_SOUTH_NORTHING_SOUTH"
+ SOUTH_POLE_EASTING_NORTH_NORTHING_NORTH = "SOUTH_POLE_EASTING_NORTH_NORTHING_NORTH"
+ WESTING_SOUTHING = "WESTING_SOUTHING"
+
+
+
+
+[docs]
+class Ellipsoidal2DCSAxis(BaseEnum):
+ """
+ .. versionadded:: 2.5.0
+
+ Ellipsoidal 2D Coordinate System Axis for creating axis with
+ with :class:`pyproj.crs.coordinate_system.Ellipsoidal2DCS`
+
+ Attributes
+ ----------
+ LONGITUDE_LATITUDE
+ LATITUDE_LONGITUDE
+ """
+
+ LONGITUDE_LATITUDE = "LONGITUDE_LATITUDE"
+ LATITUDE_LONGITUDE = "LATITUDE_LONGITUDE"
+
+
+
+
+[docs]
+class Ellipsoidal3DCSAxis(BaseEnum):
+ """
+ .. versionadded:: 2.5.0
+
+ Ellipsoidal 3D Coordinate System Axis for creating axis with
+ with :class:`pyproj.crs.coordinate_system.Ellipsoidal3DCS`
+
+ Attributes
+ ----------
+ LONGITUDE_LATITUDE_HEIGHT
+ LATITUDE_LONGITUDE_HEIGHT
+ """
+
+ LONGITUDE_LATITUDE_HEIGHT = "LONGITUDE_LATITUDE_HEIGHT"
+ LATITUDE_LONGITUDE_HEIGHT = "LATITUDE_LONGITUDE_HEIGHT"
+
+
+
+
+[docs]
+class VerticalCSAxis(BaseEnum):
+ """
+ .. versionadded:: 2.5.0
+
+ Vertical Coordinate System Axis for creating axis with
+ with :class:`pyproj.crs.coordinate_system.VerticalCS`
+
+ Attributes
+ ----------
+ UP
+ UP_FT
+ UP_US_FT
+ DEPTH
+ DEPTH_FT
+ DEPTH_US_FT
+ GRAVITY_HEIGHT
+ GRAVITY_HEIGHT_FT
+ GRAVITY_HEIGHT_US_FT
+ """
+
+ GRAVITY_HEIGHT = "GRAVITY_HEIGHT"
+ GRAVITY_HEIGHT_FT = "GRAVITY_HEIGHT_FT"
+ GRAVITY_HEIGHT_US_FT = "GRAVITY_HEIGHT_US_FT"
+ DEPTH = "DEPTH"
+ DEPTH_FT = "DEPTH_FT"
+ DEPTH_US_FT = "DEPTH_US_FT"
+ UP = "UP"
+ UP_FT = "UP_FT"
+ UP_US_FT = "UP_US_FT"
+
+
+"""
+Module for managing the PROJ data directory.
+"""
+
+# pylint: disable=global-statement
+import os
+import shutil
+import sys
+from pathlib import Path
+
+from pyproj._context import ( # noqa: F401 pylint: disable=unused-import
+ _set_context_data_dir,
+ get_user_data_dir,
+)
+from pyproj.exceptions import DataDirError
+
+_USER_PROJ_DATA = None
+_VALIDATED_PROJ_DATA = None
+
+
+
+[docs]
+def set_data_dir(proj_data_dir: str | Path) -> None:
+ """
+ Set the data directory for PROJ to use.
+
+ Parameters
+ ----------
+ proj_data_dir: str | Path
+ The path to the PROJ data directory.
+ """
+ global _USER_PROJ_DATA
+ global _VALIDATED_PROJ_DATA
+ _USER_PROJ_DATA = str(proj_data_dir)
+ # set to none to re-validate
+ _VALIDATED_PROJ_DATA = None
+ # need to reset the global PROJ context
+ # to prevent core dumping if the data directory
+ # is not found.
+ _set_context_data_dir()
+
+
+
+
+[docs]
+def append_data_dir(proj_data_dir: str | Path) -> None:
+ """
+ Add an additional data directory for PROJ to use.
+
+ Parameters
+ ----------
+ proj_data_dir: str | Path
+ The path to the PROJ data directory.
+ """
+ set_data_dir(os.pathsep.join([get_data_dir(), str(proj_data_dir)]))
+
+
+
+
+[docs]
+def get_data_dir() -> str:
+ """
+ The order of preference for the data directory is:
+
+ 1. The one set by pyproj.datadir.set_data_dir (if exists & valid)
+ 2. The internal proj directory (if exists & valid)
+ 3. The directory in PROJ_DATA (PROJ 9.1+) | PROJ_LIB (PROJ<9.1) (if exists & valid)
+ 4. The directory on sys.prefix (if exists & valid)
+ 5. The directory on the PATH (if exists & valid)
+
+ Returns
+ -------
+ str:
+ The valid data directory.
+
+ """
+ # to avoid re-validating
+ global _VALIDATED_PROJ_DATA
+ if _VALIDATED_PROJ_DATA is not None:
+ return _VALIDATED_PROJ_DATA
+ internal_datadir = Path(__file__).absolute().parent / "proj_dir" / "share" / "proj"
+ proj_lib_dirs = os.environ.get("PROJ_DATA", os.environ.get("PROJ_LIB", ""))
+ prefix_datadir = Path(sys.prefix, "share", "proj")
+ conda_windows_prefix_datadir = Path(sys.prefix, "Library", "share", "proj")
+
+ def valid_data_dir(potential_data_dir):
+ if (
+ potential_data_dir is not None
+ and Path(potential_data_dir, "proj.db").exists()
+ ):
+ return True
+ return False
+
+ def valid_data_dirs(potential_data_dirs):
+ if potential_data_dirs is None:
+ return False
+ for proj_data_dir in potential_data_dirs.split(os.pathsep):
+ if valid_data_dir(proj_data_dir):
+ return True
+ return None
+
+ if valid_data_dirs(_USER_PROJ_DATA):
+ _VALIDATED_PROJ_DATA = _USER_PROJ_DATA
+ elif valid_data_dir(internal_datadir):
+ _VALIDATED_PROJ_DATA = str(internal_datadir)
+ elif valid_data_dirs(proj_lib_dirs):
+ _VALIDATED_PROJ_DATA = proj_lib_dirs
+ elif valid_data_dir(prefix_datadir):
+ _VALIDATED_PROJ_DATA = str(prefix_datadir)
+ elif valid_data_dir(conda_windows_prefix_datadir):
+ _VALIDATED_PROJ_DATA = str(conda_windows_prefix_datadir)
+ else:
+ proj_exe = shutil.which("proj", path=sys.prefix)
+ if proj_exe is None:
+ proj_exe = shutil.which("proj")
+ if proj_exe is not None:
+ system_proj_dir = Path(proj_exe).parent.parent / "share" / "proj"
+ if valid_data_dir(system_proj_dir):
+ _VALIDATED_PROJ_DATA = str(system_proj_dir)
+
+ if _VALIDATED_PROJ_DATA is None:
+ raise DataDirError(
+ "Valid PROJ data directory not found. "
+ "Either set the path using the environmental variable "
+ "PROJ_DATA (PROJ 9.1+) | PROJ_LIB (PROJ<9.1) or "
+ "with `pyproj.datadir.set_data_dir`."
+ )
+ return _VALIDATED_PROJ_DATA
+
+
+"""
+This module contains enumerations used in pyproj.
+"""
+
+from enum import Enum, IntFlag
+
+
+class BaseEnum(Enum):
+ """
+ Base enumeration class that handles
+ input as strings ignoring case.
+ """
+
+ @classmethod
+ def create(cls, item):
+ """
+ Handles finding the enumeration
+ ignoring case if provided as a string.
+ """
+ try:
+ return cls(item)
+ except ValueError:
+ pass
+ if isinstance(item, str):
+ item = item.upper()
+ for member in cls:
+ if member.value == item:
+ return member
+ raise ValueError(
+ f"Invalid value supplied '{item}'. "
+ f"Only {tuple(version.value for version in cls)} are supported."
+ )
+
+
+
+[docs]
+class WktVersion(BaseEnum):
+ """
+ .. versionadded:: 2.2.0
+
+ Supported CRS WKT string versions
+
+ See: :c:enum:`PJ_WKT_TYPE`
+ """
+
+ #: WKT Version 2 from 2015
+ WKT2_2015 = "WKT2_2015"
+ #: WKT Version 2 from 2015 Simplified
+ WKT2_2015_SIMPLIFIED = "WKT2_2015_SIMPLIFIED"
+ #: Deprecated alias for WKT Version 2 from 2019
+ WKT2_2018 = "WKT2_2018"
+ #: Deprecated alias for WKT Version 2 from 2019 Simplified
+ WKT2_2018_SIMPLIFIED = "WKT2_2018_SIMPLIFIED"
+ #: WKT Version 2 from 2019
+ WKT2_2019 = "WKT2_2019"
+ #: WKT Version 2 from 2019 Simplified
+ WKT2_2019_SIMPLIFIED = "WKT2_2019_SIMPLIFIED"
+ #: WKT Version 1 GDAL Style
+ WKT1_GDAL = "WKT1_GDAL"
+ #: WKT Version 1 ESRI Style
+ WKT1_ESRI = "WKT1_ESRI"
+
+
+
+
+[docs]
+class ProjVersion(BaseEnum):
+ """
+ .. versionadded:: 2.2.0
+
+ Supported CRS PROJ string versions
+ """
+
+ #: PROJ String version 4
+ PROJ_4 = 4
+ #: PROJ String version 5
+ PROJ_5 = 5
+
+
+
+
+[docs]
+class TransformDirection(BaseEnum):
+ """
+ .. versionadded:: 2.2.0
+
+ Supported transform directions
+ """
+
+ #: Forward direction
+ FORWARD = "FORWARD"
+ #: Inverse direction
+ INVERSE = "INVERSE"
+ #: Do nothing
+ IDENT = "IDENT"
+
+
+
+
+[docs]
+class PJType(BaseEnum):
+ """
+ .. versionadded:: 2.4.0
+
+ PJ Types for listing codes with :func:`pyproj.get_codes`
+
+ See: :c:enum:`PJ_TYPE`
+
+ Attributes
+ ----------
+ UNKNOWN
+ ELLIPSOID
+ PRIME_MERIDIAN
+ GEODETIC_REFERENCE_FRAME
+ DYNAMIC_GEODETIC_REFERENCE_FRAME
+ VERTICAL_REFERENCE_FRAME
+ DYNAMIC_VERTICAL_REFERENCE_FRAME
+ DATUM_ENSEMBLE
+ CRS
+ GEODETIC_CRS
+ GEOCENTRIC_CRS
+ GEOGRAPHIC_CRS
+ GEOGRAPHIC_2D_CRS
+ GEOGRAPHIC_3D_CRS
+ VERTICAL_CRS
+ PROJECTED_CRS
+ COMPOUND_CRS
+ TEMPORAL_CRS
+ ENGINEERING_CRS
+ BOUND_CRS
+ OTHER_CRS
+ CONVERSION
+ TRANSFORMATION
+ CONCATENATED_OPERATION
+ OTHER_COORDINATE_OPERATION
+
+ """
+
+ UNKNOWN = "UNKNOWN"
+ ELLIPSOID = "ELLIPSOID"
+ PRIME_MERIDIAN = "PRIME_MERIDIAN"
+ GEODETIC_REFERENCE_FRAME = "GEODETIC_REFERENCE_FRAME"
+ DYNAMIC_GEODETIC_REFERENCE_FRAME = "DYNAMIC_GEODETIC_REFERENCE_FRAME"
+ VERTICAL_REFERENCE_FRAME = "VERTICAL_REFERENCE_FRAME"
+ DYNAMIC_VERTICAL_REFERENCE_FRAME = "DYNAMIC_VERTICAL_REFERENCE_FRAME"
+ DATUM_ENSEMBLE = "DATUM_ENSEMBLE"
+ CRS = "CRS"
+ GEODETIC_CRS = "GEODETIC_CRS"
+ GEOCENTRIC_CRS = "GEOCENTRIC_CRS"
+ GEOGRAPHIC_CRS = "GEOGRAPHIC_CRS"
+ GEOGRAPHIC_2D_CRS = "GEOGRAPHIC_2D_CRS"
+ GEOGRAPHIC_3D_CRS = "GEOGRAPHIC_3D_CRS"
+ VERTICAL_CRS = "VERTICAL_CRS"
+ PROJECTED_CRS = "PROJECTED_CRS"
+ DERIVED_PROJECTED_CRS = "DERIVED_PROJECTED_CRS"
+ COMPOUND_CRS = "COMPOUND_CRS"
+ TEMPORAL_CRS = "TEMPORAL_CRS"
+ ENGINEERING_CRS = "ENGINEERING_CRS"
+ BOUND_CRS = "BOUND_CRS"
+ OTHER_CRS = "OTHER_CRS"
+ CONVERSION = "CONVERSION"
+ TRANSFORMATION = "TRANSFORMATION"
+ CONCATENATED_OPERATION = "CONCATENATED_OPERATION"
+ OTHER_COORDINATE_OPERATION = "OTHER_COORDINATE_OPERATION"
+
+
+
+
+[docs]
+class GeodIntermediateFlag(IntFlag):
+ """
+ .. versionadded:: 3.1.0
+
+ Flags to be used in Geod.[inv|fwd]_intermediate()
+ """
+
+ DEFAULT = 0x0
+
+ NPTS_ROUND = 0x0
+ NPTS_CEIL = 0x1
+ NPTS_TRUNC = 0x2
+
+ DEL_S_RECALC = 0x00
+ DEL_S_NO_RECALC = 0x10
+
+ AZIS_DISCARD = 0x000
+ AZIS_KEEP = 0x100
+
+
+"""
+Exceptions for pyproj
+"""
+
+from pyproj._context import _clear_proj_error, _get_proj_error
+
+
+
+[docs]
+class ProjError(RuntimeError):
+ """Raised when a Proj error occurs."""
+
+ def __init__(self, error_message: str) -> None:
+ proj_error = _get_proj_error()
+ if proj_error is not None:
+ error_message = f"{error_message}: (Internal Proj Error: {proj_error})"
+ _clear_proj_error()
+ super().__init__(error_message)
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+"""
+The Geod class can perform forward and inverse geodetic, or
+Great Circle, computations. The forward computation involves
+determining latitude, longitude and back azimuth of a terminus
+point given the latitude and longitude of an initial point, plus
+azimuth and distance. The inverse computation involves
+determining the forward and back azimuths and distance given the
+latitudes and longitudes of an initial and terminus point.
+"""
+
+__all__ = [
+ "Geod",
+ "pj_ellps",
+ "geodesic_version_str",
+ "GeodIntermediateFlag",
+ "GeodIntermediateReturn",
+ "reverse_azimuth",
+]
+
+import math
+import warnings
+from typing import Any
+
+from pyproj._geod import Geod as _Geod
+from pyproj._geod import GeodIntermediateReturn, geodesic_version_str
+from pyproj._geod import reverse_azimuth as _reverse_azimuth
+from pyproj.enums import GeodIntermediateFlag
+from pyproj.exceptions import GeodError
+from pyproj.list import get_ellps_map
+from pyproj.utils import DataType, _convertback, _copytobuffer
+
+pj_ellps = get_ellps_map()
+
+
+def _params_from_ellps_map(ellps: str) -> tuple[float, float, float, float, bool]:
+ """
+ Build Geodesic parameters from PROJ ellips map
+
+ Parameter
+ ---------
+ ellps: str
+ The name of the ellipse in the map.
+
+ Returns
+ -------
+ tuple[float, float, float, float, bool]
+
+ """
+ ellps_dict = pj_ellps[ellps]
+ semi_major_axis, semi_minor_axis, flattening, eccentricity_squared = (
+ _params_from_kwargs(ellps_dict)
+ )
+ sphere = False
+ if ellps_dict["description"] == "Normal Sphere":
+ sphere = True
+ return semi_major_axis, semi_minor_axis, flattening, eccentricity_squared, sphere
+
+
+def _params_from_kwargs(kwargs: dict) -> tuple[float, float, float, float]:
+ """
+ Build Geodesic parameters from input kwargs:
+
+ - a: the semi-major axis (required).
+
+ Need least one of these parameters.
+
+ - b: the semi-minor axis
+ - rf: the reciprocal flattening
+ - f: flattening
+ - es: eccentricity squared
+
+
+ Parameter
+ ---------
+ kwargs: dict
+ The input kwargs for an ellipse.
+
+ Returns
+ -------
+ tuple[float, float, float, float]
+
+ """
+ semi_major_axis = kwargs["a"]
+ if "b" in kwargs:
+ semi_minor_axis = kwargs["b"]
+ eccentricity_squared = 1.0 - semi_minor_axis**2 / semi_major_axis**2
+ flattening = (semi_major_axis - semi_minor_axis) / semi_major_axis
+ elif "rf" in kwargs:
+ flattening = 1.0 / kwargs["rf"]
+ semi_minor_axis = semi_major_axis * (1.0 - flattening)
+ eccentricity_squared = 1.0 - semi_minor_axis**2 / semi_major_axis**2
+ elif "f" in kwargs:
+ flattening = kwargs["f"]
+ semi_minor_axis = semi_major_axis * (1.0 - flattening)
+ eccentricity_squared = 1.0 - (semi_minor_axis / semi_major_axis) ** 2
+ elif "es" in kwargs:
+ eccentricity_squared = kwargs["es"]
+ semi_minor_axis = math.sqrt(
+ semi_major_axis**2 - eccentricity_squared * semi_major_axis**2
+ )
+ flattening = (semi_major_axis - semi_minor_axis) / semi_major_axis
+ elif "e" in kwargs:
+ eccentricity_squared = kwargs["e"] ** 2
+ semi_minor_axis = math.sqrt(
+ semi_major_axis**2 - eccentricity_squared * semi_major_axis**2
+ )
+ flattening = (semi_major_axis - semi_minor_axis) / semi_major_axis
+ else:
+ semi_minor_axis = semi_major_axis
+ flattening = 0.0
+ eccentricity_squared = 0.0
+ return semi_major_axis, semi_minor_axis, flattening, eccentricity_squared
+
+
+
+[docs]
+class Geod(_Geod):
+ """
+ performs forward and inverse geodetic, or Great Circle,
+ computations. The forward computation (using the 'fwd' method)
+ involves determining latitude, longitude and back azimuth of a
+ terminus point given the latitude and longitude of an initial
+ point, plus azimuth and distance. The inverse computation (using
+ the 'inv' method) involves determining the forward and back
+ azimuths and distance given the latitudes and longitudes of an
+ initial and terminus point.
+
+ Attributes
+ ----------
+ initstring: str
+ The string form of the user input used to create the Geod.
+ sphere: bool
+ If True, it is a sphere.
+ a: float
+ The ellipsoid equatorial radius, or semi-major axis.
+ b: float
+ The ellipsoid polar radius, or semi-minor axis.
+ es: float
+ The 'eccentricity' of the ellipse, squared (1-b2/a2).
+ f: float
+ The ellipsoid 'flattening' parameter ( (a-b)/a ).
+
+ """
+
+
+[docs]
+ def __init__(self, initstring: str | None = None, **kwargs) -> None:
+ """
+ initialize a Geod class instance.
+
+ Geodetic parameters for specifying the ellipsoid
+ can be given in a dictionary 'initparams', as keyword arguments,
+ or as as proj geod initialization string.
+
+ You can get a dictionary of ellipsoids using :func:`pyproj.get_ellps_map`
+ or with the variable `pyproj.pj_ellps`.
+
+ The parameters of the ellipsoid may also be set directly using
+ the 'a' (semi-major or equatorial axis radius) keyword, and
+ any one of the following keywords: 'b' (semi-minor,
+ or polar axis radius), 'e' (eccentricity), 'es' (eccentricity
+ squared), 'f' (flattening), or 'rf' (reciprocal flattening).
+
+ See the proj documentation (https://proj.org) for more
+ information about specifying ellipsoid parameters.
+
+ Example usage:
+
+ >>> from pyproj import Geod
+ >>> g = Geod(ellps='clrk66') # Use Clarke 1866 ellipsoid.
+ >>> # specify the lat/lons of some cities.
+ >>> boston_lat = 42.+(15./60.); boston_lon = -71.-(7./60.)
+ >>> portland_lat = 45.+(31./60.); portland_lon = -123.-(41./60.)
+ >>> newyork_lat = 40.+(47./60.); newyork_lon = -73.-(58./60.)
+ >>> london_lat = 51.+(32./60.); london_lon = -(5./60.)
+ >>> # compute forward and back azimuths, plus distance
+ >>> # between Boston and Portland.
+ >>> az12,az21,dist = g.inv(boston_lon,boston_lat,portland_lon,portland_lat)
+ >>> f"{az12:.3f} {az21:.3f} {dist:.3f}"
+ '-66.531 75.654 4164192.708'
+ >>> # compute latitude, longitude and back azimuth of Portland,
+ >>> # given Boston lat/lon, forward azimuth and distance to Portland.
+ >>> endlon, endlat, backaz = g.fwd(boston_lon, boston_lat, az12, dist)
+ >>> f"{endlat:.3f} {endlon:.3f} {backaz:.3f}"
+ '45.517 -123.683 75.654'
+ >>> # compute the azimuths, distances from New York to several
+ >>> # cities (pass a list)
+ >>> lons1 = 3*[newyork_lon]; lats1 = 3*[newyork_lat]
+ >>> lons2 = [boston_lon, portland_lon, london_lon]
+ >>> lats2 = [boston_lat, portland_lat, london_lat]
+ >>> az12,az21,dist = g.inv(lons1,lats1,lons2,lats2)
+ >>> for faz, baz, d in list(zip(az12,az21,dist)):
+ ... f"{faz:7.3f} {baz:8.3f} {d:12.3f}"
+ ' 54.663 -123.448 288303.720'
+ '-65.463 79.342 4013037.318'
+ ' 51.254 -71.576 5579916.651'
+ >>> g2 = Geod('+ellps=clrk66') # use proj4 style initialization string
+ >>> az12,az21,dist = g2.inv(boston_lon,boston_lat,portland_lon,portland_lat)
+ >>> f"{az12:.3f} {az21:.3f} {dist:.3f}"
+ '-66.531 75.654 4164192.708'
+ """
+ # if initparams is a proj-type init string,
+ # convert to dict.
+ ellpsd: dict[str, str | float] = {}
+ if initstring is not None:
+ for kvpair in initstring.split():
+ # Actually only +a and +b are needed
+ # We can ignore safely any parameter that doesn't have a value
+ if kvpair.find("=") == -1:
+ continue
+ key, val = kvpair.split("=")
+ key = key.lstrip("+")
+ if key in ["a", "b", "rf", "f", "es", "e"]:
+ ellpsd[key] = float(val)
+ else:
+ ellpsd[key] = val
+ # merge this dict with kwargs dict.
+ kwargs = dict(list(kwargs.items()) + list(ellpsd.items()))
+ sphere = False
+ if "ellps" in kwargs:
+ (
+ semi_major_axis,
+ semi_minor_axis,
+ flattening,
+ eccentricity_squared,
+ sphere,
+ ) = _params_from_ellps_map(kwargs["ellps"])
+ else:
+ (
+ semi_major_axis,
+ semi_minor_axis,
+ flattening,
+ eccentricity_squared,
+ ) = _params_from_kwargs(kwargs)
+
+ if math.fabs(flattening) < 1.0e-8:
+ sphere = True
+
+ super().__init__(
+ semi_major_axis, flattening, sphere, semi_minor_axis, eccentricity_squared
+ )
+
+
+
+[docs]
+ def fwd( # pylint: disable=invalid-name
+ self,
+ lons: Any,
+ lats: Any,
+ az: Any,
+ dist: Any,
+ radians: bool = False,
+ inplace: bool = False,
+ return_back_azimuth: bool = True,
+ ) -> tuple[Any, Any, Any]:
+ """
+ Forward transformation
+
+ Determine longitudes, latitudes and back azimuths of terminus
+ points given longitudes and latitudes of initial points,
+ plus forward azimuths and distances.
+
+ .. versionadded:: 3.5.0 inplace
+ .. versionadded:: 3.5.0 return_back_azimuth
+
+ Accepted numeric scalar or array:
+
+ - :class:`int`
+ - :class:`float`
+ - :class:`numpy.floating`
+ - :class:`numpy.integer`
+ - :class:`list`
+ - :class:`tuple`
+ - :class:`array.array`
+ - :class:`numpy.ndarray`
+ - :class:`xarray.DataArray`
+ - :class:`pandas.Series`
+
+ Parameters
+ ----------
+ lons: scalar or array
+ Longitude(s) of initial point(s)
+ lats: scalar or array
+ Latitude(s) of initial point(s)
+ az: scalar or array
+ Forward azimuth(s)
+ dist: scalar or array
+ Distance(s) between initial and terminus point(s)
+ in meters
+ radians: bool, default=False
+ If True, the input data is assumed to be in radians.
+ Otherwise, the data is assumed to be in degrees.
+ inplace: bool, default=False
+ If True, will attempt to write the results to the input array
+ instead of returning a new array. This will fail if the input
+ is not an array in C order with the double data type.
+ return_back_azimuth: bool, default=True
+ If True, the third return value will be the back azimuth,
+ Otherwise, it will be the forward azimuth.
+
+ Returns
+ -------
+ scalar or array:
+ Longitude(s) of terminus point(s)
+ scalar or array:
+ Latitude(s) of terminus point(s)
+ scalar or array:
+ Back azimuth(s) or Forward azimuth(s)
+ """
+ try:
+ # Fast-path for scalar input, will raise if invalid types are input
+ # and we can fallback below
+ return self._fwd_point(
+ lons,
+ lats,
+ az,
+ dist,
+ radians=radians,
+ return_back_azimuth=return_back_azimuth,
+ )
+ except TypeError:
+ pass
+
+ # process inputs, making copies that support buffer API.
+ inx, x_data_type = _copytobuffer(lons, inplace=inplace)
+ iny, y_data_type = _copytobuffer(lats, inplace=inplace)
+ inz, z_data_type = _copytobuffer(az, inplace=inplace)
+ ind = _copytobuffer(dist, inplace=inplace)[0]
+ self._fwd(
+ inx, iny, inz, ind, radians=radians, return_back_azimuth=return_back_azimuth
+ )
+ # if inputs were lists, tuples or floats, convert back.
+ outx = _convertback(x_data_type, inx)
+ outy = _convertback(y_data_type, iny)
+ outz = _convertback(z_data_type, inz)
+ return outx, outy, outz
+
+
+
+[docs]
+ def inv(
+ self,
+ lons1: Any,
+ lats1: Any,
+ lons2: Any,
+ lats2: Any,
+ radians: bool = False,
+ inplace: bool = False,
+ return_back_azimuth: bool = True,
+ ) -> tuple[Any, Any, Any]:
+ """
+
+ Inverse transformation
+
+ Determine forward and back azimuths, plus distances
+ between initial points and terminus points.
+
+ .. versionadded:: 3.5.0 inplace
+ .. versionadded:: 3.5.0 return_back_azimuth
+
+ Accepted numeric scalar or array:
+
+ - :class:`int`
+ - :class:`float`
+ - :class:`numpy.floating`
+ - :class:`numpy.integer`
+ - :class:`list`
+ - :class:`tuple`
+ - :class:`array.array`
+ - :class:`numpy.ndarray`
+ - :class:`xarray.DataArray`
+ - :class:`pandas.Series`
+
+ Parameters
+ ----------
+ lons1: scalar or array
+ Longitude(s) of initial point(s)
+ lats1: scalar or array
+ Latitude(s) of initial point(s)
+ lons2: scalar or array
+ Longitude(s) of terminus point(s)
+ lats2: scalar or array
+ Latitude(s) of terminus point(s)
+ radians: bool, default=False
+ If True, the input data is assumed to be in radians.
+ Otherwise, the data is assumed to be in degrees.
+ inplace: bool, default=False
+ If True, will attempt to write the results to the input array
+ instead of returning a new array. This will fail if the input
+ is not an array in C order with the double data type.
+ return_back_azimuth: bool, default=True
+ If True, the second return value (azi21) will be the back azimuth
+ (flipped 180 degrees), Otherwise, it will also be a forward azimuth.
+
+ Returns
+ -------
+ scalar or array:
+ Forward azimuth(s) (azi12)
+ scalar or array:
+ Back azimuth(s) or Forward azimuth(s) (azi21)
+ scalar or array:
+ Distance(s) between initial and terminus point(s)
+ in meters
+ """
+ try:
+ # Fast-path for scalar input, will raise if invalid types are input
+ # and we can fallback below
+ return self._inv_point(
+ lons1,
+ lats1,
+ lons2,
+ lats2,
+ radians=radians,
+ return_back_azimuth=return_back_azimuth,
+ )
+ except TypeError:
+ pass
+
+ # process inputs, making copies that support buffer API.
+ inx, x_data_type = _copytobuffer(lons1, inplace=inplace)
+ iny, y_data_type = _copytobuffer(lats1, inplace=inplace)
+ inz, z_data_type = _copytobuffer(lons2, inplace=inplace)
+ ind = _copytobuffer(lats2, inplace=inplace)[0]
+ self._inv(
+ inx, iny, inz, ind, radians=radians, return_back_azimuth=return_back_azimuth
+ )
+ # if inputs were lists, tuples or floats, convert back.
+ outx = _convertback(x_data_type, inx)
+ outy = _convertback(y_data_type, iny)
+ outz = _convertback(z_data_type, inz)
+ return outx, outy, outz
+
+
+
+[docs]
+ def npts(
+ self,
+ lon1: float,
+ lat1: float,
+ lon2: float,
+ lat2: float,
+ npts: int,
+ radians: bool = False,
+ initial_idx: int = 1,
+ terminus_idx: int = 1,
+ ) -> list:
+ """
+ .. versionadded:: 3.1.0 initial_idx, terminus_idx
+
+ Given a single initial point and terminus point, returns
+ a list of longitude/latitude pairs describing npts equally
+ spaced intermediate points along the geodesic between the
+ initial and terminus points.
+
+ Similar to inv_intermediate(), but with less options.
+
+ Example usage:
+
+ >>> from pyproj import Geod
+ >>> g = Geod(ellps='clrk66') # Use Clarke 1866 ellipsoid.
+ >>> # specify the lat/lons of Boston and Portland.
+ >>> boston_lat = 42.+(15./60.); boston_lon = -71.-(7./60.)
+ >>> portland_lat = 45.+(31./60.); portland_lon = -123.-(41./60.)
+ >>> # find ten equally spaced points between Boston and Portland.
+ >>> lonlats = g.npts(boston_lon,boston_lat,portland_lon,portland_lat,10)
+ >>> for lon,lat in lonlats: f'{lat:.3f} {lon:.3f}'
+ '43.528 -75.414'
+ '44.637 -79.883'
+ '45.565 -84.512'
+ '46.299 -89.279'
+ '46.830 -94.156'
+ '47.149 -99.112'
+ '47.251 -104.106'
+ '47.136 -109.100'
+ '46.805 -114.051'
+ '46.262 -118.924'
+ >>> # test with radians=True (inputs/outputs in radians, not degrees)
+ >>> import math
+ >>> dg2rad = math.radians(1.)
+ >>> rad2dg = math.degrees(1.)
+ >>> lonlats = g.npts(
+ ... dg2rad*boston_lon,
+ ... dg2rad*boston_lat,
+ ... dg2rad*portland_lon,
+ ... dg2rad*portland_lat,
+ ... 10,
+ ... radians=True
+ ... )
+ >>> for lon,lat in lonlats: f'{rad2dg*lat:.3f} {rad2dg*lon:.3f}'
+ '43.528 -75.414'
+ '44.637 -79.883'
+ '45.565 -84.512'
+ '46.299 -89.279'
+ '46.830 -94.156'
+ '47.149 -99.112'
+ '47.251 -104.106'
+ '47.136 -109.100'
+ '46.805 -114.051'
+ '46.262 -118.924'
+
+ Parameters
+ ----------
+ lon1: float
+ Longitude of the initial point
+ lat1: float
+ Latitude of the initial point
+ lon2: float
+ Longitude of the terminus point
+ lat2: float
+ Latitude of the terminus point
+ npts: int
+ Number of points to be returned
+ (including initial and/or terminus points, if required)
+ radians: bool, default=False
+ If True, the input data is assumed to be in radians.
+ Otherwise, the data is assumed to be in degrees.
+ initial_idx: int, default=1
+ if initial_idx==0 then the initial point would be included in the output
+ (as the first point)
+ terminus_idx: int, default=1
+ if terminus_idx==0 then the terminus point would be included in the output
+ (as the last point)
+ Returns
+ -------
+ list of tuples:
+ list of (lon, lat) points along the geodesic
+ between the initial and terminus points.
+ """
+
+ res = self._inv_or_fwd_intermediate(
+ lon1=lon1,
+ lat1=lat1,
+ lon2_or_azi1=lon2,
+ lat2=lat2,
+ npts=npts,
+ del_s=0,
+ radians=radians,
+ initial_idx=initial_idx,
+ terminus_idx=terminus_idx,
+ flags=GeodIntermediateFlag.AZIS_DISCARD,
+ out_lons=None,
+ out_lats=None,
+ out_azis=None,
+ return_back_azimuth=False,
+ is_fwd=False,
+ )
+ return list(zip(res.lons, res.lats))
+
+
+
+[docs]
+ def inv_intermediate(
+ self,
+ lon1: float,
+ lat1: float,
+ lon2: float,
+ lat2: float,
+ npts: int = 0,
+ del_s: float = 0,
+ initial_idx: int = 1,
+ terminus_idx: int = 1,
+ radians: bool = False,
+ flags: GeodIntermediateFlag = GeodIntermediateFlag.DEFAULT,
+ out_lons: Any | None = None,
+ out_lats: Any | None = None,
+ out_azis: Any | None = None,
+ return_back_azimuth: bool | None = None,
+ ) -> GeodIntermediateReturn:
+ """
+ .. versionadded:: 3.1.0
+ .. versionadded:: 3.5.0 return_back_azimuth
+
+ Given a single initial point and terminus point,
+ and the number of points, returns
+ a list of longitude/latitude pairs describing npts equally
+ spaced intermediate points along the geodesic between the
+ initial and terminus points.
+
+ npts and del_s parameters are mutually exclusive:
+
+ if npts != 0:
+ it calculates the distance between the points by
+ the distance between the initial point and the
+ terminus point divided by npts
+ (the number of intermediate points)
+ else:
+ it calculates the number of intermediate points by
+ dividing the distance between the initial and
+ terminus points by del_s
+ (delimiter distance between two successive points)
+
+ Similar to npts(), but with more options.
+
+ Example usage:
+
+ >>> from pyproj import Geod
+ >>> g = Geod(ellps='clrk66') # Use Clarke 1866 ellipsoid.
+ >>> # specify the lat/lons of Boston and Portland.
+ >>> boston_lat = 42.+(15./60.); boston_lon = -71.-(7./60.)
+ >>> portland_lat = 45.+(31./60.); portland_lon = -123.-(41./60.)
+ >>> # find ten equally spaced points between Boston and Portland.
+ >>> r = g.inv_intermediate(boston_lon,boston_lat,portland_lon,portland_lat,10)
+ >>> for lon,lat in zip(r.lons, r.lats): f'{lat:.3f} {lon:.3f}'
+ '43.528 -75.414'
+ '44.637 -79.883'
+ '45.565 -84.512'
+ '46.299 -89.279'
+ '46.830 -94.156'
+ '47.149 -99.112'
+ '47.251 -104.106'
+ '47.136 -109.100'
+ '46.805 -114.051'
+ '46.262 -118.924'
+ >>> # test with radians=True (inputs/outputs in radians, not degrees)
+ >>> import math
+ >>> dg2rad = math.radians(1.)
+ >>> rad2dg = math.degrees(1.)
+ >>> r = g.inv_intermediate(
+ ... dg2rad*boston_lon,
+ ... dg2rad*boston_lat,
+ ... dg2rad*portland_lon,
+ ... dg2rad*portland_lat,
+ ... 10,
+ ... radians=True
+ ... )
+ >>> for lon,lat in zip(r.lons, r.lats): f'{rad2dg*lat:.3f} {rad2dg*lon:.3f}'
+ '43.528 -75.414'
+ '44.637 -79.883'
+ '45.565 -84.512'
+ '46.299 -89.279'
+ '46.830 -94.156'
+ '47.149 -99.112'
+ '47.251 -104.106'
+ '47.136 -109.100'
+ '46.805 -114.051'
+ '46.262 -118.924'
+
+ Parameters
+ ----------
+ lon1: float
+ Longitude of the initial point
+ lat1: float
+ Latitude of the initial point
+ lon2: float
+ Longitude of the terminus point
+ lat2: float
+ Latitude of the terminus point
+ npts: int, default=0
+ Number of points to be returned
+ npts == 0 if del_s != 0
+ del_s: float, default=0
+ delimiter distance between two successive points
+ del_s == 0 if npts != 0
+ radians: bool, default=False
+ If True, the input data is assumed to be in radians.
+ Otherwise, the data is assumed to be in degrees.
+ initial_idx: int, default=1
+ if initial_idx==0 then the initial point would be included in the output
+ (as the first point)
+ terminus_idx: int, default=1
+ if terminus_idx==0 then the terminus point would be included in the output
+ (as the last point)
+ flags: GeodIntermediateFlag, default=GeodIntermediateFlag.DEFAULT
+ * 1st - round/ceil/trunc (see ``GeodIntermediateFlag.NPTS_*``)
+ * 2nd - update del_s to the new npts or not
+ (see ``GeodIntermediateFlag.DEL_S_*``)
+ * 3rd - if out_azis=None, indicates if to save or discard the azimuths
+ (see ``GeodIntermediateFlag.AZIS_*``)
+ * default - round npts, update del_s accordingly, discard azis
+ out_lons: array, :class:`numpy.ndarray`, optional
+ Longitude(s) of the intermediate point(s)
+ If None then buffers would be allocated internnaly
+ out_lats: array, :class:`numpy.ndarray`, optional
+ Latitudes(s) of the intermediate point(s)
+ If None then buffers would be allocated internnaly
+ out_azis: array, :class:`numpy.ndarray`, optional
+ az12(s) of the intermediate point(s)
+ If None then buffers would be allocated internnaly
+ unless requested otherwise by the flags
+ return_back_azimuth: bool, default=True
+ if True, out_azis will store the back azimuth,
+ Otherwise, out_azis will store the forward azimuth.
+
+ Returns
+ -------
+ GeodIntermediateReturn:
+ number of points, distance and output arrays (GeodIntermediateReturn docs)
+ """
+ if return_back_azimuth is None:
+ return_back_azimuth = True
+ warnings.warn(
+ "Back azimuth is being returned by default to be compatible with fwd()"
+ "This is a breaking change for pyproj 3.5+."
+ "To avoid this warning, set return_back_azimuth=True."
+ "Otherwise, to restore old behaviour, set return_back_azimuth=False."
+ "This warning will be removed in future version."
+ )
+ return super()._inv_or_fwd_intermediate(
+ lon1=lon1,
+ lat1=lat1,
+ lon2_or_azi1=lon2,
+ lat2=lat2,
+ npts=npts,
+ del_s=del_s,
+ radians=radians,
+ initial_idx=initial_idx,
+ terminus_idx=terminus_idx,
+ flags=int(flags),
+ out_lons=out_lons,
+ out_lats=out_lats,
+ out_azis=out_azis,
+ return_back_azimuth=return_back_azimuth,
+ is_fwd=False,
+ )
+
+
+
+[docs]
+ def fwd_intermediate(
+ self,
+ lon1: float,
+ lat1: float,
+ azi1: float,
+ npts: int,
+ del_s: float,
+ initial_idx: int = 1,
+ terminus_idx: int = 1,
+ radians: bool = False,
+ flags: GeodIntermediateFlag = GeodIntermediateFlag.DEFAULT,
+ out_lons: Any | None = None,
+ out_lats: Any | None = None,
+ out_azis: Any | None = None,
+ return_back_azimuth: bool | None = None,
+ ) -> GeodIntermediateReturn:
+ """
+ .. versionadded:: 3.1.0
+ .. versionadded:: 3.5.0 return_back_azimuth
+
+ Given a single initial point and azimuth, number of points (npts)
+ and delimiter distance between two successive points (del_s), returns
+ a list of longitude/latitude pairs describing npts equally
+ spaced intermediate points along the geodesic between the
+ initial and terminus points.
+
+ Example usage:
+
+ >>> from pyproj import Geod
+ >>> g = Geod(ellps='clrk66') # Use Clarke 1866 ellipsoid.
+ >>> # specify the lat/lons of Boston and Portland.
+ >>> boston_lat = 42.+(15./60.); boston_lon = -71.-(7./60.)
+ >>> portland_lat = 45.+(31./60.); portland_lon = -123.-(41./60.)
+ >>> az12,az21,dist = g.inv(boston_lon,boston_lat,portland_lon,portland_lat)
+ >>> # find ten equally spaced points between Boston and Portland.
+ >>> npts = 10
+ >>> del_s = dist/(npts+1)
+ >>> r = g.fwd_intermediate(boston_lon,boston_lat,az12,npts=npts,del_s=del_s)
+ >>> for lon,lat in zip(r.lons, r.lats): f'{lat:.3f} {lon:.3f}'
+ '43.528 -75.414'
+ '44.637 -79.883'
+ '45.565 -84.512'
+ '46.299 -89.279'
+ '46.830 -94.156'
+ '47.149 -99.112'
+ '47.251 -104.106'
+ '47.136 -109.100'
+ '46.805 -114.051'
+ '46.262 -118.924'
+ >>> # test with radians=True (inputs/outputs in radians, not degrees)
+ >>> import math
+ >>> dg2rad = math.radians(1.)
+ >>> rad2dg = math.degrees(1.)
+ >>> r = g.fwd_intermediate(
+ ... dg2rad*boston_lon,
+ ... dg2rad*boston_lat,
+ ... dg2rad*az12,
+ ... npts=npts,
+ ... del_s=del_s,
+ ... radians=True
+ ... )
+ >>> for lon,lat in zip(r.lons, r.lats): f'{rad2dg*lat:.3f} {rad2dg*lon:.3f}'
+ '43.528 -75.414'
+ '44.637 -79.883'
+ '45.565 -84.512'
+ '46.299 -89.279'
+ '46.830 -94.156'
+ '47.149 -99.112'
+ '47.251 -104.106'
+ '47.136 -109.100'
+ '46.805 -114.051'
+ '46.262 -118.924'
+
+ Parameters
+ ----------
+ lon1: float
+ Longitude of the initial point
+ lat1: float
+ Latitude of the initial point
+ azi1: float
+ Azimuth from the initial point towards the terminus point
+ npts: int
+ Number of points to be returned
+ (including initial and/or terminus points, if required)
+ del_s: float
+ delimiter distance between two successive points
+ radians: bool, default=False
+ If True, the input data is assumed to be in radians.
+ Otherwise, the data is assumed to be in degrees.
+ initial_idx: int, default=1
+ if initial_idx==0 then the initial point would be included in the output
+ (as the first point)
+ terminus_idx: int, default=1
+ if terminus_idx==0 then the terminus point would be included in the output
+ (as the last point)
+ flags: GeodIntermediateFlag, default=GeodIntermediateFlag.DEFAULT
+ * 1st - round/ceil/trunc (see ``GeodIntermediateFlag.NPTS_*``)
+ * 2nd - update del_s to the new npts or not
+ (see ``GeodIntermediateFlag.DEL_S_*``)
+ * 3rd - if out_azis=None, indicates if to save or discard the azimuths
+ (see ``GeodIntermediateFlag.AZIS_*``)
+ * default - round npts, update del_s accordingly, discard azis
+ out_lons: array, :class:`numpy.ndarray`, optional
+ Longitude(s) of the intermediate point(s)
+ If None then buffers would be allocated internnaly
+ out_lats: array, :class:`numpy.ndarray`, optional
+ Latitudes(s) of the intermediate point(s)
+ If None then buffers would be allocated internnaly
+ out_azis: array, :class:`numpy.ndarray`, optional
+ az12(s) of the intermediate point(s)
+ If None then buffers would be allocated internnaly
+ unless requested otherwise by the flags
+ return_back_azimuth: bool, default=True
+ if True, out_azis will store the back azimuth,
+ Otherwise, out_azis will store the forward azimuth.
+
+ Returns
+ -------
+ GeodIntermediateReturn:
+ number of points, distance and output arrays (GeodIntermediateReturn docs)
+ """
+ if return_back_azimuth is None:
+ return_back_azimuth = True
+ warnings.warn(
+ "Back azimuth is being returned by default to be compatible with inv()"
+ "This is a breaking change for pyproj 3.5+."
+ "To avoid this warning, set return_back_azimuth=True."
+ "Otherwise, to restore old behaviour, set return_back_azimuth=False."
+ "This warning will be removed in future version."
+ )
+ return super()._inv_or_fwd_intermediate(
+ lon1=lon1,
+ lat1=lat1,
+ lon2_or_azi1=azi1,
+ lat2=math.nan,
+ npts=npts,
+ del_s=del_s,
+ radians=radians,
+ initial_idx=initial_idx,
+ terminus_idx=terminus_idx,
+ flags=int(flags),
+ out_lons=out_lons,
+ out_lats=out_lats,
+ out_azis=out_azis,
+ return_back_azimuth=return_back_azimuth,
+ is_fwd=True,
+ )
+
+
+
+[docs]
+ def line_length(self, lons: Any, lats: Any, radians: bool = False) -> float:
+ """
+ .. versionadded:: 2.3.0
+
+ Calculate the total distance between points along a line (meters).
+
+ >>> from pyproj import Geod
+ >>> geod = Geod('+a=6378137 +f=0.0033528106647475126')
+ >>> lats = [-72.9, -71.9, -74.9, -74.3, -77.5, -77.4, -71.7, -65.9, -65.7,
+ ... -66.6, -66.9, -69.8, -70.0, -71.0, -77.3, -77.9, -74.7]
+ >>> lons = [-74, -102, -102, -131, -163, 163, 172, 140, 113,
+ ... 88, 59, 25, -4, -14, -33, -46, -61]
+ >>> total_length = geod.line_length(lons, lats)
+ >>> f"{total_length:.3f}"
+ '14259605.611'
+
+
+ Parameters
+ ----------
+ lons: array, :class:`numpy.ndarray`, list, tuple, or scalar
+ The longitude points along a line.
+ lats: array, :class:`numpy.ndarray`, list, tuple, or scalar
+ The latitude points along a line.
+ radians: bool, default=False
+ If True, the input data is assumed to be in radians.
+ Otherwise, the data is assumed to be in degrees.
+
+ Returns
+ -------
+ float:
+ The total length of the line (meters).
+ """
+ # process inputs, making copies that support buffer API.
+ inx = _copytobuffer(lons)[0]
+ iny = _copytobuffer(lats)[0]
+ return self._line_length(inx, iny, radians=radians)
+
+
+
+[docs]
+ def line_lengths(self, lons: Any, lats: Any, radians: bool = False) -> Any:
+ """
+ .. versionadded:: 2.3.0
+
+ Calculate the distances between points along a line (meters).
+
+ >>> from pyproj import Geod
+ >>> geod = Geod(ellps="WGS84")
+ >>> lats = [-72.9, -71.9, -74.9]
+ >>> lons = [-74, -102, -102]
+ >>> for line_length in geod.line_lengths(lons, lats):
+ ... f"{line_length:.3f}"
+ '943065.744'
+ '334805.010'
+
+ Parameters
+ ----------
+ lons: array, :class:`numpy.ndarray`, list, tuple, or scalar
+ The longitude points along a line.
+ lats: array, :class:`numpy.ndarray`, list, tuple, or scalar
+ The latitude points along a line.
+ radians: bool, default=False
+ If True, the input data is assumed to be in radians.
+ Otherwise, the data is assumed to be in degrees.
+
+ Returns
+ -------
+ array, :class:`numpy.ndarray`, list, tuple, or scalar:
+ The total length of the line (meters).
+ """
+ # process inputs, making copies that support buffer API.
+ inx, x_data_type = _copytobuffer(lons)
+ iny = _copytobuffer(lats)[0]
+ self._line_length(inx, iny, radians=radians)
+ line_lengths = _convertback(x_data_type, inx)
+ return line_lengths if x_data_type == DataType.FLOAT else line_lengths[:-1]
+
+
+
+[docs]
+ def polygon_area_perimeter(
+ self, lons: Any, lats: Any, radians: bool = False
+ ) -> tuple[float, float]:
+ """
+ .. versionadded:: 2.3.0
+
+ A simple interface for computing the area (meters^2) and perimeter (meters)
+ of a geodesic polygon.
+
+ Arbitrarily complex polygons are allowed. In the case self-intersecting
+ of polygons the area is accumulated "algebraically", e.g., the areas of
+ the 2 loops in a figure-8 polygon will partially cancel. There's no need
+ to "close" the polygon by repeating the first vertex. The area returned
+ is signed with counter-clockwise traversal being treated as positive.
+
+ .. note:: lats should be in the range [-90 deg, 90 deg].
+
+
+ Example usage:
+
+ >>> from pyproj import Geod
+ >>> geod = Geod('+a=6378137 +f=0.0033528106647475126')
+ >>> lats = [-72.9, -71.9, -74.9, -74.3, -77.5, -77.4, -71.7, -65.9, -65.7,
+ ... -66.6, -66.9, -69.8, -70.0, -71.0, -77.3, -77.9, -74.7]
+ >>> lons = [-74, -102, -102, -131, -163, 163, 172, 140, 113,
+ ... 88, 59, 25, -4, -14, -33, -46, -61]
+ >>> poly_area, poly_perimeter = geod.polygon_area_perimeter(lons, lats)
+ >>> f"{poly_area:.1f} {poly_perimeter:.1f}"
+ '13376856682207.4 14710425.4'
+
+
+ Parameters
+ ----------
+ lons: array, :class:`numpy.ndarray`, list, tuple, or scalar
+ An array of longitude values.
+ lats: array, :class:`numpy.ndarray`, list, tuple, or scalar
+ An array of latitude values.
+ radians: bool, default=False
+ If True, the input data is assumed to be in radians.
+ Otherwise, the data is assumed to be in degrees.
+
+ Returns
+ -------
+ (float, float):
+ The geodesic area (meters^2) and perimeter (meters) of the polygon.
+ """
+ return self._polygon_area_perimeter(
+ _copytobuffer(lons)[0], _copytobuffer(lats)[0], radians=radians
+ )
+
+
+
+[docs]
+ def geometry_length(self, geometry, radians: bool = False) -> float:
+ """
+ .. versionadded:: 2.3.0
+
+ Returns the geodesic length (meters) of the shapely geometry.
+
+ If it is a Polygon, it will return the sum of the
+ lengths along the perimeter.
+ If it is a MultiPolygon or MultiLine, it will return
+ the sum of the lengths.
+
+ Example usage:
+
+ >>> from pyproj import Geod
+ >>> from shapely.geometry import Point, LineString
+ >>> line_string = LineString([Point(1, 2), Point(3, 4)])
+ >>> geod = Geod(ellps="WGS84")
+ >>> f"{geod.geometry_length(line_string):.3f}"
+ '313588.397'
+
+ Parameters
+ ----------
+ geometry: :class:`shapely.geometry.BaseGeometry`
+ The geometry to calculate the length from.
+ radians: bool, default=False
+ If True, the input data is assumed to be in radians.
+ Otherwise, the data is assumed to be in degrees.
+
+ Returns
+ -------
+ float:
+ The total geodesic length of the geometry (meters).
+ """
+ try:
+ return self.line_length(*geometry.xy, radians=radians) # type: ignore
+ except (AttributeError, NotImplementedError):
+ pass
+ if hasattr(geometry, "exterior"):
+ return self.geometry_length(geometry.exterior, radians=radians)
+ if hasattr(geometry, "geoms"):
+ total_length = 0.0
+ for geom in geometry.geoms:
+ total_length += self.geometry_length(geom, radians=radians)
+ return total_length
+ raise GeodError("Invalid geometry provided.")
+
+
+
+[docs]
+ def geometry_area_perimeter(
+ self, geometry, radians: bool = False
+ ) -> tuple[float, float]:
+ """
+ .. versionadded:: 2.3.0
+
+ A simple interface for computing the area (meters^2) and perimeter (meters)
+ of a geodesic polygon as a shapely geometry.
+
+ Arbitrarily complex polygons are allowed. In the case self-intersecting
+ of polygons the area is accumulated "algebraically", e.g., the areas of
+ the 2 loops in a figure-8 polygon will partially cancel. There's no need
+ to "close" the polygon by repeating the first vertex.
+
+ .. note:: lats should be in the range [-90 deg, 90 deg].
+
+ .. warning:: The area returned is signed with counter-clockwise (CCW) traversal
+ being treated as positive. For polygons, holes should use the
+ opposite traversal to the exterior (if the exterior is CCW, the
+ holes/interiors should be CW). You can use `shapely.ops.orient` to
+ modify the orientation.
+
+ If it is a Polygon, it will return the area and exterior perimeter.
+ It will subtract the area of the interior holes.
+ If it is a MultiPolygon or MultiLine, it will return
+ the sum of the areas and perimeters of all geometries.
+
+
+ Example usage:
+
+ >>> from pyproj import Geod
+ >>> from shapely.geometry import LineString, Point, Polygon
+ >>> geod = Geod(ellps="WGS84")
+ >>> poly_area, poly_perimeter = geod.geometry_area_perimeter(
+ ... Polygon(
+ ... LineString([
+ ... Point(1, 1), Point(10, 1), Point(10, 10), Point(1, 10)
+ ... ]),
+ ... holes=[LineString([Point(1, 2), Point(3, 4), Point(5, 2)])],
+ ... )
+ ... )
+ >>> f"{poly_area:.0f} {poly_perimeter:.0f}"
+ '944373881400 3979008'
+
+
+ Parameters
+ ----------
+ geometry: :class:`shapely.geometry.BaseGeometry`
+ The geometry to calculate the area and perimeter from.
+ radians: bool, default=False
+ If True, the input data is assumed to be in radians.
+ Otherwise, the data is assumed to be in degrees.
+
+ Returns
+ -------
+ (float, float):
+ The geodesic area (meters^2) and perimeter (meters) of the polygon.
+ """
+ try:
+ return self.polygon_area_perimeter( # type: ignore
+ *geometry.xy, radians=radians
+ )
+ except (AttributeError, NotImplementedError):
+ pass
+ # polygon
+ if hasattr(geometry, "exterior"):
+ total_area, total_perimeter = self.geometry_area_perimeter(
+ geometry.exterior, radians=radians
+ )
+ # subtract area of holes
+ for hole in geometry.interiors:
+ area, _ = self.geometry_area_perimeter(hole, radians=radians)
+ total_area += area
+ return total_area, total_perimeter
+ # multi geometries
+ if hasattr(geometry, "geoms"):
+ total_area = 0.0
+ total_perimeter = 0.0
+ for geom in geometry.geoms:
+ area, perimeter = self.geometry_area_perimeter(geom, radians=radians)
+ total_area += area
+ total_perimeter += perimeter
+ return total_area, total_perimeter
+ raise GeodError("Invalid geometry provided.")
+
+
+ def __repr__(self) -> str:
+ # search for ellipse name
+ for ellps, vals in pj_ellps.items():
+ if self.a == vals["a"]:
+ # self.sphere is True when self.f is zero or very close to
+ # zero (0), so prevent divide by zero.
+ if self.b == vals.get("b") or (
+ not self.sphere and (1.0 / self.f) == vals.get("rf")
+ ):
+ return f"{self.__class__.__name__}(ellps={ellps!r})"
+
+ # no ellipse name found, call super class
+ return super().__repr__()
+
+ def __eq__(self, other: Any) -> bool:
+ """
+ equality operator == for Geod objects
+
+ Example usage:
+
+ >>> from pyproj import Geod
+ >>> # Use Clarke 1866 ellipsoid.
+ >>> gclrk1 = Geod(ellps='clrk66')
+ >>> # Define Clarke 1866 using parameters
+ >>> gclrk2 = Geod(a=6378206.4, b=6356583.8)
+ >>> gclrk1 == gclrk2
+ True
+ >>> # WGS 66 ellipsoid, PROJ style
+ >>> gwgs66 = Geod('+ellps=WGS66')
+ >>> # Naval Weapons Lab., 1965 ellipsoid
+ >>> gnwl9d = Geod('+ellps=NWL9D')
+ >>> # these ellipsoids are the same
+ >>> gnwl9d == gwgs66
+ True
+ >>> gclrk1 != gnwl9d # Clarke 1866 is unlike NWL9D
+ True
+ """
+ if not isinstance(other, _Geod):
+ return False
+
+ return self.__repr__() == other.__repr__()
+
+
+
+def reverse_azimuth(azi: Any, radians: bool = False) -> Any:
+ """
+ Reverses the given azimuth (forward <-> backwards)
+
+ .. versionadded:: 3.5.0
+
+ Accepted numeric scalar or array:
+
+ - :class:`int`
+ - :class:`float`
+ - :class:`numpy.floating`
+ - :class:`numpy.integer`
+ - :class:`list`
+ - :class:`tuple`
+ - :class:`array.array`
+ - :class:`numpy.ndarray`
+ - :class:`xarray.DataArray`
+ - :class:`pandas.Series`
+
+ Parameters
+ ----------
+ azi: scalar or array
+ The azimuth.
+ radians: bool, default=False
+ If True, the input data is assumed to be in radians.
+ Otherwise, the data is assumed to be in degrees.
+
+ Returns
+ -------
+ scalar or array:
+ The reversed azimuth (forward <-> backwards)
+ """
+ inazi, azi_data_type = _copytobuffer(azi)
+ _reverse_azimuth(inazi, radians=radians)
+ return _convertback(azi_data_type, inazi)
+
+"""
+Module for managing the PROJ network settings.
+"""
+
+import os
+from pathlib import Path
+
+import certifi
+
+from pyproj._context import _set_context_ca_bundle_path
+from pyproj._network import ( # noqa: F401 pylint: disable=unused-import
+ is_network_enabled,
+ set_network_enabled,
+)
+
+
+
+[docs]
+def set_ca_bundle_path(ca_bundle_path: Path | str | bool | None = None) -> None:
+ """
+ .. versionadded:: 3.0.0
+
+ Sets the path to the CA Bundle used by the `curl`
+ built into PROJ when PROJ network is enabled.
+
+ See: :c:func:`proj_context_set_ca_bundle_path`
+
+ Environment variables:
+
+ - PROJ_CURL_CA_BUNDLE
+ - CURL_CA_BUNDLE
+ - SSL_CERT_FILE
+
+ Parameters
+ ----------
+ ca_bundle_path: Path | str | bool | None, optional
+ Default is None, which only uses the `certifi` package path as a fallback if
+ the environment variables are not set. If a path is passed in, then
+ that will be the path used. If it is set to True, then it will default
+ to using the path provided, by the `certifi` package. If it is set to False
+ or an empty string then it will default to the system settings or environment
+ variables.
+ """
+ env_var_names = ("PROJ_CURL_CA_BUNDLE", "CURL_CA_BUNDLE", "SSL_CERT_FILE")
+ if ca_bundle_path is False:
+ # need to reset CA Bundle path to use system settings
+ # or environment variables because it
+ # could have been changed by the user previously
+ ca_bundle_path = ""
+ elif isinstance(ca_bundle_path, (str, Path)):
+ ca_bundle_path = str(ca_bundle_path)
+ elif (ca_bundle_path is True) or not any(
+ env_var_name in os.environ for env_var_name in env_var_names
+ ):
+ ca_bundle_path = certifi.where()
+ else:
+ # reset CA Bundle path to use system settings
+ # or environment variables
+ ca_bundle_path = ""
+
+ _set_context_ca_bundle_path(ca_bundle_path)
+
+
+"""
+Performs cartographic transformations (converts from
+longitude,latitude to native map projection x,y coordinates and
+vice versa) using PROJ (https://proj.org).
+
+A Proj class instance is initialized with proj map projection
+control parameter key/value pairs. The key/value pairs can
+either be passed in a dictionary, or as keyword arguments,
+or as a PROJ string (compatible with the proj command). See
+:ref:`projections` for examples of
+key/value pairs defining different map projections.
+
+Calling a Proj class instance with the arguments lon, lat will
+convert lon/lat (in degrees) to x/y native map projection
+coordinates (in meters).
+"""
+
+import re
+import warnings
+from typing import Any
+
+from pyproj._compat import cstrencode
+from pyproj._transformer import Factors
+from pyproj.crs import CRS
+from pyproj.enums import TransformDirection
+from pyproj.list import get_proj_operations_map
+from pyproj.transformer import Transformer, TransformerFromPipeline
+from pyproj.utils import _convertback, _copytobuffer
+
+pj_list = get_proj_operations_map()
+
+
+
+[docs]
+class Proj(Transformer):
+ """
+ Performs cartographic transformations. Converts from
+ longitude, latitude to native map projection x,y coordinates and
+ vice versa using PROJ (https://proj.org).
+
+ Attributes
+ ----------
+ srs: str
+ The string form of the user input used to create the Proj.
+ crs: pyproj.crs.CRS
+ The CRS object associated with the Proj.
+
+ """
+
+
+[docs]
+ def __init__(
+ self, projparams: Any | None = None, preserve_units: bool = True, **kwargs
+ ) -> None:
+ """
+ A Proj class instance is initialized with proj map projection
+ control parameter key/value pairs. The key/value pairs can
+ either be passed in a dictionary, or as keyword arguments,
+ or as a PROJ string (compatible with the proj command). See
+ :ref:`projections` for examples of
+ key/value pairs defining different map projections.
+
+ Parameters
+ ----------
+ projparams: int, str, dict, pyproj.CRS
+ A PROJ or WKT string, PROJ dict, EPSG integer, or a pyproj.CRS instance.
+ preserve_units: bool
+ If false, will ensure +units=m.
+ **kwargs:
+ PROJ projection parameters.
+
+
+ Example usage:
+
+ >>> from pyproj import Proj
+ >>> p = Proj(proj='utm',zone=10,ellps='WGS84', preserve_units=False)
+ >>> x,y = p(-120.108, 34.36116666)
+ >>> 'x=%9.3f y=%11.3f' % (x,y)
+ 'x=765975.641 y=3805993.134'
+ >>> 'lon=%8.3f lat=%5.3f' % p(x,y,inverse=True)
+ 'lon=-120.108 lat=34.361'
+ >>> # do 3 cities at a time in a tuple (Fresno, LA, SF)
+ >>> lons = (-119.72,-118.40,-122.38)
+ >>> lats = (36.77, 33.93, 37.62 )
+ >>> x,y = p(lons, lats)
+ >>> 'x: %9.3f %9.3f %9.3f' % x
+ 'x: 792763.863 925321.537 554714.301'
+ >>> 'y: %9.3f %9.3f %9.3f' % y
+ 'y: 4074377.617 3763936.941 4163835.303'
+ >>> lons, lats = p(x, y, inverse=True) # inverse transform
+ >>> 'lons: %8.3f %8.3f %8.3f' % lons
+ 'lons: -119.720 -118.400 -122.380'
+ >>> 'lats: %8.3f %8.3f %8.3f' % lats
+ 'lats: 36.770 33.930 37.620'
+ >>> p2 = Proj('+proj=utm +zone=10 +ellps=WGS84', preserve_units=False)
+ >>> x,y = p2(-120.108, 34.36116666)
+ >>> 'x=%9.3f y=%11.3f' % (x,y)
+ 'x=765975.641 y=3805993.134'
+ >>> p = Proj("EPSG:32667", preserve_units=False)
+ >>> 'x=%12.3f y=%12.3f (meters)' % p(-114.057222, 51.045)
+ 'x=-1783506.250 y= 6193827.033 (meters)'
+ >>> p = Proj("EPSG:32667")
+ >>> 'x=%12.3f y=%12.3f (feet)' % p(-114.057222, 51.045)
+ 'x=-5851386.754 y=20320914.191 (feet)'
+ >>> # test data with radian inputs
+ >>> p1 = Proj("EPSG:4214")
+ >>> x1, y1 = p1(116.366, 39.867)
+ >>> f'{x1:.3f} {y1:.3f}'
+ '116.366 39.867'
+ >>> x2, y2 = p1(x1, y1, inverse=True)
+ >>> f'{x2:.3f} {y2:.3f}'
+ '116.366 39.867'
+ """
+ self.crs = CRS.from_user_input(projparams, **kwargs)
+ # make sure units are meters if preserve_units is False.
+ if not preserve_units and "foot" in self.crs.axis_info[0].unit_name:
+ # ignore export to PROJ string deprecation warning
+ with warnings.catch_warnings():
+ warnings.filterwarnings(
+ "ignore",
+ "You will likely lose important projection information",
+ UserWarning,
+ )
+ projstring = self.crs.to_proj4(4)
+ projstring = re.sub(r"\s\+units=[\w-]+", "", projstring)
+ projstring += " +units=m"
+ self.crs = CRS(projstring)
+
+ # ignore export to PROJ string deprecation warning
+ with warnings.catch_warnings():
+ warnings.filterwarnings(
+ "ignore",
+ "You will likely lose important projection information",
+ UserWarning,
+ )
+ projstring = self.crs.to_proj4() or self.crs.srs
+
+ self.srs = re.sub(r"\s\+?type=crs", "", projstring).strip()
+ super().__init__(TransformerFromPipeline(cstrencode(self.srs)))
+
+
+
+[docs]
+ def __call__(
+ self,
+ longitude: Any,
+ latitude: Any,
+ inverse: bool = False,
+ errcheck: bool = False,
+ radians: bool = False,
+ ) -> tuple[Any, Any]:
+ """
+ Calling a Proj class instance with the arguments lon, lat will
+ convert lon/lat (in degrees) to x/y native map projection
+ coordinates (in meters).
+
+ Inputs should be doubles (they will be cast to doubles if they
+ are not, causing a slight performance hit).
+
+ Works with numpy and regular python array objects, python
+ sequences and scalars, but is fastest for array objects.
+
+ Accepted numeric scalar or array:
+
+ - :class:`int`
+ - :class:`float`
+ - :class:`numpy.floating`
+ - :class:`numpy.integer`
+ - :class:`list`
+ - :class:`tuple`
+ - :class:`array.array`
+ - :class:`numpy.ndarray`
+ - :class:`xarray.DataArray`
+ - :class:`pandas.Series`
+
+ Parameters
+ ----------
+ longitude: scalar or array
+ Input longitude coordinate(s).
+ latitude: scalar or array
+ Input latitude coordinate(s).
+ inverse: bool, default=False
+ If inverse is True the inverse transformation from x/y to
+ lon/lat is performed.
+ radians: bool, default=False
+ If True, will expect input data to be in radians and will return radians
+ if the projection is geographic. Otherwise, it uses degrees.
+ This does not work with pyproj 2 and is ignored. It will be enabled again
+ in pyproj 3.
+ errcheck: bool, default=False
+ If True, an exception is raised if the errors are found in the process.
+ If False, ``inf`` is returned for errors.
+
+ Returns
+ -------
+ tuple[Any, Any]:
+ The transformed coordinates.
+ """
+ if inverse:
+ direction = TransformDirection.INVERSE
+ else:
+ direction = TransformDirection.FORWARD
+ return self.transform(
+ xx=longitude,
+ yy=latitude,
+ direction=direction,
+ errcheck=errcheck,
+ radians=radians,
+ )
+
+
+
+[docs]
+ def get_factors(
+ self,
+ longitude: Any,
+ latitude: Any,
+ radians: bool = False,
+ errcheck: bool = False,
+ ) -> Factors:
+ """
+ .. versionadded:: 2.6.0
+
+ Calculate various cartographic properties, such as scale factors, angular
+ distortion and meridian convergence. Depending on the underlying projection
+ values will be calculated either numerically (default) or analytically.
+
+ The function also calculates the partial derivatives of the given
+ coordinate.
+
+ Accepted numeric scalar or array:
+
+ - :class:`int`
+ - :class:`float`
+ - :class:`numpy.floating`
+ - :class:`numpy.integer`
+ - :class:`list`
+ - :class:`tuple`
+ - :class:`array.array`
+ - :class:`numpy.ndarray`
+ - :class:`xarray.DataArray`
+ - :class:`pandas.Series`
+
+ Parameters
+ ----------
+ longitude: scalar or array
+ Input longitude coordinate(s).
+ latitude: scalar or array
+ Input latitude coordinate(s).
+ radians: bool, default=False
+ If True, will expect input data to be in radians and will return radians
+ if the projection is geographic. Otherwise, it uses degrees.
+ errcheck: bool, default=False
+ If True, an exception is raised if the errors are found in the process.
+ If False, ``inf`` is returned on error.
+
+ Returns
+ -------
+ Factors
+ """
+ # process inputs, making copies that support buffer API.
+ inx, x_data_type = _copytobuffer(longitude)
+ iny = _copytobuffer(latitude)[0]
+
+ # calculate the factors
+ factors = self._transformer._get_factors(
+ inx, iny, radians=radians, errcheck=errcheck
+ )
+
+ # if inputs were lists, tuples or floats, convert back.
+ return Factors(
+ meridional_scale=_convertback(x_data_type, factors.meridional_scale),
+ parallel_scale=_convertback(x_data_type, factors.parallel_scale),
+ areal_scale=_convertback(x_data_type, factors.areal_scale),
+ angular_distortion=_convertback(x_data_type, factors.angular_distortion),
+ meridian_parallel_angle=_convertback(
+ x_data_type, factors.meridian_parallel_angle
+ ),
+ meridian_convergence=_convertback(
+ x_data_type, factors.meridian_convergence
+ ),
+ tissot_semimajor=_convertback(x_data_type, factors.tissot_semimajor),
+ tissot_semiminor=_convertback(x_data_type, factors.tissot_semiminor),
+ dx_dlam=_convertback(x_data_type, factors.dx_dlam),
+ dx_dphi=_convertback(x_data_type, factors.dx_dphi),
+ dy_dlam=_convertback(x_data_type, factors.dy_dlam),
+ dy_dphi=_convertback(x_data_type, factors.dy_dphi),
+ )
+
+
+
+[docs]
+ def definition_string(self) -> str:
+ """Returns formal definition string for projection
+
+ >>> Proj("EPSG:4326").definition_string()
+ 'proj=longlat datum=WGS84 no_defs ellps=WGS84 towgs84=0,0,0'
+ """
+ return self.definition
+
+
+
+[docs]
+ def to_latlong_def(self) -> str | None:
+ """return the definition string of the geographic (lat/lon)
+ coordinate version of the current projection"""
+ return self.crs.geodetic_crs.to_proj4(4) if self.crs.geodetic_crs else None
+
+
+
+[docs]
+ def to_latlong(self) -> "Proj":
+ """return a new Proj instance which is the geographic (lat/lon)
+ coordinate version of the current projection"""
+ return Proj(self.crs.geodetic_crs)
+
+
+ def __reduce__(self) -> tuple[type["Proj"], tuple[str]]:
+ """special method that allows pyproj.Proj instance to be pickled"""
+ return self.__class__, (self.crs.srs,)
+
+
+"""
+Based on the logic in the PROJ projsync CLI program
+
+https://github.com/OSGeo/PROJ/blob/9ff543c4ffd86152bc58d0a0164b2ce9ebbb8bec/src/apps/projsync.cpp
+"""
+
+import hashlib
+import json
+import os
+from datetime import datetime
+from functools import partial
+from pathlib import Path
+from typing import Any
+from urllib.request import urlretrieve
+
+from pyproj._sync import get_proj_endpoint
+from pyproj.aoi import BBox
+from pyproj.datadir import get_data_dir, get_user_data_dir
+
+
+def _bbox_from_coords(coords: list) -> BBox | None:
+ """
+ Get the bounding box from coordinates
+ """
+ try:
+ xxx, yyy = zip(*coords)
+ return BBox(west=min(xxx), south=min(yyy), east=max(xxx), north=max(yyy))
+ except ValueError:
+ pass
+ coord_bbox = None
+ for coord_set in coords:
+ bbox = _bbox_from_coords(coord_set)
+ if coord_bbox is None:
+ coord_bbox = bbox
+ else:
+ coord_bbox.west = min(coord_bbox.west, bbox.west)
+ coord_bbox.south = min(coord_bbox.south, bbox.south)
+ coord_bbox.north = max(coord_bbox.north, bbox.north)
+ coord_bbox.east = max(coord_bbox.east, bbox.east)
+ return coord_bbox
+
+
+def _bbox_from_geom(geom: dict[str, Any]) -> BBox | None:
+ """
+ Get the bounding box from geojson geometry
+ """
+ if "coordinates" not in geom or "type" not in geom:
+ return None
+ coordinates = geom["coordinates"]
+ if geom["type"] != "MultiPolygon":
+ return _bbox_from_coords(coordinates)
+ found_minus_180 = False
+ found_plus_180 = False
+ bboxes = []
+ for coordinate_set in coordinates:
+ bbox = _bbox_from_coords(coordinate_set)
+ if bbox is None:
+ continue
+ if bbox.west == -180:
+ found_minus_180 = True
+ elif bbox.east == 180:
+ found_plus_180 = True
+ bboxes.append(bbox)
+ grid_bbox = None
+ for bbox in bboxes:
+ if found_minus_180 and found_plus_180 and bbox.west == -180:
+ bbox.west = 180
+ bbox.east += 360
+ if grid_bbox is None:
+ grid_bbox = bbox
+ else:
+ grid_bbox.west = min(grid_bbox.west, bbox.west)
+ grid_bbox.south = min(grid_bbox.south, bbox.south)
+ grid_bbox.north = max(grid_bbox.north, bbox.north)
+ grid_bbox.east = max(grid_bbox.east, bbox.east)
+ return grid_bbox
+
+
+def _filter_bbox(
+ feature: dict[str, Any], bbox: BBox, spatial_test: str, include_world_coverage: bool
+) -> bool:
+ """
+ Filter by the bounding box. Designed to use with 'filter'
+ """
+ geom = feature.get("geometry")
+ if geom is not None:
+ geom_bbox = _bbox_from_geom(geom)
+ if geom_bbox is None:
+ return False
+ if (
+ geom_bbox.east - geom_bbox.west > 359
+ and geom_bbox.north - geom_bbox.south > 179
+ ):
+ if not include_world_coverage:
+ return False
+ geom_bbox.west = -float("inf")
+ geom_bbox.east = float("inf")
+ elif geom_bbox.east > 180 and bbox.west < -180:
+ geom_bbox.west -= 360
+ geom_bbox.east -= 360
+ return getattr(bbox, spatial_test)(geom_bbox)
+ return False
+
+
+def _filter_properties(
+ feature: dict[str, Any],
+ source_id: str | None = None,
+ area_of_use: str | None = None,
+ filename: str | None = None,
+) -> bool:
+ """
+ Filter by the properties. Designed to use with 'filter'
+ """
+ properties = feature.get("properties")
+ if not properties:
+ return False
+ p_filename = properties.get("name")
+ p_source_id = properties.get("source_id")
+ if not p_filename or not p_source_id:
+ return False
+ source_id__matched = source_id is None or source_id in p_source_id
+ area_of_use__matched = area_of_use is None or area_of_use in properties.get(
+ "area_of_use", ""
+ )
+ filename__matched = filename is None or filename in p_filename
+ if source_id__matched and area_of_use__matched and filename__matched:
+ return True
+ return False
+
+
+def _is_download_needed(grid_name: str) -> bool:
+ """
+ Run through all of the PROJ directories to see if the
+ file already exists.
+ """
+ if Path(get_user_data_dir(), grid_name).exists():
+ return False
+ for data_dir in get_data_dir().split(os.pathsep):
+ if Path(data_dir, grid_name).exists():
+ return False
+ return True
+
+
+def _filter_download_needed(feature: dict[str, Any]) -> bool:
+ """
+ Filter grids so only those that need to be downloaded are included.
+ """
+ properties = feature.get("properties")
+ if not properties:
+ return False
+ filename = properties.get("name")
+ if not filename:
+ return False
+ return _is_download_needed(filename)
+
+
+def _sha256sum(input_file):
+ """
+ Return sha256 checksum of file given by path.
+ """
+
+ hasher = hashlib.sha256()
+ with open(input_file, "rb") as file:
+ for chunk in iter(lambda: file.read(65536), b""):
+ hasher.update(chunk)
+
+ return hasher.hexdigest()
+
+
+def _download_resource_file(
+ file_url, short_name, directory, verbose=False, sha256=None
+):
+ """
+ Download resource file from PROJ url
+ """
+ if verbose:
+ print(f"Downloading: {file_url}")
+ tmp_path = Path(directory, f"{short_name}.part")
+ try:
+ urlretrieve(file_url, tmp_path)
+ if sha256 is not None and sha256 != _sha256sum(tmp_path):
+ raise RuntimeError(f"SHA256 mismatch: {short_name}")
+ tmp_path.replace(Path(directory, short_name))
+ finally:
+ try:
+ os.remove(tmp_path)
+ except FileNotFoundError:
+ pass
+
+
+def _load_grid_geojson(target_directory: str | Path | None = None) -> dict[str, Any]:
+ """
+ Returns
+ -------
+ dict[str, Any]:
+ The PROJ grid data list.
+ """
+ if target_directory is None:
+ target_directory = get_user_data_dir(True)
+ local_path = Path(target_directory, "files.geojson")
+ if not local_path.exists() or (
+ (datetime.utcnow() - datetime.fromtimestamp(local_path.stat().st_mtime)).days
+ > 0
+ ):
+ _download_resource_file(
+ file_url=f"{get_proj_endpoint()}/files.geojson",
+ short_name="files.geojson",
+ directory=target_directory,
+ )
+ return json.loads(local_path.read_text(encoding="utf-8"))
+
+
+
+[docs]
+def get_transform_grid_list(
+ source_id: str | None = None,
+ area_of_use: str | None = None,
+ filename: str | None = None,
+ bbox: BBox | None = None,
+ spatial_test: str = "intersects",
+ include_world_coverage: bool = True,
+ include_already_downloaded: bool = False,
+ target_directory: str | Path | None = None,
+) -> tuple:
+ """
+ Get a list of transform grids that can be downloaded.
+
+ Parameters
+ ----------
+ source_id: str, optional
+ area_of_use: str, optional
+ filename: str, optional
+ bbox: BBox, optional
+ spatial_test: str, default="intersects"
+ Can be "contains" or "intersects".
+ include_world_coverage: bool, default=True
+ If True, it will include grids with a global extent.
+ include_already_downloaded: bool, default=False
+ If True, it will list grids regardless of if they are downloaded.
+ target_directory: str | Path, optional
+ The directory to download the geojson file to.
+ Default is the user writable directory.
+
+ Returns
+ -------
+ list[dict[str, Any]]:
+ A list of geojson data of containing information about features
+ that can be downloaded.
+ """
+ features = _load_grid_geojson(target_directory=target_directory)["features"]
+ if bbox is not None:
+ if bbox.west > 180 and bbox.east > bbox.west:
+ bbox.west -= 360
+ bbox.east -= 360
+ elif bbox.west < -180 and bbox.east > bbox.west:
+ bbox.west += 360
+ bbox.east += 360
+ elif abs(bbox.west) < 180 and abs(bbox.east) < 180 and bbox.east < bbox.west:
+ bbox.east += 360
+ features = filter(
+ partial(
+ _filter_bbox,
+ bbox=bbox,
+ spatial_test=spatial_test,
+ include_world_coverage=include_world_coverage,
+ ),
+ features,
+ )
+ # filter by properties
+ features = filter(
+ partial(
+ _filter_properties,
+ source_id=source_id,
+ area_of_use=area_of_use,
+ filename=filename,
+ ),
+ features,
+ )
+ if include_already_downloaded:
+ return tuple(features)
+ return tuple(filter(_filter_download_needed, features))
+
+
+"""
+The transformer module is for performing cartographic transformations.
+"""
+
+__all__ = [
+ "transform",
+ "itransform",
+ "Transformer",
+ "TransformerGroup",
+ "AreaOfInterest",
+]
+import threading
+import warnings
+from abc import ABC, abstractmethod
+from array import array
+from collections.abc import Iterable, Iterator
+from dataclasses import dataclass
+from itertools import chain, islice
+from pathlib import Path
+from typing import Any, overload
+
+from pyproj import CRS
+from pyproj._compat import cstrencode
+from pyproj._context import _clear_proj_error
+from pyproj._crs import AreaOfUse, CoordinateOperation
+from pyproj._transformer import ( # noqa: F401 pylint: disable=unused-import
+ AreaOfInterest,
+ _Transformer,
+ _TransformerGroup,
+)
+from pyproj.datadir import get_user_data_dir
+from pyproj.enums import ProjVersion, TransformDirection, WktVersion
+from pyproj.exceptions import ProjError
+from pyproj.sync import _download_resource_file
+from pyproj.utils import _convertback, _copytobuffer
+
+
+class TransformerMaker(ABC):
+ """
+ .. versionadded:: 3.1.0
+
+ Base class for generating new instances
+ of the Cython _Transformer class for
+ thread safety in the Transformer class.
+ """
+
+ @abstractmethod
+ def __call__(self) -> _Transformer:
+ """
+ Returns
+ -------
+ _Transformer
+ """
+ raise NotImplementedError
+
+
+@dataclass(frozen=True)
+class TransformerUnsafe(TransformerMaker):
+ """
+ .. versionadded:: 3.1.0
+
+ Returns the original Cython _Transformer
+ and is not thread-safe.
+ """
+
+ transformer: _Transformer
+
+ def __call__(self) -> _Transformer:
+ """
+ Returns
+ -------
+ _Transformer
+ """
+ return self.transformer
+
+
+@dataclass(frozen=True)
+class TransformerFromCRS( # pylint: disable=too-many-instance-attributes
+ TransformerMaker
+):
+ """
+ .. versionadded:: 3.1.0
+
+ .. versionadded:: 3.4.0 force_over
+
+ Generates a Cython _Transformer class from input CRS data.
+ """
+
+ crs_from: bytes
+ crs_to: bytes
+ always_xy: bool
+ area_of_interest: AreaOfInterest | None
+ authority: str | None
+ accuracy: str | None
+ allow_ballpark: bool | None
+ force_over: bool = False
+ only_best: bool | None = None
+
+ def __call__(self) -> _Transformer:
+ """
+ Returns
+ -------
+ _Transformer
+ """
+ return _Transformer.from_crs(
+ self.crs_from,
+ self.crs_to,
+ always_xy=self.always_xy,
+ area_of_interest=self.area_of_interest,
+ authority=self.authority,
+ accuracy=self.accuracy,
+ allow_ballpark=self.allow_ballpark,
+ force_over=self.force_over,
+ only_best=self.only_best,
+ )
+
+
+@dataclass(frozen=True)
+class TransformerFromPipeline(TransformerMaker):
+ """
+ .. versionadded:: 3.1.0
+
+ Generates a Cython _Transformer class from input pipeline data.
+ """
+
+ proj_pipeline: bytes
+
+ def __call__(self) -> _Transformer:
+ """
+ Returns
+ -------
+ _Transformer
+ """
+ return _Transformer.from_pipeline(self.proj_pipeline)
+
+
+
+[docs]
+class TransformerGroup(_TransformerGroup):
+ """
+ The TransformerGroup is a set of possible transformers from one CRS to another.
+
+ .. versionadded:: 2.3.0
+
+ .. warning:: CoordinateOperation and Transformer objects
+ returned are not thread-safe.
+
+ From PROJ docs::
+
+ The operations are sorted with the most relevant ones first: by
+ descending area (intersection of the transformation area with the
+ area of interest, or intersection of the transformation with the
+ area of use of the CRS), and by increasing accuracy. Operations
+ with unknown accuracy are sorted last, whatever their area.
+
+ """
+
+
+[docs]
+ def __init__(
+ self,
+ crs_from: Any,
+ crs_to: Any,
+ always_xy: bool = False,
+ area_of_interest: AreaOfInterest | None = None,
+ authority: str | None = None,
+ accuracy: float | None = None,
+ allow_ballpark: bool = True,
+ allow_superseded: bool = False,
+ ) -> None:
+ """Get all possible transformations from a :obj:`pyproj.crs.CRS`
+ or input used to create one.
+
+ .. versionadded:: 3.4.0 authority, accuracy, allow_ballpark
+ .. versionadded:: 3.6.0 allow_superseded
+
+ Parameters
+ ----------
+ crs_from: pyproj.crs.CRS or input used to create one
+ Projection of input data.
+ crs_to: pyproj.crs.CRS or input used to create one
+ Projection of output data.
+ always_xy: bool, default=False
+ If true, the transform method will accept as input and return as output
+ coordinates using the traditional GIS order, that is longitude, latitude
+ for geographic CRS and easting, northing for most projected CRS.
+ area_of_interest: :class:`.AreaOfInterest`, optional
+ The area of interest to help order the transformations based on the
+ best operation for the area.
+ authority: str, optional
+ When not specified, coordinate operations from any authority will be
+ searched, with the restrictions set in the
+ authority_to_authority_preference database table related to the
+ authority of the source/target CRS themselves. If authority is set
+ to “any”, then coordinate operations from any authority will be
+ searched. If authority is a non-empty string different from "any",
+ then coordinate operations will be searched only in that authority
+ namespace (e.g. EPSG).
+ accuracy: float, optional
+ The minimum desired accuracy (in metres) of the candidate
+ coordinate operations.
+ allow_ballpark: bool, default=True
+ Set to False to disallow the use of Ballpark transformation
+ in the candidate coordinate operations. Default is to allow.
+ allow_superseded: bool, default=False
+ Set to True to allow the use of superseded (but not deprecated)
+ transformations in the candidate coordinate operations. Default is
+ to disallow.
+
+ """
+ super().__init__(
+ CRS.from_user_input(crs_from)._crs,
+ CRS.from_user_input(crs_to)._crs,
+ always_xy=always_xy,
+ area_of_interest=area_of_interest,
+ authority=authority,
+ accuracy=-1 if accuracy is None else accuracy,
+ allow_ballpark=allow_ballpark,
+ allow_superseded=allow_superseded,
+ )
+ for iii, transformer in enumerate(self._transformers):
+ # pylint: disable=unsupported-assignment-operation
+ self._transformers[iii] = Transformer(TransformerUnsafe(transformer))
+
+
+ @property
+ def transformers(self) -> list["Transformer"]:
+ """
+ list[:obj:`Transformer`]:
+ List of available :obj:`Transformer`
+ associated with the transformation.
+ """
+ return self._transformers
+
+ @property
+ def unavailable_operations(self) -> list[CoordinateOperation]:
+ """
+ list[:obj:`pyproj.crs.CoordinateOperation`]:
+ List of :obj:`pyproj.crs.CoordinateOperation` that are not
+ available due to missing grids.
+ """
+ return self._unavailable_operations
+
+ @property
+ def best_available(self) -> bool:
+ """
+ bool: If True, the best possible transformer is available.
+ """
+ return self._best_available
+
+
+[docs]
+ def download_grids(
+ self,
+ directory: str | Path | None = None,
+ open_license: bool = True,
+ verbose: bool = False,
+ ) -> None:
+ """
+ .. versionadded:: 3.0.0
+
+ Download missing grids that can be downloaded automatically.
+
+ .. warning:: There are cases where the URL to download the grid is missing.
+ In those cases, you can enable enable
+ :ref:`debugging-internal-proj` and perform a
+ transformation. The logs will show the grids PROJ searches for.
+
+ Parameters
+ ----------
+ directory: str or Path, optional
+ The directory to download the grids to.
+ Defaults to :func:`pyproj.datadir.get_user_data_dir`
+ open_license: bool, default=True
+ If True, will only download grids with an open license.
+ verbose: bool, default=False
+ If True, will print information about grids downloaded.
+ """
+ if directory is None:
+ directory = get_user_data_dir(True)
+ # pylint: disable=not-an-iterable
+ for unavailable_operation in self.unavailable_operations:
+ for grid in unavailable_operation.grids:
+ if (
+ not grid.available
+ and grid.url.endswith(grid.short_name)
+ and grid.direct_download
+ and (grid.open_license or not open_license)
+ ):
+ _download_resource_file(
+ file_url=grid.url,
+ short_name=grid.short_name,
+ directory=directory,
+ verbose=verbose,
+ )
+ elif not grid.available and verbose:
+ warnings.warn(f"Skipped: {grid}")
+
+
+ def __repr__(self) -> str:
+ return (
+ f"<TransformerGroup: best_available={self.best_available}>\n"
+ f"- transformers: {len(self.transformers)}\n"
+ f"- unavailable_operations: {len(self.unavailable_operations)}"
+ )
+
+
+
+class TransformerLocal(threading.local):
+ """
+ Threading local instance for cython _Transformer class.
+
+ For more details, see:
+ https://github.com/pyproj4/pyproj/issues/782
+ """
+
+ def __init__(self):
+ self.transformer = None # Initialises in each thread
+ super().__init__()
+
+
+
+[docs]
+class Transformer:
+ """
+ The Transformer class is for facilitating re-using
+ transforms without needing to re-create them. The goal
+ is to make repeated transforms faster.
+
+ Additionally, it provides multiple methods for initialization.
+
+ .. versionadded:: 2.1.0
+
+ """
+
+ def __init__(
+ self,
+ transformer_maker: TransformerMaker | None = None,
+ ) -> None:
+ if not isinstance(transformer_maker, TransformerMaker):
+ _clear_proj_error()
+ raise ProjError(
+ "Transformer must be initialized using: "
+ "'from_crs' or 'from_pipeline'."
+ )
+
+ self._local = TransformerLocal()
+ self._local.transformer = transformer_maker()
+ self._transformer_maker = transformer_maker
+
+ def __getstate__(self) -> dict[str, Any]:
+ return {"_transformer_maker": self._transformer_maker}
+
+ def __setstate__(self, state: dict[str, Any]):
+ self.__dict__.update(state)
+ self._local = TransformerLocal()
+ self._local.transformer = self._transformer_maker()
+
+ @property
+ def _transformer(self):
+ """
+ The Cython _Transformer object for this thread.
+
+ Returns
+ -------
+ _Transformer
+ """
+ if self._local.transformer is None:
+ self._local.transformer = self._transformer_maker()
+ return self._local.transformer
+
+ @property
+ def name(self) -> str:
+ """
+ str: Name of the projection.
+ """
+ return self._transformer.id
+
+ @property
+ def description(self) -> str:
+ """
+ str: Description of the projection.
+ """
+ return self._transformer.description
+
+ @property
+ def definition(self) -> str:
+ """
+ str: Definition of the projection.
+ """
+ return self._transformer.definition
+
+ @property
+ def has_inverse(self) -> bool:
+ """
+ bool: True if an inverse mapping exists.
+ """
+ return self._transformer.has_inverse
+
+ @property
+ def accuracy(self) -> float:
+ """
+ float: Expected accuracy of the transformation. -1 if unknown.
+ """
+ return self._transformer.accuracy
+
+ @property
+ def area_of_use(self) -> AreaOfUse:
+ """
+ .. versionadded:: 2.3.0
+
+ Returns
+ -------
+ AreaOfUse:
+ The area of use object with associated attributes.
+ """
+ return self._transformer.area_of_use
+
+ @property
+ def remarks(self) -> str:
+ """
+ .. versionadded:: 2.4.0
+
+ Returns
+ -------
+ str:
+ Remarks about object.
+ """
+ return self._transformer.remarks
+
+ @property
+ def scope(self) -> str:
+ """
+ .. versionadded:: 2.4.0
+
+ Returns
+ -------
+ str:
+ Scope of object.
+ """
+ return self._transformer.scope
+
+ @property
+ def operations(self) -> tuple[CoordinateOperation] | None:
+ """
+ .. versionadded:: 2.4.0
+
+ Returns
+ -------
+ tuple[CoordinateOperation]:
+ The operations in a concatenated operation.
+ """
+ return self._transformer.operations
+
+
+[docs]
+ def get_last_used_operation(self) -> "Transformer":
+ """
+ .. versionadded:: 3.4.0
+
+ .. note:: Requires PROJ 9.1+
+
+ See: :c:func:`proj_trans_get_last_used_operation`
+
+ Returns
+ -------
+ Transformer:
+ The operation used in the transform call.
+ """
+ return Transformer(
+ TransformerUnsafe(self._transformer.get_last_used_operation())
+ )
+
+
+ @property
+ def is_network_enabled(self) -> bool:
+ """
+ .. versionadded:: 3.0.0
+
+ Returns
+ -------
+ bool:
+ If the network is enabled.
+ """
+ return self._transformer.is_network_enabled
+
+ @property
+ def source_crs(self) -> CRS | None:
+ """
+ .. versionadded:: 3.3.0
+
+ Returns
+ -------
+ CRS | None:
+ The source CRS of a CoordinateOperation.
+ """
+ return (
+ None
+ if self._transformer.source_crs is None
+ else CRS(self._transformer.source_crs)
+ )
+
+ @property
+ def target_crs(self) -> CRS | None:
+ """
+ .. versionadded:: 3.3.0
+
+ Returns
+ -------
+ CRS | None:
+ The target CRS of a CoordinateOperation.
+ """
+ return (
+ None
+ if self._transformer.target_crs is None
+ else CRS(self._transformer.target_crs)
+ )
+
+
+[docs]
+ @staticmethod
+ def from_proj(
+ proj_from: Any,
+ proj_to: Any,
+ always_xy: bool = False,
+ area_of_interest: AreaOfInterest | None = None,
+ ) -> "Transformer":
+ """Make a Transformer from a :obj:`pyproj.Proj` or input used to create one.
+
+ .. deprecated:: 3.4.1 :meth:`~Transformer.from_crs` is preferred.
+
+ .. versionadded:: 2.2.0 always_xy
+ .. versionadded:: 2.3.0 area_of_interest
+
+ Parameters
+ ----------
+ proj_from: :obj:`pyproj.Proj` or input used to create one
+ Projection of input data.
+ proj_to: :obj:`pyproj.Proj` or input used to create one
+ Projection of output data.
+ always_xy: bool, default=False
+ If true, the transform method will accept as input and return as output
+ coordinates using the traditional GIS order, that is longitude, latitude
+ for geographic CRS and easting, northing for most projected CRS.
+ area_of_interest: :class:`.AreaOfInterest`, optional
+ The area of interest to help select the transformation.
+
+ Returns
+ -------
+ Transformer
+
+ """
+ # pylint: disable=import-outside-toplevel
+ from pyproj import Proj
+
+ if not isinstance(proj_from, Proj):
+ proj_from = Proj(proj_from)
+ if not isinstance(proj_to, Proj):
+ proj_to = Proj(proj_to)
+
+ return Transformer.from_crs(
+ proj_from.crs,
+ proj_to.crs,
+ always_xy=always_xy,
+ area_of_interest=area_of_interest,
+ )
+
+
+
+[docs]
+ @staticmethod
+ def from_crs(
+ crs_from: Any,
+ crs_to: Any,
+ always_xy: bool = False,
+ area_of_interest: AreaOfInterest | None = None,
+ authority: str | None = None,
+ accuracy: float | None = None,
+ allow_ballpark: bool | None = None,
+ force_over: bool = False,
+ only_best: bool | None = None,
+ ) -> "Transformer":
+ """Make a Transformer from a :obj:`pyproj.crs.CRS` or input used to create one.
+
+ See:
+
+ - :c:func:`proj_create_crs_to_crs`
+ - :c:func:`proj_create_crs_to_crs_from_pj`
+
+ .. versionadded:: 2.2.0 always_xy
+ .. versionadded:: 2.3.0 area_of_interest
+ .. versionadded:: 3.1.0 authority, accuracy, allow_ballpark
+ .. versionadded:: 3.4.0 force_over
+ .. versionadded:: 3.5.0 only_best
+
+ Parameters
+ ----------
+ crs_from: pyproj.crs.CRS or input used to create one
+ Projection of input data.
+ crs_to: pyproj.crs.CRS or input used to create one
+ Projection of output data.
+ always_xy: bool, default=False
+ If true, the transform method will accept as input and return as output
+ coordinates using the traditional GIS order, that is longitude, latitude
+ for geographic CRS and easting, northing for most projected CRS.
+ area_of_interest: :class:`.AreaOfInterest`, optional
+ The area of interest to help select the transformation.
+ authority: str, optional
+ When not specified, coordinate operations from any authority will be
+ searched, with the restrictions set in the
+ authority_to_authority_preference database table related to the
+ authority of the source/target CRS themselves. If authority is set
+ to “any”, then coordinate operations from any authority will be
+ searched. If authority is a non-empty string different from "any",
+ then coordinate operations will be searched only in that authority
+ namespace (e.g. EPSG).
+ accuracy: float, optional
+ The minimum desired accuracy (in metres) of the candidate
+ coordinate operations.
+ allow_ballpark: bool, optional
+ Set to False to disallow the use of Ballpark transformation
+ in the candidate coordinate operations. Default is to allow.
+ force_over: bool, default=False
+ If True, it will to force the +over flag on the transformation.
+ Requires PROJ 9+.
+ only_best: bool, optional
+ Can be set to True to cause PROJ to error out if the best
+ transformation known to PROJ and usable by PROJ if all grids known and
+ usable by PROJ were accessible, cannot be used. Best transformation should
+ be understood as the transformation returned by
+ :c:func:`proj_get_suggested_operation` if all known grids were
+ accessible (either locally or through network).
+ Note that the default value for this option can be also set with the
+ :envvar:`PROJ_ONLY_BEST_DEFAULT` environment variable, or with the
+ ``only_best_default`` setting of :ref:`proj-ini`.
+ The only_best kwarg overrides the default value if set.
+ Requires PROJ 9.2+.
+
+ Returns
+ -------
+ Transformer
+
+ """
+ return Transformer(
+ TransformerFromCRS(
+ cstrencode(CRS.from_user_input(crs_from).srs),
+ cstrencode(CRS.from_user_input(crs_to).srs),
+ always_xy=always_xy,
+ area_of_interest=area_of_interest,
+ authority=authority,
+ accuracy=accuracy if accuracy is None else str(accuracy),
+ allow_ballpark=allow_ballpark,
+ force_over=force_over,
+ only_best=only_best,
+ )
+ )
+
+
+
+[docs]
+ @staticmethod
+ def from_pipeline(proj_pipeline: str) -> "Transformer":
+ """Make a Transformer from a PROJ pipeline string.
+
+ :ref:`pipeline`
+
+ See:
+
+ - :c:func:`proj_create`
+ - :c:func:`proj_create_from_database`
+
+ .. versionadded:: 3.1.0 AUTH:CODE string support (e.g. EPSG:1671)
+
+ Allowed input:
+ - a PROJ string
+ - a WKT string
+ - a PROJJSON string
+ - an object code (e.g. "EPSG:1671"
+ "urn:ogc:def:coordinateOperation:EPSG::1671")
+ - an object name. e.g "ITRF2014 to ETRF2014 (1)".
+ In that case as uniqueness is not guaranteed,
+ heuristics are applied to determine the appropriate best match.
+ - a OGC URN combining references for concatenated operations
+ (e.g. "urn:ogc:def:coordinateOperation,coordinateOperation:EPSG::3895,
+ coordinateOperation:EPSG::1618")
+
+ Parameters
+ ----------
+ proj_pipeline: str
+ Projection pipeline string.
+
+ Returns
+ -------
+ Transformer
+
+ """
+ return Transformer(TransformerFromPipeline(cstrencode(proj_pipeline)))
+
+
+ @overload
+ def transform( # noqa: E704 pylint: disable=invalid-name
+ self,
+ xx: Any,
+ yy: Any,
+ radians: bool = False,
+ errcheck: bool = False,
+ direction: TransformDirection | str = TransformDirection.FORWARD,
+ inplace: bool = False,
+ ) -> tuple[Any, Any]: ...
+
+ @overload
+ def transform( # noqa: E704 pylint: disable=invalid-name
+ self,
+ xx: Any,
+ yy: Any,
+ zz: Any,
+ radians: bool = False,
+ errcheck: bool = False,
+ direction: TransformDirection | str = TransformDirection.FORWARD,
+ inplace: bool = False,
+ ) -> tuple[Any, Any, Any]: ...
+
+ @overload
+ def transform( # noqa: E704 pylint: disable=invalid-name
+ self,
+ xx: Any,
+ yy: Any,
+ zz: Any,
+ tt: Any,
+ radians: bool = False,
+ errcheck: bool = False,
+ direction: TransformDirection | str = TransformDirection.FORWARD,
+ inplace: bool = False,
+ ) -> tuple[Any, Any, Any, Any]: ...
+
+
+[docs]
+ def transform( # pylint: disable=invalid-name
+ self,
+ xx,
+ yy,
+ zz=None,
+ tt=None,
+ radians=False,
+ errcheck=False,
+ direction=TransformDirection.FORWARD,
+ inplace=False,
+ ):
+ """
+ Transform points between two coordinate systems.
+
+ See: :c:func:`proj_trans_generic`
+
+ .. versionadded:: 2.1.1 errcheck
+ .. versionadded:: 2.2.0 direction
+ .. versionadded:: 3.2.0 inplace
+
+ Accepted numeric scalar or array:
+
+ - :class:`int`
+ - :class:`float`
+ - :class:`numpy.floating`
+ - :class:`numpy.integer`
+ - :class:`list`
+ - :class:`tuple`
+ - :class:`array.array`
+ - :class:`numpy.ndarray`
+ - :class:`xarray.DataArray`
+ - :class:`pandas.Series`
+
+ Parameters
+ ----------
+ xx: scalar or array
+ Input x coordinate(s).
+ yy: scalar or array
+ Input y coordinate(s).
+ zz: scalar or array, optional
+ Input z coordinate(s).
+ tt: scalar or array, optional
+ Input time coordinate(s).
+ radians: bool, default=False
+ If True, will expect input data to be in radians and will return radians
+ if the projection is geographic. Otherwise, it uses degrees.
+ Ignored for pipeline transformations with pyproj 2,
+ but will work in pyproj 3.
+ errcheck: bool, default=False
+ If True, an exception is raised if the errors are found in the process.
+ If False, ``inf`` is returned for errors.
+ direction: pyproj.enums.TransformDirection, optional
+ The direction of the transform.
+ Default is :attr:`pyproj.enums.TransformDirection.FORWARD`.
+ inplace: bool, default=False
+ If True, will attempt to write the results to the input array
+ instead of returning a new array. This will fail if the input
+ is not an array in C order with the double data type.
+
+ Example
+ --------
+
+ >>> from pyproj import Transformer
+ >>> transformer = Transformer.from_crs("EPSG:4326", "EPSG:3857")
+ >>> x3, y3 = transformer.transform(33, 98)
+ >>> f"{x3:.3f} {y3:.3f}"
+ '10909310.098 3895303.963'
+ >>> pipeline_str = (
+ ... "+proj=pipeline +step +proj=longlat +ellps=WGS84 "
+ ... "+step +proj=unitconvert +xy_in=rad +xy_out=deg"
+ ... )
+ >>> pipe_trans = Transformer.from_pipeline(pipeline_str)
+ >>> xt, yt = pipe_trans.transform(2.1, 0.001)
+ >>> f"{xt:.3f} {yt:.3f}"
+ '2.100 0.001'
+ >>> transproj = Transformer.from_crs(
+ ... {"proj":'geocent', "ellps":'WGS84', "datum":'WGS84'},
+ ... "EPSG:4326",
+ ... always_xy=True,
+ ... )
+ >>> xpj, ypj, zpj = transproj.transform(
+ ... -2704026.010,
+ ... -4253051.810,
+ ... 3895878.820,
+ ... radians=True,
+ ... )
+ >>> f"{xpj:.3f} {ypj:.3f} {zpj:.3f}"
+ '-2.137 0.661 -20.531'
+ >>> transprojr = Transformer.from_crs(
+ ... "EPSG:4326",
+ ... {"proj":'geocent', "ellps":'WGS84', "datum":'WGS84'},
+ ... always_xy=True,
+ ... )
+ >>> xpjr, ypjr, zpjr = transprojr.transform(xpj, ypj, zpj, radians=True)
+ >>> f"{xpjr:.3f} {ypjr:.3f} {zpjr:.3f}"
+ '-2704026.010 -4253051.810 3895878.820'
+ >>> transformer = Transformer.from_crs("EPSG:4326", 4326)
+ >>> xeq, yeq = transformer.transform(33, 98)
+ >>> f"{xeq:.0f} {yeq:.0f}"
+ '33 98'
+
+ """
+ try:
+ # function optimized for point data
+ return self._transformer._transform_point(
+ inx=xx,
+ iny=yy,
+ inz=zz,
+ intime=tt,
+ direction=direction,
+ radians=radians,
+ errcheck=errcheck,
+ )
+ except TypeError:
+ pass
+ # process inputs, making copies that support buffer API.
+ inx, x_data_type = _copytobuffer(xx, inplace=inplace)
+ iny, y_data_type = _copytobuffer(yy, inplace=inplace)
+ if zz is not None:
+ inz, z_data_type = _copytobuffer(zz, inplace=inplace)
+ else:
+ inz = None
+ if tt is not None:
+ intime, t_data_type = _copytobuffer(tt, inplace=inplace)
+ else:
+ intime = None
+ # call pj_transform. inx,iny,inz buffers modified in place.
+ self._transformer._transform(
+ inx=inx,
+ iny=iny,
+ inz=inz,
+ intime=intime,
+ direction=direction,
+ radians=radians,
+ errcheck=errcheck,
+ )
+ # if inputs were lists, tuples or floats, convert back.
+ outx = _convertback(x_data_type, inx)
+ outy = _convertback(y_data_type, iny)
+ return_data: tuple[Any, ...] = (outx, outy)
+ if zz is not None:
+ return_data += (_convertback(z_data_type, inz),)
+ if tt is not None:
+ return_data += (_convertback(t_data_type, intime),)
+ return return_data
+
+
+
+[docs]
+ def itransform(
+ self,
+ points: Any,
+ switch: bool = False,
+ time_3rd: bool = False,
+ radians: bool = False,
+ errcheck: bool = False,
+ direction: TransformDirection | str = TransformDirection.FORWARD,
+ ) -> Iterator[Iterable]:
+ """
+ Iterator/generator version of the function pyproj.Transformer.transform.
+
+ See: :c:func:`proj_trans_generic`
+
+ .. versionadded:: 2.1.1 errcheck
+ .. versionadded:: 2.2.0 direction
+
+ Parameters
+ ----------
+ points: list
+ List of point tuples.
+ switch: bool, default=False
+ If True x, y or lon,lat coordinates of points are switched to y, x
+ or lat, lon. Default is False.
+ time_3rd: bool, default=False
+ If the input coordinates are 3 dimensional and the 3rd dimension is time.
+ radians: bool, default=False
+ If True, will expect input data to be in radians and will return radians
+ if the projection is geographic. Otherwise, it uses degrees.
+ Ignored for pipeline transformations with pyproj 2,
+ but will work in pyproj 3.
+ errcheck: bool, default=False
+ If True, an exception is raised if the errors are found in the process.
+ If False, ``inf`` is returned for errors.
+ direction: pyproj.enums.TransformDirection, optional
+ The direction of the transform.
+ Default is :attr:`pyproj.enums.TransformDirection.FORWARD`.
+
+
+ Example
+ --------
+
+ >>> from pyproj import Transformer
+ >>> transformer = Transformer.from_crs(4326, 2100)
+ >>> points = [(22.95, 40.63), (22.81, 40.53), (23.51, 40.86)]
+ >>> for pt in transformer.itransform(points): '{:.3f} {:.3f}'.format(*pt)
+ '2221638.801 2637034.372'
+ '2212924.125 2619851.898'
+ '2238294.779 2703763.736'
+ >>> pipeline_str = (
+ ... "+proj=pipeline +step +proj=longlat +ellps=WGS84 "
+ ... "+step +proj=unitconvert +xy_in=rad +xy_out=deg"
+ ... )
+ >>> pipe_trans = Transformer.from_pipeline(pipeline_str)
+ >>> for pt in pipe_trans.itransform([(2.1, 0.001)]):
+ ... '{:.3f} {:.3f}'.format(*pt)
+ '2.100 0.001'
+ >>> transproj = Transformer.from_crs(
+ ... {"proj":'geocent', "ellps":'WGS84', "datum":'WGS84'},
+ ... "EPSG:4326",
+ ... always_xy=True,
+ ... )
+ >>> for pt in transproj.itransform(
+ ... [(-2704026.010, -4253051.810, 3895878.820)],
+ ... radians=True,
+ ... ):
+ ... '{:.3f} {:.3f} {:.3f}'.format(*pt)
+ '-2.137 0.661 -20.531'
+ >>> transprojr = Transformer.from_crs(
+ ... "EPSG:4326",
+ ... {"proj":'geocent', "ellps":'WGS84', "datum":'WGS84'},
+ ... always_xy=True,
+ ... )
+ >>> for pt in transprojr.itransform(
+ ... [(-2.137, 0.661, -20.531)],
+ ... radians=True
+ ... ):
+ ... '{:.3f} {:.3f} {:.3f}'.format(*pt)
+ '-2704214.394 -4254414.478 3894270.731'
+ >>> transproj_eq = Transformer.from_crs(
+ ... 'EPSG:4326',
+ ... '+proj=longlat +datum=WGS84 +no_defs +type=crs',
+ ... always_xy=True,
+ ... )
+ >>> for pt in transproj_eq.itransform([(-2.137, 0.661)]):
+ ... '{:.3f} {:.3f}'.format(*pt)
+ '-2.137 0.661'
+
+ """
+ point_it = iter(points) # point iterator
+ # get first point to check stride
+ try:
+ fst_pt = next(point_it)
+ except StopIteration:
+ raise ValueError("iterable must contain at least one point") from None
+
+ stride = len(fst_pt)
+ if stride not in (2, 3, 4):
+ raise ValueError("points can contain up to 4 coordinates")
+
+ if time_3rd and stride != 3:
+ raise ValueError("'time_3rd' is only valid for 3 coordinates.")
+
+ # create a coordinate sequence generator etc. x1,y1,z1,x2,y2,z2,....
+ # chain so the generator returns the first point that was already acquired
+ coord_gen = chain(
+ fst_pt, (coords[c] for coords in point_it for c in range(stride))
+ )
+
+ while True:
+ # create a temporary buffer storage for
+ # the next 64 points (64*stride*8 bytes)
+ buff = array("d", islice(coord_gen, 0, 64 * stride))
+ if len(buff) == 0:
+ break
+
+ self._transformer._transform_sequence(
+ stride,
+ buff,
+ switch=switch,
+ direction=direction,
+ time_3rd=time_3rd,
+ radians=radians,
+ errcheck=errcheck,
+ )
+
+ yield from zip(*([iter(buff)] * stride))
+
+
+
+[docs]
+ def transform_bounds(
+ self,
+ left: float,
+ bottom: float,
+ right: float,
+ top: float,
+ densify_pts: int = 21,
+ radians: bool = False,
+ errcheck: bool = False,
+ direction: TransformDirection | str = TransformDirection.FORWARD,
+ ) -> tuple[float, float, float, float]:
+ """
+ .. versionadded:: 3.1.0
+
+ See: :c:func:`proj_trans_bounds`
+
+ Transform boundary densifying the edges to account for nonlinear
+ transformations along these edges and extracting the outermost bounds.
+
+ If the destination CRS is geographic and right < left then the bounds
+ crossed the antimeridian. In this scenario there are two polygons,
+ one on each side of the antimeridian. The first polygon should be
+ constructed with (left, bottom, 180, top) and the second with
+ (-180, bottom, top, right).
+
+ To construct the bounding polygons with shapely::
+
+ def bounding_polygon(left, bottom, right, top):
+ if right < left:
+ return shapely.geometry.MultiPolygon(
+ [
+ shapely.geometry.box(left, bottom, 180, top),
+ shapely.geometry.box(-180, bottom, right, top),
+ ]
+ )
+ return shapely.geometry.box(left, bottom, right, top)
+
+
+ Parameters
+ ----------
+ left: float
+ Minimum bounding coordinate of the first axis in source CRS
+ (or the target CRS if using the reverse direction).
+ bottom: float
+ Minimum bounding coordinate of the second axis in source CRS.
+ (or the target CRS if using the reverse direction).
+ right: float
+ Maximum bounding coordinate of the first axis in source CRS.
+ (or the target CRS if using the reverse direction).
+ top: float
+ Maximum bounding coordinate of the second axis in source CRS.
+ (or the target CRS if using the reverse direction).
+ densify_points: uint, default=21
+ Number of points to add to each edge to account for nonlinear edges
+ produced by the transform process. Large numbers will produce worse
+ performance.
+ radians: bool, default=False
+ If True, will expect input data to be in radians and will return radians
+ if the projection is geographic. Otherwise, it uses degrees.
+ errcheck: bool, default=False
+ If True, an exception is raised if the errors are found in the process.
+ If False, ``inf`` is returned for errors.
+ direction: pyproj.enums.TransformDirection, optional
+ The direction of the transform.
+ Default is :attr:`pyproj.enums.TransformDirection.FORWARD`.
+
+ Returns
+ -------
+ left, bottom, right, top: float
+ Outermost coordinates in target coordinate reference system.
+ """
+ return self._transformer._transform_bounds(
+ left=left,
+ bottom=bottom,
+ right=right,
+ top=top,
+ densify_pts=densify_pts,
+ radians=radians,
+ errcheck=errcheck,
+ direction=direction,
+ )
+
+
+
+[docs]
+ def to_proj4(
+ self,
+ version: ProjVersion | str = ProjVersion.PROJ_5,
+ pretty: bool = False,
+ ) -> str:
+ """
+ Convert the projection to a PROJ string.
+
+ .. versionadded:: 3.1.0
+
+ Parameters
+ ----------
+ version: pyproj.enums.ProjVersion
+ The version of the PROJ string output.
+ Default is :attr:`pyproj.enums.ProjVersion.PROJ_5`.
+ pretty: bool, default=False
+ If True, it will set the output to be a multiline string.
+
+ Returns
+ -------
+ str:
+ The PROJ string.
+
+ """
+ return self._transformer.to_proj4(version=version, pretty=pretty)
+
+
+
+[docs]
+ def to_wkt(
+ self,
+ version: WktVersion | str = WktVersion.WKT2_2019,
+ pretty: bool = False,
+ ) -> str:
+ """
+ Convert the projection to a WKT string.
+
+ Version options:
+ - WKT2_2015
+ - WKT2_2015_SIMPLIFIED
+ - WKT2_2019
+ - WKT2_2019_SIMPLIFIED
+ - WKT1_GDAL
+ - WKT1_ESRI
+
+
+ Parameters
+ ----------
+ version: pyproj.enums.WktVersion, optional
+ The version of the WKT output.
+ Default is :attr:`pyproj.enums.WktVersion.WKT2_2019`.
+ pretty: bool, default=False
+ If True, it will set the output to be a multiline string.
+
+ Returns
+ -------
+ str:
+ The WKT string.
+ """
+ return self._transformer.to_wkt(version=version, pretty=pretty)
+
+
+
+[docs]
+ def to_json(self, pretty: bool = False, indentation: int = 2) -> str:
+ """
+ Convert the projection to a JSON string.
+
+ .. versionadded:: 2.4.0
+
+ Parameters
+ ----------
+ pretty: bool, default=False
+ If True, it will set the output to be a multiline string.
+ indentation: int, default=2
+ If pretty is True, it will set the width of the indentation.
+
+ Returns
+ -------
+ str:
+ The JSON string.
+ """
+ return self._transformer.to_json(pretty=pretty, indentation=indentation)
+
+
+
+[docs]
+ def to_json_dict(self) -> dict:
+ """
+ Convert the projection to a JSON dictionary.
+
+ .. versionadded:: 2.4.0
+
+ Returns
+ -------
+ dict:
+ The JSON dictionary.
+ """
+ return self._transformer.to_json_dict()
+
+
+ def __str__(self) -> str:
+ return self.definition
+
+ def __repr__(self) -> str:
+ return (
+ f"<{self._transformer.type_name}: {self.name}>\n"
+ f"Description: {self.description}\n"
+ f"Area of Use:\n{self.area_of_use or '- undefined'}"
+ )
+
+ def __eq__(self, other: Any) -> bool:
+ if not isinstance(other, Transformer):
+ return False
+ return self._transformer.__eq__(other._transformer)
+
+
+[docs]
+ def is_exact_same(self, other: Any) -> bool:
+ """
+ Check if the Transformer objects are the exact same.
+ If it is not a Transformer, then it returns False.
+
+ Parameters
+ ----------
+ other: Any
+
+ Returns
+ -------
+ bool
+ """
+ if not isinstance(other, Transformer):
+ return False
+ return self._transformer.is_exact_same(other._transformer)
+
+
+
+
+
+[docs]
+def transform( # pylint: disable=invalid-name
+ p1: Any,
+ p2: Any,
+ x: Any,
+ y: Any,
+ z: Any | None = None,
+ tt: Any | None = None,
+ radians: bool = False,
+ errcheck: bool = False,
+ always_xy: bool = False,
+):
+ """
+ .. versionadded:: 2.2.0 always_xy
+
+ .. deprecated:: 2.6.1
+ This function is deprecated. See: :ref:`upgrade_transformer`
+
+ x2, y2, z2 = transform(p1, p2, x1, y1, z1)
+
+ Transform points between two coordinate systems defined by the
+ Proj instances p1 and p2.
+
+ The points x1,y1,z1 in the coordinate system defined by p1 are
+ transformed to x2,y2,z2 in the coordinate system defined by p2.
+
+ z1 is optional, if it is not set it is assumed to be zero (and
+ only x2 and y2 are returned). If the optional keyword
+ 'radians' is True (default is False), then all input and
+ output coordinates will be in radians instead of the default
+ of degrees for geographic input/output projections.
+ If the optional keyword 'errcheck' is set to True an
+ exception is raised if the transformation is
+ invalid. By default errcheck=False and ``inf`` is returned for an
+ invalid transformation (and no exception is raised).
+ If `always_xy` is toggled, the transform method will accept as
+ input and return as output coordinates using the traditional GIS order,
+ that is longitude, latitude for geographic CRS and easting,
+ northing for most projected CRS.
+
+ In addition to converting between cartographic and geographic
+ projection coordinates, this function can take care of datum
+ shifts (which cannot be done using the __call__ method of the
+ Proj instances). It also allows for one of the coordinate
+ systems to be geographic (proj = 'latlong').
+
+ x,y and z can be numpy or regular python arrays, python
+ lists/tuples or scalars. Arrays are fastest. For projections in
+ geocentric coordinates, values of x and y are given in meters.
+ z is always meters.
+
+ """
+ warnings.warn(
+ (
+ "This function is deprecated. "
+ "See: https://pyproj4.github.io/pyproj/stable/"
+ "gotchas.html#upgrading-to-pyproj-2-from-pyproj-1"
+ ),
+ FutureWarning,
+ stacklevel=2,
+ )
+ return Transformer.from_proj(p1, p2, always_xy=always_xy).transform(
+ xx=x, yy=y, zz=z, tt=tt, radians=radians, errcheck=errcheck
+ )
+
+
+
+
+[docs]
+def itransform( # pylint: disable=invalid-name
+ p1: Any,
+ p2: Any,
+ points: Iterable[Iterable],
+ switch: bool = False,
+ time_3rd: bool = False,
+ radians: bool = False,
+ errcheck: bool = False,
+ always_xy: bool = False,
+):
+ """
+ .. versionadded:: 2.2.0 always_xy
+
+ .. deprecated:: 2.6.1
+ This function is deprecated. See: :ref:`upgrade_transformer`
+
+ points2 = itransform(p1, p2, points1)
+ Iterator/generator version of the function pyproj.transform.
+ Transform points between two coordinate systems defined by the
+ Proj instances p1 and p2. This function can be used as an alternative
+ to pyproj.transform when there is a need to transform a big number of
+ coordinates lazily, for example when reading and processing from a file.
+ Points1 is an iterable/generator of coordinates x1,y1(,z1) or lon1,lat1(,z1)
+ in the coordinate system defined by p1. Points2 is an iterator that returns tuples
+ of x2,y2(,z2) or lon2,lat2(,z2) coordinates in the coordinate system defined by p2.
+ z are provided optionally.
+
+ Points1 can be:
+ - a tuple/list of tuples/lists i.e. for 2d points: [(xi,yi),(xj,yj),....(xn,yn)]
+ - a Nx3 or Nx2 2d numpy array where N is the point number
+ - a generator of coordinates (xi,yi) for 2d points or (xi,yi,zi) for 3d
+
+ If optional keyword 'switch' is True (default is False) then x, y or lon,lat
+ coordinates of points are switched to y, x or lat, lon.
+ If the optional keyword 'radians' is True (default is False),
+ then all input and output coordinates will be in radians instead
+ of the default of degrees for geographic input/output projections.
+ If the optional keyword 'errcheck' is set to True an
+ exception is raised if the transformation is
+ invalid. By default errcheck=False and ``inf`` is returned for an
+ invalid transformation (and no exception is raised).
+ If `always_xy` is toggled, the transform method will accept as
+ input and return as output coordinates using the traditional GIS order,
+ that is longitude, latitude for geographic CRS and easting, northing
+ for most projected CRS.
+
+
+ Example usage:
+
+ >>> from pyproj import Proj, itransform
+ >>> # projection 1: WGS84
+ >>> # (defined by epsg code 4326)
+ >>> p1 = Proj('epsg:4326', preserve_units=False)
+ >>> # projection 2: GGRS87 / Greek Grid
+ >>> p2 = Proj('epsg:2100', preserve_units=False)
+ >>> # Three points with coordinates lon, lat in p1
+ >>> points = [(22.95, 40.63), (22.81, 40.53), (23.51, 40.86)]
+ >>> # transform this point to projection 2 coordinates.
+ >>> for pt in itransform(p1,p2,points, always_xy=True): '%6.3f %7.3f' % pt
+ '411050.470 4497928.574'
+ '399060.236 4486978.710'
+ '458553.243 4523045.485'
+ >>> for pt in itransform(4326, 4326, [(30, 60)]):
+ ... '{:.0f} {:.0f}'.format(*pt)
+ '30 60'
+
+ """
+ warnings.warn(
+ (
+ "This function is deprecated. "
+ "See: https://pyproj4.github.io/pyproj/stable/"
+ "gotchas.html#upgrading-to-pyproj-2-from-pyproj-1"
+ ),
+ FutureWarning,
+ stacklevel=2,
+ )
+ return Transformer.from_proj(p1, p2, always_xy=always_xy).itransform(
+ points, switch=switch, time_3rd=time_3rd, radians=radians, errcheck=errcheck
+ )
+
+' + + '' + + _("Hide Search Matches") + + "
" + ) + ); + }, + + /** + * helper function to hide the search marks again + */ + hideSearchWords: () => { + document + .querySelectorAll("#searchbox .highlight-link") + .forEach((el) => el.remove()); + document + .querySelectorAll("span.highlighted") + .forEach((el) => el.classList.remove("highlighted")); + localStorage.removeItem("sphinx_highlight_terms") + }, + + initEscapeListener: () => { + // only install a listener if it is really needed + if (!DOCUMENTATION_OPTIONS.ENABLE_SEARCH_SHORTCUTS) return; + + document.addEventListener("keydown", (event) => { + // bail for input elements + if (BLACKLISTED_KEY_CONTROL_ELEMENTS.has(document.activeElement.tagName)) return; + // bail with special keys + if (event.shiftKey || event.altKey || event.ctrlKey || event.metaKey) return; + if (DOCUMENTATION_OPTIONS.ENABLE_SEARCH_SHORTCUTS && (event.key === "Escape")) { + SphinxHighlight.hideSearchWords(); + event.preventDefault(); + } + }); + }, +}; + +_ready(() => { + /* Do not call highlightSearchWords() when we are on the search page. + * It will highlight words from the *previous* search query. + */ + if (typeof Search === "undefined") SphinxHighlight.highlightSearchWords(); + SphinxHighlight.initEscapeListener(); +}); diff --git a/3.7.0/_static/styles/furo-extensions.css b/3.7.0/_static/styles/furo-extensions.css new file mode 100644 index 000000000..822958761 --- /dev/null +++ b/3.7.0/_static/styles/furo-extensions.css @@ -0,0 +1,2 @@ +#furo-sidebar-ad-placement{padding:var(--sidebar-item-spacing-vertical) var(--sidebar-item-spacing-horizontal)}#furo-sidebar-ad-placement .ethical-sidebar{background:var(--color-background-secondary);border:none;box-shadow:none}#furo-sidebar-ad-placement .ethical-sidebar:hover{background:var(--color-background-hover)}#furo-sidebar-ad-placement .ethical-sidebar a{color:var(--color-foreground-primary)}#furo-sidebar-ad-placement .ethical-callout a{color:var(--color-foreground-secondary)!important}#furo-readthedocs-versions{background:transparent;display:block;position:static;width:100%}#furo-readthedocs-versions .rst-versions{background:#1a1c1e}#furo-readthedocs-versions .rst-current-version{background:var(--color-sidebar-item-background);cursor:unset}#furo-readthedocs-versions .rst-current-version:hover{background:var(--color-sidebar-item-background)}#furo-readthedocs-versions .rst-current-version .fa-book{color:var(--color-foreground-primary)}#furo-readthedocs-versions>.rst-other-versions{padding:0}#furo-readthedocs-versions>.rst-other-versions small{opacity:1}#furo-readthedocs-versions .injected .rst-versions{position:unset}#furo-readthedocs-versions:focus-within,#furo-readthedocs-versions:hover{box-shadow:0 0 0 1px var(--color-sidebar-background-border)}#furo-readthedocs-versions:focus-within .rst-current-version,#furo-readthedocs-versions:hover .rst-current-version{background:#1a1c1e;font-size:inherit;height:auto;line-height:inherit;padding:12px;text-align:right}#furo-readthedocs-versions:focus-within .rst-current-version .fa-book,#furo-readthedocs-versions:hover .rst-current-version .fa-book{color:#fff;float:left}#furo-readthedocs-versions:focus-within .fa-caret-down,#furo-readthedocs-versions:hover .fa-caret-down{display:none}#furo-readthedocs-versions:focus-within .injected,#furo-readthedocs-versions:focus-within .rst-current-version,#furo-readthedocs-versions:focus-within .rst-other-versions,#furo-readthedocs-versions:hover .injected,#furo-readthedocs-versions:hover .rst-current-version,#furo-readthedocs-versions:hover .rst-other-versions{display:block}#furo-readthedocs-versions:focus-within>.rst-current-version,#furo-readthedocs-versions:hover>.rst-current-version{display:none}.highlight:hover button.copybtn{color:var(--color-code-foreground)}.highlight button.copybtn{align-items:center;background-color:var(--color-code-background);border:none;color:var(--color-background-item);cursor:pointer;height:1.25em;right:.5rem;top:.625rem;transition:color .3s,opacity .3s;width:1.25em}.highlight button.copybtn:hover{background-color:var(--color-code-background);color:var(--color-brand-content)}.highlight button.copybtn:after{background-color:transparent;color:var(--color-code-foreground);display:none}.highlight button.copybtn.success{color:#22863a;transition:color 0ms}.highlight button.copybtn.success:after{display:block}.highlight button.copybtn svg{padding:0}body{--sd-color-primary:var(--color-brand-primary);--sd-color-primary-highlight:var(--color-brand-content);--sd-color-primary-text:var(--color-background-primary);--sd-color-shadow:rgba(0,0,0,.05);--sd-color-card-border:var(--color-card-border);--sd-color-card-border-hover:var(--color-brand-content);--sd-color-card-background:var(--color-card-background);--sd-color-card-text:var(--color-foreground-primary);--sd-color-card-header:var(--color-card-marginals-background);--sd-color-card-footer:var(--color-card-marginals-background);--sd-color-tabs-label-active:var(--color-brand-content);--sd-color-tabs-label-hover:var(--color-foreground-muted);--sd-color-tabs-label-inactive:var(--color-foreground-muted);--sd-color-tabs-underline-active:var(--color-brand-content);--sd-color-tabs-underline-hover:var(--color-foreground-border);--sd-color-tabs-underline-inactive:var(--color-background-border);--sd-color-tabs-overline:var(--color-background-border);--sd-color-tabs-underline:var(--color-background-border)}.sd-tab-content{box-shadow:0 -2px var(--sd-color-tabs-overline),0 1px var(--sd-color-tabs-underline)}.sd-card{box-shadow:0 .1rem .25rem var(--sd-color-shadow),0 0 .0625rem rgba(0,0,0,.1)}.sd-shadow-sm{box-shadow:0 .1rem .25rem var(--sd-color-shadow),0 0 .0625rem rgba(0,0,0,.1)!important}.sd-shadow-md{box-shadow:0 .3rem .75rem var(--sd-color-shadow),0 0 .0625rem rgba(0,0,0,.1)!important}.sd-shadow-lg{box-shadow:0 .6rem 1.5rem var(--sd-color-shadow),0 0 .0625rem rgba(0,0,0,.1)!important}.sd-card-hover:hover{transform:none}.sd-cards-carousel{gap:.25rem;padding:.25rem}body{--tabs--label-text:var(--color-foreground-muted);--tabs--label-text--hover:var(--color-foreground-muted);--tabs--label-text--active:var(--color-brand-content);--tabs--label-text--active--hover:var(--color-brand-content);--tabs--label-background:transparent;--tabs--label-background--hover:transparent;--tabs--label-background--active:transparent;--tabs--label-background--active--hover:transparent;--tabs--padding-x:0.25em;--tabs--margin-x:1em;--tabs--border:var(--color-background-border);--tabs--label-border:transparent;--tabs--label-border--hover:var(--color-foreground-muted);--tabs--label-border--active:var(--color-brand-content);--tabs--label-border--active--hover:var(--color-brand-content)}[role=main] .container{max-width:none;padding-left:0;padding-right:0}.shadow.docutils{border:none;box-shadow:0 .2rem .5rem rgba(0,0,0,.05),0 0 .0625rem rgba(0,0,0,.1)!important}.sphinx-bs .card{background-color:var(--color-background-secondary);color:var(--color-foreground)} +/*# sourceMappingURL=furo-extensions.css.map*/ \ No newline at end of file diff --git a/3.7.0/_static/styles/furo-extensions.css.map b/3.7.0/_static/styles/furo-extensions.css.map new file mode 100644 index 000000000..c26eac7f5 --- /dev/null +++ b/3.7.0/_static/styles/furo-extensions.css.map @@ -0,0 +1 @@ +{"version":3,"file":"styles/furo-extensions.css","mappings":"AAGA,2BACE,oFACA,4CAKE,6CAHA,YACA,eAEA,CACA,kDACE,yCAEF,8CACE,sCAEJ,8CACE,kDAEJ,2BAGE,uBACA,cAHA,gBACA,UAEA,CAGA,yCACE,mBAEF,gDAEE,gDADA,YACA,CACA,sDACE,gDACF,yDACE,sCAEJ,+CACE,UACA,qDACE,UAGF,mDACE,eAEJ,yEAEE,4DAEA,mHASE,mBAPA,kBAEA,YADA,oBAGA,aADA,gBAIA,CAEA,qIAEE,WADA,UACA,CAEJ,uGACE,aAEF,iUAGE,cAEF,mHACE,aC1EJ,gCACE,mCAEF,0BAEE,mBAUA,8CACA,YAFA,mCAKA,eAZA,cAIA,YADA,YAYA,iCAdA,YAcA,CAEA,gCAEE,8CADA,gCACA,CAEF,gCAGE,6BADA,mCADA,YAEA,CAEF,kCAEE,cADA,oBACA,CACA,wCACE,cAEJ,8BACE,UCzCN,KAEE,6CAA8C,CAC9C,uDAAwD,CACxD,uDAAwD,CAGxD,iCAAsC,CAGtC,+CAAgD,CAChD,uDAAwD,CACxD,uDAAwD,CACxD,oDAAqD,CACrD,6DAA8D,CAC9D,6DAA8D,CAG9D,uDAAwD,CACxD,yDAA0D,CAC1D,4DAA6D,CAC7D,2DAA4D,CAC5D,8DAA+D,CAC/D,iEAAkE,CAClE,uDAAwD,CACxD,wDAAyD,CAG3D,gBACE,qFAGF,SACE,6EAEF,cACE,uFAEF,cACE,uFAEF,cACE,uFAGF,qBACE,eAEF,mBACE,WACA,eChDF,KACE,gDAAiD,CACjD,uDAAwD,CACxD,qDAAsD,CACtD,4DAA6D,CAC7D,oCAAqC,CACrC,2CAA4C,CAC5C,4CAA6C,CAC7C,mDAAoD,CACpD,wBAAyB,CACzB,oBAAqB,CACrB,6CAA8C,CAC9C,gCAAiC,CACjC,yDAA0D,CAC1D,uDAAwD,CACxD,8DAA+D,CCbjE,uBACE,eACA,eACA,gBAGF,iBACE,YACA,+EAGF,iBACE,mDACA","sources":["webpack:///./src/furo/assets/styles/extensions/_readthedocs.sass","webpack:///./src/furo/assets/styles/extensions/_copybutton.sass","webpack:///./src/furo/assets/styles/extensions/_sphinx-design.sass","webpack:///./src/furo/assets/styles/extensions/_sphinx-inline-tabs.sass","webpack:///./src/furo/assets/styles/extensions/_sphinx-panels.sass"],"sourcesContent":["// This file contains the styles used for tweaking how ReadTheDoc's embedded\n// contents would show up inside the theme.\n\n#furo-sidebar-ad-placement\n padding: var(--sidebar-item-spacing-vertical) var(--sidebar-item-spacing-horizontal)\n .ethical-sidebar\n // Remove the border and box-shadow.\n border: none\n box-shadow: none\n // Manage the background colors.\n background: var(--color-background-secondary)\n &:hover\n background: var(--color-background-hover)\n // Ensure the text is legible.\n a\n color: var(--color-foreground-primary)\n\n .ethical-callout a\n color: var(--color-foreground-secondary) !important\n\n#furo-readthedocs-versions\n position: static\n width: 100%\n background: transparent\n display: block\n\n // Make the background color fit with the theme's aesthetic.\n .rst-versions\n background: rgb(26, 28, 30)\n\n .rst-current-version\n cursor: unset\n background: var(--color-sidebar-item-background)\n &:hover\n background: var(--color-sidebar-item-background)\n .fa-book\n color: var(--color-foreground-primary)\n\n > .rst-other-versions\n padding: 0\n small\n opacity: 1\n\n .injected\n .rst-versions\n position: unset\n\n &:hover,\n &:focus-within\n box-shadow: 0 0 0 1px var(--color-sidebar-background-border)\n\n .rst-current-version\n // Undo the tweaks done in RTD's CSS\n font-size: inherit\n line-height: inherit\n height: auto\n text-align: right\n padding: 12px\n\n // Match the rest of the body\n background: #1a1c1e\n\n .fa-book\n float: left\n color: white\n\n .fa-caret-down\n display: none\n\n .rst-current-version,\n .rst-other-versions,\n .injected\n display: block\n\n > .rst-current-version\n display: none\n",".highlight\n &:hover button.copybtn\n color: var(--color-code-foreground)\n\n button.copybtn\n // Align things correctly\n align-items: center\n\n height: 1.25em\n width: 1.25em\n\n top: 0.625rem // $code-spacing-vertical\n right: 0.5rem\n\n // Make it look better\n color: var(--color-background-item)\n background-color: var(--color-code-background)\n border: none\n\n // Change to cursor to make it obvious that you can click on it\n cursor: pointer\n\n // Transition smoothly, for aesthetics\n transition: color 300ms, opacity 300ms\n\n &:hover\n color: var(--color-brand-content)\n background-color: var(--color-code-background)\n\n &::after\n display: none\n color: var(--color-code-foreground)\n background-color: transparent\n\n &.success\n transition: color 0ms\n color: #22863a\n &::after\n display: block\n\n svg\n padding: 0\n","body\n // Colors\n --sd-color-primary: var(--color-brand-primary)\n --sd-color-primary-highlight: var(--color-brand-content)\n --sd-color-primary-text: var(--color-background-primary)\n\n // Shadows\n --sd-color-shadow: rgba(0, 0, 0, 0.05)\n\n // Cards\n --sd-color-card-border: var(--color-card-border)\n --sd-color-card-border-hover: var(--color-brand-content)\n --sd-color-card-background: var(--color-card-background)\n --sd-color-card-text: var(--color-foreground-primary)\n --sd-color-card-header: var(--color-card-marginals-background)\n --sd-color-card-footer: var(--color-card-marginals-background)\n\n // Tabs\n --sd-color-tabs-label-active: var(--color-brand-content)\n --sd-color-tabs-label-hover: var(--color-foreground-muted)\n --sd-color-tabs-label-inactive: var(--color-foreground-muted)\n --sd-color-tabs-underline-active: var(--color-brand-content)\n --sd-color-tabs-underline-hover: var(--color-foreground-border)\n --sd-color-tabs-underline-inactive: var(--color-background-border)\n --sd-color-tabs-overline: var(--color-background-border)\n --sd-color-tabs-underline: var(--color-background-border)\n\n// Tabs\n.sd-tab-content\n box-shadow: 0 -2px var(--sd-color-tabs-overline), 0 1px var(--sd-color-tabs-underline)\n\n// Shadows\n.sd-card // Have a shadow by default\n box-shadow: 0 0.1rem 0.25rem var(--sd-color-shadow), 0 0 0.0625rem rgba(0, 0, 0, 0.1)\n\n.sd-shadow-sm\n box-shadow: 0 0.1rem 0.25rem var(--sd-color-shadow), 0 0 0.0625rem rgba(0, 0, 0, 0.1) !important\n\n.sd-shadow-md\n box-shadow: 0 0.3rem 0.75rem var(--sd-color-shadow), 0 0 0.0625rem rgba(0, 0, 0, 0.1) !important\n\n.sd-shadow-lg\n box-shadow: 0 0.6rem 1.5rem var(--sd-color-shadow), 0 0 0.0625rem rgba(0, 0, 0, 0.1) !important\n\n// Cards\n.sd-card-hover:hover // Don't change scale on hover\n transform: none\n\n.sd-cards-carousel // Have a bit of gap in the carousel by default\n gap: 0.25rem\n padding: 0.25rem\n","// This file contains styles to tweak sphinx-inline-tabs to work well with Furo.\n\nbody\n --tabs--label-text: var(--color-foreground-muted)\n --tabs--label-text--hover: var(--color-foreground-muted)\n --tabs--label-text--active: var(--color-brand-content)\n --tabs--label-text--active--hover: var(--color-brand-content)\n --tabs--label-background: transparent\n --tabs--label-background--hover: transparent\n --tabs--label-background--active: transparent\n --tabs--label-background--active--hover: transparent\n --tabs--padding-x: 0.25em\n --tabs--margin-x: 1em\n --tabs--border: var(--color-background-border)\n --tabs--label-border: transparent\n --tabs--label-border--hover: var(--color-foreground-muted)\n --tabs--label-border--active: var(--color-brand-content)\n --tabs--label-border--active--hover: var(--color-brand-content)\n","// This file contains styles to tweak sphinx-panels to work well with Furo.\n\n// sphinx-panels includes Bootstrap 4, which uses .container which can conflict\n// with docutils' `.. container::` directive.\n[role=\"main\"] .container\n max-width: initial\n padding-left: initial\n padding-right: initial\n\n// Make the panels look nicer!\n.shadow.docutils\n border: none\n box-shadow: 0 0.2rem 0.5rem rgba(0, 0, 0, 0.05), 0 0 0.0625rem rgba(0, 0, 0, 0.1) !important\n\n// Make panel colors respond to dark mode\n.sphinx-bs .card\n background-color: var(--color-background-secondary)\n color: var(--color-foreground)\n"],"names":[],"sourceRoot":""} \ No newline at end of file diff --git a/3.7.0/_static/styles/furo.css b/3.7.0/_static/styles/furo.css new file mode 100644 index 000000000..05a56b17f --- /dev/null +++ b/3.7.0/_static/styles/furo.css @@ -0,0 +1,2 @@ +/*! normalize.css v8.0.1 | MIT License | github.com/necolas/normalize.css */html{line-height:1.15;-webkit-text-size-adjust:100%}body{margin:0}main{display:block}h1{font-size:2em;margin:.67em 0}hr{box-sizing:content-box;height:0;overflow:visible}pre{font-family:monospace,monospace;font-size:1em}a{background-color:transparent}abbr[title]{border-bottom:none;text-decoration:underline;text-decoration:underline dotted}b,strong{font-weight:bolder}code,kbd,samp{font-family:monospace,monospace;font-size:1em}sub,sup{font-size:75%;line-height:0;position:relative;vertical-align:baseline}sub{bottom:-.25em}sup{top:-.5em}img{border-style:none}button,input,optgroup,select,textarea{font-family:inherit;font-size:100%;line-height:1.15;margin:0}button,input{overflow:visible}button,select{text-transform:none}[type=button],[type=reset],[type=submit],button{-webkit-appearance:button}[type=button]::-moz-focus-inner,[type=reset]::-moz-focus-inner,[type=submit]::-moz-focus-inner,button::-moz-focus-inner{border-style:none;padding:0}[type=button]:-moz-focusring,[type=reset]:-moz-focusring,[type=submit]:-moz-focusring,button:-moz-focusring{outline:1px dotted ButtonText}fieldset{padding:.35em .75em .625em}legend{box-sizing:border-box;color:inherit;display:table;max-width:100%;padding:0;white-space:normal}progress{vertical-align:baseline}textarea{overflow:auto}[type=checkbox],[type=radio]{box-sizing:border-box;padding:0}[type=number]::-webkit-inner-spin-button,[type=number]::-webkit-outer-spin-button{height:auto}[type=search]{-webkit-appearance:textfield;outline-offset:-2px}[type=search]::-webkit-search-decoration{-webkit-appearance:none}::-webkit-file-upload-button{-webkit-appearance:button;font:inherit}details{display:block}summary{display:list-item}[hidden],template{display:none}@media print{.content-icon-container,.headerlink,.mobile-header,.related-pages{display:none!important}.highlight{border:.1pt solid var(--color-foreground-border)}a,blockquote,dl,ol,p,pre,table,ul{page-break-inside:avoid}caption,figure,h1,h2,h3,h4,h5,h6,img{page-break-after:avoid;page-break-inside:avoid}dl,ol,ul{page-break-before:avoid}}.visually-hidden{height:1px!important;margin:-1px!important;overflow:hidden!important;padding:0!important;position:absolute!important;width:1px!important;clip:rect(0,0,0,0)!important;background:var(--color-background-primary);border:0!important;color:var(--color-foreground-primary);white-space:nowrap!important}:-moz-focusring{outline:auto}body{--font-stack:-apple-system,BlinkMacSystemFont,Segoe UI,Helvetica,Arial,sans-serif,Apple Color Emoji,Segoe UI Emoji;--font-stack--monospace:"SFMono-Regular",Menlo,Consolas,Monaco,Liberation Mono,Lucida Console,monospace;--font-stack--headings:var(--font-stack);--font-size--normal:100%;--font-size--small:87.5%;--font-size--small--2:81.25%;--font-size--small--3:75%;--font-size--small--4:62.5%;--sidebar-caption-font-size:var(--font-size--small--2);--sidebar-item-font-size:var(--font-size--small);--sidebar-search-input-font-size:var(--font-size--small);--toc-font-size:var(--font-size--small--3);--toc-font-size--mobile:var(--font-size--normal);--toc-title-font-size:var(--font-size--small--4);--admonition-font-size:0.8125rem;--admonition-title-font-size:0.8125rem;--code-font-size:var(--font-size--small--2);--api-font-size:var(--font-size--small);--header-height:calc(var(--sidebar-item-line-height) + var(--sidebar-item-spacing-vertical)*4);--header-padding:0.5rem;--sidebar-tree-space-above:1.5rem;--sidebar-caption-space-above:1rem;--sidebar-item-line-height:1rem;--sidebar-item-spacing-vertical:0.5rem;--sidebar-item-spacing-horizontal:1rem;--sidebar-item-height:calc(var(--sidebar-item-line-height) + var(--sidebar-item-spacing-vertical)*2);--sidebar-expander-width:var(--sidebar-item-height);--sidebar-search-space-above:0.5rem;--sidebar-search-input-spacing-vertical:0.5rem;--sidebar-search-input-spacing-horizontal:0.5rem;--sidebar-search-input-height:1rem;--sidebar-search-icon-size:var(--sidebar-search-input-height);--toc-title-padding:0.25rem 0;--toc-spacing-vertical:1.5rem;--toc-spacing-horizontal:1.5rem;--toc-item-spacing-vertical:0.4rem;--toc-item-spacing-horizontal:1rem;--icon-search:url('data:image/svg+xml;charset=utf-8,');--icon-pencil:url('data:image/svg+xml;charset=utf-8,');--icon-abstract:url('data:image/svg+xml;charset=utf-8,');--icon-info:url('data:image/svg+xml;charset=utf-8,');--icon-flame:url('data:image/svg+xml;charset=utf-8,');--icon-question:url('data:image/svg+xml;charset=utf-8,');--icon-warning:url('data:image/svg+xml;charset=utf-8,');--icon-failure:url('data:image/svg+xml;charset=utf-8,');--icon-spark:url('data:image/svg+xml;charset=utf-8,');--color-admonition-title--caution:#ff9100;--color-admonition-title-background--caution:rgba(255,145,0,.2);--color-admonition-title--warning:#ff9100;--color-admonition-title-background--warning:rgba(255,145,0,.2);--color-admonition-title--danger:#ff5252;--color-admonition-title-background--danger:rgba(255,82,82,.2);--color-admonition-title--attention:#ff5252;--color-admonition-title-background--attention:rgba(255,82,82,.2);--color-admonition-title--error:#ff5252;--color-admonition-title-background--error:rgba(255,82,82,.2);--color-admonition-title--hint:#00c852;--color-admonition-title-background--hint:rgba(0,200,82,.2);--color-admonition-title--tip:#00c852;--color-admonition-title-background--tip:rgba(0,200,82,.2);--color-admonition-title--important:#00bfa5;--color-admonition-title-background--important:rgba(0,191,165,.2);--color-admonition-title--note:#00b0ff;--color-admonition-title-background--note:rgba(0,176,255,.2);--color-admonition-title--seealso:#448aff;--color-admonition-title-background--seealso:rgba(68,138,255,.2);--color-admonition-title--admonition-todo:grey;--color-admonition-title-background--admonition-todo:hsla(0,0%,50%,.2);--color-admonition-title:#651fff;--color-admonition-title-background:rgba(101,31,255,.2);--icon-admonition-default:var(--icon-abstract);--color-topic-title:#14b8a6;--color-topic-title-background:rgba(20,184,166,.2);--icon-topic-default:var(--icon-pencil);--color-problematic:#b30000;--color-foreground-primary:#000;--color-foreground-secondary:#5a5c63;--color-foreground-muted:#6b6f76;--color-foreground-border:#878787;--color-background-primary:#fff;--color-background-secondary:#f8f9fb;--color-background-hover:#efeff4;--color-background-hover--transparent:#efeff400;--color-background-border:#eeebee;--color-background-item:#ccc;--color-announcement-background:#000000dd;--color-announcement-text:#eeebee;--color-brand-primary:#0a4bff;--color-brand-content:#2757dd;--color-brand-visited:#872ee0;--color-api-background:var(--color-background-hover--transparent);--color-api-background-hover:var(--color-background-hover);--color-api-overall:var(--color-foreground-secondary);--color-api-name:var(--color-problematic);--color-api-pre-name:var(--color-problematic);--color-api-paren:var(--color-foreground-secondary);--color-api-keyword:var(--color-foreground-primary);--color-api-added:#21632c;--color-api-added-border:#38a84d;--color-api-changed:#046172;--color-api-changed-border:#06a1bc;--color-api-deprecated:#605706;--color-api-deprecated-border:#f0d90f;--color-api-removed:#b30000;--color-api-removed-border:#ff5c5c;--color-highlight-on-target:#ffc;--color-inline-code-background:var(--color-background-secondary);--color-highlighted-background:#def;--color-highlighted-text:var(--color-foreground-primary);--color-guilabel-background:#ddeeff80;--color-guilabel-border:#bedaf580;--color-guilabel-text:var(--color-foreground-primary);--color-admonition-background:transparent;--color-table-header-background:var(--color-background-secondary);--color-table-border:var(--color-background-border);--color-card-border:var(--color-background-secondary);--color-card-background:transparent;--color-card-marginals-background:var(--color-background-secondary);--color-header-background:var(--color-background-primary);--color-header-border:var(--color-background-border);--color-header-text:var(--color-foreground-primary);--color-sidebar-background:var(--color-background-secondary);--color-sidebar-background-border:var(--color-background-border);--color-sidebar-brand-text:var(--color-foreground-primary);--color-sidebar-caption-text:var(--color-foreground-muted);--color-sidebar-link-text:var(--color-foreground-secondary);--color-sidebar-link-text--top-level:var(--color-brand-primary);--color-sidebar-item-background:var(--color-sidebar-background);--color-sidebar-item-background--current:var( --color-sidebar-item-background );--color-sidebar-item-background--hover:linear-gradient(90deg,var(--color-background-hover--transparent) 0%,var(--color-background-hover) var(--sidebar-item-spacing-horizontal),var(--color-background-hover) 100%);--color-sidebar-item-expander-background:transparent;--color-sidebar-item-expander-background--hover:var( --color-background-hover );--color-sidebar-search-text:var(--color-foreground-primary);--color-sidebar-search-background:var(--color-background-secondary);--color-sidebar-search-background--focus:var(--color-background-primary);--color-sidebar-search-border:var(--color-background-border);--color-sidebar-search-icon:var(--color-foreground-muted);--color-toc-background:var(--color-background-primary);--color-toc-title-text:var(--color-foreground-muted);--color-toc-item-text:var(--color-foreground-secondary);--color-toc-item-text--hover:var(--color-foreground-primary);--color-toc-item-text--active:var(--color-brand-primary);--color-content-foreground:var(--color-foreground-primary);--color-content-background:transparent;--color-link:var(--color-brand-content);--color-link-underline:var(--color-background-border);--color-link--hover:var(--color-brand-content);--color-link-underline--hover:var(--color-foreground-border);--color-link--visited:var(--color-brand-visited);--color-link-underline--visited:var(--color-background-border);--color-link--visited--hover:var(--color-brand-visited);--color-link-underline--visited--hover:var(--color-foreground-border)}.only-light{display:block!important}html body .only-dark{display:none!important}@media not print{body[data-theme=dark]{--color-problematic:#ee5151;--color-foreground-primary:#cfd0d0;--color-foreground-secondary:#9ca0a5;--color-foreground-muted:#81868d;--color-foreground-border:#666;--color-background-primary:#131416;--color-background-secondary:#1a1c1e;--color-background-hover:#1e2124;--color-background-hover--transparent:#1e212400;--color-background-border:#303335;--color-background-item:#444;--color-announcement-background:#000000dd;--color-announcement-text:#eeebee;--color-brand-primary:#3d94ff;--color-brand-content:#5ca5ff;--color-brand-visited:#b27aeb;--color-highlighted-background:#083563;--color-guilabel-background:#08356380;--color-guilabel-border:#13395f80;--color-api-keyword:var(--color-foreground-secondary);--color-highlight-on-target:#330;--color-api-added:#3db854;--color-api-added-border:#267334;--color-api-changed:#09b0ce;--color-api-changed-border:#056d80;--color-api-deprecated:#b1a10b;--color-api-deprecated-border:#6e6407;--color-api-removed:#ff7575;--color-api-removed-border:#b03b3b;--color-admonition-background:#18181a;--color-card-border:var(--color-background-secondary);--color-card-background:#18181a;--color-card-marginals-background:var(--color-background-hover)}html body[data-theme=dark] .only-light{display:none!important}body[data-theme=dark] .only-dark{display:block!important}@media(prefers-color-scheme:dark){body:not([data-theme=light]){--color-problematic:#ee5151;--color-foreground-primary:#cfd0d0;--color-foreground-secondary:#9ca0a5;--color-foreground-muted:#81868d;--color-foreground-border:#666;--color-background-primary:#131416;--color-background-secondary:#1a1c1e;--color-background-hover:#1e2124;--color-background-hover--transparent:#1e212400;--color-background-border:#303335;--color-background-item:#444;--color-announcement-background:#000000dd;--color-announcement-text:#eeebee;--color-brand-primary:#3d94ff;--color-brand-content:#5ca5ff;--color-brand-visited:#b27aeb;--color-highlighted-background:#083563;--color-guilabel-background:#08356380;--color-guilabel-border:#13395f80;--color-api-keyword:var(--color-foreground-secondary);--color-highlight-on-target:#330;--color-api-added:#3db854;--color-api-added-border:#267334;--color-api-changed:#09b0ce;--color-api-changed-border:#056d80;--color-api-deprecated:#b1a10b;--color-api-deprecated-border:#6e6407;--color-api-removed:#ff7575;--color-api-removed-border:#b03b3b;--color-admonition-background:#18181a;--color-card-border:var(--color-background-secondary);--color-card-background:#18181a;--color-card-marginals-background:var(--color-background-hover)}html body:not([data-theme=light]) .only-light{display:none!important}body:not([data-theme=light]) .only-dark{display:block!important}}}body[data-theme=auto] .theme-toggle svg.theme-icon-when-auto-light{display:block}@media(prefers-color-scheme:dark){body[data-theme=auto] .theme-toggle svg.theme-icon-when-auto-dark{display:block}body[data-theme=auto] .theme-toggle svg.theme-icon-when-auto-light{display:none}}body[data-theme=dark] .theme-toggle svg.theme-icon-when-dark,body[data-theme=light] .theme-toggle svg.theme-icon-when-light{display:block}body{font-family:var(--font-stack)}code,kbd,pre,samp{font-family:var(--font-stack--monospace)}body{-webkit-font-smoothing:antialiased;-moz-osx-font-smoothing:grayscale}article{line-height:1.5}h1,h2,h3,h4,h5,h6{border-radius:.5rem;font-family:var(--font-stack--headings);font-weight:700;line-height:1.25;margin:.5rem -.5rem;padding-left:.5rem;padding-right:.5rem}h1+p,h2+p,h3+p,h4+p,h5+p,h6+p{margin-top:0}h1{font-size:2.5em;margin-bottom:1rem}h1,h2{margin-top:1.75rem}h2{font-size:2em}h3{font-size:1.5em}h4{font-size:1.25em}h5{font-size:1.125em}h6{font-size:1em}small{font-size:80%;opacity:75%}p{margin-bottom:.75rem;margin-top:.5rem}hr.docutils{background-color:var(--color-background-border);border:0;height:1px;margin:2rem 0;padding:0}.centered{text-align:center}a{color:var(--color-link);text-decoration:underline;text-decoration-color:var(--color-link-underline)}a:visited{color:var(--color-link--visited);text-decoration-color:var(--color-link-underline--visited)}a:visited:hover{color:var(--color-link--visited--hover);text-decoration-color:var(--color-link-underline--visited--hover)}a:hover{color:var(--color-link--hover);text-decoration-color:var(--color-link-underline--hover)}a.muted-link{color:inherit}a.muted-link:hover{color:var(--color-link--hover);text-decoration-color:var(--color-link-underline--hover)}a.muted-link:hover:visited{color:var(--color-link--visited--hover);text-decoration-color:var(--color-link-underline--visited--hover)}html{overflow-x:hidden;overflow-y:scroll;scroll-behavior:smooth}.sidebar-scroll,.toc-scroll,article[role=main] *{scrollbar-color:var(--color-foreground-border) transparent;scrollbar-width:thin}.sidebar-scroll::-webkit-scrollbar,.toc-scroll::-webkit-scrollbar,article[role=main] ::-webkit-scrollbar{height:.25rem;width:.25rem}.sidebar-scroll::-webkit-scrollbar-thumb,.toc-scroll::-webkit-scrollbar-thumb,article[role=main] ::-webkit-scrollbar-thumb{background-color:var(--color-foreground-border);border-radius:.125rem}body,html{height:100%}.skip-to-content,body,html{background:var(--color-background-primary);color:var(--color-foreground-primary)}.skip-to-content{border-radius:1rem;left:.25rem;padding:1rem;position:fixed;top:.25rem;transform:translateY(-200%);transition:transform .3s ease-in-out;z-index:40}.skip-to-content:focus-within{transform:translateY(0)}article{background:var(--color-content-background);color:var(--color-content-foreground);overflow-wrap:break-word}.page{display:flex;min-height:100%}.mobile-header{background-color:var(--color-header-background);border-bottom:1px solid var(--color-header-border);color:var(--color-header-text);display:none;height:var(--header-height);width:100%;z-index:10}.mobile-header.scrolled{border-bottom:none;box-shadow:0 0 .2rem rgba(0,0,0,.1),0 .2rem .4rem rgba(0,0,0,.2)}.mobile-header .header-center a{color:var(--color-header-text);text-decoration:none}.main{display:flex;flex:1}.sidebar-drawer{background:var(--color-sidebar-background);border-right:1px solid var(--color-sidebar-background-border);box-sizing:border-box;display:flex;justify-content:flex-end;min-width:15em;width:calc(50% - 26em)}.sidebar-container,.toc-drawer{box-sizing:border-box;width:15em}.toc-drawer{background:var(--color-toc-background);padding-right:1rem}.sidebar-sticky,.toc-sticky{display:flex;flex-direction:column;height:min(100%,100vh);height:100vh;position:sticky;top:0}.sidebar-scroll,.toc-scroll{flex-grow:1;flex-shrink:1;overflow:auto;scroll-behavior:smooth}.content{display:flex;flex-direction:column;justify-content:space-between;padding:0 3em;width:46em}.icon{display:inline-block;height:1rem;width:1rem}.icon svg{height:100%;width:100%}.announcement{align-items:center;background-color:var(--color-announcement-background);color:var(--color-announcement-text);display:flex;height:var(--header-height);overflow-x:auto}.announcement+.page{min-height:calc(100% - var(--header-height))}.announcement-content{box-sizing:border-box;min-width:100%;padding:.5rem;text-align:center;white-space:nowrap}.announcement-content a{color:var(--color-announcement-text);text-decoration-color:var(--color-announcement-text)}.announcement-content a:hover{color:var(--color-announcement-text);text-decoration-color:var(--color-link--hover)}.no-js .theme-toggle-container{display:none}.theme-toggle-container{display:flex}.theme-toggle{background:transparent;border:none;cursor:pointer;display:flex;padding:0}.theme-toggle svg{color:var(--color-foreground-primary);display:none;height:1.25rem;width:1.25rem}.theme-toggle-header{align-items:center;display:flex;justify-content:center}.nav-overlay-icon,.toc-overlay-icon{cursor:pointer;display:none}.nav-overlay-icon .icon,.toc-overlay-icon .icon{color:var(--color-foreground-secondary);height:1.5rem;width:1.5rem}.nav-overlay-icon,.toc-header-icon{align-items:center;justify-content:center}.toc-content-icon{height:1.5rem;width:1.5rem}.content-icon-container{display:flex;float:right;gap:.5rem;margin-bottom:1rem;margin-left:1rem;margin-top:1.5rem}.content-icon-container .edit-this-page svg,.content-icon-container .view-this-page svg{color:inherit;height:1.25rem;width:1.25rem}.sidebar-toggle{display:none;position:absolute}.sidebar-toggle[name=__toc]{left:20px}.sidebar-toggle:checked{left:40px}.overlay{background-color:rgba(0,0,0,.54);height:0;opacity:0;position:fixed;top:0;transition:width 0ms,height 0ms,opacity .25s ease-out;width:0}.sidebar-overlay{z-index:20}.toc-overlay{z-index:40}.sidebar-drawer{transition:left .25s ease-in-out;z-index:30}.toc-drawer{transition:right .25s ease-in-out;z-index:50}#__navigation:checked~.sidebar-overlay{height:100%;opacity:1;width:100%}#__navigation:checked~.page .sidebar-drawer{left:0;top:0}#__toc:checked~.toc-overlay{height:100%;opacity:1;width:100%}#__toc:checked~.page .toc-drawer{right:0;top:0}.back-to-top{background:var(--color-background-primary);border-radius:1rem;box-shadow:0 .2rem .5rem rgba(0,0,0,.05),0 0 1px 0 hsla(220,9%,46%,.502);display:none;font-size:.8125rem;left:0;margin-left:50%;padding:.5rem .75rem .5rem .5rem;position:fixed;text-decoration:none;top:1rem;transform:translateX(-50%);z-index:10}.back-to-top svg{height:1rem;width:1rem;fill:currentColor;display:inline-block}.back-to-top span{margin-left:.25rem}.show-back-to-top .back-to-top{align-items:center;display:flex}@media(min-width:97em){html{font-size:110%}}@media(max-width:82em){.toc-content-icon{display:flex}.toc-drawer{border-left:1px solid var(--color-background-muted);height:100vh;position:fixed;right:-15em;top:0}.toc-tree{border-left:none;font-size:var(--toc-font-size--mobile)}.sidebar-drawer{width:calc(50% - 18.5em)}}@media(max-width:67em){.content{margin-left:auto;margin-right:auto;padding:0 1em}}@media(max-width:63em){.nav-overlay-icon{display:flex}.sidebar-drawer{height:100vh;left:-15em;position:fixed;top:0;width:15em}.theme-toggle-header,.toc-header-icon{display:flex}.theme-toggle-content,.toc-content-icon{display:none}.mobile-header{align-items:center;display:flex;justify-content:space-between;position:sticky;top:0}.mobile-header .header-left,.mobile-header .header-right{display:flex;height:var(--header-height);padding:0 var(--header-padding)}.mobile-header .header-left label,.mobile-header .header-right label{height:100%;-webkit-user-select:none;-moz-user-select:none;user-select:none;width:100%}.nav-overlay-icon .icon,.theme-toggle svg{height:1.5rem;width:1.5rem}:target{scroll-margin-top:calc(var(--header-height) + 2.5rem)}.back-to-top{top:calc(var(--header-height) + .5rem)}.page{flex-direction:column;justify-content:center}}@media(max-width:48em){.content{overflow-x:auto;width:100%}}@media(max-width:46em){article[role=main] aside.sidebar{float:none;margin:1rem 0;width:100%}}.admonition,.topic{background:var(--color-admonition-background);border-radius:.2rem;box-shadow:0 .2rem .5rem rgba(0,0,0,.05),0 0 .0625rem rgba(0,0,0,.1);font-size:var(--admonition-font-size);margin:1rem auto;overflow:hidden;padding:0 .5rem .5rem;page-break-inside:avoid}.admonition>:nth-child(2),.topic>:nth-child(2){margin-top:0}.admonition>:last-child,.topic>:last-child{margin-bottom:0}.admonition p.admonition-title,p.topic-title{font-size:var(--admonition-title-font-size);font-weight:500;line-height:1.3;margin:0 -.5rem .5rem;padding:.4rem .5rem .4rem 2rem;position:relative}.admonition p.admonition-title:before,p.topic-title:before{content:"";height:1rem;left:.5rem;position:absolute;width:1rem}p.admonition-title{background-color:var(--color-admonition-title-background)}p.admonition-title:before{background-color:var(--color-admonition-title);-webkit-mask-image:var(--icon-admonition-default);mask-image:var(--icon-admonition-default);-webkit-mask-repeat:no-repeat;mask-repeat:no-repeat}p.topic-title{background-color:var(--color-topic-title-background)}p.topic-title:before{background-color:var(--color-topic-title);-webkit-mask-image:var(--icon-topic-default);mask-image:var(--icon-topic-default);-webkit-mask-repeat:no-repeat;mask-repeat:no-repeat}.admonition{border-left:.2rem solid var(--color-admonition-title)}.admonition.caution{border-left-color:var(--color-admonition-title--caution)}.admonition.caution>.admonition-title{background-color:var(--color-admonition-title-background--caution)}.admonition.caution>.admonition-title:before{background-color:var(--color-admonition-title--caution);-webkit-mask-image:var(--icon-spark);mask-image:var(--icon-spark)}.admonition.warning{border-left-color:var(--color-admonition-title--warning)}.admonition.warning>.admonition-title{background-color:var(--color-admonition-title-background--warning)}.admonition.warning>.admonition-title:before{background-color:var(--color-admonition-title--warning);-webkit-mask-image:var(--icon-warning);mask-image:var(--icon-warning)}.admonition.danger{border-left-color:var(--color-admonition-title--danger)}.admonition.danger>.admonition-title{background-color:var(--color-admonition-title-background--danger)}.admonition.danger>.admonition-title:before{background-color:var(--color-admonition-title--danger);-webkit-mask-image:var(--icon-spark);mask-image:var(--icon-spark)}.admonition.attention{border-left-color:var(--color-admonition-title--attention)}.admonition.attention>.admonition-title{background-color:var(--color-admonition-title-background--attention)}.admonition.attention>.admonition-title:before{background-color:var(--color-admonition-title--attention);-webkit-mask-image:var(--icon-warning);mask-image:var(--icon-warning)}.admonition.error{border-left-color:var(--color-admonition-title--error)}.admonition.error>.admonition-title{background-color:var(--color-admonition-title-background--error)}.admonition.error>.admonition-title:before{background-color:var(--color-admonition-title--error);-webkit-mask-image:var(--icon-failure);mask-image:var(--icon-failure)}.admonition.hint{border-left-color:var(--color-admonition-title--hint)}.admonition.hint>.admonition-title{background-color:var(--color-admonition-title-background--hint)}.admonition.hint>.admonition-title:before{background-color:var(--color-admonition-title--hint);-webkit-mask-image:var(--icon-question);mask-image:var(--icon-question)}.admonition.tip{border-left-color:var(--color-admonition-title--tip)}.admonition.tip>.admonition-title{background-color:var(--color-admonition-title-background--tip)}.admonition.tip>.admonition-title:before{background-color:var(--color-admonition-title--tip);-webkit-mask-image:var(--icon-info);mask-image:var(--icon-info)}.admonition.important{border-left-color:var(--color-admonition-title--important)}.admonition.important>.admonition-title{background-color:var(--color-admonition-title-background--important)}.admonition.important>.admonition-title:before{background-color:var(--color-admonition-title--important);-webkit-mask-image:var(--icon-flame);mask-image:var(--icon-flame)}.admonition.note{border-left-color:var(--color-admonition-title--note)}.admonition.note>.admonition-title{background-color:var(--color-admonition-title-background--note)}.admonition.note>.admonition-title:before{background-color:var(--color-admonition-title--note);-webkit-mask-image:var(--icon-pencil);mask-image:var(--icon-pencil)}.admonition.seealso{border-left-color:var(--color-admonition-title--seealso)}.admonition.seealso>.admonition-title{background-color:var(--color-admonition-title-background--seealso)}.admonition.seealso>.admonition-title:before{background-color:var(--color-admonition-title--seealso);-webkit-mask-image:var(--icon-info);mask-image:var(--icon-info)}.admonition.admonition-todo{border-left-color:var(--color-admonition-title--admonition-todo)}.admonition.admonition-todo>.admonition-title{background-color:var(--color-admonition-title-background--admonition-todo)}.admonition.admonition-todo>.admonition-title:before{background-color:var(--color-admonition-title--admonition-todo);-webkit-mask-image:var(--icon-pencil);mask-image:var(--icon-pencil)}.admonition-todo>.admonition-title{text-transform:uppercase}dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple) dd{margin-left:2rem}dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple) dd>:first-child{margin-top:.125rem}dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple) .field-list,dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple) dd>:last-child{margin-bottom:.75rem}dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple) .field-list>dt{font-size:var(--font-size--small);text-transform:uppercase}dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple) .field-list dd:empty{margin-bottom:.5rem}dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple) .field-list dd>ul{margin-left:-1.2rem}dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple) .field-list dd>ul>li>p:nth-child(2){margin-top:0}dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple) .field-list dd>ul>li>p+p:last-child:empty{margin-bottom:0;margin-top:0}dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple)>dt{color:var(--color-api-overall)}.sig:not(.sig-inline){background:var(--color-api-background);border-radius:.25rem;font-family:var(--font-stack--monospace);font-size:var(--api-font-size);font-weight:700;margin-left:-.25rem;margin-right:-.25rem;padding:.25rem .5rem .25rem 3em;text-indent:-2.5em;transition:background .1s ease-out}.sig:not(.sig-inline):hover{background:var(--color-api-background-hover)}.sig:not(.sig-inline) a.reference .viewcode-link{font-weight:400;width:4.25rem}em.property{font-style:normal}em.property:first-child{color:var(--color-api-keyword)}.sig-name{color:var(--color-api-name)}.sig-prename{color:var(--color-api-pre-name);font-weight:400}.sig-paren{color:var(--color-api-paren)}.sig-param{font-style:normal}div.deprecated,div.versionadded,div.versionchanged,div.versionremoved{border-left:.1875rem solid;border-radius:.125rem;padding-left:.75rem}div.deprecated p,div.versionadded p,div.versionchanged p,div.versionremoved p{margin-bottom:.125rem;margin-top:.125rem}div.versionadded{border-color:var(--color-api-added-border)}div.versionadded .versionmodified{color:var(--color-api-added)}div.versionchanged{border-color:var(--color-api-changed-border)}div.versionchanged .versionmodified{color:var(--color-api-changed)}div.deprecated{border-color:var(--color-api-deprecated-border)}div.deprecated .versionmodified{color:var(--color-api-deprecated)}div.versionremoved{border-color:var(--color-api-removed-border)}div.versionremoved .versionmodified{color:var(--color-api-removed)}.viewcode-back,.viewcode-link{float:right;text-align:right}.line-block{margin-bottom:.75rem;margin-top:.5rem}.line-block .line-block{margin-bottom:0;margin-top:0;padding-left:1rem}.code-block-caption,article p.caption,table>caption{font-size:var(--font-size--small);text-align:center}.toctree-wrapper.compound .caption,.toctree-wrapper.compound :not(.caption)>.caption-text{font-size:var(--font-size--small);margin-bottom:0;text-align:initial;text-transform:uppercase}.toctree-wrapper.compound>ul{margin-bottom:0;margin-top:0}.sig-inline,code.literal{background:var(--color-inline-code-background);border-radius:.2em;font-size:var(--font-size--small--2);padding:.1em .2em}pre.literal-block .sig-inline,pre.literal-block code.literal{font-size:inherit;padding:0}p .sig-inline,p code.literal{border:1px solid var(--color-background-border)}.sig-inline{font-family:var(--font-stack--monospace)}div[class*=" highlight-"],div[class^=highlight-]{display:flex;margin:1em 0}div[class*=" highlight-"] .table-wrapper,div[class^=highlight-] .table-wrapper,pre{margin:0;padding:0}pre{overflow:auto}article[role=main] .highlight pre{line-height:1.5}.highlight pre,pre.literal-block{font-size:var(--code-font-size);padding:.625rem .875rem}pre.literal-block{background-color:var(--color-code-background);border-radius:.2rem;color:var(--color-code-foreground);margin-bottom:1rem;margin-top:1rem}.highlight{border-radius:.2rem;width:100%}.highlight .gp,.highlight span.linenos{pointer-events:none;-webkit-user-select:none;-moz-user-select:none;user-select:none}.highlight .hll{display:block;margin-left:-.875rem;margin-right:-.875rem;padding-left:.875rem;padding-right:.875rem}.code-block-caption{background-color:var(--color-code-background);border-bottom:1px solid;border-radius:.25rem;border-bottom-left-radius:0;border-bottom-right-radius:0;border-color:var(--color-background-border);color:var(--color-code-foreground);display:flex;font-weight:300;padding:.625rem .875rem}.code-block-caption+div[class]{margin-top:0}.code-block-caption+div[class] pre{border-top-left-radius:0;border-top-right-radius:0}.highlighttable{display:block;width:100%}.highlighttable tbody{display:block}.highlighttable tr{display:flex}.highlighttable td.linenos{background-color:var(--color-code-background);border-bottom-left-radius:.2rem;border-top-left-radius:.2rem;color:var(--color-code-foreground);padding:.625rem 0 .625rem .875rem}.highlighttable .linenodiv{box-shadow:-.0625rem 0 var(--color-foreground-border) inset;font-size:var(--code-font-size);padding-right:.875rem}.highlighttable td.code{display:block;flex:1;overflow:hidden;padding:0}.highlighttable td.code .highlight{border-bottom-left-radius:0;border-top-left-radius:0}.highlight span.linenos{box-shadow:-.0625rem 0 var(--color-foreground-border) inset;display:inline-block;margin-right:.875rem;padding-left:0;padding-right:.875rem}.footnote-reference{font-size:var(--font-size--small--4);vertical-align:super}dl.footnote.brackets{color:var(--color-foreground-secondary);display:grid;font-size:var(--font-size--small);grid-template-columns:max-content auto}dl.footnote.brackets dt{margin:0}dl.footnote.brackets dt>.fn-backref{margin-left:.25rem}dl.footnote.brackets dt:after{content:":"}dl.footnote.brackets dt .brackets:before{content:"["}dl.footnote.brackets dt .brackets:after{content:"]"}dl.footnote.brackets dd{margin:0;padding:0 1rem}aside.footnote{color:var(--color-foreground-secondary);font-size:var(--font-size--small)}aside.footnote>span,div.citation>span{float:left;font-weight:500;padding-right:.25rem}aside.footnote>:not(span),div.citation>p{margin-left:2rem}img{box-sizing:border-box;height:auto;max-width:100%}article .figure,article figure{border-radius:.2rem;margin:0}article .figure :last-child,article figure :last-child{margin-bottom:0}article .align-left{clear:left;float:left;margin:0 1rem 1rem}article .align-right{clear:right;float:right;margin:0 1rem 1rem}article .align-center,article .align-default{display:block;margin-left:auto;margin-right:auto;text-align:center}article table.align-default{display:table;text-align:initial}.domainindex-jumpbox,.genindex-jumpbox{border-bottom:1px solid var(--color-background-border);border-top:1px solid var(--color-background-border);padding:.25rem}.domainindex-section h2,.genindex-section h2{margin-bottom:.5rem;margin-top:.75rem}.domainindex-section ul,.genindex-section ul{margin-bottom:0;margin-top:0}ol,ul{margin-bottom:1rem;margin-top:1rem;padding-left:1.2rem}ol li>p:first-child,ul li>p:first-child{margin-bottom:.25rem;margin-top:.25rem}ol li>p:last-child,ul li>p:last-child{margin-top:.25rem}ol li>ol,ol li>ul,ul li>ol,ul li>ul{margin-bottom:.5rem;margin-top:.5rem}ol.arabic{list-style:decimal}ol.loweralpha{list-style:lower-alpha}ol.upperalpha{list-style:upper-alpha}ol.lowerroman{list-style:lower-roman}ol.upperroman{list-style:upper-roman}.simple li>ol,.simple li>ul,.toctree-wrapper li>ol,.toctree-wrapper li>ul{margin-bottom:0;margin-top:0}.field-list dt,.option-list dt,dl.footnote dt,dl.glossary dt,dl.simple dt,dl:not([class]) dt{font-weight:500;margin-top:.25rem}.field-list dt+dt,.option-list dt+dt,dl.footnote dt+dt,dl.glossary dt+dt,dl.simple dt+dt,dl:not([class]) dt+dt{margin-top:0}.field-list dt .classifier:before,.option-list dt .classifier:before,dl.footnote dt .classifier:before,dl.glossary dt .classifier:before,dl.simple dt .classifier:before,dl:not([class]) dt .classifier:before{content:":";margin-left:.2rem;margin-right:.2rem}.field-list dd ul,.field-list dd>p:first-child,.option-list dd ul,.option-list dd>p:first-child,dl.footnote dd ul,dl.footnote dd>p:first-child,dl.glossary dd ul,dl.glossary dd>p:first-child,dl.simple dd ul,dl.simple dd>p:first-child,dl:not([class]) dd ul,dl:not([class]) dd>p:first-child{margin-top:.125rem}.field-list dd ul,.option-list dd ul,dl.footnote dd ul,dl.glossary dd ul,dl.simple dd ul,dl:not([class]) dd ul{margin-bottom:.125rem}.math-wrapper{overflow-x:auto;width:100%}div.math{position:relative;text-align:center}div.math .headerlink,div.math:focus .headerlink{display:none}div.math:hover .headerlink{display:inline-block}div.math span.eqno{position:absolute;right:.5rem;top:50%;transform:translateY(-50%);z-index:1}abbr[title]{cursor:help}.problematic{color:var(--color-problematic)}kbd:not(.compound){background-color:var(--color-background-secondary);border:1px solid var(--color-foreground-border);border-radius:.2rem;box-shadow:0 .0625rem 0 rgba(0,0,0,.2),inset 0 0 0 .125rem var(--color-background-primary);color:var(--color-foreground-primary);display:inline-block;font-size:var(--font-size--small--3);margin:0 .2rem;padding:0 .2rem;vertical-align:text-bottom}blockquote{background:var(--color-background-secondary);border-left:4px solid var(--color-background-border);margin-left:0;margin-right:0;padding:.5rem 1rem}blockquote .attribution{font-weight:600;text-align:right}blockquote.highlights,blockquote.pull-quote{font-size:1.25em}blockquote.epigraph,blockquote.pull-quote{border-left-width:0;border-radius:.5rem}blockquote.highlights{background:transparent;border-left-width:0}p .reference img{vertical-align:middle}p.rubric{font-size:1.125em;font-weight:700;line-height:1.25}dd p.rubric{font-size:var(--font-size--small);font-weight:inherit;line-height:inherit;text-transform:uppercase}article .sidebar{background-color:var(--color-background-secondary);border:1px solid var(--color-background-border);border-radius:.2rem;clear:right;float:right;margin-left:1rem;margin-right:0;width:30%}article .sidebar>*{padding-left:1rem;padding-right:1rem}article .sidebar>ol,article .sidebar>ul{padding-left:2.2rem}article .sidebar .sidebar-title{border-bottom:1px solid var(--color-background-border);font-weight:500;margin:0;padding:.5rem 1rem}[role=main] .table-wrapper.container{margin-bottom:.5rem;margin-top:1rem;overflow-x:auto;padding:.2rem .2rem .75rem;width:100%}table.docutils{border-collapse:collapse;border-radius:.2rem;border-spacing:0;box-shadow:0 .2rem .5rem rgba(0,0,0,.05),0 0 .0625rem rgba(0,0,0,.1)}table.docutils th{background:var(--color-table-header-background)}table.docutils td,table.docutils th{border-bottom:1px solid var(--color-table-border);border-left:1px solid var(--color-table-border);border-right:1px solid var(--color-table-border);padding:0 .25rem}table.docutils td p,table.docutils th p{margin:.25rem}table.docutils td:first-child,table.docutils th:first-child{border-left:none}table.docutils td:last-child,table.docutils th:last-child{border-right:none}table.docutils td.text-left,table.docutils th.text-left{text-align:left}table.docutils td.text-right,table.docutils th.text-right{text-align:right}table.docutils td.text-center,table.docutils th.text-center{text-align:center}:target{scroll-margin-top:2.5rem}@media(max-width:67em){:target{scroll-margin-top:calc(2.5rem + var(--header-height))}section>span:target{scroll-margin-top:calc(2.8rem + var(--header-height))}}.headerlink{font-weight:100;-webkit-user-select:none;-moz-user-select:none;user-select:none}.code-block-caption>.headerlink,dl dt>.headerlink,figcaption p>.headerlink,h1>.headerlink,h2>.headerlink,h3>.headerlink,h4>.headerlink,h5>.headerlink,h6>.headerlink,p.caption>.headerlink,table>caption>.headerlink{margin-left:.5rem;visibility:hidden}.code-block-caption:hover>.headerlink,dl dt:hover>.headerlink,figcaption p:hover>.headerlink,h1:hover>.headerlink,h2:hover>.headerlink,h3:hover>.headerlink,h4:hover>.headerlink,h5:hover>.headerlink,h6:hover>.headerlink,p.caption:hover>.headerlink,table>caption:hover>.headerlink{visibility:visible}.code-block-caption>.toc-backref,dl dt>.toc-backref,figcaption p>.toc-backref,h1>.toc-backref,h2>.toc-backref,h3>.toc-backref,h4>.toc-backref,h5>.toc-backref,h6>.toc-backref,p.caption>.toc-backref,table>caption>.toc-backref{color:inherit;text-decoration-line:none}figure:hover>figcaption>p>.headerlink,table:hover>caption>.headerlink{visibility:visible}:target>h1:first-of-type,:target>h2:first-of-type,:target>h3:first-of-type,:target>h4:first-of-type,:target>h5:first-of-type,:target>h6:first-of-type,span:target~h1:first-of-type,span:target~h2:first-of-type,span:target~h3:first-of-type,span:target~h4:first-of-type,span:target~h5:first-of-type,span:target~h6:first-of-type{background-color:var(--color-highlight-on-target)}:target>h1:first-of-type code.literal,:target>h2:first-of-type code.literal,:target>h3:first-of-type code.literal,:target>h4:first-of-type code.literal,:target>h5:first-of-type code.literal,:target>h6:first-of-type code.literal,span:target~h1:first-of-type code.literal,span:target~h2:first-of-type code.literal,span:target~h3:first-of-type code.literal,span:target~h4:first-of-type code.literal,span:target~h5:first-of-type code.literal,span:target~h6:first-of-type code.literal{background-color:transparent}.literal-block-wrapper:target .code-block-caption,.this-will-duplicate-information-and-it-is-still-useful-here li :target,figure:target,table:target>caption{background-color:var(--color-highlight-on-target)}dt:target{background-color:var(--color-highlight-on-target)!important}.footnote-reference:target,.footnote>dt:target+dd{background-color:var(--color-highlight-on-target)}.guilabel{background-color:var(--color-guilabel-background);border:1px solid var(--color-guilabel-border);border-radius:.5em;color:var(--color-guilabel-text);font-size:.9em;padding:0 .3em}footer{display:flex;flex-direction:column;font-size:var(--font-size--small);margin-top:2rem}.bottom-of-page{align-items:center;border-top:1px solid var(--color-background-border);color:var(--color-foreground-secondary);display:flex;justify-content:space-between;line-height:1.5;margin-top:1rem;padding-bottom:1rem;padding-top:1rem}@media(max-width:46em){.bottom-of-page{flex-direction:column-reverse;gap:.25rem;text-align:center}}.bottom-of-page .left-details{font-size:var(--font-size--small)}.bottom-of-page .right-details{display:flex;flex-direction:column;gap:.25rem;text-align:right}.bottom-of-page .icons{display:flex;font-size:1rem;gap:.25rem;justify-content:flex-end}.bottom-of-page .icons a{text-decoration:none}.bottom-of-page .icons img,.bottom-of-page .icons svg{font-size:1.125rem;height:1em;width:1em}.related-pages a{align-items:center;display:flex;text-decoration:none}.related-pages a:hover .page-info .title{color:var(--color-link);text-decoration:underline;text-decoration-color:var(--color-link-underline)}.related-pages a svg.furo-related-icon,.related-pages a svg.furo-related-icon>use{color:var(--color-foreground-border);flex-shrink:0;height:.75rem;margin:0 .5rem;width:.75rem}.related-pages a.next-page{clear:right;float:right;max-width:50%;text-align:right}.related-pages a.prev-page{clear:left;float:left;max-width:50%}.related-pages a.prev-page svg{transform:rotate(180deg)}.page-info{display:flex;flex-direction:column;overflow-wrap:anywhere}.next-page .page-info{align-items:flex-end}.page-info .context{align-items:center;color:var(--color-foreground-muted);display:flex;font-size:var(--font-size--small);padding-bottom:.1rem;text-decoration:none}ul.search{list-style:none;padding-left:0}ul.search li{border-bottom:1px solid var(--color-background-border);padding:1rem 0}[role=main] .highlighted{background-color:var(--color-highlighted-background);color:var(--color-highlighted-text)}.sidebar-brand{display:flex;flex-direction:column;flex-shrink:0;padding:var(--sidebar-item-spacing-vertical) var(--sidebar-item-spacing-horizontal);text-decoration:none}.sidebar-brand-text{color:var(--color-sidebar-brand-text);font-size:1.5rem;overflow-wrap:break-word}.sidebar-brand-text,.sidebar-logo-container{margin:var(--sidebar-item-spacing-vertical) 0}.sidebar-logo{display:block;margin:0 auto;max-width:100%}.sidebar-search-container{align-items:center;background:var(--color-sidebar-search-background);display:flex;margin-top:var(--sidebar-search-space-above);position:relative}.sidebar-search-container:focus-within,.sidebar-search-container:hover{background:var(--color-sidebar-search-background--focus)}.sidebar-search-container:before{background-color:var(--color-sidebar-search-icon);content:"";height:var(--sidebar-search-icon-size);left:var(--sidebar-item-spacing-horizontal);-webkit-mask-image:var(--icon-search);mask-image:var(--icon-search);position:absolute;width:var(--sidebar-search-icon-size)}.sidebar-search{background:transparent;border:none;border-bottom:1px solid var(--color-sidebar-search-border);border-top:1px solid var(--color-sidebar-search-border);box-sizing:border-box;color:var(--color-sidebar-search-foreground);padding:var(--sidebar-search-input-spacing-vertical) var(--sidebar-search-input-spacing-horizontal) var(--sidebar-search-input-spacing-vertical) calc(var(--sidebar-item-spacing-horizontal) + var(--sidebar-search-input-spacing-horizontal) + var(--sidebar-search-icon-size));width:100%;z-index:10}.sidebar-search:focus{outline:none}.sidebar-search::-moz-placeholder{font-size:var(--sidebar-search-input-font-size)}.sidebar-search::placeholder{font-size:var(--sidebar-search-input-font-size)}#searchbox .highlight-link{margin:0;padding:var(--sidebar-item-spacing-vertical) var(--sidebar-item-spacing-horizontal) 0;text-align:center}#searchbox .highlight-link a{color:var(--color-sidebar-search-icon);font-size:var(--font-size--small--2)}.sidebar-tree{font-size:var(--sidebar-item-font-size);margin-bottom:var(--sidebar-item-spacing-vertical);margin-top:var(--sidebar-tree-space-above)}.sidebar-tree ul{display:flex;flex-direction:column;list-style:none;margin-bottom:0;margin-top:0;padding:0}.sidebar-tree li{margin:0;position:relative}.sidebar-tree li>ul{margin-left:var(--sidebar-item-spacing-horizontal)}.sidebar-tree .icon,.sidebar-tree .reference{color:var(--color-sidebar-link-text)}.sidebar-tree .reference{box-sizing:border-box;display:inline-block;height:100%;line-height:var(--sidebar-item-line-height);overflow-wrap:anywhere;padding:var(--sidebar-item-spacing-vertical) var(--sidebar-item-spacing-horizontal);text-decoration:none;width:100%}.sidebar-tree .reference:hover{background:var(--color-sidebar-item-background--hover);color:var(--color-sidebar-link-text)}.sidebar-tree .reference.external:after{color:var(--color-sidebar-link-text);content:url("data:image/svg+xml;charset=utf-8,%3Csvg xmlns='http://www.w3.org/2000/svg' width='12' height='12' fill='none' stroke='%23607D8B' stroke-linecap='round' stroke-linejoin='round' stroke-width='1.5' viewBox='0 0 24 24'%3E%3Cpath stroke='none' d='M0 0h24v24H0z'/%3E%3Cpath d='M11 7H6a2 2 0 0 0-2 2v9a2 2 0 0 0 2 2h9a2 2 0 0 0 2-2v-5M10 14 20 4M15 4h5v5'/%3E%3C/svg%3E");margin:0 .25rem;vertical-align:middle}.sidebar-tree .current-page>.reference{font-weight:700}.sidebar-tree label{align-items:center;cursor:pointer;display:flex;height:var(--sidebar-item-height);justify-content:center;position:absolute;right:0;top:0;-webkit-user-select:none;-moz-user-select:none;user-select:none;width:var(--sidebar-expander-width)}.sidebar-tree .caption,.sidebar-tree :not(.caption)>.caption-text{color:var(--color-sidebar-caption-text);font-size:var(--sidebar-caption-font-size);font-weight:700;margin:var(--sidebar-caption-space-above) 0 0 0;padding:var(--sidebar-item-spacing-vertical) var(--sidebar-item-spacing-horizontal);text-transform:uppercase}.sidebar-tree li.has-children>.reference{padding-right:var(--sidebar-expander-width)}.sidebar-tree .toctree-l1>.reference,.sidebar-tree .toctree-l1>label .icon{color:var(--color-sidebar-link-text--top-level)}.sidebar-tree label{background:var(--color-sidebar-item-expander-background)}.sidebar-tree label:hover{background:var(--color-sidebar-item-expander-background--hover)}.sidebar-tree .current>.reference{background:var(--color-sidebar-item-background--current)}.sidebar-tree .current>.reference:hover{background:var(--color-sidebar-item-background--hover)}.toctree-checkbox{display:none;position:absolute}.toctree-checkbox~ul{display:none}.toctree-checkbox~label .icon svg{transform:rotate(90deg)}.toctree-checkbox:checked~ul{display:block}.toctree-checkbox:checked~label .icon svg{transform:rotate(-90deg)}.toc-title-container{padding:var(--toc-title-padding);padding-top:var(--toc-spacing-vertical)}.toc-title{color:var(--color-toc-title-text);font-size:var(--toc-title-font-size);padding-left:var(--toc-spacing-horizontal);text-transform:uppercase}.no-toc{display:none}.toc-tree-container{padding-bottom:var(--toc-spacing-vertical)}.toc-tree{border-left:1px solid var(--color-background-border);font-size:var(--toc-font-size);line-height:1.3;padding-left:calc(var(--toc-spacing-horizontal) - var(--toc-item-spacing-horizontal))}.toc-tree>ul>li:first-child{padding-top:0}.toc-tree>ul>li:first-child>ul{padding-left:0}.toc-tree>ul>li:first-child>a{display:none}.toc-tree ul{list-style-type:none;margin-bottom:0;margin-top:0;padding-left:var(--toc-item-spacing-horizontal)}.toc-tree li{padding-top:var(--toc-item-spacing-vertical)}.toc-tree li.scroll-current>.reference{color:var(--color-toc-item-text--active);font-weight:700}.toc-tree a.reference{color:var(--color-toc-item-text);overflow-wrap:anywhere;text-decoration:none}.toc-scroll{max-height:100vh;overflow-y:scroll}.contents:not(.this-will-duplicate-information-and-it-is-still-useful-here){background:rgba(255,0,0,.25);color:var(--color-problematic)}.contents:not(.this-will-duplicate-information-and-it-is-still-useful-here):before{content:"ERROR: Adding a table of contents in Furo-based documentation is unnecessary, and does not work well with existing styling. Add a 'this-will-duplicate-information-and-it-is-still-useful-here' class, if you want an escape hatch."}.text-align\:left>p{text-align:left}.text-align\:center>p{text-align:center}.text-align\:right>p{text-align:right} +/*# sourceMappingURL=furo.css.map*/ \ No newline at end of file diff --git a/3.7.0/_static/styles/furo.css.map b/3.7.0/_static/styles/furo.css.map new file mode 100644 index 000000000..3ecc37150 --- /dev/null +++ b/3.7.0/_static/styles/furo.css.map @@ -0,0 +1 @@ +{"version":3,"file":"styles/furo.css","mappings":"AAAA,2EAA2E,CAU3E,KACE,gBAAiB,CACjB,6BACF,CASA,KACE,QACF,CAMA,KACE,aACF,CAOA,GACE,aAAc,CACd,cACF,CAUA,GACE,sBAAuB,CACvB,QAAS,CACT,gBACF,CAOA,IACE,+BAAiC,CACjC,aACF,CASA,EACE,4BACF,CAOA,YACE,kBAAmB,CACnB,yBAA0B,CAC1B,gCACF,CAMA,SAEE,kBACF,CAOA,cAGE,+BAAiC,CACjC,aACF,CAeA,QAEE,aAAc,CACd,aAAc,CACd,iBAAkB,CAClB,uBACF,CAEA,IACE,aACF,CAEA,IACE,SACF,CASA,IACE,iBACF,CAUA,sCAKE,mBAAoB,CACpB,cAAe,CACf,gBAAiB,CACjB,QACF,CAOA,aAEE,gBACF,CAOA,cAEE,mBACF,CAMA,gDAIE,yBACF,CAMA,wHAIE,iBAAkB,CAClB,SACF,CAMA,4GAIE,6BACF,CAMA,SACE,0BACF,CASA,OACE,qBAAsB,CACtB,aAAc,CACd,aAAc,CACd,cAAe,CACf,SAAU,CACV,kBACF,CAMA,SACE,uBACF,CAMA,SACE,aACF,CAOA,6BAEE,qBAAsB,CACtB,SACF,CAMA,kFAEE,WACF,CAOA,cACE,4BAA6B,CAC7B,mBACF,CAMA,yCACE,uBACF,CAOA,6BACE,yBAA0B,CAC1B,YACF,CASA,QACE,aACF,CAMA,QACE,iBACF,CAiBA,kBACE,YACF,CCvVA,aAcE,kEACE,uBAOF,WACE,iDAMF,kCACE,wBAEF,qCAEE,uBADA,uBACA,CAEF,SACE,wBAtBA,CCpBJ,iBAGE,qBAEA,sBACA,0BAFA,oBAHA,4BACA,oBAKA,6BAIA,2CAFA,mBACA,sCAFA,4BAGA,CAEF,gBACE,aCTF,KCGE,mHAEA,wGAEA,wCAAyC,CAEzC,wBAAyB,CACzB,wBAAyB,CACzB,4BAA6B,CAC7B,yBAA0B,CAC1B,2BAA4B,CAG5B,sDAAuD,CACvD,gDAAiD,CACjD,wDAAyD,CAGzD,0CAA2C,CAC3C,gDAAiD,CACjD,gDAAiD,CAKjD,gCAAiC,CACjC,sCAAuC,CAGvC,2CAA4C,CAG5C,uCAAwC,CCjCxC,+FAGA,uBAAwB,CAGxB,iCAAkC,CAClC,kCAAmC,CAEnC,+BAAgC,CAChC,sCAAuC,CACvC,sCAAuC,CACvC,qGAIA,mDAAoD,CAEpD,mCAAoC,CACpC,8CAA+C,CAC/C,gDAAiD,CACjD,kCAAmC,CACnC,6DAA8D,CAG9D,6BAA8B,CAC9B,6BAA8B,CAC9B,+BAAgC,CAChC,kCAAmC,CACnC,kCAAmC,CCPjC,+jBCYA,iqCAZF,iaCVA,8KAOA,4SAWA,4SAUA,0CACA,gEAGA,0CAGA,gEAGA,yCACA,+DAIA,4CACA,kEAGA,wCAUA,8DACA,uCAGA,4DACA,sCACA,2DAGA,4CACA,kEACA,uCAGA,6DACA,2GAGA,sHAEA,yFAEA,+CACA,+EAGA,4MAOA,gCACA,sHAIA,kCACA,uEACA,gEACA,4DACA,kEAGA,2DACA,sDACA,0CACA,8CACA,wGAGA,0BACA,iCAGA,+DACA,+BACA,sCACA,+DAEA,kGACA,oCACA,yDACA,sCL7HF,kCAEA,sDAIA,0CK2HE,kEAIA,oDACA,sDAGA,oCACA,oEAEA,0DACA,qDAIA,oDACA,6DAIA,iEAIA,2DAIA,2DAGA,4DACA,gEAIA,gEAEA,gFAEA,oNASA,qDLxKE,gFAGE,4DAIF,oEKkHF,yEAEA,6DAGA,0DAEA,uDACA,qDACA,wDAIA,6DAIA,yDACA,2DAIA,uCAGA,wCACA,sDAGA,+CAGA,6DAEA,iDACA,+DAEA,wDAEA,sEAMA,0DACA,sBACA,mEL9JI,wEAEA,iCACE,+BAMN,wEAGA,iCACE,kFAEA,uEAIF,gEACE,8BAGF,qEMvDA,sCAKA,wFAKA,iCAIA,0BAWA,iCACA,4BACA,mCAGA,+BAEA,sCACA,4BAEA,mCAEA,sCAKA,sDAIA,gCAEA,gEAQF,wCAME,sBACA,kCAKA,uBAEA,gEAIA,2BAIA,mCAEA,qCACA,iCAGE,+BACA,wEAEE,iCACA,kFAGF,6BACA,0CACF,kCAEE,8BACE,8BACA,qEAEE,sCACA,wFCnFN,iCAGF,2DAEE,4BACA,oCAGA,mIAGA,4HACE,gEAMJ,+CAGE,sBACA,yCAEF,uBAEE,sEAKA,gDACA,kEAGA,iFAGE,YAGF,EACA,4HAQF,mBACE,6BACA,mBACA,wCACA,wCACA,2CAIA,eAGA,mBAKE,mBAGA,CAJA,uCACA,iBAFF,gBACE,CAKE,mBACA,mBAGJ,oBAIF,+BAGE,kDACA,OADA,kBAGA,CAFA,gBAEA,mBACA,oBAEA,sCACA,OAGF,cAHE,WAGF,GAEE,oBACA,CAHF,gBAGE,CC9Gc,YDiHd,+CAIF,SAEE,CAPF,UACE,wBAMA,4BAEA,GAGA,uBACA,CAJA,yBAGA,CACA,iDAKA,2CAGA,2DAQA,iBACA,uCAGA,kEAKE,SAKJ,8BACE,yDACA,2BAEA,oBACA,8BAEA,yDAEE,4BAEJ,uCACE,CACA,iEAGA,CAEA,wCACE,uBACA,kDAEA,0DAEE,CAJF,oBAIE,0GAWN,aACE,CAHA,YAGA,4HASA,+CAGF,sBACE,WACA,WAQA,4BAFF,0CAEE,CARA,qCAsBA,CAdA,iBAEA,kBACE,aADF,4BACE,WAMF,2BAGF,qCAEE,CAXE,UAWF,+BAGA,uBAEA,SAEA,0CAIE,CANF,qCAEA,CAIE,2DACE,gBAIN,+CAIA,CAEA,kDAKE,CAPF,8BAEA,CAOE,YACA,CAjBI,2BAGN,CAHM,WAcJ,UAGA,CAEA,2GAIF,iCAGE,8BAIA,qBACA,oBACF,uBAOI,0CAIA,CATF,6DAKE,CALF,sBASE,qCAKF,CACE,cACA,CAFF,sBAEE,CACA,+BAEA,qBAEE,WAKN,aACE,sCAGA,mBAEA,6BAMA,kCACA,CAJA,sBACA,aAEA,CAJA,eACA,MAIA,2FAEA,UAGA,YACA,sBACE,8BAEA,CALF,aACA,WAIE,OACA,oBAEF,uBACE,WAEF,YAFE,UAEF,eAgBA,kBACE,CAhBA,qDAQF,qCAGF,CAGI,YACF,CAJF,2BAGI,CAEA,eACA,qBAGA,mEAEA,qBACA,8BAIA,kBADF,kBACE,yBAEJ,oCAGI,qDAIJ,+BAGI,oCAEA,+CAQF,4CACE,yBACF,2BAOE,sBACA,CAHA,WACA,CAFF,cACE,CAJA,YAGF,CAEE,SAEA,mBAGA,kDAEE,CAJF,cAEA,cAEE,sBAEA,mBADA,YACA,uBACA,mDACE,CADF,YACE,iDAEA,uCAEN,+DAOE,mBADF,sBACE,mBAGF,aACE,sCAIA,aADF,WACE,CAKF,SACE,CAHJ,kBAEE,CAJE,gBAEJ,CAHI,iBAMA,yFAKA,aACA,eACA,cElbJ,iBAEE,aADA,iBACA,6BAEA,kCAEA,SACA,UAIA,gCACA,CALA,SAEA,SAEA,CAJA,0EAEA,CAFA,OAKA,CAGA,mDACE,iBAGF,gCACE,CADF,UACE,aAEJ,iCAEE,CAFF,UAEE,wCAEA,WACA,WADA,UACA,CACA,4CAGA,MACA,CADA,KACA,wCACA,UAGA,CAJA,UAIA,6DAUA,0CACE,CAFF,mBAEE,wEACA,CAVA,YACA,CAMF,mBAJE,OAOA,gBAJJ,gCACE,CANE,cACA,CAHA,oBACA,CAGA,QAGJ,CAII,0BACA,CADA,UACA,wCAEJ,kBACE,0DACA,gCACE,kBACA,CADA,YACA,oEACA,2CAMF,mDAII,CALN,YACE,CANE,cAKJ,CACE,iBAII,kEACA,yCACE,kDACA,yDACE,+CACA,uBANN,CAMM,+BANN,uCACE,qDACA,4BAEE,mBADA,0CACA,CADA,qBACA,0DACE,wCACA,sGALJ,oCACA,sBACE,kBAFF,UAEE,2CACA,wFACE,cACA,kEANN,uBACE,iDACA,CADA,UACA,0DACE,wDAEE,iEACA,qEANN,sCACE,CAGE,iBAHF,gBAGE,qBACE,CAJJ,uBACA,gDACE,wDACA,6DAHF,2CACA,CADA,gBACA,eACE,CAGE,sBANN,8BACE,CAII,iBAFF,4DACA,WACE,YADF,uCACE,6EACA,2BANN,8CACE,kDACA,0CACE,8BACA,yFACE,sBACA,sFALJ,mEACA,sBACE,kEACA,6EACE,uCACA,kEALJ,qGAEE,kEACA,6EACE,uCACA,kEALJ,8CACA,uDACE,sEACA,2EACE,sCACA,iEALJ,mGACA,qCACE,oDACA,0DACE,6GACA,gDAGR,yDCrEA,sEACE,CACA,6GACE,gEACF,iGAIF,wFACE,qDAGA,mGAEE,2CAEF,4FACE,gCACF,wGACE,8DAEE,6FAIA,iJAKN,6GACE,gDAKF,yDACA,qCAGA,6BACA,kBACA,qDAKA,oCAEA,+DAGA,2CAGE,oDAIA,oEAEE,qBAGJ,wDAEE,uCAEF,kEAGA,8CAEA,uDAIF,gEAIE,6BACA,gEAIA,+CACE,0EAIF,sDAEE,+DAGF,sCACA,8BACE,oCAEJ,wBACE,4FAEE,gBAEJ,yGAGI,kBAGJ,CCnHE,2MCFF,oBAGE,wGAKA,iCACE,CADF,wBACE,8GAQA,mBCjBJ,2GAIE,mBACA,6HAMA,YACE,mIAYF,eACA,CAHF,YAGE,4FAGE,8BAKF,uBAkBE,sCACA,CADA,qBAbA,wCAIA,CALF,8BACE,CADF,gBAKE,wCACA,CAOA,kDACA,CACA,kCAKF,6BAGA,4CACE,kDACA,eAGF,cACE,aACA,iBACA,yBACA,8BACA,WAGJ,2BACE,cAGA,+BACA,CAHA,eAGA,wCACA,YACA,iBACA,uEAGA,0BACA,2CAEA,8EAGI,qBACA,CAFF,kBAEE,kBAGN,0CAGE,mCAGA,4BAIA,gEACE,qCACA,8BAEA,gBACA,+CACA,iCAEF,iCAEE,gEACA,qCAGF,8BAEE,+BAIA,yCAEE,qBADA,gBACA,yBAKF,eACA,CAFF,YACE,CACA,iBACA,qDAEA,mDCvIJ,2FAOE,iCACA,CAEA,eACA,CAHA,kBAEA,CAFA,wBAGA,8BACA,eACE,CAFF,YAEE,0BACA,8CAGA,oBACE,oCAGA,kBACE,8DAEA,iBAEN,UACE,8BAIJ,+CAEE,qDAEF,kDAIE,YAEF,CAFE,YAEF,CCpCE,mFADA,kBAKE,CAJF,IAGA,aACE,mCAGA,iDACE,+BAEJ,wBAEE,mBAMA,6CAEF,CAJE,mBAEA,CAEF,kCAGE,CARF,kBACE,CAHA,eAUA,YACA,mBACA,CADA,UACA,wCC9BF,oBDkCE,wBCnCJ,uCACE,+BACA,+DACA,sBAGA,qBCDA,6CAIE,CAPF,uBAGA,CDGE,oBACF,yDAEE,CCDE,2CAGF,CAJA,kCACE,CDJJ,YACE,CAIA,eCTF,CDKE,uBCMA,gCACE,YAEF,oCAEE,wBACA,0BAIF,iBAEA,cADF,UACE,uBAEA,iCAEA,wCAEA,6CAMA,CAYF,gCATI,4BASJ,CAZE,mCAEE,iCAUJ,4BAGE,4DADA,+BACA,CAHF,qBAGE,sCACE,OAEF,iBAHA,SAGA,iHACE,2DAKF,CANA,8EAMA,uSAEE,kBAEF,+FACE,yCCjEJ,WACA,yBAGA,uBACA,gBAEA,uCAIA,CAJA,iCAIA,uCAGA,UACE,gBACA,qBAEA,0CClBJ,gBACE,KAGF,qBACE,YAGF,CAHE,cAGF,gCAEE,mBACA,iEAEA,oCACA,wCAEA,sBACA,WAEA,CAFA,YAEA,8EAEA,mCAFA,iBAEA,6BAIA,wEAKA,sDAIE,CARF,mDAIA,CAIE,cAEF,8CAIA,oBAFE,iBAEF,8CAGE,eAEF,CAFE,YAEF,OAEE,kBAGJ,CAJI,eACA,CAFF,mBAKF,yCCjDE,oBACA,CAFA,iBAEA,uCAKE,iBACA,qCAGA,mBCZJ,CDWI,gBCXJ,6BAEE,eACA,sBAGA,eAEA,sBACA,oDACA,iGAMA,gBAFE,YAEF,8FAME,iJCnBF,YACA,gNAWE,gDAEF,iSAaE,kBACE,gHAKF,oCACE,eACF,CADE,UACF,8CACE,gDACF,wCACE,oBCxCJ,oBAEF,6BACE,QACE,kDAGF,yBACE,kDAmBA,kDAEF,CAhBA,+CAaA,CAbA,oBAaA,0FACE,CADF,gGAfF,cACE,gBACA,CAaA,0BAGA,mQACE,gBAGF,oMACE,iBACA,CAFF,eACE,CADF,gBAEE,aAGJ,iCAEE,CAFF,wCAEE,wBAUE,+VAIE,uEAHA,2BAGA,wXAKJ,iDAGF,CARM,+CACE,iDAIN,CALI,gBAQN,mHACE,gBAGF,2DACE,0EAOA,0EAGF,gBAEE,6DC/EA,kDACA,gCACA,qDAGA,qBACA,qDCFA,cACA,eAEA,yBAGF,sBAEE,iBACA,sNAWA,iBACE,kBACA,wRAgBA,kBAEA,iOAgBA,uCACE,uEAEA,kBAEF,qUAuBE,iDAIJ,CACA,geCxFF,4BAEE,CAQA,6JACA,iDAIA,sEAGA,mDAOF,iDAGE,4DAIA,8CACA,qDAEE,eAFF,cAEE,oBAEF,uBAFE,kCAGA,eACA,iBACA,mBAIA,mDACA,CAHA,uCAEA,CAJA,0CACA,CAIA,gBAJA,gBACA,oBADA,gBAIA,wBAEJ,gBAGE,6BACA,YAHA,iBAGA,gCACA,iEAEA,6CACA,sDACA,0BADA,wBACA,0BACA,oIAIA,mBAFA,YAEA,qBACA,0CAIE,uBAEF,CAHA,yBACE,CAEF,iDACE,mFAKJ,oCACE,CANE,aAKJ,CACE,qEAIA,YAFA,WAEA,CAHA,aACA,CAEA,gBACE,4BACA,sBADA,aACA,gCAMF,oCACA,yDACA,2CAEA,qBAGE,kBAEA,CACA,mCAIF,CARE,YACA,CAOF,iCAEE,CAPA,oBACA,CAQA,oBACE,uDAEJ,sDAGA,CAHA,cAGA,0BACE,oDAIA,oCACA,4BACA,sBAGA,cAEA,oFAGA,sBAEA,yDACE,CAIF,iBAJE,wBAIF,6CAHE,6CAKA,eACA,aACA,CADA,cACA,yCAGJ,kBACE,CAKA,iDAEA,CARF,aACE,4CAGA,kBAIA,wEAGA,wDAGA,kCAOA,iDAGA,CAPF,WAEE,sCAEA,CAJF,2CACE,CAMA,qCACA,+BARF,kBACE,qCAOA,iBAsBA,sBACE,CAvBF,WAKA,CACE,0DAIF,CALA,uDACE,CANF,sBAqBA,4CACA,CALA,gRAIA,YAEE,6CAEN,mCAEE,+CASA,6EAIA,4BChNA,SDmNA,qFCnNA,gDACA,sCAGA,qCACA,sDACA,CAKA,kDAGA,CARA,0CAQA,kBAGA,YACA,sBACA,iBAFA,gBADF,YACE,CAHA,SAKA,kBAEA,SAFA,iBAEA,uEAGA,CAEE,6CAFF,oCAgBI,CAdF,yBACE,qBACF,CAGF,oBACE,CAIF,WACE,CALA,2CAGA,uBACF,CACE,mFAGE,CALF,qBAEA,UAGE,gCAIF,sDAEA,CALE,oCAKF,yCC7CJ,oCACE,CD+CA,yXAQE,sCCrDJ,wCAGA,oCACE","sources":["webpack:///./node_modules/normalize.css/normalize.css","webpack:///./src/furo/assets/styles/base/_print.sass","webpack:///./src/furo/assets/styles/base/_screen-readers.sass","webpack:///./src/furo/assets/styles/base/_theme.sass","webpack:///./src/furo/assets/styles/variables/_fonts.scss","webpack:///./src/furo/assets/styles/variables/_spacing.scss","webpack:///./src/furo/assets/styles/variables/_icons.scss","webpack:///./src/furo/assets/styles/variables/_admonitions.scss","webpack:///./src/furo/assets/styles/variables/_colors.scss","webpack:///./src/furo/assets/styles/base/_typography.sass","webpack:///./src/furo/assets/styles/_scaffold.sass","webpack:///./src/furo/assets/styles/variables/_layout.scss","webpack:///./src/furo/assets/styles/content/_admonitions.sass","webpack:///./src/furo/assets/styles/content/_api.sass","webpack:///./src/furo/assets/styles/content/_blocks.sass","webpack:///./src/furo/assets/styles/content/_captions.sass","webpack:///./src/furo/assets/styles/content/_code.sass","webpack:///./src/furo/assets/styles/content/_footnotes.sass","webpack:///./src/furo/assets/styles/content/_images.sass","webpack:///./src/furo/assets/styles/content/_indexes.sass","webpack:///./src/furo/assets/styles/content/_lists.sass","webpack:///./src/furo/assets/styles/content/_math.sass","webpack:///./src/furo/assets/styles/content/_misc.sass","webpack:///./src/furo/assets/styles/content/_rubrics.sass","webpack:///./src/furo/assets/styles/content/_sidebar.sass","webpack:///./src/furo/assets/styles/content/_tables.sass","webpack:///./src/furo/assets/styles/content/_target.sass","webpack:///./src/furo/assets/styles/content/_gui-labels.sass","webpack:///./src/furo/assets/styles/components/_footer.sass","webpack:///./src/furo/assets/styles/components/_sidebar.sass","webpack:///./src/furo/assets/styles/components/_table_of_contents.sass","webpack:///./src/furo/assets/styles/_shame.sass"],"sourcesContent":["/*! normalize.css v8.0.1 | MIT License | github.com/necolas/normalize.css */\n\n/* Document\n ========================================================================== */\n\n/**\n * 1. Correct the line height in all browsers.\n * 2. Prevent adjustments of font size after orientation changes in iOS.\n */\n\nhtml {\n line-height: 1.15; /* 1 */\n -webkit-text-size-adjust: 100%; /* 2 */\n}\n\n/* Sections\n ========================================================================== */\n\n/**\n * Remove the margin in all browsers.\n */\n\nbody {\n margin: 0;\n}\n\n/**\n * Render the `main` element consistently in IE.\n */\n\nmain {\n display: block;\n}\n\n/**\n * Correct the font size and margin on `h1` elements within `section` and\n * `article` contexts in Chrome, Firefox, and Safari.\n */\n\nh1 {\n font-size: 2em;\n margin: 0.67em 0;\n}\n\n/* Grouping content\n ========================================================================== */\n\n/**\n * 1. Add the correct box sizing in Firefox.\n * 2. Show the overflow in Edge and IE.\n */\n\nhr {\n box-sizing: content-box; /* 1 */\n height: 0; /* 1 */\n overflow: visible; /* 2 */\n}\n\n/**\n * 1. Correct the inheritance and scaling of font size in all browsers.\n * 2. Correct the odd `em` font sizing in all browsers.\n */\n\npre {\n font-family: monospace, monospace; /* 1 */\n font-size: 1em; /* 2 */\n}\n\n/* Text-level semantics\n ========================================================================== */\n\n/**\n * Remove the gray background on active links in IE 10.\n */\n\na {\n background-color: transparent;\n}\n\n/**\n * 1. Remove the bottom border in Chrome 57-\n * 2. Add the correct text decoration in Chrome, Edge, IE, Opera, and Safari.\n */\n\nabbr[title] {\n border-bottom: none; /* 1 */\n text-decoration: underline; /* 2 */\n text-decoration: underline dotted; /* 2 */\n}\n\n/**\n * Add the correct font weight in Chrome, Edge, and Safari.\n */\n\nb,\nstrong {\n font-weight: bolder;\n}\n\n/**\n * 1. Correct the inheritance and scaling of font size in all browsers.\n * 2. Correct the odd `em` font sizing in all browsers.\n */\n\ncode,\nkbd,\nsamp {\n font-family: monospace, monospace; /* 1 */\n font-size: 1em; /* 2 */\n}\n\n/**\n * Add the correct font size in all browsers.\n */\n\nsmall {\n font-size: 80%;\n}\n\n/**\n * Prevent `sub` and `sup` elements from affecting the line height in\n * all browsers.\n */\n\nsub,\nsup {\n font-size: 75%;\n line-height: 0;\n position: relative;\n vertical-align: baseline;\n}\n\nsub {\n bottom: -0.25em;\n}\n\nsup {\n top: -0.5em;\n}\n\n/* Embedded content\n ========================================================================== */\n\n/**\n * Remove the border on images inside links in IE 10.\n */\n\nimg {\n border-style: none;\n}\n\n/* Forms\n ========================================================================== */\n\n/**\n * 1. Change the font styles in all browsers.\n * 2. Remove the margin in Firefox and Safari.\n */\n\nbutton,\ninput,\noptgroup,\nselect,\ntextarea {\n font-family: inherit; /* 1 */\n font-size: 100%; /* 1 */\n line-height: 1.15; /* 1 */\n margin: 0; /* 2 */\n}\n\n/**\n * Show the overflow in IE.\n * 1. Show the overflow in Edge.\n */\n\nbutton,\ninput { /* 1 */\n overflow: visible;\n}\n\n/**\n * Remove the inheritance of text transform in Edge, Firefox, and IE.\n * 1. Remove the inheritance of text transform in Firefox.\n */\n\nbutton,\nselect { /* 1 */\n text-transform: none;\n}\n\n/**\n * Correct the inability to style clickable types in iOS and Safari.\n */\n\nbutton,\n[type=\"button\"],\n[type=\"reset\"],\n[type=\"submit\"] {\n -webkit-appearance: button;\n}\n\n/**\n * Remove the inner border and padding in Firefox.\n */\n\nbutton::-moz-focus-inner,\n[type=\"button\"]::-moz-focus-inner,\n[type=\"reset\"]::-moz-focus-inner,\n[type=\"submit\"]::-moz-focus-inner {\n border-style: none;\n padding: 0;\n}\n\n/**\n * Restore the focus styles unset by the previous rule.\n */\n\nbutton:-moz-focusring,\n[type=\"button\"]:-moz-focusring,\n[type=\"reset\"]:-moz-focusring,\n[type=\"submit\"]:-moz-focusring {\n outline: 1px dotted ButtonText;\n}\n\n/**\n * Correct the padding in Firefox.\n */\n\nfieldset {\n padding: 0.35em 0.75em 0.625em;\n}\n\n/**\n * 1. Correct the text wrapping in Edge and IE.\n * 2. Correct the color inheritance from `fieldset` elements in IE.\n * 3. Remove the padding so developers are not caught out when they zero out\n * `fieldset` elements in all browsers.\n */\n\nlegend {\n box-sizing: border-box; /* 1 */\n color: inherit; /* 2 */\n display: table; /* 1 */\n max-width: 100%; /* 1 */\n padding: 0; /* 3 */\n white-space: normal; /* 1 */\n}\n\n/**\n * Add the correct vertical alignment in Chrome, Firefox, and Opera.\n */\n\nprogress {\n vertical-align: baseline;\n}\n\n/**\n * Remove the default vertical scrollbar in IE 10+.\n */\n\ntextarea {\n overflow: auto;\n}\n\n/**\n * 1. Add the correct box sizing in IE 10.\n * 2. Remove the padding in IE 10.\n */\n\n[type=\"checkbox\"],\n[type=\"radio\"] {\n box-sizing: border-box; /* 1 */\n padding: 0; /* 2 */\n}\n\n/**\n * Correct the cursor style of increment and decrement buttons in Chrome.\n */\n\n[type=\"number\"]::-webkit-inner-spin-button,\n[type=\"number\"]::-webkit-outer-spin-button {\n height: auto;\n}\n\n/**\n * 1. Correct the odd appearance in Chrome and Safari.\n * 2. Correct the outline style in Safari.\n */\n\n[type=\"search\"] {\n -webkit-appearance: textfield; /* 1 */\n outline-offset: -2px; /* 2 */\n}\n\n/**\n * Remove the inner padding in Chrome and Safari on macOS.\n */\n\n[type=\"search\"]::-webkit-search-decoration {\n -webkit-appearance: none;\n}\n\n/**\n * 1. Correct the inability to style clickable types in iOS and Safari.\n * 2. Change font properties to `inherit` in Safari.\n */\n\n::-webkit-file-upload-button {\n -webkit-appearance: button; /* 1 */\n font: inherit; /* 2 */\n}\n\n/* Interactive\n ========================================================================== */\n\n/*\n * Add the correct display in Edge, IE 10+, and Firefox.\n */\n\ndetails {\n display: block;\n}\n\n/*\n * Add the correct display in all browsers.\n */\n\nsummary {\n display: list-item;\n}\n\n/* Misc\n ========================================================================== */\n\n/**\n * Add the correct display in IE 10+.\n */\n\ntemplate {\n display: none;\n}\n\n/**\n * Add the correct display in IE 10.\n */\n\n[hidden] {\n display: none;\n}\n","// This file contains styles for managing print media.\n\n////////////////////////////////////////////////////////////////////////////////\n// Hide elements not relevant to print media.\n////////////////////////////////////////////////////////////////////////////////\n@media print\n // Hide icon container.\n .content-icon-container\n display: none !important\n\n // Hide showing header links if hovering over when printing.\n .headerlink\n display: none !important\n\n // Hide mobile header.\n .mobile-header\n display: none !important\n\n // Hide navigation links.\n .related-pages\n display: none !important\n\n////////////////////////////////////////////////////////////////////////////////\n// Tweaks related to decolorization.\n////////////////////////////////////////////////////////////////////////////////\n@media print\n // Apply a border around code which no longer have a color background.\n .highlight\n border: 0.1pt solid var(--color-foreground-border)\n\n////////////////////////////////////////////////////////////////////////////////\n// Avoid page break in some relevant cases.\n////////////////////////////////////////////////////////////////////////////////\n@media print\n ul, ol, dl, a, table, pre, blockquote, p\n page-break-inside: avoid\n\n h1, h2, h3, h4, h5, h6, img, figure, caption\n page-break-inside: avoid\n page-break-after: avoid\n\n ul, ol, dl\n page-break-before: avoid\n",".visually-hidden\n position: absolute !important\n width: 1px !important\n height: 1px !important\n padding: 0 !important\n margin: -1px !important\n overflow: hidden !important\n clip: rect(0,0,0,0) !important\n white-space: nowrap !important\n border: 0 !important\n color: var(--color-foreground-primary)\n background: var(--color-background-primary)\n\n:-moz-focusring\n outline: auto\n","// This file serves as the \"skeleton\" of the theming logic.\n//\n// This contains the bulk of the logic for handling dark mode, color scheme\n// toggling and the handling of color-scheme-specific hiding of elements.\n\nbody\n @include fonts\n @include spacing\n @include icons\n @include admonitions\n @include default-admonition(#651fff, \"abstract\")\n @include default-topic(#14B8A6, \"pencil\")\n\n @include colors\n\n.only-light\n display: block !important\nhtml body .only-dark\n display: none !important\n\n// Ignore dark-mode hints if print media.\n@media not print\n // Enable dark-mode, if requested.\n body[data-theme=\"dark\"]\n @include colors-dark\n\n html & .only-light\n display: none !important\n .only-dark\n display: block !important\n\n // Enable dark mode, unless explicitly told to avoid.\n @media (prefers-color-scheme: dark)\n body:not([data-theme=\"light\"])\n @include colors-dark\n\n html & .only-light\n display: none !important\n .only-dark\n display: block !important\n\n//\n// Theme toggle presentation\n//\nbody[data-theme=\"auto\"]\n .theme-toggle svg.theme-icon-when-auto-light\n display: block\n\n @media (prefers-color-scheme: dark)\n .theme-toggle svg.theme-icon-when-auto-dark\n display: block\n .theme-toggle svg.theme-icon-when-auto-light\n display: none\n\nbody[data-theme=\"dark\"]\n .theme-toggle svg.theme-icon-when-dark\n display: block\n\nbody[data-theme=\"light\"]\n .theme-toggle svg.theme-icon-when-light\n display: block\n","// Fonts used by this theme.\n//\n// There are basically two things here -- using the system font stack and\n// defining sizes for various elements in %ages. We could have also used `em`\n// but %age is easier to reason about for me.\n\n@mixin fonts {\n // These are adapted from https://systemfontstack.com/\n --font-stack: -apple-system, BlinkMacSystemFont, Segoe UI, Helvetica, Arial,\n sans-serif, Apple Color Emoji, Segoe UI Emoji;\n --font-stack--monospace: \"SFMono-Regular\", Menlo, Consolas, Monaco,\n Liberation Mono, Lucida Console, monospace;\n --font-stack--headings: var(--font-stack);\n\n --font-size--normal: 100%;\n --font-size--small: 87.5%;\n --font-size--small--2: 81.25%;\n --font-size--small--3: 75%;\n --font-size--small--4: 62.5%;\n\n // Sidebar\n --sidebar-caption-font-size: var(--font-size--small--2);\n --sidebar-item-font-size: var(--font-size--small);\n --sidebar-search-input-font-size: var(--font-size--small);\n\n // Table of Contents\n --toc-font-size: var(--font-size--small--3);\n --toc-font-size--mobile: var(--font-size--normal);\n --toc-title-font-size: var(--font-size--small--4);\n\n // Admonitions\n //\n // These aren't defined in terms of %ages, since nesting these is permitted.\n --admonition-font-size: 0.8125rem;\n --admonition-title-font-size: 0.8125rem;\n\n // Code\n --code-font-size: var(--font-size--small--2);\n\n // API\n --api-font-size: var(--font-size--small);\n}\n","// Spacing for various elements on the page\n//\n// If the user wants to tweak things in a certain way, they are permitted to.\n// They also have to deal with the consequences though!\n\n@mixin spacing {\n // Header!\n --header-height: calc(\n var(--sidebar-item-line-height) + 4 * #{var(--sidebar-item-spacing-vertical)}\n );\n --header-padding: 0.5rem;\n\n // Sidebar\n --sidebar-tree-space-above: 1.5rem;\n --sidebar-caption-space-above: 1rem;\n\n --sidebar-item-line-height: 1rem;\n --sidebar-item-spacing-vertical: 0.5rem;\n --sidebar-item-spacing-horizontal: 1rem;\n --sidebar-item-height: calc(\n var(--sidebar-item-line-height) + 2 *#{var(--sidebar-item-spacing-vertical)}\n );\n\n --sidebar-expander-width: var(--sidebar-item-height); // be square\n\n --sidebar-search-space-above: 0.5rem;\n --sidebar-search-input-spacing-vertical: 0.5rem;\n --sidebar-search-input-spacing-horizontal: 0.5rem;\n --sidebar-search-input-height: 1rem;\n --sidebar-search-icon-size: var(--sidebar-search-input-height);\n\n // Table of Contents\n --toc-title-padding: 0.25rem 0;\n --toc-spacing-vertical: 1.5rem;\n --toc-spacing-horizontal: 1.5rem;\n --toc-item-spacing-vertical: 0.4rem;\n --toc-item-spacing-horizontal: 1rem;\n}\n","// Expose theme icons as CSS variables.\n\n$icons: (\n // Adapted from tabler-icons\n // url: https://tablericons.com/\n \"search\":\n url('data:image/svg+xml;charset=utf-8,'),\n // Factored out from mkdocs-material on 24-Aug-2020.\n // url: https://squidfunk.github.io/mkdocs-material/reference/admonitions/\n \"pencil\":\n url('data:image/svg+xml;charset=utf-8,'),\n \"abstract\":\n url('data:image/svg+xml;charset=utf-8,'),\n \"info\":\n url('data:image/svg+xml;charset=utf-8,'),\n \"flame\":\n url('data:image/svg+xml;charset=utf-8,'),\n \"question\":\n url('data:image/svg+xml;charset=utf-8,'),\n \"warning\":\n url('data:image/svg+xml;charset=utf-8,'),\n \"failure\":\n url('data:image/svg+xml;charset=utf-8,'),\n \"spark\":\n url('data:image/svg+xml;charset=utf-8,')\n);\n\n@mixin icons {\n @each $name, $glyph in $icons {\n --icon-#{$name}: #{$glyph};\n }\n}\n","// Admonitions\n\n// Structure of these is:\n// admonition-class: color \"icon-name\";\n//\n// The colors are translated into CSS variables below. The icons are\n// used directly in the main declarations to set the `mask-image` in\n// the title.\n\n// prettier-ignore\n$admonitions: (\n // Each of these has an reST directives for it.\n \"caution\": #ff9100 \"spark\",\n \"warning\": #ff9100 \"warning\",\n \"danger\": #ff5252 \"spark\",\n \"attention\": #ff5252 \"warning\",\n \"error\": #ff5252 \"failure\",\n \"hint\": #00c852 \"question\",\n \"tip\": #00c852 \"info\",\n \"important\": #00bfa5 \"flame\",\n \"note\": #00b0ff \"pencil\",\n \"seealso\": #448aff \"info\",\n \"admonition-todo\": #808080 \"pencil\"\n);\n\n@mixin default-admonition($color, $icon-name) {\n --color-admonition-title: #{$color};\n --color-admonition-title-background: #{rgba($color, 0.2)};\n\n --icon-admonition-default: var(--icon-#{$icon-name});\n}\n\n@mixin default-topic($color, $icon-name) {\n --color-topic-title: #{$color};\n --color-topic-title-background: #{rgba($color, 0.2)};\n\n --icon-topic-default: var(--icon-#{$icon-name});\n}\n\n@mixin admonitions {\n @each $name, $values in $admonitions {\n --color-admonition-title--#{$name}: #{nth($values, 1)};\n --color-admonition-title-background--#{$name}: #{rgba(\n nth($values, 1),\n 0.2\n )};\n }\n}\n","// Colors used throughout this theme.\n//\n// The aim is to give the user more control. Thus, instead of hard-coding colors\n// in various parts of the stylesheet, the approach taken is to define all\n// colors as CSS variables and reusing them in all the places.\n//\n// `colors-dark` depends on `colors` being included at a lower specificity.\n\n@mixin colors {\n --color-problematic: #b30000;\n\n // Base Colors\n --color-foreground-primary: black; // for main text and headings\n --color-foreground-secondary: #5a5c63; // for secondary text\n --color-foreground-muted: #6b6f76; // for muted text\n --color-foreground-border: #878787; // for content borders\n\n --color-background-primary: white; // for content\n --color-background-secondary: #f8f9fb; // for navigation + ToC\n --color-background-hover: #efeff4ff; // for navigation-item hover\n --color-background-hover--transparent: #efeff400;\n --color-background-border: #eeebee; // for UI borders\n --color-background-item: #ccc; // for \"background\" items (eg: copybutton)\n\n // Announcements\n --color-announcement-background: #000000dd;\n --color-announcement-text: #eeebee;\n\n // Brand colors\n --color-brand-primary: #0a4bff;\n --color-brand-content: #2757dd;\n --color-brand-visited: #872ee0;\n\n // API documentation\n --color-api-background: var(--color-background-hover--transparent);\n --color-api-background-hover: var(--color-background-hover);\n --color-api-overall: var(--color-foreground-secondary);\n --color-api-name: var(--color-problematic);\n --color-api-pre-name: var(--color-problematic);\n --color-api-paren: var(--color-foreground-secondary);\n --color-api-keyword: var(--color-foreground-primary);\n\n --color-api-added: #21632c;\n --color-api-added-border: #38a84d;\n --color-api-changed: #046172;\n --color-api-changed-border: #06a1bc;\n --color-api-deprecated: #605706;\n --color-api-deprecated-border: #f0d90f;\n --color-api-removed: #b30000;\n --color-api-removed-border: #ff5c5c;\n\n --color-highlight-on-target: #ffffcc;\n\n // Inline code background\n --color-inline-code-background: var(--color-background-secondary);\n\n // Highlighted text (search)\n --color-highlighted-background: #ddeeff;\n --color-highlighted-text: var(--color-foreground-primary);\n\n // GUI Labels\n --color-guilabel-background: #ddeeff80;\n --color-guilabel-border: #bedaf580;\n --color-guilabel-text: var(--color-foreground-primary);\n\n // Admonitions!\n --color-admonition-background: transparent;\n\n //////////////////////////////////////////////////////////////////////////////\n // Everything below this should be one of:\n // - var(...)\n // - *-gradient(...)\n // - special literal values (eg: transparent, none)\n //////////////////////////////////////////////////////////////////////////////\n\n // Tables\n --color-table-header-background: var(--color-background-secondary);\n --color-table-border: var(--color-background-border);\n\n // Cards\n --color-card-border: var(--color-background-secondary);\n --color-card-background: transparent;\n --color-card-marginals-background: var(--color-background-secondary);\n\n // Header\n --color-header-background: var(--color-background-primary);\n --color-header-border: var(--color-background-border);\n --color-header-text: var(--color-foreground-primary);\n\n // Sidebar (left)\n --color-sidebar-background: var(--color-background-secondary);\n --color-sidebar-background-border: var(--color-background-border);\n\n --color-sidebar-brand-text: var(--color-foreground-primary);\n --color-sidebar-caption-text: var(--color-foreground-muted);\n --color-sidebar-link-text: var(--color-foreground-secondary);\n --color-sidebar-link-text--top-level: var(--color-brand-primary);\n\n --color-sidebar-item-background: var(--color-sidebar-background);\n --color-sidebar-item-background--current: var(\n --color-sidebar-item-background\n );\n --color-sidebar-item-background--hover: linear-gradient(\n 90deg,\n var(--color-background-hover--transparent) 0%,\n var(--color-background-hover) var(--sidebar-item-spacing-horizontal),\n var(--color-background-hover) 100%\n );\n\n --color-sidebar-item-expander-background: transparent;\n --color-sidebar-item-expander-background--hover: var(\n --color-background-hover\n );\n\n --color-sidebar-search-text: var(--color-foreground-primary);\n --color-sidebar-search-background: var(--color-background-secondary);\n --color-sidebar-search-background--focus: var(--color-background-primary);\n --color-sidebar-search-border: var(--color-background-border);\n --color-sidebar-search-icon: var(--color-foreground-muted);\n\n // Table of Contents (right)\n --color-toc-background: var(--color-background-primary);\n --color-toc-title-text: var(--color-foreground-muted);\n --color-toc-item-text: var(--color-foreground-secondary);\n --color-toc-item-text--hover: var(--color-foreground-primary);\n --color-toc-item-text--active: var(--color-brand-primary);\n\n // Actual page contents\n --color-content-foreground: var(--color-foreground-primary);\n --color-content-background: transparent;\n\n // Links\n --color-link: var(--color-brand-content);\n --color-link-underline: var(--color-background-border);\n --color-link--hover: var(--color-brand-content);\n --color-link-underline--hover: var(--color-foreground-border);\n\n --color-link--visited: var(--color-brand-visited);\n --color-link-underline--visited: var(--color-background-border);\n --color-link--visited--hover: var(--color-brand-visited);\n --color-link-underline--visited--hover: var(--color-foreground-border);\n}\n\n@mixin colors-dark {\n --color-problematic: #ee5151;\n\n // Base Colors\n --color-foreground-primary: #cfd0d0; // for main text and headings\n --color-foreground-secondary: #9ca0a5; // for secondary text\n --color-foreground-muted: #81868d; // for muted text\n --color-foreground-border: #666666; // for content borders\n\n --color-background-primary: #131416; // for content\n --color-background-secondary: #1a1c1e; // for navigation + ToC\n --color-background-hover: #1e2124ff; // for navigation-item hover\n --color-background-hover--transparent: #1e212400;\n --color-background-border: #303335; // for UI borders\n --color-background-item: #444; // for \"background\" items (eg: copybutton)\n\n // Announcements\n --color-announcement-background: #000000dd;\n --color-announcement-text: #eeebee;\n\n // Brand colors\n --color-brand-primary: #3d94ff;\n --color-brand-content: #5ca5ff;\n --color-brand-visited: #b27aeb;\n\n // Highlighted text (search)\n --color-highlighted-background: #083563;\n\n // GUI Labels\n --color-guilabel-background: #08356380;\n --color-guilabel-border: #13395f80;\n\n // API documentation\n --color-api-keyword: var(--color-foreground-secondary);\n --color-highlight-on-target: #333300;\n\n --color-api-added: #3db854;\n --color-api-added-border: #267334;\n --color-api-changed: #09b0ce;\n --color-api-changed-border: #056d80;\n --color-api-deprecated: #b1a10b;\n --color-api-deprecated-border: #6e6407;\n --color-api-removed: #ff7575;\n --color-api-removed-border: #b03b3b;\n\n // Admonitions\n --color-admonition-background: #18181a;\n\n // Cards\n --color-card-border: var(--color-background-secondary);\n --color-card-background: #18181a;\n --color-card-marginals-background: var(--color-background-hover);\n}\n","// This file contains the styling for making the content throughout the page,\n// including fonts, paragraphs, headings and spacing among these elements.\n\nbody\n font-family: var(--font-stack)\npre,\ncode,\nkbd,\nsamp\n font-family: var(--font-stack--monospace)\n\n// Make fonts look slightly nicer.\nbody\n -webkit-font-smoothing: antialiased\n -moz-osx-font-smoothing: grayscale\n\n// Line height from Bootstrap 4.1\narticle\n line-height: 1.5\n\n//\n// Headings\n//\nh1,\nh2,\nh3,\nh4,\nh5,\nh6\n line-height: 1.25\n font-family: var(--font-stack--headings)\n font-weight: bold\n\n border-radius: 0.5rem\n margin-top: 0.5rem\n margin-bottom: 0.5rem\n margin-left: -0.5rem\n margin-right: -0.5rem\n padding-left: 0.5rem\n padding-right: 0.5rem\n\n + p\n margin-top: 0\n\nh1\n font-size: 2.5em\n margin-top: 1.75rem\n margin-bottom: 1rem\nh2\n font-size: 2em\n margin-top: 1.75rem\nh3\n font-size: 1.5em\nh4\n font-size: 1.25em\nh5\n font-size: 1.125em\nh6\n font-size: 1em\n\nsmall\n opacity: 75%\n font-size: 80%\n\n// Paragraph\np\n margin-top: 0.5rem\n margin-bottom: 0.75rem\n\n// Horizontal rules\nhr.docutils\n height: 1px\n padding: 0\n margin: 2rem 0\n background-color: var(--color-background-border)\n border: 0\n\n.centered\n text-align: center\n\n// Links\na\n text-decoration: underline\n\n color: var(--color-link)\n text-decoration-color: var(--color-link-underline)\n\n &:visited\n color: var(--color-link--visited)\n text-decoration-color: var(--color-link-underline--visited)\n &:hover\n color: var(--color-link--visited--hover)\n text-decoration-color: var(--color-link-underline--visited--hover)\n\n &:hover\n color: var(--color-link--hover)\n text-decoration-color: var(--color-link-underline--hover)\n &.muted-link\n color: inherit\n &:hover\n color: var(--color-link--hover)\n text-decoration-color: var(--color-link-underline--hover)\n &:visited\n color: var(--color-link--visited--hover)\n text-decoration-color: var(--color-link-underline--visited--hover)\n","// This file contains the styles for the overall layouting of the documentation\n// skeleton, including the responsive changes as well as sidebar toggles.\n//\n// This is implemented as a mobile-last design, which isn't ideal, but it is\n// reasonably good-enough and I got pretty tired by the time I'd finished this\n// to move the rules around to fix this. Shouldn't take more than 3-4 hours,\n// if you know what you're doing tho.\n\n// HACK: Not all browsers account for the scrollbar width in media queries.\n// This results in horizontal scrollbars in the breakpoint where we go\n// from displaying everything to hiding the ToC. We accomodate for this by\n// adding a bit of padding to the TOC drawer, disabling the horizontal\n// scrollbar and allowing the scrollbars to cover the padding.\n// https://www.456bereastreet.com/archive/201301/media_query_width_and_vertical_scrollbars/\n\n// HACK: Always having the scrollbar visible, prevents certain browsers from\n// causing the content to stutter horizontally between taller-than-viewport and\n// not-taller-than-viewport pages.\n\nhtml\n overflow-x: hidden\n overflow-y: scroll\n scroll-behavior: smooth\n\n.sidebar-scroll, .toc-scroll, article[role=main] *\n // Override Firefox scrollbar style\n scrollbar-width: thin\n scrollbar-color: var(--color-foreground-border) transparent\n\n // Override Chrome scrollbar styles\n &::-webkit-scrollbar\n width: 0.25rem\n height: 0.25rem\n &::-webkit-scrollbar-thumb\n background-color: var(--color-foreground-border)\n border-radius: 0.125rem\n\n//\n// Overalls\n//\nhtml,\nbody\n height: 100%\n color: var(--color-foreground-primary)\n background: var(--color-background-primary)\n\n.skip-to-content\n position: fixed\n padding: 1rem\n border-radius: 1rem\n left: 0.25rem\n top: 0.25rem\n z-index: 40\n background: var(--color-background-primary)\n color: var(--color-foreground-primary)\n\n transform: translateY(-200%)\n transition: transform 300ms ease-in-out\n\n &:focus-within\n transform: translateY(0%)\n\narticle\n color: var(--color-content-foreground)\n background: var(--color-content-background)\n overflow-wrap: break-word\n\n.page\n display: flex\n // fill the viewport for pages with little content.\n min-height: 100%\n\n.mobile-header\n width: 100%\n height: var(--header-height)\n background-color: var(--color-header-background)\n color: var(--color-header-text)\n border-bottom: 1px solid var(--color-header-border)\n\n // Looks like sub-script/super-script have this, and we need this to\n // be \"on top\" of those.\n z-index: 10\n\n // We don't show the header on large screens.\n display: none\n\n // Add shadow when scrolled\n &.scrolled\n border-bottom: none\n box-shadow: 0 0 0.2rem rgba(0, 0, 0, 0.1), 0 0.2rem 0.4rem rgba(0, 0, 0, 0.2)\n\n .header-center\n a\n color: var(--color-header-text)\n text-decoration: none\n\n.main\n display: flex\n flex: 1\n\n// Sidebar (left) also covers the entire left portion of screen.\n.sidebar-drawer\n box-sizing: border-box\n\n border-right: 1px solid var(--color-sidebar-background-border)\n background: var(--color-sidebar-background)\n\n display: flex\n justify-content: flex-end\n // These next two lines took me two days to figure out.\n width: calc((100% - #{$full-width}) / 2 + #{$sidebar-width})\n min-width: $sidebar-width\n\n// Scroll-along sidebars\n.sidebar-container,\n.toc-drawer\n box-sizing: border-box\n width: $sidebar-width\n\n.toc-drawer\n background: var(--color-toc-background)\n // See HACK described on top of this document\n padding-right: 1rem\n\n.sidebar-sticky,\n.toc-sticky\n position: sticky\n top: 0\n height: min(100%, 100vh)\n height: 100vh\n\n display: flex\n flex-direction: column\n\n.sidebar-scroll,\n.toc-scroll\n flex-grow: 1\n flex-shrink: 1\n\n overflow: auto\n scroll-behavior: smooth\n\n// Central items.\n.content\n padding: 0 $content-padding\n width: $content-width\n\n display: flex\n flex-direction: column\n justify-content: space-between\n\n.icon\n display: inline-block\n height: 1rem\n width: 1rem\n svg\n width: 100%\n height: 100%\n\n//\n// Accommodate announcement banner\n//\n.announcement\n background-color: var(--color-announcement-background)\n color: var(--color-announcement-text)\n\n height: var(--header-height)\n display: flex\n align-items: center\n overflow-x: auto\n & + .page\n min-height: calc(100% - var(--header-height))\n\n.announcement-content\n box-sizing: border-box\n padding: 0.5rem\n min-width: 100%\n white-space: nowrap\n text-align: center\n\n a\n color: var(--color-announcement-text)\n text-decoration-color: var(--color-announcement-text)\n\n &:hover\n color: var(--color-announcement-text)\n text-decoration-color: var(--color-link--hover)\n\n////////////////////////////////////////////////////////////////////////////////\n// Toggles for theme\n////////////////////////////////////////////////////////////////////////////////\n.no-js .theme-toggle-container // don't show theme toggle if there's no JS\n display: none\n\n.theme-toggle-container\n display: flex\n\n.theme-toggle\n display: flex\n cursor: pointer\n border: none\n padding: 0\n background: transparent\n\n.theme-toggle svg\n height: 1.25rem\n width: 1.25rem\n color: var(--color-foreground-primary)\n display: none\n\n.theme-toggle-header\n display: flex\n align-items: center\n justify-content: center\n\n////////////////////////////////////////////////////////////////////////////////\n// Toggles for elements\n////////////////////////////////////////////////////////////////////////////////\n.toc-overlay-icon, .nav-overlay-icon\n display: none\n cursor: pointer\n\n .icon\n color: var(--color-foreground-secondary)\n height: 1.5rem\n width: 1.5rem\n\n.toc-header-icon, .nav-overlay-icon\n // for when we set display: flex\n justify-content: center\n align-items: center\n\n.toc-content-icon\n height: 1.5rem\n width: 1.5rem\n\n.content-icon-container\n float: right\n display: flex\n margin-top: 1.5rem\n margin-left: 1rem\n margin-bottom: 1rem\n gap: 0.5rem\n\n .edit-this-page, .view-this-page\n svg\n color: inherit\n height: 1.25rem\n width: 1.25rem\n\n.sidebar-toggle\n position: absolute\n display: none\n//