Struct Header 

pub struct Header { /* private fields */ }

A FITS header: the cards that describe an HDU and its data.

Implementations

impl Header

pub fn author(&self) -> Option<&str>

The AUTHOR card: who prepared the data.

pub fn bitpix(&self) -> Option<Bitpix>

The BITPIX card: the type of the values in the data section.

BITPIX is mandatory, and a header lacking it is rejected when the file is opened, so this returns Some for any header read from a file. It is None only for a header built by hand and left incomplete.

pub fn blank(&self) -> Option<i64>

The BLANK card: the raw value that stands for an undefined pixel.

The standard defines it only for the integer BITPIX types; a floating point array says the same thing with a NaN.

pub fn blocked(&self) -> Option<bool>

The BLOCKED card, a deprecated hint about the file’s block size.

pub fn bscale(&self) -> Option<f64>

The BSCALE card: the factor a raw array value is multiplied by.

See Header::bscale_or_default for the standard’s default of 1.

pub fn bscale_or_default(&self) -> f64

BSCALE, defaulting to 1.0 when the card is absent.

BSCALE is optional; the FITS standard defines its default as 1.0, so a missing card means unscaled data rather than unknown data.

pub fn bunit(&self) -> Option<&str>

The BUNIT card: the physical unit the array’s values are in.

pub fn bzero(&self) -> Option<f64>

The BZERO card: the offset added to a scaled array value.

See Header::bzero_or_default for the standard’s default of 0.

pub fn bzero_or_default(&self) -> f64

BZERO, defaulting to 0.0 when the card is absent.

BZERO is optional; the FITS standard defines its default as 0.0, so a missing card means unshifted data rather than unknown data.

pub fn data_max(&self) -> Option<f64>

The DATAMAX card: the largest physical value in the array.

pub fn data_min(&self) -> Option<f64>

The DATAMIN card: the smallest physical value in the array.

pub fn date(&self) -> Option<&DateTime<Utc>>

The DATE card: when the file was written.

pub fn date_observed(&self) -> Option<&DateTime<Utc>>

The DATE-OBS card: when the observation was made.

pub fn epoch(&self) -> Option<f64>

The EPOCH card, which EQUINOX supersedes.

pub fn equinox(&self) -> Option<f64>

The EQUINOX card: the epoch of the coordinate system, in years.

pub fn extend(&self) -> Option<bool>

The EXTEND card: whether extensions may follow the primary HDU.

pub fn extension_level(&self) -> Option<i64>

The EXTLEVEL card: this extension’s level in a hierarchy of them.

pub fn extension_name(&self) -> Option<&str>

The EXTNAME card: this extension’s name.

pub fn extension_version(&self) -> Option<i64>

The EXTVER card: this extension’s version.

pub fn group_count(&self) -> Option<i64>

The GCOUNT card: how many groups the data section holds.

One for everything but a random-groups HDU.

pub fn groups(&self) -> Option<bool>

The GROUPS card: whether this HDU uses the random-groups convention.

See Header::is_random_groups, which also checks the axis that marks it.

pub fn instrument(&self) -> Option<&str>

The INSTRUME card: the instrument the data came from.

pub fn naxis(&self) -> Option<i64>

The NAXIS card: how many axes the data section has.

NAXIS is mandatory, and a header lacking it is rejected when the file is opened, so this returns Some for any header read from a file. It is None only for a header built by hand and left incomplete.

pub fn object(&self) -> Option<&str>

The OBJECT card: what was observed.

pub fn observer(&self) -> Option<&str>

The OBSERVER card: who made the observation.

pub fn origin(&self) -> Option<&str>

The ORIGIN card: the organisation that wrote the file.

pub fn pcount(&self) -> Option<i64>

The PCOUNT card: how many extra values follow the array.

This is a binary table’s heap, or the parameters of a random-groups HDU.

pub fn reference(&self) -> Option<&str>

The REFERENC card: a publication describing the data.

pub fn simple(&self) -> Option<bool>

The SIMPLE card: whether the file conforms to the FITS standard.

Only a primary header carries it.

pub fn telescope(&self) -> Option<&str>

The TELESCOP card: the telescope the data came from.

pub fn table_fields(&self) -> Option<i64>

The TFIELDS card: how many columns the table has.

pub fn table_heap(&self) -> Option<i64>

The THEAP card: where a binary table’s heap starts, as a byte offset into the data section.

pub fn extension(&self) -> Option<ExtensionType>

