1FITS(3) User Contributed Perl Documentation FITS(3)
2
6 PDL::IO::FITS -- Simple FITS support for PDL
7
9 use PDL;
10 use PDL::IO::FITS;
11 $x = rfits('foo.fits'); # read a FITS file
13 $x->wfits('bar.fits'); # write a FITS file
14
16 This module provides basic FITS support for PDL, in the sense of
17 reading and writing whole FITS files. (For more complex operations,
18 such as prefiltering rows out of tables or performing operations on the
19 FITS file in-place on disk), you can use the Astro::FITS::CFITSIO
20 module that is available on CPAN.
21 Basic FITS image files are supported, along with BINTABLE and IMAGE
23 extensions. ASCII Table support is planned, as are the HEASARC
24 bintable extensions that are recommended in the 1999 FITS standard.
25 Table support is based on hashes and named columns, rather than the
27 less convenient (but slightly more congruent) technique of perl lists
28 of numbered columns.
29 The principle interface routines are "rfits" and "wfits", for reading
31 and writing respectively. FITS headers are returned as perl hashes or
32 (if the module is present) Astro::FITS::Header objects that are tied to
33 perl hashes. Astro::FITS::Header objects provide convenient access
34 through the tied hash interface, but also allow you to control the card
35 structure in more detail using a separate method interface; see the
36 Astro::FITS::Header documentation for details.
37
39 Copyright (C) Karl Glazebrook, Craig DeForest, and Doug Burke,
40 1997-2010. There is no warranty. You are allowed to redistribute
41 and/or modify this software under certain conditions. For details, see
42 the file COPYING in the PDL distribution. If this file is separated
43 from the PDL distribution, the copyright notice should be pasted into
44 in this file.
45
47 rfits()
48 Simple piddle FITS reader.
49 $pdl = rfits('file.fits'); # Read a simple FITS image
51 Suffix magic:
53 $pdl = rfits('file.fits.gz'); # Read a file with gunzip(1)
55 $pdl = rfits('file.fits.Z'); # Read a file with uncompress(1)
56 $pdl = rfits('file.fits[2]'); # Read 2nd extension
58 $pdl = rfits('file.fits.gz[3]'); # Read 3rd extension
59 @pdls = rfits('file.fits'); # Read primary data and extensions
60 Tilde expansion:
62 #expand leading ~ to home directory (using glob())
63 $pdl = rfits '~/filename.fits';
64 $hdr = rfits('file.fits',{data=>0}); # Options hash changes behavior
66 In list context, "rfits" reads the primary image and all possible
68 extensions, returning them in the same order that they occurred in the
69 file -- except that, by default, the primary HDU is skipped if it
70 contains no data. In scalar context, the default is to read the first
71 HDU that contains data. One can read other HDU's by using the [n]
72 syntax. Using the [0] syntax forces a read of the first HDU,
73 regardless of whether it contains data or no. Currently recognized
74 extensions are IMAGE and BINTABLE. (See the addendum on EXTENSIONS for
75 details).
76 "rfits" accepts several options that may be passed in as a hash ref if
78 desired:
79 bscale (default=1)
81 Determines whether the data are linearly scaled using the
82 BSCALE/BZERO keywords in the FITS header. To read in the exact data
83 values in the file, set this to 0.
84 data (default=1)
86 Determines whether to read the data, or just the header. If you set
87 this to 0, you will get back the FITS header rather than the data
88 themselves. (Note that the header is normally returned as the "hdr"
89 field of the returned PDL; this causes it to be returned as a hash
90 ref directly.)
91 hdrcpy (default=0)
93 Determines whether the hdrcpy flag is set in the returned PDL.
94 Setting the flag will cause an explicit deep copy of the header
95 whenever you use the returned PDL in an arithmetic or slicing
96 operation. That is useful in many circumstances but also causes a
97 hit in speed. When two or more PDLs with hdrcpy set are used in an
98 expression, the result gets the header of the first PDL in the
99 expression. See hdrcpy for an example.
100 expand (default=1)
102 Determines whether auto-expansion of tile-compressed images should
103 happen. Tile-compressed images are transmitted as binary tables
104 with particular fields ("ZIMAGE") set. Leaving this alone does what
105 you want most of the time, unpacking such images transparently and
106 returning the data and header as if they were part of a normal IMAGE
107 extension. Setting "expand" to 0 delivers the binary table, rather
108 than unpacking it into an image.
109 afh (default=1)
111 By default rfits uses Astro::FITS::Header tied-hash objects to
112 contain the FITS header information. This permits explicit control
113 over FITS card information, and conforms well with the FITS
114 specification. But Astro::FITS::Header objects are about 40-60x
115 more memory intensive than comparable perl hashes, and also use ~10x
116 more CPU to manage. For jobs where header processing performance is
117 important (e.g. reading just the headers of 1,000 FITS files), set
118 afh to 0 to use the legacy parser and get a large boost in speed.
119 FITS image headers are stored in the output PDL and can be retrieved
121 with hdr or gethdr. The hdrcpy flag of the PDL is set so that the
122 header is copied to derived piddles by default. (This is inefficient
123 if you are planning to do lots of small operations on the data; clear
124 the flag with "->hcpy(0)" or via the options hash if that's the case.)
125 The header is a hash whose keys are the keywords in the FITS header.
127 If you have the "Astro::FITS::Header" module installed, the header is
128 actually a tied hash to a FITS header object, which can give you more
129 control over card order, comment fields, and variable types. (see
130 Astro::FITS::Header for details).
131 The header keywords are converted to uppercase per the FITS standard.
133 Access is case-insensitive on the perl side, provided that
134 Astro::FITS::Header is installed.
135 If Astro::FITS::Header is not installed, then a built-in legacy parser
137 is used to generate the header hash. Keyword-associated comments in
138 the headers are stored under the hash key "<keyword>_COMMENT>". All
139 HISTORY cards in the header are collected into a single multiline
140 string stored in the "HISTORY" key. All COMMENT cards are similarly
141 collected under the "COMMENT" key.
142 BSCALE/BZERO
144 If the BSCALE and/or BZERO keywords are set, they are applied to the
146 image before it is returned. The returned PDL is promoted as necessary
147 to contain the multiplied values, and the BSCALE and BZERO keywords are
148 deleted from the header for clarity. If you don't want this type of
149 processing, set 'bscale=>0' in the options hash.
150 EXTENSIONS
152 Sometimes a FITS file contains only extensions and a stub header in the
154 first header/data unit ("primary HDU"). In scalar context, you
155 normally only get back the primary HDU -- but in this special case, you
156 get back the first extension HDU. You can force a read of the primary
157 HDU by adding a '[0]' suffix to the file name.
158 BINTABLE EXTENSIONS
160 Binary tables are handled. Currently only the following PDL datatypes
162 are supported: byte, short, ushort, long, float, and double. At present
163 ushort() data is written as a long rather than as a short with
164 TSCAL/ZERO; this may change.
165 The return value for a binary table is a hash ref containing the names
167 of the columns in the table (in UPPER CASE as per the FITS standard).
168 Each element of the hash contains a PDL (for numerical values) or a
169 perl list (for string values). The PDL's 0th dimension runs across
170 rows; the 1st dimension runs across the repeat index within the row
171 (for rows with more than one value). (Note that this is different from
172 standard threading order - but it allows Least Surprise to work when
173 adding more complicated objects such as collections of numbers (via the
174 repeat count) or variable length arrays.)
175 Thus, if your table contains a column named "FOO" with type "5D", the
177 expression
178 $x->{FOO}->((2))
180 returns a 5-element double-precision PDL containing the values of FOO
182 from the third row of the table.
183 The header of the table itself is parsed as with a normal FITS HDU, and
185 is returned in the element 'hdr' of the returned hash. You can use
186 that to preserve the original column order or access the table at a low
187 level, if you like.
188 Scaling and zero-point adjustment are performed as with BSCALE/BZERO:
190 the appropriate keywords are deleted from the as-returned header. To
191 avoid this behavior, set 'bscale=>0' in the options hash.
192 As appropriate, TSCAL/ZERO and TUNIT are copied into each column-PDL's
194 header as BSCALE/BZERO and BUNIT.
195 The main hash also contains the element 'tbl', which is set to 'binary'
197 to distinguish it from an ASCII table.
198 Because different columns in the table might have identical names in a
200 FITS file, the binary table reader practices collision avoidance. If
201 you have multiple columns named "FOO", then the first one encountered
202 (numerically) gets the name "FOO", the next one gets "FOO_1", and the
203 next "FOO_2", etc. The appropriate TTYPEn fields in the header are
204 changed to match the renamed column fields.
205 Columns with no name are assigned the name "COL_<n>", where <n> starts
207 at 1 and increments for each no-name column found.
208 Variable-length arrays are supported for reading. They are unpacked
210 into PDLs that appear exactly the same as the output for fixed-length
211 rows, except that each row is padded to the maximum length given in the
212 extra characters -- e.g. a row with TFORM of 1PB(300) will yield an
213 NAXIS2x300 output field in the final hash. The padding uses the TNULn
214 keyword for the column, or 0 if TNULn is not present. The output hash
215 also gets an additional field, "len_<name>", that contains the number
216 of elements in each table row.
217 TILE-COMPRESSED IMAGES
219 CFITSIO and several large projects (including NASA's Solar Dynamics
221 Observatory) now support an unofficial extension to FITS that stores
222 images as a collection of individually compressed tiles within a
223 BINTABLE extension. These images are automagically uncompressed by
224 default, and delivered as if they were normal image files. You can
225 override this behavior by supplying the "expand" key in the options
226 hash.
227 Currently, only Rice compression is supported, though there is a
229 framework in place for adding other compression schemes.
230 BAD VALUE HANDLING
232 If a FITS file contains the "BLANK" keyword (and has "BITPIX > 0"), the
234 piddle will have its bad flag set, and those elements which equal the
235 "BLANK" value will be set bad. For "BITPIX < 0", any NaN's are
236 converted to bad (if necessary).
237 rfitshdr()
239 Read only the header of a FITS file or an extension within it.
240 This is syntactic sugar for the "data=>0" option to rfits.
242 See rfits for details on header handling. rfitshdr() runs the same
244 code to read the header, but returns it rather than reading in a data
245 structure as well.
246 wfits()
248 Simple PDL FITS writer
249 wfits $pdl, 'filename.fits', [$BITPIX], [$COMPRESSION_OPTIONS];
251 wfits $hash, 'filename.fits', [$OPTIONS];
252 $pdl->wfits('foo.fits',-32);
253 Suffix magic:
255 # Automatically compress through pipe to gzip
257 wfits $pdl, 'filename.fits.gz';
258 # Automatically compress through pipe to compress
259 wfits $pdl, 'filename.fits.Z';
260 Tilde expansion:
262 #expand leading ~ to home directory (using glob())
263 wfits $pdl, '~/filename.fits';
264 · Ordinary (PDL) data handling:
266 If the first argument is a PDL, then the PDL is written out as an
268 ordinary FITS file with a single Header/Data Unit of data.
269 $BITPIX is then optional and coerces the output data type according
271 to the standard FITS convention for the BITPIX field (with positive
272 values representing integer types and negative values representing
273 floating-point types).
274 If $pdl has a FITS header attached to it (actually, any hash that
276 contains a "SIMPLE=>T" keyword), then that FITS header is written
277 out to the file. The image dimension tags are adjusted to the
278 actual dataset. If there's a mismatch between the dimensions of the
279 data and the dimensions in the FITS header, then the header gets
280 corrected and a warning is printed.
281 If $pdl is a slice of another PDL with a FITS header already present
283 (and header copying enabled), then you must be careful. "wfits"
284 will remove any extraneous "NAXISn" keywords (per the FITS
285 standard), and also remove the other keywords associated with that
286 axis: "CTYPEn", "CRPIXn", "CRVALn", "CDELTn", and "CROTAn". This
287 may cause confusion if the slice is NOT out of the last dimension:
288 "wfits($x(:,(0),:),'file.fits');" and you would be best off
289 adjusting the header yourself before calling "wfits".
290 You can tile-compress images according to the CFITSIO extension to
292 the FITS standard, by adding an option hash to the arguments:
293 compress
295 This can be either unity, in which case Rice compression is used,
296 or a (case-insensitive) string matching the CFITSIO compression
297 type names. Currently supported compression algorithms are:
298 · RICE_1 - linear Rice compression
300 This uses limited-symbol-length Rice compression, which works
302 well on low entropy image data (where most pixels differ from
303 their neighbors by much less than the dynamic range of the
304 image).
305 tilesize (default "[-1,1]")
307 This specifies the dimension of the compression tiles, in pixels.
308 You can hand in a PDL, a scalar, or an array ref. If you specify
309 fewer dimensions than exist in the image, the last dim is
310 repeated - so "32" yields 32x32 pixel tiles in a 2-D image. A
311 dim of -1 in any dimension duplicates the image size, so the
312 default "[-1,1]" causes compression along individual rows.
313 tilesize (RICE_1 only; default 32)
315 For RICE_1, BLOCKSIZE indicates the number of pixel samples to
316 use for each compression block within the compression algorithm.
317 The blocksize is independent of the tile dimensions. For RICE
318 compression the pixels from each tile are arranged in normal
319 pixel order (early dims fastest) and compressed as a linear
320 stream.
321 · Table handling:
323 If you feed in a hash ref instead of a PDL, then the hash ref is
325 written out as a binary table extension. The hash ref keys are
326 treated as column names, and their values are treated as the data to
327 be put in each column.
328 For numeric information, the hash values should contain PDLs. The
330 0th dim of the PDL runs across rows, and higher dims are written as
331 multi-value entries in the table (e.g. a 7x5 PDL will yield a single
332 named column with 7 rows and 5 numerical entries per row, in a
333 binary table). Note that this is slightly different from the usual
334 concept of threading, in which dimension 1 runs across rows.
335 ASCII tables only allow one entry per column in each row, so if you
337 plan to write an ASCII table then all of the values of $hash should
338 have at most one dim.
339 All of the columns' 0 dims must agree in the threading sense. That
341 is to say, the 0th dimension of all of the values of $hash should be
342 the same (indicating that all columns have the same number of rows).
343 As an exception, if the 0th dim of any of the values is 1, or if
344 that value is a PDL scalar (with 0 dims), then that value is
345 "threaded" over -- copied into all rows.
346 Data dimensions higher than 2 are preserved in binary tables, via
348 the TDIMn field (e.g. a 7x5x3 PDL is stored internally as seven rows
349 with 15 numerical entries per row, and reconstituted as a 7x5x3 PDL
350 on read).
351 Non-PDL Perl scalars are treated as strings, even if they contain
353 numerical values. For example, a list ref containing 7 values is
354 treated as 7 rows containing one string each. There is no such
355 thing as a multi-string column in FITS tables, so any nonscalar
356 values in the list are stringified before being written. For
357 example, if you pass in a perl list of 7 PDLs, each PDL will be
358 stringified before being written, just as if you printed it to the
359 screen. This is probably not what you want -- you should use glue
360 to connect the separate PDLs into a single one. (e.g.
361 "$x->glue(1,$y,$c)->mv(1,0)")
362 The column names are case-insensitive, but by convention the keys of
364 $hash should normally be ALL CAPS, containing only digits, capital
365 letters, hyphens, and underscores. If you include other characters,
366 then case is smashed to ALL CAPS, whitespace is converted to
367 underscores, and unrecognized characters are ignored -- so if you
368 include the key "Au Purity (%)", it will be written to the file as a
369 column that is named "AU_PURITY". Since this is not guaranteed to
370 produce unique column names, subsequent columns by the same name are
371 disambiguated by the addition of numbers.
372 You can specify the use of variable-length rows in the output,
374 saving space in the file. To specify variable length rows for a
375 column named "FOO", you can include a separate key "len_FOO" in the
376 hash to be written. The key's value should be a PDL containing the
377 number of actual samples in each row. The result is a FITS P-type
378 variable length column that, upon read with "rfits()", will restore
379 to a field named FOO and a corresponding field named "len_FOO".
380 Invalid data in the final PDL consist of a padding value (which
381 defaults to 0 but which you may set by including a TNULL field in
382 the hdr specificaion). Variable length arrays must be 2-D PDLs,
383 with the variable length in the 1 dimension.
384 Two further special keys, 'hdr' and 'tbl', can contain meta-
386 information about the type of table you want to write. You may
387 override them by including an $OPTIONS hash with a 'hdr' and/or
388 'tbl' key.
389 The 'tbl' key, if it exists, must contain either 'ASCII' or 'binary'
391 (case-insensitive), indicating whether to write an ascii or binary
392 table. The default is binary. [ASCII table writing is planned but
393 does not yet exist].
394 You can specify the format of the table quite specifically with the
396 'hdr' key or option field. If it exists, then the 'hdr' key should
397 contain fields appropriate to the table extension being used. Any
398 field information that you don't specify will be filled in
399 automatically, so (for example) you can specify that a particular
400 column name goes in a particular position, but allow "wfits" to
401 arrange the other columns in the usual alphabetical order into any
402 unused slots that you leave behind. The "TFORMn", "TFIELDS",
403 "PCOUNT", "GCOUNT", "NAXIS", and "NAXISn" keywords are ignored:
404 their values are calculated based on the hash that you supply. Any
405 other fields are passed into the final FITS header verbatim.
406 As an example, the following
408 $x = long(1,2,4);
410 $y = double(1,2,4);
411 wfits { 'COLA'=>$x, 'COLB'=>$y }, "table1.fits";
412 will create a binary FITS table called table1.fits which contains
414 two columns called "COLA" and "COLB". The order of the columns is
415 controlled by setting the "TTYPEn" keywords in the header array, so
416 $h = { 'TTYPE1'=>'Y', 'TTYPE2'=>'X' };
418 wfits { 'X'=>$x, 'Y'=>$y, hdr=>$h }, "table2.fits";
419 creates table2.fits where the first column is called "Y" and the
421 second column is "X".
422 · multi-value handling
424 If you feed in a perl list rather than a PDL or a hash, then each
426 element is written out as a separate HDU in the FITS file. Each
427 element of the list must be a PDL or a hash. [This is not
428 implemented yet but should be soon!]
429 · DEVEL NOTES
431 ASCII tables are not yet handled but should be.
433 Binary tables currently only handle one vector (up to 1-D array) per
435 table entry; the standard allows more, and should be fully
436 implemented. This means that PDL::Complex piddles currently can not
437 be written to disk.
438 Handling multidim arrays implies that perl multidim lists should
440 also be handled.
441 For integer types (ie "BITPIX > 0"), the "BLANK" keyword is set to the
443 bad value. For floating-point types, the bad value is converted to NaN
444 (if necessary) before writing.
445 fits_field_cmp
447 fits_field_cmp
448 Sorting comparison routine that makes proper sense of the digits at the
450 end of some FITS header fields. Sort your hash keys using
451 "fits_field_cmp" and you will get (e.g.) your "TTYPE" fields in the
452 correct order even if there are 140 of them.
453 This is a standard kludgey perl comparison sub -- it uses the magical
455 $a and $b variables, rather than normal argument passing.
456 _rows()
458 Return the number of rows in a variable for table entry
459 You feed in a PDL or a list ref, and you get back the 0th dimension.
461 _prep_table()
463 Accept a hash ref containing a table, and return a header describing
464 the table and a string to be written out as the table, or barf.
465 You can indicate whether the table should be binary or ascii. The
467 default is binary; it can be overridden by the "tbl" field of the hash
468 (if present) or by parameter.
469perl v5.30.2 2020-04-02 FITS(3)