### Install GWCS

Source: https://github.com/spacetelescope/gwcs/blob/master/README.rst

Instructions for installing the GWCS package using pip or from the master branch on GitHub.

```Python
pip install gwcs
```

```Bash
git clone https://github.com/spacetelescope/gwcs.git
cd gwcs
pip install --editable .
```

--------------------------------

### Install GWCS using pip

Source: https://github.com/spacetelescope/gwcs/blob/master/docs/index.rst

Installs the latest release of the GWCS package using pip.

```shell
pip install gwcs
```

--------------------------------

### Install GWCS from source

Source: https://github.com/spacetelescope/gwcs/blob/master/docs/index.rst

Installs the latest development version of GWCS directly from its GitHub repository using pip. This is generally not recommended unless specific new features or bug fixes are required.

```shell
pip install git+https://github.com/spacetelescope/gwcs.git
```

--------------------------------

### Install GWCS using conda

Source: https://github.com/spacetelescope/gwcs/blob/master/docs/index.rst

Installs the GWCS package from the conda-forge channel using conda.

```shell
conda install -c conda-forge gwcs
```

--------------------------------

### GWCS IFU Example: Pixel to Slice Mapping

Source: https://github.com/spacetelescope/gwcs/blob/master/docs/gwcs/ifu.rst

This snippet demonstrates setting up a WCS for an IFU with 6 slits using a pixel-to-slice mapping. It involves creating a LabelMapperArray and a RegionsSelector to handle different transforms for each slice.

```python
import numpy as np
from astropy.modeling import models
from astropy import coordinates as coord
from astropy import units as u
from gwcs import wcs, selector
from gwcs import coordinate_frames as cf

# Ignore the details of how this mask is constructed; they are using
# array operations to generate the mask displayed for this example.
y, x = np.mgrid[:1000, :500]
fmask = (((-x + 0.01 * y + 0.00002 * y**2)/ 500) * 13 - 0.5) + 14
mask = fmask.astype(np.int8)
mask[(mask % 2) == 1] = 0
mask[mask > 13] = 0
mask = mask // 2
labelmapper = selector.LabelMapperArray(mask)

sky_frame = cf.CelestialFrame(name='icrs', reference_frame=coord.ICRS(), axes_order=(0, 2))
spec_frame = cf.SpectralFrame(name='wave', unit=(u.micron,), axes_order=(1,), axes_names=('lambda',))
cframe = cf.CompositeFrame([sky_frame, spec_frame], name='world')
det = cf.Frame2D(name='detector')

transforms = {}
for i in range(1, 7):
    transforms[i] = models.Mapping([0, 0, 1]) | models.Shift(i * 0.1) & models.Shift(i * 0.2) & models.Scale(i * 0.1)

regions_transform = selector.RegionsSelector(inputs=['x','y'],
                                             outputs=['ra', 'dec', 'lam'],
                                             selector=transforms,
                                             label_mapper=labelmapper,
                                             undefined_transform_value=np.nan)

wifu = wcs.WCS(forward_transform=regions_transform, output_frame=cframe, input_frame=det)
y, x = labelmapper.mapper.shape
y, x = np.mgrid[:y, :x]
r, d, l = wifu(x, y)

print(wifu.forward_transform.set_input(4)(1, 2))
```

--------------------------------

### gwcs: Add compound bounding boxes and examples module

Source: https://github.com/spacetelescope/gwcs/blob/master/CHANGES.rst

Introduces support for compound bounding boxes and ignored entries, and adds a new `gwcs.examples` module.

```Python
# Add support for compound bounding boxes and ignored bounding box entries. [#519]
# Add ``gwcs.examples`` module, based on the examples located in the testing ``conftest.py``. [#521]
```

--------------------------------

### GWCS Model Usage Example

Source: https://github.com/spacetelescope/gwcs/blob/master/docs/gwcs/user_introduction.rst

Demonstrates how to load a GWCS model from an ASDF file and use it to convert pixel coordinates to world coordinates. The example shows accessing the WCS object and performing a transformation.

```Python
import asdf
af = asdf.open('wcs_examples.asdf')
wcs = af['image_wcs']
print(wcs)
print(wcs.output_frame)
print(wcs(500, 600))
```

--------------------------------

### GWCS Basic Transformation and Insertion

Source: https://github.com/spacetelescope/gwcs/blob/master/docs/gwcs/using_wcs.rst

Demonstrates basic transformation scaling and inserting a transform into a WCS object. It also shows a forward transformation example.

```Python
>>> scale = models.Scale(2) & models.Scale(1)
>>> wcsobj.insert_transform('icrs', scale, after=False)
>>> wcsobj(1, 2)          # doctest: +FLOAT_CMP
(11.002128560195604, -72.04557376712566)
```

--------------------------------

### GWCS Transformation Example

Source: https://github.com/spacetelescope/gwcs/blob/master/docs/gwcs/user_introduction.rst

Demonstrates opening an ASDF file, accessing GWCS and data, transforming pixel coordinates to world coordinates (RA, Dec, wavelength), and inverting the transformation. It also shows how to inspect input and output frames.