The XTENSION card: which kind of extension this is.

None for a primary header, which is not an extension.

pub fn focal_length(&self) -> Option<f64>

The FOCALLEN card: the telescope’s focal length.

A widespread convention among astrophotography software rather than part of the standard, as are the other camera keywords near it.

pub fn exposure_time(&self) -> Option<Duration>

The EXPTIME card: how long the exposure lasted.

pub fn ccd_temperature(&self) -> Option<f64>

The CCD-TEMP card: the sensor’s temperature, in degrees Celsius.

pub fn bayer_pattern(&self) -> Option<BayerPattern>

The BAYERPAT card: the colour filter layout over the sensor.

None for a monochrome sensor, or one that did not record the pattern.

pub fn creator(&self) -> Option<&str>

The CREATOR card: the software that wrote the file.

pub fn subframe_x_position_in_binned_pixels(&self) -> Option<i64>

The XORGSUBF card: where a subframe starts on the sensor, horizontally.

pub fn subframe_y_position_in_binned_pixels(&self) -> Option<i64>

The YORGSUBF card: where a subframe starts on the sensor, vertically.

pub fn binned_pixels_x(&self) -> Option<i64>

The XBINNING card: how many sensor pixels were binned into one, horizontally.

pub fn binned_pixels_y(&self) -> Option<i64>

The YBINNING card: how many sensor pixels were binned into one, vertically.

pub fn ccd_binned_pixels_x(&self) -> Option<i64>

The CCDXBIN card, another spelling of XBINNING.

pub fn ccd_binned_pixels_y(&self) -> Option<i64>

The CCDYBIN card, another spelling of YBINNING.

pub fn pixel_size_x_with_binning_in_microns(&self) -> Option<f64>

The XPIXSZ card: the width of a pixel in microns, binning included.

pub fn pixel_size_y_with_binning_in_microns(&self) -> Option<f64>

The YPIXSZ card: the height of a pixel in microns, binning included.

pub fn image_type(&self) -> Option<&ImageType>

The IMAGETYP card: whether this is a light, dark, flat or bias frame.

pub fn exposure(&self) -> Option<Duration>

The EXPOSURE card, another spelling of EXPTIME.

pub fn ra(&self) -> Option<f64>

The RA card: the right ascension the telescope was pointed at.

pub fn dec(&self) -> Option<f64>

The DEC card: the declination the telescope was pointed at.

pub fn guide_cam(&self) -> Option<&str>

The GUIDECAM card: the guide camera in use.

pub fn focus_position(&self) -> Option<i64>

The FOCUSPOS card: where the focuser was.

pub fn site_longitude(&self) -> Option<f64>

The SITELONG card: the observing site’s longitude.

pub fn site_latitude(&self) -> Option<f64>

The SITELAT card: the observing site’s latitude.

pub fn image_width(&self) -> Option<i64>

The IMAGEW card: the image’s width, as the writing software recorded it.

pub fn image_height(&self) -> Option<i64>

The IMAGEH card: the image’s height, as the writing software recorded it.

pub fn coordinate_delta(&self, index: usize) -> Option<f64>

The CDELTn card for axis index: how far the world coordinate moves per pixel.

pub fn coordinate_rotation(&self, index: usize) -> Option<f64>

The CROTAn card for axis index: the rotation between the pixel and world axes, in degrees.

pub fn coordinate_reference_pixel(&self, index: usize) -> Option<f64>

The CRPIXn card for axis index: the pixel that the reference value sits at, counting from 1.

pub fn coordinate_value_at_pixel(&self, index: usize) -> Option<f64>

The CRVALn card for axis index: the world coordinate at the reference pixel.

pub fn coordinate_transform(&self, row: usize, column: usize) -> Option<f64>

The CDi_j card: one element of the matrix taking pixel offsets to intermediate world coordinates.

row and column count from 0, so CD1_1 is coordinate_transform(0, 0). This matrix carries the scale as well as the rotation, which is why a header using it has no CDELTn cards.

pub fn coordinate_rotation_matrix( &self, row: usize, column: usize, ) -> Option<f64>

The PCi_j card: one element of the dimensionless matrix that rotates and skews pixel offsets, before CDELTn scales them.

row and column count from 0, so PC1_1 is coordinate_rotation_matrix(0, 0).

pub fn coordinate_axis_name(&self, index: usize) -> Option<&str>

The CTYPEn card for axis index: what the axis measures, and the projection it uses.

