.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is turned on, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{ . if \nF \{ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "CFITSIO 3pm" .TH CFITSIO 3pm "2013-06-06" "perl v5.20.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Astro::FITS::CFITSIO \- Perl extension for using the cfitsio library .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 4 \& use Astro::FITS::CFITSIO; \& use Astro::FITS::CFITSIO qw( :longnames ); \& use Astro::FITS::CFITSIO qw( :shortnames ); \& use Astro::FITS::CFITSIO qw( :constants ); .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" Perl interface to William Pence's cfitsio subroutine library. For more information on cfitsio, see http://heasarc.gsfc.nasa.gov/fitsio. .PP This module attempts to provide a wrapper for nearly every cfitsio routine, while retaining as much cfitsio behavior as possible. As such, one should be aware that it is still somewhat low-level, in the sense that handing an array which is not the correct size to a routine like \f(CW\*(C`fits_write_img()\*(C'\fR may cause SIGSEGVs. .PP My goal is to eventually use these routines to build a more Perl-like interface to many common tasks such as reading and writing of images and \&\s-1ASCII\s0 and binary tables. .SH "cfitsio API MAPPING" .IX Header "cfitsio API MAPPING" Astro::FITS::CFITSIO allows one to use either the long or short name forms of the cfitsio routines. These work by using the exact same form of arguments as one would find in an equivalent C program. .PP There is also an object-oriented \s-1API\s0 which uses the same function names as the long-name \s-1API,\s0 but with the leading \*(L"fits_\*(R" stripped. To get a Astro::FITS::CFITSIO \*(L"object\*(R" one would call \f(CW\*(C`open_file()\*(C'\fR, \f(CW\*(C`create_file()\*(C'\fR or \&\f(CW\*(C`create_template()\*(C'\fR: .PP .Vb 3 \& my $status = 0; \& my $fptr = Astro::FITS::CFITSIO::open_file($filename, \& Astro::FITS::CFITSIO::READONLY(),$status); \& \& $fptr\->read_key_str(\*(AqNAXIS1\*(Aq,$naxis1,undef,$status); .Ve .PP Note that the object-oriented forms of function names are only available for those cfitsio routines which accept a \f(CW\*(C`fitsfile*\*(C'\fR data-type as the first argument. .PP As an added benefit, whenever a filehandle goes out of scope, \fB\f(BIffclos()\fB\fR is automatically closed: .PP .Vb 4 \& { \& my $fptr = Astro::FITS::CFITSIO::open_file($filename, \& Astro::FITS::CFITSIO::READWRITE(),$status); \& [manipulate $fptr] \& \& # neither of the following are needed \& # ffclos($fptr,$status); \& # $fptr\->close_file($status); \& } .Ve .PP It there is an error, it will \fB\f(BIcroak()\fB\fR. .SH "NAME SPACE" .IX Header "NAME SPACE" All cfitsio routines, with the exception of \f(CW\*(C`fits_iterate_data()\*(C'\fR and \&\f(CW\*(C`fits_open_memfile()\*(C'\fR, are available in both long and short name forms (e.g., \f(CW\*(C`fits_read_key\*(C'\fR <=> \f(CW\*(C`ffgky\*(C'\fR), as well as all constants defined in the \fIfitsio.h\fR header file. This raises the possibility of your name space being invaded by nearly 1000 function and constant names. .PP To deal with this situation, Astro::FITS::CFITSIO makes use of the Exporter package support for \f(CW%EXPORT_TAGS\fR. You can import the long-named functions with .PP .Vb 1 \& use Astro::FITS::CFITSIO qw( :longnames ); .Ve .PP and the short-named routines with .PP .Vb 1 \& use Astro::FITS::CFITSIO qw( :shortnames ); .Ve .PP Constants are actually implemented as AUTOLOADed functions, so \f(CW\*(C`TSTRING\*(C'\fR, for instance, would be accessed via \f(CW\*(C`Astro::FITS::CFITSIO::TSTRING()\*(C'\fR. Alternatively you can .PP .Vb 1 \& use Astro::FITS::CFITSIO qw( :constants ); .Ve .PP which would allow you to simply say \f(CW\*(C`TSTRING\*(C'\fR. .SH "DATA STORAGE DETAILS" .IX Header "DATA STORAGE DETAILS" .SS "Input Variables" .IX Subsection "Input Variables" If a routine expects an N\-dimensional array as input, and you hand it a reference to a scalar, then Astro::FITS::CFITSIO simply uses the data in the scalar which the argument is referencing. Otherwise it expects the argument to be a Perl array reference whose total number of elements satisfies the input demands of the corresponding C routine. Astro::FITS::CFITSIO then unpacks the array reference into a format that the C routine can understand. If your input array does not hold enough data for the C routine then a segfault is likely to occur. .PP cfitsio functions which take an optional \s-1NULL\s0 pointer \- indicating no output in that place is desired \- can instead be given an \f(CW\*(C`undef\*(C'\fR. In other words, the following C and Perl statements which read a keyword but ignore the comment would be roughly equivalent: .PP .Vb 1 \& fits_read_key_lng(fptr,key,&value,NULL,&status); \& \& fits_read_key_lng($fptr,$key,$value,undef,$status); .Ve .SS "Output Variables" .IX Subsection "Output Variables" Calling cfitsio routines which read data from \s-1FITS\s0 files causes the output variable to be transformed into a Perl array of the appropriate dimensions. The exception to this is if one wants the output to be in the machine-native format (e.g., for use with \s-1PDL\s0). Then all output variables will become scalars containing the appropriate data. The exception here is with routines which read arrays of strings (e.g., \f(CW\*(C`fits_read_col_str()\*(C'\fR). In this case the output is again a Perl array reference. .PP There are two ways to specify how data are retrieved. The behavior can be specified either globally or on a per filehandle basis. The global selection is done by calling the \fBPerlyUnpacking\fR function. This sets the behavior for \fIall\fR file handles which do not \&\fIexplicitly\fR choose not to follow it. .PP .Vb 2 \& # turn ON unpacking into Perl arrays. This is the default \& PerlyUnpacking(1); \& \& # turn OFF unpacking into Perl arrays, i.e. put in machine\-native \& # format \& PerlyUnpacking(0); \& \& # retrieve the current state: \& $state = PerlyUnpacking(); .Ve .PP To change the behavior for a particular file handle, use the \&\fBperlyunpacking\fR method. The default behavior for a file handle is to track what is done with \fB\f(BIPerlyUnpacking()\fB\fR .PP .Vb 2 \& # track PerlyUnpacking(). This is the default \& $fptr\->perlyunpacking(\-1); \& \& # turn ON unpacking into Perl arrays \& $fptr\->perlyunpacking(1); \& \& # turn OFF unpacking into Perl arrays \& $fptr\->perlyunpacking(0); \& \& # retrieve the current state: \& $state = $fptr\->perlyunpacking; .Ve .SH "EXAMPLES" .IX Header "EXAMPLES" Take a look at \fItestprog/testprog.pl\fR under the distribution directory. It should produce output identical to \fItestprog.c\fR which comes with the cfitsio library. Additionally, the versions named \fItestprog_longnames.pl\fR, \fItestprog_OO.pl\fR and \&\fItestprog_pdl.pl\fR test the long-name and object-oriented APIs, and machine-native unpacking with \s-1PDL.\s0 .PP There is also an \fIexamples/\fR directory with scripts which do the following: .IP "\fIimage_read.pl\fR" 4 .IX Item "image_read.pl" reads a \s-1FITS\s0 primary image and displays it using \s-1PGPLOT\s0 .IP "\fIimage_read_pdl.pl\fR" 4 .IX Item "image_read_pdl.pl" same as above, but uses machine-native unpacking with \s-1PDL\s0 .IP "\fIbintable_read_pdl.pl\fR" 4 .IX Item "bintable_read_pdl.pl" reads binary table column into \s-1PDL\s0 object, makes histogram and plots it .SH "CONSIDERATIONS" .IX Header "CONSIDERATIONS" .IP "Ensure your input arrays contain enough data" 4 .IX Item "Ensure your input arrays contain enough data" The caller is responsible for ensuring that the input arrays given to Astro::FITS::CFITSIO routines are large enough to satisfy the access demands of said routines. For example, if you tell \f(CW\*(C`fits_write_col()\*(C'\fR to write a data column containing 100 elements, your Perl array should contain at least 100 elements. Segfaults abound, so beware! .IP "maxdim semantics" 4 .IX Item "maxdim semantics" Some cfitsio routines take a parameter named something like '\f(CW\*(C`maxdim\*(C'\fR', indicating that no more than that many elements should be placed into the output data area. An example of this would be \f(CW\*(C`fits_read_tdim()\*(C'\fR. In these cases Astro::FITS::CFITSIO will automatically determine how much storage space is needed for the full amount of output possible. As a result, the arguments expected in Astro::FITS::CFITSIO are slightly different than one would use in a C program, in that the '\f(CW\*(C`maxdim\*(C'\fR' argument is unnecessary. .Sp Currently the routines for which this is the case are \f(CW\*(C`fits_read_atblhdr()\*(C'\fR, \f(CW\*(C`fits_read_btblhdr()\*(C'\fR, \&\f(CW\*(C`fits_read_imghdr()\*(C'\fR, \f(CW\*(C`fits_decode_tdim()\*(C'\fR, \f(CW\*(C`fits_read_tdim()\*(C'\fR \&\f(CW\*(C`fits_test_expr()\*(C'\fR, \f(CW\*(C`fits_get_img_parm()\*(C'\fR and \f(CW\*(C`fits_get_img_size()\*(C'\fR. .IP "Output arrays remain as undisturbed as possible" 4 .IX Item "Output arrays remain as undisturbed as possible" For routines like \f(CW\*(C`fits_read_col()\*(C'\fR, Astro::FITS::CFITSIO unpacks the output into a Perl array reference (unless \f(CWPerlyUnpacking(0)\fR has been called, of course). Prior to doing this, it ensures the scalar passed is a reference to an array large enough to hold the data. If the argument is an array reference which is too small, it expands the array pointed to appropriately. \fBBut\fR, if the array is large enough already, the data are just unpacked into the array. The upshot: If you call \&\f(CW\*(C`fits_read_col()\*(C'\fR, telling it to read 100 data elements, and the array you are placing the data into already has 200 elements, then after \&\f(CW\*(C`fits_read_col()\*(C'\fR returns your array will still have 200 elements, only the first 100 of which actually correspond to the data read by the routine. .Sp In more succinct language: .Sp .Vb 2 \& @output = (0..199); \& fits_read_col_lng($fptr,2,1,1,100,0,\e@output,$anynul,$status); \& \& # @output still has 200 elements, only first 100 are from FITS \& # file .Ve .SH "EXTRA COMMANDS" .IX Header "EXTRA COMMANDS" Some extra commands that use sets of cfitsio routines are supplied to simplify some standard tasks: .IP "fits_read_header(filename)" 4 .IX Item "fits_read_header(filename)" This command reads in a primary fits header (unless one is using the extended filename sytax to move to a different \s-1HDU\s0 on open) from the specified filename and returns the header as a hash reference and a status (when called in an array context) or simply a hash reference (when called in a scalar context): .Sp .Vb 2 \& ($hash_ref, $status) = fits_read_header ($file); \& $hash_ref = fits_read_header($file); .Ve .Sp An object-oriented interface is also provided for reading headers from \&\s-1FITS\s0 files that have already been opened. In this case, the header read is from the current \s-1HDU.\s0 .Sp .Vb 3 \& $fitsfile = Astro::FITS::CFITSIO::open_file($file); \& $hash_ref = $fitsfile\->read_header; \& ($hash_ref, $status) = $fitsfile\->read_header; .Ve .IP "sizeof_datatype(datatype)" 4 .IX Item "sizeof_datatype(datatype)" Returns the size of the given Astro::FITS::CFITSIO datatype constant (e.g., \f(CW\*(C`Astro::FITS::CFITSIO::TSHORT()\*(C'\fR). .SH "BUGS" .IX Header "BUGS" \&\s-1FIXME\s0 .SH "AUTHOR" .IX Header "AUTHOR" Pete Ratzlaff , with a great deal of code taken from Karl Glazebrook's \s-1PGPLOT\s0 module. .PP Contributors include: .IP "Diab Jerius, " 4 .IX Item "Diab Jerius, " general improvements .IP "Tim Jenness, " 4 .IX Item "Tim Jenness, " convenience routines .IP "Tim Conrow, " 4 .IX Item "Tim Conrow, " function implementations, bug fixes .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" Copyright (C) 2002,2004,2006,2011 by the Smithsonian Astrophysical Observatory. .PP This software is released under the same terms as Perl. A copy of the Perl license may be obtained at http://dev.perl.org/licenses/