Index of Functions: A B C D E F G H I J K L M N O P Q R S T U V W X
Index Page ltime_c

Table of contents

Procedure Abstract Required_Reading Keywords Brief_I/O Detailed_Input | Detailed_Output Parameters Exceptions Files Particulars Examples | Restrictions Literature_References Author_and_Institution Version Index_Entries

#### Procedure

       ltime_c ( Light Time )

       void ltime_c ( SpiceDouble        etobs,
                      SpiceInt           obs,
                      ConstSpiceChar   * dir,
                      SpiceInt           targ,
                      SpiceDouble      * ettarg,
                      SpiceDouble      * elapsd  )

#### Abstract

       Compute the transmission (or reception) time of a signal at a
       specified target, given the reception (or transmission) time at a
       specified observer. Also return the elapsed time between
       transmission and reception.

#### Required_Reading

       None.

#### Keywords

       SPK

#### Brief_I/O

       VARIABLE  I/O  DESCRIPTION
       --------  ---  --------------------------------------------------
       etobs      I   Epoch of a signal at some observer.
       obs        I   NAIF ID of some observer.
       dir        I   Direction the signal travels ( "->" or "<-" ).
       targ       I   NAIF ID of the target object.
       ettarg     O   Epoch of the signal at the target.
       elapsd     O   Time between transmit and receipt of the signal.

#### Detailed_Input

       etobs       is an epoch expressed as ephemeris seconds past J2000
                   TDB. This is the time at which an electromagnetic
                   signal is "at" the observer.

       obs         is the NAIF ID of some observer.

       dir         is the direction the signal travels. The
                   acceptable values are "->" and "<-". When
                   you read the calling sequence from left to
                   right, the "arrow" given by `dir' indicates
                   which way the electromagnetic signal is traveling.

                   If the argument list reads as below,

                      ..., `obs', "->", `targ', ...

                   the signal is traveling from the observer to the
                   target.

                   If the argument reads as

                      ..., `obs', "<-", `targ'

                   the signal is traveling from the target to
                   the observer.

       targ        is the NAIF ID of the target.

#### Detailed_Output

       ettarg      is the epoch expressed as ephemeris seconds past J2000
                   TDB at which the electromagnetic signal is "at" the
                   target body.

                   Note `ettarg' is computed using only Newtonian
                   assumptions about the propagation of light.

       elapsd      is the number of ephemeris seconds (TDB) between
                   transmission and receipt of the signal.

                   `elapsd' is computed as:

                      elapsd = fabs( etobs - ettarg )

#### Parameters

       None.

