<commit_before>.. _examples:

Getting Started
===============

There are examples of usage within the API documentation and tests. This
section is to demonstrate recommended usage.

Also see: :ref:`gotchas`


Using CRS
---------
For more usage examples and documentation see :class:`pyproj.crs.CRS`.

Initializing CRS
~~~~~~~~~~~~~~~~

The :class:`pyproj.crs.CRS` class can be initialized in many different ways.
Here are some examples of initialization.


.. code:: python

    >>> from pyproj import CRS
    >>> crs = CRS.from_epsg(4326)
    >>> crs = CRS.from_string("epsg:4326")
    >>> crs = CRS.from_proj4("+proj=latlon")
    >>> crs = CRS.from_user_input(4326)


Converting CRS to a different format
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. warning:: You will likely lose important projection
    information when converting to a PROJ string from
    another format. See: https://proj4.org/faq.html#what-is-the-best-format-for-describing-coordinate-reference-systems


.. code:: python

    >>> from pyproj import CRS
    >>> crs = CRS.from_epsg(4326)
    >>> crs.to_epsg()
    4326
    >>> crs.to_authority()
    ('EPSG', '4326')
    >>> crs = CRS.from_proj4("+proj=omerc +lat_0=-36 +lonc=147 +alpha=-54 +k=1 +x_0=0 +y_0=0 +gamma=0 +ellps=WGS84 +towgs84=0,0,0,0,0,0,0")
    >>> crs
    <Bound CRS: +proj=omerc +lat_0=-36 +lonc=147 +alpha=-54 +k=1 + ...>
    Name: unknown
    Axis Info [cartesian]:
    - E[east]: Easting (metre)
    - N[north]: Northing (metre)
    Area of Use:
    - undefined
    Coordinate Operation:
    - name: Transformation from unknown to WGS84
    - method: Position Vector transformation (geog2D domain)
    Datum: Unknown based on WGS84 ellipsoid
    - Ellipsoid: WGS 84
    - Prime Meridian: Greenwich
    Source CRS: unknown

    >>> print(crs.to_wkt(pretty=True))
    BOUNDCRS[
        SOURCECRS[
            PROJCRS["unknown",
                BASEGEOGCRS["unknown",
                    DATUM["Unknown based on WGS84 ellipsoid",
                        ELLIPSOID["WGS 84",6378137,298.257223563,
                            LENGTHUNIT["metre",1],
                            ID["EPSG",7030]]],
    ...
            PARAMETER["Z-axis rotation",0,
                ID["EPSG",8610]],
            PARAMETER["Scale difference",1,
                ID["EPSG",8611]]]]

    >>> from pyproj.enums import WktVersion
    >>> print(crs.to_wkt(WktVersion.WKT1_GDAL, pretty=True))
    PROJCS["unknown",
        GEOGCS["unknown",
            DATUM["Unknown_based_on_WGS84_ellipsoid",
                SPHEROID["WGS 84",6378137,298.257223563,
                    AUTHORITY["EPSG","7030"]],
                TOWGS84[0,0,0,0,0,0,0]],
            PRIMEM["Greenwich",0,
                AUTHORITY["EPSG","8901"]],
            UNIT["degree",0.0174532925199433,
                AUTHORITY["EPSG","9122"]]],
        PROJECTION["Hotine_Oblique_Mercator_Azimuth_Center"],
        PARAMETER["latitude_of_center",-36],
        PARAMETER["longitude_of_center",147],
        PARAMETER["azimuth",-54],
        PARAMETER["rectified_grid_angle",0],
        PARAMETER["scale_factor",1],
        PARAMETER["false_easting",0],
        PARAMETER["false_northing",0],
        UNIT["metre",1,
            AUTHORITY["EPSG","9001"]],
        AXIS["Easting",EAST],
        AXIS["Northing",NORTH]]

    >>> from pprint import pprint
    >>> pprint(crs.to_cf())
    {'azimuth_of_central_line': -54,
    'crs_wkt': 'BOUNDCRS[SOURCECRS[PROJCRS["unknown",BASEGEOGCRS["unknown",DATUM["Unknown '
    ...
                'difference",1,ID["EPSG",8611]]]]',
    'false_easting': 0.0,
    'false_northing': 0.0,
    'grid_mapping_name': 'oblique_mercator',
    'horizontal_datum_name': 'Unknown based on WGS84 ellipsoid',
    'inverse_flattening': 298.257223563,
    'latitude_of_projection_origin': -36.0,
    'longitude_of_prime_meridian': 0.0,
    'longitude_of_projection_origin': 147.0,
    'prime_meridian_name': 'Greenwich',
    'reference_ellipsoid_name': 'WGS 84',
    'scale_factor_at_projection_origin': 1.0,
    'semi_major_axis': 6378137.0,
    'semi_minor_axis': 6356752.314245179,
    'towgs84': [0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0]}


Extracting attributes from CRS
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

There are many attributes you can pull from the :class:`pyproj.crs.CRS`.
This is just a small subset of what is available.


.. code:: python

    >>> crs = CRS("urn:ogc:def:crs,crs:EPSG::2393,crs:EPSG::5717")
    >>> crs
    <Compound CRS: EPSG:3901>
    Name: KKJ / Finland Uniform Coordinate System + N60 height
    Axis Info [cartesian|vertical]:
    - X[north]: Northing (metre)
    - Y[east]: Easting (metre)
    - H[up]: Gravity-related height (metre)
    Area of Use:
    - undefined
    Datum: Kartastokoordinaattijarjestelma (1966)
    - Ellipsoid: International 1924
    - Prime Meridian: Greenwich
    Sub CRS:
    - KKJ / Finland Uniform Coordinate System
    - N60 height
    >>> crs.sub_crs_list
    [<Projected CRS: EPSG:2393>
    Name: KKJ / Finland Uniform Coordinate System
    Axis Info [cartesian]:
    - X[north]: Northing (metre)
    - Y[east]: Easting (metre)
    Area of Use:
    - name: Finland - 25.5°E to 28.5°E onshore. Also all country.
    - bounds: (19.24, 59.75, 31.59, 70.09)
    Coordinate Operation:
    - name: Finland Uniform Coordinate System
    - method: Transverse Mercator
    Datum: Kartastokoordinaattijarjestelma (1966)
    - Ellipsoid: International 1924
    - Prime Meridian: Greenwich
    , <Vertical CRS: EPSG:5717>
    Name: N60 height
    Axis Info [vertical]:
    - H[up]: Gravity-related height (metre)
    Area of Use:
    - name: Finland - onshore.
    - bounds: (19.24, 59.75, 31.59, 70.09)
    Datum: Helsinki 1960
    - Ellipsoid: undefined
    - Prime Meridian: undefined
    ]
    >>> print(crs.sub_crs_list[0].coordinate_operation.to_wkt(pretty=True))
    CONVERSION["Finland Uniform Coordinate System",
        METHOD["Transverse Mercator",
            ID["EPSG",9807]],
        PARAMETER["Latitude of natural origin",0,
            ANGLEUNIT["degree",0.0174532925199433],
            ID["EPSG",8801]],
        PARAMETER["Longitude of natural origin",27,
            ANGLEUNIT["degree",0.0174532925199433],
            ID["EPSG",8802]],
        PARAMETER["Scale factor at natural origin",1,<commit_msg>Add missing definition of cop to docs<commit_after>.. _examples:

Getting Started
===============

There are examples of usage within the API documentation and tests. This
section is to demonstrate recommended usage.

Also see: :ref:`gotchas`


Using CRS
---------
For more usage examples and documentation see :class:`pyproj.crs.CRS`.

Initializing CRS
~~~~~~~~~~~~~~~~

The :class:`pyproj.crs.CRS` class can be initialized in many different ways.
Here are some examples of initialization.


.. code:: python

    >>> from pyproj import CRS
    >>> crs = CRS.from_epsg(4326)
    >>> crs = CRS.from_string("epsg:4326")
    >>> crs = CRS.from_proj4("+proj=latlon")
    >>> crs = CRS.from_user_input(4326)


Converting CRS to a different format
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. warning:: You will likely lose important projection
    information when converting to a PROJ string from
    another format. See: https://proj4.org/faq.html#what-is-the-best-format-for-describing-coordinate-reference-systems


.. code:: python

    >>> from pyproj import CRS
    >>> crs = CRS.from_epsg(4326)
    >>> crs.to_epsg()
    4326
    >>> crs.to_authority()
    ('EPSG', '4326')
    >>> crs = CRS.from_proj4("+proj=omerc +lat_0=-36 +lonc=147 +alpha=-54 +k=1 +x_0=0 +y_0=0 +gamma=0 +ellps=WGS84 +towgs84=0,0,0,0,0,0,0")
    >>> crs
    <Bound CRS: +proj=omerc +lat_0=-36 +lonc=147 +alpha=-54 +k=1 + ...>
    Name: unknown
    Axis Info [cartesian]:
    - E[east]: Easting (metre)
    - N[north]: Northing (metre)
    Area of Use:
    - undefined
    Coordinate Operation:
    - name: Transformation from unknown to WGS84
    - method: Position Vector transformation (geog2D domain)
    Datum: Unknown based on WGS84 ellipsoid
    - Ellipsoid: WGS 84
    - Prime Meridian: Greenwich
    Source CRS: unknown

    >>> print(crs.to_wkt(pretty=True))
    BOUNDCRS[
        SOURCECRS[
            PROJCRS["unknown",
                BASEGEOGCRS["unknown",
                    DATUM["Unknown based on WGS84 ellipsoid",
                        ELLIPSOID["WGS 84",6378137,298.257223563,
                            LENGTHUNIT["metre",1],
                            ID["EPSG",7030]]],
    ...
            PARAMETER["Z-axis rotation",0,
                ID["EPSG",8610]],
            PARAMETER["Scale difference",1,
                ID["EPSG",8611]]]]

    >>> from pyproj.enums import WktVersion
    >>> print(crs.to_wkt(WktVersion.WKT1_GDAL, pretty=True))
    PROJCS["unknown",
        GEOGCS["unknown",
            DATUM["Unknown_based_on_WGS84_ellipsoid",
                SPHEROID["WGS 84",6378137,298.257223563,
                    AUTHORITY["EPSG","7030"]],
                TOWGS84[0,0,0,0,0,0,0]],
            PRIMEM["Greenwich",0,
                AUTHORITY["EPSG","8901"]],
            UNIT["degree",0.0174532925199433,
                AUTHORITY["EPSG","9122"]]],
        PROJECTION["Hotine_Oblique_Mercator_Azimuth_Center"],
        PARAMETER["latitude_of_center",-36],
        PARAMETER["longitude_of_center",147],
        PARAMETER["azimuth",-54],
        PARAMETER["rectified_grid_angle",0],
        PARAMETER["scale_factor",1],
        PARAMETER["false_easting",0],
        PARAMETER["false_northing",0],
        UNIT["metre",1,
            AUTHORITY["EPSG","9001"]],
        AXIS["Easting",EAST],
        AXIS["Northing",NORTH]]

    >>> from pprint import pprint
    >>> pprint(crs.to_cf())
    {'azimuth_of_central_line': -54,
    'crs_wkt': 'BOUNDCRS[SOURCECRS[PROJCRS["unknown",BASEGEOGCRS["unknown",DATUM["Unknown '
    ...
                'difference",1,ID["EPSG",8611]]]]',
    'false_easting': 0.0,
    'false_northing': 0.0,
    'grid_mapping_name': 'oblique_mercator',
    'horizontal_datum_name': 'Unknown based on WGS84 ellipsoid',
    'inverse_flattening': 298.257223563,
    'latitude_of_projection_origin': -36.0,
    'longitude_of_prime_meridian': 0.0,
    'longitude_of_projection_origin': 147.0,
    'prime_meridian_name': 'Greenwich',
    'reference_ellipsoid_name': 'WGS 84',
    'scale_factor_at_projection_origin': 1.0,
    'semi_major_axis': 6378137.0,
    'semi_minor_axis': 6356752.314245179,
    'towgs84': [0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0]}


Extracting attributes from CRS
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

There are many attributes you can pull from the :class:`pyproj.crs.CRS`.
This is just a small subset of what is available.


.. code:: python

    >>> crs = CRS("urn:ogc:def:crs,crs:EPSG::2393,crs:EPSG::5717")
    >>> crs
    <Compound CRS: EPSG:3901>
    Name: KKJ / Finland Uniform Coordinate System + N60 height
    Axis Info [cartesian|vertical]:
    - X[north]: Northing (metre)
    - Y[east]: Easting (metre)
    - H[up]: Gravity-related height (metre)
    Area of Use:
    - undefined
    Datum: Kartastokoordinaattijarjestelma (1966)
    - Ellipsoid: International 1924
    - Prime Meridian: Greenwich
    Sub CRS:
    - KKJ / Finland Uniform Coordinate System
    - N60 height
    >>> crs.sub_crs_list
    [<Projected CRS: EPSG:2393>
    Name: KKJ / Finland Uniform Coordinate System
    Axis Info [cartesian]:
    - X[north]: Northing (metre)
    - Y[east]: Easting (metre)
    Area of Use:
    - name: Finland - 25.5°E to 28.5°E onshore. Also all country.
    - bounds: (19.24, 59.75, 31.59, 70.09)
    Coordinate Operation:
    - name: Finland Uniform Coordinate System
    - method: Transverse Mercator
    Datum: Kartastokoordinaattijarjestelma (1966)
    - Ellipsoid: International 1924
    - Prime Meridian: Greenwich
    , <Vertical CRS: EPSG:5717>
    Name: N60 height
    Axis Info [vertical]:
    - H[up]: Gravity-related height (metre)
    Area of Use:
    - name: Finland - onshore.
    - bounds: (19.24, 59.75, 31.59, 70.09)
    Datum: Helsinki 1960
    - Ellipsoid: undefined
    - Prime Meridian: undefined
    ]
    >>> cop = crs.sub_crs_list[0].coordinate_operation
    >>> print(cop.to_wkt(pretty=True))
    CONVERSION["Finland Uniform Coordinate System",
        METHOD["Transverse Mercator",
            ID["EPSG",9807]],
        PARAMETER["Latitude of natural origin",0,
            ANGLEUNIT["degree",0.0174532925199433],
            ID["EPSG",8801]],
        PARAMETER["Longitude of natural origin",27,
            ANGLEUNIT["degree",0.0174532925199433],
            ID["EPSG",8802]],
        PARAMETER["Scale factor at natural origin",1,
{'fraction_non_alphanumeric': 0.14952229299363057, 'fraction_numerical': 0.06337579617834395, 'mean_word_length': 2.847166921898928, 'pattern_counts': {'":': 0, '<': 11, '<?xml version=': 0, '>': 134, 'https://': 2, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6154192', 'n_tokens_mistral': 4968, 'n_tokens_neox': 4338, 'n_words': 913}