pub fn naxis_n(&self, index: usize) -> Option<i64>

The NAXISn card for axis index: how long that axis is.

index counts from 0, so NAXIS1 is naxis_n(0).

pub fn parameter_scaling_factor(&self, index: usize) -> Option<f64>

The PSCALn card for group parameter index.

pub fn parameter_type(&self, index: usize) -> Option<&str>

The PTYPEn card for group parameter index: what it measures.

pub fn parameter_scaling_zero_point(&self, index: usize) -> Option<f64>

The PZEROn card for group parameter index.

pub fn table_column(&self, index: usize) -> Option<i64>

The TBCOLn card for column index: where the column starts within an ASCII table’s row, counting from 1.

pub fn table_dimensions(&self, index: usize) -> Option<&str>

The TDIMn card for column index: the shape of a multidimensional column, as written.

pub fn table_display_format(&self, index: usize) -> Option<&str>

The TDISPn card for column index: how the column is best displayed.

pub fn table_null_value(&self, index: usize) -> Option<&TableNullValue>

The TNULLn card for column index: the value that marks an undefined entry in that column.

pub fn table_scaling_factor(&self, index: usize) -> Option<f64>

The TSCALn card for column index: the factor a stored entry is multiplied by.

pub fn table_column_type(&self, index: usize) -> Option<&str>

The TTYPEn card for column index: the column’s name.

pub fn table_format(&self, index: usize) -> Option<&str>

The TFORMn card for column index, exactly as written.

pub fn table_column_format(&self, index: usize) -> Option<TableColumnFormat>

The TFORMn card for column index, read as a binary table format.

None when the card is absent or does not name a binary table format, which is the case for every ASCII table; use Header::ascii_column_format for those.

pub fn ascii_column_format(&self, index: usize) -> Option<AsciiColumnFormat>

The TFORMn card for column index, read as an ASCII table format.

None when the card is absent or does not name an ASCII table format.

pub fn table_unit(&self, index: usize) -> Option<&str>

The TUNITn card for column index: the column’s physical unit.

pub fn table_scaling_zero_point(&self, index: usize) -> Option<f64>

The TZEROn card for column index: the offset added after scaling.

pub fn is_compressed_image(&self) -> bool

Whether this HDU is an image stored compressed inside a table.

The tiled image convention keeps a compressed image in a binary table, one tile per row, and describes the image it stands for with keywords beginning Z. Such an HDU reads as a table unless it is decompressed; see BinTableHDU::read_compressed_image.

pub fn compressed_bitpix(&self) -> Option<Bitpix>

The ZBITPIX card: the type of the values in the image once decompressed.

pub fn compressed_naxis(&self) -> Option<i64>

The ZNAXIS card: how many axes the decompressed image has.

pub fn compressed_naxis_n(&self, index: usize) -> Option<i64>

The ZNAXISn card for axis index: the decompressed image’s length along it. index counts from 0.

pub fn compressed_tile_size(&self, index: usize) -> i64

The ZTILEn card for axis index: how far a tile reaches along it.

The convention’s default is a tile one row of the image wide, which is what a header that leaves the card out means.

pub fn compression_type(&self) -> Option<&str>

The ZCMPTYPE card: which algorithm the tiles were compressed with.

pub fn compression_parameter(&self, name: &str) -> Option<i64>

A compression parameter, looked up by the name a ZNAMEn card gives it.

The algorithms take their settings as name and value pairs rather than as keywords of their own, so Rice’s block size arrives as ZNAME1 = 'BLOCKSIZE' with the value in ZVAL1.

pub fn quantization_method(&self) -> Option<&str>

The ZQUANTIZ card: how a floating point image’s values were turned into the integers the compressor works on.

NO_DITHER quantises plainly; the two SUBTRACTIVE_DITHER methods add a known pseudo-random number to each value before rounding it and take the same number off again on the way back, which keeps quantisation from laying a pattern over a smooth background.

pub fn dither_seed(&self) -> Option<i64>

The ZDITHER0 card: which entry of the dithering sequence the first tile starts at.

pub fn compressed_blank(&self) -> Option<i64>

The ZBLANK card: the quantised value that stands for a pixel the image does not define.

A tile may carry its own ZBLANK column instead, which takes precedence over this for that tile.

pub fn uncompressed(&self) -> Self

The header the decompressed image would have.

