KAPPA is package of general-purpose astronomical image-processing and visualization commands. It is documented in SUN/95. Over the long history of the KAPPA package, many internal Fortran subroutines have been written to provide facilities within KAPPA which have subsequently proved to be of more-general use outside KAPPA. In order to gain the benefit of these internal KAPPA facilities, software developers have in the past taken copies of the relevant routines and included them in their own projects. The disadvantages of this are obvious—it is easy to end up with many, potentially different, copies of the same routines within a large software suite such as the Starlink Software Collection, and bug fixes need to be implemented in many different places, rather than a in single master copy.
Another way of using the internal KAPPA routines is to link your applications directly against the libraries in the KAPPA package, but this requires the KAPPA package to be installed anywhere where your software is to be built, which is not always convenient.
To get round these problems, the KAPLIBS package was created to contain the internal routines from KAPPA which are deemed to be “generally useful”. Now, you only need to have KAPLIBS installed to build your software, not the much larger KAPPA.
There are a large number of routines in KAPLIBS, making it potentially difficult to find the routines you want. To ease this problem, a search tool is provided which allows the contents of this document to be searched (see SEC:SEARCH).
KAPLIBS was created as a pragmatic solution to the problem of proliferation of KAPPA source code in several other packages. One of the reasons for previously keeping these routines hidden away within KAPPA was so that changes could be made to the argument lists or functionality of these routines without breaking software within other packages. In practice, it has hardly ever been necessary to change the interface to routines after an initial development period, but the possibility still exists that this may be necessary. For this reason, users of KAPLIBS should be aware that it may occasionally be necessary to change the interface to KAPLIBS routines. Such changes will be listed within this document at each release. To aid developers decisions over which routines to use, routines which are deemed to have a significant chance of being changed within the foreseeable future are highlighted later in this document. This class of routine will normally just include routines which have only recently been written.
The purpose of this document is to give reference information about the argument lists and functionality of the internal KAPPA routines which are contained within KAPLIBS. It does not give a detailed explanation of how these routines should be used within a real application. Developers should usually study examples of existing code within KAPPA for this purpose. The source code for KAPPA is available from the source code repository at https://github.com/Starlink/starlink.
Applications within KAPPA are split up into several groups (called “monoliths’), with names such as
kapview, ndfpack and (rather confusingly but at one time the only KAPPA monolith) kappa. The
top-level routines for the applications in monolith xyz are in the tar file $KAPPA_DIR/xyz_sub.tar.
Each application may use some application-specific subroutines (i.e. subroutines which are so closely
related to the purpose of a single application that they are not deemed as “generally useful”). These
will be denoted by subroutines names with prefix “KPS1_” and will be contained within the tar file
$KAPPA_DIR/kapsub_sub.tar.