Skip to main content

rfitsio/
header.rs

1//! In-memory header: a sequence of 80-byte cards plus record padding.
2
3use crate::card::{
4    Card, format_complex_exp, format_complex_fixed, format_exp_double, format_fixed_double,
5    format_string_value, make_card_string, parse_value_comment, unquote_fits_string,
6};
7use crate::error::{FitsError, Result};
8use crate::status::{
9    BAD_BITPIX, BAD_KEYCHAR, BAD_NAXES, BAD_NAXIS, BAD_TBCOL, BAD_TFIELDS, BAD_TFORM, KEY_NO_EXIST,
10    KEY_OUT_BOUNDS, NEG_AXIS, NEG_ROWS, NEG_WIDTH, NO_END, NO_TBCOL, NO_TFORM, NO_XTENSION,
11    NOT_ATABLE, NOT_BTABLE,
12};
13use crate::tform::{BinaryKind, BinaryTform, ascii_column_starts, binary_column_offsets};
14use crate::types::{CARD_LEN, ImageType, RECORD_LEN};
15
16/// CFITSIO `ffphpr` self-documenting COMMENT cards (primary array).
17pub const COMMENT_FITS_1: &str =
18    "COMMENT   FITS (Flexible Image Transport System) format is defined in 'Astronomy";
19pub const COMMENT_FITS_2: &str =
20    "COMMENT   and Astrophysics', volume 376, page 359; bibcode: 2001A&A...376..359H";
21
22pub const COMM_SIMPLE: &str = "file does conform to FITS standard";
23pub const COMM_BITPIX: &str = "number of bits per data pixel";
24pub const COMM_NAXIS: &str = "number of data axes";
25pub const COMM_EXTEND: &str = "FITS dataset may contain extensions";
26pub const COMM_NAXIS_N: &str = "length of data axis ";
27pub const COMM_XTENSION_IMAGE: &str = "IMAGE extension";
28pub const COMM_PCOUNT: &str = "required keyword; must = 0";
29pub const COMM_GCOUNT: &str = "required keyword; must = 1";
30pub const COMM_PCOUNT_GROUP: &str = "number of random group parameters";
31pub const COMM_GCOUNT_GROUP: &str = "number of random groups";
32pub const COMM_BSCALE: &str = "default scaling factor";
33pub const COMM_BZERO_USHORT: &str = "offset data range to that of unsigned short";
34pub const COMM_BZERO_ULONG: &str = "offset data range to that of unsigned long";
35pub const COMM_BZERO_SBYTE: &str = "offset data range to that of signed byte";
36pub const BZERO_ULONGLONG_CARD: &str =
37    "BZERO   =  9223372036854775808 / offset data range to that of unsigned long long";
38
39pub const COMM_XTENSION_TABLE: &str = "ASCII table extension";
40pub const COMM_BITPIX_ASCII: &str = "8-bit ASCII characters";
41pub const COMM_NAXIS_ASCII: &str = "2-dimensional ASCII table";
42pub const COMM_NAXIS1_ASCII: &str = "width of table in characters";
43pub const COMM_NAXIS2_ASCII: &str = "number of rows in table";
44pub const COMM_PCOUNT_ASCII: &str = "no group parameters (required keyword)";
45pub const COMM_GCOUNT_ASCII: &str = "one data group (required keyword)";
46pub const COMM_TFIELDS: &str = "number of fields in each row";
47pub const COMM_TFORM_ASCII: &str = "Fortran-77 format of field";
48pub const COMM_TUNIT: &str = "physical unit of field";
49pub const COMM_EXTNAME_ASCII: &str = "name of this ASCII table extension";
50pub const COMM_TTYPE_INSERTED: &str = "label for field";
51pub const COMM_TFORM_INSERTED: &str = "format of field";
52pub const COMM_TBCOL_INSERTED: &str = "beginning column of field";
53
54pub const COMM_XTENSION_BINTABLE: &str = "binary table extension";
55pub const COMM_BITPIX_BIN: &str = "8-bit bytes";
56pub const COMM_NAXIS_BIN: &str = "2-dimensional binary table";
57pub const COMM_NAXIS1_BIN: &str = "width of table in bytes";
58pub const COMM_NAXIS2_BIN: &str = "number of rows in table";
59pub const COMM_PCOUNT_BIN: &str = "size of special data area";
60pub const COMM_GCOUNT_BIN: &str = "one data group (required keyword)";
61pub const COMM_TFORM_BIN: &str = "data format of field";
62pub const COMM_TZERO_UNSIGNED: &str = "offset for unsigned integers";
63pub const COMM_TZERO_SBYTE: &str = "offset for signed bytes";
64pub const COMM_TSCAL_BIN: &str = "data are not scaled";
65pub const COMM_EXTNAME_BIN: &str = "name of this binary table extension";
66
67/// Result of [`Header::primary_info`] (`ffghpr`).
68#[derive(Debug, Clone, PartialEq, Eq)]
69pub struct PrimaryInfo {
70    /// SIMPLE.
71    pub simple: bool,
72    /// BITPIX.
73    pub bitpix: i32,
74    /// NAXIS.
75    pub naxis: i32,
76    /// NAXISn.
77    pub naxes: Vec<i64>,
78    /// PCOUNT (0 if absent).
79    pub pcount: i64,
80    /// GCOUNT (1 if absent).
81    pub gcount: i64,
82    /// EXTEND (false if absent).
83    pub extend: bool,
84}
85
86/// Result of [`Header::ascii_table_info`] (`ffghtb`).
87#[derive(Debug, Clone, PartialEq, Eq)]
88pub struct AsciiTableInfo {
89    /// NAXIS1: characters per row.
90    pub rowlen: i64,
91    /// NAXIS2: number of rows.
92    pub nrows: i64,
93    /// TFIELDS.
94    pub tfields: i32,
95    /// TTYPEn (empty string if absent).
96    pub ttype: Vec<String>,
97    /// TBCOLn (1-based).
98    pub tbcol: Vec<i64>,
99    /// TFORMn.
100    pub tform: Vec<String>,
101    /// TUNITn (empty string if absent).
102    pub tunit: Vec<String>,
103    /// EXTNAME (empty if absent).
104    pub extname: String,
105}
106
107/// Result of [`Header::binary_table_info`] (`ffghbn`).
108#[derive(Debug, Clone, PartialEq, Eq)]
109pub struct BinaryTableInfo {
110    /// NAXIS2.
111    pub nrows: i64,
112    /// TFIELDS.
113    pub tfields: i32,
114    /// TTYPEn.
115    pub ttype: Vec<String>,
116    /// TFORMn.
117    pub tform: Vec<String>,
118    /// TUNITn.
119    pub tunit: Vec<String>,
120    /// EXTNAME.
121    pub extname: String,
122    /// PCOUNT (heap size).
123    pub pcount: i64,
124    /// NAXIS1 (row width in bytes).
125    pub rowlen: i64,
126}
127
128/// Ordered list of header cards, without the END card or fill.
129#[derive(Clone, Debug, Default, PartialEq, Eq)]
130pub struct Header {
131    cards: Vec<Card>,
132}
133
134impl Header {
135    /// Empty header (no cards yet).
136    #[must_use]
137    pub fn new() -> Self {
138        Self { cards: Vec::new() }
139    }
140
141    /// Header from an ordered list of cards (no END).
142    #[must_use]
143    pub fn from_cards(cards: Vec<Card>) -> Self {
144        Self { cards }
145    }
146
147    /// True if this header is a primary array (`SIMPLE` present).
148    #[must_use]
149    pub fn is_primary(&self) -> bool {
150        self.card_by_name("SIMPLE").is_some()
151    }
152
153    /// CFITSIO empty primary: SIMPLE/BITPIX=8/NAXIS=0/EXTEND plus COMMENTs.
154    pub fn empty_primary() -> Result<Self> {
155        let mut h = Self::new();
156        h.write_logical("SIMPLE", true, Some(COMM_SIMPLE))?;
157        h.write_long("BITPIX", 8, Some(COMM_BITPIX))?;
158        h.write_long("NAXIS", 0, Some(COMM_NAXIS))?;
159        h.write_logical("EXTEND", true, Some(COMM_EXTEND))?;
160        h.push(Card::from_text(COMMENT_FITS_1));
161        h.push(Card::from_text(COMMENT_FITS_2));
162        Ok(h)
163    }
164
165    /// Number of keyword cards (not counting END or fill).
166    #[must_use]
167    pub fn len(&self) -> usize {
168        self.cards.len()
169    }
170
171    /// True if no cards have been written.
172    #[must_use]
173    pub fn is_empty(&self) -> bool {
174        self.cards.is_empty()
175    }
176
177    /// Append a fully formatted card.
178    pub fn push(&mut self, card: Card) {
179        self.cards.push(card);
180    }
181
182    /// Replace 0-based card `idx`.
183    pub fn replace_record_idx(&mut self, idx: usize, card: Card) -> Result<()> {
184        if idx >= self.cards.len() {
185            return Err(FitsError::new(KEY_OUT_BOUNDS));
186        }
187        self.cards[idx] = card;
188        Ok(())
189    }
190
191    /// Cards in order.
192    #[must_use]
193    pub fn cards(&self) -> &[Card] {
194        &self.cards
195    }
196
197    /// `fits_write_key_log` / `ffpkyl`.
198    pub fn write_logical(&mut self, name: &str, value: bool, comm: Option<&str>) -> Result<()> {
199        let v = if value { "T" } else { "F" };
200        let s = make_card_string(name, v, comm)?;
201        self.cards.push(Card::from_text(&s));
202        Ok(())
203    }
204
205    /// `fits_write_key_lng` / `ffpkyj`.
206    pub fn write_long(&mut self, name: &str, value: i64, comm: Option<&str>) -> Result<()> {
207        let v = value.to_string();
208        let s = make_card_string(name, &v, comm)?;
209        self.cards.push(Card::from_text(&s));
210        Ok(())
211    }
212
213    /// `fits_write_key_str` / `ffpkys`.
214    pub fn write_string(&mut self, name: &str, value: &str, comm: Option<&str>) -> Result<()> {
215        let v = format_string_value(value);
216        let s = make_card_string(name, &v, comm)?;
217        self.cards.push(Card::from_text(&s));
218        Ok(())
219    }
220
221    /// `fits_write_key_fixdbl` / `ffpkyg`.
222    pub fn write_fixed_double(
223        &mut self,
224        name: &str,
225        value: f64,
226        decim: usize,
227        comm: Option<&str>,
228    ) -> Result<()> {
229        let v = format_fixed_double(value, decim);
230        let s = make_card_string(name, &v, comm)?;
231        self.cards.push(Card::from_text(&s));
232        Ok(())
233    }
234
235    /// Required keywords for a primary image (`ffphps` / `ffcrim` on HDU 0).
236    pub fn primary_image(ty: ImageType, naxes: &[i64]) -> Result<Self> {
237        if naxes.len() > 999 {
238            return Err(FitsError::new(BAD_NAXIS));
239        }
240        let mut h = Self::new();
241        h.write_logical("SIMPLE", true, Some(COMM_SIMPLE))?;
242        h.write_long("BITPIX", i64::from(ty.bitpix()), Some(COMM_BITPIX))?;
243        h.write_long("NAXIS", naxes.len() as i64, Some(COMM_NAXIS))?;
244        for (i, &len) in naxes.iter().enumerate() {
245            if len < 1 {
246                return Err(FitsError::new(NEG_AXIS));
247            }
248            let name = format!("NAXIS{}", i + 1);
249            let comm = format!("{COMM_NAXIS_N}{}", i + 1);
250            h.write_long(&name, len, Some(&comm))?;
251        }
252        h.write_logical("EXTEND", true, Some(COMM_EXTEND))?;
253        h.push(Card::from_text(COMMENT_FITS_1));
254        h.push(Card::from_text(COMMENT_FITS_2));
255        write_unsigned_scaling(&mut h, ty)?;
256        Ok(h)
257    }
258
259    /// Required keywords for an IMAGE extension (`ffphpr` when not HDU 0).
260    pub fn image_extension(ty: ImageType, naxes: &[i64]) -> Result<Self> {
261        if naxes.len() > 999 {
262            return Err(FitsError::new(BAD_NAXIS));
263        }
264        let mut h = Self::new();
265        h.write_string("XTENSION", "IMAGE", Some(COMM_XTENSION_IMAGE))?;
266        h.write_long("BITPIX", i64::from(ty.bitpix()), Some(COMM_BITPIX))?;
267        h.write_long("NAXIS", naxes.len() as i64, Some(COMM_NAXIS))?;
268        for (i, &len) in naxes.iter().enumerate() {
269            if len < 0 {
270                return Err(FitsError::new(BAD_NAXES));
271            }
272            let name = format!("NAXIS{}", i + 1);
273            let comm = format!("{COMM_NAXIS_N}{}", i + 1);
274            h.write_long(&name, len, Some(&comm))?;
275        }
276        h.write_long("PCOUNT", 0, Some(COMM_PCOUNT))?;
277        h.write_long("GCOUNT", 1, Some(COMM_GCOUNT))?;
278        write_unsigned_scaling(&mut h, ty)?;
279        Ok(h)
280    }
281
282    /// Required keywords for an ASCII table extension (`ffphtb`).
283    ///
284    /// TBCOL values and NAXIS1 are computed with one blank between columns
285    /// (`ffgabc` with `space = 1`).
286    pub fn ascii_table(
287        nrows: i64,
288        ttype: &[&str],
289        tform: &[&str],
290        tunit: &[Option<&str>],
291        extname: Option<&str>,
292    ) -> Result<Self> {
293        if nrows < 0 {
294            return Err(FitsError::new(NEG_ROWS));
295        }
296        let tfields = tform.len();
297        if tfields > 999 {
298            return Err(FitsError::new(BAD_TFIELDS));
299        }
300        for tf in tform {
301            if tf.len() > 29 {
302                return Err(FitsError::with_message(
303                    BAD_TFORM,
304                    "Error: ASCII table TFORM code is too long (ffphtb)",
305                ));
306            }
307        }
308        let (rowlen, tbcol) = ascii_column_starts(tform, 1)?;
309        if rowlen < 0 {
310            return Err(FitsError::new(NEG_WIDTH));
311        }
312        let mut h = Self::new();
313        h.write_string("XTENSION", "TABLE", Some(COMM_XTENSION_TABLE))?;
314        h.write_long("BITPIX", 8, Some(COMM_BITPIX_ASCII))?;
315        h.write_long("NAXIS", 2, Some(COMM_NAXIS_ASCII))?;
316        h.write_long("NAXIS1", rowlen, Some(COMM_NAXIS1_ASCII))?;
317        h.write_long("NAXIS2", nrows, Some(COMM_NAXIS2_ASCII))?;
318        h.write_long("PCOUNT", 0, Some(COMM_PCOUNT_ASCII))?;
319        h.write_long("GCOUNT", 1, Some(COMM_GCOUNT_ASCII))?;
320        h.write_long("TFIELDS", tfields as i64, Some(COMM_TFIELDS))?;
321        for (ii, tf) in tform.iter().enumerate() {
322            let n = ii + 1;
323            let ttype_s = ttype.get(ii).copied().unwrap_or("");
324            if !ttype_s.is_empty() {
325                let comm = format!("label for field {n:3}");
326                h.write_string(&format!("TTYPE{n}"), ttype_s, Some(&comm))?;
327            }
328            let col = tbcol[ii];
329            if col < 1 || (rowlen > 0 && col > rowlen) {
330                return Err(FitsError::new(BAD_TBCOL));
331            }
332            let comm = format!("beginning column of field {n:3}");
333            h.write_long(&format!("TBCOL{n}"), col, Some(&comm))?;
334            let tfmt = tf.to_ascii_uppercase();
335            h.write_string(&format!("TFORM{n}"), &tfmt, Some(COMM_TFORM_ASCII))?;
336            if let Some(&Some(unit)) = tunit.get(ii) {
337                if !unit.is_empty() {
338                    h.write_string(&format!("TUNIT{n}"), unit, Some(COMM_TUNIT))?;
339                }
340            }
341        }
342        if let Some(name) = extname {
343            if !name.is_empty() {
344                h.write_string("EXTNAME", name, Some(COMM_EXTNAME_ASCII))?;
345            }
346        }
347        Ok(h)
348    }
349
350    /// ASCII-table required keywords (`fits_read_atblhdr` / `ffghtb`).
351    pub fn ascii_table_info(&self) -> Result<AsciiTableInfo> {
352        let first = self
353            .cards
354            .first()
355            .ok_or_else(|| FitsError::new(NO_XTENSION))?;
356        let (fname, _) = first.keyword_name()?;
357        if !fname.eq_ignore_ascii_case("XTENSION") {
358            return Err(FitsError::new(NO_XTENSION));
359        }
360        let (xt, _) = self.get_string("XTENSION")?;
361        if xt.trim() != "TABLE" {
362            return Err(FitsError::new(NOT_ATABLE));
363        }
364        let rowlen = self.get_i64("NAXIS1")?;
365        let nrows = self.get_i64("NAXIS2")?;
366        let tfields_i = self.get_i64("TFIELDS")?;
367        if !(0..=999).contains(&tfields_i) {
368            return Err(FitsError::new(BAD_TFIELDS));
369        }
370        let tfields = tfields_i as i32;
371        let mut ttype = Vec::new();
372        let mut tbcol = Vec::new();
373        let mut tform = Vec::new();
374        let mut tunit = Vec::new();
375        for i in 1..=tfields {
376            ttype.push(
377                self.get_string(&format!("TTYPE{i}"))
378                    .map(|(v, _)| v)
379                    .unwrap_or_default(),
380            );
381            tbcol.push(
382                self.get_i64(&format!("TBCOL{i}"))
383                    .map_err(|_| FitsError::new(NO_TBCOL))?,
384            );
385            tform.push(
386                self.get_string(&format!("TFORM{i}"))
387                    .map(|(v, _)| v)
388                    .map_err(|_| FitsError::new(NO_TFORM))?,
389            );
390            tunit.push(
391                self.get_string(&format!("TUNIT{i}"))
392                    .map(|(v, _)| v)
393                    .unwrap_or_default(),
394            );
395        }
396        let extname = self
397            .get_string("EXTNAME")
398            .map(|(v, _)| v)
399            .unwrap_or_default();
400        Ok(AsciiTableInfo {
401            rowlen,
402            nrows,
403            tfields,
404            ttype,
405            tbcol,
406            tform,
407            tunit,
408            extname,
409        })
410    }
411
412    /// Required keywords for a binary table extension (`ffphbn`).
413    pub fn binary_table(
414        nrows: i64,
415        ttype: &[&str],
416        tform: &[&str],
417        tunit: &[Option<&str>],
418        extname: Option<&str>,
419    ) -> Result<Self> {
420        if nrows < 0 {
421            return Err(FitsError::new(NEG_ROWS));
422        }
423        let tfields = tform.len();
424        if tfields > 999 {
425            return Err(FitsError::new(BAD_TFIELDS));
426        }
427        for tf in tform {
428            if tf.len() > 29 {
429                return Err(FitsError::with_message(
430                    BAD_TFORM,
431                    "Error: BIN table TFORM code is too long (ffphbn)",
432                ));
433            }
434        }
435        let (rowlen, _) = binary_column_offsets(tform)?;
436        let mut h = Self::new();
437        h.write_string("XTENSION", "BINTABLE", Some(COMM_XTENSION_BINTABLE))?;
438        h.write_long("BITPIX", 8, Some(COMM_BITPIX_BIN))?;
439        h.write_long("NAXIS", 2, Some(COMM_NAXIS_BIN))?;
440        h.write_long("NAXIS1", rowlen, Some(COMM_NAXIS1_BIN))?;
441        h.write_long("NAXIS2", nrows, Some(COMM_NAXIS2_BIN))?;
442        h.write_long("PCOUNT", 0, Some(COMM_PCOUNT_BIN))?;
443        h.write_long("GCOUNT", 1, Some(COMM_GCOUNT_BIN))?;
444        h.write_long("TFIELDS", tfields as i64, Some(COMM_TFIELDS))?;
445        for (ii, tf) in tform.iter().enumerate() {
446            let n = ii + 1;
447            let ttype_s = ttype.get(ii).copied().unwrap_or("");
448            if !ttype_s.is_empty() {
449                let comm = format!("label for field {n:3}");
450                h.write_string(&format!("TTYPE{n}"), ttype_s, Some(&comm))?;
451            }
452            let parsed = BinaryTform::parse(tf)?;
453            let stored = BinaryTform::stored_code(tf);
454            let comm = format!("{COMM_TFORM_BIN}{}", parsed.tform_comment_suffix());
455            h.write_string(&format!("TFORM{n}"), &stored, Some(&comm))?;
456            match parsed.kind {
457                BinaryKind::S => {
458                    h.write_fixed_double(&format!("TZERO{n}"), -128.0, 0, Some(COMM_TZERO_SBYTE))?;
459                    h.write_fixed_double(&format!("TSCAL{n}"), 1.0, 0, Some(COMM_TSCAL_BIN))?;
460                }
461                BinaryKind::U => {
462                    h.write_fixed_double(
463                        &format!("TZERO{n}"),
464                        32768.0,
465                        0,
466                        Some(COMM_TZERO_UNSIGNED),
467                    )?;
468                    h.write_fixed_double(&format!("TSCAL{n}"), 1.0, 0, Some(COMM_TSCAL_BIN))?;
469                }
470                BinaryKind::V => {
471                    h.write_fixed_double(
472                        &format!("TZERO{n}"),
473                        2_147_483_648.0,
474                        0,
475                        Some(COMM_TZERO_UNSIGNED),
476                    )?;
477                    h.write_fixed_double(&format!("TSCAL{n}"), 1.0, 0, Some(COMM_TSCAL_BIN))?;
478                }
479                BinaryKind::W => {
480                    let name = format!("TZERO{n}");
481                    let card =
482                        format!("{name:<8}=  9223372036854775808 / offset for unsigned integers");
483                    h.push(Card::from_text(&card));
484                    h.write_fixed_double(&format!("TSCAL{n}"), 1.0, 0, Some(COMM_TSCAL_BIN))?;
485                }
486                _ => {}
487            }
488            if let Some(&Some(unit)) = tunit.get(ii) {
489                if !unit.is_empty() {
490                    h.write_string(&format!("TUNIT{n}"), unit, Some(COMM_TUNIT))?;
491                }
492            }
493        }
494        if let Some(name) = extname {
495            if !name.is_empty() {
496                h.write_string("EXTNAME", name, Some(COMM_EXTNAME_BIN))?;
497            }
498        }
499        Ok(h)
500    }
501
502    /// Binary-table required keywords (`fits_read_btblhdr` / `ffghbn`).
503    pub fn binary_table_info(&self) -> Result<BinaryTableInfo> {
504        let first = self
505            .cards
506            .first()
507            .ok_or_else(|| FitsError::new(NO_XTENSION))?;
508        let (fname, _) = first.keyword_name()?;
509        if !fname.eq_ignore_ascii_case("XTENSION") {
510            return Err(FitsError::new(NO_XTENSION));
511        }
512        let (xt, _) = self.get_string("XTENSION")?;
513        let xt = xt.trim();
514        if xt != "BINTABLE" && xt != "A3DTABLE" && xt != "3DTABLE" {
515            return Err(FitsError::new(NOT_BTABLE));
516        }
517        let rowlen = self.get_i64("NAXIS1")?;
518        let nrows = self.get_i64("NAXIS2")?;
519        let pcount = self.get_i64("PCOUNT").unwrap_or(0);
520        let tfields_i = self.get_i64("TFIELDS")?;
521        if !(0..=999).contains(&tfields_i) {
522            return Err(FitsError::new(BAD_TFIELDS));
523        }
524        let tfields = tfields_i as i32;
525        let mut ttype = Vec::new();
526        let mut tform = Vec::new();
527        let mut tunit = Vec::new();
528        for i in 1..=tfields {
529            ttype.push(
530                self.get_string(&format!("TTYPE{i}"))
531                    .map(|(v, _)| v)
532                    .unwrap_or_default(),
533            );
534            tform.push(
535                self.get_string(&format!("TFORM{i}"))
536                    .map(|(v, _)| v)
537                    .map_err(|_| FitsError::new(NO_TFORM))?,
538            );
539            tunit.push(
540                self.get_string(&format!("TUNIT{i}"))
541                    .map(|(v, _)| v)
542                    .unwrap_or_default(),
543            );
544        }
545        let extname = self
546            .get_string("EXTNAME")
547            .map(|(v, _)| v)
548            .unwrap_or_default();
549        Ok(BinaryTableInfo {
550            nrows,
551            tfields,
552            ttype,
553            tform,
554            tunit,
555            extname,
556            pcount,
557            rowlen,
558        })
559    }
560
561    /// Replace a long keyword, keeping its existing comment (`ffmkyj` with `"&"`).
562    pub fn update_long_keep_comment(&mut self, name: &str, value: i64) -> Result<()> {
563        let comm = match self.raw_value_comment(name) {
564            Ok((_, c)) if !c.is_empty() => Some(c),
565            Ok(_) => None,
566            Err(e) => return Err(e),
567        };
568        let s = make_card_string(name, &value.to_string(), comm.as_deref())?;
569        self.replace_name(name, Card::from_text(&s))
570    }
571
572    /// Shift `Txxxn` keyword indices (`ffkshf`). Starts at the 9th card.
573    ///
574    /// If `incre <= 0`, keywords with index `colmin` are deleted.
575    pub fn shift_table_col_keys(&mut self, colmin: i32, colmax: i32, incre: i32) -> Result<()> {
576        let mut i = 8usize;
577        while i < self.cards.len() {
578            let bytes = *self.cards[i].as_bytes();
579            if bytes[0] != b'T' {
580                i += 1;
581                continue;
582            }
583            let Some((prefix_len, ivalue)) = tkey_index(&bytes) else {
584                i += 1;
585                continue;
586            };
587            if ivalue < colmin || ivalue > colmax {
588                i += 1;
589                continue;
590            }
591            if incre <= 0 && ivalue == colmin {
592                self.cards.remove(i);
593                continue;
594            }
595            let new_idx = ivalue + incre;
596            let prefix = std::str::from_utf8(&bytes[0..prefix_len]).unwrap_or("");
597            let new_name = format!("{prefix}{new_idx}");
598            self.cards[i].set_keyword_name(&new_name);
599            i += 1;
600        }
601        Ok(())
602    }
603
604    /// First card whose 8-character name matches `name` (case-insensitive).
605    #[must_use]
606    pub fn card_by_name(&self, name: &str) -> Option<&Card> {
607        let key = name8(name);
608        self.cards
609            .iter()
610            .find(|c| name8_bytes(&c.as_bytes()[..8]) == key)
611    }
612
613    /// Integer keyword value (`fits_read_key_lng`).
614    pub fn get_i64(&self, name: &str) -> Result<i64> {
615        let card = self
616            .card_by_name(name)
617            .ok_or_else(|| FitsError::new(KEY_NO_EXIST))?;
618        let text = card.as_str().unwrap_or("");
619        let (val, _) = parse_value_comment(text)?;
620        val.trim()
621            .parse::<i64>()
622            .map_err(|_| FitsError::new(crate::status::BAD_INTKEY))
623    }
624
625    /// Floating keyword value (`fits_read_key_dbl`).
626    pub fn get_f64(&self, name: &str) -> Result<f64> {
627        let card = self
628            .card_by_name(name)
629            .ok_or_else(|| FitsError::new(KEY_NO_EXIST))?;
630        let text = card.as_str().unwrap_or("");
631        let (val, _) = parse_value_comment(text)?;
632        val.trim()
633            .parse::<f64>()
634            .map_err(|_| FitsError::new(crate::status::BAD_FLOATKEY))
635    }
636
637    /// NAXIS axis lengths.
638    pub fn naxes(&self) -> Result<Vec<i64>> {
639        let n = self.get_i64("NAXIS")?;
640        if n < 0 {
641            return Err(FitsError::new(BAD_NAXIS));
642        }
643        let mut out = Vec::with_capacity(n as usize);
644        for i in 1..=n {
645            out.push(self.get_i64(&format!("NAXIS{i}"))?);
646        }
647        Ok(out)
648    }
649
650    /// Stored BITPIX.
651    pub fn bitpix(&self) -> Result<i32> {
652        let v = self.get_i64("BITPIX")?;
653        i32::try_from(v).map_err(|_| FitsError::new(BAD_BITPIX))
654    }
655
656    /// BSCALE, default 1.0.
657    pub fn bscale(&self) -> f64 {
658        self.get_f64("BSCALE").unwrap_or(1.0)
659    }
660
661    /// BZERO, default 0.0. ULONGLONG's integer BZERO is returned as f64.
662    pub fn bzero(&self) -> f64 {
663        self.get_f64("BZERO").unwrap_or(0.0)
664    }
665
666    /// BLANK keyword if present.
667    pub fn blank(&self) -> Option<i64> {
668        self.get_i64("BLANK").ok()
669    }
670
671    /// Replace or append a BLANK keyword.
672    pub fn set_blank(&mut self, value: i64) -> Result<()> {
673        self.upsert_long("BLANK", value, Some("undefined pixel value"))
674    }
675
676    /// Replace the first card of this name, or append.
677    pub fn upsert_long(&mut self, name: &str, value: i64, comm: Option<&str>) -> Result<()> {
678        let v = value.to_string();
679        let s = make_card_string(name, &v, comm)?;
680        let card = Card::from_text(&s);
681        let key = name8(name);
682        if let Some(i) = self
683            .cards
684            .iter()
685            .position(|c| name8_bytes(&c.as_bytes()[..8]) == key)
686        {
687            self.cards[i] = card;
688        } else {
689            self.cards.push(card);
690        }
691        Ok(())
692    }
693
694    /// `fits_write_key_flt` / `ffpkye` (exponential).
695    pub fn write_float_exp(
696        &mut self,
697        name: &str,
698        value: f64,
699        decim: usize,
700        comm: Option<&str>,
701    ) -> Result<()> {
702        let v = format_exp_double(value, decim);
703        self.push_made(name, &v, comm)
704    }
705
706    /// `fits_write_key_null` / `ffpkyu`.
707    pub fn write_null(&mut self, name: &str, comm: Option<&str>) -> Result<()> {
708        self.push_made(name, " ", comm)
709    }
710
711    /// `fits_write_comment` / `ffpcom`.
712    pub fn write_comment(&mut self, comm: &str) {
713        for chunk in comm.as_bytes().chunks(72) {
714            let mut card = String::from("COMMENT ");
715            card.push_str(std::str::from_utf8(chunk).unwrap_or(""));
716            self.cards.push(Card::from_text(&card));
717        }
718    }
719
720    /// `fits_write_history` / `ffphis`.
721    pub fn write_history(&mut self, hist: &str) {
722        for chunk in hist.as_bytes().chunks(72) {
723            let mut card = String::from("HISTORY ");
724            card.push_str(std::str::from_utf8(chunk).unwrap_or(""));
725            self.cards.push(Card::from_text(&card));
726        }
727    }
728
729    /// `fits_write_record` / `ffprec`.
730    pub fn write_record(&mut self, card: &str) {
731        self.cards.push(Card::from_text(card));
732    }
733
734    /// Complex exponential (`ffpkyc` / `ffpkym`).
735    pub fn write_complex_exp(
736        &mut self,
737        name: &str,
738        real: f64,
739        imag: f64,
740        decim: usize,
741        comm: Option<&str>,
742    ) -> Result<()> {
743        let v = format_complex_exp(real, imag, decim);
744        self.push_made(name, &v, comm)
745    }
746
747    /// Complex fixed (`ffpkfc` / `ffpkfm`).
748    pub fn write_complex_fixed(
749        &mut self,
750        name: &str,
751        real: f64,
752        imag: f64,
753        decim: usize,
754        comm: Option<&str>,
755    ) -> Result<()> {
756        let v = format_complex_fixed(real, imag, decim);
757        self.push_made(name, &v, comm)
758    }
759
760    /// Unsigned 64-bit integer keyword.
761    pub fn write_ulong(&mut self, name: &str, value: u64, comm: Option<&str>) -> Result<()> {
762        self.push_made(name, &value.to_string(), comm)
763    }
764
765    fn push_made(&mut self, name: &str, value: &str, comm: Option<&str>) -> Result<()> {
766        let s = make_card_string(name, value, comm)?;
767        self.cards.push(Card::from_text(&s));
768        Ok(())
769    }
770
771    /// 1-based keyword record (`fits_read_record`). Does not include END.
772    pub fn record(&self, n: usize) -> Result<Card> {
773        self.cards
774            .get(n.wrapping_sub(1))
775            .copied()
776            .ok_or_else(|| FitsError::new(KEY_OUT_BOUNDS))
777    }
778
779    /// Unquoted string value (`fits_read_key_str`).
780    pub fn get_string(&self, name: &str) -> Result<(String, String)> {
781        let (val, comm) = self.raw_value_comment(name)?;
782        Ok((unquote_fits_string(&val), comm))
783    }
784
785    /// Logical value (`fits_read_key_log`).
786    pub fn get_logical(&self, name: &str) -> Result<(bool, String)> {
787        let (val, comm) = self.raw_value_comment(name)?;
788        let v = val.trim();
789        match v.as_bytes().first() {
790            Some(b'T' | b't') => Ok((true, comm)),
791            Some(b'F' | b'f') => Ok((false, comm)),
792            _ => Err(FitsError::new(crate::status::BAD_LOGICALKEY)),
793        }
794    }
795
796    /// Raw value + comment strings (`fits_read_keyword`).
797    pub fn raw_value_comment(&self, name: &str) -> Result<(String, String)> {
798        let card = self
799            .card_by_name(name)
800            .ok_or_else(|| FitsError::new(KEY_NO_EXIST))?;
801        parse_value_comment(card.as_str().unwrap_or(""))
802    }
803
804    /// Units from `[...]` in the comment (`fits_read_key_unit`).
805    pub fn get_unit(&self, name: &str) -> Result<String> {
806        let (_, comm) = self.raw_value_comment(name)?;
807        if let Some(rest) = comm.strip_prefix('[') {
808            if let Some(end) = rest.find(']') {
809                return Ok(rest[..end].to_string());
810            }
811        }
812        Ok(String::new())
813    }
814
815    /// Prepend `[unit] ` to the comment (`fits_write_key_unit`).
816    pub fn set_unit(&mut self, name: &str, unit: &str) -> Result<()> {
817        let card = *self
818            .card_by_name(name)
819            .ok_or_else(|| FitsError::new(KEY_NO_EXIST))?;
820        let text = card.as_str().unwrap_or("");
821        let (val, oldcomm) = parse_value_comment(text)?;
822        let rest = if let Some(stripped) = oldcomm.strip_prefix('[') {
823            if let Some(idx) = stripped.find(']') {
824                stripped[idx + 1..].trim_start().to_string()
825            } else {
826                oldcomm
827            }
828        } else {
829            oldcomm
830        };
831        let newcomm = if unit.is_empty() {
832            rest
833        } else {
834            let mut c = format!("[{unit}] ");
835            c.push_str(&rest);
836            c
837        };
838        let s = make_card_string(name, &val, Some(&newcomm))?;
839        self.replace_name(name, Card::from_text(&s))?;
840        Ok(())
841    }
842
843    /// Update: replace if present, otherwise append (`fits_update_key`).
844    pub fn update_with(&mut self, name: &str, value: &str, comm: Option<&str>) -> Result<()> {
845        let s = make_card_string(name, value, comm)?;
846        let card = Card::from_text(&s);
847        if self.card_by_name(name).is_some() {
848            self.replace_name(name, card)
849        } else {
850            self.cards.push(card);
851            Ok(())
852        }
853    }
854
855    /// Modify an existing keyword; error if missing (`fits_modify_key`).
856    pub fn modify_with(&mut self, name: &str, value: &str, comm: Option<&str>) -> Result<()> {
857        let s = make_card_string(name, value, comm)?;
858        self.replace_name(name, Card::from_text(&s))
859    }
860
861    /// Insert `card` at 1-based `pos` (before that record). `pos > nkeys`
862    /// appends.
863    pub fn insert_record_at(&mut self, pos: usize, card: Card) -> Result<()> {
864        let idx = pos.saturating_sub(1);
865        if idx >= self.cards.len() {
866            self.cards.push(card);
867        } else {
868            self.cards.insert(idx, card);
869        }
870        Ok(())
871    }
872
873    /// Delete first keyword with this name (`fits_delete_key`).
874    pub fn delete_key(&mut self, name: &str) -> Result<()> {
875        let key = name8(name);
876        let idx = self
877            .cards
878            .iter()
879            .position(|c| name8_bytes(&c.as_bytes()[..8]) == key)
880            .ok_or_else(|| FitsError::new(KEY_NO_EXIST))?;
881        self.cards.remove(idx);
882        Ok(())
883    }
884
885    /// Delete 1-based record (`fits_delete_record`).
886    pub fn delete_record(&mut self, n: usize) -> Result<()> {
887        let idx = n.wrapping_sub(1);
888        if idx >= self.cards.len() {
889            return Err(FitsError::new(KEY_OUT_BOUNDS));
890        }
891        self.cards.remove(idx);
892        Ok(())
893    }
894
895    /// Replace first matching name.
896    pub fn replace_name(&mut self, name: &str, card: Card) -> Result<()> {
897        let key = name8(name);
898        let idx = self
899            .cards
900            .iter()
901            .position(|c| name8_bytes(&c.as_bytes()[..8]) == key)
902            .ok_or_else(|| FitsError::new(KEY_NO_EXIST))?;
903        self.cards[idx] = card;
904        Ok(())
905    }
906
907    /// Write DATE with the given timestamp value (`fits_write_date` body).
908    pub fn write_date_value(&mut self, datetime: &str) -> Result<()> {
909        let comm = "file creation date (YYYY-MM-DDThh:mm:ss UT)";
910        let v = format_string_value(datetime);
911        self.update_with("DATE", &v, Some(comm))
912    }
913
914    /// `fits_write_keys_lng`: KEY1, KEY2, ... from `start`.
915    pub fn write_keys_long(
916        &mut self,
917        root: &str,
918        start: i32,
919        values: &[i64],
920        comms: &[Option<&str>],
921    ) -> Result<()> {
922        for (i, val) in values.iter().enumerate() {
923            let name = format!("{root}{}", start as usize + i);
924            let comm = comms.get(i).copied().flatten();
925            self.write_long(&name, *val, comm)?;
926        }
927        Ok(())
928    }
929
930    /// Read KEY{start}.. as integers. Returns how many were found.
931    pub fn get_keys_long(&self, root: &str, start: i32, nmax: usize) -> (Vec<i64>, usize) {
932        let mut out = Vec::new();
933        for i in 0..nmax {
934            let name = format!("{root}{}", start as usize + i);
935            match self.get_i64(&name) {
936                Ok(v) => out.push(v),
937                Err(_) => break,
938            }
939        }
940        let n = out.len();
941        (out, n)
942    }
943
944    /// Primary-array required keywords (`fits_read_imghdr` / `ffghpr`).
945    pub fn primary_info(&self) -> Result<PrimaryInfo> {
946        let simple = self.get_logical("SIMPLE").map(|(v, _)| v).unwrap_or(true);
947        let bitpix = self.bitpix()?;
948        let naxes = self.naxes()?;
949        let naxis = naxes.len() as i32;
950        let pcount = self.get_i64("PCOUNT").unwrap_or(0);
951        let gcount = self.get_i64("GCOUNT").unwrap_or(1);
952        let extend = self.get_logical("EXTEND").map(|(v, _)| v).unwrap_or(false);
953        Ok(PrimaryInfo {
954            simple,
955            bitpix,
956            naxis,
957            naxes,
958            pcount,
959            gcount,
960            extend,
961        })
962    }
963
964    /// Infer [`ImageType`] from BITPIX + BZERO.
965    pub fn image_type(&self) -> Result<ImageType> {
966        let bp = self.bitpix()?;
967        let z = self.bzero();
968        Ok(match bp {
969            8 if (z + 128.0).abs() < 0.5 => ImageType::I8,
970            8 => ImageType::U8,
971            16 if (z - 32768.0).abs() < 0.5 => ImageType::U16,
972            16 => ImageType::I16,
973            32 if (z - 2_147_483_648.0).abs() < 0.5 => ImageType::U32,
974            32 => ImageType::I32,
975            64 if z > 1e18 => ImageType::U64,
976            64 => ImageType::I64,
977            -32 => ImageType::F32,
978            -64 => ImageType::F64,
979            _ => return Err(FitsError::new(BAD_BITPIX)),
980        })
981    }
982
983    /// Serialize cards + END + space fill to a multiple of 2880 bytes.
984    #[must_use]
985    pub fn to_record_bytes(&self) -> Vec<u8> {
986        self.to_record_bytes_with_morekeys(0)
987    }
988
989    /// Like [`Self::to_record_bytes`], reserving `morekeys` extra 80-byte slots
990    /// after `END` (`fits_write_hdu_space` / `ffhdef`).
991    #[must_use]
992    pub fn to_record_bytes_with_morekeys(&self, morekeys: i32) -> Vec<u8> {
993        let mut out = Vec::with_capacity(RECORD_LEN);
994        for card in &self.cards {
995            out.extend_from_slice(card.as_bytes());
996        }
997        out.extend_from_slice(end_card().as_bytes());
998        let extra = morekeys.max(0) as usize * CARD_LEN;
999        let min_len = out.len() + extra;
1000        let padded = min_len.div_ceil(RECORD_LEN).max(1) * RECORD_LEN;
1001        out.resize(padded, b' ');
1002        out
1003    }
1004
1005    /// Remaining keyword slots in an on-disk header of `header_len` bytes
1006    /// (`ffghsp` `nmore`, not counting `END`).
1007    #[must_use]
1008    pub fn nmore_in(&self, header_len: u64) -> i32 {
1009        let nmore = (header_len / CARD_LEN as u64) as i32 - self.cards.len() as i32 - 1;
1010        nmore.max(0)
1011    }
1012
1013    /// Convert a primary-array header into an IMAGE extension (`ffcphd`).
1014    pub fn primary_as_image_extension(&self) -> Result<Self> {
1015        let naxis = self.get_i64("NAXIS").unwrap_or(0).max(0) as usize;
1016        let mut out = Self::new();
1017        out.write_string("XTENSION", "IMAGE", Some(COMM_XTENSION_IMAGE))?;
1018        let start = 1.min(self.cards.len());
1019        let struct_end = (3 + naxis).min(self.cards.len());
1020        if start < struct_end {
1021            for card in &self.cards[start..struct_end] {
1022                out.cards.push(*card);
1023            }
1024        }
1025        out.write_long("PCOUNT", 0, Some(COMM_PCOUNT_GROUP))?;
1026        out.write_long("GCOUNT", 1, Some(COMM_GCOUNT_GROUP))?;
1027        for card in &self.cards[struct_end..] {
1028            if card_name_is(card, "EXTEND") || is_std_fits_comment(card) {
1029                continue;
1030            }
1031            out.cards.push(*card);
1032        }
1033        Ok(out)
1034    }
1035
1036    /// Convert an IMAGE extension header into a primary array (`ffcphd`).
1037    pub fn image_extension_as_primary(&self) -> Result<Self> {
1038        let naxis = self.get_i64("NAXIS").unwrap_or(0).max(0) as usize;
1039        let mut out = Self::new();
1040        out.write_logical("SIMPLE", true, Some(COMM_SIMPLE))?;
1041        let struct_end = (3 + naxis).min(self.cards.len());
1042        let start = 1.min(self.cards.len());
1043        for card in &self.cards[start..struct_end] {
1044            out.cards.push(*card);
1045        }
1046        out.write_logical("EXTEND", true, Some(COMM_EXTEND))?;
1047        out.push(Card::from_text(COMMENT_FITS_1));
1048        out.push(Card::from_text(COMMENT_FITS_2));
1049        for card in &self.cards[struct_end..] {
1050            if card_name_is(card, "PCOUNT") || card_name_is(card, "GCOUNT") {
1051                continue;
1052            }
1053            out.cards.push(*card);
1054        }
1055        Ok(out)
1056    }
1057
1058    /// Parse a header from the start of a FITS file image.
1059    ///
1060    /// Reads 80-byte cards until END. Returns the header and the byte
1061    /// offset of the following data unit (a multiple of 2880).
1062    pub fn parse(bytes: &[u8]) -> Result<(Self, u64)> {
1063        if bytes.len() < CARD_LEN {
1064            return Err(FitsError::new(NO_END));
1065        }
1066        let mut cards = Vec::new();
1067        let mut off = 0usize;
1068        loop {
1069            if off + CARD_LEN > bytes.len() {
1070                return Err(FitsError::new(NO_END));
1071            }
1072            let slice = &bytes[off..off + CARD_LEN];
1073            off += CARD_LEN;
1074            if is_end_card(slice) {
1075                break;
1076            }
1077            let mut card_bytes = [b' '; CARD_LEN];
1078            card_bytes.copy_from_slice(slice);
1079            cards.push(Card::from_text(
1080                std::str::from_utf8(&card_bytes).map_err(|_| FitsError::new(BAD_KEYCHAR))?,
1081            ));
1082        }
1083        let recs = off.div_ceil(RECORD_LEN).max(1);
1084        let data_start = (recs * RECORD_LEN) as u64;
1085        Ok((Self { cards }, data_start))
1086    }
1087}
1088
1089fn end_card() -> Card {
1090    Card::from_text("END")
1091}
1092
1093fn card_name_is(card: &Card, name: &str) -> bool {
1094    name8_bytes(&card.as_bytes()[..8]) == name8(name)
1095}
1096
1097fn is_std_fits_comment(card: &Card) -> bool {
1098    let s = card.as_str().unwrap_or("");
1099    s.starts_with("COMMENT   FITS (Flexible Image Transport System) format is")
1100        || s.starts_with("COMMENT   and Astrophysics', volume 376, page 3")
1101}
1102
1103fn is_end_card(bytes: &[u8]) -> bool {
1104    bytes.len() >= 8 && bytes.starts_with(b"END") && bytes[3..8].iter().all(|&b| b == b' ')
1105}
1106
1107fn write_unsigned_scaling(h: &mut Header, ty: ImageType) -> Result<()> {
1108    match ty {
1109        ImageType::U16 => {
1110            h.write_fixed_double("BZERO", 32768.0, 0, Some(COMM_BZERO_USHORT))?;
1111            h.write_fixed_double("BSCALE", 1.0, 0, Some(COMM_BSCALE))?;
1112        }
1113        ImageType::U32 => {
1114            h.write_fixed_double("BZERO", 2_147_483_648.0, 0, Some(COMM_BZERO_ULONG))?;
1115            h.write_fixed_double("BSCALE", 1.0, 0, Some(COMM_BSCALE))?;
1116        }
1117        ImageType::U64 => {
1118            h.push(Card::from_text(BZERO_ULONGLONG_CARD));
1119            h.write_fixed_double("BSCALE", 1.0, 0, Some(COMM_BSCALE))?;
1120        }
1121        ImageType::I8 => {
1122            h.write_fixed_double("BZERO", -128.0, 0, Some(COMM_BZERO_SBYTE))?;
1123            h.write_fixed_double("BSCALE", 1.0, 0, Some(COMM_BSCALE))?;
1124        }
1125        _ => {}
1126    }
1127    Ok(())
1128}
1129
1130fn name8(name: &str) -> [u8; 8] {
1131    name8_bytes(name.as_bytes())
1132}
1133
1134/// Parse a `Txxxn` / `TDIMn` name. Returns `(prefix_len, index)`.
1135fn tkey_index(bytes: &[u8; 80]) -> Option<(usize, i32)> {
1136    let rec = bytes;
1137    let q = &rec[1..5];
1138    let i1 = if q == b"BCOL"
1139        || q == b"FORM"
1140        || q == b"TYPE"
1141        || q == b"SCAL"
1142        || q == b"UNIT"
1143        || q == b"NULL"
1144        || q == b"ZERO"
1145        || q == b"DISP"
1146        || q == b"LMIN"
1147        || q == b"LMAX"
1148        || q == b"DMIN"
1149        || q == b"DMAX"
1150        || q == b"CTYP"
1151        || q == b"CRPX"
1152        || q == b"CRVL"
1153        || q == b"CDLT"
1154        || q == b"CROT"
1155        || q == b"CUNI"
1156    {
1157        5usize
1158    } else if rec.starts_with(b"TDIM") {
1159        4usize
1160    } else {
1161        return None;
1162    };
1163    let mut suffix = String::new();
1164    for &b in rec[i1..8].iter() {
1165        if b == b' ' {
1166            break;
1167        }
1168        suffix.push(b as char);
1169    }
1170    let ivalue = suffix.parse::<i32>().ok()?;
1171    Some((i1, ivalue))
1172}
1173
1174fn name8_bytes(bytes: &[u8]) -> [u8; 8] {
1175    let mut n = [b' '; 8];
1176    let len = bytes.len().min(8);
1177    n[..len].copy_from_slice(&bytes[..len]);
1178    for b in &mut n {
1179        *b = b.to_ascii_uppercase();
1180    }
1181    n
1182}