```python
import asdf
import numpy as np
from matplotlib import pyplot as plt
plt.ion()
af = asdf.open('wcs_examples.asdf')
wcs = af['slit_wcs']
data = af['slit_data']
print(data.shape)
# print world coordinates of a single pixel corresponding to data[11, 220]
print(wcs(220, 11))
# Inspect input and output frames
print(wcs.input_frame)
print(wcs.output_frame)
# Determine the valid region of the data array
ysize, xsize = data.shape
y, x = np.mgrid[:ysize, :xsize]
ra, dec, lam = wcs(x, y)
# Create a mask for non-NaN values
mask = np.ones(data.shape, dtype=np.uint8)
mask[np.isnan(ra)] = 0
plt.imshow(mask)
plt.clf(); plt.imshow(lam)
plt.colorbar(orientation='horizontal', label='wavelength (microns)')
# Show that the wcs values round trip
ra1, dec1, lambda1 = wcs(220, 11)
print(wcs.invert(ra1, dec1, lambda1))
```

```asdf
{
  'slit_wcs': <GWCS object>,
  'slit_data': <numpy array>
}
```

--------------------------------

### FITS WCS Equivalent Construction

Source: https://github.com/spacetelescope/gwcs/blob/master/docs/gwcs/fits_analog.rst

Constructs a GWCS WCS object equivalent to a FITS imaging WCS. It involves defining detector and celestial frames and a transformation pipeline using astropy.modeling components like Shift, AffineTransformation2D, Pix2Sky_TAN, and RotateNative2Celestial.

```python
>>> import numpy as np
>>> from astropy.modeling import models
>>> from astropy import coordinates as coord
>>> from astropy import units as u
>>> from gwcs import wcs
>>> from gwcs import coordinate_frames as cf

>>> # Shift by CRPIX (adjusting for 1-based FITS indexing)
>>> shift_by_crpix = models.Shift(-(2048 - 1)*u.pix) & models.Shift(-(1024 - 1)*u.pix)

>>> # Rotation using PC matrix
>>> matrix = np.array([[1.290551569736E-05, 5.9525007864732E-06],
...                    [5.0226382102765E-06 , -1.2644844123757E-05]])
>>> rotation = models.AffineTransformation2D(matrix * u.deg,
...                                          translation=[0, 0] * u.deg)
>>> rotation.input_units_equivalencies = {"x": u.pixel_scale(1*u.deg/u.pix),
...                                       "y": u.pixel_scale(1*u.deg/u.pix)}
>>> rotation.inverse = models.AffineTransformation2D(np.linalg.inv(matrix) * u.pix,
...                                                  translation=[0, 0] * u.pix)
>>> rotation.inverse.input_units_equivalencies = {"x": u.pixel_scale(1*u.pix/u.deg),
...                                               "y": u.pixel_scale(1*u.pix/u.deg)}

>>> # Tangent projection and celestial rotation
>>> tan = models.Pix2Sky_TAN()
>>> celestial_rotation =  models.RotateNative2Celestial(5.63056810618*u.deg, -72.05457184279*u.deg, 180*u.deg)

>>> # Combined transformation pipeline
>>> det2sky = shift_by_crpix | rotation | tan | celestial_rotation
>>> det2sky.name = "linear_transform"

>>> # Define coordinate frames
>>> detector_frame = cf.Frame2D(name="detector", axes_names=("x", "y"),
...                             unit=(u.pix, u.pix))
>>> sky_frame = cf.CelestialFrame(reference_frame=coord.ICRS(), name='icrs',
...                               unit=(u.deg, u.deg))

>>> # Create the WCS pipeline
>>> pipeline = [(detector_frame, det2sky),
...             (sky_frame, None)
...            ]
>>> wcsobj = wcs.WCS(pipeline)
>>> print(wcsobj)
  From      Transform
-------- ----------------
detector linear_transform
    icrs             None

>>> # Convert pixel coordinates to sky coordinates
>>> sky = wcsobj(1*u.pix, 2*u.pix, with_units=True)
>>> print(sky)
<SkyCoord (ICRS): (ra, dec) in deg
  (5.52515954, -72.05190935)>
```

--------------------------------

### Python: gwcs Imaging Example with Distortion

Source: https://github.com/spacetelescope/gwcs/blob/master/docs/gwcs/imaging_with_distortion.rst

This snippet demonstrates the creation of a WCS object with polynomial distortion correction. It utilizes astropy's modeling classes like Shift, AffineTransformation2D, Pix2Sky_TAN, RotateNative2Celestial, Polynomial2D, and Mapping to define the transformations between detector and sky frames.

