diff --git a/docs/api/transformer.rst b/docs/api/transformer.rst index 0d3fa2f51..a04bee726 100644 --- a/docs/api/transformer.rst +++ b/docs/api/transformer.rst @@ -6,7 +6,7 @@ Transformer The `pyproj.Transformer` has the capabilities of performing 2D, 3D, and 4D (time) transformations. It can do anything that the PROJ command line programs -:ref:`proj`, :ref:`cs2cs`, and :ref:`cct` can do. +:ref:`proj:proj`, :ref:`proj:cs2cs`, and :ref:`proj:cct` can do. This means that it allows translation between any pair of definable coordinate systems, including support for datum transformation. diff --git a/docs/concepts.rst b/docs/concepts.rst new file mode 100644 index 000000000..5fa64e313 --- /dev/null +++ b/docs/concepts.rst @@ -0,0 +1,209 @@ +.. _concepts: + +Concepts +======== + +pyproj is a Python interface to the :term:`PROJ` library. Most of what it does +comes down to answering two questions about a pair (or triple) of numbers: + +1. *Where on the Earth is this?* The numbers are only meaningful once you know + the :term:`Coordinate Reference System (CRS)` they belong to. pyproj + describes a CRS with the :class:`pyproj.crs.CRS` class. +2. *What are these same points in a different CRS?* Converting coordinates + between two CRSes is a :term:`coordinate operation`. pyproj does this with + the :class:`pyproj.transformer.Transformer` class. + +A third helper, :class:`pyproj.Geod`, answers questions like "how far apart +are these two points?" directly on the curved Earth without picking a +projection at all. + +This page explains the ideas behind these classes without much code. The +:ref:`examples` page shows how to use the classes themselves and the +:ref:`glossary` defines the terms used throughout the documentation. If you +already know what a CRS, a datum, and an EPSG code are, you can skip straight +to :ref:`examples`. + + +Coordinate Reference Systems (CRS) +---------------------------------- + +A pair of numbers like ``(-93.58, 42.03)`` does not identify a location on its +own. Is it longitude and latitude in degrees? Or is it latitude first? Is it +meters east and north of some origin? On which model of the Earth? A +**Coordinate Reference System** (CRS) is the description that answers those +questions so that the numbers can be tied to a real place. + +A CRS bundles a few things together: + +- A :term:`datum`: a model of the shape of the Earth (an :term:`ellipsoid`) + plus how that model is positioned relative to the real Earth. The + :term:`WGS 84` datum used by GPS is the most common one you will meet. +- A coordinate system: which axes there are, what units they use, and what + order they come in (see :term:`axis order`). +- For a projected CRS, the :term:`projection`: the recipe for flattening the + curved Earth onto a plane. + +The :class:`pyproj.crs.CRS` class stores all of this and lets you inspect each +part (``crs.datum``, ``crs.ellipsoid``, ``crs.axis_info``, +``crs.coordinate_operation``, ...). + +Geographic CRS +~~~~~~~~~~~~~~ + +A :term:`geographic CRS` describes positions as angles on the ellipsoid: +longitude and latitude, usually in degrees. No projection is involved. The +best-known example is WGS 84 (``EPSG:4326``), the datum used by GPS receivers +and many web APIs. + +Projected CRS +~~~~~~~~~~~~~ + +A :term:`projected CRS` takes a geographic CRS and applies a map projection to +it so that positions become distances on a flat plane, usually in meters. +Working on a plane makes distances, areas, and gridded data much simpler to +handle. Common examples are the :term:`UTM` zones (for example +``EPSG:26917``, NAD83 / UTM zone 17N) and Web Mercator (``EPSG:3857``), the +projection used by most online map tiles. + +Every projection distorts something (shapes, areas, distances, or directions) +and each one is designed to keep that distortion small over a particular +region, its :term:`area of use`. Using a CRS far outside its area of use +gives poor or nonsensical results. PROJ documents the theory in its +:ref:`cartographic projection ` page and lists every +supported projection with pictures in :ref:`proj:projections`. + +Why it matters +~~~~~~~~~~~~~~ + +The same numbers can refer to different places in different CRSes. Two +datasets that both report "longitude and latitude" may still disagree by tens +of meters if they use different datums. When combining data from different +sources, make sure the CRS of each source is known and compatible, transforming +the coordinates into one common CRS where necessary. + + +How a CRS is written down +------------------------- + +There are several textual ways to describe a CRS, and pyproj accepts all of +them. Understanding the three most common ones explains most of what you will +see in the examples. + +Authority codes (EPSG:4326) +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Rather than write out the full definition of a CRS every time, organizations +maintain registries of predefined CRSes where each entry has a short numeric +code. The most widely used registry is the :term:`EPSG` dataset, and an +:term:`authority code` such as ``EPSG:4326`` simply means "entry 4326 in the +EPSG registry", which happens to be WGS 84 longitude/latitude. PROJ ships a +copy of this registry as a database, so codes work without a network +connection. + +EPSG is not the only authority. PROJ also knows codes from ``ESRI``, ``IGNF``, +``OGC``, and a few others; :func:`pyproj.database.get_authorities` lists them. +In pyproj you can pass a code as an integer (``4326``, assumed to be EPSG), a +string (``"EPSG:4326"``), or a tuple (``("EPSG", "4326")``). + +To find the code for a CRS you can search the PROJ database from Python with +:func:`pyproj.database.query_crs_info` or, for UTM zones, +:func:`pyproj.database.query_utm_crs_info`, or browse online at +`epsg.org `__ or `epsg.io `__. +An authority code is the recommended way to identify a CRS when one exists +for it, because it is short, unambiguous, and cannot lose information. + +Well-Known Text (WKT) +~~~~~~~~~~~~~~~~~~~~~ + +:term:`Well-Known Text (WKT)` is a standard, human-readable format that spells +out the complete definition of a CRS: its name, datum, ellipsoid, axes, +units, projection parameters, and authority identifiers. It is what +``print(crs.to_wkt(pretty=True))`` shows you and what most geospatial file +formats and databases store internally. WKT can describe any CRS, including +ones that have no authority code, without losing information. There are two +generations of the format; WKT2 is the current one and is preferred. + +PROJ strings (+proj=latlon) +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +A :term:`PROJ string` is PROJ's own compact ``+key=value`` syntax, for example +``+proj=utm +zone=17 +datum=NAD83`` or ``+proj=latlon``. The ``+proj`` key +names the projection and the remaining keys set its parameters; the available +keys for each projection are documented on the PROJ page for that projection +in :ref:`proj:projections`. ``+proj=latlon`` (an alias of ``+proj=longlat``) is the +special case of "no projection, just longitude and latitude", so +``+proj=latlon`` and ``EPSG:4326`` describe a very similar CRS. + +PROJ strings are convenient for building a CRS by hand, and much of the older +documentation and code you will find online uses them. However, they cannot +express everything a CRS can contain, so converting a CRS to a PROJ string may +silently drop information. Prefer an authority code or WKT for storing or +sharing a CRS; see :ref:`gotchas` and the PROJ :ref:`FAQ ` for details. + +Other forms +~~~~~~~~~~~ + +pyproj also accepts PROJ JSON (a JSON equivalent of WKT), Python dictionaries +of PROJ parameters, and objects from other libraries that have a ``to_wkt()`` +method. :meth:`pyproj.crs.CRS.from_user_input` lists everything that is +accepted, and :ref:`examples` shows each form in use. + + +Transformations between CRSes +----------------------------- + +A :term:`coordinate operation` takes coordinates expressed in one CRS and +produces the coordinates of the same physical points in another CRS. In +everyday use any such operation is called a "transformation", and that is the +sense in which pyproj's :class:`pyproj.transformer.Transformer` class is +named. PROJ (following the ISO 19111 standard) reserves the word for one of +two more specific kinds of operation: + +- A :term:`conversion` is pure mathematics with an exact answer, such as + turning longitude/latitude into UTM meters on the same datum. +- A :term:`transformation` changes datum, for example from NAD27 to WGS 84. + Because the relationship between two datums is measured rather than defined, + transformations are approximate, have an associated accuracy, and the most + accurate ones often rely on :term:`transformation grid` files that are + downloaded separately (see :ref:`transformation_grids`). + +Going between two arbitrary CRSes often involves both kinds, chained +together. When you call ``Transformer.from_crs(source_crs, target_crs)`` +pyproj asks PROJ to find the best available chain of operations between the +two CRSes for your area of interest and wraps it in a single +:class:`pyproj.transformer.Transformer`; the transformer's ``repr`` tells you +which kind it ended up with (``Conversion Transformer`` or +``Transformation Transformer``). The PROJ page on +:doc:`geodetic transformation ` explains what +happens underneath. + +Axis order +~~~~~~~~~~ + +One surprise for newcomers is :term:`axis order`. Many CRS definitions, +including ``EPSG:4326``, officially list latitude *first* and longitude +second, while many software packages and file formats (GeoJSON, for example) +assume longitude/latitude (x/y). +pyproj follows the official definition by default, so +``transformer.transform(lat, lon)`` is correct for ``EPSG:4326`` input. If you +prefer to always work in x/y (longitude/latitude) order, create the +transformer with ``always_xy=True``. The :ref:`gotchas` page has more on this. + + +Geodesic calculations +--------------------- + +Sometimes you do not want a projection at all; you want the distance between +two points or the area of a polygon *on the curved surface of the Earth*. +These are :term:`geodesic` calculations and pyproj provides them through +:class:`pyproj.Geod`, which only needs to know the ellipsoid (for example +WGS 84). See PROJ's :doc:`geodesic calculations ` page for the +background. + + +Further reading +--------------- + +- PROJ's own :ref:`quick start ` and + :ref:`cartographic projection ` pages. +- The PROJ :doc:`glossary ` and :ref:`FAQ `. diff --git a/docs/examples.rst b/docs/examples.rst index fa42d8d77..2f6ed0ece 100644 --- a/docs/examples.rst +++ b/docs/examples.rst @@ -3,38 +3,67 @@ Getting Started =============== -There are examples of usage within the API documentation and tests. This -section is to demonstrate recommended usage. +This section demonstrates recommended usage of the three main classes in +pyproj: + +- :class:`pyproj.crs.CRS` describes a + :term:`Coordinate Reference System (CRS)`: the model of the Earth, the + axes, and the map projection (if any) that give meaning to a set of + coordinates. +- :class:`pyproj.transformer.Transformer` converts coordinates from one CRS + to another. +- :class:`pyproj.Geod` calculates distances and areas on the curved surface + of the Earth. + +New to coordinate reference systems, EPSG codes, or PROJ? Read the +:ref:`concepts` page first. Unfamiliar terms are defined in the +:ref:`glossary`. There are also more examples of usage within the API +documentation and tests. Also see: :ref:`gotchas` -Using Coordinate Reference Systems (CRS) ----------------------------------------- -For more usage examples and documentation see :class:`pyproj.crs.CRS`. +Using the CRS class +------------------- -Initializing CRS -~~~~~~~~~~~~~~~~ +A :class:`pyproj.crs.CRS` object holds the definition of a +:term:`Coordinate Reference System (CRS)`. For more usage examples and +documentation see :class:`pyproj.crs.CRS`. -The :class:`pyproj.crs.CRS` class can be initialized in many different ways. -Here are some examples of initialization. +Creating a CRS +~~~~~~~~~~~~~~ + +The :class:`pyproj.crs.CRS` class can be initialized from any of the +common ways of describing a CRS. Here are some examples; all four produce +the same CRS, WGS 84 longitude/latitude. .. 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) + >>> crs = CRS.from_epsg(4326) # EPSG code as an integer + >>> crs = CRS.from_string("EPSG:4326") # authority string "AUTHORITY:CODE" + >>> crs = CRS.from_proj4("+proj=latlon") # PROJ string + >>> crs = CRS.from_user_input(4326) # any of the above (and more) + +``4326`` is an :term:`authority code` in the :term:`EPSG` registry and +``+proj=latlon`` is a :term:`PROJ string`; see +:ref:`concepts` for what these mean. :meth:`pyproj.crs.CRS.from_user_input` +lists every kind of input that is accepted, including +:term:`Well-Known Text (WKT)` and PROJ JSON, and is what the ``CRS(...)`` +constructor and most other pyproj functions use to interpret CRS arguments. Converting CRS to a different format ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +A CRS can be exported as an :term:`authority code`, +:term:`Well-Known Text (WKT)` in several versions, a :term:`PROJ string`, +or a `CF `__ grid mapping dictionary. + .. 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 + another format. See: https://proj.org/faq.html#what-is-the-best-format-for-describing-coordinate-reference-systems .. code:: python @@ -128,7 +157,9 @@ 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. +This is just a small subset of what is available. The example below uses an +:term:`OGC` :term:`URN` that combines two EPSG codes (a projected CRS and a +vertical CRS) into a single :term:`compound CRS`. .. code:: python @@ -231,6 +262,10 @@ Find UTM CRS by Latitude and Longitude Transformations from CRS to CRS ------------------------------- +A :class:`pyproj.transformer.Transformer` converts coordinates from one CRS +to another, including any change of :term:`datum` between them. See +:ref:`concepts` for background on what happens during a transformation. + Step 1: Inspect CRS definition to ensure proper area of use and axis order ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ For more options available for inspection, usage examples, @@ -389,8 +424,10 @@ Step 2: Create Transformer to convert from geodetic CRS to CRS Geodesic calculations --------------------- -This is useful if you need to calculate the distance between two -points or the area of a geometry on Earth's surface. + +:term:`Geodesic` calculations are useful if you need to calculate the +distance between two points or the area of a geometry on Earth's surface +without projecting it onto a plane. For more examples of usage and documentation, see :class:`pyproj.Geod`. diff --git a/docs/glossary.rst b/docs/glossary.rst new file mode 100644 index 000000000..bd37578f1 --- /dev/null +++ b/docs/glossary.rst @@ -0,0 +1,173 @@ +.. _glossary: + +Glossary +======== + +Short definitions of terms used throughout the pyproj documentation. For a +longer, narrative introduction see :ref:`concepts`. The PROJ project also +maintains its own :doc:`glossary `. + +.. glossary:: + :sorted: + + Area of use + The geographic region a :term:`Coordinate Reference System (CRS)` or + :term:`coordinate operation` is intended for. Outside of it the + projection may be badly distorted or the transformation inaccurate. + Available as :attr:`pyproj.crs.CRS.area_of_use`. + + Authority code + A short identifier for a predefined CRS, datum, ellipsoid, or operation + in a registry, written as ``AUTHORITY:CODE``, for example ``EPSG:4326`` + or ``ESRI:54009``. The most common authority is :term:`EPSG`. + :func:`pyproj.database.get_authorities` lists the authorities known to + PROJ. + + Axis order + The order in which a CRS lists its coordinates. Many geographic CRSes, + including ``EPSG:4326``, define latitude first and longitude second, + whereas many software packages assume x/y (longitude/latitude). Check + :attr:`pyproj.crs.CRS.axis_info` or use ``always_xy=True`` when + creating a :class:`pyproj.transformer.Transformer`. See also the + :ref:`gotchas` page. + + Bound CRS + A CRS bundled with an explicit :term:`transformation` to a target CRS + (usually WGS 84), for example a PROJ string containing ``+towgs84=``. + Represented by :class:`pyproj.crs.BoundCRS`. + + Compound CRS + A CRS made of a horizontal CRS plus a :term:`vertical CRS`, so that + coordinates carry a height as well as a position. Represented by + :class:`pyproj.crs.CompoundCRS`. + + Conversion + In the strict sense used by PROJ and the ISO 19111 standard, a + :term:`coordinate operation` defined purely by mathematics, with no + change of :term:`datum`, such as applying a map :term:`projection`. + Conversions are exact. Compare with :term:`transformation`. + + Coordinate operation + Any process that takes coordinates in one CRS and produces coordinates + in another. Either a :term:`conversion` or a :term:`transformation`, or + a chain of both. Represented in pyproj by + :class:`pyproj.transformer.Transformer`. + + Coordinate Reference System (CRS) + The full description needed to tie coordinates to positions on the + Earth: a :term:`datum`, a coordinate system (axes, units, and + :term:`axis order`), and for a :term:`projected CRS` a + :term:`projection`. Represented by :class:`pyproj.crs.CRS`. + + Datum + A model of the Earth's shape (an :term:`ellipsoid`) together with how + that model is positioned and oriented relative to the real Earth. Two + CRSes with different datums can report different coordinates for the + same physical location. Available as :attr:`pyproj.crs.CRS.datum`. + + Ellipsoid + The slightly flattened sphere used to approximate the Earth's shape, + defined by a semi-major axis and a flattening. Examples: WGS 84, + GRS 1980, Clarke 1866. Available as :attr:`pyproj.crs.CRS.ellipsoid`. + + EPSG + The most widely used registry of CRS, datum, ellipsoid, and coordinate + operation definitions, originally created by the European Petroleum + Survey Group and now maintained by the International Association of Oil + & Gas Producers (IOGP) at `epsg.org `__. PROJ ships + a copy of it as its database, so ``EPSG:4326`` style + :term:`authority codes ` work offline. + + Geodesic + The shortest path between two points on the surface of an + :term:`ellipsoid`. Geodesic calculations give distances, azimuths, and + areas on the curved Earth without using a projection. Provided by + :class:`pyproj.Geod`. + + Geographic CRS + A CRS whose coordinates are angles on the :term:`ellipsoid`, i.e. + longitude and latitude, usually in degrees. Example: WGS 84 + (``EPSG:4326``). Represented by :class:`pyproj.crs.GeographicCRS`. + + OGC + The Open Geospatial Consortium, the standards body that (jointly with + ISO) publishes the specifications PROJ implements, including + :term:`Well-Known Text (WKT)` and the ``urn:ogc:def:...`` :term:`URN` + scheme for identifying CRSes. + + Prime meridian + The line of zero longitude for a CRS. Almost always Greenwich, but some + historical CRSes use others (Paris, Ferro, ...). + + PROJ + The C/C++ library (https://proj.org) that pyproj wraps. PROJ implements + the projections and transformations and ships the CRS database. + + PROJ string + PROJ's compact ``+key=value`` syntax for describing a CRS or a + pipeline, for example ``+proj=utm +zone=17 +datum=NAD83`` or + ``+proj=latlon``. Convenient, but it cannot express everything in a + CRS, so prefer an :term:`authority code` or :term:`Well-Known Text (WKT)` + for storing a CRS. See :ref:`gotchas`. + + Projected CRS + A CRS in which a map :term:`projection` has been applied to a + :term:`geographic CRS`, so that coordinates are distances (usually + meters) on a plane. Examples: :term:`UTM` zones, Web Mercator + (``EPSG:3857``). Represented by :class:`pyproj.crs.ProjectedCRS`. + + Projection + The mathematical recipe for flattening the curved surface of the Earth + onto a plane, such as Transverse Mercator or Lambert Conformal Conic. + Every projection distorts some combination of shape, area, distance, or + direction. PROJ lists all supported projections in :ref:`proj:projections`. + + Transformation + In everyday use, and in the names of :class:`pyproj.transformer.Transformer` + and its ``transform`` method, any :term:`coordinate operation` from one + CRS to another. In the stricter sense used by PROJ and the ISO 19111 + standard, only an operation between two different :term:`datums + `; because such an operation is based on measurements rather + than pure mathematics it is approximate and has an accuracy, and the + most accurate ones often need a :term:`transformation grid`. Compare + with :term:`conversion`. + + Transformation grid + A data file of measured corrections that PROJ uses to make some + :term:`transformations ` more accurate. Grids are not + bundled with pyproj wheels; see :ref:`transformation_grids`. + + URN + Uniform Resource Name: a standard syntax for persistent identifiers. + The :term:`OGC` defines a URN form of :term:`authority codes `, for example ``urn:ogc:def:crs:EPSG::4326`` is the same CRS as + ``EPSG:4326``, and several codes can be combined into a + :term:`compound CRS` with ``urn:ogc:def:crs,crs:EPSG::2393,crs:EPSG::5717``. + :class:`pyproj.crs.CRS` accepts both forms. + + UTM + Universal Transverse Mercator: a projection system that divides the + Earth into 60 longitude zones, each 6° wide, with a northern and + southern hemisphere variant of each zone. Each zone/hemisphere/datum + combination is a separate :term:`projected CRS ` with + coordinates in meters, for example ``EPSG:26917`` (NAD83 / UTM zone + 17N) and ``EPSG:32617`` (WGS 84 / UTM zone 17N). Use + :func:`pyproj.database.query_utm_crs_info` to find the zone for a + location. + + Vertical CRS + A CRS describing heights only, for example height above a particular + sea-level model. Usually combined with a horizontal CRS in a + :term:`compound CRS`. Represented by :class:`pyproj.crs.VerticalCRS`. + + Well-Known Text (WKT) + A standard text format that spells out the complete definition of a + CRS (datum, ellipsoid, axes, units, projection parameters, identifiers). + Lossless, and the preferred way to store a CRS that has no + :term:`authority code`. Two versions exist; WKT2 is current and + preferred. Produced by :meth:`pyproj.crs.CRS.to_wkt`. + + WGS 84 + World Geodetic System 1984, the :term:`datum` (and :term:`ellipsoid`) + used by GPS and most web mapping. As a :term:`geographic CRS` it is + ``EPSG:4326``. diff --git a/docs/gotchas.rst b/docs/gotchas.rst index 9aee75f77..0e830cc2d 100644 --- a/docs/gotchas.rst +++ b/docs/gotchas.rst @@ -6,21 +6,23 @@ Gotchas/FAQ This is a page for some suggestions, gotchas, and FAQs. Also see: + - :ref:`concepts` - :ref:`examples` - - :ref:`PROJ FAQ ` + - :ref:`glossary` + - :ref:`PROJ FAQ ` What are the best formats to store the CRS information? -------------------------------------------------------- -In general, `Well-Known Text (WKT) `__ -or `Spatial Reference ID -(SRID) `__, such as EPSG -codes, are the preferred formats to describe a CRS. +In general, :term:`Well-Known Text (WKT)` or a `Spatial Reference ID +(SRID) `__, such as +an :term:`EPSG` :term:`authority code`, are the preferred formats to describe +a CRS. .. note:: WKT2 is preferred over WKT1. -PROJ strings can be lossy for storing CRS information. +:term:`PROJ strings ` can be lossy for storing CRS information. If you can avoid it, it is best to not use them. Additionally, PROJ strings will likely not be supported in future major version of PROJ for storing CRS information. diff --git a/docs/history.rst b/docs/history.rst index 8b48ef0ae..836065082 100644 --- a/docs/history.rst +++ b/docs/history.rst @@ -3,6 +3,7 @@ Change Log Latest ------ +- DOC: Add concepts and glossary pages and make Getting Started friendlier to newcomers (issue #1507) 3.8.0 ------ diff --git a/docs/index.rst b/docs/index.rst index b95b15f58..3870d4f06 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -20,9 +20,11 @@ GitHub Repository: https://github.com/pyproj4/pyproj :caption: Contents: installation + concepts examples transformation_grids gotchas + glossary api/index cli advanced_examples diff --git a/docs/installation.rst b/docs/installation.rst index 2601633a6..afa56c57f 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -91,7 +91,7 @@ Setup PROJ PROJ is required when building from source. -:ref:`PROJ Installation Instructions ` +:ref:`PROJ Installation Instructions ` You can also download PROJ from: diff --git a/docs/transformation_grids.rst b/docs/transformation_grids.rst index cbdd633c0..07e1b6295 100644 --- a/docs/transformation_grids.rst +++ b/docs/transformation_grids.rst @@ -6,7 +6,7 @@ Transformation Grids Transformation grids improve accuracy when you are performing datum transformations. More information about the data available is located under the PROJ -:ref:`resource files ` documentation. +:ref:`resource files ` documentation. .. note:: `pyproj` API for managing the :ref:`data_directory` and :ref:`network_api`. @@ -20,7 +20,7 @@ PROJ 7+ ^^^^^^^^ PROJ 7.0 has introduced, per -:ref:`PROJ RFC 4: Remote access to grids and GeoTIFF grids `, +:ref:`PROJ RFC 4: Remote access to grids and GeoTIFF grids `, the capability to work with grid files that are not installed on the local machine where PROJ is executed. Available methods for download include: @@ -53,11 +53,11 @@ Available methods for download include: wget --mirror https://cdn.proj.org/ -P ${PROJ_DOWNLOAD_DIR} -- The :ref:`projsync ` command line program. +- The :ref:`projsync ` command line program. - `pyproj sync `__ command line program (pyproj 3+; useful if you use pyproj wheels). -- Enabling :ref:`PROJ network ` capabilities. See also :ref:`network_api`. +- Enabling :ref:`PROJ network ` capabilities. See also :ref:`network_api`. - Download stable from https://download.osgeo.org/proj or latest from https://github.com/OSGeo/PROJ-data diff --git a/pyproj/_context.pyx b/pyproj/_context.pyx index cdb9f1ca0..d51513f2b 100644 --- a/pyproj/_context.pyx +++ b/pyproj/_context.pyx @@ -38,7 +38,7 @@ def set_use_global_context(active=None): through the duration of each python session and is closed once the program terminates. - .. note:: To modify network settings see: :ref:`network`. + .. note:: To modify network settings see: :ref:`proj:network`. Parameters ---------- @@ -70,9 +70,9 @@ def get_user_data_dir(create=False): See: :c:func:`proj_context_get_user_writable_directory` This is where grids will be downloaded when - :ref:`PROJ network ` capabilities + :ref:`PROJ network ` capabilities are enabled. It is also the default download location for the - :ref:`projsync` command line program. + :ref:`proj:projsync` command line program. Parameters ---------- diff --git a/pyproj/proj.py b/pyproj/proj.py index ff95f0862..5b2844b10 100644 --- a/pyproj/proj.py +++ b/pyproj/proj.py @@ -7,7 +7,7 @@ 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 +:ref:`proj:projections` for examples of key/value pairs defining different map projections. Calling a Proj class instance with the arguments lon, lat will @@ -53,7 +53,7 @@ def __init__( 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 + :ref:`proj:projections` for examples of key/value pairs defining different map projections. Parameters diff --git a/pyproj/transformer.py b/pyproj/transformer.py index c51139b88..4863fccf9 100644 --- a/pyproj/transformer.py +++ b/pyproj/transformer.py @@ -728,7 +728,7 @@ def from_crs( 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`. + ``only_best_default`` setting of :ref:`proj:proj-ini`. The only_best kwarg overrides the default value if set. Requires PROJ 9.2+.