astro-sharp WinFITS - Documentation

IntroductionWinFITS 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 filesWinFITS 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 defaultsCSharpFITS_v1.1.dll A library of FIT file utilities for C# required by WinFITS

WinFITS OverviewWhen 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 filesThe 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 NamesThe 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 FilesThe 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 EditorNotice, 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 HeadersThe 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 FilesThis 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 DiskTo 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 StructureThe '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 SortIt 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:

OptionsFurther descriptions of the options on the 'Options' tab are described here:

Renaming Patterns and TagsAs 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 REPLACED BY EXAMPLE <OBJECT> Trimmed version of the OBJECT field in the header NGC300<FILTER> The name of the filter used RED, HA, OIII<EXP_SEC> The exposure in seconds 600<BIN> The binning value of the X axis 1, 2 etc<BINNINGX> The binning value of the X axis 1, 2 etc<BINNINGY> The binning value of the Y axis 1, 2 etc<NAXIS1> The number of pixels along the X axis 4096<NAXIS2> The number of pixels along the Y axis 4096<SET-TEMP> The temperature the CCD was set at -20<CCD-TEMP> The temperature the CCD was at -19.8<SCOPE_SIDE> The side the of the meridian E or W<PA> The Position angle of the rotator in degrees 344<UTC_TIME_START> The time of the start of exposure in UT UT125502<CAMERA> The name of the CCD camera (from Options Tab) ATIK314L<COUNTER> An incrementing file counter 001, 002 etc<PA_FILENAME> Read PA from file-name (see notes below) 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 notesTip: 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 EnhancementsThe 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