```python
import numpy as np
from astropy.modeling import models
from astropy import coordinates as coord
from astropy import units as u
from gwcs import wcs
from gwcs import coordinate_frames as cf

crpix = (2048, 1024)
shift_by_crpix = models.Shift(-crpix[0]) & models.Shift(-crpix[1])
matrix = np.array([[1.290551569736E-05, 5.9525007864732E-06],
                   [5.0226382102765E-06 , -1.2644844123757E-05]])
rotation = models.AffineTransformation2D(matrix)
rotation.inverse = models.AffineTransformation2D(np.linalg.inv(matrix))
tan = models.Pix2Sky_TAN()
celestial_rotation =  models.RotateNative2Celestial(5.63056810618, -72.05457184279, 180)
det2sky = shift_by_crpix | rotation | tan | celestial_rotation
det2sky.name = "linear_transform"
detector_frame = cf.Frame2D(name="detector", axes_names=("x", "y"),
                              unit=(u.pix, u.pix))
sky_frame = cf.CelestialFrame(reference_frame=coord.ICRS(), name='icrs',
                                unit=(u.deg, u.deg))
pipeline = [(detector_frame, det2sky),
            (sky_frame, None)
           ]
wcs_obj = wcs.WCS(pipeline)
print(wcs_obj)

poly_x = models.Polynomial2D(4)
poly_x.parameters = [0, 1, 8.55e-06, -4.73e-10, 2.37e-14, 0, -5.20e-06,
                     -3.98e-11, 1.97e-15, 2.17e-06, -5.23e-10, 3.47e-14,
                     1.08e-11, -2.46e-14, 1.49e-14]
poly_y = models.Polynomial2D(4)
poly_y.parameters = [0, 0, -1.75e-06, 8.57e-11, -1.77e-14, 1, 6.18e-06,
                     -5.09e-10, -3.78e-15, -7.22e-06, -6.17e-11,
                     -3.66e-14, -4.18e-10, 1.22e-14, -9.96e-15]
distortion = ((models.Shift(-crpix[0]) & models.Shift(-crpix[1])) |
              models.Mapping((0, 1, 0, 1)) | (poly_x & poly_y) |
              (models.Shift(crpix[0]) & models.Shift(crpix[1])))
distortion.name = "distortion"

undistorted_frame = cf.Frame2D(name="undistorted_frame", unit=(u.pix, u.pix),
                               axes_names=("undist_x", "undist_y"))

pipeline = [(detector_frame, distortion),
            (undistorted_frame, det2sky),
            (sky_frame, None)
            ]
wcs_obj = wcs.WCS(pipeline)
print(wcs_obj)

from asdf import AsdfFile
tree = {"wcs": wcs_obj}
wcs_file = AsdfFile(tree)
wcs_file.write_to("imaging_wcs_wdist.asdf")
```

--------------------------------

### Save and Read GWCS WCS Object with ASDF

Source: https://github.com/spacetelescope/gwcs/blob/master/docs/gwcs/constructing_gwcs_models.rst

Provides examples of saving a GWCS WCS object to a pure ASDF file and subsequently reading it back. This demonstrates the serialization capabilities of GWCS using the ASDF standard.

```python
from asdf import AsdfFile
import asdf

# Assuming wcsobj is a valid WCS object

# Save WCS object to an ASDF file
tree = {"wcs": wcsobj}
wcs_file = AsdfFile(tree)
wcs_file.write_to("imaging_wcs.asdf")

# Read WCS object from an ASDF file
asdf_file = asdf.open("imaging_wcs.asdf")
loaded_wcsobj = asdf_file.tree['wcs']
```

--------------------------------

### GWCS Pixel to Sky Transformation Example

Source: https://github.com/spacetelescope/gwcs/blob/master/docs/gwcs/constructing_gwcs_models.rst

Demonstrates a sequence of Astropy models used within GWCS to transform pixel coordinates to sky coordinates. This includes shifting the pixel origin, applying a plate scale, projecting to a tangent plane, and rotating to celestial coordinates.

```python
# Adjust pixel coordinates so the center is (0, 0)
pixelshift = models.Shift(-500) & models.Shift(-500)

# Scale pixels to the correct angular size (e.g., 0.1 arcsec/pixel)
pixelscale = models.Scale(0.1 / 3600.) & models.Scale(0.1 / 3600.)

# Project coordinates onto the sky using a TAN projection
tangent_projection = models.Pix2Sky_TAN()

# Rotate coordinates to align with celestial frame (RA=30, Dec=45, PA=180)
celestial_rotation = models.RotateNative2Celestial(30., 45., 180.)
```

--------------------------------

### GWCS WCS Inversion

Source: https://github.com/spacetelescope/gwcs/blob/master/docs/gwcs/fits_analog.rst

Explains the functionality of the `~gwcs.wcs.WCS.invert` method, which evaluates the `~gwcs.wcs.WCS.backward_transform` to map sky coordinates back to pixel coordinates. It notes that if an inverse transform is not available, an iterative method is used.

```python
# The :meth:`~gwcs.wcs.WCS.invert` method evaluates the :meth:`~gwcs.wcs.WCS.backward_transform` to provide a mapping from sky coordinates to pixel coordinates
# if available, otherwise it applies an iterative method to calculate the pixel coordinates.
```

--------------------------------

### Coordinate Transformation Lookup

Source: https://github.com/spacetelescope/gwcs/blob/master/docs/gwcs/ifu.rst

Retrieves and applies a coordinate transformation model based on a given label. It finds the index of the label in the internal list and then calls the corresponding model with the provided x and y coordinates.

```Python
index = self.labels.index(label)
return self.models[index](x, y)
```

--------------------------------

### ASDF Requirement Added

Source: https://github.com/spacetelescope/gwcs/blob/master/CHANGES.rst

Adds the ASDF package as a requirement for the setup, enabling ASDF serialization capabilities.

```Python
# setup.py modification: requires 'asdf'
```

--------------------------------

### Fit WCS from Pixel and Sky Coordinates

Source: https://github.com/spacetelescope/gwcs/blob/master/docs/gwcs/points_to_wcs.rst

Fits a GWCS object to a set of matched pixel and sky coordinates. Supports specifying projection type and geometric distortion models (e.g., polynomial). The function requires pixel coordinates (x, y) as a tuple of arrays, sky coordinates as an astropy.coordinates.SkyCoord object, and a fiducial point for the projection.

