001    package edu.nrao.sss.astronomy;
002    
003    import edu.nrao.sss.geom.EarthPosition;
004    import edu.nrao.sss.measure.LocalSiderealTime;
005    
006    /**
007     * A converter of sky positions to other celestial coordinate systems.
008     * <p>
009     * <b>Version Info:</b>
010     * <table style="margin-left:2em">
011     *   <tr><td>$Revision: 1132 $</td></tr>
012     *   <tr><td>$Date: 2008-02-29 09:29:02 -0700 (Fri, 29 Feb 2008) $</td></tr>
013     *   <tr><td>$Author: dharland $</td></tr>
014     * </table></p>
015     * 
016     * @author David M. Harland
017     * @since 2007-04-13
018     */
019    public interface CelestialCoordinateConverter
020    {
021      /**
022       * Returns a new position that is equivalent to {@code position},
023       * but in the given coordinate system and epoch.
024       * 
025       * @param position
026       *   the position to be converted.
027       *   
028       * @param toSystem
029       *   the coordinate system for the returned position.
030       *   
031       * @param toEpoch
032       *   the epoch for the returned position.  Unless the <tt>toSystem</tt> is
033       *   <tt>EQUATORIAL</tt>, this value will probably not be used.
034       *   
035       * @param observer
036       *   the location of the the observer.  Unless one of the coordinate systems
037       *   is <tt>HORIZONTAL</tt>, this value will probably not be used.
038       *   
039       * @param lst
040       *   the local sidereal time at the observer's location.
041       *   This value is important when one of the coordinate systems is
042       *   <tt>HORIZONTAL</tt>.  However, it can be used for <i>all</i>
043       *   systems in order to get the coordinates of <tt>position</tt>
044       *   at a particular point in time.  If this value is <i>null</i>
045       *   and neither of the coordinate systems is <tt>HORIZONTAL</tt>,
046       *   the coordinates of <tt>position</tt> will be determined as
047       *   of the time on the system clock. 
048       * 
049       * @return
050       *   a new position that is equivalent to {@code position},
051       *   but is expressed in a coordinate system of {@code toSystem}
052       *   for epoch {@code toEpoch}.
053       *         
054       * @throws CoordinateConversionException
055       *   if anything goes wrong during conversion.
056       */
057      public SkyPosition createFrom(SkyPosition               position,
058                                    CelestialCoordinateSystem toSystem,
059                                    Epoch                     toEpoch,
060                                    EarthPosition             observer,
061                                    LocalSiderealTime         lst)
062        throws CoordinateConversionException;
063    }