PUNCH_IDL_Tools

Tools for accessing PUNCH data in IDL and/or GDL.

These tools require the gen and astrom packages from SolarSoft, and optionally the vso/ontology package.

The intent is that they will allow SolarSoft users to ingest and interpret any level of PUNCH data from Level 0 to 3.

They should work equally well in recent versions of IDL and the current GIT of GDL.

Status

These routines have as yet had limited testing. In particular, as yet no images with non-null distortion tables have been available for testing.

All testing by the Author has been on Linux systems (OpenSuSE with IDL and Manjaro with GDL)

Note: using distortion tables on low-level data requires the latest version of wcs_get_pixel, please ensure that your SolarSoft installation has been updated since 29-Oct-2025.

Tools provided

READ_PUNCH:

Reads a PUNCH FITS file into IDL. This should handle the Rice-compressed files either with the shared library in the appropriate subdirectory of /soft/rsi/ssw/vobs/ontology/binaries/ and fitsio_read_image or via the imcopy command, and the regular readfits procedure.

In general, it is probably better to use the shared library by adding the /use_shared_lib keyword. However the use of DLL's is not (yet) supported by GDL so imcopy must be used in that case. This is configured as the default behaviour.

N.B. The layout of a Rice-compressed file is assumed to be:

• A dummy header for the primary data block.
• The actual primary data compressed into a BINTABLE in the first extension.
• Uncertainty information in the second extension.
• Distortion lookup tables in later extensions (fits_info is used to identify them).

PUNCH_STACK

Reads the data from a list of PUNCH FITS files into a data cube. Also returns supporting data (uncertainties and distortions) as available.

Reads the data using read_punch.pro from a list of PUNCH FITS files into data cubes of total brightness and polarized brightness. Also returns supporting data (uncertainties and distortions) as available.

WCS_APPEND_TABLES

Append the distortion tables to the WCS structure generated by fitshead2wcs so that they can be used by wcs_get_coord and wcs_get_pixel.

Notes:

• When the shared libraries are used, including the filename = ... keyword should also work.
• Relies on PUNCH NOT using dq or ds tables.

This is the preferred method rather than using the hacked versions of wcs_get_... or xy2ad and ad2xy.

PUNCH_XY2AD and PUNCH_AD2XY (Deprecated)

In the current SolarSoft astrometry package, the only way to access distortion tables is by opening the file with fits_open, but this is not possible for Rice-compressed files. These routines therefore combine the relevant parts of fits_xy2ad and xy2ad, and fits_ad2xy and ad2xy respectively.

Using the WCS suite is preferred.

PUNCH_WCS_GET_COORD and PUNCH_WCS_GET_PIXEL (Deprecated)

These routines support the conversion of WCS structure from data coordinates to IDL pixel position and back. These allow the use of distortion tables alongside the WCS family of SSWIDL astrometry codes.

• punch_wcs_get_coord: This procedure takes a WCS structure, and calculates the data coordinates at each IDL pixel position.
• punch_wcs_get_pixel: This procedure is inverse of punch_wcs_get_coord and takes a WCS structure, and converts coordinates back into IDL pixel positions.

It is now recommended to use the filename keyword in fitshead2wcs or wcs_append_tables to properly integrate the distortion into the system.

REPAIR_PUNCH_HEAD

Only applicable to low-level (L0, L1) files.

There are a number of flaws in the headers of some version 0x files that need to be corrected if the distortion tables are to be used on the RA and Dec coordinates. Other more esoteric fixes are available for development purposes.

Should be applied before using fitshead2wcs.

FIX_Z_HEAD

Modifies header keys starting with "Z", in Rice-compressed files read by fitsio_read_image to be the actual image parameters (e.g. ZNAXIS1 becomes NAXIS1), tries to follow the pattern of imcopy. This is only intended to be used internally within read_punch.

Building imcopy

is an ancillary program that is part of the cfitsio library. However many Linux distributions do not build it by default. It can be simply built by downloading the cfitsio source and going to the utilities subdirectory and compiling with (assuming the cfitsio library is installed):

gcc -o imcopy imcopy.c $(pkg-config -libs -cflags cfitsio$)

and copying the executable to somewhere in your path (e.g. /usr/local/bin or ~/bin if you don't have root access).

Using latest SSW package

We recommend using the latest SSW package to run these routines smoothly across various platforms (Windows, Linux, MacOS etc.).

Getting help

All routines contain a documentation header that can be read via doc_library.

For further assistance, please open an issue or create a discussion here on GitHub.

Contributing

We welcome all contributions. Please open a pull request to contribute.

imcopy

is an ancillary program that is part of the cfitsio library. However many Linux distributions do not build it by default. It can be simply built by downloading the cfitsio source and going to the utilities subdirectory and compiling with (assuming the cfitsio library is installed):

gcc -o imcopy imcopy.c $(pkg-config -libs -cflags cfitsio$)

and copying the executable to somewhere in your path (e.g. /usr/local/bin or ~/bin if you don't have root access).

Note that as of 3-Nov-25, the version of imcopy distributed with SolarSoft does not correctly handle all PUNCH files.

For Linux users also check whether your distro installs it under a modified name, (e.g. Arch derivatives install it as cfitsio-imcopy --- this is automatically searched). If you find other modified names let me know and I'll add them to the search.