Skip to main content
`Ctrl`+`K`

# Prjprm

class astropy.wcs.Prjprm

  Bases: `object`

  Class that contains information needed to project or deproject native spherical coordinates. It consists of certain members that must be set by the user (given) and others that are set by the WCSLIB routines (returned). Some of the latter are supplied for informational purposes and others are for internal use only.

  Attributes Summary

  `bounds` | Controls bounds checking.
  `category` | Read-only. Projection category matching the value of the relevant `wcs` module constants:
  `code` | Three-letter projection code defined by the FITS standard.
  `conformal` | Read-only. True if the projection is conformal.
  `divergent` | Read-only. True if the projection diverges in latitude.
  `equiareal` | Read-only. True if the projection is equal area.
  `global_projection` | Read-only. True if the projection can represent the whole sphere in a finite, non-overlapped mapping.
  `m` | Read-only. Intermediate integer value (used only for the `ZPN` and `HPX` projections).
  `n` | Read-only. Intermediate integer value (used only for the `ZPN` and `HPX` projections).
  `name` | Read-only. Long name of the projection.
  `phi0` | The native longitude, \(\phi_0\) (in degrees) of the reference point, i.e. the point `(x,y) = (0,0)`.
  `pv` | Projection parameters.
  `pvrange` | Read-only. Range of projection parameter indices: 100 times the first allowed index plus the number of parameters, e.g. `TAN` is 0 (no parameters), `SZP` is 103 (1 to 3), and `ZPN` is 30 (0 to 29).
  `r0` | The radius of the generating sphere for the projection, a linear scaling parameter.
  `simplezen` | Read-only. True if the projection is a radially-symmetric zenithal projection.
  `theta0` | the native latitude, \(\theta_0\) (in degrees) of the reference point, i.e. the point `(x,y) = (0,0)`.
  `w` | Read-only. Intermediate floating-point values derived from the projection parameters, cached here to save recomputation.
  `x0` | Read-only. The offset in `x` used to force \((x,y) = (0,0)\) at \((\phi_0, \theta_0)\).
  `y0` | Read-only. The offset in `y` used to force \((x,y) = (0,0)\) at \((\phi_0, \theta_0)\).

  Methods Summary

  `get_pvi` | Set/Get projection parameters for specific index.
  `prjs2x` | Project native spherical coordinates \((\phi,\theta)\) to Cartesian `(x,y)` coordinates in the plane of projection.
  `prjx2s` | Deproject Cartesian `(x,y)` coordinates in the plane of projection to native spherical coordinates \((\phi,\theta)\).
  `set`(/) | This method sets up a `Prjprm` object according to information supplied within it.
  `set_pvi` | Set/Get projection parameters for specific index.

  Attributes Documentation

  bounds

    Controls bounds checking. If `bounds&1` then enable strict bounds checking for the spherical-to-Cartesian (`s2x`) transformation for the `AZP`, `SZP`, `TAN`, `SIN`, `ZPN`, and `COP` projections. If `bounds&2` then enable strict bounds checking for the Cartesian-to-spherical transformation (`x2s`) for the `HPX` and `XPH` projections. If `bounds&4` then the Cartesian- to-spherical transformations (`x2s`) will invoke WCSLIB’s `prjbchk()` to perform bounds checking on the computed native coordinates, with a tolerance set to suit each projection. bounds is set to 7 during initialization by default which enables all checks. Zero it to disable all checking.

    It is not necessary to reset the `Prjprm` struct (via `Prjprm.set()`) when `bounds` is changed.

  category

    Read-only. Projection category matching the value of the relevant `wcs` module constants:

    PRJ_ZENITHAL, PRJ_CYLINDRICAL, PRJ_PSEUDOCYLINDRICAL, PRJ_CONVENTIONAL, PRJ_CONIC, PRJ_POLYCONIC, PRJ_QUADCUBE, and PRJ_HEALPIX.

  code

    Three-letter projection code defined by the FITS standard.

  conformal

    Read-only. True if the projection is conformal.

  divergent

    Read-only. True if the projection diverges in latitude.

  equiareal

    Read-only. True if the projection is equal area.

  global_projection

    Read-only. True if the projection can represent the whole sphere in a finite, non-overlapped mapping.

  m

    Read-only. Intermediate integer value (used only for the `ZPN` and `HPX` projections).

  n

    Read-only. Intermediate integer value (used only for the `ZPN` and `HPX` projections).

  name

    Read-only. Long name of the projection.

  phi0

    The native longitude, \(\phi_0\) (in degrees) of the reference point, i.e. the point `(x,y) = (0,0)`. If undefined the initialization routine will set this to a projection-specific default.

  pv

    Projection parameters. These correspond to the `PVi_ma` keywords in FITS, so `pv[0]` is `PVi_0a`, `pv[1]` is `PVi_1a`, etc., where `i` denotes the latitude-like axis. Many projections use `pv[1]` (`PVi_1a`), some also use `pv[2]` (`PVi_2a`) and `SZP` uses `pv[3]` (`PVi_3a`). `ZPN` is currently the only projection that uses any of the others.

    When setting `pv` values using lists or `numpy.ndarray`, elements set to `None` will be left unchanged while those set to `numpy.nan` will be set to `WCSLIB`’s `UNDEFINED` special value. For efficiency purposes, if supplied list or `numpy.ndarray` is shorter than the length of the `pv` member, then remaining values in `pv` will be left unchanged.

    Note

    When retrieving `pv`, a copy of the `prjprm.pv` array is returned. Modifying this array values will not modify underlying `WCSLIB`’s `prjprm.pv` data.

  pvrange

    Read-only. Range of projection parameter indices: 100 times the first allowed index plus the number of parameters, e.g. `TAN` is 0 (no parameters), `SZP` is 103 (1 to 3), and `ZPN` is 30 (0 to 29).

  r0

    The radius of the generating sphere for the projection, a linear scaling parameter. If this is zero, it will be reset to its default value of \(180^\circ/\pi\) (the value for FITS WCS).

  simplezen

    Read-only. True if the projection is a radially-symmetric zenithal projection.

  theta0

    the native latitude, \(\theta_0\) (in degrees) of the reference point, i.e. the point `(x,y) = (0,0)`. If undefined the initialization routine will set this to a projection-specific default.

  w

    Read-only. Intermediate floating-point values derived from the projection parameters, cached here to save recomputation.

    Note

    When retrieving `w`, a copy of the `prjprm.w` array is returned. Modifying this array values will not modify underlying `WCSLIB`’s `prjprm.w` data.

  x0

    Read-only. The offset in `x` used to force \((x,y) = (0,0)\) at \((\phi_0, \theta_0)\).

  y0

    Read-only. The offset in `y` used to force \((x,y) = (0,0)\) at \((\phi_0, \theta_0)\).

  Methods Documentation

  get_pvi()

    Set/Get projection parameters for specific index. These correspond to the `PVi_ma` keywords in FITS, so `pv[0]` is `PVi_0a`, `pv[1]` is `PVi_1a`, etc., where `i` denotes the latitude-like axis. Many projections use `pv[1]` (`PVi_1a`), some also use `pv[2]` (`PVi_2a`) and `SZP` uses `pv[3]` (`PVi_3a`). `ZPN` is currently the only projection that uses any of the others.

    Setting a `pvi` value to `None` will reset the corresponding `WCSLIB`’s `prjprm.pv` element to the default value as set by `WCSLIB`’s `prjini()`.

    Setting a `pvi` value to `numpy.nan` will set the corresponding `WCSLIB`’s `prjprm.pv` element to `WCSLIB`’s `UNDEFINED` special value.

  prjs2x()

    Project native spherical coordinates \((\phi,\theta)\) to Cartesian `(x,y)` coordinates in the plane of projection.

    The projection is that specified by `Prjprm.code`.

    Parameters:
      phi `numpy.ndarray`

        Array corresponding to the longitude \(\phi\) of the projected point in native spherical coordinates (in degrees).

      theta `numpy.ndarray`

        Array corresponding to the longitude \(\theta\) of the projected point in native spherical coordinates (in degrees). Values corresponding to invalid \((\phi, \theta)\) coordinates are set to `numpy.nan`.

    Returns:
      x, y `python:tuple` of `numpy.ndarray`

        Projected coordinates.

    Raises:
      `MemoryError`

        Null `prjprm` pointer passed to WCSLIB routines.

      `InvalidPrjParametersError`

        Invalid projection parameters.

  prjx2s()

    Deproject Cartesian `(x,y)` coordinates in the plane of projection to native spherical coordinates \((\phi,\theta)\).

    The projection is that specified by `Prjprm.code`.

    Parameters:
      x, y `numpy.ndarray`

        Arrays corresponding to the first (`x`) and second (`y`) projected coordinates.

    Returns:
      phi, theta `python:tuple` of `numpy.ndarray`

        Longitude and latitude \((\phi,\theta)\) of the projected point in native spherical coordinates (in degrees). Values corresponding to invalid `(x,y)` coordinates are set to `numpy.nan`.

    Raises:
      `MemoryError`

        Null `prjprm` pointer passed to WCSLIB routines.

      `InvalidPrjParametersError`

        Invalid projection parameters.

  set(/)

    This method sets up a `Prjprm` object according to information supplied within it.

    Note that this routine need not be called directly; it will be invoked by `prjx2s` and `prjs2x` if `Prjprm.flag` is anything other than a predefined magic value.

    The one important property of `set()` is that the projection code must be defined in the `Prjprm` in order for `set()` to identify the required projection.

    Raises:
      `MemoryError`

        Null `prjprm` pointer passed to WCSLIB routines.

      `InvalidPrjParametersError`

        Invalid projection parameters.

      `InvalidCoordinateError`

        One or more of the `(x,y)` or `(lon,lat)` coordinates were invalid.

  set_pvi()

    Set/Get projection parameters for specific index. These correspond to the `PVi_ma` keywords in FITS, so `pv[0]` is `PVi_0a`, `pv[1]` is `PVi_1a`, etc., where `i` denotes the latitude-like axis. Many projections use `pv[1]` (`PVi_1a`), some also use `pv[2]` (`PVi_2a`) and `SZP` uses `pv[3]` (`PVi_3a`). `ZPN` is currently the only projection that uses any of the others.

    Setting a `pvi` value to `None` will reset the corresponding `WCSLIB`’s `prjprm.pv` element to the default value as set by `WCSLIB`’s `prjini()`.

    Setting a `pvi` value to `numpy.nan` will set the corresponding `WCSLIB`’s `prjprm.pv` element to `WCSLIB`’s `UNDEFINED` special value.