```python
from gwcs.wcstools import wcs_from_points
from astropy.coordinates import SkyCoord
import astropy.units as u
import numpy as np

# Matched coordinate pairs (20 pairs)
xy = (np.array([2810.156, 2810.156,  650.236, 1820.927, 3425.779, 2750.369,
                212.422, 1146.91 ,   27.055, 2100.888,  648.149,   22.212,
                2003.314,  727.098,  248.91 ,  409.998, 1986.931,  128.925,
                1106.654, 1502.67 ]),
      np.array([1670.347, 1670.347,  360.325,  165.663,  900.922,  700.148,
                1416.235, 1372.364,  398.823,  580.316,  317.952,  733.984,
                339.024,  234.29 , 1241.608,  293.545, 1794.522, 1365.706,
                583.135,   25.306]))
ra, dec = (np.array([246.75001315, 246.75001315, 246.72033646, 246.72303144,
                    246.74164072, 246.73540614, 246.73379121, 246.73761455,
	        	 246.7179495 , 246.73051123, 246.71970072, 246.7228646 ,
			 246.72647213, 246.7188386 , 246.7314031 , 246.71821002,
			 246.74785534, 246.73265223, 246.72579817, 246.71943263]),
	       np.array([43.48690547,  43.48690547,  43.46792989,  43.48075238,
		         43.49560501,  43.48903538,  43.46045875,  43.47030776,
			 43.46132376,  43.48252763,  43.46802566,  43.46035331,
			 43.48218262,  43.46908299,  43.46131665,  43.46560591,
			 43.47791234,  43.45973025,  43.47208325,  43.47779988]))
radec = SkyCoord(ra, dec, unit=(u.deg, u.deg))

# Fiducial point for the projection
proj_point = SkyCoord(246.7368408, 43.480712949, frame = 'icrs', unit = (u.deg,u.deg))

# Fit WCS with TAN projection and 4th degree polynomial distortion
gwcs_obj = wcs_from_points(xy, radec, proj_point, order=4)

# Example transformations
# Pixel to World (forward transformation)
world_coords = gwcs_obj(36.235, 642.215)
print(f"Pixel (36.235, 642.215) -> World: {world_coords}")

# Using WCS API for pixel to world
world_values = gwcs_obj.pixel_to_world_values(36.235, 642.215)
print(f"Pixel (36.235, 642.215) -> World Values: {world_values}")

world_skycoord = gwcs_obj.pixel_to_world(36.235, 642.215)
print(f"Pixel (36.235, 642.215) -> SkyCoord: {world_skycoord}")
```

--------------------------------

### GWCS Custom Model for Transforms

Source: https://github.com/spacetelescope/gwcs/blob/master/docs/gwcs/ifu.rst

This snippet defines a custom `astropy.modeling.core.Model` subclass named `CustomModel`. This model is designed to store and apply different transforms based on input labels, suitable for cases where a pixel-to-slice mapping is not available.

```python
from astropy.modeling.core import Model
from astropy.modeling.parameters import Parameter


class CustomModel(Model):

    inputs = ('label', 'x', 'y')
    outputs = ('xout', 'yout')


    def __init__(self, labels, transforms):
        super().__init__()
        self.labels = labels
        self.models = models

    def evaluate(self, label, x, y):
        # Placeholder for the actual evaluation logic
        pass
```

--------------------------------

### Prepare Distribution Package

Source: https://github.com/spacetelescope/gwcs/wiki/Release-procedures

Cleans the working directory, builds the source distribution package using setup.py, and prepares for signing and uploading to PyPI.

```python
git clean -dfx
python setup.py build sdist
```

--------------------------------

### Sign and Upload to PyPI

Source: https://github.com/spacetelescope/gwcs/wiki/Release-procedures

Signs the distribution package with GPG and uploads it to PyPI using twine. This is a manual step for publishing the release.

```python
git clean -dfx
python setup.py build sdist
gpg --detach-sign -a dist/gwcs-2.0.0.tar.gz
twine upload dist/gwcs-2.0.0.tar.gz
```

--------------------------------

### Prepare Release Branch

Source: https://github.com/spacetelescope/gwcs/wiki/Release-procedures

Steps to create and checkout a new release branch from the master branch. It includes checking the current branch, creating a new branch (e.g., '2.0.0x'), and switching to it.

```git
git status
git branch 2.0.0x
git checkout 2.0.0x
```

--------------------------------

### gwcs: Removed astropy-helpers from package

Source: https://github.com/spacetelescope/gwcs/blob/master/CHANGES.rst

Removed the `astropy-helpers` dependency from the gwcs package, simplifying installation and reducing external dependencies.

```Python
# Removed astropy-helpers from package.
# ... implementation details ...
```

--------------------------------

### Clone GWCS Repository

Source: https://github.com/spacetelescope/gwcs/wiki/Release-procedures

Clones the GWCS repository from GitHub using SSH. This is the initial step before preparing a release branch.

```git
git clone git@github.com:spacetelescope/gwcs.git
```

--------------------------------

### Get WCS Footprint

Source: https://github.com/spacetelescope/gwcs/blob/master/docs/gwcs/using_wcs.rst

Calculates and returns the footprint of the WCS transformation on the sky, represented as an array of coordinates.

```Python
print(wcsobj.footprint())
```

--------------------------------

### Tag and Push Stable Branch

Source: https://github.com/spacetelescope/gwcs/wiki/Release-procedures

Checks out the 'stable' branch, tags it with the new release version (e.g., '2.0.0'), and pushes the tag to the remote repository.

```git
git checkout stable
git tag -a "2.0.0" -m "tagging release 2.0.0"
git push origin 2.0.0
```

--------------------------------

