FITSImage

This class provides an object-oriented interface to FITS images as both primary data units and extensions, the only difference between these of course being a few mandatory keywords in the unit header which the class keeps track of if necessary.

Note on Image Cubes and N-Dimensional Data

The most typical use-case scenario with FITS files is in fact the manipulation of 2-dimensional image data, and so this is what the class is designed around. If a user must truly interact with N-dimensional arrays, then there is a method to return the data unit and the user may do what they wish with it.

Vectors are transformed to 2D arrays with width = 1, but elements may be indexed with a single indexer (FITSImage[index]).

In the case where a primary unit is saved as a stack of images, i.e. a "data cube", typically each layer actually represents something unique such as, for example, R, G, and B color bands, etc. This is considered extremely poor practice to save an image set in this way - it is better to save the images as named extensions so that each may be given an explicit name and their own unique keywords if necessary. Thus, one may use the function ExtendizePrimaryImageLayerCube to pull the image layer out of the primary data unit and save them as extensions with names provided, etc.

Constructors

FITSImage(String^ FullFileName, bool mayContainExtensions); Create a dummy FITSImage object with arbitrary filename. Set the EXTEND key to true or false.

• fullFileName File name. May be anything for this dummy object, but if provided should follow a normal directory structure with file name and extension. Otherwise pass empty string.
• mayContainExtensions Sets the EXTEND keyword if true for the dummy header of this FITSImage.

FITSImage(String^ FullFileName, Object^ ImageData, bool Do_Stats, bool do_parallel); Create a FITSImage object with an existing ImageData vector or array of values. Optionally determine statistics of the data and perform construction operation with parallelism.

• FullFileName The intended full path file name of the FITS file.
• ImageData A vector or array of data values of any valid FITS type, for example double, int, short, float, etc.
• Do_Stats Compute the statistics of the data when the FITSImage object is formed (min, max, mean, sum, stdv).
• do_parallel Compute the statistics using parallelism (saves a bit of construction time for large image on multithreaded machines).

FITSImage(String^ FullFileName, array<int, 1>^ Range, bool Populate_Header, bool Populate_Data, bool Do_Stats, bool do_parallel); Create a FITSImage object from a primary data unit in a file on disk. Optionally load only a sub-range of the image, populate its header lines, populate its data, and perform statistics and construction operations with parallelism.

• FullFileName The full path file name of the FITS file on disk.
• range Range is ZERO based 1-D int array [xmin xmax ymin ymax]. Pass null or Range[0] = -1 to default to full image size.
• populateHeader Optionally populate the header - sometimes you just want the data, and can skip reading the non-essential header lines.
• populateData Optionally populate the image data array - sometimes you just want the header and don't need the data.
• doStats Optionally perform the statistics to determine min, max, mean, median, and standard deviation of the image data (if populated) - saves time if you don't need those.
• doParallel Populate the FITSImage object Image Data and perform stats (if true) with parallelization.

FITSImage(String^ FullFileName, String^ extensionName, array<int, 1>^ Range, bool Populate_Header, bool Populate_Data, bool Do_Stats, bool do_parallel); Same as previous, but read an IMAGE extension to build the object.

• FullFileName The full path file name of the FITS file on disk.
• extensionName The EXTNAME extension name of the image. If an empty string is passed, the first nameless IMAGE extension will be read. Exception if no such extension exits.
• range Range is ZERO based 1-D int array [xmin xmax ymin ymax]. Pass null or Range[0] = -1 to default to full image size.
• populateHeader Optionally populate the header - sometimes you just want the data, and can skip reading the non-essential header lines.
• populateData Optionally populate the image data array - sometimes you just want the header and don't need the data.
• doStats Optionally perform the statistics to determine min, max, mean, median, and standard deviation of the image data (if populated) - saves time if you don't need those.
• doParallel Populate the FITSImage object Image Data and perform stats (if true) with parallelization.

public FITSImage(string fullFileName, int extensionNumber, int[]? range, bool populateHeader, bool populateData, bool doStats, bool doParallel) >Useful when extensions are not named with EXTNAME keyword. Will return the image at the extension number if they are named regardless.

