SDS_SET_SCALING(3)
NAME
sds_get_fits sds_put_fits sds_read_fits sds_write_fits
sds_get_fits_head sds_read_fits_head sds_read_fits_data
sds_set_scaling
functions to convert between a SDS and its FITS file
representation.
SYNOPSIS
#include <stdio.h>
#include <soi_sds.h>
SDS *sds_get_fits (char *filename)
SDS *sds_read_fits (char FILE *fp)
int sds_put_fits (SDS *sds, char *filename)
int sds_write_fits (SDS *sds, FILE *fp)
SDS *sds_get_fits_head (char *filename)
SDS *sds_read_fits_head (FILE *fp)
int sds_read_fits_data (SDS *sds)
int sds_set_scaling (SDS *sds, int bitpix, double bscale, double bzero)
DESCRIPTION
These functions implement the sds/FITS interface specifica-
tion of SOI-TN 97-137. They replace the functions
sds_get_one_fits and sds_put_one_fits, as well as
sds_get_fits_header, sds_get_fits_data, and
sds_read_FITS_header. sds_get_fits and sds_put_fits (and
sds_get_fits_head) open the named files for read or write;
sds_read_fits and sds_write_fits require previously opened
streams and leave the file pointer positioned at the end of
file on successful completion. sds_read_fits_head also
requires a previously opened stream; it leave the file
pointer positioned at the beginning of the FITS data sec-
tion. sds_read_fits_data assumes that sds->fp is positioned
at the beginning of the data section; if the file pointer is
positioned at the beginning of the FITS file
sds_read_fits_data will re-read the header and override the
data type and organization of the sds as needed.
sds_get_fits and sds_get_fits_header set sds->filename to
their argument.
sds_set_scaling sets the desired scaling parameters to be
used when writing a sds to a FITS file. Valid values of
bitpix are 0 (implying no scaling), 8, 16, and 32. The
advisory scaling is only meaningful if the data internal to
the sds are of floating-point type. Any previously existing
scaling parameters are ignored and over-written.
DIAGNOSTICS
sds_get_fits and sds_read_fits return a valid pointer to a
new sds structure filled with data on successful completion;
otherwise they return a NULL. If the sds cannot be created,
soi_errno is set to MALLOC_FAILED. soi_errno is set to
FITS_ERROR and messages are appended to the error stack if
the FITS file does not conform to the standard; serious
errors will result in a NULL sds sds pointer.
sds_put_fits and sds_write_fits set and return various error
codes if a stream or write error occurs. An error condition
will also be returned if an attempt is made to write data of
an unsupported length.
sds_set_scaling returns soi_errno = SDS_PTR_NULLR if the sds
has not been mallocd.
FILES
~CM/include/soi_sds.h
~CM/src/libsds.d/sds_fits.c
SEE ALSO
SOI Technical Note 97-137
sds_get_one_fits(3) sds_get_fits_header(3)
BUGS
The entire dataset is read or written in a single operation;
this may be very efficient for small datasets, but may lead
to inefficiencies or even unnecessary limits for large
datasets.
No warnings are issued when writing sds's of data types
officially unsupported by FITS (SDS_BYTE, SDS_USHORT,
SDS_UINT, SDS_ULONG). The data will be written in the for-
mats specified in SOI-TN 97-137. On machines which support
64-bit integers, non-conforming FITS files involving such
integers (SDS_LONG) can be read and written with no more
than a warning message on the error stack. If the data type
has a length different from one of the supported lengths,
the BITPIX field will be set to 8. The functions assume
that the machine architecture conforms with the IEEE stan-
dard for numeric data representation.
Data types SDS_STRING and SDS_COMPLEX and anything else
involving FITS tables are not supported.
sds_set_scaling does not refuse a bscale value of 0.0,
although this will destroy the output information.
HISTORY
1998-01-28 SOI V 2.8