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 / DESCRIPTIONWinFITS.exe / The main executable (run this)
WinFITs.xml / The file where WinFITS stores settings and defaults
CSharpFITS_v1.1.dll / 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 sub-folders, 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: