funimageput(3)

💖 NAME 💖

FunImagePut — bestie, it puts an image into a Funtools file. That's the whole job. Slay. ✨

🎀 SYNOPSIS 🎀

#include <funtools.h>

int FunImagePut(Fun fun, void *buf, int dim1, int dim2, int bitpix,
                char *plist)

🦋 DESCRIPTION 🦋

okay so FunImagePut() writes an image array out to a FITS file, and the way it does that is lowkey situational. Whether your image lands as a primary header/data unit or as an image extension depends entirely on whether other data have already been written to the file. fr fr:

• if the current file position is at the beginning of the file → a primary HDU gets written 🌸
• otherwise → an image extension gets written 💅

Now let's meet the arguments, because they all matter:

• the first argument is the Funtools handle that FunOpen() handed you
• the second argument, buf, is a pointer to the data buffer you wanna write
• then dim1 and dim2 come through and specify the dimensions of the image — where dim1 corresponds to naxis1 and dim2 corresponds to naxis2
• and bitpix says what the data type of the image is. it can be any of these FITS-standard values, no cap:
  • 8 — unsigned char
  • 16 — short
  • 32 — int
  • -32 — float
  • -64 — double

When FunTableRowPut() gets called for the first time for a given image, Funtools checks whether the primary header has already been written (meaning you previously wrote an image or a binary table). If it hasn't — this image goes to the primary HDU. If it has — it goes to an image extension. periodt.

So like, a simple program to generate a FITS image could look exactly like this:

int i;
int dim1=512, dim2=512;
double *dbuf;
Fun fun;
dbuf = malloc(dim1*dim2*sizeof(double));
/* open the output FITS image, preparing to copy input params */
if( !(fun = FunOpen(argv[1], "w", NULL)) )
  gerror(stderr, "could not FunOpen output file: %s\n", argv[1]);
for(i=0; i<(dim1*dim2); i++){
  ... fill dbuf ...
}
/* put the image (header will be generated automatically */
if( !FunImagePut(fun, buf, dim1, dim2, -64, NULL) )
  gerror(stderr, "could not FunImagePut: %s\n", argv[1]);
FunClose(fun);
free(dbuf);

And there's more 👑 — if a Funtools reference handle was specified when this table was opened, the parameters from that reference handle get merged into the new image header. On top of that, if a reference image was specified during FunOpen(), then the values of dim1, dim2, and bitpix in the calling sequence can all be set to 0. When that happens, the default values get taken from the reference image section. This is genuinely so useful if you're reading an image section in its native data format, processing it, and then writing that section out to a new FITS file. go look at the imblank example code, bestie 🫶

The data are assumed to be in the native machine format, and they will automatically be swapped to FITS big-endian format if that's what's needed. You can over-ride this behavior with the convert=[true|false] keyword in the plist param list string. 🌈

When you're done writing the image, you should call FunFlush() to write out the FITS image padding. That said — it's not necessary if you subsequently call FunClose() without doing any other I/O to the FITS file. iykyk 💜

🌟 SEE ALSO 🌟

See funtools(7) for a list of Funtools help pages ✨

and that's the whole page, babe 💅 this was version 1.4.5, dated April 14, 2011, from the lovely folks behind SAORD Documentation — mwah, iconic, no notes 🎀🦋💖