C/C++ * source code for UCAC4

Last changed 2013 April 25

Note: star catalog code is now hosted on GitHub

Links to other source code on this site

Important: Fix to UCAC4 proper motion errors

Differences between this code and the UCAC3 code

I've written C/C++ code to access UCAC4 files. In most ways, it's very similar to the code I wrote for UCAC3 (which, in turn, resembled the code I wrote for UCAC2; in each case, I took the previous version and tweaked things a bit to allow for changes in formatting, indexing, and file naming conventions.) The code for all UCACs (and some other catalogues) is here on GitHub.

ucac4.h and ucac4.c show how one can process UCAC4 binary data from C or C++. The code will work in Linux and DOS/Windows. I've added in byte-reordering code that ought to let it work on "big-Endian" (non-Intel, such as Sun and PowerPC) 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 UCAC4 star, stored in a structure. The second allows one to extract all UCAC4 stars in a given RA/dec rectangle. The data is stored in an ASCII file.

Also provided is u4test.c, which both shows how the functions are used and can serve as a command-line utility for extracting a rectangle of UCAC4 data or getting data on a specific UCAC4 star.

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

u4test <ra> <dec> <width> <height>

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

u4test <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

u4test 50 -12 1.3 1.8 d:

to extract a 1.3-degree wide, 1.8-degree high field around RA=3h20m00s (a.k.a. 50 degrees), declination -12. On Linux/Unix systems, this would become something like

./u4test 50 -12 1.3 1.8 /media/cdrom/

The layout of UCAC4 is such that files for the north (zones 380-900, corresponding to declinations -14.2 to the north celestial pole) are in the u4n folder of one DVD. Those for the south (zones 1-379, declinations -14.2 and south) are in the u4s folder of the other DVD. People may copy these retaining the path structure, or maybe they'll put all 900 files in one folder. So if you ask this function for, say, zone_number = 314 and files in the folder /data/ucac4, the function will look for the data under the following four filenames:

z314            (i.e.,  all data copied to the current folder)
u4s/z314        (i.e.,  you've copied everything to two subfolders of the current)

...stopping when it finds a file. This will, I hope, cover all likely situations. If you make things any more complicated, you've only yourself to blame.

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

u4test 314-159265

would cause the program to display the basic data for 4U314-159265 (I think this will be the desired designation scheme).

u4test 314-159265 /media/cdrom

would do the same thing, but tell u4test where to look for the data files (going through the same possible paths as above).

To any of these, one may add command line options -h to include a header line, and/or -f4 to get the same output as from the FORTRAN code.

Hope this is useful to you, or at least interesting. Please let me know if you've problems or thoughts, at plüto.prôjéçtpluto.cøm (making changes that I hope will be obvious to non-spammers!)

Fix to UCAC4 proper motion errors: USNO has found that certain high proper motion stars were written out with incorrect proper motion data. They've provided a little program to fix this (which I've converted from Python to C). Details are at the UCAC4 home page, listed under the "2013 Feb" news.

Differences between this code and the UCAC3 code: This code is heavily based on the code for accessing UCAC3 data. However, the actual data provided for each star is very different. Also, I tried some different ideas that I'd pondered for UCAC3, but hadn't gotten around to implementing for that version.

For example: for UCAC3 and UCAC4, two indices are provided, an ASCII one and an "unformatted" (binary) one. Both are quite large. The ASCII one is nicely organized, but it is ASCII and therefore larger and a little more difficult to use than it otherwise would be. Nevertheless, the UCAC4 code will make use of this index if it is available, and data extraction will be somewhat faster if the index is used.

However, the code will work without the index. The index provides a starting location for each 1/4 degree in RA within a zone; i.e., if you're looking for the first record of a given RA, the index will enable you to bracket that record between two records a quarter degree apart. Without the index, the desired record is bracketed somewhere between the start and the end of the zone (i.e., over a 360-degree range instead of a quarter-degree one.)

In either case, the code will then narrow the bracket down to within 40 records. (Experiment suggests that there's not much benefit in narrowing things down more than this.) The bracketing is done by a secant search, modified slightly to improve speed. (The UCAC3 code used a binary search. The secant search is a little faster.) Once we have found the first record in our desired RA range (or a record no more than 40 records before it), we start reading UCAC4 records; if they fall within the desired RA/dec rectangle, they are written out to the file.

I also revised the code to read multiple UCAC4 stars at a time (currently set to 400 stars; see the buffsize parameter in ucac4.c.) This resulted in a small, but noticeable, improvement in performance.


(2013 April 26) Posted a change made by Skip Gaede to ensure that the code will compile correctly on OS/X. (Previously, the code would use the '\' character as a path separator when compiled for OS/X. This is correct for DOS/Windows, but in Linux and OS/X, the '/' character should be used.)

(2012 April 1) Storing proper motions in units of .0001 arcsec/year in two-byte integers means that proper motions outside the range -3.2766 to +3.2766 "/year cannot be stored. This affects 25 stars; for these, I added a special function that looks up the "real" proper motions. Also, Dave Herald pointed out that there's a little bit of similar trickery in the way in which the standard errors for proper motions are stored. Both problems are now handled correctly.