psFitsWriteImage specification clarifications/enhancements

[robert.desonia@…]

psFitsWriteImage is specified to write "in the file at the current position of the psFits pointer" (i.e., the
CHDU). Is it your intention that the existing HDU that the CHDU pointer was pointing at would be
replaced with the new IMAGE HDU? This is, of course, not a typical CFITSIO behavior.

The raw CFITSIO options are to a) have a new HDU appended to the end of the file, which is how it was
originally implemented, b) inserted after the current HDU, or c) prepended to the beginning of the file,
i.e., made the primary HDU.

I could insert a new HDU after the current HDU and then delete the previously set CHDU, but I don't
know if it is really a good idea to implicitly delete data. Would it be better/safer to either insert the new
HDU before or after the CHDU and force the user to manually remove the old HDU via psFitsDeleteExt*?

-rdd

[robert.desonia@…]

BTW: To give the user the option to insert the HDU before or after the CHDU, the function would need
another parameter of type bool.

[robert.desonia@…]

Oh, and the same sort of issue applies to psFitsWriteTable.

[Paul Price]

Changed psFitsWriteImage and psFitsWriteTable definitions so that they write to
the end of the file, and added psFitsInsertImage and psFitsInsertTable. The
reasoning is that we want the normal usage (psFitsWrite{Image,Table}) not to be
an expensive operation, and inserting involves rewriting the entire file
following the insert. The psFitsInsert{Image,Table} functions are provided with
a warning to this effect, just in case the user really really wants to do this.

\begin{prototype}
bool psFitsWriteImage(psFits *fits, psMetadata *header, const psImage *input,
int depth,

const char *extname);

\end{prototype}
Create a new image based on the dimensions specified for the image and
the requested depth. The header and image data segments are written
at the end of the file. This function will only write images of the
native FITS image types (\code{psU8}, \code{psS16}, \code{psS32},
\code{psF32}, \code{psF64}). The user is expected to convert the data
type as needed with \code{psImageCopy}. The return value must be 0
for a successful operation and 1 for an error. If \code{extname} is
not \code{NULL}, the \code{EXTNAME} in the \code{header} shall be
updated to be \code{extname} before writing.

\begin{prototype}
bool psFitsInsertImage(psFits *fits, psMetadata *header, const psImage *input,
int depth,

const char *extname, bool after);

\end{prototype}

\code{psFitsInsertImage} behaves in the same manner as
\code{psFitsWriteImage}, except that the extension is inserted
according to the value of the boolean \code{after}. If \code{after}
is \code{true}, then the extension is inserted after the current
\code{psFits} pointer; otherwise the extension is inserted before the
current \code{psFits} pointer. \textbf{The user should beware that
this is potentially a very expensive operation in terms of time, since
the entire file following the inserted extension must be rewritten.}

\begin{prototype}
bool psFitsWriteTable(psFits* fits, const psMetadata *header, const psArray*
table);
\end{prototype}
Accepts a \code{psArray} of \code{psMetadata} and writes it to the end
of the file.

\begin{prototype}
bool psFitsInsertTable(psFits *fits, const psMetadata *header, const psArray* table,

bool after);

\end{prototype}

\code{psFitsInsertTable} behaves in the same manner as
\code{psFitsWriteTable}, except that the extension is inserted
according to the value of the boolean \code{after}. If \code{after}
is \code{true}, then the extension is inserted after the current
\code{psFits} pointer; otherwise the extension is inserted before the
current \code{psFits} pointer. \textbf{The user should beware that
this is potentially a very expensive operation in terms of time, since
the entire file following the inserted extension must be rewritten.}