### Tag Master for Further Development

Source: https://github.com/spacetelescope/gwcs/wiki/Release-procedures

Checks out the 'master' branch and tags it with the next development version (e.g., '2.1.0a') to facilitate nightly builds and indicate ongoing development.

```git
git checkout master
git tag -a "2.1.0a" -m "tagging for further development"
git push origin 2.1.0a
```

--------------------------------

### Create and Use GWCS WCS Object

Source: https://github.com/spacetelescope/gwcs/blob/master/docs/gwcs/constructing_gwcs_models.rst

Shows how to define input and output frames of reference and create a WCS object by combining frames with their associated transformations. It also demonstrates how to query the WCS object to convert pixel coordinates to sky coordinates.

```python
detector_frame = cf.Frame2D(name="detector", axes_names=("x", "y"),
                            unit=(u.pix, u.pix))
sky_frame = cf.CelestialFrame(reference_frame=coord.ICRS(), name='icrs',
                                unit=(u.deg, u.deg))

# Assuming det2sky is defined as the transformation from detector to sky
wcsobj = wcs.WCS([(detector_frame, det2sky),
                  (sky_frame, None)
                 ])

# Convert pixel coordinates (1, 2) to sky coordinates
sky = wcsobj(1, 2)
print(sky)
```

--------------------------------

### Push Release Branch and Create PR

Source: https://github.com/spacetelescope/gwcs/wiki/Release-procedures

Pushes the newly created release branch to the remote repository (spacetelescope) and prepares for creating a Pull Request to the 'stable' branch.

```git
git push origin 2.0.0x
```

--------------------------------

### gwcs: Improve documentation and add asdf-wcs-schemas minimum version

Source: https://github.com/spacetelescope/gwcs/blob/master/CHANGES.rst

Enhances the project's documentation and sets a minimum version requirement for the `asdf-wcs-schemas` package.

```Python
# Improve documentation. [#483]
# Add a minimum version requirement for ``asdf-wcs-schemas``. [#491]
```

--------------------------------

### gwcs: Switch to new sphinx theme and clean documentation

Source: https://github.com/spacetelescope/gwcs/blob/master/CHANGES.rst

Updates the documentation build process by adopting a new Sphinx theme and cleaning up the existing documentation.

```Python
# Switch to using a new sphinx theme and clean up the documentation. [#580]
```

--------------------------------

### Tag Release Branch

Source: https://github.com/spacetelescope/gwcs/wiki/Release-procedures

Checks out the release branch again, tags it with the new release version, and pushes the tag to the remote repository. This is done after the PR is merged into stable.

```git
git checkout 2.0.0x
git tag -a "2.0.0" -m "tagging release 2.0.0"
git push origin 2.0.0
```

--------------------------------

### gwcs: Use CD formalism in WCS.to_fits_sip()

Source: https://github.com/spacetelescope/gwcs/blob/master/CHANGES.rst

Implemented the use of the `CD` formalism within the `WCS.to_fits_sip()` method for generating FITS WCS headers.

```Python
from gwcs import WCS

# Use 'CD' formalism in WCS.to_fits_sip()
# ... implementation details ...
```

--------------------------------

### GWCS Model Construction Imports

Source: https://github.com/spacetelescope/gwcs/blob/master/docs/gwcs/constructing_gwcs_models.rst

Imports necessary modules from Astropy and GWCS for constructing world coordinate system models. These include models for transformations, coordinate frames, and the main GWCS class.

```python
import numpy as np
from astropy.modeling import models
from astropy import coordinates as coord
from astropy import units as u
from gwcs import wcs
from gwcs import coordinate_frames as cf
```

--------------------------------

### gwcs: Add to_fits_sip method for FITS header generation

Source: https://github.com/spacetelescope/gwcs/blob/master/CHANGES.rst

Added the `to_fits_sip` method to generate FITS headers including SIP (Simple Imaging Polynomial) keywords, facilitating WCS representation in FITS files.

```Python
from gwcs import WCS

# Added to_fits_sip method to generate FITS header with SIP keywords
# ... implementation details ...
```

--------------------------------

### GWCS Spectroscopy Module API

Source: https://github.com/spacetelescope/gwcs/blob/master/docs/gwcs/api.rst

API documentation for the gwcs.spectroscopy module, focusing on WCS transformations relevant to spectroscopic data, including inherited members.

```APIDOC
gwcs.spectroscopy
  :inherited-members:
  Contains classes and functions specifically designed for handling spectroscopic WCS, including wavelength and spectral resolution transformations.
```

--------------------------------

### gwcs: Replace pkg_resources with importlib.metadata and serialize pixel_shape

Source: https://github.com/spacetelescope/gwcs/blob/master/CHANGES.rst

Updates dependency management by replacing `pkg_resources` with `importlib.metadata` and enables serialization/deserialization of `pixel_shape` with ASDF.

```Python
# Replace ``pkg_resources`` with ``importlib.metadata``. [#478]
# Serialize and deserialize ``pixel_shape`` with asdf. [#480]
```

--------------------------------

### GWCS Inverse Transformation with Numerical Inverse

Source: https://github.com/spacetelescope/gwcs/blob/master/docs/gwcs/using_wcs.rst

Illustrates how to compute inverse transformations using `WCS.invert()` and `WCS.numerical_inverse()`. It covers converting single points and multiple points, and handling potential numerical issues.

