JSkyCalc Manual

Using JSkyCalc13m John Thorstensen, Dartmouth College; 2009 December

Important Background -- What this is and What this isn't:

This is a special version of JSkyCalc, retrofitted for pointing the 1.3m telescope at MDM. It does not control the mirror cover, dome, and so on -- pretty much all it does is point the telescope. So JSkyCalc13m supplements the control panel GUI (the one that says Telescope Status at the top), but does not replace it. You will want to run the control panel GUI as well as JSkyCalc13m.

Both the control panel GUI and JSkyCalc13m work internally by talking to Dick Treffers' telescope control program over a socket, which is a little like a telephone connection between independent computer programs. Because Dick's program sits and listens for requests, it is known as a server, whereas both the TCS GUI and JSkyCalc13m are called clients. It's important to understand these three points:

JSkyCalc13m needs to be connected to Dick's server to run, and in fact it won't start up unless Dick's server is running.
JSkyCalc13m doesn't actually move motors directly. It just asks the server to do it. So if JSkyCalc13m quits on you, the telescope should continue to function (unless the server has crashed for some reason). You can quit from JSkyCalc13m at any time.
Dick's server can only do one thing at a time. Until a process finishes, it locks you out. Thus JSkyCalc13m will appear unresponsive during a slew, and so on; don't expect instant response.

It's not a good idea to move the telescope with both programs at the same time. It shouldn't cause any catastrophes, but it may produce weird behavior. You might be tempted to try this if the telescope doesn't start moving the moment you tell it to. Be patient -- remember that the telescope server program can only do one thing at a time. If there's a delay, the server may just be busy.

Here's what JSkyCalc13m gives you:

A way to feed the telescope coordinates from lists, rather than typing the coordinates of each object into the control panel;
A graphical representation of where the telescope is pointing in the sky;
All the features of regular JSkyCalc (moon, twilight, and so on);
An easy way to look up bright-star coordinates for use in checking your pointing;
A way of re-zeroing the coordinates without having to transcribe the coordinates by hand (which is cumbersome and error-prone); and
Several frequently-updated "situational awareness" boxes that report how long you have until twilight, sunrise, and the like.

Using JSkyCalc13m at the Telescope

(Note: farther down there is a complete manual on the standard JSkyCalc.)

Starting. As noted earlier, JSkyCalc13m won't start unless Dick Treffers' telescope control server is running, because Dick's program actually runs the telescope. When JSkyCalc13m starts up, it immediately tries to connect to the telescope control server; if it can't for any reason, it puts up a dialog box that lets you fix the problem:

If the server isn't running yet, start it up and then click OK on the dialog box.
The server normally runs on hill, and JSkyCalc13m "wakes up" assuming this is the correct machine. If it is running on another computer for some reason, just supply the name of the correct computer in the dialog box.
If you want to give up, type QUIT (all uppercase letters) and hit OK. (The Cancel button also gets you out a bit less gracefully.)

Handling object lists. One main point of the program is to handle object lists, so you don't have to type in coordinates every time you set the telescope. An object list is a file with coordinates in it, with one object per line, in this format:

     name_no_blanks   hh mm ss   dd mm ss   equinox

for example,

     4U1234+56   12 34 35.3  56 01 02   1950

The window labeled Object Selector handles object lists. Clicking on Load New Object List opens a file dialog; once you select a file, the names of the objects appear in the selector box at the top of the window, and the objects themselves are also marked on the Sky Display. You can now select an object in one of three ways:

Click on the object on the Sky Display [If this doesn't work, the Sky Display window probably doesn't have focus; try moving the mouse in and out of the window a few times to highlight it], or
Click on the object's name in the object list, or ,
Type the object's name in the Object box to the upper left in the main JSkyCalc13m window. (The name must exactly match an object in the list).

When you select an object, its coordinates appear in the main window at the upper left. It will also be highlighted by a blue square on the Sky Display.

Note that you can view the list in alphabetical order, as well as sorted by RA.

More than one object list. When you read in a new object list with another already loaded, it's simply merged with the old list. If you have several long lists, the display gets too crowded. For this reason, there is a provision to remember the lists you've loaded and recall them quickly, without having to navigate down through the directory heirarchy. To use this, hit the "Clear List" button and then select the file you want to load from the lower list in the object list window. If it doesn't load, do a control-click to deselect it, then select it again -- lists only load when the selection changes, so if you click it when it's already selected, nothing happens.

