C/C++ source code for UCAC-3

C/C++ * source code for UCAC-3

Norbert Zacharias has kindly provided me with some example data for the UCAC-3 catalog, and I've written C/C++ code to access it. In most ways, it's very similar to the code I wrote for UCAC-2. The code for all UCACs (and some other catalogues) is here on GitHub.

ucac3.h and ucac3.cpp show how one can process UCAC-3 binary data from C. The code will work in Linux and DOS/Windows. I've added in byte-reordering code that ought to let it work on "wrong-Endian" platforms, but I don't have one handy with which to test the matter.

Essentially, two functions are provided. One allows you to extract the data for a particular UCAC-3 star, stored in a structure. The second allows one to extract all UCAC-3 stars in a given RA/dec rectangle. The data is stored in an ASCII file.

Make files are provided for GNU C/C++ (this also works with MinGW), Microsoft C/C++, and OpenWatcom C/C++. After building the software, one can run

u3test <ra> <dec> <width> <height>

with all arguments in decimal degrees. UCAC-3 data will be extracted and written to a text file, ucac3.txt. Optionally, one can add a path:

u3test <ra> <dec> <width> <height> <path>

to have the data read from another directory or from DVD. For example, if your DVD drive is d:, you might put the DVD in the drive and run

u3test 50 -12 1.3 1.8 d:\u2

to extract a 1.3-degree wide, 1.8-degree high field around RA=3h20m00s (a.k.a. 50 degrees), declination -12. As you might expect, if you've not copied the data and are running straight off the DVD, you need to be sure to have the correct side up in the drive.

Also, one can run the program in the folder containing UCAC-3 data with a UCAC-3 star number. The output will be a text version of the UCAC-3 record for that star. For example,

uca32 314 159265

would cause the program to display the basic data for 3UC314-159265.

I have added UCAC-3 display in Guide 8.0 on an "in-testing" basis, much as it's long been possible to display UCAC-2 data in Guide. (In fact, one can display UCAC-3 from the binary data files from the USNO DVD, or from data downloaded from VizieR.)

Hope this is useful to you, or at least interesting. Please let me know if you've problems or thoughts.

18 September 2009 update: It was pointed out that the ucac3.zip file that I posted lacked the very crucial file ucac3.h . I've fixed this.

Also, I've switched over to the new designation scheme.

Also, I added an 'output_format' argument to the functions to extract UCAC-3 stars and to write the data out to a text string. This allows one to tell the extraction function to skip over Tycho-2 stars (useful in star charting if you're already drawing stars from Tycho-2; it lets you avoid making 'false doubles'), and you can ensure that blank fields are written out as blanks rather than with zeroes. There is also a flag to cause the output to match that from the FORTRAN example code that's provided with UCAC-3. This last flag doesn't quite work yet. I'm thinking that if this code and the USNO FORTRAN code could produce identical results, it might prove useful at some point.

I also expect to add an 'output_format' flag that will suppress stars that lack a 2MASS match. It's starting to look as if any UCAC-3 star that didn't get matched to 2MASS is doubtful at best.

There is also at least one speed improvement I expect to make: at present, the extraction code reads in stars one at a time. I think performance might be better if it read in bigger chunks. That should be easy to implement (and may be needed for some things I hope to do with UCAC-3 in the future.)

New UCAC-3 designation scheme: UCAC-3 had two designation schemes, but a third has been settled upon: '3UC', followed by a zone number from 1 (stars between declinations -90 to -89.5) to 360 (stars between decs +89.5 to +90), followed by a six-digit number giving the order of that star within that declination zone. For example, '3UC314-159265' would be the 159265th star in zone 314 (the zone covering declinations +66.5 to +67).

'3UC' was used because '3U' had been taken by another astronomical catalogue.

Differences between this code and the UCAC-2 code: This code is heavily based on the code for accessing UCAC-2 data. However, the actual data provided for each star is very different, resulting in an 84-byte structure where there was once a 44-byte structure. So the actual data written out is quite different.

Also, the index provided for UCAC-3 would have been somewhat awkward to use. Instead of just seeking within it for a particular item, I'd have had to read in half of the index and do some convoluted code to figure out where the desired data started. So I wrote a small utility, makebin, which builds a better index, u3index.bin. But even this index simply narrows down the range in which the desired data might be found. I decided it would be well to binary-search to find the actual start of the desired range of stars.

This binary search is done over the small range specified by the index, if the index is available. If there is no index file provided, we just binary-search over the entire zone. This has several effects. It means the index is slightly helpful, but not really necessary; binary-searching with the index will be only slightly faster than without it. Previously, with UCAC-2, the index file was absolutely essential.

Also, my UCAC-2 code made the very bad assumption that a char is one byte, a short two, and a long four. These have been switched to use of int8_t, int16_t, and int32_t, and their unsigned flavors. This will, I hope, make the code a little more portable (for example, to 64-bit land).