astro-sharp WinFITS - Documentation
Introduction
WinFITS was written to solve some frustrations I have experienced with FITS file organisation during
the process of deep-sky astro-imaging.
Many astronomers who get involved with deep-sky object (DSO) imaging soon realise that there are
a lot of files generated in the course of producing an image. The problem gets worse when separate
filters are used and flat files are added into the mix (not to mention dark and bias files). To add
another dimension to this, recently I have been sharing a telescope which uses a field rotator. This
means that, when the scope is flipped over the meridian, the rotator rotates the camera by 180°. It
does this to keep the guide star correctly in the field of the guide camera. The result is a requirement
to take flats at both of the position angles, and so there are 'East' and 'West' varieties of both light
and flat images to manage for all the different filters used!
So far, the programme provides the following facilities:



Flexible tag-based FIT file renaming using values from the FITS file header
A FITS header viewer
A flexible FITS file sorter which sorts and saves the files into a tree structure
Installation and required files
WinFITS is written in C#.NET and as such requires the .NET framework to be installed on your
Windows operating system. It will be extremely likely that you have this already, especially since it
has been included in the OS since Windows 7. However, if you do not have it, you can download it
here: http://www.microsoft.com/en-gb/download/details.aspx?id=21
There is no setup programme required for installation. There are three required files; simply unzip
them into the folder of your choice and set up a shortcut to the main WinFITS.exe file.
FILE
WinFITS.exe
WinFITs.xml
CSharpFITS_v1.1.dll
DESCRIPTION
The main executable (run this)
The file where WinFITS stores settings and defaults
A library of FIT file utilities for C# required by WinFITS
WinFITS Overview
When WinFITS is first launched, the screen below appears. It can be seen that it is a tab-based
design. Click on any of the tabs to go to a particular function, although some tabs only show useful
information after a certain function has been executed. For example, the 'Preview Renaming' tab is
populated and shown after the 'Preview Renamed Filenames' button is clicked from the main
renaming tab shown below.
If the 'About WinFITS' tab is selected, the version and other information is displayed, along with a
photograph of the telescope system that inspired me to write WinFITS. (The version is also
displayed in the caption bar). The about tab is show below:
Renaming FITS files
The first of the main features to be described is the FITS file renaming facility. This can be a useful
function if the FITS files you have are not named in a useful way. Here is an example of some files
that were stored on my hard drive that do not allow me to see what they are at a glance:
Although the file names tell me the target (NGC2070) and the filter (HA) they don't let me know the
exposure time, binning mode, the time taken, whether the scope was East or West of the meridian
or the position angle etc. However, all of this missing information is actually stored within the FITS
files in a well-defined header format, and the renaming function can read and use this data to
rename the files.
To remedy this, click on the 'Select Files to Rename...' button on the 'Rename FIT Files' tab as shown
below:
This causes an open dialog to be displayed. Note that the filter is set to show all the normal FITS file
extensions (*.fit, *.fits and *.fts). Select the files you wish to rename as shown here:
After the Open button has been clicked, the selected file names will be displayed in the list box as
shown below:
Previewing Renamed File Names
The idea is to (eventually) save these renamed files on to the hard disk again, but before this is done,
it might be a good idea to preview the renamed file names before they are saved. To do this click the
'Preview Renamed Filenames' button which causes the tab to be switched to the 'Preview Renaming'
tab as shown here:
It can be seen that the files have been renamed to include many other parameters. But before we
discuss how to save the renamed files, how was the remaining 'pattern' defined?
This can be seen by looking at the Options tab, the top part of which is shown below:
Here we can see the 'Rename Patterns' which contain 'tags'. The tags are defined with the '<>'
chevrons around them. For example the <FILTER> tag will get replaced by the FILTER property in the
FITS header of the particular file concerned. This subject will be expanded further in the section on
Options below, but it should be immediately obvious that there are separate patterns available for
light, flat, dark and bias files. Also, the tags can be 'sprinkled' in between fixed text.
Also note the checkboxes to the right of each of the rename patterns. These are used to enable or
disable each of the patterns. If a pattern is disabled, the rename process will simply use the original
file name. This can be useful, for example, if you are dealing with a mix of FITS image types and you
want to leave all flat filenames untouched. In my experience (and for reasons explained later in this
document) it is best to leave flat file filenames as they are.
Saving the Renamed Files
The bottom of the renaming tab has the options for saving the renamed files. These are shown
below:
They are pretty-well self explanatory. The main thing is to choose a destination folder to save the
files into. Then choose an option of what should be done if a destination file already exists. To
execute the save process, click the 'Rename Files' button. If all is well, the process will result in a
similar message to that shown here:
Using the Rename Pattern Editor
Notice, to the right of each of the rename patterns on the Options tab, that there is an edit button
for each of the four patterns, as shown here:
Clicking any of these will bring up a tag-builder dialog to assist in the process of editing the patterns
if required. The editor screen, showing the Light frame pattern, is shown below:
The pattern can simply be edited using the edit-box at the top, but to assist is getting the correct
format, all the available tags are shown in the list-box on the left. This list shows the familiar,
descriptive names of the tags. Clicking on any of the tags in the list will highlight it, and the tag
details will be displayed on the bottom status bar (see the example for Binning X above).
To add a tag to the rename pattern in the edit box, select a tag, then use the two buttons to either
add the tag to the end, or insert the tag at the location where the cursor is located in the text.
Double-clicking an item in the list also adds the tag to the end. The usual editing key strokes work as
usual, so it is possible to delete, backspace, copy and paste etc, as well as add the fixed parts of the
text in which the tags are 'sprinkled'.
When the pattern is edited to your liking, click the OK button, and the text will appear in the edit box
on the Options tab. Please note, you must still click the 'Save Rename Pattern' button to have
WinFITS remember your changes in the settings file.
I have tried to make WinFITS check for illegal characters, illegal tags etc, but I daresay it might be
possible to fool it! Just remember that the resulting text (after tag replacement) must make a legal
file-name.
Viewing FITS Headers
The next major function in WinFITS is the ability to look inside any FITS file and view the contents of
the header. This feature goes hand-in-hand with the above-mentioned renaming feature as the
selected files in the renaming list can also be used to select a file to view.
The above shows a few files selected in the renaming list. To view the header of one of them, select
the file (it is then highlighted) and then click the 'View FITS Header' button. This causes the header of
that file to be displayed in the 'View FITS Header' tab as shown below:
Use the scroll bar on the right to see all of the properties stored in the FITS header.
Note that there is a drop-down combo-box above the table which has been pre-populated with all of
the files that were in the renaming list, and you can switch to another file using this without having
to return to the rename tab. This is shown below:
Sorting FITS Files
This is probably the most useful feature in WinFITS. It allows the user to select a large number of
FITS files, a mixture of any type (lights, darks, flats and bias), and it will sort them into a configurable
tree structure ready to be saved on the hard drive.
The first thing to do is to select the files to be sorted. This is done using the 'FITS Sorter' tab shown
below.
There are two way to select the files you want to be sorted, and both of them allow for the fact that
you probably want to gather together different FITS files from several folders on your hard drive so
that they can all be sorted into a nice tree-like hierarchy. These two buttons provide the different
techniques (which, by the way, can be combined).
First, the 'Select Files to Sort' button. Clicking this brings up the usual file-open dialog allowing
multiple FITS files to be selected from a single folder at a time. With repeated uses of this button,
lots of FITS files from many folders can be gathered together for sorting.
If, however, you know that all of your FITS files are stored in sub-folders below one parent root
folder, you can use the second 'Select Root Folder...' button. Once selected, WinFITS will explore the
root folder and all of its sub-folders to find all of the FITS files.
Whichever method you use, when ready, click the 'Sort Files' button. This causes the resulting sorted
tree to be displayed in the 'Sorted Tree' tab:
The above shows a small portion of the tree in this example. Scroll down the tree and use the +/icons to expand or collapse the nodes of the tree to see the full picture:
Saving the Tree to Disk
To save the tree structure with all the sorted FITS files, select a folder and click the 'Save Tree to
Disk' button, as shown here:
You will first receive this warning, choose Yes to continue with the Save operation:
This operation may take some time, especially with large numbers of large FITS files saved on to
external USB hard drives. The progress meter on the bottom left of the screen will operate and
eventually you should see something like this:
Inspection of the hard disk will reveal the newly saved hierarchy of sorted files, an example of which
(using Windows Explorer) is shown here:
Configuring the Tree Structure
The 'nodes' or branches of the tree can be configured using the Options tab.
The order of the sorted branches can be individually controlled for the four file types. The order of
the sorting can be changed and each item can be enabled or disabled. So, for example, if you were
not interested in the scope-side, or the binning mode (on light files) you could use the check-boxes
to set the following arrangement:
If you wanted Position Angle above Filter, click on it and press the 'Move Up' button twice to obtain
this:
If you want WinFITS to remember these settings, click the 'Save' button just to the right of the
options. Do this for each image type. Note that not all the options make sense for all the image
types. For example, Dark frames only have these 2 options available:
Handling Duplicate Filenames in the Sort
It is quite likely, especially with many files being gathered together from many folders and subfolders, that more than one file of the same type with identical filenames will be selected. For
example, if you had backed up some files in a sub folder.
WinFITS deals with this by allowing the files to be selected together (because they have different
folder names) but when it comes to the Sort process, it detects any duplicates that end up in the
same branch of the Tree. WinFITS then makes the names unique by adding "_1" to the duplicate file
name before the extension. If there were 3 files with the same name it would add "_1_1" on to the
second duplicate and so on.
Here's an example where I deliberately duplicated a file in two sub-folders below a root folder:
Options
Further descriptions of the options on the 'Options' tab are described here:
Renaming Patterns and Tags
As mentioned above, the renaming feature uses a system of tagged text as a pattern when renaming
FITS files. The tags are dynamically replaced by the associated values that are held in the FITS file
header of each file. Here is the list of available <tags> and their meaning:
TAG
<OBJECT>
<FILTER>
<EXP_SEC>
<BIN>
<BINNINGX>
<BINNINGY>
<NAXIS1>
<NAXIS2>
<SET-TEMP>
<CCD-TEMP>
<SCOPE_SIDE>
<PA>
<UTC_TIME_START>
<CAMERA>
<COUNTER>
<PA_FILENAME>
REPLACED BY
Trimmed version of the OBJECT field in the header
The name of the filter used
The exposure in seconds
The binning value of the X axis
The binning value of the X axis
The binning value of the Y axis
The number of pixels along the X axis
The number of pixels along the Y axis
The temperature the CCD was set at
The temperature the CCD was at
The side the of the meridian
The Position angle of the rotator in degrees
The time of the start of exposure in UT
The name of the CCD camera (from Options Tab)
An incrementing file counter
Read PA from file-name (see notes below)
EXAMPLE
NGC300
RED, HA, OIII
600
1, 2 etc
1, 2 etc
1, 2 etc
4096
4096
-20
-19.8
E or W
344
UT125502
ATIK314L
001, 002 etc
PA344
It is expected that list will grow in future releases, but the most useful items are included here.
Note that the <CAMERA>, <COUNTER> and <PA_FILENAME> tags are not replaced by values from
the FITS header, see below for details.
The <COUNTER> tag is useful for bias and dark files where the rest of the filename would otherwise
be the same, and therefore not unique. The count starts at 001 and increments by 1 for every file in
the list of selected files.
The <CAMERA> tag value can be specified on the Options tab as shown below:
Notes about using <PA_FILENAME> (with Flat Files)
The <PA_FILENAME>tag has been provided to solve a particular issue that drove me mad with flat
files!
This issue is what I see with files that have been generated by DC-3 Dreams' excellent ACP Scheduler
software; it might not be an issue with FITS files saved by other means - I'm not sure! Anyway please
bear with me...
The problem seems to be that the PA value in the FITS header for flat files has not been
compensated for the scope-side in the same way as light files. Take an example where you have flats
for a PA of 344°. What we would like is to have flat file names marked as PA344 with varieties of 'E'
and 'W' in the same way as light files. However, it seems that the PA values in the FITS header for
those flats taken in the 'W' are 180° out (which is correct, but not what we want). If we left them at
PA164 (i.e. 344 - 180) we might not recognise them as really being flats for our PA of 344. Added to
that how would we know if they were really meant to be PA164?
So, my solution is to use the existing PA value in the flat file name, rather than in the header. It
should also be noted that WinFITS also gets the SCOPE_SIDE value from flat-file filenames because
they do not (in my experience) contain the PIERSIDE value in the header which WinFITS uses to
generate <SCOPE_SIDE>. (Note: SCOPE_SIDE is the opposite of PIERSIDE).
To hammer this home, here are two example flat filenames generate by ACP:
Flat-Green-PA055East-Bin1-005-194559.fts
Flat-Green-PA055West-Bin1-001-194128.fts
Note that one is East and the other West. However, if you were to inspect both these files using the
FITS Header viewer you would see that the East file has a PA=55 and the West file has a PA=235, but
both are really the same PA of 55! So by fetching the PA and the E/W from the filename the problem
is solved! After running these 2 files through the WinFITS renaming, we get this result:
Of course, one could argue that these particular flat files do not need renaming at all!
Other Tag notes
Tip: Think twice before using the CCD-TEMP tag because this might be slightly different for image
files taken in the same batch, and this would cause different branches to be created by the tree
sorting function! It is much safer to use SET-TEMP here.
Future Enhancements
The following ideas are being considered for future versions of WinFITS:



Adding editing facilities to the FITS header viewer
Extending tags
Improvements to user interface, including better re-sizing features