Every card that describes the table rather than the image is dropped, and BITPIX and the NAXISn cards are taken from their Z counterparts, so that the result describes the image the HDU stands for. Anything else the header carried — WCS keywords especially — comes across untouched.

pub fn is_random_groups(&self) -> bool

Whether this HDU uses the random-groups convention.

Such an HDU’s data section is not an image but GCOUNT groups, each one a run of PCOUNT parameters followed by an array. The convention is marked by GROUPS = T, and by a first axis of length zero standing in for the axis the groups occupy.

pub fn to_bytes(&self) -> Vec<u8>

Renders this header as the bytes it occupies in a file.

The result is always a whole number of 2880-byte blocks, padded with spaces, and always ends with an END card — a header without one is not a header a reader can find the end of.

pub fn set_naxis_n( &mut self, index: usize, length: i64, ) -> Result<(), Box<dyn Error + Send + Sync>>

Sets the NAXISn card for axis index, which counts from 0.

Errors

Returns an error for a negative length, which no axis can have.

pub fn raw_card(&self, key: &str) -> Vec<Value>

Every card with the keyword key, as raw values.

Most keywords appear once, but COMMENT and HISTORY may repeat, and an unrecognised keyword can appear as often as the writer liked.

pub fn card(&self, key: &str) -> Option<Value>

The value of the card with the keyword key, if there is one.

Where a keyword repeats — COMMENT and HISTORY do, and an unrecognised one may — this is the first of them; Header::raw_card returns them all.

let mut header = Header::default();
header.set_card("OBJECT", "M31")?;

assert_eq!(header.card("OBJECT").map(|v| v.value_to_string()), Some("M31".into()));
assert!(header.card("MISSING").is_none());

pub fn contains_card(&self, key: &str) -> bool

Whether this header carries a card with the keyword key.

pub fn card_keys(&self) -> impl Iterator<Item = String> + '_

Every keyword this header holds, in the order the cards are in.

A repeated keyword appears once per card, and the blank keyword of a COMMENT-style card with no keyword appears as an empty string.

pub fn set_card( &mut self, key: &str, value: impl Into<Value>, ) -> Result<(), Box<dyn Error + Send + Sync>>

Sets the card with the keyword key to value, adding it if the header does not already have one.

The value may be any of the types a FITS card can hold — an integer, a float, a bool, a string, or None for a keyword written with no value — and Value::with_comment puts a comment beside it.

A keyword of up to eight characters drawn from A–Z, 0–9, - and _ is written as an ordinary card, upper-cased on the way in. A longer or otherwise unconventional keyword is written with the HIERARCH convention, which keeps its case. Setting a keyword this crate reads through one of its typed accessors — OBJECT, DATE-OBS, BUNIT and the rest — leaves that accessor returning the new value.

Errors

Returns an error for a keyword that is empty, holds characters a card cannot carry, or is one of the repeatable and structural keywords that have setters of their own: use Header::add_comment, Header::add_history and Header::set_naxis_n for those. Also returns an error when the value is too long for the one card it has to fit on — a long string is written across CONTINUE cards instead and is never too long.

let mut header = Header::default();

header.set_card("OBJECT", "NGC 7000")?;
header.set_card("EXPTIME", Value::from(120.0).with_comment("seconds"))?;
header.set_card("MOONLIT", true)?;

// A keyword too long for the eight columns a card gives it becomes a
// HIERARCH card.
header.set_card("ESO INS FILT1 NAME", "Halpha")?;

assert_eq!(header.object(), Some("NGC 7000"));

pub fn remove_card(&mut self, key: &str) -> usize

Removes every card with the keyword key, and says how many went.

A mandatory card removed this way comes back when the header is written: SIMPLE, BITPIX, NAXIS and the rest are filled in from the data whatever the cards say.

pub fn add_comment(&mut self, text: impl AsRef<str>)

Adds a COMMENT card carrying text.

COMMENT cards repeat, so this always adds one rather than replacing what is there. Text too long for a card is split across as many as it needs.

pub fn add_history(&mut self, text: impl AsRef<str>)

Adds a HISTORY card carrying text.

As with Header::add_comment, this adds rather than replaces, and text too long for one card is split across several.

pub fn comments(&self) -> impl Iterator<Item = &str>

The text of every COMMENT card, in order.

pub fn history(&self) -> impl Iterator<Item = &str>

The text of every HISTORY card, in order.

Trait Implementations

impl Clone for Header

fn clone(&self) -> Header

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Header

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Header

fn default() -> Header

Returns the “default value” for a type.