/********************************************************/
/*                         radec.h                      */
/*  Header file for utility functions which are useful  */
/*           for objects with known RA and Dec.         */
/********************************************************/

/* Length of string needed to hold RA and Dec in text   */
/* form (see radec_text below):                         */
#define RADEC_TEXTLEN 31

/*--------------------- radec_sethoriz -------------------
 * Description: Sets altitude which object must exceed
 *              in order to be regarded as visible.
 *
 * Parameters:  REAL altitude -- altitude in radians.
 * Returns:     void.
 * Other info:  Call before the first call to radec_phenomena.
 *              Do not call in mid calculation.
 */

  void radec_sethoriz(REAL altitude);


/*---------------------- radec_altaz ---------------------
 * Description: Converts from Right Ascension and Dec-
 *              lination to Altitude and Azimuth.
 *
 * Parameters:  REAL ra  -- right ascension.
 *              REAL dec -- declination.
 *              observerstr *ob_ptr -- pointer to observerstr containing
 *                                     details of location.
 *              REAL sid      -- local siderial time at time and
 *                               location required.
 *              REAL *altptr  -- pointer to REAL to fill
 *                               in with altitude.
 *              REAL *azimptr -- pointer to REAL to fill
 *                               in with azimuth.
 * Returns:     void.
 * Other info:  All angles in radians.
 *              The following fields of the observerstr must be valid:
 *              latit.
 */

void radec_altaz(REAL ra, REAL dec, observerstr *ob_ptr, REAL sid,
                 REAL *altptr, REAL *azimptr);


/*--------------------- radec_phenomena ------------------
 * Description: Determines whether object rises, sets or
 *              culminates on the current day.
 *
 * Parameters:  REAL ra  -- right ascension.
 *              REAL dec -- declination.
 *              observerstr *ob_ptr -- pointer to observerstr containing
 *                                     details of location.
 *              double *chp -- pointer to double to fill
 *                             in with cosine of hour
 *                             angle at horizon.
 *              BOOL *riset_ptr -- filled in with TRUE if object
 *                                 rises and sets, FALSE otherwise.
 *              BOOL *cul_ptr   -- filled in with TRUE if object
 *                                 culminates, FALSE otherwise.
 * Returns:     void.
 * Other info:  All angles in radians.
 *              *chp is an intermediate result needed by rise_details
 *              and set_details.  It is only valid if *riset_ptr is TRUE.
 *              The following fields of the observerstr must be valid:
 *              latit.
 */

void radec_phenomena(REAL ra, REAL dec, observerstr *ob_ptr,
                     double *chp, BOOL *riset_ptr, BOOL *cul_ptr);


/*------------------- radec_cul_details ------------------
 * Description: Determines details of culmination.
 *
 * Parameters:  REAL ra  -- right ascension.
 *              REAL dec -- declination.
 *              observerstr *ob_ptr -- pointer to observerstr containing
 *                                     details of location and the relation-
 *                                     ship between civil and local siderial
 *                                     time.
 *              REAL *al -- pointer to REAL to fill in with
 *                          altitude of culmination.
 *              REAL *az -- pointer to REAL to fill in with
 *                          azimuth of culmination.
 *              int *hourptr -- pointer to int to fill in with
 *                              hour of culmination.
 *              int *minptr  -- pointer to int to fill in with
 *                              minute of culmination.
 * Returns:     void.
 * Other info:  All angles in radians.
 *              Routine assumes that object does indeed culminate.
 *              The latit field of the observerstr must be valid, and
 *              the sid field must correspond with the hour & min fields.
 */

void radec_cul_details(REAL ra, REAL dec, observerstr *ob_ptr,
                       REAL *al, REAL *az, int *hourptr, int *minptr);


/*------------------- radec_rise_details ------------------
 * Description: Determines details of rising.
 *
 * Parameters:  REAL ra   -- right ascension.
 *              REAL dec  -- declination.
 *              observerstr *ob_ptr -- pointer to observerstr containing
 *                                     details of location and the relation-
 *                                     ship between civil and local siderial
 *                                     time.
 *              double ch -- cosine of hour angle when object is
 *                           at horizon.
 *              REAL *az  -- pointer to REAL to fill in with
 *                           azimuth of rising.
 *              int *hourptr -- pointer to int to fill in with
 *                              hour of rising.
 *              int *minptr  -- pointer to int to fill in with
 *                              minute of rising.
 * Returns:     void.
 * Other info:  All angles in radians.
 *              Routine assumes that object does indeed rise.
 *              The latit field of the observerstr must be valid, and
 *              the sid field must correspond with the hour & min fields.
 */

void radec_rise_details(REAL ra, REAL dec, observerstr *ob_ptr,
                        double ch, REAL *az, int *hourptr, int *minptr);


/*------------------- radec_set_details ------------------
 * Description: Determines details of setting.
 *
 * Parameters:  REAL ra   -- right ascension.
 *              REAL dec  -- declination.
 *              observerstr *ob_ptr -- pointer to observerstr containing
 *                                     details of location and the relation-
 *                                     ship between civil and local siderial
 *                                     time.
 *              double ch -- cosine of hour angle when object is
 *                           at horizon.
 *              REAL *az  -- pointer to REAL to fill in with
 *                           azimuth of setting.
 *              int *hourptr -- pointer to int to fill in with
 *                              hour of setting.
 *              int *minptr  -- pointer to int to fill in with
 *                              minute of setting.
 * Returns:     void.
 * Other info:  All angles in radians.
 *              Routine assumes that object does indeed set.
 *              The latit field of the observerstr must be valid, and
 *              the sid field must correspond with the hour & min fields.
 */

void radec_set_details(REAL ra, REAL dec, observerstr *ob_ptr,
                       double ch, REAL *az, int *hourptr, int *minptr);



/*--------------------- radec_text -----------------------
 * Description: Builds a text string giving the specified RA
 *              and Dec in conventional units.
 *
 * Parameters:  REAL ra       -- Right Ascension in radians, in the range
 *                               0 <= ra < 2 PI.
 *              REAL dec      -- Declination in radians, in the range
 *                               -PI/2 <= dec <= PI/2 (South negative).
 *              char *textptr -- pointer to string to receive text.
 *                               String must be RADEC_TEXTLEN long at least.
 * Returns:     void.
 * Other info:  see above for macro RADEC_TEXTLEN.
 */

void radec_text(REAL ra, REAL dec, char *textptr);