```Python
>>> import asdf
>>> from astropy.utils.data import get_pkg_data_filename
>>> wcsobj = asdf.open(get_pkg_data_filename('imaging_wcs_wdist.asdf')).tree['wcs']

>>> world = wcsobj(350, 200)
>>> print(wcsobj.invert(*world))  # convert a single point
(349.9999994163172, 200.00000017679295)
>>> world = wcsobj([2, 350, -5000], [2, 200, 6000])
>>> print(wcsobj.invert(*world))  # convert multiple points at once
(array([ 1.99999752,  3.49999999e+02, -5.00000000e+03]), array([1.99999972e+00, 2.00000002e+02, 6.00000000e+03])
```

```Python
>>> from gwcs import NoConvergence
>>> world = wcsobj([-85000, 2, 350, 3333, -5000], [-55000, 2, 200, 1111, 6000],
...                with_bounding_box=False)
>>> try:
...     x, y = wcsobj.invert(*world, quiet=False, maxiter=40,
...                          detect_divergence=True, with_bounding_box=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: [0]
Indices of poorly converging points: [4]
Best solution:
[[ 1.38600585e+11  6.77595594e+11]
 [ 2.00000000e+00  1.99999972e+00]
 [ 3.49999999e+02  2.00000002e+02]
 [ 3.33300000e+03  1.11100000e+03]
 [-4.99999985e+03  5.99999985e+03]]
Achieved accuracy:
[[8.56497375e+02 5.09216089e+03]
 [6.57962988e-06 3.70445289e-07]
 [5.31656943e-06 2.72052603e-10]
 [6.81557583e-06 1.06560533e-06]
 [3.96365344e-04 6.41822468e-05]]
```

--------------------------------

### gwcs: Reorganize documentation and drop Python 3.10

Source: https://github.com/spacetelescope/gwcs/blob/master/CHANGES.rst

Restructures the project's documentation into user and developer introductions and removes support for Python 3.10.

```Python
# Reorganize documentation to have two separate introductions (user and developer) [#604]
# Test with latest version of Python and drop Python 3.10 [#569]
```

--------------------------------

### GWCS Selector Module API

Source: https://github.com/spacetelescope/gwcs/blob/master/docs/gwcs/api.rst

API documentation for the gwcs.selector module, which handles the selection of appropriate WCS transformations based on input coordinates, including inherited members.

```APIDOC
gwcs.selector
  :inherited-members:
  Implements logic for selecting the correct WCS transformation pipeline based on input data characteristics or coordinate values, facilitating complex multi-component WCS definitions.
```

--------------------------------

### gwcs: Enable CompoundBoundingBox support

Source: https://github.com/spacetelescope/gwcs/blob/master/CHANGES.rst

Enabled support for `CompoundBoundingBox` within the gwcs package. This allows for more complex bounding box definitions and handling.

```Python
from gwcs.regions import CompoundBoundingBox

# Enable CompoundBoundingBox support
# ... implementation details ...
```

--------------------------------

### GWCS Extensibility

Source: https://github.com/spacetelescope/gwcs/blob/master/docs/gwcs/user_introduction.rst

Mechanisms are provided for extending GWCS transformations and their serialization. This allows instruments or telescopes to incorporate custom extensions into formats like ASDF without requiring standards updates.

```Python
# Example: Defining a custom transformation and its serialization
# class MyCustomTransform(gwcs.transform.Transform):
#     def __call__(self, x, y):
#         # Custom transformation logic
#         return new_x, new_y
#
#     def inverse(self, x, y):
#         # Inverse transformation logic
#         return inv_x, inv_y
#
# # Registering custom transform for serialization (details depend on serialization library)
```

--------------------------------

### gwcs: Add to_fits_tab method

Source: https://github.com/spacetelescope/gwcs/blob/master/CHANGES.rst

Added the `to_fits_tab` method to generate FITS header and binary table extensions conforming to the FITS WCS '-TAB' convention.

```Python
from gwcs import WCS

# Added to_fits_tab method to generate FITS header and binary table extension
# ... implementation details ...
```

--------------------------------

### gwcs: Add WCS.Step class for ASDF serialization

Source: https://github.com/spacetelescope/gwcs/blob/master/CHANGES.rst

Introduced a `wcs.Step` class to facilitate the use of references during serialization to ASDF format.

```Python
from gwcs import WCS

# Added wcs.Step class for serialization to ASDF using references
# ... implementation details ...
```

--------------------------------

### gwcs: Fix unit handling in __call__ and invert

Source: https://github.com/spacetelescope/gwcs/blob/master/CHANGES.rst

Corrects a bug in the `__call__` and `invert` methods that affected unit handling with parameterless transforms.

```Python
# Bugfix for ``__call__`` and ``invert`` incorrectly handling units when involving
# "parameterless" transforms. [#562]
```

--------------------------------

### gwcs: WCS.pipeline is now a list of Step instances

Source: https://github.com/spacetelescope/gwcs/blob/master/CHANGES.rst

The `WCS.pipeline` attribute is now a list of `Step` instances, replacing the previous tuple format of (frame, transform). Access components via `WCS.pipeline.transform` and `WCS.pipeline.frame`.

```Python
from gwcs import WCS

# WCS.pipeline is now a list of Step instances
# Access transforms via: wcs.pipeline.transform
# Access frames via: wcs.pipeline.frame
# ... implementation details ...
```

--------------------------------

### TemporalFrame Initialization Consistency

Source: https://github.com/spacetelescope/gwcs/blob/master/CHANGES.rst

