diff options
Diffstat (limited to 'sys/imio/iki/stf/README')
| -rw-r--r-- | sys/imio/iki/stf/README | 300 |
1 files changed, 300 insertions, 0 deletions
diff --git a/sys/imio/iki/stf/README b/sys/imio/iki/stf/README new file mode 100644 index 00000000..5540110b --- /dev/null +++ b/sys/imio/iki/stf/README @@ -0,0 +1,300 @@ +IKI/STF -- IKI kernel for the STScI SDAS/GEIS image format. This format stores +images in a format which resembles FITS group format. A GROUP FORMAT IMAGE is +a set of one or more images, all of which are the same size, dimension, and +datatype, and which share a common FITS header. The individual images in a +group each has a binary GROUP PARAMETER BLOCK (GPB). The image and associated +group parameter block are commonly referred to as a GROUP. A group format +image consists of two files, the FITS format header file for the group, +and the pixel file containing the image data and GPBs. + + +1. Typical STF group format FITS image header (imname.hhh) + + SIMPLE = F / Standard STF keywords + BITPIX = 32 + DATATYPE= 'REAL*4 ' + NAXIS = 2 + NAXIS1 = 512 + NAXIS2 = 512 + GROUPS = T + PSIZE = 512 + GCOUNT = 1 + PCOUNT = 12 + + PTYPE1 = 'DATAMIN ' / Define binary group params + PSIZE1 = 32 + PDTYPE1 = 'REAL*4 ' + (etc, for a total of 3*PCOUNT entries) + + (special keywords and HISTORY cards) + + +2. Pixel file format (imname.hhd) (byte stream, no alignment, no header) + + [1].pixels + [1].group parameter block + [2].pixels + [2].group parameter block + ... + [GCOUNT].pixels + [GCOUNT].group parameter block + + +The chief problems with this format are that the FITS format header can contain +only parameters which pertain to the group as a whole, while the format of the +GPBs is fixed at image creation time. Images may be neither deleted from nor +added to a group. It is possible for parameters in the FITS header to have +the same names as parameters in the GPBs. Multiple entries for the same +keyword may appear in the FITS header and the format does not define how +these are to be handled. Although the format is general enough to support +any datatype pixels, in practice only REAL*4 can be used as the SDAS software +maps the pixfile directly into virtual memory. + +CAVEAT -- This is an awkward interface and some liberties have been taken in +the code (hidden, subtle semantics, etc.). At least we were able to confine +the bad code to this one directory; any problems can be fixed without any +changes to the rest of IMIO. All of this low level code is expected to be +thrown out when IMIO is cut over onto DBIO (the upcoming IRAF database +interface). + + +IKI/STF Pseudocode +---------------------------- + +1. Data structures: + + 1.1 IMIO image descriptor + header, pixel file descriptors + pointer to additional kernel descriptor, if any + index of IKI kernel in use + pathnames of header, pixel files + IM_NDIM, IM_LEN, etc., physical image parameters + + 1.2 STF image descriptor + Pointed to by IM_KDES field of IMIO descriptor. + Contains values of all reserved fields of STF image header, + some of which duplicate values in IMIO descriptor. + Group, gcount, size of a group in pixfile, description of + the group parameter block, i.e., for each parameter, + the offset, datatype type, name, length if array, etc. + + 1.3 IMIO user area (FITS cards) + While an image is open, the first few cards in the user area + contain the FITS encoded group parameters. + The remainder of the user area contains an exact image of + all non-reserved keyword cards found in the STF image + header (or in the header of some other type of image + when making a new_copy of an image stored in some other + format). + + +2. Major Procedures + +procedure open_image + +begin + if (mode is not new_image or new_copy) { + open_existing_image + return + } + + We are opening a new_image or new_copy image. The problem here is + that the new image might be a group within an existing group format + image. This ambiguity is resolved by a simple test on the group + index, rather than by a context dependent test on the existence of + the group format image. If the mode is new_whatever and the group + is 1, a new group format image is created, else if the group is > 1, + the indicated group is initialized in an existing group format image. + + if (group > 1) { + We are opening a new group within an existing group format image. + + Call open_existing_image to open the group without reading the + group parameter block, which has not yet been initialized. + + if (mode is new_image) + initialize GPB to pixel coords + else if (mode is new_copy) + copy old GPB to new image; transform coords if necessary + + Note that when opening a new copy of an existing image as a new + group within a group format image, it is not clear what to do + with the FITS header of the old image. Our solution is to ignore + it, and retain only the GPB, the only part of the old header + pertaining directly to the group being accessed. + + } else if (opening group 1 of a new image) { + We are creating a new group format image. + + if (mode is new_image) + open_new_image + else + open_new_copy + } +end + + +procedure open_existing_image + +begin + Allocate STF descriptor, save pointer in imio descriptor. + Open image header. + + Read header: + process reserved cards into STF descriptor + spool other cards + + Load group data block from pixfile, get datamin/datamax: + if (there is a gdb) { + open pixfile + read gdb into buffer + for (each param in gdb) { + set up parameter descriptor + format FITS card and put in imio user area + } + } + + fetch datamin, datamax from user area + + Set IM_MIN, IM_MAX, IM_LIMTIME from DATAMIN, DATAMAX. + Mark end of user area. + Copy spooled cards to user area. + (increase size of user area if necessary) + + Call imioff to set up imio pixel offset parameters +end + + +procedure open_new_image + +begin + Upon entry, the imio iminie procedure has already been called to + initialize the imio descriptor for the new image. + + Allocate STF descriptor, save pointer in imio descriptor. + Create header file from template dev$pix.hhh. + Open new image header. + + (At this point the IMIO header fields IM_NDIM, IM_LEN, etc., and + (the STF descriptor fields have not yet been set, and cannot be set + (until the image dimensions have been defined by the high level code. + (imopix() will later have to fix up the remaining header fields and + (set up the default group data block. +end + + +procedure open_new_copy + +begin + Upon entry, the imio immaky procedure has already been called to + copy the old header to the new and initialize the data + dependent fields. This will include the FITS encoded group + parameters in the user area of the old image. + + Allocate STF descriptor, save pointer in imio descriptor. + Create header file from template dev$pix.hhh. + Open new image header. + + Copy the STF descriptor of the old image to the new. Preserve + the parameter marking the end of the GPB area of the old + user area, as we do not want to write these cards when the + header is updated. + + (At this point all header information is set up, except that there + (is no pixel file and the pixfile offsets have not been set. + (Provided the image dimensions do not change, one could simply + (set the pixfile name, call imioff, and do i/o to the image. +end + + +procedure open_pixel_file + +begin + (We are called when the first i/o is done to an image. When writing + (to a new image, the user may change any of the image header attributes + (after the open and before we are called. + + if (pixel file already open) + return + else if (opening existing image) { + open pixel file + return + } + + if (opening a new image) { + Given the values of IM_NDIM and IM_LEN set by the user, set up the + STF descriptor including the default group parameter block. Add + the FITS encoded cards for the GPB to the image header. Mark the + end of the GPB cards, i.e., the start of the real user parameter + area. Ignore IM_PIXTYPE; always open an image of type real since + that is what the SDAS software requires. Set up the WCS to linear + pixel coordinates. + + } else if (opening a new_copy image) { + (The STF descriptor and GPB will already have been set up as a + (copy of the data structures used by the old image. However, + (the user may have changed the values of IM_NDIM and IM_LEN + (since the image was opened, and the value of GCOUNT set when + (the image was opened may be different than that of the old image. + + Transform the coordinate system of the old image to produce the + WCS for the new image, i.e., if an image section was used to + reference the old image. + + Make a new STF descriptor using the values of IM_NDIM and IM_LEN + given, as for a new_image, but using the WCS information for the + new image. The FITS encoded fields in the IMIO user area will be + automatically updated by the IMADD functions, or new cards added + if not present. + + Merge any additional fields from the old STF descriptor into the + new one, e.g., any instrument dependent parameters stored in the + GPB. + + (The STF and FITS encoded user area should now contain a full + (description of the GPB for the new image. + } + + Allocate the pixel file, using the GCOUNT parameter set in the + STF descriptor at stf_open time. + Open the pixel file. + + Set IM_MIN and IM_MAX to zero (not defined). + Call IMIOFF to initialize the pixel offsets. +end + + +procedure update_image_header + +begin + Update the values of DATAMIN, DATAMAX from the IMIO header fields. + + Update the binary GPB in the pixel file from the FITS encoded GPB + in the IMIO user area, using the GPB structure defined in the + STF descriptor. + + Update the STF image header file: + Open a new, empty header file using FMKCOPY and OPEN. + Format and output FITS cards for the reserved header fields, + e.g., SIMPLE, BITPIX, GCOUNT, the GPB information, etc. + Copy the user area to the new header file, excluding the + GPB cards at the beginning of the user area. + Close the new header file and replace the old header file + with the new one via a rename operation. +end + + +procedure close_image + +begin + (We assume that IMIO has already update the image header if such + (is necessary. + + if (pixel file open) + close pixel file + if (header file open) + close header file + + deallocate STF descriptor + (IMIO will deallocate the IMIO descriptor) +end |