#### Exceptions

       1)  If `dir' is not one of "->" or "<-", the error
           SPICE(BADDIRECTION) is signaled by a routine in the call tree
           of this routine. In this case `ettarg' and `elapsd' will not be
           altered from their input values.

       2)  If insufficient ephemeris information is available to
           compute the outputs `ettarg' and `elapsd', or if observer
           or target is not recognized, an error is signaled
           by a routine in the call tree of this routine.

           In this case, the value of `ettarg' will be set to `etobs'
           and `elapsd' will be set to zero.

       3)  If the `dir' input string pointer is null, the error
           SPICE(NULLPOINTER) is signaled.

       4)  If the `dir' input string has zero length, the error
           SPICE(EMPTYSTRING) is signaled.

#### Files

       None.

#### Particulars

       Suppose a radio signal travels between two solar system objects.
       Given an ephemeris for the two objects, which way the signal is
       traveling, and the time when the signal is "at" at one of the
       objects (the observer obs), this routine determines when the signal
       is "at" the other object (the target targ).  It also returns the
       elapsed time between transmission and receipt of the signal.

#### Examples

       1) Suppose a signal is transmitted at time et from the Goldstone
          tracking site (ID code 399001) to a spacecraft whose ID code
          is -77.

             signal traveling to spacecraft
             *  -._.-._.-._.-._.-._.-._.-._.-._.->  *

             Goldstone (obs=399001)            Spacecraft (targ = -77)
             at epoch etobs(given)             at epoch ettarg(unknown)

          Assuming that all of the required SPICE kernels have been
          loaded, the code fragment below shows how to compute the
          time (arrive) at which the signal arrives at the spacecraft
          and how long (howlng) it took the signal to reach the spacecraft.
          (Note that we display the arrival time as the number of seconds
          past J2000.)

             #include <stdio.h>
             #include "SpiceUsr.h"
                   .
                   .
                   .
             #define  OBS            399001
             #define  TARG           -77
             #define  LENOUT         81
             #define  OBSUTC         "1999 May 25"
             #define  LSK            "leapseconds.ker"

             SpiceChar               timestr [ LENOUT ];

             SpiceDouble             arrive;
             SpiceDouble             howlng;
             SpiceDouble             etobs;
             SpiceDouble             sent;

             [ load kernels ]

             str2et_c ( OBSUTC, &etobs );

             ltime_c ( etobs,   OBS,    "->",   TARG,  &arrive, &howlng );
             etcal_c ( arrive,  LENOUT, timestr );

             printf ( "The signal arrived at time: %s\n",       timestr );
             printf ( "It took %15.6f seconds to get there.\n", howlng  );

       2) Suppose a signal is received at the Goldstone tracking sight
          at epoch ET from the spacecraft of the previous example.

                  signal sent from spacecraft
             *  <-._.-._.-._.-._.-._.-._.-._.-._.- *

             Goldstone (OBS=399001)               Spacecraft (TARG = -77)
             at epoch ETOBS(given)                at epoch ETTARG(unknown)

          Again assuming that all the required kernels have been loaded
          the code fragment below computes the epoch at which the
          signal was transmitted from the spacecraft.

             ltime_c ( etobs,   OBS,    "<-",   TARG,  &sent, &howlng );
             etcal_c ( sent,    LENOUT, timestr );

             printf ( "The signal was transmitted at: %s\n",    timestr );
             printf ( "It took %15.6f seconds to get there.\n", howlng );

       3) Suppose there is a transponder on board the spacecraft of
          the previous examples that transmits a signal back to the
          sender exactly 1 microsecond after a signal arrives at
          the spacecraft. If we send a signal from Goldstone
          to the spacecraft and wait to receive it at Canberra.
          What will be the epoch at which the return signal arrives
          in Canberra? ( The ID code for Canberra is 399002 ).

          Again, assuming we've loaded all the necessary kernels,
          the fragment below will give us the answer.

             #define   GSTONE        399001
             #define   SC            -77
             #define   CANBER        399002

             str2et_c ( OBSUTC, &etgold );

             ltime_c ( etgold, GSTONE, "->", SC, &scget, &lt1 );

             /.
             Account for the microsecond delay between receipt and
             transmission.
             ./
             scsend = scget + 0.000001;

             ltime_c ( scsend, SC, "->", CANBER, &etcanb, &lt2 );

             rndtrp = etcanb - etgold;

             printf ( "The  signal arrives in Canberra at ET: %15.6f\n"
                      "Round trip time for the signal was:    %15.6f\n",
                      etcanb,
                      rndtrp                                            );

#### Restrictions

       None.

#### Literature_References

       None.

#### Author_and_Institution

       N.J. Bachman        (JPL)
       J. Diaz del Rio     (ODC Space)
       W.L. Taber          (JPL)

#### Version

       -CSPICE Version 1.0.2, 01-NOV-2021 (JDR)

           Edited the header to comply with NAIF standard.

       -CSPICE Version 1.0.1, 09-NOV-2006 (NJB)

           Corrected a reference to the function j2000_c; this had been
           erroneously changed from the name J2000 to j2000_c
           during translation from Fortran.

           Re-ordered header sections to conform to standard.

       -CSPICE Version 1.0.0, 29-MAY-1999 (WLT) (NJB)

#### Index_Entries

       Compute uplink and downlink light time

#### Link to routine ltime_c source file ltime_c.c

    Fri Dec 31 18:41:09 2021