Ensures the initialization of TemporalFrame is consistent with other coordinate frames, improving usability and adherence to standards.

```Python
from gwcs.frames import TemporalFrame
```

--------------------------------

### gwcs: Fix deprecation warning with pipeline initialization

Source: https://github.com/spacetelescope/gwcs/blob/master/CHANGES.rst

Resolved a deprecation warning that occurred when initializing `gwcs` with a pipeline, ensuring compatibility with current standards.

```Python
from gwcs import WCS

# Fix deprecation warning when wcs is initialized with a pipeline
# ... implementation details ...
```

--------------------------------

### Load and Print WCS Object

Source: https://github.com/spacetelescope/gwcs/blob/master/docs/gwcs/using_wcs.rst

Loads a WCS object from an ASDF file and prints its structure, showing the coordinate frames involved in the transformation pipeline.

```Python
import asdf
asdf_file = asdf.open("imaging_wcs_wdist.asdf")
wcsobj = asdf_file.tree["wcs"]
print(wcsobj)
```

--------------------------------

### gwcs: Generalized WCS.to_fits_sip for FITS WCS

Source: https://github.com/spacetelescope/gwcs/blob/master/CHANGES.rst

Generalized `WCS.to_fits_sip` to create a 2D celestial FITS WCS from the celestial subspace of a WCS. It now supports arbitrary order of output axes.

```Python
from gwcs import WCS

# Generalized WCS.to_fits_sip to create a 2D celestial FITS WCS
# Supports arbitrary order of output axes.
# ... implementation details ...
```

--------------------------------

### GWCS Transformations

Source: https://github.com/spacetelescope/gwcs/blob/master/docs/gwcs/user_introduction.rst

GWCS allows arbitrary construction of transformations by combining simpler transformations arithmetically or by feeding the output of one transformation into another. It provides a rich library of transformations, including all FITS-supported projections.

```Python
from gwcs import wcs
from gwcs import utils

# Example: Combining transformations
# Assume 'transform1' and 'transform2' are defined transformation objects
# combined_transform = utils.add_transform(transform1, transform2)
# or
# combined_transform = utils.compose_transform(transform1, transform2)
```

--------------------------------

### grid_from_domain Function

Source: https://github.com/spacetelescope/gwcs/blob/master/CHANGES.rst

Introduces the `grid_from_domain` function for generating grids based on the WCS domain.

```Python
from gwcs import grid_from_domain
# Example usage: grid = grid_from_domain(wcs_object, ...)
```

--------------------------------

### New Grating Equation Transforms

Source: https://github.com/spacetelescope/gwcs/blob/master/CHANGES.rst

Introduces new transforms for grating equations, enabling more advanced optical path calculations.

```Python
from gwcs.transforms import WavelengthFromGratingEquation, AnglesFromGratingEquation3D
```

--------------------------------

### gwcs: Implement code linting and formatting, refactor WCS

Source: https://github.com/spacetelescope/gwcs/blob/master/CHANGES.rst

Introduces code linting and automatic formatting. Refactors `WCS` to use a `Pipeline` base class for validation checks.

```Python
# Implement code linting and automatic formatting. [#544]
# Refactor ``WCS`` to use a ``Pipeline`` base class which adds basic checks to ensure that the pipeline is valid. These
# include checking for duplicate frame names and that the last transform is ``None``. [#545]
```

--------------------------------

### gwcs: Allow sub-pixel sampling in to_fits_sip()

Source: https://github.com/spacetelescope/gwcs/blob/master/CHANGES.rst

Enabled sub-pixel sampling of the WCS model when computing the SIP approximation in the `to_fits_sip()` method.

```Python
from gwcs import WCS

# Allow sub-pixel sampling of WCS model in to_fits_sip()
# ... implementation details ...
```

--------------------------------

### Replace and Apply Transform

Source: https://github.com/spacetelescope/gwcs/blob/master/docs/gwcs/using_wcs.rst

Replaces an existing transform in the WCS pipeline with a new one and demonstrates the effect on the WCS transformation output.

```Python
from gwcs import models
new_transform = models.Shift(1) & models.Shift(1.5) | distortion
wcsobj.set_transform('detector', 'undistorted_frame', new_transform)
print(wcsobj(1, 2))
```

--------------------------------

### GWCS WCS Module API

Source: https://github.com/spacetelescope/gwcs/blob/master/docs/gwcs/api.rst

API documentation for the gwcs.wcs module, including inherited members. This module is central to defining and applying World Coordinate Systems.

```APIDOC
gwcs.wcs
  :inherited-members:
  Provides the core functionality for World Coordinate System (WCS) transformations, including the definition of celestial and spectral coordinate systems and the application of transformations between them.
```

--------------------------------

### gwcs: Support custom range of degrees in to_fits_sip()

Source: https://github.com/spacetelescope/gwcs/blob/master/CHANGES.rst

Added support for providing a custom range of degrees when using the `to_fits_sip()` method, allowing more control over the generated FITS WCS.

```Python
from gwcs import WCS

# Added support for providing custom range of degrees in to_fits_sip()
# ... implementation details ...
```

--------------------------------

### New 3D Transforms

Source: https://github.com/spacetelescope/gwcs/blob/master/CHANGES.rst

Adds new transforms for 3D optical path calculations, including Snell's law and Sellmeier equations for glass properties.

```Python
from gwcs.transforms import Snell3D, SellmeierGlass, SellmeierZemax
```

--------------------------------