• FullFileName The full path file name of the FITS file on disk.
• extensionNumber The ONE-BASED extension number of the image.
• range Range is ZERO based 1-D int array [xmin xmax ymin ymax]. Pass null or Range[0] = -1 to default to full image size.
• populateHeader Optionally populate the header - sometimes you just want the data, and can skip reading the non-essential header lines.
• populateData Optionally populate the image data array - sometimes you just want the header and don't need the data.
• doStats Optionally perform the statistics to determine min, max, mean, median, and standard deviation of the image data (if populated) - saves time if you don't need those.
• doParallel Populate the FITSImage object Image Data and perform stats (if true) with parallelization.

FITSImage(String^ FullFileName, String^ DiskUCharBufferName, TypeCode Precision, int NAxis1, int NAxis2); Use this only if there is a raw data file on disk containing only the image data. Specify the precision the data is saved at on disk, and its axes dimensions. Use WriteFileFromDiskBuffer immediately after to write the data as a FITS file.

• fullFileName File name for the FITS object.
• DiskUCharBufferName File name of the disk byte data.
• Precision Precision of the data stored in the disk char array.
• NAxis1 Length of the 1st axis (x-axis)
• NAxis2 Length of the 2nd axis (y-axis)

Writing

void WriteImage(TypeCode Precision, bool do_parallel); Write a FITS image to disk as a primary header and primary image from the FITSImage object with its existing file name. If the file name already exists on disk, the primary unit will be overwritten, and any existing extensions will be appended to conserve the data file.

• precision Byte precision at which to write the image data.
• doParallel Populate the underlying byte arrays for writing with parallelization.

void WriteImage(String^ FullFileName, TypeCode Precision, bool do_parallel); Write a FITS image to disk as a primary header and primary image from the FITSImage object with a given file name. If the file name already exists on disk, the primary unit will be overwritten, and any existing extensions will be appended to conserve the data file.

• fullFileName File name.
• precision Byte precision at which to write the image data.
• doParallel Populate the underlying byte arrays for writing with parallelization.

void WriteImage(String^ FullFileName, String^ extensionName, bool overwriteExtensionIfExists, TypeCode Precision, bool do_parallel); Write a FITS image to disk as an extension from the FITSImage object with a given file name. The existing primary unit and any other extensions will be conserved to the file.

• fullFileName File name. Pass the object's own FullFileName to write to its existing file name. If the file doesn't yet exist on disk, then a new file will be created with an empty Primary Unit, and the image will be written as an extension. If the file does exist, then the extension will be written with the logic for the overwriteIfExists parameter, and the existing primary unit and any other extensions will be conserved to the file.
• extensionName The EXTNAME extension name of the IMAGE extension. If an empty string is passed, the first nameless IMAGE extension will be written to. If no such extension exists, the extension will be written as a new extension to the FITS file.
• overwriteExtensionIfExists If the image extension already exists it can be overwritten. If it exists and the option is given to not overwrite it, then an exception will be thrown.
• precision Byte precision at which to write the image data.
• doParallel Populate the underlying byte arrays for writing with parallelization.

void WriteFileFromDiskBuffer(bool DeleteOrigDiskBuffer); Use this to save the FITSImage object constructed from the constructor referencing raw data on disk.

Static File I/O

public static double[,] ConvertTxtToDblArray(string fullFileName, string delimit) Convert a text file to an array of data. delimit The field delimiter. If unknown pass empty string

static array<double, 2>^ ReadImageArrayOnly(String^ file, array<int, 1>^ Range, bool do_parallel); Just get the image data array from a file on disk.

static array<double>^ ReadImageVectorOnly(String^ file, array<int, 1>^ Range, bool do_parallel); Just get the data vector, assuming it is a vector.

static array<double>^ ReadPrimaryNDimensionalData(String^ fullFileName, array<int>^ &nAxisN); Return an N-dimensional primary data unit as a double vector. The axes dimensions are returned to the user in nAxisN.

static void ExtendizePrimaryImageLayerCube(String^ sourceFullFileName, String^ destFullFileName, array<String^>^ layerExtensionNames); Pull out the image layers from the image cube in the primary unit, and write them as named extensions instead.

public static string[] GetAllExtensionNames(string FileName) Returns an array of all image table extension names in a FITS file. If there are no image table extensions, returns an empty array.

public static double[,] DeHotPixel(FITSImage image, double countThreshold) Identifies and removes hot pixels from an image. The algorithm is not a simple find and replace, but assesses whether a pixel is part of a source with legitimate high values or is a solitary or paired high value which is simply hot.

