Kapteyn Institute Kapteyn Package

How to start


This chapter is intended to be a guide on how to use the modules from the Kapteyn Package for your own astronomical software. The Kapteyn Package provides building blocks for software that has a focus on the use of world coordinates and/or plotting image data.

To get an overview of what is possible, have a look at Tutorial maputils module which contains many examples of world coordinate annotations and plots of astronomical data. It can be a good starting point to use the source code in the example scripts to process your own data by making only small changes to the code.

If you are only interested in coordinate transformations, then the Tutorial wcs module is a good starting point.

Which module and documents to use?

You want: You need:
For a set of world coordinates, I want to transform these to another projection system. I have a FITS header. wcs, Tutorial wcs module
I want to transform world coordinates between sky- and reference systems wcs, Tutorial wcs module
I want a parser to convert a string with position information to pixel- and/or world coordinates. positions
I want to transform image data in a FITS file from one projection system to another maputils, Tutorial maputils module
I want to build a utility that converts a header with a PC or CD matrix to a ‘classic’ header with CRPIX, CRVAL, CDELT and CROTA maputils, Tutorial maputils module
I want to create a utility that can display a mosaic of image data maputils, Tutorial maputils module
I want to plot an all sky map with graticules maputils, Tutorial maputils module
I want to calculate flux in a set of images maputils, shapes, Tutorial maputils module
I want to create a simple FITS file viewer with user interaction for the colors etc. maputils, Tutorial maputils module
I want to read a large data file very fast tabarray, Tutorial tabarray module
Given a year, month and day number, I want the corresponding Julian date celestial, Tutorial wcs module
I want to know the obliquity of the ecliptic at a Julian date? celestial, Tutorial wcs module, Background information module celestial
I want to convert my spectral axis from frequency to relativistic velocity wcs, Tutorial maputils module, Background information spectral translations

Functionality of the modules in the Kapteyn Package


  • Given a FITS header or a Python dictionary with header information about a World Coordinate System (WCS), transform between pixel- and world coordinates.
  • Different coordinate representations are possible (tuple of scalars, NumPy array etc.)
  • Transformations between sky and reference systems.
  • Epoch transformations
  • Support for ‘alternate’ headers (a header can have more than one description of a WCS)
  • Support for mixed coordinate transformations (i.e. pixel- and world coordinates at input are mixed).
  • Spectral coordinate translations, e.g. convert a frequency axis to an optical velocity axis.


  • Coordinate transformations between sky and reference systems. Also available via module wcs
  • Epoch transformations. Also available via module wcs
  • Many utility functions e.g. to convert epochs, to parse strings that define sky- and reference systems, calculate Julian dates, precession angles etc.


  • Most of the functionality in this module is provided via user friendly methods in module maputils.
  • Calculate grid lines showing constant latitude as function of varying longitude or vice versa.
  • Methods to set the properties of various plot elements like tick marks, tick labels and axis labels.
  • Methods to calculate positions of labels inside a plot (e.g. for all sky plots).


  • Easy to combine with Matplotlib
  • Convenience methods for methods of modules wcs, celestial, wcsgrat
  • Overlays of different graticules (each representing a different sky system),
  • Plots of data slices from a data set with more than two axes (e.g. a FITS file with channel maps from a radio interferometer observation)
  • Plots with a spectral axis with a ‘spectral translation’ (e.g. Frequency to Radio velocity)
  • Rulers with distances in world coordinates, corrected for projections.
  • Plots for data that cover the entire sky (allsky plot)
  • Mosaics of multiple images (e.g. HI channel maps)
  • A simple movie loop program to view ‘channel’ maps.
  • Interactive colormap selection and modification.


  • Convert strings to positions in pixel- and world coordinates


  • Plot a straight line with markers at constant distance in world coordinates. Its functionality is available in module maputils


  • Advanced plotting with user interaction. A user defines a shape (polygon, ellipse, circle, rectangle, spline) in an image and the shape propagates (in world coordinates) to other images. A shape object keeps track of its area (in pixels) and the sum of the pixels within the shape. From these a flux can be calculated.


  • Fast I/O for data in ASCII files on disk.


  • Various advanced utilities for event handling in Matplotlib. Most of its functionality is used in module maputils.

Table Of Contents

Please cite the Kapteyn Package if you use it in the preparation of a publication. These citations help us to justify the resources spent on this software.