Skip to main content
`Ctrl`+`K`

# Initializing axes with world coordinates

## Basic initialization

To make a plot using `WCSAxes`, we first read in the data using astropy.io.fits and parse the WCS information. In this example, we will use an example FITS file from the http://data.astropy.org server (the `get_pkg_data_filename()` function downloads the file and returns a filename):

    from astropy.wcs import WCS
    from astropy.io import fits
    from astropy.utils.data import get_pkg_data_filename

    filename = get_pkg_data_filename('galactic_center/gc_msx_e.fits')

    hdu = fits.open(filename)[0]
    wcs = WCS(hdu.header)

We then create a figure using Matplotlib and create the axes using the `WCS` object created above. The following example shows how to do this with the Matplotlib ‘pyplot’ interface, keeping a reference to the axes object:

    import matplotlib.pyplot as plt
    fig, ax = plt.subplots(subplot_kw=dict(projection=wcs))

The `ax` object created is an instance of the `WCSAxes` class. Note that if no WCS transformation is specified, the transformation will default to identity, meaning that the world coordinates will match the pixel coordinates.

The field of view shown is, as for standard matplotlib axes, 0 to 1 in both directions, in pixel coordinates. As soon as you show an image (see Plotting images and contours), the limits will be adjusted, but if you want you can also adjust the limits manually. Adjusting the limits is done using the same functions/methods as for a normal Matplotlib plot:

    ax.set_xlim(-0.5, hdu.data.shape[1] - 0.5)
    ax.set_ylim(-0.5, hdu.data.shape[0] - 0.5)

Note

If you use the pyplot interface, you can also replace `ax.set_xlim` and `ax.set_ylim` by `plt.xlim` and `plt.ylim`.

## Alternative methods

As in Matplotlib, there are in fact several ways you can initialize the `WCSAxes`.

As shown above, the simplest way is to make use of the `WCS` class and pass this to `plt.subplot`. If you normally use the (partially) object-oriented interface of Matplotlib, you can also do:

    fig = plt.figure()
    ax = fig.add_subplot(1, 1, 1, projection=wcs)

Note that this also works with `add_axes()` and `axes()`, e.g.:

    ax = fig.add_axes([0.1, 0.1, 0.8, 0.8], projection=wcs)

or:

    plt.axes([0.1, 0.1, 0.8, 0.8], projection=wcs)

Any additional arguments passed to `add_subplot()`, `add_axes()`, `subplot()`, or `axes()`, such as `slices` or `frame_class`, will be passed on to the `WCSAxes` class.

## Directly initializing WCSAxes

As an alternative to the above methods of initializing `WCSAxes`, you can also instantiate `WCSAxes` directly and add it to the figure:

    from astropy.wcs import WCS
    from astropy.visualization.wcsaxes import WCSAxes
    import matplotlib.pyplot as plt

    wcs = WCS(...)

    fig = plt.figure()
    ax = WCSAxes(fig, [0.1, 0.1, 0.8, 0.8], wcs=wcs)
    fig.add_axes(ax)  # note that the axes have to be explicitly added to the figure