Skip to content
Back to top
View this page

# WCS

class gwcs.wcs.WCS(forward_transform: Model | list[Step | tuple[CoordinateFrame, Model | None]] | None = None, input_frame: CoordinateFrame | None = None, output_frame: CoordinateFrame | None = None, name: str | None = None)

  Bases: `GWCSAPIMixin`, `Pipeline`

  Basic WCS class.

  Parameters:
    forward_transform `Model` or a list

      The transform between `input_frame` and `output_frame`. A list of (frame, transform) tuples where `frame` is the starting frame and `transform` is the transform from this frame to the next one or `output_frame`. The last tuple is (transform, None), where None indicates the end of the pipeline.

    input_frame str, `CoordinateFrame`

      A coordinates object or a string name.

    output_frame str, `CoordinateFrame`

      A coordinates object or a string name.

    name str

      a name for this WCS

  Attributes Summary

  `array_shape` | The shape of the data that the WCS applies to as a tuple of length `pixel_n_dim`.
  `available_frames` | List of all the frame names in this WCS in their order in the pipeline
  `axis_correlation_matrix` | Returns an (`world_n_dim`, `pixel_n_dim`) matrix that indicates using booleans whether a given world coordinate depends on a given pixel coordinate.
  `backward_transform` | Return the total backward transform if available - from output to input coordinate system.
  `bounding_box` | Return the bounding box of the pipeline.
  `forward_transform` | Return the forward transform of the pipeline.
  `input_frame` | Return the input frame name of the pipeline.
  `low_level_wcs` | Returns a reference to the underlying low-level WCS object.
  `name` | Return the name for this WCS.
  `output_frame` | Return the output frame name of the pipeline.
  `pipeline` | Allow direct access to the raw pipeline steps.
  `pixel_axis_names` | An iterable of strings describing the name for each pixel axis.
  `pixel_bounds` | The bounds (in pixel coordinates) inside which the WCS is defined, as a list with `pixel_n_dim` `(min, max)` tuples.
  `pixel_n_dim` | The number of axes in the pixel coordinate system.
  `pixel_shape` | The shape of the data that the WCS applies to as a tuple of length `pixel_n_dim` in `(x, y)` order (where for an image, `x` is the horizontal coordinate and `y` is the vertical coordinate) (optional).
  `serialized_classes` | Indicates whether Python objects are given in serialized form or as actual Python objects.
  `unit` | The unit of the coordinates in the output coordinate system.
  `world_axis_names` | An iterable of strings describing the name for each world axis.
  `world_axis_object_classes` | A dictionary giving information on constructing high-level objects for the world coordinates.
  `world_axis_object_components` | A list with `world_n_dim` elements giving information on constructing high-level objects for the world coordinates.
  `world_axis_physical_types` | An iterable of strings describing the physical type for each world axis.
  `world_axis_units` | An iterable of strings given the units of the world coordinates for each axis.
  `world_n_dim` | The number of axes in the world coordinate system.

  Methods Summary

  `__call__`(*args[, with_bounding_box, fill_value]) | Executes the forward transform.
  `array_index_to_world`(*index_arrays) | Convert array indices to world coordinates (represented by Astropy objects).
  `array_index_to_world_values`(*index_arrays) | Convert array indices to world coordinates.
  `attach_compound_bounding_box`(cbbox, ...) | Attach a compound bounding box dictionary to the pipeline.
  `fix_inputs`(fixed) | Return a new unique WCS by fixing inputs to constant values.
  `footprint`([bounding_box, center, axis_type]) | Return the footprint in world coordinates.
  `get_transform`(from_frame, to_frame) | Return a transform between two coordinate frames.
  `in_image`(*args, **kwargs) | This method tests if one or more of the input world coordinates are contained within forward transformation's image and that it maps to the domain of definition of the forward transformation.
  `insert_frame`(input_frame, transform, ...) | Insert a new frame into an existing pipeline.
  `insert_transform`(frame, transform[, after]) | Insert a transform before (default) or after a coordinate frame.
  `invert`(*args[, with_bounding_box, fill_value]) | Invert coordinates from output frame to input frame using analytical or user-supplied inverse.
  `numerical_inverse`(*args[, tolerance, ...]) | Invert coordinates from output frame to input frame using numerical inverse.
  `out_of_bounds`(pixel_arrays[, fill_value]) |
  `outside_footprint`(world_arrays) |
  `pixel_to_world`(*pixel_arrays) | Convert pixel coordinates to world coordinates (represented by high-level objects).
  `pixel_to_world_values`(*pixel_arrays) | Convert pixel coordinates to world coordinates.
  `set_transform`(from_frame, to_frame, transform) | Set/replace the transform between two coordinate frames.
  `to_fits`([bounding_box, max_pix_error, ...]) | Construct a FITS WCS `-TAB`-based approximation to the WCS in the form of a FITS header and a binary table extension.
  `to_fits_sip`([bounding_box, max_pix_error, ...]) | Construct a SIP-based approximation to the WCS for the axes corresponding to the `CelestialFrame` in the form of a FITS header.
  `to_fits_tab`([bounding_box, bin_ext_name, ...]) | Construct a FITS WCS `-TAB`-based approximation to the WCS in the form of a FITS header and a binary table extension.
  `transform`(from_frame, to_frame, *args[, ...]) | Transform positions between two frames.
  `world_to_array_index`(*world_objects) | Convert world coordinates (represented by Astropy objects) to array indices.
  `world_to_array_index_values`(*world_arrays) | Convert world coordinates to array indices.
  `world_to_pixel`(*world_objects) | Convert world coordinates (represented by Astropy objects) to pixel coordinates.
  `world_to_pixel_values`(*world_arrays) | Convert world coordinates to pixel coordinates.

  Attributes Documentation

  array_shape

    The shape of the data that the WCS applies to as a tuple of length `pixel_n_dim`. If the WCS is valid in the context of a dataset with a particular shape, then this property can be used to store the shape of the data. This can be used for example if implementing slicing of WCS objects. This is an optional property, and it should return `None` if a shape is not known or relevant. The shape should be given in `(row, column)` order (the convention for arrays in Python).

  available_frames

    List of all the frame names in this WCS in their order in the pipeline

  axis_correlation_matrix

    Returns an (`world_n_dim`, `pixel_n_dim`) matrix that indicates using booleans whether a given world coordinate depends on a given pixel coordinate. This defaults to a matrix where all elements are `True` in the absence of any further information. For completely independent axes, the diagonal would be `True` and all other entries `False`.

  backward_transform

    Return the total backward transform if available - from output to input coordinate system.

    Raises:
      NotImplementedError

        An analytical inverse does not exist.

  bounding_box

    Return the bounding box of the pipeline.

  forward_transform

    Return the forward transform of the pipeline.

  input_frame

    Return the input frame name of the pipeline.

  low_level_wcs
  name

    Return the name for this WCS.

  output_frame

    Return the output frame name of the pipeline.

  pipeline

    Allow direct access to the raw pipeline steps.

  pixel_axis_names

    An iterable of strings describing the name for each pixel axis.

  pixel_bounds

    The bounds (in pixel coordinates) inside which the WCS is defined, as a list with `pixel_n_dim` `(min, max)` tuples. The bounds should be given in `[(xmin, xmax), (ymin, ymax)]` order. WCS solutions are sometimes only guaranteed to be accurate within a certain range of pixel values, for example when defining a WCS that includes fitted distortions. This is an optional property, and it should return `None` if a shape is not known or relevant.

  pixel_n_dim

    The number of axes in the pixel coordinate system.

  pixel_shape

    The shape of the data that the WCS applies to as a tuple of length `pixel_n_dim` in `(x, y)` order (where for an image, `x` is the horizontal coordinate and `y` is the vertical coordinate) (optional).

    If the WCS is valid in the context of a dataset with a particular shape, then this property can be used to store the shape of the data. This can be used for example if implementing slicing of WCS objects. This is an optional property, and it should return `None` if a shape is neither known nor relevant.

  serialized_classes

    Indicates whether Python objects are given in serialized form or as actual Python objects.

  unit

    The unit of the coordinates in the output coordinate system.

  world_axis_names

    An iterable of strings describing the name for each world axis.

  world_axis_object_classes
  world_axis_object_components
  world_axis_physical_types

    An iterable of strings describing the physical type for each world axis. These should be names from the VO UCD1+ controlled Vocabulary (http://www.ivoa.net/documents/latest/UCDlist.html). If no matching UCD type exists, this can instead be `"custom:xxx"`, where `xxx` is an arbitrary string. Alternatively, if the physical type is unknown/undefined, an element can be `None`.

  world_axis_units

    An iterable of strings given the units of the world coordinates for each axis. The strings should follow the IVOA VOUnit standard (though as noted in the VOUnit specification document, units that do not follow this standard are still allowed, but just not recommended).

  world_n_dim

    The number of axes in the world coordinate system.

  Methods Documentation

  __call__(*args, with_bounding_box: bool = True, fill_value: float | number = nan, **kwargs)

    Executes the forward transform.

    argsfloat or array-like

      Inputs in the input coordinate system, separate inputs for each dimension.

    with_bounding_boxbool, optional

      If True(default) values in the result which correspond to any of the inputs being outside the bounding_box are set to `fill_value`.

    fill_valuefloat, optional

      Output value for inputs outside the bounding_box (default is np.nan).

  array_index_to_world(*index_arrays)

    Convert array indices to world coordinates (represented by Astropy objects).

    If a single high-level object is used to represent the world coordinates (i.e., if `len(wcs.world_axis_object_classes) == 1`), it is returned as-is (not in a tuple/list), otherwise a tuple of high-level objects is returned. See `array_index_to_world_values` for pixel indexing and ordering conventions.

  array_index_to_world_values(*index_arrays)

    Convert array indices to world coordinates. This is the same as `pixel_to_world_values` except that the indices should be given in `(i, j)` order, where for an image `i` is the row and `j` is the column (i.e. the opposite order to `pixel_to_world_values`).

  attach_compound_bounding_box(cbbox: dict[tuple[str], tuple], selector_args: tuple[str])

    Attach a compound bounding box dictionary to the pipeline.

    Parameters:
      cbbox
        Dictionary of the bounding box tuples (F order) for each input set

          keys: selector argument values: bounding box tuple in F order

      selector_args:

        Argument names to the model that are used to select the bounding box

  fix_inputs(fixed)

    Return a new unique WCS by fixing inputs to constant values.

    Parameters:
      fixed dict

        Keyword arguments with fixed values corresponding to `self.selector`.

    Returns:
      new_wcs `WCS`

        A new unique WCS corresponding to the values in `fixed`.

    Examples

        >>> w = WCS(pipeline, selector={"spectral_order": [1, 2]})
        >>> new_wcs = w.set_inputs(spectral_order=2)
        >>> new_wcs.inputs
            ("x", "y")

  footprint(bounding_box=None, center=False, axis_type='all')

    Return the footprint in world coordinates.

    Parameters:
      bounding_box tuple of floats: (start, stop)

        `prop: bounding_box`

      center bool

        If `True` use the center of the pixel, otherwise use the corner.

      axis_type str

        A supported `output_frame.axes_type` or `"all"` (default). One of [`'spatial'`, `'spectral'`, `'temporal'`] or a custom type.

    Returns:
      coord ndarray

        Array of coordinates in the output_frame mapping corners to the output frame. For spatial coordinates the order is clockwise, starting from the bottom left corner.

  get_transform(from_frame: str | CoordinateFrame, to_frame: str | CoordinateFrame) → Model | None

    Return a transform between two coordinate frames.

    Parameters:
      from_frame str or `CoordinateFrame`

        Initial coordinate frame name of object.

      to_frame str or `CoordinateFrame`

        End coordinate frame name or object.

    Returns:
      transform `Model`

        Transform between two frames.

  in_image(*args, **kwargs)

    This method tests if one or more of the input world coordinates are contained within forward transformation’s image and that it maps to the domain of definition of the forward transformation. In practical terms, this function tests that input world coordinate(s) can be converted to input frame and that it is within the forward transformation’s `bounding_box` when defined.

    Parameters:
      args float, array like, `SkyCoord` or

        `Unit` coordinates to be inverted

      kwargs dict

        keyword arguments to be passed either to `backward_transform` (when defined) or to the iterative invert method.

    Returns:
      result bool, numpy.ndarray

        A single boolean value or an array of boolean values with `True` indicating that the WCS footprint contains the coordinate and `False` if input is outside the footprint.

  insert_frame(input_frame: str | CoordinateFrame, transform: Model, output_frame: str | CoordinateFrame) → None

    Insert a new frame into an existing pipeline. This frame must be anchored to a frame already in the pipeline by a transform. This existing frame is identified solely by its name, although an entire `CoordinateFrame` can be passed (e.g., the `input_frame` or `output_frame` attribute). This frame is never modified.

    Parameters:
      input_frame str or `CoordinateFrame`

        Coordinate frame at start of new transform

      transform `Model`

        New transform to be inserted in the pipeline

      output_frame: str or `~gwcs.coordinate_frames.CoordinateFrame`

        Coordinate frame at end of new transform

  insert_transform(frame: str | CoordinateFrame, transform: Model, after: bool = False) → None

    Insert a transform before (default) or after a coordinate frame.

    Append (or prepend) a transform to the transform connected to frame.

    Parameters:
      frame str or `CoordinateFrame`

        Coordinate frame which sets the point of insertion.

      transform `Model`

        New transform to be inserted in the pipeline

      after bool

        If True, the new transform is inserted in the pipeline immediately after `frame`.

  invert(*args, with_bounding_box: bool = True, fill_value: float | number = nan, **kwargs)

    Invert coordinates from output frame to input frame using analytical or user-supplied inverse. When neither analytical nor user-supplied inverses are defined, a numerical solution will be attempted using `numerical_inverse()`.

    Note

    Currently numerical inverse is implemented only for 2D imaging WCS.

    Parameters:
      args float, array like, `SkyCoord` or `Unit`

        Coordinates to be inverted. The number of arguments must be equal to the number of world coordinates given by `world_n_dim`.

      with_bounding_box bool, optional

        If `True` (default) values in the result which correspond to any of the inputs being outside the bounding_box are set to `fill_value`.

      fill_value float, optional

        Output value for inputs outside the bounding_box (default is `np.nan`).

    Returns:
      result tuple or value

        Returns a tuple of scalar or array values for each axis. Unless `input_frame.naxes == 1` when it shall return the value. The return type will be `Quantity` objects if the transform returns `Quantity` objects, else values.

    Other Parameters:
      kwargs dict

        Keyword arguments to be passed to `numerical_inverse()` (when defined) or to the iterative invert method.

  numerical_inverse(*args, tolerance=1e-05, maxiter=30, adaptive=True, detect_divergence=True, quiet=True, with_bounding_box=True, fill_value=nan, **kwargs)

    Invert coordinates from output frame to input frame using numerical inverse.

    Note

    Currently numerical inverse is implemented only for 2D imaging WCS.

    Note

    This method uses a combination of vectorized fixed-point iterations algorithm and `scipy.optimize.root`. The later is used for input coordinates for which vectorized algorithm diverges.

    Parameters:
      args float, array like, `SkyCoord` or `Unit`

        Coordinates to be inverted. The number of arguments must be equal to the number of world coordinates given by `world_n_dim`.

      with_bounding_box bool, optional

        If `True` (default) values in the result which correspond to any of the inputs being outside the bounding_box are set to `fill_value`.

      fill_value float, optional

        Output value for inputs outside the bounding_box (default is `np.nan`).

      tolerance float, optional

        Absolute tolerance of solution. Iteration terminates when the iterative solver estimates that the “true solution” is within this many pixels current estimate, more specifically, when the correction to the solution found during the previous iteration is smaller (in the sense of the L2 norm) than `tolerance`. Default `tolerance` is 1.0e-5.

      maxiter int, optional

        Maximum number of iterations allowed to reach a solution. Default is 50.

      quiet bool, optional

        Do not throw `NoConvergence` exceptions when the method does not converge to a solution with the required accuracy within a specified number of maximum iterations set by `maxiter` parameter. Instead, simply return the found solution. Default is `True`.

      adaptive bool, optional

        Specifies whether to adaptively select only points that did not converge to a solution within the required accuracy for the next iteration. Default (`True`) is recommended.

        Note

        The `numerical_inverse()` uses a vectorized implementation of the method of consecutive approximations (see `Notes` section below) in which it iterates over all input points regardless until the required accuracy has been reached for all input points. In some cases it may be possible that almost all points have reached the required accuracy but there are only a few of input data points for which additional iterations may be needed (this depends mostly on the characteristics of the geometric distortions for a given instrument). In this situation it may be advantageous to set `adaptive` = `True` in which case `numerical_inverse()` will continue iterating only over the points that have not yet converged to the required accuracy.

        Note

        When `detect_divergence` is `True`, `numerical_inverse()` will automatically switch to the adaptive algorithm once divergence has been detected.

      detect_divergence bool, optional

        Specifies whether to perform a more detailed analysis of the convergence to a solution. Normally `numerical_inverse()` may not achieve the required accuracy if either the `tolerance` or `maxiter` arguments are too low. However, it may happen that for some geometric distortions the conditions of convergence for the the method of consecutive approximations used by `numerical_inverse()` may not be satisfied, in which case consecutive approximations to the solution will diverge regardless of the `tolerance` or `maxiter` settings.

        When `detect_divergence` is `False`, these divergent points will be detected as not having achieved the required accuracy (without further details). In addition, if `adaptive` is `False` then the algorithm will not know that the solution (for specific points) is diverging and will continue iterating and trying to “improve” diverging solutions. This may result in `NaN` or `Inf` values in the return results (in addition to a performance penalties). Even when `detect_divergence` is `False`, `numerical_inverse()`, at the end of the iterative process, will identify invalid results (`NaN` or `Inf`) as “diverging” solutions and will raise `NoConvergence` unless the `quiet` parameter is set to `True`.

        When `detect_divergence` is `True` (default), `numerical_inverse()` will detect points for which current correction to the coordinates is larger than the correction applied during the previous iteration if the requested accuracy has not yet been achieved. In this case, if `adaptive` is `True`, these points will be excluded from further iterations and if `adaptive` is `False`, `numerical_inverse()` will automatically switch to the adaptive algorithm. Thus, the reported divergent solution will be the latest converging solution computed immediately before divergence has been detected.

        Note

        When accuracy has been achieved, small increases in current corrections may be possible due to rounding errors (when `adaptive` is `False`) and such increases will be ignored.

        Note

        Based on our testing using JWST NIRCAM images, setting `detect_divergence` to `True` will incur about 5-10% performance penalty with the larger penalty corresponding to `adaptive` set to `True`. Because the benefits of enabling this feature outweigh the small performance penalty, especially when `adaptive` = `False`, it is recommended to set `detect_divergence` to `True`, unless extensive testing of the distortion models for images from specific instruments show a good stability of the numerical method for a wide range of coordinates (even outside the image itself).

        Note

        Indices of the diverging inverse solutions will be reported in the `divergent` attribute of the raised `NoConvergence` exception object.

    Returns:
      result tuple

        Returns a tuple of scalar or array values for each axis.

    Raises:
      NoConvergence

        The iterative method did not converge to a solution to the required accuracy within a specified number of maximum iterations set by the `maxiter` parameter. To turn off this exception, set `quiet` to `True`. Indices of the points for which the requested accuracy was not achieved (if any) will be listed in the `slow_conv` attribute of the raised `NoConvergence` exception object.

        See `NoConvergence` documentation for more details.

      NotImplementedError

        Numerical inverse has not been implemented for this WCS.

      ValueError

        Invalid argument values.

    Examples

        >>> from astropy.utils.data import get_pkg_data_filename
        >>> from gwcs import NoConvergence
        >>> import asdf
        >>> import numpy as np

        >>> filename = get_pkg_data_filename('data/nircamwcs.asdf', package='gwcs.tests')
        >>> with asdf.open(filename, lazy_load=False, ignore_missing_extensions=True) as af:
        ...    w = af.tree['wcs']

        >>> ra, dec = w([1,2,3], [1,1,1])
        >>> assert np.allclose(ra, [5.927628, 5.92757069, 5.92751337]);
        >>> assert np.allclose(dec, [-72.01341247, -72.01341273, -72.013413])

        >>> x, y = w.numerical_inverse(ra, dec)
        >>> assert np.allclose(x, [1.00000005, 2.00000005, 3.00000006]);
        >>> assert np.allclose(y, [1.00000004, 0.99999979, 1.00000015]);

        >>> x, y = w.numerical_inverse(ra, dec, maxiter=3, tolerance=1.0e-10, quiet=False)
        Traceback (most recent call last):
        ...
        gwcs.wcs._exception.NoConvergence: 'WCS.numerical_inverse' failed to converge to the
        requested accuracy after 3 iterations.

        >>> w.numerical_inverse(
        ...     *w([1, 300000, 3], [2, 1000000, 5], with_bounding_box=False),
        ...     adaptive=False,
        ...     detect_divergence=True,
        ...     quiet=False,
        ...     with_bounding_box=False
        ... )
        Traceback (most recent call last):
        ...
        gwcs.wcs._exception.NoConvergence: 'WCS.numerical_inverse' failed to converge to the
        requested accuracy. After 4 iterations, the solution is diverging at
        least for one input point.

        >>> # Now try to use some diverging data:
        >>> divra, divdec = w([1, 300000, 3], [2, 1000000, 5], with_bounding_box=False)
        >>> assert np.allclose(divra, [5.92762673, 148.21600848, 5.92750827])
        >>> assert np.allclose(divdec, [-72.01339464, -7.80968079, -72.01334172])
        >>> try:
        ...     x, y = w.numerical_inverse(divra, divdec, maxiter=20,
        ...                                tolerance=1.0e-4, adaptive=True,
        ...                                detect_divergence=True,
        ...                                quiet=False)
        ... except NoConvergence as e:
        ...     print(f"Indices of diverging points: {e.divergent}")
        ...     print(f"Indices of poorly converging points: {e.slow_conv}")
        ...     print(f"Best solution:\n{e.best_solution}")
        ...     print(f"Achieved accuracy:\n{e.accuracy}")
        Indices of diverging points: None
        Indices of poorly converging points: [1]
        Best solution:
        [[1.00000040e+00 1.99999841e+00]
         [6.33507833e+17 3.40118820e+17]
         [3.00000038e+00 4.99999841e+00]]
        Achieved accuracy:
        [[2.75925982e-05 1.18471543e-05]
         [3.65405005e+04 1.31364188e+04]
         [2.76552923e-05 1.14789013e-05]]

  out_of_bounds(pixel_arrays, fill_value=nan)
  outside_footprint(world_arrays)
  pixel_to_world(*pixel_arrays)

    Convert pixel coordinates to world coordinates (represented by high-level objects).

    If a single high-level object is used to represent the world coordinates (i.e., if `len(wcs.world_axis_object_classes) == 1`), it is returned as-is (not in a tuple/list), otherwise a tuple of high-level objects is returned. See `pixel_to_world_values` for pixel indexing and ordering conventions.

  pixel_to_world_values(*pixel_arrays)

    Convert pixel coordinates to world coordinates.

    This method takes `pixel_n_dim` scalars or arrays as input, and pixel coordinates should be zero-based. Returns `world_n_dim` scalars or arrays in units given by `world_axis_units`. Note that pixel coordinates are assumed to be 0 at the center of the first pixel in each dimension. If a pixel is in a region where the WCS is not defined, NaN can be returned. The coordinates should be specified in the `(x, y)` order, where for an image, `x` is the horizontal coordinate and `y` is the vertical coordinate.

  set_transform(from_frame: str | CoordinateFrame, to_frame: str | CoordinateFrame, transform: Model) → None

    Set/replace the transform between two coordinate frames.

    Parameters:
      from_frame str or `CoordinateFrame`

        Initial coordinate frame.

      to_frame str, or instance of `CoordinateFrame`

        End coordinate frame.

      transform `Model`

        Transform between `from_frame` and `to_frame`.

  to_fits(bounding_box=None, max_pix_error=0.25, degree=None, max_inv_pix_error=0.25, inv_degree=None, npoints=32, crpix=None, projection='TAN', bin_ext_name='WCS-TABLE', coord_col_name='coordinates', sampling=1, verbose=False)

    Construct a FITS WCS `-TAB`-based approximation to the WCS in the form of a FITS header and a binary table extension. For the description of the FITS WCS `-TAB` convention, see “Representations of spectral coordinates in FITS” in Greisen, E. W. et al. A&A 446 (2) 747-771 (2006) . If WCS contains celestial frame, PC/CD formalism will be used for the celestial axes.

    Note

    SIP distortion fitting requires that the WCS object has only two celestial axes. When WCS does not contain celestial axes, SIP fitting parameters (`max_pix_error`, `degree`, `max_inv_pix_error`, `inv_degree`, and `projection`) are ignored. When a WCS, in addition to celestial frame, contains other types of axes, SIP distortion fitting is disabled (only linear terms are fitted for celestial frame).

    Parameters:
      bounding_box tuple, optional

        Specifies the range of acceptable values for each input axis. The order of the axes is `axes_order`. For two image axes `bounding_box` is of the form `((xmin, xmax), (ymin, ymax))`.

      max_pix_error float, optional

        Maximum allowed error over the domain of the pixel array. This error is the equivalent pixel error that corresponds to the maximum error in the output coordinate resulting from the fit based on a nominal plate scale.

      degree int, iterable, None, optional

        Degree of the SIP polynomial. Default value `None` indicates that all allowed degree values (`[1...9]`) will be considered and the lowest degree that meets accuracy requerements set by `max_pix_error` will be returned. Alternatively, `degree` can be an iterable containing allowed values for the SIP polynomial degree. This option is similar to default `None` but it allows caller to restrict the range of allowed SIP degrees used for fitting. Finally, `degree` can be an integer indicating the exact SIP degree to be fit to the WCS transformation. In this case `max_pixel_error` is ignored.

        Note

        When WCS object has When `degree` is `None` and the WCS object has

      max_inv_pix_error float, optional

        Maximum allowed inverse error over the domain of the pixel array in pixel units. If None, no inverse is generated.

      inv_degree int, iterable, None, optional

        Degree of the SIP polynomial. Default value `None` indicates that all allowed degree values (`[1...9]`) will be considered and the lowest degree that meets accuracy requerements set by `max_pix_error` will be returned. Alternatively, `degree` can be an iterable containing allowed values for the SIP polynomial degree. This option is similar to default `None` but it allows caller to restrict the range of allowed SIP degrees used for fitting. Finally, `degree` can be an integer indicating the exact SIP degree to be fit to the WCS transformation. In this case `max_inv_pixel_error` is ignored.

      npoints int, optional

        The number of points in each dimension to sample the bounding box for use in the SIP fit. Minimum number of points is 3.

      crpix list of float, None, optional

        Coordinates (1-based) of the reference point for the new FITS WCS. When not provided, i.e., when set to `None` (default) the reference pixel will be chosen near the center of the bounding box for axes corresponding to the celestial frame.

      projection str, `Pix2SkyProjection`, optional

        Projection to be used for the created FITS WCS. It can be specified as a string of three characters specifying a FITS projection code from Table 13 in Representations of World Coordinates in FITS (Paper I), Greisen, E. W., and Calabretta, M. R., A & A, 395, 1061-1075, 2002. Alternatively, it can be an instance of one of the astropy’s Pix2Sky_* projection models inherited from `Pix2SkyProjection`.

      bin_ext_name str, optional

        Extension name for the `BinTableHDU` HDU for those axes groups that will be converted using FITW WCS’ `-TAB` algorithm. Extension version will be determined automatically based on the number of separable group of axes.

      coord_col_name str, optional

        Field name of the coordinate array in the structured array stored in `BinTableHDU` data. This corresponds to `TTYPEi` field in the FITS header of the binary table extension.

      sampling float, tuple, optional

        The target “density” of grid nodes per pixel to be used when creating the coordinate array for the `-TAB` FITS WCS convention. It is equal to `1/step` where `step` is the distance between grid nodes in pixels. `sampling` can be specified as a single number to be used for all axes or as a `tuple` of numbers that specify the sampling for each image axis.

      verbose bool, optional

        Print progress of fits.

    Returns:
      hdr `Header`

        Header with WCS-TAB information associated (to be used) with image data.

      hdulist a list of `BinTableHDU`

        A Python list of binary table extensions containing the coordinate array for TAB extensions; one extension per separable axes group.

    Raises:
      ValueError

        When `bounding_box` is not defined either through the input `bounding_box` parameter or this object’s `bounding_box` property.

      ValueError

        When `sampling` is a `tuple` of length larger than 1 that does not match the number of image axes.

      RuntimeError

        If the number of image axes (`~gwcs.WCS.pixel_n_dim`) is larger than the number of world axes (`~gwcs.WCS.world_n_dim`).

  to_fits_sip(bounding_box=None, max_pix_error=0.25, degree=None, max_inv_pix_error=0.25, inv_degree=None, npoints=32, crpix=None, projection='TAN', verbose=False)

    Construct a SIP-based approximation to the WCS for the axes corresponding to the `CelestialFrame` in the form of a FITS header.

    The default mode in using this attempts to achieve roughly 0.25 pixel accuracy over the whole image.

    Parameters:
      bounding_box tuple, optional

        A pair of tuples, each consisting of two numbers Represents the range of pixel values in both dimensions ((xmin, xmax), (ymin, ymax))

      max_pix_error float, optional

        Maximum allowed error over the domain of the pixel array. This error is the equivalent pixel error that corresponds to the maximum error in the output coordinate resulting from the fit based on a nominal plate scale. Ignored when `degree` is an integer or a list with a single degree.

      degree int, iterable, None, optional

        Degree of the SIP polynomial. Default value `None` indicates that all allowed degree values (`[1...9]`) will be considered and the lowest degree that meets accuracy requerements set by `max_pix_error` will be returned. Alternatively, `degree` can be an iterable containing allowed values for the SIP polynomial degree. This option is similar to default `None` but it allows caller to restrict the range of allowed SIP degrees used for fitting. Finally, `degree` can be an integer indicating the exact SIP degree to be fit to the WCS transformation. In this case `max_pixel_error` is ignored.

      max_inv_pix_error float, optional

        Maximum allowed inverse error over the domain of the pixel array in pixel units. If None, no inverse is generated. Ignored when `degree` is an integer or a list with a single degree.

      inv_degree int, iterable, None, optional

        Degree of the SIP polynomial. Default value `None` indicates that all allowed degree values (`[1...9]`) will be considered and the lowest degree that meets accuracy requerements set by `max_pix_error` will be returned. Alternatively, `degree` can be an iterable containing allowed values for the SIP polynomial degree. This option is similar to default `None` but it allows caller to restrict the range of allowed SIP degrees used for fitting. Finally, `degree` can be an integer indicating the exact SIP degree to be fit to the WCS transformation. In this case `max_inv_pixel_error` is ignored.

      npoints int, optional

        The number of points in each dimension to sample the bounding box for use in the SIP fit. Minimum number of points is 3.

      crpix list of float, None, optional

        Coordinates (1-based) of the reference point for the new FITS WCS. When not provided, i.e., when set to `None` (default) the reference pixel will be chosen near the center of the bounding box for axes corresponding to the celestial frame.

      projection str, `Pix2SkyProjection`, optional

        Projection to be used for the created FITS WCS. It can be specified as a string of three characters specifying a FITS projection code from Table 13 in Representations of World Coordinates in FITS (Paper I), Greisen, E. W., and Calabretta, M. R., A & A, 395, 1061-1075, 2002. Alternatively, it can be an instance of one of the astropy’s Pix2Sky_* projection models inherited from `Pix2SkyProjection`.

      verbose bool, optional

        Print progress of fits.

    Returns:
      FITS header with all SIP WCS keywords
    Raises:
      ValueError

        If the WCS is not at least 2D, an exception will be raised. If the specified accuracy (both forward and inverse, both rms and maximum) is not achieved an exception will be raised.

    Notes

    Use of this requires a judicious choice of required accuracies. Attempts to use higher degrees (~7 or higher) will typically fail due to floating point problems that arise with high powers.

  to_fits_tab(bounding_box=None, bin_ext_name='WCS-TABLE', coord_col_name='coordinates', sampling=1)

    Construct a FITS WCS `-TAB`-based approximation to the WCS in the form of a FITS header and a binary table extension. For the description of the FITS WCS `-TAB` convention, see “Representations of spectral coordinates in FITS” in Greisen, E. W. et al. A&A 446 (2) 747-771 (2006) .

    Parameters:
      bounding_box tuple, optional

        Specifies the range of acceptable values for each input axis. The order of the axes is `axes_order`. For two image axes `bounding_box` is of the form `((xmin, xmax), (ymin, ymax))`.

      bin_ext_name str, optional

        Extension name for the `BinTableHDU` HDU for those axes groups that will be converted using FITW WCS’ `-TAB` algorithm. Extension version will be determined automatically based on the number of separable group of axes.

      coord_col_name str, optional

        Field name of the coordinate array in the structured array stored in `BinTableHDU` data. This corresponds to `TTYPEi` field in the FITS header of the binary table extension.

      sampling float, tuple, optional

        The target “density” of grid nodes per pixel to be used when creating the coordinate array for the `-TAB` FITS WCS convention. It is equal to `1/step` where `step` is the distance between grid nodes in pixels. `sampling` can be specified as a single number to be used for all axes or as a `tuple` of numbers that specify the sampling for each image axis.

    Returns:
      hdr `Header`

        Header with WCS-TAB information associated (to be used) with image data.

      bin_table_hdu `BinTableHDU`

        Binary table extension containing the coordinate array.

    Raises:
      ValueError

        When `bounding_box` is not defined either through the input `bounding_box` parameter or this object’s `bounding_box` property.

      ValueError

        When `sampling` is a `tuple` of length larger than 1 that does not match the number of image axes.

      RuntimeError

        If the number of image axes (`~gwcs.WCS.pixel_n_dim`) is larger than the number of world axes (`~gwcs.WCS.world_n_dim`).

  transform(from_frame: str | CoordinateFrame, to_frame: str | CoordinateFrame, *args, with_bounding_box: bool = True, fill_value: float | number = nan, **kwargs)

    Transform positions between two frames.

    Parameters:
      from_frame str or `CoordinateFrame`

        Initial coordinate frame.

      to_frame str, or instance of `CoordinateFrame`

        Coordinate frame into which to transform.

      args float or array-like

        Inputs in `from_frame`, separate inputs for each dimension.

      with_bounding_box bool, optional

        If True(default) values in the result which correspond to any of the inputs being outside the bounding_box are set to `fill_value`.

      fill_value float, optional

        Output value for inputs outside the bounding_box (default is np.nan).

  world_to_array_index(*world_objects)

    Convert world coordinates (represented by Astropy objects) to array indices.

    If `pixel_n_dim` is `1`, this method returns a single scalar or array, otherwise a tuple of scalars or arrays is returned. See `world_to_array_index_values` for pixel indexing and ordering conventions. The indices should be returned as rounded integers.

  world_to_array_index_values(*world_arrays)

    Convert world coordinates to array indices. This is the same as `world_to_pixel_values` except that the indices should be returned in `(i, j)` order, where for an image `i` is the row and `j` is the column (i.e. the opposite order to `pixel_to_world_values`). The indices should be returned as rounded integers.

  world_to_pixel(*world_objects)

    Convert world coordinates (represented by Astropy objects) to pixel coordinates.

    If `pixel_n_dim` is `1`, this method returns a single scalar or array, otherwise a tuple of scalars or arrays is returned. See `world_to_pixel_values` for pixel indexing and ordering conventions.

  world_to_pixel_values(*world_arrays)

    Convert world coordinates to pixel coordinates.

    This method takes `world_n_dim` scalars or arrays as input in units given by `world_axis_units`. Returns `pixel_n_dim` scalars or arrays. Note that pixel coordinates are assumed to be 0 at the center of the first pixel in each dimension. If a world coordinate does not have a matching pixel coordinate, NaN can be returned. The coordinates should be returned in the `(x, y)` order, where for an image, `x` is the horizontal coordinate and `y` is the vertical coordinate.