The list-switching feature should be helpful if you have object lists for several different categories of targets -- these might be for different programs, or appropriate to different observing conditions, or something as simple as standard stars versus program objects.

Moving the telescope to a new target. The slew telescope button in the 1.3m Telescope Interface window will move the telescope so that it is pointed at the RA and dec listed at the upper left of the main JSkyCalc window. The slew won't actually start until you confirm it with the dialog box that pops up. When you confirm the slew, the program sends a request to the server for the move; if the server is busy, or if the requested coordinates are illegal, the telescope won't move. Note that the program freezes up until the telescope has finished moving. Once the move is complete, you'll see that

the new telescope coordinates appear in the Telescope coordinate fields; they're precessed to the equinox specified in the main window. Also,
the little red circle on the sky display (which represents the telescope aim point) is centered on the little blue box (which represents the coordinates in JSkyCalc13m).

Note that the Telescope RA, dec, and equinox that are displayed are passive displays of the telescope position -- they do not accept user input. In JSkyCalc convention, passive fields are rendered with a a light-grey background, while fields that accept input are rendered in white. Input coordinates need to appear in the boxes in the main window, in the upper left; those boxes are automatically updated when you select a target from a list.

Note also that there's a scroll box window that reports the telescope server's responses. You can usually ignore these, but it can be helpful to scroll back through them in case something unexpected happens (it keeps a couple hundred lines). If there's some kind of problem, you may find an ERROR lurking there -- for instance, you might be trying to slew past the telescope's limits.

A bit about Auto-update and Timing ... Unlike the usual JSkyCalc, this version starts up in auto-update mode, which means it wakes up every 15 seconds or so, reads the system clock and telescope coordinates, and redisplays everything for the current moment; it behaves like a very slowly ticking clock. It's possible to speed up the action by changing the 'sleep for' value, but I don't recommend it -- that just makes it more likely that things will screw up. If you're impatient you can use the Read telescope button to get an immediate update -- but remember that this won't respond if the telescope is slewing.

If you click on the orange "Stop Update" button on the main window, it stops the automatic updating, which makes it possible to look at times and dates other that the present. This may be helpful if you're thinking about tomorrow night, or something, but if you stop auto-update, the telescope control window disappears. This is by design, because you never want to slew the telescope based on information that may not correspond to the present time. If you resume the update again (simply by clicking the button), the telescope window reappears.