### WCS Initialization with Pipeline

Source: https://github.com/spacetelescope/gwcs/blob/master/CHANGES.rst

Allows initializing a WCS object with a pipeline from another WCS object, preserving complete CoordinateFrame objects.

```Python
from gwcs import WCS

# Initialize WCS with a pipeline from another WCS object
```

--------------------------------

### Invert GWCS Transformation and Use Astropy API

Source: https://github.com/spacetelescope/gwcs/blob/master/docs/gwcs/constructing_gwcs_models.rst

Illustrates how to invert a WCS transformation using the `invert` method and how to leverage the `wcsapi` for seamless integration with Astropy objects like SkyCoord. It shows converting pixel to world coordinates and vice versa.

```python
# Assuming wcsobj is a valid WCS object

# Convert pixel to world coordinates using wcsapi
sky_obj = wcsobj.pixel_to_world(1, 2)
print(sky_obj)

# Convert world back to pixel coordinates
world_to_pixel_result = wcsobj.world_to_pixel(sky_obj)
print(world_to_pixel_result)
```

--------------------------------

### Generate Grid from Bounding Box

Source: https://github.com/spacetelescope/gwcs/blob/master/docs/gwcs/wcstools.rst

The `grid_from_bounding_box` function generates a grid of input points based on the provided bounding box of a WCS. It takes a bounding box tuple as input and returns the x and y coordinates of the grid points.

```Python
from gwcs.wcstools import grid_from_bounding_box
bounding_box = ((0, 4096), (0, 2048))
x, y = grid_from_bounding_box(bounding_box)
# Example usage with a WCS object (w):
# ra, dec = w(x, y)   # doctest: +SKIP
```

--------------------------------

### FITS Header Keywords for GWCS

Source: https://github.com/spacetelescope/gwcs/blob/master/gwcs/tests/data/stokes.txt

This snippet details various FITS header keywords used for defining World Coordinate System (WCS) information, pixel coordinates, spectral parameters, and observation metadata within the GWCS project.

```FITS
WCSAXES =                    4 / Number of coordinate axes
CRPIX1  =                126.0 / Pixel coordinate of reference point
CRPIX2  =                126.0 / Pixel coordinate of reference point
CRPIX3  =                  1.0 / Pixel coordinate of reference point
CRPIX4  =                  1.0 / Pixel coordinate of reference point
CDELT1  =  -2.777777777778E-05 / [deg] Coordinate increment at reference point
CDELT2  =   2.777777777778E-05 / [deg] Coordinate increment at reference point
CDELT3  =       20000205938.09 / [Hz] Coordinate increment at reference point
CDELT4  =                  1.0 / Coordinate increment at reference point
CUNIT1  = 'deg'                / Units of coordinate increment and value
CUNIT2  = 'deg'                / Units of coordinate increment and value
CUNIT3  = 'Hz'                 / Units of coordinate increment and value
CTYPE1  = 'RA---SIN'           / Right ascension, orthographic/synthesis project
CTYPE2  = 'DEC--SIN'           / Declination, orthographic/synthesis projection
CTYPE3  = 'FREQ'               / Frequency (linear)
CTYPE4  = 'STOKES'             / Coordinate type code
CRVAL1  =         202.78453375 / [deg] Coordinate value at reference point
CRVAL2  =       30.50915555556 / [deg] Coordinate value at reference point
CRVAL3  =       233000102969.0 / [Hz] Coordinate value at reference point
CRVAL4  =                  1.0 / Coordinate value at reference point
PV2_1   =                  0.0 / SIN projection parameter
PV2_2   =                  0.0 / SIN projection parameter
LONPOLE =                180.0 / [deg] Native longitude of celestial pole
LATPOLE =       30.50915555556 / [deg] Native latitude of celestial pole
RESTFRQ =       224000000000.1 / [Hz] Line rest frequency
TIMESYS = 'UTC'                / Time scale
MJDREF  =                  0.0 / [d] MJD of fiducial time
DATE-OBS= '2014-07-01T21:36:05.280000' / ISO-8601 time of observation
MJD-OBS =      56839.900061111 / [d] MJD of observation
OBSGEO-X=       2225142.180269 / [m] observatory X-coordinate
OBSGEO-Y=      -5440307.370349 / [m] observatory Y-coordinate
OBSGEO-Z=      -2481029.851874 / [m] observatory Z-coordinate
RADESYS = 'FK5'                / Equatorial coordinate system
EQUINOX =               2000.0 / [yr] Equinox of equatorial coordinates
SPECSYS = 'TOPOCENT'           / Reference frame of spectral coordinates
END
```

--------------------------------

### Define Pixel to Celestial Transformation in GWCS

Source: https://github.com/spacetelescope/gwcs/blob/master/docs/gwcs/constructing_gwcs_models.rst

Demonstrates defining a sequence of transformations to convert pixel coordinates to celestial coordinates. This involves composing transformations like pixel shift, scaling, projection, and rotation.

```python
from gwcs import wcs
from gwcs import celestial_frame as cf
from astropy import units as u
from astropy import coordinates as coord

# Assuming pixelshift, pixelscale, tangent_projection, celestial_rotation are defined transformations
# Example placeholder transformations:
pixelshift = None # Replace with actual transformation
pixelscale = None # Replace with actual transformation
tangent_projection = None # Replace with actual transformation
celestial_rotation = None # Replace with actual transformation

det2sky = pixelshift | pixelscale | tangent_projection | celestial_rotation
```