""" project - Project data onto lines or great circles, or generate tracks. """ from typing import Literal import numpy as np import pandas as pd from pygmt.clib import Session from pygmt.exceptions import GMTInvalidInput from pygmt.helpers import ( build_arg_list, fmt_docstring, kwargs_to_strings, use_alias, validate_output_table_type, ) @fmt_docstring @use_alias( A="azimuth", C="center", E="endpoint", F="convention", G="generate", L="length", N="flat_earth", Q="unit", S="sort", T="pole", V="verbose", W="width", Z="ellipse", f="coltypes", ) @kwargs_to_strings(E="sequence", L="sequence", T="sequence", W="sequence", C="sequence") def project( data=None, x=None, y=None, z=None, output_type: Literal["pandas", "numpy", "file"] = "pandas", outfile: str | None = None, **kwargs, ) -> pd.DataFrame | np.ndarray | None: r""" Project data onto lines or great circles, or generate tracks. Project reads arbitrary :math:`(x, y [, z])` data and returns any combination of :math:`(x, y, z, p, q, r, s)`, where :math:`(p, q)` are the coordinates in the projection, :math:`(r, s)` is the position in the :math:`(x, y)` coordinate system of the point on the profile (:math:`q = 0` path) closest to :math:`(x, y)`, and :math:`z` is all remaining columns in the input (beyond the required :math:`x` and :math:`y` columns). Alternatively, ``project`` may be used to generate :math:`(r, s, p)` triplets at equal increments along a profile using the ``generate`` parameter. In this case, the value of ``data`` is ignored (you can use, e.g., ``data=None``). Projections are defined in any (but only) one of three ways: 1. By a ``center`` and an ``azimuth`` in degrees clockwise from North. 2. By a ``center`` and ``endpoint`` of the projection path. 3. By a ``center`` and a ``pole`` position. To spherically project data along a great circle path, an oblique coordinate system is created which has its equator along that path, and the zero meridian through the Center. Then the oblique longitude (:math:`p`) corresponds to the distance from the Center along the great circle, and the oblique latitude (:math:`q`) corresponds to the distance perpendicular to the great circle path. When moving in the increasing (:math:`p`) direction, (toward B or in the azimuth direction), the positive (:math:`q`) direction is to your left. If a Pole has been specified, then the positive (:math:`q`) direction is toward the pole. To specify an oblique projection, use the ``pole`` parameter to set the pole. Then the equator of the projection is already determined and the ``center`` parameter is used to locate the :math:`p = 0` meridian. The center *cx/cy* will be taken as a point through which the :math:`p = 0` meridian passes. If you do not care to choose a particular point, use the South pole (*cx* = 0, *cy* = -90). Data can be selectively windowed by using the ``length`` and ``width`` parameters. If ``width`` is used, the projection width is set to use only data with :math:`w_{{min}} < q < w_{{max}}`. If ``length`` is set, then the length is set to use only those data with :math:`l_{{min}} < p < l_{{max}}`. If the ``endpoint`` parameter has been used to define the projection, then ``length="w"`` may be used to window the length of the projection to exactly the span from O to B. Flat Earth (Cartesian) coordinate transformations can also be made. Set ``flat_earth=True`` and remember that azimuth is clockwise from North (the y axis), NOT the usual cartesian theta, which is counterclockwise from the x axis. azimuth = 90 - theta. No assumptions are made regarding the units for :math:`x, y, r, s, p, q, dist, l_{{min}}, l_{{max}}, w_{{min}}, w_{{max}}`. If ``unit`` is selected, map units are assumed and :math:`x, y, r, s` must be in degrees and :math:`p, q, dist, l_{{min}}, l_{{max}}, w_{{min}}, w_{{max}}` will be in km. Calculations of specific great-circle and geodesic distances or for back-azimuths or azimuths are better done using :gmt-docs:`mapproject` as project is strictly spherical. Full option list at :gmt-docs:`project.html` {aliases} Parameters ---------- data : str, {table-like} Pass in (x, y, z) or (longitude, latitude, elevation) values by providing a file name to an ASCII data table, a 2-D {table-classes}. {output_type} {outfile} center : str or list *cx*/*cy*. Set the origin of the projection, in Definition 1 or 2. If Definition 3 is used, then *cx/cy* are the coordinates of a point through which the oblique zero meridian (:math:`p = 0`) should pass. The *cx/cy* is not required to be 90 degrees from the pole. azimuth : float or str Define the azimuth of the projection (Definition 1). endpoint : str or list *bx*/*by*. Define the end point of the projection path (Definition 2). convention : str Specify the desired output using any combination of **xyzpqrs**, in any order [Default is **xypqrsz**]. Do not space between the letters. Use lower case. The output will be columns of values corresponding to your ``convention``. The **z** flag is special and refers to all numerical columns beyond the leading **x** and **y** in your input record. The **z** flag also includes any trailing text (which is placed at the end of the record regardless of the order of **z** in ``convention``). **Note**: If ``generate`` is True, then the output order is hardwired to be **rsp** and ``convention`` is not allowed. generate : str *dist* [/*colat*][**+c**\|\ **h**]. Create :math:`(r, s, p)` output data every *dist* units of :math:`p` (See ``unit`` parameter). Alternatively, append */colat* for a small circle instead [Default is a colatitude of 90, i.e., a great circle]. If setting a pole with ``pole`` and you want the small circle to go through *cx*/*cy*, append **+c** to compute the required colatitude. Use ``center`` and ``endpoint`` to generate a circle that goes through the center and end point. Note, in this case the center and end point cannot be farther apart than :math:`2|\mbox{{colat}}|`. Finally, if you append **+h** then we will report the position of the pole as part of the segment header [Default is no header]. **Note**: No input is read and the value of ``data``, ``x``, ``y``, and ``z`` is ignored if ``generate`` is used. length : str or list [**w**\|\ *l_min*/*l_max*]. Project only those data whose *p* coordinate is within :math:`l_{{min}} < p < l_{{max}}`. If ``endpoint`` has been set, then you may alternatively use **w** to stay within the distance from ``center`` to ``endpoint``. flat_earth : bool Make a Cartesian coordinate transformation in the plane. [Default is ``False``; plane created with spherical trigonometry.] unit : bool Set units for :math:`x, y, r, s` to degrees and :math:`p, q, dist, l_{{min}}, l_{{max}}, w_{{min}}, w_{{max}}` to km. [Default is ``False``; all arguments use the same units] sort : bool Sort the output into increasing :math:`p` order. Useful when projecting random data into a sequential profile. pole : str or list *px*/*py*. Set the position of the rotation pole of the projection. (Definition 3). {verbose} width : str or list *w_min*/*w_max*. Project only those data whose :math:`q` coordinate is within :math:`w_{{min}} < q < w_{{max}}`. ellipse : str *major*/*minor*/*azimuth* [**+e**\|\ **n**]. Used in conjunction with ``center`` (sets its center) and ``generate`` (sets the distance increment) to create the coordinates of an ellipse with *major* and *minor* axes given in km (unless ``flat_earth`` is given for a Cartesian ellipse) and the *azimuth* of the major axis in degrees. Append **+e** to adjust the increment set via ``generate`` so that the the ellipse has equal distance increments [Default uses the given increment and closes the ellipse]. Instead, append **+n** to set a specific number of unique equidistant data via ``generate``. For degenerate ellipses you can just supply a single *diameter* instead. A geographic diameter may be specified in any desired unit other than km by appending the unit (e.g., 3-D for degrees) [Default is km]; the increment is assumed to be in the same unit. **Note**: For the Cartesian ellipse (which requires ``flat_earth``), the *direction* is counter-clockwise from the horizontal instead of an *azimuth*. {coltypes} Returns ------- ret Return type depends on ``outfile`` and ``output_type``: - ``None`` if ``outfile`` is set (output will be stored in file set by ``outfile``) - :class:`pandas.DataFrame` or :class:`numpy.ndarray` if ``outfile`` is not set (depends on ``output_type``) """ if kwargs.get("C") is None: raise GMTInvalidInput("The `center` parameter must be specified.") if kwargs.get("G") is None and data is None: raise GMTInvalidInput( "The `data` parameter must be specified unless `generate` is used." ) if kwargs.get("G") is not None and kwargs.get("F") is not None: raise GMTInvalidInput( "The `convention` parameter is not allowed with `generate`." ) output_type = validate_output_table_type(output_type, outfile=outfile) column_names = None if output_type == "pandas" and kwargs.get("G") is not None: column_names = list("rsp") with Session() as lib: with ( lib.virtualfile_in( check_kind="vector", data=data, x=x, y=y, z=z, required_z=False, required_data=False, ) as vintbl, lib.virtualfile_out(kind="dataset", fname=outfile) as vouttbl, ): lib.call_module( module="project", args=build_arg_list(kwargs, infile=vintbl, outfile=vouttbl), ) return lib.virtualfile_to_dataset( vfname=vouttbl, output_type=output_type, column_names=column_names, )