• countThreshold The pixel value above which a pixel might be considered to be hot.

Image Operations

void StatsUpD(bool do_parallel); Updates the statistics for the primary image: maximum, minimum, mean, median, and standard deviation.

void SetImage(array<double, 2>^ ImageData, bool Do_Stats, bool do_parallel); Use SetImage to replace the existing double array for the FITSImage object with a new double array.

array<double, 2>^ GetSubImage(int X_Center, int Y_Center, int X_HalfWidth, int Y_HalfWidth); Returns a double array of a subset of coordinates from the primary image.

array<double, 2>^ GetSubImage(int X_Center, int Y_Center, int X_HalfWidth, int Y_HalfWidth, array<int>^ &xdata, array<int>^& ydata); Same as previous, but also return to the user vectors of the indices of the extracted array.

array<double, 2>^ GetSubImage(array<int, 1>^ Range); Returns a double array of a subset of coordinates from the primary image.

void RotateCW(bool CW); Rotate the primary image by 90 degrees.

void FlipVertical(); Flips the image across the horizontal axis, i.e. up to down.

void FlipHorizontal(); Flips the image across the vertical axis, i.e. left to right.

Header Operations

Header operations for an instance may all be accessed via the FITSHeader class instance accessed via FITSImage->Header.

Static Operators

One may apply common mathematical operators between FITSImages and/or scalars. For example data_array = FITSImage_A - FITSImage_B, or, FITSImage_C = FITSImage_A - 3.14159. Coded operators are +, -, *, /, and ^, between co-dimensional FITSImage image data arrays (or vectors) and/or scalars with the scalar being either on the right or the left hand side of the operator relative to the image. The operators return a data array, not a FITSImage object, and so if a FITSImage object should have its data updated, use SetImage to update the FITSImage object's data.

Properties

property double default[int] Index the FITSImage data vector, assuming it is a vector. Get and Set vector elements.

property double default[int, int] Index the FITSImage data array. Get and Set array elements.

property double Min Min returns the minimum of the FITS image data array. Returns zero if there is no array loaded or if stats have not been performed.

property double Max Max returns the maximum of the FITS image data array. Returns zero if there is no array loaded or if stats have not been performed.

property double Median Median returns the median of the FITS image data array. Returns zero if there is no array loaded or if stats have not been performed.

property double Mean Mean returns the average of the FITS image data array. Returns zero if there is no array loaded or if stats have not been performed.

property double Std Std returns the standard deviation of the FITS image data array. Returns zero if there is no array loaded or if stats have not been performed.

property double Sum Sum returns the sum of the FITS image data array. Returns zero if there is no array loaded or if stats have not been performed.

property int Width Width returns the width of the FITS image data array. Returns zero if there is no array loaded.

property int Height Height returns the height of the FITS image data array. Returns zero if there is no array loaded.

property int Length Length returns the total number of elements of the FITS image data array. Returns zero if there is no array loaded.

property String^ FileName FileName accesses just the file name of the FITS object, without the path. Get and Set. If it is Set, the full path name is tracked internally.

property String^ FilePath FilePath accesses just the file path of the FITS object. Get and Set. It if is Set, the full path name is tracked internally.

property String^ FullFileName FullFileName accesses the full file path + name of the FITS object. Get and Set. If it is Set, the path and the filename are tracked internally.

property array<double, 2>^ Image Image accesses the 2-D double array of the primary FITS object image. If the data is a vector then the width of the array = 1. Individual elements of the array can be accessed by indexing Image[x, y], or by using the default indexer of the FITSImage object. Property setter automatically performs image stats when Image is set. Use SetImage instead for option to not perform stats.

property array<String^>^ HeaderKeys HeaderKeys accesses a string array of all keys of the primary header. Get only. Use header operations for manipulating the header entries.

property array<String^>^ HeaderKeyValues HeaderKeyValues accesses a string array of all key values of the primary header. Get only. Use header operations for manipulating the header entries.

property array<String^>^ HeaderKeyComments HeaderKeyComments accesses a string array of all key comments of the primary header. Get only. Use header operations for manipulating the header entries.

property JPFITS.FITSHeader Header Provides access to the image header object.

public JPFITS.WorldCoordinateSolution WCS Provides access to the image WCS.