nom.tam.fits.Header Maven / Gradle / Ivy
Go to download
Show more of this group Show more artifacts with this name
Show all versions of nom-tam-fits Show documentation
Show all versions of nom-tam-fits Show documentation
Java library for reading and writing FITS files. FITS, the Flexible Image Transport System, is the format commonly used in the archiving and transport of astronomical data.
package nom.tam.fits;
import java.io.EOFException;
import java.io.IOException;
import java.io.PrintStream;
import java.math.BigDecimal;
import java.math.BigInteger;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.Comparator;
import java.util.HashSet;
import java.util.List;
import java.util.Set;
import java.util.logging.Level;
import java.util.logging.Logger;
import nom.tam.fits.FitsFactory.FitsSettings;
import nom.tam.fits.header.Bitpix;
import nom.tam.fits.header.Checksum;
import nom.tam.fits.header.IFitsHeader;
import nom.tam.fits.header.IFitsHeader.VALUE;
import nom.tam.fits.header.Standard;
import nom.tam.fits.utilities.FitsCheckSum;
import nom.tam.util.ArrayDataInput;
import nom.tam.util.ArrayDataOutput;
import nom.tam.util.AsciiFuncs;
import nom.tam.util.ComplexValue;
import nom.tam.util.Cursor;
import nom.tam.util.FitsIO;
import nom.tam.util.FitsInputStream;
import nom.tam.util.FitsOutput;
import nom.tam.util.HashedList;
import nom.tam.util.RandomAccess;
/*
* #%L
* nom.tam FITS library
* %%
* Copyright (C) 2004 - 2024 nom-tam-fits
* %%
* This is free and unencumbered software released into the public domain.
*
* Anyone is free to copy, modify, publish, use, compile, sell, or
* distribute this software, either in source code form or as a compiled
* binary, for any purpose, commercial or non-commercial, and by any
* means.
*
* In jurisdictions that recognize copyright laws, the author or authors
* of this software dedicate any and all copyright interest in the
* software to the public domain. We make this dedication for the benefit
* of the public at large and to the detriment of our heirs and
* successors. We intend this dedication to be an overt act of
* relinquishment in perpetuity of all present and future rights to this
* software under copyright law.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
* EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
* MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
* IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR
* OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
* ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
* OTHER DEALINGS IN THE SOFTWARE.
* #L%
*/
import static nom.tam.fits.header.Standard.BITPIX;
import static nom.tam.fits.header.Standard.BLANKS;
import static nom.tam.fits.header.Standard.COMMENT;
import static nom.tam.fits.header.Standard.END;
import static nom.tam.fits.header.Standard.EXTEND;
import static nom.tam.fits.header.Standard.GCOUNT;
import static nom.tam.fits.header.Standard.GROUPS;
import static nom.tam.fits.header.Standard.HISTORY;
import static nom.tam.fits.header.Standard.NAXIS;
import static nom.tam.fits.header.Standard.NAXISn;
import static nom.tam.fits.header.Standard.PCOUNT;
import static nom.tam.fits.header.Standard.SIMPLE;
import static nom.tam.fits.header.Standard.TFIELDS;
import static nom.tam.fits.header.Standard.XTENSION;
import static nom.tam.fits.header.Standard.XTENSION_BINTABLE;
import static nom.tam.fits.header.extra.CXCExt.LONGSTRN;
/**
*
* Access and manipulate the header of a HDU. FITS headers serve more than a single purpose:
*
*
* - provide an essential description of the type, size, and layout of the HDUs data segment
* - describe the data as completely as possible via standardized (or conventional) keywords
* - provide storage for additional user-specific key / value pairs
* - allow for comments to aid human readability
*
*
* First and foremost headers provide a description of the data object that follows the header in the HDU. Some of that
* description is essential and critical to the integrity of the FITS file, such as the header keywords that describe
* the type, size, and layout of the data segment. This library will automatically populate the header with appropriate
* information using the mandatory keywords (such as SIMPLE or XTENSION, BITPIX,
* NAXIS, NAXISn, PCOUNT, GCOUNT keywords, as well as
* essential table column format descriptions). Users of the library should avoid overwriting these mandatory keywords
* manually, since they may corrupt the FITS file, rendering it unreadable.
*
*
* Beyond the keywords that describe the type, shape, and size of data, the library will not add further information to
* the header. The users of the library are responsible to complete the header description as necessary. This includes
* non-enssential data descriptions (such as EXTNAME, BUNIT, OBSERVER, or
* optional table column descriptors TTYPEn, TUNITn, coordinate systems via the
* appropriate WCS keywords, or checksums). Users of the library are responsible for completing the data description
* using whatever standard or conventional keywords are available and appropriate. Please refer to the
* FITS Standard documentation to see what typical
* descriptions of data you might want to use.
*
*
* Last but not least, the header is also a place where FITS creators can store (nearly) arbitrary key/value pairs. In
* earlier versions of the FITS standard, header keywords were restricted to max. 8 upper case letters and numbers (plus
* hyphen and underscore), and no more than 70 character value fields. However, as of FITS 4.0 (and even before as a
* registered convention), string values of arbitrary length may be stored using the OGIP 1.0 long string convention,
* while the ESO HIERARCH convention allows
* keywords with more than 8 characters and hierarchical keywords. Support, conformance, and compliance to these
* conventions can be toggled by static settings in {@link FitsFactory} to user preference.
*
*
* As of version 1.16, we also support reserving space in headers for future additions using the
* {@link #ensureCardSpace(int)} method, also part of the FITS 4.0 standard. It allows users to finish populating
* headers after data that follows the header is already written -- a useful feature for recording data from
* streaming sources.
*
*/
@SuppressWarnings("deprecation")
public class Header implements FitsElement {
/**
* The default character position to which comments should be aligned if possible (zero-based). The fITS standard
* requires that 'fixed-format' values are right-justified to byte 30 (index 29 in Java), and recommends a space
* after that before the comment. As such, comments should normally start at byte 30 (counted from 0). (We will add
* a space at that position before the '/' indicating the comment start)
*/
public static final int DEFAULT_COMMENT_ALIGN = 30;
/**
* The earliest position (zero-based) at which a comment may start for a regular key/value entry.
*
* @deprecated We will disable changing alignment in the future because it may violate the standard for
* 'fixed-format' header entries, and result in files that are unreadable by some other software.
* This constant will be obsoleted and removed.
*/
public static final int MIN_COMMENT_ALIGN = 20;
/**
* The largest (zero-based) comment alignment allowed that can still contain some meaningful comment (word)
*
* @deprecated We will disable changing alignment in the future because it may violate the standard for
* 'fixed-format' header entries, and result in files that are unreadable by some other software.
* This constant will be obsoleted and removed.
*/
public static final int MAX_COMMENT_ALIGN = 70;
/**
* The alignment position of card comments for a more pleasing visual experience. Comments will be aligned to this
* position, provided the lengths of all fields allow for it.
*/
private static int commentAlign = DEFAULT_COMMENT_ALIGN;
private static final Logger LOG = Logger.getLogger(Header.class.getName());
private static final int MIN_NUMBER_OF_CARDS_FOR_VALID_HEADER = 4;
/**
* The actual header data stored as a HashedList of HeaderCard's.
*/
private final HashedList cards;
/** Offset of this Header in the FITS file */
private long fileOffset;
private List duplicates;
private HashSet dupKeys;
/** Input descriptor last time header was read */
private ArrayDataInput input;
/**
* The mimimum number of cards to write, including blank header space as described in the FITS 4.0 standard.
*/
private int minCards;
/**
* The number of bytes that this header occupied in file. (for re-writing).
*/
private long readSize;
/** The checksum calculated from the input stream */
private long streamSum = -1L;
/**
* the sorter used to sort the header cards defore writing the header.
*/
private Comparator headerSorter;
private BasicHDU owner;
private boolean validating = false;
/**
* Keyword checking mode when adding standardized keywords via the {@link IFitsHeader} interface.
*
* @author Attila Kovacs
*
* @since 1.19
*/
public enum KeywordCheck {
/** No keyword checking will be performed. */
NONE,
/** Check only that the keyword is appropriate for the type of data contained in the associated HDU */
DATA_TYPE,
/**
* Strict checking, will refuse to set mandatory FITS keywords -- which should normally be set by the library
* alone.
*/
STRICT
}
/**
* The keyword checking mode used by the library until the user changes it it.
*
* @since 1.19
*/
public static final KeywordCheck DEFAULT_KEYWORD_CHECK_POLICY = KeywordCheck.DATA_TYPE;
private static KeywordCheck defaultKeyCheck = DEFAULT_KEYWORD_CHECK_POLICY;
private KeywordCheck keyCheck = defaultKeyCheck;
/**
* Create a header by reading the information from the input stream.
*
* @param dis The input stream to read the data from.
*
* @return null if there was a problem with the header; otherwise return the
* header read from the input stream.
*
* @throws TruncatedFileException if the stream ended prematurely
* @throws IOException if the header could not be read.
*/
public static Header readHeader(ArrayDataInput dis) throws TruncatedFileException, IOException {
Header myHeader = new Header();
try {
myHeader.read(dis);
} catch (EOFException e) {
// An EOF exception is thrown only if the EOF was detected
// when reading the first card. In this case we want
// to return a null.
return null;
}
return myHeader;
}
/**
* please use {@link FitsFactory#setLongStringsEnabled(boolean)} instead.
*
* @param flag the new value for long-string enabling.
*/
@Deprecated
public static void setLongStringsEnabled(boolean flag) {
FitsFactory.setLongStringsEnabled(flag);
}
/** Create a new header with the required default keywords for a standalone header. */
public Header() {
cards = new HashedList<>();
headerSorter = new HeaderOrder();
duplicates = null;
clear();
}
/**
* Create a header and populate it from the input stream
*
* @param is The input stream where header information is expected.
*
* @throws IOException if the header could not be read.
* @throws TruncatedFileException if the stream ended prematurely
*/
public Header(ArrayDataInput is) throws TruncatedFileException, IOException {
this();
read(is);
}
/**
* Create a header which points to the given data object.
*
* @param o The data object to be described.
*
* @throws FitsException if the data was not valid for this header.
*/
public Header(Data o) throws FitsException {
this();
o.fillHeader(this);
}
/**
* Create a header and initialize it with a vector of strings.
*
* @param newCards Card images to be placed in the header.
*/
public Header(String[] newCards) {
this();
for (String newCard : newCards) {
cards.add(HeaderCard.create(newCard));
}
}
void assignTo(BasicHDU hdu) {
// if (owner != null) {
// throw new IllegalStateException("This header was already assigned to a HDU");
// }
this.owner = hdu;
}
/**
*
* Reserves header card space for populating at a later time. When written to a stream, the header will be large
* enough to hold at least the specified number of cards. If the header has fewer physical cards then the remaining
* space will be padded with blanks, leaving space for future additions, as specified by the FITS 4.0 standard for
* preallocated header space.
*
*
* This method is also called by {@link #read(ArrayDataInput)}, with the number of cards (including reserved blank
* space) contained in the header input stream, in order to ensure that the header remains rewritable even if it is
* shortened by the removal of cards (explicitly, or because they were duplicates).
*
*
* A new setting always overrides prior ones. For example, calling this method with an argument that is %lt;=1 will
* eliminate (reset) any prior preallocated header space.
*
*
* @param nCards the mimimum number of 80-character header records that is header must be able to support when
* written to a stream, including preallocated blank header space.
*
* @since 1.16
*
* @see #getMinimumSize()
* @see #write(ArrayDataOutput)
* @see #read(ArrayDataInput)
* @see #resetOriginalSize()
*/
public void ensureCardSpace(int nCards) {
if (nCards < 1) {
nCards = 1;
}
minCards = nCards;
}
/**
* Merges copies of all cards from another header, provided they are not readily present in this header. That is, it
* merges only the non-conflicting or distinct header entries from the designated source (in contrast to
* {@link #updateLines(Header)}). All comment cards are merged also (since these can always appear multiple times,
* so they do not conflict). The merged entries are added at the end of the header, in the same order as they appear
* in the source. The merged entries will be copies of the cards in the original, such that subsequent modifications
* to the source will not affect this header or vice versa.
*
* @param source The header from which to inherit non-conflicting entries
*
* @since 1.19
*
* @see #updateLines(Header)
*/
public void mergeDistinct(Header source) {
seekTail();
Cursor c = source.iterator();
while (c.hasNext()) {
HeaderCard card = c.next();
if (card.isCommentStyleCard() || !containsKey(card.getKey())) {
if (card.getKey().equals(Standard.SIMPLE.key()) || card.getKey().equals(Standard.XTENSION.key())) {
// Do not merge SIMPLE / XTENSION -- these are private matters...
continue;
}
addLine(card.copy());
}
}
}
/**
* Insert a new header card at the current position, deleting any prior occurence of the same card while maintaining
* the current position to point to after the newly inserted card.
*
* @param fcard The card to be inserted.
*
* @throws IllegalArgumentException if the current keyword checking mode does not allow the headercard with its
* standard keyword in the header.
*
* @see #setKeywordChecking(KeywordCheck)
*/
public void addLine(HeaderCard fcard) throws IllegalArgumentException {
if (fcard == null) {
return;
}
if (fcard.getStandardKey() != null) {
checkKeyword(fcard.getStandardKey());
}
cursor().add(fcard);
}
/**
*
* Sets the built-in standard keyword checking mode. When populating the header using {@link IFitsHeader} keywords
* the library will check if the given keyword is appropriate for the type of HDU that the header represents, and
* will throw an {@link IllegalArgumentException} if the specified keyword is not allowed for that type of HDU.
*
*
* This method changes the keyword checking mode for this header instance only. If you want to change the mode for
* all newly created headers globally, use {@link #setDefaultKeywordChecking(KeywordCheck)} instead.
*
*
* @param mode The keyword checking mode to use.
*
* @see #getKeywordChecking()
* @see HeaderCard#setValueCheckingPolicy(nom.tam.fits.HeaderCard.ValueCheck)
*
* @since 1.19
*/
public void setKeywordChecking(KeywordCheck mode) {
keyCheck = mode;
}
/**
* Sets the default mode of built-in standard keyword checking mode for new headers. When populating the header
* using {@link IFitsHeader} keywords the library will check if the given keyword is appropriate for the type of HDU
* that the header represents, and will throw an {@link IllegalArgumentException} if the specified keyword is not
* allowed for that type of HDU.
*
* @param mode The keyword checking policy to use.
*
* @see #setKeywordChecking(KeywordCheck)
* @see #getKeywordChecking()
* @see HeaderCard#setValueCheckingPolicy(nom.tam.fits.HeaderCard.ValueCheck)
*
* @since 1.19
*/
public static void setDefaultKeywordChecking(KeywordCheck mode) {
defaultKeyCheck = mode;
}
/**
* Returns the current keyword checking mode.
*
* @return the current keyword checking mode
*
* @see #setKeywordChecking(KeywordCheck)
*
* @since 1.19
*/
public final KeywordCheck getKeywordChecking() {
return keyCheck;
}
private void checkKeyword(IFitsHeader keyword) throws IllegalArgumentException {
if (keyCheck == KeywordCheck.NONE || owner == null) {
return;
}
if (keyCheck == KeywordCheck.STRICT
&& (keyword.status() == IFitsHeader.SOURCE.MANDATORY || keyword.status() == IFitsHeader.SOURCE.INTEGRAL)) {
throw new IllegalArgumentException("Keyword " + keyword + " should be set by the library only");
}
switch (keyword.hdu()) {
case PRIMARY:
if (!owner.canBePrimary()) {
throw new IllegalArgumentException(
"Keyword " + keyword + " is a primary keyword and may not be used in extensions");
}
return;
case EXTENSION:
if (owner instanceof RandomGroupsHDU) {
throw new IllegalArgumentException(
"Keyword " + keyword + " is an extension keyword but random groups may only be primary");
}
return;
case IMAGE:
if (owner instanceof ImageHDU || owner instanceof RandomGroupsHDU) {
return;
}
break;
case GROUPS:
if (owner instanceof RandomGroupsHDU) {
return;
}
break;
case TABLE:
if (owner instanceof TableHDU) {
return;
}
break;
case ASCII_TABLE:
if (owner instanceof AsciiTableHDU) {
return;
}
break;
case BINTABLE:
if (owner instanceof BinaryTableHDU) {
return;
}
break;
default:
return;
}
throw new IllegalArgumentException(
"Keyword " + keyword.key() + " is not appropriate for " + owner.getClass().getName());
}
/**
* Add or replace a key with the given boolean value and its standardized comment. If the value is not compatible
* with the convention of the keyword, a warning message is logged but no exception is thrown (at this point). The
* new card will be placed at the current mark position, as set e.g. by {@link #findCard(IFitsHeader)}.
*
* @param key The header key.
* @param val The boolean value.
*
* @return the new card that was added.
*
* @throws HeaderCardException If the parameters cannot build a valid FITS card.
* @throws IllegalArgumentException If the keyword is invalid
*
* @see #addValue(String, Boolean, String)
*/
public HeaderCard addValue(IFitsHeader key, Boolean val) throws HeaderCardException, IllegalArgumentException {
HeaderCard card = HeaderCard.create(key, val);
addLine(card);
return card;
}
/**
* Add or replace a key with the given double value and its standardized comment. If the value is not compatible
* with the convention of the keyword, a warning message is logged but no exception is thrown (at this point). The
* new card will be placed at the current mark position, as set e.g. by {@link #findCard(IFitsHeader)}.
*
* @param key The header key.
* @param val The double value.
*
* @return the new card that was added.
*
* @throws HeaderCardException If the parameters cannot build a valid FITS card.
* @throws IllegalArgumentException If the keyword is invalid
*
* @see #addValue(String, Number, String)
*/
public HeaderCard addValue(IFitsHeader key, Number val) throws HeaderCardException, IllegalArgumentException {
HeaderCard card = HeaderCard.create(key, val);
addLine(card);
return card;
}
/**
* Add or replace a key with the given string value and its standardized comment. If the value is not compatible
* with the convention of the keyword, a warning message is logged but no exception is thrown (at this point). The
* new card will be placed at the current mark position, as set e.g. by {@link #findCard(IFitsHeader)}.
*
* @param key The header key.
* @param val The string value.
*
* @return the new card that was added.
*
* @throws HeaderCardException If the parameters cannot build a valid FITS card.
* @throws IllegalArgumentException If the keyword is invalid
*
* @see #addValue(String, String, String)
*/
public HeaderCard addValue(IFitsHeader key, String val) throws HeaderCardException, IllegalArgumentException {
HeaderCard card = HeaderCard.create(key, val);
addLine(card);
return card;
}
/**
* Add or replace a key with the given complex value and its standardized comment. If the value is not compatible
* with the convention of the keyword, a warning message is logged but no exception is thrown (at this point). The
* new card will be placed at the current mark position, as set e.g. by {@link #findCard(IFitsHeader)}.
*
* @param key The header key.
* @param val The complex value.
*
* @return the new card that was added.
*
* @throws HeaderCardException If the parameters cannot build a valid FITS card.
* @throws IllegalArgumentException If the keyword is invalid
*
* @see #addValue(String, ComplexValue, String)
*
* @since 1.17
*/
public HeaderCard addValue(IFitsHeader key, ComplexValue val) throws HeaderCardException, IllegalArgumentException {
HeaderCard card = HeaderCard.create(key, val);
addLine(card);
return card;
}
/**
* Add or replace a key with the given boolean value and comment. The new card will be placed at the current mark
* position, as set e.g. by {@link #findCard(String)}.
*
* @param key The header key.
* @param val The boolean value.
* @param comment A comment to append to the card.
*
* @return the new card that was added.
*
* @throws HeaderCardException If the parameters cannot build a valid FITS card.
*
* @see #addValue(IFitsHeader, Boolean)
* @see HeaderCard#HeaderCard(String, Boolean, String)
*/
public HeaderCard addValue(String key, Boolean val, String comment) throws HeaderCardException {
HeaderCard hc = new HeaderCard(key, val, comment);
addLine(hc);
return hc;
}
/**
* Add or replace a key with the given number value and comment. The value will be represented in the header card
* with use the native precision of the value or at least {@link nom.tam.util.FlexFormat#DOUBLE_DECIMALS}, whichever
* fits in the available card space. Trailing zeroes will be ommitted. The new card will be placed at the current
* mark position, as set e.g. by {@link #findCard(String)}.
*
* @param key The header key.
* @param val The number value.
* @param comment A comment to append to the card.
*
* @return the new card that was added.
*
* @throws HeaderCardException If the parameters cannot build a valid FITS card.
*
* @see #addValue(String, Number, int, String)
* @see #addValue(IFitsHeader, Number)
* @see HeaderCard#HeaderCard(String, Number, String)
*/
public HeaderCard addValue(String key, Number val, String comment) throws HeaderCardException {
HeaderCard hc = new HeaderCard(key, val, comment);
addLine(hc);
return hc;
}
/**
* Add or replace a key with the given number value and comment, using up to the specified decimal places after the
* leading figure. Trailing zeroes will be ommitted. The new card will be placed at the current mark position, as
* set e.g. by {@link #findCard(String)}.
*
* @param key The header key.
* @param val The number value.
* @param decimals The number of decimal places to show after the leading figure, or
* {@link nom.tam.util.FlexFormat#AUTO_PRECISION} to use the native precision of the
* value or at least {@link nom.tam.util.FlexFormat#DOUBLE_DECIMALS}, whichever fits
* in the available card space.
* @param comment A comment to append to the card.
*
* @return the new card that was added.
*
* @throws HeaderCardException If the parameters cannot build a valid FITS card.
*
* @see #addValue(String, Number, String)
* @see HeaderCard#HeaderCard(String, Number, int, String)
*/
public HeaderCard addValue(String key, Number val, int decimals, String comment) throws HeaderCardException {
HeaderCard hc = new HeaderCard(key, val, decimals, comment);
addLine(hc);
return hc;
}
/**
* Add or replace a key with the given complex number value and comment. Trailing zeroes will be ommitted. The new
* card will be placed at the current mark position, as set e.g. by {@link #findCard(String)}.
*
* @param key The header keyword.
* @param val The complex number value.
* @param comment A comment to append to the card.
*
* @return the new card that was added.
*
* @throws HeaderCardException If the parameters cannot build a valid FITS card.
*
* @since 1.16
*
* @see #addValue(String, ComplexValue, int, String)
* @see HeaderCard#HeaderCard(String, ComplexValue, String)
*/
public HeaderCard addValue(String key, ComplexValue val, String comment) throws HeaderCardException {
HeaderCard hc = new HeaderCard(key, val, comment);
addLine(hc);
return hc;
}
/**
* Add or replace a key with the given complex number value and comment, using up to the specified decimal places
* after the leading figure. Trailing zeroes will be ommitted. The new card will be placed at the current mark
* position, as set e.g. by {@link #findCard(String)}.
*
* @param key The header keyword.
* @param val The complex number value.
* @param decimals The number of decimal places to show after the leading figure, or
* {@link nom.tam.util.FlexFormat#AUTO_PRECISION} to use the native precision of the
* value, or at least {@link nom.tam.util.FlexFormat#DOUBLE_DECIMALS}, whichever
* fits in the available card space.
* @param comment A comment to append to the card.
*
* @return the new card that was added.
*
* @throws HeaderCardException If the parameters cannot build a valid FITS card.
*
* @since 1.16
*
* @see #addValue(String, ComplexValue, String)
* @see HeaderCard#HeaderCard(String, ComplexValue, int, String)
*/
public HeaderCard addValue(String key, ComplexValue val, int decimals, String comment) throws HeaderCardException {
HeaderCard hc = new HeaderCard(key, val, decimals, comment);
addLine(hc);
return hc;
}
/**
* @deprecated Not supported by the FITS standard, so do not use. It was included due to a
* misreading of the standard itself. We will remove this method in the future.
*
* @param key The header key.
* @param val The integer value.
* @param comment A comment to append to the card.
*
* @return the new card that was added.
*
* @throws HeaderCardException If the parameters cannot build a valid FITS card.
*
* @since 1.16
*
* @see #addValue(String, Number, String)
* @see HeaderCard#createHexValueCard(String, long)
* @see #getHexValue(String)
*/
@Deprecated
public HeaderCard addHexValue(String key, long val, String comment) throws HeaderCardException {
HeaderCard hc = HeaderCard.createHexValueCard(key, val, comment);
addLine(hc);
return hc;
}
/**
* Add or replace a key with the given string value and comment. The new card will be placed at the current mark
* position, as set e.g. by {@link #findCard(String)}.
*
* @param key The header key.
* @param val The string value.
* @param comment A comment to append to the card.
*
* @return the new card that was added.
*
* @throws HeaderCardException If the parameters cannot build a valid FITS card.
*
* @see #addValue(IFitsHeader, String)
* @see HeaderCard#HeaderCard(String, String, String)
*/
public HeaderCard addValue(String key, String val, String comment) throws HeaderCardException {
HeaderCard hc = new HeaderCard(key, val, comment);
addLine(hc);
return hc;
}
/**
* get a builder for filling the header cards using the builder pattern.
*
* @param key the key for the first card.
*
* @return the builder for header cards.
*/
public HeaderCardBuilder card(IFitsHeader key) {
return new HeaderCardBuilder(this, key);
}
/**
* Tests if the specified keyword is present in this table.
*
* @param key the keyword to be found.
*
* @return true if the specified keyword is present in this table; false otherwise.
*/
public final boolean containsKey(IFitsHeader key) {
return cards.containsKey(key.key());
}
/**
* Tests if the specified keyword is present in this table.
*
* @param key the keyword to be found.
*
* @return true if the specified keyword is present in this table; false otherwise.
*/
public final boolean containsKey(String key) {
return cards.containsKey(key);
}
/**
* Delete the card associated with the given key. Nothing occurs if the key is not found.
*
* @param key The header key.
*/
public void deleteKey(IFitsHeader key) {
deleteKey(key.key());
}
/**
* Delete the card associated with the given key. Nothing occurs if the key is not found.
*
* @param key The header key.
*/
public void deleteKey(String key) {
// AK: This version will not move the current position to the deleted
// key
if (containsKey(key)) {
cards.remove(cards.get(key));
}
}
/**
* Print the header to a given stream. Note that this method does not show reserved card space before the END
* keyword, and thus does not necessarily show the same layout as what would appear in a file.
*
* @param ps the stream to which the card images are dumped.
*
* @see #ensureCardSpace(int)
*/
public void dumpHeader(PrintStream ps) {
Cursor iter = iterator();
while (iter.hasNext()) {
ps.println(iter.next());
}
}
/**
* Returns the card associated with a given key. Unlike {@link #findCard(IFitsHeader)}, it does not alter the mark
* position at which new cards are added.
*
* @param key the header key.
*
* @return null if the keyword could not be found; return the HeaderCard object otherwise.
*
* @see #getCard(String)
* @see #findCard(IFitsHeader)
*
* @since 1.18.1
*/
public HeaderCard getCard(IFitsHeader key) {
return this.getCard(key.key());
}
/**
* Find the card associated with a given key. If found this sets the mark (cursor) to the card, otherwise it unsets
* the mark. The mark is where new cards will be added to the header by default. If you do not want to change the
* mark position, use {@link #getCard(IFitsHeader)} instead.
*
* @param key The header key.
*
* @return null if the keyword could not be found; return the HeaderCard object otherwise.
*
* @see #getCard(IFitsHeader)
* @see #findCard(String)
*/
public HeaderCard findCard(IFitsHeader key) {
return this.findCard(key.key());
}
/**
* Returns the card associated with a given key. Unlike {@link #findCard(String)}, it does not alter the mark
* position at which new cards are added.
*
* @param key the header key.
*
* @return null if the keyword could not be found; return the HeaderCard object otherwise.
*
* @see #getCard(IFitsHeader)
* @see #findCard(String)
*
* @since 1.18.1
*/
public HeaderCard getCard(String key) {
return cards.get(key);
}
/**
* Finds the card associated with a given key, and returns it. If found this sets the mark (cursor) to just before
* the card, such that {@link #nextCard()} will return that very same card on the first subsequent call. If the
* header contains no matching entry, the mark is reset to the tail of the header (the same as {@link #seekTail()}).
* The mark determines where new cards will be added to the header by default. If you do not want to alter the mark
* position, use {@link #getCard(String)} instead.
*
* @param key the header key.
*
* @return Returns the header entry for the given keyword, or null if the header has no such entry.
*
* @see #getCard(String)
* @see #findCard(String)
*/
public HeaderCard findCard(String key) {
HeaderCard card = cards.get(key);
if (card != null) {
cursor().setKey(key);
} else {
cursor().end();
}
return card;
}
/************************************
* brief Collect the header cards that match a regular expression. This is useful if one needs to search for a
* keyword that is buried under some HIERARCH string conventions of unspecified depth. So to search for some key
* like "HIERARCH OBO SUBOBO MYOBO", which would appear with the key HIERARCH.OBO.SUBOBO.MYOBO in this FITS
* implementation, one could search with regex="HIER.*MYOBO" and find it, supposed FitsFactory.setUseHierarch(true)
* was called before creating the header.
*
* @param regex The generalized regular expression for the keyword search
*
* @return The list of header cards that match the regular expression.
*
* @author Richard J. Mathar
*
* @since 1.19.1
*/
public HeaderCard[] findCards(final String regex) {
/*
* The collection of header cards that match.
*/
ArrayList crds = new ArrayList<>();
/*
* position pointer to start of card stack and loop over all header cards
*/
nom.tam.util.Cursor iter = iterator();
while (iter.hasNext()) {
final HeaderCard card = iter.next();
/*
* compare with regular expression and add to output list if it does
*/
if (card.getKey().matches(regex)) {
crds.add(card);
}
}
HeaderCard[] tmp = new HeaderCard[crds.size()];
return crds.toArray(tmp);
} /* findCards */
/**
* @deprecated Use {@link #findCard(String)} or {@link #getCard(String)} instead. Find the card associated with
* a given key.
*
* @param key The header key.
*
* @return null if the keyword could not be found; return the card image otherwise.
*/
@Deprecated
public String findKey(String key) {
HeaderCard card = findCard(key);
if (card == null) {
return null;
}
return card.toString();
}
/**
* Get the bid decimal value associated with the given key.
*
* @deprecated The FITS header does not support decimal types beyond those that can be represented by a 64-bit
* IEEE double-precision floating point value.
*
* @param key The header key.
*
* @return The associated value or 0.0 if not found.
*/
public final BigDecimal getBigDecimalValue(IFitsHeader key) {
return getBigDecimalValue(key.key());
}
/**
* Get the big decimal value associated with the given key.
*
* @deprecated The FITS header does not support decimal types beyond those that can be represented by a 64-bit
* IEEE double-precision floating point value.
*
* @param key The header key.
* @param dft The default value to return if the key cannot be found.
*
* @return the associated value.
*/
public final BigDecimal getBigDecimalValue(IFitsHeader key, BigDecimal dft) {
return getBigDecimalValue(key.key(), dft);
}
/**
* Get the big decimal value associated with the given key.
*
* @deprecated The FITS header does not support decimal types beyond those that can be represented by a 64-bit
* IEEE double-precision floating point value.
*
* @param key The header key.
*
* @return The associated value or 0.0 if not found.
*/
public final BigDecimal getBigDecimalValue(String key) {
return getBigDecimalValue(key, BigDecimal.ZERO);
}
/**
* Get the big decimal value associated with the given key.
*
* @deprecated The FITS header does not support decimal types beyond those that can be represented by a 64-bit
* IEEE double-precision floating point value.
*
* @param key The header key.
* @param dft The default value to return if the key cannot be found.
*
* @return the associated value.
*/
public BigDecimal getBigDecimalValue(String key, BigDecimal dft) {
HeaderCard fcard = getCard(key);
if (fcard == null) {
return dft;
}
return fcard.getValue(BigDecimal.class, dft);
}
/**
* Get the big integer value associated with the given key.
*
* @deprecated The FITS header does not support integer types beyond those that can be represented by a 64-bit
* integer.
*
* @param key The header key.
*
* @return the associated value or 0 if not found.
*/
public final BigInteger getBigIntegerValue(IFitsHeader key) {
return getBigIntegerValue(key.key());
}
/**
* Get the big integer value associated with the given key, or return a default value.
*
* @deprecated The FITS header does not support integer types beyond those that can be represented by a 64-bit
* integer.
*
* @param key The header key.
* @param dft The default value to be returned if the key cannot be found.
*
* @return the associated value.
*/
public final BigInteger getBigIntegerValue(IFitsHeader key, BigInteger dft) {
return getBigIntegerValue(key.key(), dft);
}
/**
* Get the big integer value associated with the given key.
*
* @deprecated The FITS header does not support integer types beyond those that can be represented by a 64-bit
* integer.
*
* @param key The header key.
*
* @return The associated value or 0 if not found.
*/
public final BigInteger getBigIntegerValue(String key) {
return getBigIntegerValue(key, BigInteger.ZERO);
}
/**
* Get the big integer value associated with the given key.
*
* @deprecated The FITS header does not support integer types beyond those that can be represented by a 64-bit
* integer.
*
* @param key The header key.
* @param dft The default value to be returned if the key cannot be found.
*
* @return the associated value.
*/
public BigInteger getBigIntegerValue(String key, BigInteger dft) {
HeaderCard fcard = getCard(key);
if (fcard == null) {
return dft;
}
return fcard.getValue(BigInteger.class, dft);
}
/**
* Get the complex number value associated with the given key.
*
* @param key The header key.
*
* @return The associated value or {@link ComplexValue#ZERO} if not found.
*
* @since 1.16
*
* @see #getComplexValue(String, ComplexValue)
* @see HeaderCard#getValue(Class, Object)
* @see #addValue(String, ComplexValue, String)
*/
public final ComplexValue getComplexValue(String key) {
return getComplexValue(key, ComplexValue.ZERO);
}
/**
* Get the complex number value associated with the given key, or return a default value.
*
* @param key The header key.
* @param dft The default value to return if the key cannot be found.
*
* @return the associated value.
*
* @since 1.16
*
* @see #getComplexValue(String)
* @see HeaderCard#getValue(Class, Object)
* @see #addValue(String, ComplexValue, String)
*/
public ComplexValue getComplexValue(String key, ComplexValue dft) {
HeaderCard fcard = getCard(key);
if (fcard == null) {
return dft;
}
return fcard.getValue(ComplexValue.class, dft);
}
/**
* Get the boolean value associated with the given key.
*
* @param key The header key.
*
* @return The value found, or false if not found or if the keyword is not a logical keyword.
*/
public final boolean getBooleanValue(IFitsHeader key) {
return getBooleanValue(key.key());
}
/**
* Get the boolean value associated with the given key.
*
* @param key The header key.
* @param dft The value to be returned if the key cannot be found or if the parameter does not seem to be a
* boolean.
*
* @return the associated value.
*/
public final boolean getBooleanValue(IFitsHeader key, boolean dft) {
return getBooleanValue(key.key(), dft);
}
/**
* Get the boolean value associated with the given key.
*
* @param key The header key.
*
* @return The value found, or false if not found or if the keyword is not a logical keyword.
*/
public final boolean getBooleanValue(String key) {
return getBooleanValue(key, false);
}
/**
* Get the boolean value associated with the given key.
*
* @param key The header key.
* @param dft The value to be returned if the key cannot be found or if the parameter does not seem to be a
* boolean.
*
* @return the associated value.
*/
public boolean getBooleanValue(String key, boolean dft) {
HeaderCard fcard = getCard(key);
if (fcard == null) {
return dft;
}
return fcard.getValue(Boolean.class, dft).booleanValue();
}
/**
* Get the n'th card image in the header
*
* @param n the card index to get
*
* @return the card image; return null if the n'th card does not exist.
*
* @deprecated An iterator from {@link #iterator(int)} or {@link #iterator()} should be used for sequential access
* to the header.
*/
@Deprecated
public String getCard(int n) {
if (n >= 0 && n < cards.size()) {
return cards.get(n).toString();
}
return null;
}
/**
* Return the size of the data including any needed padding.
*
* @return the data segment size including any needed padding.
*/
public long getDataSize() {
return FitsUtil.addPadding(trueDataSize());
}
/**
* Get the double value associated with the given key.
*
* @param key The header key.
*
* @return The associated value or 0.0 if not found.
*/
public final double getDoubleValue(IFitsHeader key) {
return getDoubleValue(key.key());
}
/**
* Get the double value associated with the given key, or return a default value.
*
* @param key The header key.
* @param dft The default value to return if the key cannot be found.
*
* @return the associated value.
*/
public final double getDoubleValue(IFitsHeader key, double dft) {
return getDoubleValue(key.key(), dft);
}
/**
* Get the double value associated with the given key.
*
* @param key The header key.
*
* @return The associated value or 0.0 if not found.
*/
public final double getDoubleValue(String key) {
return getDoubleValue(key, 0.0);
}
/**
* Get the double value associated with the given key, or return a default value.
*
* @param key The header key.
* @param dft The default value to return if the key cannot be found.
*
* @return the associated value.
*/
public double getDoubleValue(String key, double dft) {
HeaderCard fcard = getCard(key);
if (fcard == null) {
return dft;
}
return fcard.getValue(Double.class, dft).doubleValue();
}
/**
*
* Returns the list of duplicate cards in the order they appeared in the parsed header. You can access the first
* occurence of each of every duplicated FITS keyword using the usual Header.getValue(), and find
* further occurrences in the list returned here.
*
*
* The FITS standared strongly discourages using the keywords multiple times with assigned values, and specifies
* that the values of such keywords are undefined by definitions. Our library is thus far more tolerant than the
* FITS standard, allowing you to access each and every value that was specified for the same keyword.
*
*
* On the other hand FITS does not limit how many times you can add comment-style keywords to a header. If you must
* used the same keyword multiple times in your header, you should consider using comment-style entries instead.
*
*
* @return the list of duplicate cards. Note that when the header is read in, only the last entry for a given
* keyword is retained in the active header. This method returns earlier cards that have been discarded
* in the order in which they were encountered in the header. It is possible for there to be many cards
* with the same keyword in this list.
*
* @see #hadDuplicates()
* @see #getDuplicateKeySet()
*/
public List getDuplicates() {
return duplicates;
}
/**
* Returns the set of keywords that had more than one value assignment in the parsed header.
*
* @return the set of header keywords that were assigned more than once in the same header, or null if
* there were no duplicate assignments.
*
* @see #hadDuplicates()
* @see #getDuplicates()
*
* @since 1.17
*/
public Set getDuplicateKeySet() {
return dupKeys;
}
@Override
public long getFileOffset() {
return fileOffset;
}
/**
* Get the float value associated with the given key.
*
* @param key The header key.
*
* @return The associated value or 0.0 if not found.
*/
public final float getFloatValue(IFitsHeader key) {
return getFloatValue(key.key());
}
/**
* Get the float value associated with the given key, or return a default value.
*
* @return the float value associated with the given key.
*
* @param key The header key.
* @param dft The value to be returned if the key is not found.
*/
public final float getFloatValue(IFitsHeader key, float dft) {
return getFloatValue(key.key(), dft);
}
/**
* Get the float value associated with the given key.
*
* @param key The header key.
*
* @return The associated value or 0.0 if not found.
*/
public final float getFloatValue(String key) {
return getFloatValue(key, 0.0F);
}
/**
* Get the float value associated with the given key, or return a default value.
*
* @return the float value associated with the given key.
*
* @param key The header key.
* @param dft The value to be returned if the key is not found.
*/
public float getFloatValue(String key, float dft) {
HeaderCard fcard = getCard(key);
if (fcard == null) {
return dft;
}
return fcard.getValue(Float.class, dft).floatValue();
}
/**
* Get the int value associated with the given key.
*
* @param key The header key.
*
* @return The associated value or 0 if not found.
*/
public final int getIntValue(IFitsHeader key) {
return (int) getLongValue(key);
}
/**
* Get the int value associated with the given key, or return a default value.
*
* @return the value associated with the key as an int.
*
* @param key The header key.
* @param dft The value to be returned if the key is not found.
*/
public final int getIntValue(IFitsHeader key, int dft) {
return (int) getLongValue(key, dft);
}
/**
* Get the int value associated with the given key.
*
* @param key The header key.
*
* @return The associated value or 0 if not found.
*/
public final int getIntValue(String key) {
return (int) getLongValue(key);
}
/**
* Get the int value associated with the given key, or return a default value.
*
* @return the value associated with the key as an int.
*
* @param key The header key.
* @param dft The value to be returned if the key is not found.
*/
public int getIntValue(String key, int dft) {
return (int) getLongValue(key, dft);
}
/**
* Get the n'th key in the header.
*
* @param n the index of the key
*
* @return the card image; return null if the n'th key does not exist.
*
* @deprecated An iterator from {@link #iterator(int)} or {@link #iterator()} should be used for sequential access
* to the header.
*/
@Deprecated
public String getKey(int n) {
if (n >= 0 && n < cards.size()) {
return cards.get(n).getKey();
}
return null;
}
/**
* Get the long value associated with the given key.
*
* @param key The header key.
*
* @return The associated value or 0 if not found.
*/
public final long getLongValue(IFitsHeader key) {
return getLongValue(key.key());
}
/**
* Get the long value associated with the given key, or return a default value.
*
* @param key The header key.
* @param dft The default value to be returned if the key cannot be found.
*
* @return the associated value.
*/
public final long getLongValue(IFitsHeader key, long dft) {
return getLongValue(key.key(), dft);
}
/**
* Get the long value associated with the given key.
*
* @param key The header key.
*
* @return The associated value or 0 if not found.
*/
public final long getLongValue(String key) {
return getLongValue(key, 0L);
}
/**
* Get the long value associated with the given key, or return a default value.
*
* @param key The header key.
* @param dft The default value to be returned if the key cannot be found.
*
* @return the associated value.
*/
public long getLongValue(String key, long dft) {
HeaderCard fcard = getCard(key);
if (fcard == null) {
return dft;
}
return fcard.getValue(Long.class, dft).longValue();
}
/**
* @deprecated Not supported by the FITS standard, so do not use. It was included due to a misreading of the
* standard itself.
*
* @param key The header key.
*
* @return The associated value or 0 if not found.
*
* @since 1.16
*
* @see #getHexValue(String, long)
* @see HeaderCard#getHexValue()
* @see #addHexValue(String, long, String)
*/
@Deprecated
public final long getHexValue(String key) {
return getHexValue(key, 0L);
}
/**
* @deprecated Not supported by the FITS standard, so do not use. It was included due to a misreading of the
* standard itself.
*
* @param key The header key.
* @param dft The default value to be returned if the key cannot be found.
*
* @return the associated value.
*
* @since 1.16
*
* @see #getHexValue(String)
* @see HeaderCard#getHexValue()
* @see #addHexValue(String, long, String)
*/
public long getHexValue(String key, long dft) {
HeaderCard fcard = getCard(key);
if (fcard == null) {
return dft;
}
try {
return fcard.getHexValue();
} catch (NumberFormatException e) {
return dft;
}
}
/**
* Returns the nominal number of currently defined cards in this header. Each card can consist of one or more
* 80-character wide header records.
*
* @return the number of nominal cards in the header
*
* @see #getNumberOfPhysicalCards()
*/
public int getNumberOfCards() {
return cards.size();
}
/**
* Returns the number of 80-character header records in this header, including an END marker (whether or not it is
* currently contained).
*
* @return the number of physical cards in the header, including the END marker.
*
* @see #getNumberOfCards()
* @see #getSize()
*/
public int getNumberOfPhysicalCards() {
int count = 0;
for (HeaderCard card : cards) {
count += card.cardSize();
}
// AK: Count the END card, which may not have been added yet...
if (!containsKey(END)) {
count++;
}
return count;
}
/**
* Returns the minimum number of bytes that will be written by this header, either as the original byte size of a
* header that was read, or else the minimum preallocated capacity after setting {@link #ensureCardSpace(int)}.
*
* @return the minimum byte size for this header. The actual header may take up more space than that (but never
* less!), depending on the number of cards contained.
*
* @since 1.16
*
* @see #ensureCardSpace(int)
* @see #read(ArrayDataInput)
*/
public long getMinimumSize() {
return FitsUtil.addPadding((long) minCards * HeaderCard.FITS_HEADER_CARD_SIZE);
}
/**
* @deprecated for internal use) It should be a private method in the future. Returns the original size of
* the header in the stream from which it was read.
*
* @return the size of the original header in bytes, or 0 if the header was not read from a stream.
*
* @see #read(ArrayDataInput)
* @see #getMinimumSize()
*/
@Deprecated
public final long getOriginalSize() {
return readSize;
}
@Override
public final long getSize() {
if (!isValidHeader()) {
return 0;
}
return FitsUtil
.addPadding((long) Math.max(minCards, getNumberOfPhysicalCards()) * HeaderCard.FITS_HEADER_CARD_SIZE);
}
/**
* Get the String value associated with the given standard key.
*
* @param key The standard header key.
*
* @return The associated value or null if not found or if the value is not a string.
*
* @see #getStringValue(String)
* @see #getStringValue(IFitsHeader, String)
*/
public final String getStringValue(IFitsHeader key) {
return getStringValue(key.key());
}
/**
* Get the String value associated with the given standard key, or return a default value.
*
* @param key The standard header key.
* @param dft The default value.
*
* @return The associated value or the default value if not found or if the value is not a string.
*
* @see #getStringValue(String, String)
* @see #getStringValue(IFitsHeader)
*/
public final String getStringValue(IFitsHeader key, String dft) {
return getStringValue(key.key(), dft);
}
/**
* Get the String value associated with the given key.
*
* @param key The header key.
*
* @return The associated value or null if not found or if the value is not a string.
*
* @see #getStringValue(IFitsHeader)
* @see #getStringValue(String, String)
*/
public final String getStringValue(String key) {
return getStringValue(key, null);
}
/**
* Get the String value associated with the given key, or return a default value.
*
* @param key The header key.
* @param dft The default value.
*
* @return The associated value or the default value if not found or if the value is not a string.
*
* @see #getStringValue(IFitsHeader, String)
* @see #getStringValue(String)
*/
public String getStringValue(String key, String dft) {
HeaderCard fcard = getCard(key);
if (fcard == null || !fcard.isStringValue()) {
return dft;
}
return fcard.getValue();
}
/**
* Checks if the header had duplicate assignments in the FITS.
*
* @return Were duplicate header keys found when this record was read in?
*/
public boolean hadDuplicates() {
return duplicates != null;
}
/**
* Adds a line to the header using the COMMENT style, i.e., no '=' in column 9. The comment text may be truncated to
* fit into a single record, which is returned. Alternatively, you can split longer comments among multiple
* consecutive cards of the same type by {@link #insertCommentStyleMultiline(String, String)}.
*
* @param key The comment style header keyword, or null for an empty comment line.
* @param comment A string comment to follow. Illegal characters will be replaced by '?' and the comment may be
* truncated to fit into the card-space (71 characters).
*
* @return The new card that was inserted, or null if the keyword itself was invalid or the
* comment was null.
*
* @see #insertCommentStyleMultiline(String, String)
* @see HeaderCard#createCommentStyleCard(String, String)
*/
public HeaderCard insertCommentStyle(String key, String comment) {
if (comment == null) {
comment = "";
} else if (comment.length() > HeaderCard.MAX_COMMENT_CARD_COMMENT_LENGTH) {
comment = comment.substring(0, HeaderCard.MAX_COMMENT_CARD_COMMENT_LENGTH);
LOG.warning("Truncated comment to fit card: [" + comment + "]");
}
try {
HeaderCard hc = HeaderCard.createCommentStyleCard(key, HeaderCard.sanitize(comment));
cursor().add(hc);
return hc;
} catch (HeaderCardException e) {
LOG.log(Level.WARNING, "Ignoring comment card with invalid key [" + HeaderCard.sanitize(key) + "]", e);
return null;
}
}
/**
* Adds a line to the header using the COMMENT style, i.e., no '=' in column 9. If the comment does not fit in a
* single record, then it will be split (wrapped) among multiple consecutive records with the same keyword. Wrapped
* lines will end with '&' (not itself a standard) to indicate comment cards that might belong together.
*
* @param key The comment style header keyword, or null for an empty comment line.
* @param comment A string comment to follow. Illegal characters will be replaced by '?' and the comment may be
* split among multiple records as necessary to be fully preserved.
*
* @return The number of cards inserted.
*
* @since 1.16
*
* @see #insertCommentStyle(String, String)
* @see #insertComment(String)
* @see #insertUnkeyedComment(String)
* @see #insertHistory(String)
*/
public int insertCommentStyleMultiline(String key, String comment) {
// Empty comments must have at least one space char to write at least one
// comment card...
if ((comment == null) || comment.isEmpty()) {
comment = " ";
}
int n = 0;
for (int from = 0; from < comment.length();) {
int to = from + HeaderCard.MAX_COMMENT_CARD_COMMENT_LENGTH;
String part = null;
if (to < comment.length()) {
part = comment.substring(from, --to) + "&";
} else {
part = comment.substring(from);
}
if (insertCommentStyle(key, part) == null) {
return n;
}
from = to;
n++;
}
return n;
}
/**
* Adds one or more consecutive COMMENT records, wrapping the comment text as necessary.
*
* @param value The comment.
*
* @return The number of consecutive COMMENT cards that were inserted
*
* @see #insertCommentStyleMultiline(String, String)
* @see #insertUnkeyedComment(String)
* @see #insertHistory(String)
* @see HeaderCard#createCommentCard(String)
*/
public int insertComment(String value) {
return insertCommentStyleMultiline(COMMENT.key(), value);
}
/**
* Adds one or more consecutive comment records with no keyword (bytes 1-9 left blank), wrapping the comment text as
* necessary.
*
* @param value The comment.
*
* @return The number of consecutive comment-style cards with no keyword (blank keyword) that were inserted.
*
* @since 1.16
*
* @see #insertCommentStyleMultiline(String, String)
* @see #insertComment(String)
* @see #insertHistory(String)
* @see HeaderCard#createUnkeyedCommentCard(String)
* @see #insertBlankCard()
*/
public int insertUnkeyedComment(String value) {
return insertCommentStyleMultiline(BLANKS.key(), value);
}
/**
* Adds a blank card into the header.
*
* @since 1.16
*
* @see #insertUnkeyedComment(String)
*/
public void insertBlankCard() {
insertCommentStyle(null, null);
}
/**
* Adds one or more consecutive a HISTORY records, wrapping the comment text as necessary.
*
* @param value The history record.
*
* @return The number of consecutive HISTORY cards that were inserted
*
* @see #insertCommentStyleMultiline(String, String)
* @see #insertComment(String)
* @see #insertUnkeyedComment(String)
* @see HeaderCard#createHistoryCard(String)
*/
public int insertHistory(String value) {
return insertCommentStyleMultiline(HISTORY.key(), value);
}
/**
* Returns a cursor-based iterator for this header's entries starting at the first entry.
*
* @return an iterator over the header cards
*/
public Cursor iterator() {
return cards.iterator(0);
}
/**
* Returns a cursor-based iterator for this header's entries.
*
* @deprecated We should never use indexed access to the header. This function will be removed in 2.0.
*
* @return an iterator over the header cards starting at an index
*
* @param index the card index to start the iterator
*/
@Deprecated
public Cursor iterator(int index) {
return cards.iterator(index);
}
/**
* Return the iterator that represents the current position in the header. This provides a connection between
* editing headers through Header add/append/update methods, and via Cursors, which can be used side-by-side while
* maintaining desired card ordering. For the reverse direction ( translating iterator position to current position
* in the header), we can just use findCard().
*
* @return the iterator representing the current position in the header.
*
* @see #iterator()
*/
private Cursor cursor() {
return cards.cursor();
}
/**
* Move the cursor to the end of the header. Subsequently, all addValue() calls will add new cards to
* the end of the header.
*
* @return the cursor after it has been repositioned to the end
*
* @since 1.18.1
*
* @see #seekTail()
* @see #findCard(String)
* @see #nextCard()
*/
public Cursor seekHead() {
Cursor c = cursor();
while (c.hasPrev()) {
c.prev();
}
return c;
}
/**
* Move the cursor to the end of the header. Subsequently, all addValue() calls will add new cards to
* the end of the header.
*
* @return the cursor after it has been repositioned to the end
*
* @since 1.18.1
*
* @see #seekHead()
* @see #findCard(String)
*/
public Cursor seekTail() {
cursor().end();
return cursor();
}
/**
* @deprecated (for internal use) Normally we either want to write a Java object to FITS (in
* which case we have the dataand want to make a header for it), or we read some data
* from a FITS input. In either case, there is no benefit of exposing such a function
* as this to the user.
*
* @return Create the data element corresponding to the current header
*
* @throws FitsException if the header did not contain enough information to detect the type of the data
*/
@Deprecated
public Data makeData() throws FitsException {
return FitsFactory.dataFactory(this);
}
/**
* Returns the header card at the currently set mark position and increments the mark position by one. The mark
* position determines the location at which new entries are added to the header. The mark is set either to just
* prior a particular card (e.g. via {@link #findCard(IFitsHeader)}.
*
* @return the next card in the Header using the built-in iterator
*
* @see #prevCard()
* @see #findCard(IFitsHeader)
* @see #findCard(String)
* @see #seekHead()
*/
public HeaderCard nextCard() {
if (cursor().hasNext()) {
return cursor().next();
}
return null;
}
/**
* Returns the header card prior to the currently set mark position and decrements the mark position by one. The
* mark position determines the location at which new entries are added to the header. The mark is set either to
* just prior a particular card (e.g. via {@link #findCard(IFitsHeader)}.
*
* @return the next card in the Header using the built-in iterator
*
* @see #nextCard()
* @see #findCard(IFitsHeader)
* @see #findCard(String)
* @see #seekHead()
*
* @since 1.18.1
*/
public HeaderCard prevCard() {
if (cursor().hasPrev()) {
return cursor().prev();
}
return null;
}
/**
* Create a header which points to the given data object.
*
* @param o The data object to be described.
*
* @throws FitsException if the data was not valid for this header.
*
* @deprecated Use the appropriate Header constructor instead. Will remove in a future
* releae.
*/
@Deprecated
public void pointToData(Data o) throws FitsException {
o.fillHeader(this);
}
/**
* Remove all cards and reset the header to its default status.
*/
private void clear() {
cards.clear();
duplicates = null;
dupKeys = null;
readSize = 0;
fileOffset = -1;
minCards = 0;
}
/**
* Checks if the header is empty, that is if it contains no cards at all.
*
* @return true if the header contains no cards, otherwise false.
*
* @since 1.16
*/
public boolean isEmpty() {
return cards.isEmpty();
}
/**
*
* Reads new header data from an input, discarding any prior content.
*
*
* As of 1.16, the header is ensured to (re)write at least the same number of cards as before, padding with blanks
* as necessary, unless the user resets the preallocated card space with a call to {@link #ensureCardSpace(int)}.
*
*
* @param dis The input stream to read the data from.
*
* @throws TruncatedFileException the the stream ended prematurely
* @throws IOException if the operation failed
*
* @see #ensureCardSpace(int)
*/
@Override
public void read(ArrayDataInput dis) throws TruncatedFileException, IOException {
// AK: Start afresh, in case the header had prior contents from before.
clear();
if (dis instanceof RandomAccess) {
fileOffset = FitsUtil.findOffset(dis);
} else {
fileOffset = -1;
}
if (dis instanceof FitsInputStream) {
((FitsInputStream) dis).nextChecksum();
}
streamSum = -1L;
int trailingBlanks = 0;
minCards = 0;
HeaderCardCountingArrayDataInput cardCountingArray = new HeaderCardCountingArrayDataInput(dis);
try {
for (;;) {
HeaderCard fcard = new HeaderCard(cardCountingArray);
minCards += fcard.cardSize();
// AK: Note, 'key' can never be null, as per contract of getKey(). So no need to check...
String key = fcard.getKey();
if (isEmpty()) {
checkFirstCard(key);
} else if (fcard.isBlank()) {
// AK: We don't add the trailing blank cards, but keep count of them.
// (esp. in case the aren't trailing...)
trailingBlanks++;
continue;
} else if (END.key().equals(key)) {
addLine(fcard);
break; // Out of reading the header.
} else if (LONGSTRN.key().equals(key)) {
// We don't check the value here. If the user
// wants to be sure that long strings are disabled,
// they can call setLongStringsEnabled(false) after
// reading the header.
FitsFactory.setLongStringsEnabled(true);
}
// AK: The preceding blank spaces were internal, not trailing
// so add them back in now...
for (int i = 0; i < trailingBlanks; i++) {
insertBlankCard();
}
trailingBlanks = 0;
if (cards.containsKey(key)) {
addDuplicate(cards.get(key));
}
addLine(fcard);
}
} catch (EOFException e) {
// Normal end-of-file before END key...
throw e;
} catch (Exception e) {
if (isEmpty() && FitsFactory.getAllowTerminalJunk()) {
// If this happened where we expect a new header to start, then
// treat is as if end-of-file if terminal junk is allowed
forceEOF(
"Junk detected where header was expected to start" + ((fileOffset > 0) ? ": at " + fileOffset : ""),
e);
}
if (e instanceof TruncatedFileException) {
throw (TruncatedFileException) e;
}
throw new IOException("Invalid FITS Header" + (isEmpty() ? e :
":\n\n --> Try FitsFactory.setAllowTerminalJunk(true) prior to reading to work around.\n"), e);
}
if (fileOffset >= 0) {
input = dis;
}
ensureCardSpace(cardCountingArray.getPhysicalCardsRead());
readSize = FitsUtil.addPadding((long) minCards * HeaderCard.FITS_HEADER_CARD_SIZE);
// Read to the end of the current FITS block.
//
try {
dis.skipAllBytes(FitsUtil.padding(minCards * HeaderCard.FITS_HEADER_CARD_SIZE));
} catch (EOFException e) {
// No biggy. We got a complete header just fine, it's only that there was no
// padding before EOF. We'll just log that, but otherwise keep going.
LOG.log(Level.WARNING, "Premature end-of-file: no padding after header.", e);
}
if (dis instanceof FitsInputStream) {
streamSum = ((FitsInputStream) dis).nextChecksum();
}
// AK: Log if the file ends before the expected end-of-header position.
if (Fits.checkTruncated(dis)) {
// No biggy. We got a complete header just fine, it's only that there was no
// padding before EOF. We'll just log that, but otherwise keep going.
LOG.warning("Premature end-of-file: no padding after header.");
}
// Move the cursor to after the last card -- this is where new cards will be added.
seekTail();
}
/**
* Returns the random-accessible input from which this header was read, or null if the header is not
* associated with an input, or the input is not random accessible.
*
* @return the random-accessible input associated with this header or null
*
* @see #read(ArrayDataInput)
*
* @since 1.18.1
*/
RandomAccess getRandomAccessInput() {
return (input instanceof RandomAccess) ? (RandomAccess) input : null;
}
/**
* Returns the checksum value calculated duting reading from a stream. It is only populated when reading from
* {@link FitsInputStream} imputs, and never from other types of inputs. Valid values are greater or equal to zero.
* Thus, the return value will be -1L to indicate an invalid (unpopulated) checksum.
*
* @return the non-negative checksum calculated for the data read from a stream, or else -1L if the
* data was not read from the stream.
*
* @see FitsInputStream
* @see Data#getStreamChecksum()
*
* @since 1.18.1
*/
final long getStreamChecksum() {
return streamSum;
}
/**
* Forces an EOFException to be thrown when some other exception happened, essentially treating the exception to
* force a normal end the reading of the header.
*
* @param message the message to log.
* @param cause the exception encountered while reading the header
*
* @throws EOFException the EOFException we'll throw instead.
*/
private void forceEOF(String message, Exception cause) throws EOFException {
LOG.log(Level.WARNING, message, cause);
throw new EOFException("Forced EOF at " + fileOffset + " due to: " + message);
}
/**
* Delete a key.
*
* @param key The header key.
*
* @throws HeaderCardException if the operation failed
*
* @deprecated (duplicate method) Use {@link #deleteKey(String)} instead.
*/
@Deprecated
public void removeCard(String key) throws HeaderCardException {
deleteKey(key);
}
@Override
public boolean reset() {
try {
FitsUtil.reposition(input, fileOffset);
return true;
} catch (Exception e) {
LOG.log(Level.WARNING, "Exception while repositioning " + input, e);
return false;
}
}
/**
* @deprecated Use {@link #ensureCardSpace(int)} with 1 as the argument instead.
*
* Resets any prior preallocated header space, such as was explicitly set by
* {@link #ensureCardSpace(int)}, or when the header was read from a stream to ensure it remains
* rewritable, if possible.
*
*
* For headers read from a stream, this will affect {@link #rewriteable()}, so users should not call
* this method unless they do not intend to {@link #rewrite()} this header into the original FITS.
*
*
* @see #ensureCardSpace(int)
* @see #read(ArrayDataInput)
* @see #getMinimumSize()
* @see #rewriteable()
* @see #rewrite()
*/
@Deprecated
public final void resetOriginalSize() {
ensureCardSpace(1);
}
@Override
public void rewrite() throws FitsException, IOException {
ArrayDataOutput dos = (ArrayDataOutput) input;
if (!rewriteable()) {
throw new FitsException("Invalid attempt to rewrite Header.");
}
FitsUtil.reposition(dos, fileOffset);
write(dos);
dos.flush();
}
@Override
public boolean rewriteable() {
long writeSize = FitsUtil
.addPadding((long) Math.max(minCards, getNumberOfPhysicalCards()) * HeaderCard.FITS_HEADER_CARD_SIZE);
return fileOffset >= 0 && input instanceof ArrayDataOutput && writeSize == getOriginalSize();
}
/**
* Set the BITPIX value for the header. The following values are permitted by FITS conventions:
*
* - 8 -- signed byte data. Also used for tables.
* - 16 -- signed short data.
* - 32 -- signed int data.
* - 64 -- signed long data.
* - -32 -- IEEE 32 bit floating point numbers.
* - -64 -- IEEE 64 bit floating point numbers.
*
*
* @deprecated Use the safer {@link #setBitpix(Bitpix)} instead.
*
* @param val The value set by the user.
*
* @throws IllegalArgumentException if the value is not a valid BITPIX value.
*
* @see #setBitpix(Bitpix)
*/
@Deprecated
public void setBitpix(int val) throws IllegalArgumentException {
try {
setBitpix(Bitpix.forValue(val));
} catch (FitsException e) {
throw new IllegalArgumentException("Invalid BITPIX value: " + val, e);
}
}
/**
* Sets a standard BITPIX value for the header.
*
* @deprecated (for internall use) Visibility will be reduced to the package level in the future.
*
* @param bitpix The predefined enum value, e.g. {@link Bitpix#INTEGER}.
*
* @since 1.16
*
* @see #setBitpix(int)
*/
@Deprecated
public void setBitpix(Bitpix bitpix) {
Cursor iter = iterator();
iter.next();
iter.add(bitpix.getHeaderCard());
}
/**
* Overwite the default header card sorter.
*
* @param headerSorter the sorter tu use or null to disable sorting
*/
public void setHeaderSorter(Comparator headerSorter) {
this.headerSorter = headerSorter;
}
/**
* Set the value of the NAXIS keyword
*
* @deprecated (for internal use) Visibility will be reduced to the package level in the future.
*
* @param val The dimensionality of the data.
*/
@Deprecated
public void setNaxes(int val) {
Cursor iter = iterator();
iter.setKey(BITPIX.key());
if (iter.hasNext()) {
iter.next();
}
iter.add(HeaderCard.create(NAXIS, val));
}
/**
* Set the dimension for a given axis.
*
* @deprecated (for internal use) Visibility will be reduced to the package level in the future.
*
* @param axis The axis being set.
* @param dim The dimension
*/
@Deprecated
public void setNaxis(int axis, int dim) {
Cursor iter = iterator();
if (axis <= 0) {
LOG.warning("setNaxis ignored because axis less than 0");
return;
}
if (axis == 1) {
iter.setKey(NAXIS.key());
} else if (axis > 1) {
iter.setKey(NAXISn.n(axis - 1).key());
}
if (iter.hasNext()) {
iter.next();
}
iter.add(HeaderCard.create(NAXISn.n(axis), dim));
}
/**
* Set the SIMPLE keyword to the given value.
*
* @deprecated (for internall use) Visibility will be reduced to the package level in the future.
*
* @param val true for the primary header, otherwise false
*/
@Deprecated
public void setSimple(boolean val) {
deleteKey(SIMPLE);
deleteKey(XTENSION);
deleteKey(EXTEND);
Cursor iter = iterator();
iter.add(HeaderCard.create(SIMPLE, val));
// If we're flipping back to and from the primary header
// we need to add in the EXTEND keyword whenever we become
// a primary, because it's not permitted in the extensions
// (at least not where it needs to be in the primary array).
if (findCard(NAXIS) != null) {
if (findCard(NAXISn.n(getIntValue(NAXIS))) != null) {
iter.next();
}
}
iter.add(HeaderCard.create(EXTEND, true));
}
/**
* Set the XTENSION keyword to the given value.
*
* @deprecated (for internall use) Visibility will be reduced to the package level
* in the future.
*
* @param val The name of the extension.
*
* @throws IllegalArgumentException if the string value contains characters that are not allowed in FITS
* headers, that is characters outside of the 0x20 thru 0x7E range.
*/
@Deprecated
public void setXtension(String val) throws IllegalArgumentException {
deleteKey(SIMPLE);
deleteKey(XTENSION);
deleteKey(EXTEND);
iterator().add(HeaderCard.create(XTENSION, val));
}
/**
* @return the number of cards in the header
*
* @deprecated use {@link #getNumberOfCards()}. The units of the size of the header may be unclear.
*/
@Deprecated
public int size() {
return cards.size();
}
/**
* Update a valued entry in the header, or adds a new header entry. If the header does not contain a prior entry for
* the specific keyword, or if the keyword is a comment-style key, a new entry is added at the current editing
* position. Otherwise, the matching existing entry is updated in situ.
*
* @param key The key of the card to be replaced (or added).
* @param card A new card
*
* @throws HeaderCardException if the operation failed
*/
public void updateLine(IFitsHeader key, HeaderCard card) throws HeaderCardException {
updateLine(key.key(), card);
}
private void updateValue(IFitsHeader key, Boolean value) {
HeaderCard prior = cards.get(key.key());
if (prior != null) {
prior.setValue(value);
} else {
addValue(key, value);
}
}
private void updateValue(IFitsHeader key, Number value) {
HeaderCard prior = cards.get(key.key());
if (prior != null) {
prior.setValue(value);
} else {
addValue(key, value);
}
}
private void updateValue(IFitsHeader key, String value) {
HeaderCard prior = cards.get(key.key());
if (prior != null) {
prior.setValue(value);
} else {
addValue(key, value);
}
}
/**
* Update an existing card in situ, without affecting the current position, or else add a new card at the current
* position.
*
* @param key The key of the card to be replaced.
* @param card A new card
*
* @throws HeaderCardException if the operation failed
*/
public final void updateLine(String key, HeaderCard card) throws HeaderCardException {
// Remove an existing card with the matching 'key' (even if that key
// isn't the same
// as the key of the card argument!)
cards.update(key, card);
}
/**
* Overwrite the lines in the header. Add the new PHDU header to the current one. If keywords appear twice, the new
* value and comment overwrite the current contents. By Richard J Mathar.
*
* @param newHdr the list of new header data lines to replace the current ones.
*
* @throws HeaderCardException if the operation failed
*
* @see #mergeDistinct(Header)
*/
public void updateLines(final Header newHdr) throws HeaderCardException {
Cursor j = newHdr.iterator();
while (j.hasNext()) {
HeaderCard card = j.next();
if (card.isCommentStyleCard()) {
insertCommentStyle(card.getKey(), card.getComment());
} else {
updateLine(card.getKey(), card);
}
}
}
/**
* Writes a number of blank header records, for example to create preallocated blank header space as described by
* the FITS 4.0 standard.
*
* @param dos the output stream to which the data is to be written.
* @param n the number of blank records to add.
*
* @throws IOException if there was an error writing to the stream
*
* @since 1.16
*
* @see #ensureCardSpace(int)
*/
private void writeBlankCards(ArrayDataOutput dos, int n) throws IOException {
byte[] blank = new byte[HeaderCard.FITS_HEADER_CARD_SIZE];
Arrays.fill(blank, (byte) ' ');
while (--n >= 0) {
dos.write(blank);
}
}
/**
* Add required keywords, and removes conflicting ones depending on whether it is designated as a primary header or
* not.
*
* @param xType The value for the XTENSION keyword, or null if primary HDU.
*
* @throws FitsException if there was an error trying to edit the header.
*
* @since 1.17
*
* @see #validate(FitsOutput)
*/
void setRequiredKeys(String xType) throws FitsException {
if (xType == null) {
// Delete keys that cannot be in primary
deleteKey(XTENSION);
// Some FITS readers don't like the PCOUNT and GCOUNT keywords in the primary header
if (!getBooleanValue(GROUPS, false)) {
deleteKey(PCOUNT);
deleteKey(GCOUNT);
}
// Make sure we have SIMPLE
updateValue(SIMPLE, true);
} else {
// Delete keys that cannot be in extensions
deleteKey(SIMPLE);
// Some FITS readers don't like the EXTEND keyword in extensions.
deleteKey(EXTEND);
// Make sure we have XTENSION
updateValue(XTENSION, xType);
}
// Make sure we have BITPIX
updateValue(BITPIX, getIntValue(BITPIX, Bitpix.VALUE_FOR_INT));
int naxes = getIntValue(NAXIS, 0);
updateValue(NAXIS, naxes);
for (int i = 1; i <= naxes; i++) {
IFitsHeader naxisi = NAXISn.n(i);
updateValue(naxisi, getIntValue(naxisi, 1));
}
if (xType == null) {
updateValue(EXTEND, true);
} else {
updateValue(PCOUNT, getIntValue(PCOUNT, 0));
updateValue(GCOUNT, getIntValue(GCOUNT, 1));
}
}
/**
* Validates this header by making it a proper primary or extension header. In both cases it means adding required
* keywords if missing, and removing conflicting cards. Then ordering is checked and corrected as necessary and
* ensures that the END card is at the tail.
*
* @param asPrimary true if this header is to be a primary FITS header
*
* @throws FitsException If there was an issue getting the header into proper form.
*
* @since 1.17
*/
public void validate(boolean asPrimary) throws FitsException {
setRequiredKeys(asPrimary ? null : getStringValue(XTENSION, "UNKNOWN"));
validate();
}
/**
* Validates the header making sure it has the required keywords and that the essential keywords appeat in the in
* the required order
*
* @throws FitsException If there was an issue getting the header into proper form.
*/
private void validate() throws FitsException {
// Ensure that all cards are in the proper order.
if (headerSorter != null) {
cards.sort(headerSorter);
}
checkBeginning();
checkEnd();
updateChecksum();
}
private void updateChecksum() throws FitsException {
if (containsKey(Checksum.CHECKSUM)) {
HeaderCard dsum = getCard(Checksum.DATASUM);
if (dsum != null) {
FitsCheckSum.setDatasum(this, dsum.getValue(Long.class, 0L));
} else {
deleteKey(Checksum.CHECKSUM);
}
}
}
/**
* (for internal use) Similar to {@link #write(ArrayDataOutput)}, but writes the header as is, without
* ensuring that mandatory keys are present, and in the correct order, or that checksums are updated.
*
* @param out The output file or stream to which to write
*
* @throws FitsException if there was a violation of the FITS standard
* @throws IOException if the output was not accessible
*
* @since 1.20.1
*
* @see #write(ArrayDataOutput)
* @see #validate(boolean)
*/
public void writeUnchecked(ArrayDataOutput out) throws FitsException, IOException {
FitsSettings settings = FitsFactory.current();
fileOffset = FitsUtil.findOffset(out);
Cursor writeIterator = cards.iterator(0);
int size = 0;
while (writeIterator.hasNext()) {
HeaderCard card = writeIterator.next();
byte[] b = AsciiFuncs.getBytes(card.toString(settings));
size += b.length;
if (END.key().equals(card.getKey()) && minCards * HeaderCard.FITS_HEADER_CARD_SIZE > size) {
// AK: Add preallocated blank header space before the END key.
writeBlankCards(out, minCards - size / HeaderCard.FITS_HEADER_CARD_SIZE);
size = minCards * HeaderCard.FITS_HEADER_CARD_SIZE;
}
out.write(b);
}
FitsUtil.pad(out, size, (byte) ' ');
out.flush();
}
@Override
public void write(ArrayDataOutput out) throws FitsException {
validate();
try {
writeUnchecked(out);
} catch (IOException e) {
throw new FitsException("IO Error writing header", e);
}
}
private void addDuplicate(HeaderCard dup) {
// AK: Don't worry about duplicates for comment-style cards in general.
if (dup.isCommentStyleCard()) {
return;
}
if (duplicates == null) {
duplicates = new ArrayList<>();
dupKeys = new HashSet<>();
}
if (!dupKeys.contains(dup.getKey())) {
HeaderCardParser.getLogger().log(Level.WARNING, "Multiple occurrences of key:" + dup.getKey());
dupKeys.add(dup.getKey());
}
duplicates.add(dup);
}
/**
* Check if the given key is the next one available in the header.
*/
private void cardCheck(Cursor iter, IFitsHeader key) throws FitsException {
cardCheck(iter, key.key());
}
/**
* Check if the given key is the next one available in the header.
*/
private void cardCheck(Cursor iter, String key) throws FitsException {
if (!iter.hasNext()) {
throw new FitsException("Header terminates before " + key);
}
HeaderCard card = iter.next();
if (!card.getKey().equals(key)) {
throw new FitsException("Key " + key + " not found where expected." + "Found " + card.getKey());
}
}
private void checkFirstCard(String key) throws FitsException {
// AK: key cannot be null by the caller already, so checking for it makes dead code.
if (!SIMPLE.key().equals(key) && !XTENSION.key().equals(key)) {
throw new FitsException("Not a proper FITS header: " + HeaderCard.sanitize(key) + " at " + fileOffset);
}
}
private void doCardChecks(Cursor iter, boolean isTable, boolean isExtension) throws FitsException {
cardCheck(iter, BITPIX);
cardCheck(iter, NAXIS);
int nax = getIntValue(NAXIS);
for (int i = 1; i <= nax; i++) {
cardCheck(iter, NAXISn.n(i));
}
if (isExtension) {
cardCheck(iter, PCOUNT);
cardCheck(iter, GCOUNT);
if (isTable) {
cardCheck(iter, TFIELDS);
}
}
// This does not check for the EXTEND keyword which
// if present in the primary array must immediately follow
// the NAXISn.
}
/**
* Ensure that the header begins with a valid set of keywords. Note that we do not check the values of these
* keywords.
*/
private void checkBeginning() throws FitsException {
Cursor iter = iterator();
if (!iter.hasNext()) {
throw new FitsException("Empty Header");
}
HeaderCard card = iter.next();
String key = card.getKey();
if (!key.equals(SIMPLE.key()) && !key.equals(XTENSION.key())) {
throw new FitsException("No SIMPLE or XTENSION at beginning of Header");
}
boolean isTable = false;
boolean isExtension = false;
if (key.equals(XTENSION.key())) {
String value = card.getValue();
if (value == null || value.isEmpty()) {
throw new FitsException("Empty XTENSION keyword");
}
isExtension = true;
if (value.equals(XTENSION_BINTABLE) || value.equals("A3DTABLE") || value.equals("TABLE")) {
isTable = true;
}
}
doCardChecks(iter, isTable, isExtension);
Bitpix.fromHeader(this, false);
}
/**
* Ensure that the header has exactly one END keyword in the appropriate location.
*/
private void checkEnd() {
// Ensure we have an END card only at the end of the
// header.
Cursor iter = iterator();
HeaderCard card;
while (iter.hasNext()) {
card = iter.next();
if (!card.isKeyValuePair() && card.getKey().equals(END.key())) {
iter.remove();
}
}
// End cannot have a comment
iter.add(HeaderCard.createCommentStyleCard(END.key(), null));
}
/**
* Is this a valid header.
*
* @return true for a valid header, false otherwise.
*/
// TODO retire?
private boolean isValidHeader() {
if (getNumberOfCards() < MIN_NUMBER_OF_CARDS_FOR_VALID_HEADER) {
return false;
}
Cursor iter = iterator();
String key = iter.next().getKey();
if (!key.equals(SIMPLE.key()) && !key.equals(XTENSION.key())) {
return false;
}
key = iter.next().getKey();
if (!key.equals(BITPIX.key())) {
return false;
}
key = iter.next().getKey();
if (!key.equals(NAXIS.key())) {
return false;
}
while (iter.hasNext()) {
key = iter.next().getKey();
}
return key.equals(END.key());
}
/**
* @deprecated Use {@link NullDataHDU} instead. Create a header for a null image.
*/
@Deprecated
void nullImage() {
Cursor iter = iterator();
iter.add(HeaderCard.create(SIMPLE, true));
iter.add(Bitpix.BYTE.getHeaderCard());
iter.add(HeaderCard.create(NAXIS, 0));
iter.add(HeaderCard.create(EXTEND, true));
}
/**
* Find the end of a set of keywords describing a column or axis (or anything else terminated by an index). This
* routine leaves the header ready to add keywords after any existing keywords with the index specified. The user
* should specify a prefix to a keyword that is guaranteed to be present.
*/
Cursor positionAfterIndex(IFitsHeader prefix, int col) {
String colnum = String.valueOf(col);
cursor().setKey(prefix.n(col).key());
if (cursor().hasNext()) {
// Bug fix (references to forward) here by Laurent Borges
boolean toFar = false;
while (cursor().hasNext()) {
String key = cursor().next().getKey().trim();
// AK: getKey() cannot return null so no need to check.
if (key.length() <= colnum.length() || !key.substring(key.length() - colnum.length()).equals(colnum)) {
toFar = true;
break;
}
}
if (toFar) {
cursor().prev(); // Gone one too far, so skip back an element.
}
}
return cursor();
}
/**
* Replace the key with a new key. Typically this is used when deleting or inserting columns. If the convention of
* the new keyword is not compatible with the existing value a warning message is logged but no exception is thrown
* (at this point).
*
* @param oldKey The old header keyword.
* @param newKey the new header keyword.
*
* @return true if the card was replaced.
*
* @throws HeaderCardException If newKey is not a valid FITS keyword.
*/
boolean replaceKey(IFitsHeader oldKey, IFitsHeader newKey) throws HeaderCardException {
if (oldKey.valueType() == VALUE.NONE) {
throw new IllegalArgumentException("cannot replace comment-style " + oldKey.key());
}
HeaderCard card = getCard(oldKey);
VALUE newType = newKey.valueType();
if (card != null && oldKey.valueType() != newType && newType != VALUE.ANY) {
Class type = card.valueType();
Exception e = null;
// Check that the exisating cards value is compatible with the expected type of the new key.
if (newType == VALUE.NONE) {
e = new IllegalArgumentException(
"comment-style " + newKey.key() + " cannot replace valued key " + oldKey.key());
} else if (Boolean.class.isAssignableFrom(type) && newType != VALUE.LOGICAL) {
e = new IllegalArgumentException(newKey.key() + " cannot not support the existing boolean value.");
} else if (String.class.isAssignableFrom(type) && newType != VALUE.STRING) {
e = new IllegalArgumentException(newKey.key() + " cannot not support the existing string value.");
} else if (ComplexValue.class.isAssignableFrom(type) && newType != VALUE.COMPLEX) {
e = new IllegalArgumentException(newKey.key() + " cannot not support the existing complex value.");
} else if (card.isDecimalType() && newType != VALUE.REAL && newType != VALUE.COMPLEX) {
e = new IllegalArgumentException(newKey.key() + " cannot not support the existing decimal values.");
} else if (Number.class.isAssignableFrom(type) && newType != VALUE.REAL && newType != VALUE.INTEGER
&& newType != VALUE.COMPLEX) {
e = new IllegalArgumentException(newKey.key() + " cannot not support the existing numerical value.");
}
if (e != null) {
LOG.log(Level.WARNING, e.getMessage(), e);
}
}
return replaceKey(oldKey.key(), newKey.key());
}
/**
* Replace the key with a new key. Typically this is used when deleting or inserting columns so that TFORMx ->
* TFORMx-1
*
* @param oldKey The old header keyword.
* @param newKey the new header keyword.
*
* @return true if the card was replaced.
*
* @exception HeaderCardException If newKey is not a valid FITS keyword. TODO should be private
*/
boolean replaceKey(String oldKey, String newKey) throws HeaderCardException {
HeaderCard oldCard = getCard(oldKey);
if (oldCard == null) {
return false;
}
if (!cards.replaceKey(oldKey, newKey)) {
throw new HeaderCardException("Duplicate key [" + newKey + "] in replace");
}
try {
oldCard.changeKey(newKey);
} catch (IllegalArgumentException e) {
throw new HeaderCardException("New key [" + newKey + "] is invalid or too long for existing value.", e);
}
return true;
}
/**
* Calculate the unpadded size of the data segment from the header information.
*
* @return the unpadded data segment size.
*/
private long trueDataSize() {
// AK: No need to be too strict here. We can get a data size even if the
// header isn't 100% to spec,
// as long as the necessary keys are present. So, just check for the
// required keys, and no more...
if (!containsKey(BITPIX.key()) || !containsKey(NAXIS.key())) {
return 0L;
}
int naxis = getIntValue(NAXIS, 0);
// If there are no axes then there is no data.
if (naxis == 0) {
return 0L;
}
int[] axes = new int[naxis];
for (int axis = 1; axis <= naxis; axis++) {
axes[axis - 1] = getIntValue(NAXISn.n(axis), 0);
}
boolean isGroup = getBooleanValue(GROUPS, false);
int pcount = getIntValue(PCOUNT, 0);
int gcount = getIntValue(GCOUNT, 1);
int startAxis = 0;
if (isGroup && naxis > 1 && axes[0] == 0) {
startAxis = 1;
}
long size = 1;
for (int i = startAxis; i < naxis; i++) {
size *= axes[i];
}
size += pcount;
size *= gcount;
// Now multiply by the number of bits per pixel and
// convert to bytes.
size *= Math.abs(getIntValue(BITPIX, 0)) / FitsIO.BITS_OF_1_BYTE;
return size;
}
/**
*
* Sets whether warnings about FITS standard violations are logged when a header is being read (parsed). Enabling
* this feature can help identifying various standard violations in existing FITS headers, which nevertheless do not
* prevent the successful reading of the header by this library.
*
*
* If {@link FitsFactory#setAllowHeaderRepairs(boolean)} is set false, this will affect only minor
* violations (e.g. a misplaced '=', missing space after '=', non-standard characters in header etc.), which
* nevertheless do not interfere with the unamiguous parsing of the header information. More severe standard
* violations, where some guessing may be required about the intent of some malformed header record, will throw
* appropriate exceptions. If, however, {@link FitsFactory#setAllowHeaderRepairs(boolean)} is set true,
* the parsing will throw fewer exceptions, and the additional issues may get logged as additional warning instead.
*
* @param value true if parser warnings about FITS standard violations when reading in existing FITS
* headers are to be logged, otherwise false
*
* @see #isParserWarningsEnabled()
* @see FitsFactory#setAllowHeaderRepairs(boolean)
*
* @since 1.16
*/
public static void setParserWarningsEnabled(boolean value) {
Level level = value ? Level.WARNING : Level.SEVERE;
HeaderCardParser.getLogger().setLevel(level);
Logger.getLogger(ComplexValue.class.getName()).setLevel(level);
}
/**
* Checks whether warnings about FITS standard violations are logged when a header is being read (parsed).
*
* @return true if parser warnings about FITS standard violations when reading in existing FITS headers
* are enabled and logged, otherwise false
*
* @see #setParserWarningsEnabled(boolean)
*
* @since 1.16
*/
public static boolean isParserWarningsEnabled() {
return !HeaderCardParser.getLogger().getLevel().equals(Level.SEVERE);
}
/**
* Returns the current preferred alignment character position of inline header comments. This is the position at
* which the '/' is placed for the inline comment. #deprecated
*
* @return The current alignment position for inline comments.
*
* @see #setCommentAlignPosition(int)
*
* @since 1.17
*/
public static int getCommentAlignPosition() {
return commentAlign;
}
/**
* Sets a new alignment position for inline header comments.
*
* @param pos [20:70] The character position to which inline comments should be aligned if
* possible.
*
* @throws IllegalArgumentException if the position is outside of the allowed range.
*
* @see #getCommentAlignPosition()
*
* @deprecated Not recommended as it may violate the FITS standart for 'fixed-format'
* header entries, and make our FITS files unreadable by software that
* expects strict adherence to the standard. We will remove this feature in
* the future.
*
* @since 1.17
*/
public static void setCommentAlignPosition(int pos) throws IllegalArgumentException {
if (pos < Header.MIN_COMMENT_ALIGN || pos > Header.MAX_COMMENT_ALIGN) {
throw new IllegalArgumentException(
"Comment alignment " + pos + " out of range (" + MIN_COMMENT_ALIGN + ":" + MAX_COMMENT_ALIGN + ").");
}
commentAlign = pos;
}
}
© 2015 - 2025 Weber Informatics LLC | Privacy Policy