Skip to content

FITSBinTable

Jump to bottom
Joseph Postma edited this page Jan 31, 2023 · 6 revisions

Overview

The FITSBinTable class provides functionality for interacting with BINTABLEs in an object-oriented fashion. It includes support for complex number pairs and heap area "variable array" data (which are more accurately called "variable repeat" data).

Constructors

FITSBinTable(string extensionName); Create an empty FITSBinTable object. TTYPE entries may be added later via SetTTYPEEntries or AddTTYPEEntry. An extension name must be provided.

FITSBinTable(String^ fileName, String^ extensionName); Create a FITSBinTable object from an existing file and extension. If an empty string is passed as extensionName the first nameless extension will be found, if one exists.

Properties

public int NumberOfTableEntriesTFIELDS NumberOfTableEntries reports the number of fields in the extension, i.e. the TFIELDS value.

public int[] TableDataRepeats TableDataRepeats reports the number of columns or repeats in each table entry. Variable repeat (heap data) entries only report 1...use GetTTYPERowRepeatsHeapEntry to get the number of repeats for a given row.

public string[] TableDataLabelsTTYPE TableDataLabels reports the name of each table entry, i.e. the TTYPE values.

public string[] ExtensionEntryUnits ExtensionEntryUnits reports the units of each table entry, i.e. the TUNITS values.

public string[] Header Return the binary table header as an array of Strings for each line of the header.

public string ExtensionNameEXTNAME Return the name of the extension.

public int Naxis1 Return the width, in bytes, of the table.

public int Naxis2 Return the height, number of rows, of the table.

public byte[] BINTABLEByteArray Return the BINTABLE data block, excluding header, as a (unsigned) byte array.

Member Methods

public bool TTYPEEntryExists(string ttypeEntry) Check if a TTYPE entry exists within the bintable.

  • ttypeEntry The name of the binary table extension entry, i.e. the TTYPE value.

array<double>^ GetTTYPEEntry(String^ ttypeEntry); Return a binary table entry as a double 1-D array, assuming it is a single column non-repeated entry. If the entry has more than one column, use the overload function to get its dimensions.

array<double>^ GetTTYPEEntry(String^ ttypeEntry, array<int>^ &dimNElements); Return a binary table entry as a double 1-D array with dimensions returned. "dimNElements" is a vector to return the number of elements along each dimension of the Object. Contains the TDIM key values for an n > 2 dimensional array, otherwise contains the instances (repeats, i.e. columns) and NAXIS2 (number of rows). Its length gives the rank of the array Object. If rank = 1 then it contains only NAXIS2 elements as a vector.

Object^ GetTTYPEEntry(String^ ttypeEntry, TypeCode &objectTypeCode, array<int>^ &dimNElements); Return a binary table entry as an Object. Its type and dimensions are returned. If you just need a double precision array to work on, use the overload for that.

public string GetTTypeEntryRow(string ttypeEntry, int rowindex) Use this to access individual elements of the table with a String return. Useful for looking at TTYPEs with multiple instances.

void RemoveTTYPEEntry(String^ ttypeEntry); Remove one of the entries from the binary table.

void AddTTYPEEntry(String^ ttypeEntry, bool replaceIfExists, String^ entryUnits, Object^ entryArray); Add an entry to the binary table. Useful when dealing with a small table. Use SetTTYPEEntries for a large table to set all entries at once.

  • ttypeEntry is the name of the binary table extension entry, i.e. the TTYPE value.
  • replaceIfExists to replace the TTYPE entry if it already exists. If it already exists and the option is given to not replace, then an exception will be thrown.
  • entryUnits is the physical units of the values of the array; if it is not needed the pass nullptr or empty String "".
  • entryArray is the vector or 2D array object to enter into the table.

void AddTTYPEEntry(String^ ttypeEntry, bool replaceIfExists, String^ entryUnits, Object^ entryArray, array<int>^ dimNElements, bool isComplex, bool addAsHeapVarLenArray); Add an n > 2 dimensional and/or complex entry to the binary table or heap area. If entries already exist then the user must have formatted the n > 2 dimensional array to match the existing table height NAXIS2. Otherwise it is recommended to create this table with ONLY the n > 2 dimensional entry formatted simply as a vector, non-repeated instance. The height or NAXIS2 will then be the number of elements of the n > 2 dimensional array. If adding a complex number array to the binary table, the entryArray must be either single or double floating point. If complex the entryArray must be a factor of two columns repeats where the 1st and odd numbered columns are the spatial part, and the 2nd and even numbered columns are the temporal part. If it is a variable length heap array then the entry must be supplied as an array of arrays, and if complex each subarray must be an even pairing of values. If dimensions need to be recorded then supply the dimNelements argument.

  • dimNElements A vector giving the number of elements along each dimension of the array, to write as the TDIM key for the entry IF the entry is n > 2 dimensional; pass nullptr if the entry is not n > 2 dimensional.
  • isComplex A boolean to set whether the array should be interpreted as complex value pairings.
  • addAsHeapVarLenArray A boolean to set whether to save the array as a variable repeat array in the heap area; if it is, it must be formatted as a vector array of arrays, or as a vector of Strings.

void SetTTYPEEntries(array<String^>^ ttypeEntries, array<String^>^ entryUnits, array<Object^>^ entryArrays); Set the bintable full of entries all at once. More efficient than adding a large number of entries once at a time. Useful to use with a brand new and empty FITSBinTable. NOTE: THIS CLEARS ANY EXISTING ENTRIES INCLUDING THE HEAP. Do not use for n > 2 dimensional and/or complex entries...use addTTYPEEntry instead.

  • ttypeEntries The names of the binary table extension entries, i.e. the TTYPE values.
  • entryUnits the physical units of the field; may be passed as null if not needed, or with empty elements where not needed, etc.
  • entryArrays An array of vectors or 2D arrays to enter into the table.

public TypeCode GetTableDataTypes(int n) TableDataTypes reports the .NET typecodes for each entry in the table.

public bool GetTTYPEIsHeapVariableRepeatEntry(int n) Returns wheather the TTYPE entry at the given entry index is a variable repeat array.

public int GetTTYPERowRepeatsHeapEntry(int ttypeindex, int row) Returns the number of elements (repeats) for a given heap entry at a given row.

void AddExtraHeaderKey(String^ keyName, String^ keyValue, String^ keyComment); Add an extra key to the extension header. If it is to be a COMMENT, just fill the keyValue with eighteen characters, and the keyComment with 54 characters.

public string GetExtraHeaderKeyValue(string keyName) Get the value of an extra Key. If the key doesn't exist, an empty String is returned.

void RemoveExtraHeaderKey(String^ keyName, String^ keyValue); Remove the extra header key with the given name and value.

void RemoveAllExtraHeaderKeys(); Clear all extra header keys.

void Write(String^ FileName, String^ ExtensionName, bool OverWriteExtensionIfExists); Write the binary table into a new or existing FITS file. If the binary table already exists in an existing FITS file, it can optionally be replaced.

Static Functions

static array<String^>^ GetAllExtensionNames(String^ FileName); Returns an array of all binary table extension names in a FITS file. If there are no binary table extensions, returns an empty array.

static void RemoveExtension(String^ FileName, String^ ExtensionName); Remove a binary table extension from the given FITS file.

public static bool ExtensionExists(string FileName, string ExtensionName) Checks if the binary extension exists inside the given FITS file.

Clone this wiki locally