View source for AstroCC Coordinate Converter for Astronomy

<center>Karen Collins and John Kielkopf </center>

<center>University of Louisville</center>

AstroCC is available for download from [http://www.astro.louisville.edu/software/astrocc http://www.astro.louisville.edu/software/astrocc].

The current version of AstroCC ...

*Uses Java and runs on any Linux, Mac, and Windows system
*Accesses SIMBAD
*Provides ephemerides for the Moon and major planets
*Provides Julian and barycentric dates and times
*Has been extensively validated


AstroCC is a coordinate conversion utility for astronomy. It accepts an object designation or the coordinates of an object and calculates coordinates in alternative systems, and at different dates, times, and locations. It also provides lunar and bright planet coordinates to aid in planning observations.


==Installation==

You may run AstroCC through your browser, or download a copy of AstroCC.jar from [http://www.astro.louisville.edu/software/astrocc http://www.astro.louisville.edu/software/astrocc].  Depending on your applications and location, you may prefer to change the defaults on first use.  For example, by default the software opens to use the Simbad resolver in the US, but the one in France is better if you are in Europe. Select your location. When you exit and start AstroCC a second time, the defaults will be replaced by your new selections.  


'''Browser'''


First, on most systems simply click the link to the "webstart" file on our server:

<center>[http://www.astro.louisville.edu/software/astrocc/astrocc.jnlp http://www.astro.louisville.edu/software/astrocc/astrocc.jnlp]</center>


Second,  if it does not work test whether you have a working recent version of Java installed:

<center>[http://www.java.com/en/download/help/testvm.xml Java Browser Test]</center>


Third, if your computer has the Java Run Time Environment installed, your browser should detect the file type and start a copy of AstroCC on your system. In some cases you may be asked what to use to run the program.  Try "/usr/bin/javaws" on Linux systems that have the Sun version of Java installed. We have found that setting "javaws" as the application to open all files with an extension "jnlp" on systems that couple the file selection to the browser will make this automatic.  Typically this is for OpenSuse vesions of Linux.

Google's Chrome browser will store the file by default rather than run it.  After you have stored it, right click the file name at the bottom of the Google Chrome browser window, and select the check box that says "Always Open Files of This Type". After that, when you again try to run the software through the web it will start automatically.



'''Linux'''

Run AstroCC from the command line with "java -jar AstroCC.jar". Alternatively, install it system wide:

*As root user, make a directory for the AstroCC source file with "mkdir /usr/local/astrocc" 
*Copy the source into this directory with "cp AstroCC.jar /usr/local/astrocc"
*Create a script called "astrocc" in /usr/local/bin that contains "java -jar /usr/local/astrocc/AstroCC.jar" on one line.
*Make this script executable an any user with "chmod a+x astrocc"
*As a normal user enter "astrocc" on the command line to start the program, or create a graphical icon launcher.


'''MacOS'''

From a terminal on a Mac, as in Linux,  AstroCC can be started by typing "java -jar AstroCC.jar" or creating a link as described above.  It can also be started with a  double-click on the icon for the AstroCC.jar file

'''Windows'''

AstroCC can be started in Windows by double-clicking the AstroCC.jar file

==Overview==

The AstroCC coordinate converter user interface is shown below. The top row shows the current date and time in UT, local time, Julian Date, and local sidereal time (LST) formats. These and other items with a gray background cannot be modified by the user. Tooltips are provided for each item to describe its use and syntax. Tooltips can be disabled under the '''Preferences''' menu.

The desired '''Observatory ID''' should be selected on the second line, and the Latitude, Longitude, and Altitude fields will be updated automatically. Otherwise select “custom” as the observatory ID and enter the latitude and longitude entries directly. Press <Enter> after each entry is typed.

Enter a valid '''SIMBAD object ID''' and press enter. If the object ID and relevant data are found in SIMBAD, the '''Target Proper Motion''' ''Right Ascension (RA)'' and ''Declination (Dec)'' fields and the '''Standard Coordinates J2000''' Equatorial RA and Dec fields will be updated automatically. A green border will be placed around those coordinate fields indicating that they are the active fields from which all other coordinates are calculated. Also, major solar system object names may be entered (Moon, Mercury, Venus, Mars, Jupiter, Saturn, Uranus, Neptune, and Pluto). The '''Epoch of Interest''' ''Equatorial RA'' and ''Dec'' fields will be updated automatically since these objects do not have a (relatively) fixed RA and Dec. While a solar system object name is entered in the Object ID field, the active coordinate fields cannot be changed. To do so, remove the solar system object name from the Object ID field.

Finally, the '''Epoch of Interest''' should be entered. Click the Now button to set the epoch of interest to your computer’s current time. Select Lock to keep the epoch of interest locked to your computer’s time every second. Otherwise, the epoch of interest can be entered as UT date and time, local date and time, Julian Day, Heliocentric Julian Day (HJD) or Barycentric Julian Day (BJD). All other date formats will be calculated from the entered format. The up/down arrows to the left of UTC time can be clicked to increment/decrement the date/time by one step. The time step can be set by right-clicking the up/down arrows or the UTC, Local, or JD time or date fields. The mouse wheel will also increment/decrement time if the pointer is located within one of those fields. Evening and morning nautical twilight start/end times are also shown for the epoch of interest. Click inside these fields or on the adjacent icons to set the current time to the corresponding twilight time. If the epoch of interest falls between evening and morning twilight, the twilight field backgrounds are changed to green.

For accurate dynamical time and coordinate calculations, leap second data must be kept current. To do so, simply press the Update button while connected to the internet and the data will be downloaded into AstroCC and stored along with other program preferences. New leap seconds may be introduced every six months at the end of the day on June 30 and December 31. New leap second announcements are made several months in advance. Simply click the Update button once every 3-6 months to check for an update. If Auto is selected, an appropriate leap second value is determined for the epoch of interest. A green Leap-secs background indicates that the displayed number of leap seconds is from the leap second table. The table is valid from 1/1/1961 though the current epoch. Outside this range, leap seconds must be estimated. To estimate leap seconds, AstroCC uses the formulae of Espenak and Meeus 2006, which cover the range from 1999 BCE to 3000 CE. If the epoch of interest is within this range, the Leap-secs background color is yellow, otherwise the background color is red. If Auto is not selected, the field background is white, and the user can enter a custom number of leap seconds.

Any coordinate pair can be used as the source to calculate all others. Simply type (or cut/paste) the desired coordinates into the appropriate pair of coordinate boxes and press <Enter>. The border for the entered coordinates will become green to remind the user which coordinates are being used as the source for the computation of the other coordinates. For convenience, both coordinates of a pair can be typed (or cut/pasted) into one of the boxes of a pair in sexagesimal format. When <Enter> is pressed, the coordinates will be automatically separated and placed into the appropriate boxes. While a solar system object name is entered in the Object ID field, the active coordinate fields cannot be changed. To do so, remove the solar system object name from the Object ID field.  

The ''Phase-Altitude-Proximity'' section under '''Epoch of Interest''' shows the illuminated portion of the moon at the epoch of interest and the altitude of each solar system object (top number) and the distance from the current object coordinates (bottom number). A green background indicates that observations of the target of interest at the epoch of interest should be minimally affected by the solar system object. Yellow means the objects are near each other, and red means the objects are very near each other. A mouse click on the data field of a particular solar system body will make that object the current object of interest and its full coordinate conversions will be shown in AstroCC.
  
[[File:Astrocc.jpg|600px|center]]

==Numbers, Bases, Formats, and Indicators==

Fields with a gray, green, yellow, or red background cannot be modified by the user. Fields with a white background can be directly modified by the user. The coordinate pair with green borders indicates the active coordinate pair. All other coordinates are calculated based on the active coordinates as the source. Coordinate conversion formulae are not exact, so pressing <Enter> in a new coordinate pair (using the existing values) may result in a slight change to the other computed coordinate pairs.

RA and UT time must be entered in hours. All other coordinate numbers must be entered in degrees. Observatory latitude is in degrees (north positive) and observatory longitude is in degrees (east positive). Proper motion is in SIMBAD milli-arcsec per year (mas/yr) format. UT Date is in YYYY MM DD.DD format. Hour Angle (HA) is reported in the range -12:00:00 to 00:00:00 indicating sidereal hours until the object crosses the meridian and 00:00:00 to 12:00:00 indicating sidereal hours since the meridian crossing. All numbers except UT date can be entered in decimal format (i.e. dd.dddd) or in sexagesimal format (i.e. dd mm ss.ss). To facilitate cut and paste of coordinates from other sources, sexagesimal parsing is very lenient and treats any contiguous set of nonnumeric characters as a delimiter. For convenience, both coordinates of a pair can be typed (or cut/pasted) into one of the boxes of a pair in sexagesimal format. When <Enter> is pressed, the first coordinate will be automatically placed in the left-most box of the pair and the second coordinate will be placed in the right-most box. A decimal format number must be entered directly into its corresponding box.

==Preferences==

Several options are provided under the Preferences pull-down menu at the top of the user window. After closing the program for the first time, a new file named “AstroCC_Prefs.txt” will be created. On Microsoft Windows computers, the file is saved in the same directory as the AstroCC.jar file (AstroCC should be installed in a directory with user write access). On Linux systems, the preferences file will be saved at each users /home/username/astrocc/AsctroCC_Prefs.txt. On an Apple Mac computer, the file is saved at user/home/Library/Preferences/AstroCC_Prefs.txt. This file will automatically reload on startup and allows preferences, leap seconds, and other settings to be maintained across sessions.

==Show coordinates in sexagesimal format==

*deselected – all coordinates are displayed in decimal format (i.e.  dd.dddd or hh.hhhh) 
*selected - all coordinates are displayed in sexagesimal format (i.e. dd:mm:ss.ss or hh:mm:ss.ss)

==Use Harvard SIMBAD Server, deselect to use CDS Server==

*deselected – use the SIMBAD server at the Centre de données astronomiques de Strasbourg (CDS), France 
*selected – use the SIMBAD server at Harvard  

==Use Ohio State BJD Server, deselect to calculate internally== 

*deselected – calculate BJD internally (slightly less accurate, but fast and requires no internet access) 
*selected – use the Ohio State server to calculate BJD (more accurate, but slower and requires internet connectivity)

==Use computer time zone, deselect to manually enter offset from UTC==

*deselected – enter offset from UTC in the Time Zone field 
*selected – use the time zone of the host computer’s internal clock  

==Use 12-hour local clock format, deselect to use 24 hour format== 

*deselected – display Local time in 24-hour format 
*selected – display Local time in 12-hour (AM/PM) format  

==Show local twilight times, deselect for UTC format== 

*deselected – display twilight times in Local format 
*selected – display twilight times in UTC format

==Show tooltips== 

Field-specific help displayed after hovering mouse over a field.

*deselected – deactivates tooltip field specific help 
*selected – enables display of tooltips field specific help

==Include proper motion correction==

*deselected – do not include proper motion correction to Epoch of Interest coordinates 
*selected – include proper motion correction to Epoch of Interest coordinates

==Include precession correction== 

*deselected – do not include precession correction to Epoch of Interest coordinates 
*selected – include proper motion correction to Epoch of Interest coordinates

==Include nutation correction== 

*deselected – do not include nutation correction to Epoch of Interest coordinates 
*selected – include nutation correction to Epoch of Interest coordinates

==Include stellar aberration correction== 

*deselected – do not include nutation correction to Epoch of Interest coordinates 
*selected – include nutation correction to Epoch of Interest coordinates

==Include atmospheric refraction correction to altitude== 

*deselected – do not include atmospheric refraction correction to Epoch of Interest altitude coordinate 
*selected – include atmospheric refraction correction to Epoch of Interest altitude coordinate


==Customizing Observatory Data==

Observatory data is stored in a file named "observatories.txt" within the AstroCC.jar file structure. Using an unzip program, a copy of the file can be extracted and placed in the same directory as the AstroCC.jar file. If this file exists, it will be read with priority over the version in the jar file. The file is a simple tab-delimited file.

New entries should be added separated by tabs in the following sequence on one line:

*Observatory Name
*Observatory Latitude
*Observatory Longitude
*Altitude 

All numeric entries should be entered as decimal numbers (not sexagesimal). Latitude is in degrees (positive north). Longitude is in degrees (positive east). Altitude is in meters above mean sea level.

==About==

Help: Report problems to karen_dot_collins_at_insightbb_dot_com. 

Availability: AstroCC is open source software and is distributed under the terms of the GNU General Public License. It is available from [http://www.astro.louisville.edu/software/astrocc http://www.astro.louisville.edu/software/astrocc].

Credits: Parts of AstroCC are based on XmTel, WCSTools, Nuvola icons, and ImageJ open source software packages. Solar system object coordinate calculations and internal HJD/BJD calculations are based on code adapted from JSkyCalc which was written by John Thorstensen of Dartmouth College. BJD values may also be retrieved from http://astroutils.astronomy.ohio-state.edu/time/utc2bjd.html which is based on Eastman et al. 2010. Coordinate data are obtained from SIMBAD. Leap second data is obtained from the U.S. Naval Observatory at http://maia.usno.navy.mil/ser7/tai-utc.dat. The observatory data were compiled from the ESO website at http://www.eso.org/~ndelmott/obs_sites.htm which credits the U.S. Naval Observatory and the H.M. Nautical Almanac Office. The lunar phase images are adapted from Lunar_libration_with_phase_Oct_2007.gif from Wikimedia Commons (submitted by Tom Ruen).