diff options
Diffstat (limited to 'doc/source')
| -rw-r--r-- | doc/source/headerlet_def.rst | 30 |
1 files changed, 24 insertions, 6 deletions
diff --git a/doc/source/headerlet_def.rst b/doc/source/headerlet_def.rst index 2c43f4c..8619c6e 100644 --- a/doc/source/headerlet_def.rst +++ b/doc/source/headerlet_def.rst @@ -5,7 +5,7 @@ Definition of a Headerlet and It's Role in Updating WCS Information Abstract ======== -The 'headerlet' serves as a mechanism for encapsulating WCS information which can be used to update the WCS solution of an image. This object needs to be as compact as possible while providing an unambigious and self-consistent WCS solution for an image while requiring a minimum level of software necessary to apply the headerlet to an image. These basic requirements come from the desire to create improved astrometric solutions for HST data and provide those solutions in a manner that would not require getting entirely new images from an archive when only the WCS information has been updated. This report describes the format and contents of a headerlet along with the procedures which would be used to update images with the updated WCS information from the headerlet. +The 'headerlet' serves as a mechanism for encapsulating WCS information which can be used to update the WCS solution of an image. This object needs to be as compact as possible while providing an unambigious and self-consistent WCS solution for an image while requiring a minimum level of software necessary to apply the headerlet to an image. These basic requirements come from the desire to create a mechanism for passing improved astrometric solutions for HST data and provide those solutions in a manner that would not require getting entirely new images from an archive when only the WCS information has been updated. This report describes the format and contents of a headerlet along with the procedures which would be used to update images with the updated WCS information from the headerlet. Introduction ============ @@ -17,7 +17,7 @@ Source Image ============ All users get their copy of an image from the HST Archive (OTFR) after being processed with the latest image calibrations, including applying the latest available distortion models. The calibrated image gets passed to the user with the ``_flt.fits`` suffix and is referred to as the ``FLT`` image. These FLT images serve as the inputs to MultiDrizzle in order to apply the distortion models and combine the images into a single ``DRZ`` product. -The WCS information in the FLT images has been updated to include the full distortion model, including the full polynomial solution from the IDCTAB and all the corrections formerly combined into the DGEOFILE. The FITSConventions_ report by Dencheva (currently available online) contains the full description of the conventions used to described all these components in a FITS file. The header now contains the following set of keywords and extensions to fully describe the WCS with distortion: +The WCS information in the FLT images has been updated to include the full distortion model, including the full polynomial solution from the IDCTAB and all the corrections formerly combined into the DGEOFILE. The FITSConventions_ report by Dencheva (currently available online) contains the full description of the conventions used to describe all these components in a FITS file. The header now contains the following set of keywords and extensions to fully describe the WCS with distortion: * **Linear WCS keywords**: specifically, CRPIX, CRVAL, CTYPE, CD matrix keywords * **SIP coefficients**: A_*_* and B_*_*, A_ORDER, B_ORDER, @@ -57,11 +57,12 @@ There may be a lot of extensions appended to this FITS file, but the sum total o Headerlet Definition ==================== -The `headerlet` needs to be a self-consistent, fully described definition of a WCS and its distortion. The WCS and SIP coefficients get derived from the SCI header directly, along with the keywords which refer to the extensions with the NPOLFILE and D2IMFILE corrections. This original WCS information should also never be deleted from the file so that the user can always revert back to the original WCS solution at any time. +The `headerlet` needs to be a self-consistent, fully described definition of a WCS and its distortion. The WCS and SIP coefficients get derived from the SCI header directly, along with the keywords which refer to the extensions with the NPOLFILE and D2IMFILE corrections. This original WCS information in general will not be deleted from the file so that the user can always revert back to the original WCS solution at any time. +There will be a way to delete it in cases when the user want to update the model and does not need to keep the old model. New WCS Extension ----------------- -A new extension, named SIPWCS, containing all the WCS-related keywords from the SCI header, including all keywords referring to NPOL and D2IM extensions as well as all sets of alternate WCS keywords, can be created to serve as the record of the original WCS. All the sets of linear WCS keywords stored using FITS Paper I Multiple WCS Standard would be defined using the same set of distortion coefficients written to the SIP keywords and NPOL files. This insures that all the information in the header remains consistent. The keywords in this extension can be used to overwrite the keywords in the corresponding SCI header to update the WCS solution for each chip without any further modification or computation. The new extension then serves not only as a record of all the WCS solutions derived for the image, but also the source of values for restoring the SCI header WCS when desired. +A new extension, named SIPWCS, containing all the WCS-related keywords from the SCI header, including all keywords referring to NPOL and D2IM extensions as well as all sets of alternate WCS keywords, can be created to serve as the record of the original WCS. Keywords (TBD) recording the alignment information are recorded in this header as well. All the sets of linear WCS keywords stored using FITS Paper I Multiple WCS Standard would be defined using the same set of distortion coefficients written to the SIP keywords and NPOL files. This insures that all the information in the header remains consistent. The keywords in this extension can be used to overwrite the keywords in the corresponding SCI header to update the WCS solution for each chip without any further modification or computation. The new extension then serves not only as a record of all the WCS solutions derived for the image, but also the source of values for restoring the SCI header WCS when desired. Updated Example FITS Listing @@ -99,15 +100,24 @@ This new extension along with the NPOLFILE and the D2IMFILE extensions fully des 6 IMAGE SIPWCS 1 8 7 IMAGE SIPWCS 2 8 -This file now full describes the WCS solution for this image, complete with all the distortion information used to originally define the solution. No further reference files or computations would be needed when this `headerlet` gets used to update an image. +This file now fully describes the WCS solution for this image, complete with all the distortion information used to originally define the solution. No further reference files or computations would be needed when this `headerlet` gets used to update an image. + +The primary header must have 4 required keywords: + +`HDRNAME` - a unique name for the headerlet +`DISTIM` - target image filename (the original archive filename) +`STWCSVER` - version of STWCS used to create the headerlet +`PYWCSVER` - version of PyWCS used to create the headerlet User-Defined Headerlet ====================== The `headerlet` defined above serves as the default headerlet for any image provided by the HST Archive. However, should the user perform their own calibrations which they feel improve on the standard calibrations provided by the pipeline, a custom `headerlet` can be provided. Any `headerlet` should simply include: + * **Required**: A primary header with specific keywords which specify a unique headerlet name and a targeted image. * **Required**: An SIPWCS extension for each chip which contains the linear WCS as well as any distortion model supported by FITS (for example, updated SIP coefficients) * **Optional**: Any additional look up tables with refinements to the polynomial solutions in the SIPWCS extension. Any such extensions should be linked to the SIPWCS extension using the same Paper IV conventions used for the NPOLFILE tables. - + * **Optional**: Detector to image correction array as a separate extension if needed. + This custom `headerlet` should be capable of being used to overwrite the existing SCI header WCS keywords to provide a FITS-supported WCS. @@ -118,11 +128,19 @@ Updating an image retrieved from the HST Archive with a `headerlet` only require #. Append the `headerlet` to the FITS file #. Update the extver IDs for the NPOLFILE and D2IMFILE keywords in the headerlet SIPWCS extensions to point to the actual extver values for the new extensions #. Overwrite the SCI header keywords for each chip with the same keywords from the SIPWCS extension that corresponds to the same chip from the newly appended `headerlet` + #. Add a keyword `SIPVER` to each science header with a value of the appropriate SIPWCS' `EXTVER` keyword. #. Update the WCSCORR table with the linear WCS keyword values and name of the SIP solution from each SIPWCS extension from the `headerlet` This process assumes that when an image gets updated with a `headerlet`, the new solution from the `headerlet` should become the prime WCS. Further implementations of the software to work with `headerlets` can expand on this functionality if necessary. Initially, the `headerlet` simply needs to be used to update the image's FITS file so that the WCS information can be used at all. +Software Requirements +===================== +- A task which given a science file creates a headerlet and writes it to a file. +- A task which given a science file and a headerlet applies the headerlet to the science file + + #. Default behaviour will be to append the headerlet to the file and copy the WCS recorded in the headerlet as a primary WCS. + #. It will be possible (optionally) to copy the updated science file to a new file and keep the original science file locally unchanged. .. _FITSConventions: http://mediawiki.stsci.edu/mediawiki/index.php/Telescopedia:FITSDistortionConventions |