Looking up Bright Stars. The Nearest Bright Star button in the main JSkyCalc13m control window looks up the bright star nearest to the telescope coordinates (not the JSkyCalc13m coordinates, which might already be set on the next object or something), and loads them into JSkyCalc13m. If you now slew to these coordinates, you should be able to find the bright star (unless there's something wrong). The bright star list is kept in equinox 2000, but the coordinates have been updated for proper motion to 2010, so they should be more than good enough for setting the telescope coordinates. (I intend to freshen the list for proper motions from time to time.)

Re-zeroing the telescope coordinates. Be careful with this, since you can easily lose track of pointing if you don't do it right. If you click the Reset tel. coords, button, the telescope coordinate readouts will be reset so that they equal the coordinates displayed in the main window. Before you fire this command, you should be certain that both these conditions are met:

you're pointed right at a known object, and
the coordinates of that same object appear in the coordinate boxes at the upper left of the main JSkyCalc13m window.

If either of these is false, the reset command will leave you hopelessly lost, and you will need to home the telescope at the zenith using the tilt meters.

The command works internally by resetting the zero points in the pointing model. It's best to do this not too far from the zenith, because the telescope flexure and so on are not very well modeled at extreme positions.

A step-by-step procedure for re-zeroing the coordinates might be:

Slew to your target's coordinates.
Suppose you can't identify the target. There are many reasons this might be the case -- you may be looking at the wrong finding chart, the mirror cover or MIS dark hatch may be closed, the find/guide mirror may be in, the TV may be turned down, the telescope may be grossly out of focus, or what have you. So the first step is to check all these things. Don't proceed until you're pretty sure the pointing is the culprit.
In JSkyCalc13m, click on the Nearest Bright Star button. This puts the coordinates of the star (and its name and V mag) into the main window.
Slew to the coordinates of the bright star with the Slew telescope button. It should be a short move.
Hunt around until you find the bright star. Bright stars are stupendously bright compared to most other stars; don't take any cheap imitations.
Once you're sure you're looking at the genuine article and not an imposter, center the star where you like it, and finally
Hit Re-set tel. coords, read the dialog box, and proceed when you're sure.
Carfully check that the coordinates reset correctly. It may look as if the coordinates on the TCS control panel GUI (under "Telescope Status") disagree, but they are always reported in the present equinox. The coordinates in the JSkyCalc13m display will be in the same equinox used in the main window. In any case, don't move off the bright star until you're sure the coordinates are hunky-dory.
Once you're happy that the reset, reload your target coords and slew the telescope back to your target. It should be right there. If it's not, you're in trouble; go to the zenith, home the telescope on the tilt meters, and try again.

"Situational Awareness" boxes. At the bottom of the telescope control window are five boxes that simply report how long it will be until certain events happen -- how long until twilight and sunrise (or sunset, if it's afternoon), until the telescope (if it continues tracking) will hit 2 and 3 airmasses in the west, and until the moon rises or sets. In a few situations, the event reported is in the past; during evening twilight, for example the time since sunset is reported. During the day, the moonrise or set reported may be on the previous night, but during the day this won't matter much. This feature only makes sense when Auto update is in effect (as it is by default), so that the program's time is kept close to the actual time.

Warning Lights. At the bottom of the panel there three labels, "Sun:", "Moon:", and "Airmass:". Next to each is a little circle which you can think of as a warning light. The warning colors used are identical to those used for fields in the main window (and are explained in detail below), but they are computed for the telescope coordinates, not the coordinates in the main window, which may be different. If there's a situation you should be aware of -- twilight, you're too close to the moon, or the airmass is high -- these circles take on warning colors. Mostly their meanings are pretty obvious - yellow, orange or red -- but there are a few that are not:

When the moon is bright, but you're not close to it, the Moon warning light turns light blue (for moderate moonlight), or light purple (for very bright moonlight), because bright time is a normal occurrence. But if the telescope is pointing close to the moon, then the light turns red.
Yellow, orange, and red are used in twilight, but when the sun is actually up, the circle turns sky-blue.

Reassurance. JSkyCalc13m operates independently of the telescope -- it just listens to the telescope and sends a limited set of commands. If JSkyCalc13m crashes, or you quit out of it, the telescope will still work fine. Hopefully the program will make your work more pleasant and efficient, but it isn't essential. So relax and enjoy using it -- it's not critical to anything.

Acknowledgments. It would have been nearly impossible to develop this program without using a companion program that mimics the telescope server communications; Rick Pogge (OSU) generously shared his simulator, and offered good advice. I also want to thank Bob Barr for help testing the program at MDM.

JSkyCalc has a huge number of other capabilities, some of which may be useful (e.g. the Nightly Almanac). The manual for the standard JSkyCalc follows.

MANUAL FOR THE STANDARD VERSION

What is this for?

JSkyCalc is a tool designed to help you plan and execute astronomical observations. It shares some features with "desktop planetarium" programs such as XEphem and its many commercial alternatives, but rather than elegant visual presentation, the program emphasizes convenient controls and calculation of the quantities of greatest interest to professional astronomers.

Getting Started

The main JSkyCalc window controls most of the operation and reports the instantaneous circumstances.
Fields with white backgrounds will accept input, such as RA, dec, date and time. (You don't need to supply the day of week, it's computed on output.)
To make computations happen you can hit the Enter key in an input field, or use the buttons at the bottom of the panel, like Refresh output.
On refresh, all the input is read, and both the input and output are all overwritten with their values in the default formats.
When you select a different site from the menu, the output is computed for that site, for the same UT.
If your site isn't listed on the menu, first select Enable user input on the site menu. The site fields in the main window turn white, indicating that they can accept your input. Note the syntax used for the units and positive direction of longitude -- for example, " D E" (separated by spaces) would mean degrees east, while " H W" would mean hours west. (If the program is installed locally, you can change the site menu permanently by altering a configuration file, as explained later.)
Pressing Enter in the timestep field advances the program time by the amount you set. Units can be d, h, m, s for days, hours, minutes, or seconds, t for sidereal days (successive transits), or l (letter L) for lunar months.
One wrinkle: entering a Julian date in the JD field and pressing Enter sets the program time to the JD you entered.
Another: Entering a negative year for equinox causes the equinox of date to be computed and used instead.

The control buttons at the bottom of the frame do the following; more detailed descriptions of some of the windows they pop can be found a little further down:

Refresh Output reads all the input values, computes everything, and refreshes all the output. The input values are overwritten with the values that the program used, and the the day of week is appended to the date.

Set to now sets the program time using your computer's clock, and refreshes the output. Step Forward and Step Back step the time forward or back using the value of the timestep (explained above).

Auto Update keeps the program close to real time -- it sets everything using Java's clock time (which is UT), sleeps for the number of seconds indicated in the sleep for (s) field, and then wakes up and updates again. Auto Step steps forward by the timestep, sleeps for the desired number of seconds, and then repeats. The sleep for field accepts only integers.

The Site Menu (which is displayed on startup) allows you to select among many of the world's major observatories. Changing sites causes the computations to be refreshed; the Universal time is kept the same, so the local time will jump if the offset from UT is different. If the desired site is not on the list you must enter its parameters in the fields in the main window, but you must first click the button on the site menu to Enable User Input. The DST code parameter is used to select the convention used for Daylight Savings time (if any). The US convention is 1 (but Arizona and Hawaii do not observe DST); negative numbers are used for southern hemisphere sites. [If you're using the program with WebStart, you're stuck with either using the pre-programmed menu choices or entering your own site's parameters every time; if you install the program locally, just find the file "skycalcsites.dat" and install your own site following the format explained there. The file "skycalcsites.orig" should be left untouched for use in case you inadvertently corrup "skycalcsites.dat". The skycalcsites.dat file must be kept in the same directory as the class files.]

The Planet Table gives low-precision positions of the planets (to about 1 arcmin for the inner planets, and several arcmin for the outer ones), in the epoch of date. The last column in the table, Proximity, gives the angular distance between the planet and the coordinates that are used in the main program.

Hourly Circumstances summarizes the observability of your object through the night. If the time is before local noon, the previous night is tabulated. This is among the most heavily used features..

The Nightly Almanac lists the times of sunset and sunrise, twilight, and moonset and moonrise, corrected for the Terrain elevation (of the observatory above its surroundings). The terrain elevation must be a positive number (this is checked on input and reset to zero if negative).

Seasonal Observability presents a table summarizing the observability of the object at each new moon and each full moon over a span of about 6 months centered on the program date.

Object lists ... lets you read in a list of your own objects, which you can then select from a menu or call by name from the Object field in the main window. They also appear on the Sky display, and you can select them there with a left mouse click. The Object List feature is extremely useful, but security features of WebStart prevent loading of object lists, so you need to install the program locally to make it work; fortunately, this is very straightforward.

The Sky Display gives a schematic view of the sky, with stars to V = 4.5 , the planets, the sun, the moon, and any objects loaded in the list indicated. You can control some things from the display window with mouse and keyboard commands -- holding down the right mouse button in the sky display gives a brief menu.

The Alt. Coordinates window gives the input coordinates precessed to the present equinox, the Galactic coordinates, and the ecliptic coordinates. If you type Enter in the Galactic coordinate field, the position in the main program is set to the galactic coordinates you give, that is, the program converts from galactic back to equatorial.

The Airmass Graphs window creates a display of airmass vs. time through the night. Local time is plotted at the bottom of the frame, and UT at the top. Airmass is plotted vertically, with low airmass (small zenith distance) at the top. The altitude of the moon above the horizon, is plotted in yellow, with little symbols indicating the phase. This is keyed to the yellow scale at the right-hand side of the plot (not the same vertical used for the airmass). A few non-obvious features of this tool:

Displaying the airmass graph causes a little grey object-selector menu to appear, which shows the the object list if you've loaded one. Use this to select which objects to plot on the airmass graph. To select more than one object at a time, use ctrl-click, that is, hold down the Ctrl key and click on the name with the left mouse button. Then click on the Plot Airmasses button to see nice color-coded curves for the different objects.
Within the airmass graph window itself, a mouse click sets the program time to the time you clicked, and updates everything (it's pretty dramatic). This lets you quickly see the circumstances at any point during the night.

More detail on the Output Parameters

The output parameters on the right-hand side of the window are:

sidereal -- the local mean sidereal time, in H M S.
HA -- the hour angle, in H M S. Negative values are east. The field turns orange when the HA is more than 6 hours.
Airmass -- the true airmass, which is slightly different from the secant of z. Yellow, orange, and red warning colors are used at large airmass; yellow starts at airmass 2, orange at 3, and red at 4 (which is a huge airmass).
parallactic -- the position angle of "straight up", and its 180-degree opposite.
SunRAdec -- the topocentric (corrected for observer's horizontal parallax) position of the sun, in the equinox of date. Accuracy should be better than 1 arcsec.
SunAltAz -- the altitude and azimuth of the sun, uncorrected for refraction.
ZTwilight -- An estimate of how many magnitudes of twilight there is in blue light at the zenith. Yellow, orange, and red draw attention to this field when twilight might be an issue. Light blue indicates daytime sky.
MoonPhase -- A verbal description of the moon phase.
moonRAdec -- The topocentric position of the moon in the equinox of date. The moon's horizontal parallax can be very large (up to 1 degree), so the correction is important here. The lunar ephemeris used is good to about 10 arcseconds.
moonAltAz -- Altitude and azimuth of the moon, uncorrected for refraction.
illumFrac -- Fraction of the moon's face that is illuminated.
LunSkyBright -- an estimate of the brightness of scattered moonlight, in V magnitudes per square arcsecond, at the coordinates you're looking at. This is based on K. Krisciunas and B. Schaefer's analytical fit to their empirical measurements (1991, PASP, 103, 1033). An elaborate warning color scheme is used, starting with light blue when the background is roughly doubled from its dark value, and turning a light purple to indicate "normal" bright-run conditions. When you're close to the moon a yellow-orange-red scheme comes into play.
Moon-Obj ang. -- Angle between the moon and the object. Warning colors are used to indicate problematic conditions.
Bary. JD -- The time corrected to the solar system center-of-mass (nearly the same as the heliocentric correction, but more correct), and the size of the correction, which is accurate to a couple of hundredths of a second.
Bary. Vcorrn -- Add this to an observed radial velocity to get the value observed from the solar system barycenter. Accuracy is much better than 10 m/s.
Constellation -- The constellation that the current coordinates lie in. This is computed using the algorithm given by N. G. Roman (1987, PASP, 99, 695). Francois Ochsenbein's (CDS Strasbourg) implementation of this algorithm in C is ported here to Java.
Planet Warning? -- This field lights up when your coordinates are near to a planet. Being close to a bright planet (e.g. 1 degree from Jupiter) gets a red warning.

More Detail on the Other Windows

Except for the Site Menu and Sky Display window, these other windows are all hidden on startup. You can get the windows to show using the buttons at the bottom of the main panel -- the buttons toggle the corresponding window on and off. Most of the windows also have their own "hide" buttons. Don't use your windowing system's buttons to close windows, as this can kill processes.

The Hourly Circumstances window is a popular favorite. It gives the circumstances for the object coordinates (from the main window), computed for each hour through the night. Time is given in Local, UT, and sidereal (LST), followed by the hour angle and airmass, followed by the altitude of the moon and the sun. Warning colors (red, orange, yellow, light purple, and blue) are used in the HA, airmass, moonalt, and sunalt columns. If the time in the main window is before noon, the previous night is shown; if the time is after noon, the coming night is shown. This is so that if you run a calculation with the time set to 2 AM, it computes the table for the most appropriate night.

The refresh time for this window can be noticeable; if you're not using the output, you can hide it using the button provided, which turns off the refresh and can speed things up a bit. You can put the window back up using the button in the main window.

A button is provided to dump the contents of this window to a file in your local directory. The output is appended to the file, so you can run a number of objects and then print the file.

The Nightly Almanac window gives times of sunset, sunrise, twilight (when the sun is 18 degrees below the horizon), moonrise, and moonset, defined as when the upper limb is on the visible horizon. When the terrain elevation is zero (this quantity is defined here as the elevation of the observatory above the terrain that forms its horizon), the rise and set times are computed for when the center of the sun or moon is 90 degrees, 50 minutes from the zenith, which accounts roughly for atmospheric refraction and the angular size. If the terrain elevation is greater than zero, the rise and set times are adjusted accordingly. The sidereal times at evening and morning 18-degree twilight are also listed.

If the time in the main program is before local noon, the previous night is computed. If it's after local noon, the next night is computed. This is just like the Hourly Circumstances window. The window is invisible on startup, but can be revealed or hidden using the buttons provided.

The Planet Table gives low-precision coordinates of the planets, derived from algorithms given by Jean Meeus in Astronomical Formulae for Calculators (Willman-Bell). The inner planets are good to about a minute of arc, but the outer planets are somewhat worse, and Pluto (I know, it's not a planet any more officially) is pretty bad. Coordinates are in the epoch of date. (These planetary positions are also used internally to find the offset between the heliocenter and the barycenter for the barycentric corrections.) The last column in the table, Proximity, gives the angular distance between the planet and the coordinates that are used in the main window. The planet table can be printed using the built-in print method provided by Java for this class.

The Object List window lets you read in a list of astronomical objects. Reading in a list of objects read in greatly enhances the usability and power of the program -- you don't have to type in coordinates, and the objects are graphed on the Sky Display. The list must be in this format:

     name_no_blanks   hh mm ss   dd mm ss   equinox

for example,

     4U1234+56   12 34 35.3  56 01 02   1950

The format is dictated by the telescope pointing list format expected at MDM Observatory, where I do most of my observing. Colons are acceptable as delimiters for the RA and dec fields (but be advised that they don't work with the MDM telescope software). The Load Object List button pops a file-selecting dialog box. Once you've loaded up a list, you can click on the object you want, and it will be loaded into the program. If you prefer, you can also select an object by typing its exact name into the Object: field in the main window and pressing the Enter key. You can present the list in either RA or alphabetical order using the buttons provided, and the Clear List button deletes all the objects (but for technical reasons, a single object called null at zero hours and zero degrees will remain). A hide button is provided also.

The Alternate Coordinates window gives the coordinates precessed to the equinox of date, the galactic coordinates, (which are rigorously accurate), and ecliptic coordinates. There's no hide button -- use the button on the main window to toggle the window on and off.

The white background behind the galactic coordinates signifies that they can be used for input. Entering a value in the galactic latitude or longitude fields and pressing Enter sets the coordinates in the main window to the location specified by the longitude and latitude you entered. Thus the program can serve as a galactic-to-equatorial converter. I have not implemented an analagous function for ecliptic coordinates.

The Seasonal Observability window is useful for planning when to observe an object (for example, in filling out a time request form). It takes the date from the main window, figures out when new and full moons will occur for about three months on either side, and generates a table, each line of which gives a brief summary of the object's observability at each of these dates. The hour angle and airmass are given at the start of the night, the natural center of the night, and the end of the night. The last three columns give the number of hours that the object is accessible without twilight and at airmasses of less than 3, less than 2, and less than 1.5. A button is provided to print the output.

The Sky Display Window

The Sky Display button in the main window toggles the display on and off (it does take a lot of screen real estate). The window plots a map of the sky, showing stars to V = 4.5, the sun, moon, and the planets (including Pluto, whatever you want to call it). If you have an object list loaded, it also plots each object as a text string, the bottom of which is centered on the object. The coordinates in the main program are marked with a greenish box. The stars are generally not plotted in a pure white, but with a color derived from the spectral type; the RGB values chosen to represent the spectral types are based on those computed by M. N. Charity (see http://www.vendian.org/mncharity/dir3/starcolor/). I de-saturated his suggested colors slightly (moved them toward white) because the full colors were a bit distracting.

Red arcs indicate the meridian, the equator, and lines of constant hour angle every 2 h out to +- 6 h. Dotted red circles indicate 2, 3, and 4 airmasses.

The moon is drawn at exaggerated size but in the correct phase and orientation. The planets are sized according to magnitude, with the fainter ones rendered as very small dots. A clock drawn in the upper right corner shows the prevailing local time; the Site and Universal Time information are printed at the lower right. The background color is controlled by where the sun is -- when there is no twilight the background is black (even if the moon is bright). There's a small, discontinous jump to dark grey at the beginning and end of twilight, and a continuous ramp between twilight and daylight, which is rendered in blue. This proves very helpful in keeping the user oriented in time.

The sky display updates whenever the main window changes, so the Auto Step command results in a somewhat jerky animation.

The sky display recognizes several mouse and keyboard commands , as follows. But first, note that the window will not respond to the keyboard commands unless it has focus (with most systems, this is indicated by some kind of change in the window border). The mouse commands work regardless (though I have heard of people having issues with these features on Macs running OS-X).

Pressing and holding the Right Mouse Button pops up a little command summary.
Middle Mouse Button (or typing 'c' at the keyboard) sets the position in the main program to the position of the mouse.
Left Mouse Button , or 's', looks for the listed object nearest the mouse, and sets the main window to that object. You need to hit it within about 5 degrees.
'f' - step the time forward (same as "Step Forward") in the main window.
'b' - step the time back (same as "Step Back") in the main window.
'z' - Zoom in by a factor of two around the mouse position.
'o' - zoom Out by a factor of two around the mouse position.
'p' - Pan, or recenter at the mouse position.
'r' - Restore the original view.
'h' - set the coordinates and object name to that of the bright (HR catalog) star closest to the cursor.

It's a minor detail, but the stars are precessed to the current equinox whenever their coordinates are more than one year out of date; they are not precessed with every refresh to save computation time. One notices this with the 'h' command - the coordinates loaded will be close to the equinox of date, rather than (say) J2000. The planets, sun, and moon are already in the equinox of date. The object list is precessed with every refresh.

Bugs, "Gotchas", and Limitations

This is surely an incomplete list:

Do not use/trust this program for archeoastronomy. It is designed for use near the present time and the calendrical, lunar, precession, and planetary calculations will surely be flaky outside of a couple centuries from the present time. It should work well within that range.
This program is not designed as a teaching tool. While it can certainly be used to supplement instruction, it isn't meant to be a standalone tutorial. Users are expected to understand the relevant concepts.
The code has not been extensively tested at high geographic latitudes.
The planetary ephemeris used is not particularly accurate -- it is meant to be small, portable, reasonably fast, and "good enough". If you need to aim directly at a planet, or calculate stellar occultations, use something else, e.g. get your positions from the JPL Horizons site.
The sky display is not a full-featured planetarium program, like Elwood Downey's excellent XEphem (for unix/linux) or Bill Gray's Guide program (for Windows), or any of the many other commercially available programs. It is meant as a tool for planning and carrying out observations.
The source code is messy. I've written a lot of code in my life but I am a novice with Java, so the souce code has many shortcomings and aesthetic flaws (e.g., no consistent capitalization style). It is distributed as one giant file, which is not the usual practice. However, it does run!

About the Program

This program is a re-implementation in Java of the venerable skycalc code, which is a text-only program written entirely in C. A couple of years ago I wrote a graphical user interface for skycalc by wrapping the C routines in Python and implementing the user interface with Python's Tkinter module. One version of this also has a sky display, which uses the Python wrapper around PGPLOT. This has proven extremely useful, but the software dependencies make installation complicated (and probably impossible on Windows), so I undertook the present effort for the sake of portability.

Accuracy. A rough extrapolation of delta-T is used for the time argument of the lunar and solar calculations. The sun should be good to 1 arcsecond or so, the moon to a few arcseconds. Comparison with the JPL ephemerides shows that the barycentric corrections are good to a few meters per second in velocity and a few hundredths of a second in time. The precession routine used conforms to the IAU 1976 resolutions, and is not as rigorous as the 2000 conventions; the penalty in accuracy is of order 0.1 arcsecond. As noted above, the planetary ephemerides are only accurate enough for rough purposes. The text-based Skycalc program has an extensive manual describing the algorithms used; the present Java code uses the same algorithms (and gives identical results as far as I have been able to test).

Legalities. I am offering this program freely but claim copyright. Anyone may copy and modify the code, provided that the credit banner with my name and institutional affiliation is not altered. Although I have been careful to ensure that the code is correct, I make no claim that it will always be correct or sufficiently accurate. I also make no claim that it will be suitable for your application. This code should never be relied for applications in which personal safety might be an issue, and it should not be considered authoritative for legal purposes.

I will not be able to answer all queries, but if you believe there is a bug, or have a suggestion for an improvement, or just want to comment, please do email me (john dot thorstensen at dartmouth dot edu).