示例#1
0
文件: swpool_c.c 项目: Dbelsa/coft
   void swpool_c ( ConstSpiceChar    * agent,
                   SpiceInt            nnames,
                   SpiceInt            lenvals,
                   const void        * names   ) 
/*

-Brief_I/O
 
   VARIABLE  I/O  DESCRIPTION 
   --------  ---  -------------------------------------------------- 
   agent      I   The name of an agent to be notified after updates. 
   nnames     I   The number of variables to associate with agent. 
   lenvals    I   Length of strings in the names array.
   names      I   Variable names whose update causes the notice. 
 
-Detailed_Input
 
   agent       is the name of a routine or entry point (agency) that 
               will want to know when a some variables in the kernel 
               pool have been updated. 
 
   nnames      is the number of kernel pool variable names that will 
               be associated with agent. 
 
   lenvals     is the length of the strings in the array names, 
               including the null terminators.  
              
   names       is an array of names of variables in the kernel pool. 
               Whenever any of these is updated, a notice will be 
               posted for agent so that one can quickly check 
               whether needed data has been modified. 
 
-Detailed_Output
 
   None. 
 
-Parameters
 
   None. 
 
-Files
 
   None. 
 
-Exceptions
 
   1) If sufficient room is not available to hold a name or new agent,
      a routine in the call tree for this routine will signal an error.
 
   2) If either of the input string pointers are null, the error 
      SPICE(NULLPOINTER) will be signaled.
      
   3) If any input string agent has length zero, the error 
      SPICE(EMPTYSTRING) will be signaled.
      
   4) The caller must pass a value indicating the length of the strings
      in the names array.  If this value is not at least 2, the error
      SPICE(STRINGTOOSHORT) will be signaled.
      
-Particulars
 
   The kernel pool is a convenient place to store a wide variety of
   data needed by routines in CSPICE and routines that interface with
   CSPICE routines.  However, when a single name has a large quantity
   of data associated with it, it becomes inefficient to constantly
   query the kernel pool for values that are not updated on a frequent
   basis.
 
   This entry point allows a routine to instruct the kernel pool to
   post a message whenever a particular value gets updated. In this
   way, a routine can quickly determine whether or not data it requires
   has been updated since the last time the data was accessed.  This
   makes it reasonable to buffer the data in local storage and update
   it only when a variable in the kernel pool that affects this data
   has been updated.
 
   Note that swpool_c has a side effect.  Whenever a call to swpool_c
   is made, the agent specified in the calling sequence is added to the
   list of agents that should be notified that an update of its
   variables has occurred.  In other words the code
 
       swpool_c ( agent, nnames, lenvals, names   ); 
       cvpool_c ( agent,                  &update ); 
 
   will always return update as SPICETRUE. 
 
   This feature allows for a slightly cleaner use of swpool_c and
   cvpool_c as shown in the example below.  Because swpool_c
   automatically loads agent into the list of agents to notify of a
   kernel pool update, you do not have to include the code for fetching
   the initial values of the kernel variables in the initialization
   portion of a subroutine.  Instead, the code for the first fetch from
   the pool is the same as the code for fetching when the pool is
   updated.
 
-Examples
 
   Suppose that you have an application subroutine, MYTASK, that 
   needs to access a large data set in the kernel pool.  If this 
   data could be kept in local storage and kernel pool queries 
   performed only when the data in the kernel pool has been 
   updated, the routine can perform much more efficiently. 
 
   The code fragment below illustrates how you might make use of this 
   feature. 
 
      #include "SpiceUsr.h"
           .
           .
           .
      /.  
      On the first call to this routine establish those variables 
      that we will want to read from the kernel pool only when 
      new values have been assigned. 
      ./
      if ( first )
      {
         first = SPICEFALSE;
         swpool_c ( "MYTASK", nnames, lenvals, names ); 
      }
 
      /.
      If any of the variables has been updated, fetch them from the
      kernel pool.
      ./    
        
      cvpool_c ( "MYTASK", &update ); 
 
      if ( update )
      {
         for ( i = 0;  i < NVAR;  i++ )
         {
            gdpool_c( MYTASK_VAR[i], 1, NMAX, n[i], val[i], &found[i] );
         }
      }
 
 
-Restrictions
 
   None. 
 
-Literature_References
 
   None. 
 
-Author_and_Institution
 
   N.J. Bachman    (JPL)
   W.L. Taber      (JPL) 
 
-Version
 
   -CSPICE Version 1.3.0, 27-AUG-2002 (NJB)

      Call to C2F_CreateStrArr_Sig replaced with call to C2F_MapStrArr.

   -CSPICE Version 1.2.0, 28-AUG-2001 (NJB)

      Const-qualified input array names.

   -CSPICE Version 1.1.0, 14-FEB-2000 (NJB)

       Calls to C2F_CreateStrArr replaced with calls to error-signaling 
       version of this routine:  C2F_CreateStrArr_Sig.
      
   -CSPICE Version 1.0.0, 05-JUN-1999 (NJB) (WLT)

-Index_Entries
 
   Watch for an update to a kernel pool variable 
   Notify a routine of an update to a kernel pool variable 
-&
*/

{ /* Begin swpool_c */


   /*
   Local variables
   */

   SpiceChar             * fCvalsArr;

   SpiceInt                fCvalsLen;


   /*
   Participate in error tracing.
   */
   chkin_c ( "swpool_c" );


   /*
   Make sure the input string pointer for agent is non-null 
   and that the length is sufficient.  
   */
   CHKFSTR ( CHK_STANDARD, "swpool_c", agent );

   /*
   Make sure the input string pointer for the names array is non-null 
   and that the length lenvals is sufficient.  
   */
   CHKOSTR ( CHK_STANDARD, "swpool_c", names, lenvals );

   /*
   Create a Fortran-style string array.
   */
   C2F_MapStrArr ( "swpool_c", 
                   nnames, lenvals, names, &fCvalsLen,  &fCvalsArr );

   if ( failed_c() )
   {
      chkout_c ( "swpool_c" );
      return;
   }


   /*
   Call the f2c'd routine.
   */
   swpool_ (  ( char       * ) agent,
              ( integer    * ) &nnames,
              ( char       * ) fCvalsArr,
              ( ftnlen       ) strlen(agent),
              ( ftnlen       ) fCvalsLen      );


   /*
   Free the dynamically allocated array.
   */
   free ( fCvalsArr );


   chkout_c ( "swpool_c" );

} /* End swpool_c */
示例#2
0
文件: pckcov_c.c 项目: Dbelsa/coft
   void pckcov_c ( ConstSpiceChar   * pck,
                   SpiceInt           idcode,
                   SpiceCell        * cover   ) 
/*

-Brief_I/O
 
   Variable  I/O  Description 
   --------  ---  -------------------------------------------------- 
   pck        I   Name of PCK file. 
   idcode     I   Class ID code of PCK reference frame. 
   cover     I/O  Window giving coverage in `pck' for `idcode'. 
 
-Detailed_Input
 
   pck            is the name of a binary PCK file.
 
   idcode         is the integer frame class ID code of a PCK reference
                  frame for which data are expected to exist in the
                  specified PCK file.
 
   cover          is an initialized CSPICE window data structure.
                  `cover' optionally may contain coverage data on
                  input; on output, the data already present in `cover'
                  will be combined with coverage found for the
                  reference frame designated by `idcode' in the file
                  `pck'.
 
                  If `cover' contains no data on input, its size and
                  cardinality still must be initialized.
                   
-Detailed_Output
 
   cover          is a CSPICE window data structure which represents
                  the merged coverage for the reference frame having
                  frame class ID `idcode'. This is the set of time
                  intervals for which data for `idcode' are present in
                  the file `pck', merged with the set of time intervals
                  present in `cover' on input.  The merged coverage is
                  represented as the union of one or more disjoint time
                  intervals. The window `cover' contains the pairs of
                  endpoints of these intervals.
 
                  The interval endpoints contained in `cover' are 
                  ephemeris times, expressed as seconds past J2000 
                  TDB. 
 
                  See the Examples section below for a complete 
                  example program showing how to retrieve the 
                  endpoints from `cover'. 
                                     
-Parameters
 
   None. 
 
-Exceptions
 
   1)  If the input file has transfer format, the error  
       SPICE(INVALIDFORMAT) is signaled. 
 
   2)  If the input file is not a transfer file but has architecture 
       other than DAF, the error SPICE(BADARCHTYPE) is signaled. 
 
   3)  If the input file is a binary DAF file of type other than 
       PCK, the error SPICE(BADFILETYPE) is signaled. 
 
   4)  If the PCK file cannot be opened or read, the error will 
       be diagnosed by routines called by this routine. The output 
       window will not be modified. 
 
   5)  If the size of the output window argument COVER is 
       insufficient to contain the actual number of intervals in the 
       coverage window for IDCODE, the error will be diagnosed by 
       routines called by this routine.   
 
   6)  The error SPICE(EMPTYSTRING) is signaled if the input
       string `pck' does not contain at least one character, since the
       input string cannot be converted to a Fortran-style string in
       this case.
      
   7)  The error SPICE(NULLPOINTER) is signaled if the input string
       pointer `pck' is null.

-Files
 
   This routine reads a PCK file. 
 
-Particulars
 
   This routine provides an API via which applications can determine 
   the coverage a specified PCK file provides for a specified 
   PCK class reference frame. 
 
-Examples
 
   1)  This example demonstrates combined usage of pckcov_c and the 
       related PCK utility pckfrm_c. 
 
       Display the coverage for each object in a specified PCK file. 
       Find the set of objects in the file; for each object, find 
       and display the coverage. 
 

          #include <stdio.h>
          #include "SpiceUsr.h"

          int main()
          {
             /.
             Local parameters
             ./
             #define  FILSIZ         256
             #define  MAXIV          1000
             #define  WINSIZ         ( 2 * MAXIV )
             #define  TIMLEN         51
             #define  MAXOBJ         1000

             /.
             Local variables
             ./
             SPICEDOUBLE_CELL        ( cover, WINSIZ );
             SPICEINT_CELL           ( ids,   MAXOBJ );

             SpiceChar               lsk     [ FILSIZ ];
             SpiceChar               pck     [ FILSIZ ];
             SpiceChar               timstr  [ TIMLEN ];

             SpiceDouble             b;
             SpiceDouble             e;

             SpiceInt                i;
             SpiceInt                j;
             SpiceInt                niv;
             SpiceInt                obj;


             /.
             Load a leapseconds kernel for output time conversion.
             PCKCOV itself does not require a leapseconds kernel.
             ./
             prompt_c ( "Name of leapseconds kernel > ", FILSIZ, lsk );
             furnsh_c ( lsk );

             /.
             Get name of PCK file.
             ./
             prompt_c ( "Name of PCK file           > ", FILSIZ, pck    );

             /.
             Find the set of frames in the PCK file. 
             ./
             pckfrm_c ( pck, &ids );

             /.
             We want to display the coverage for each frame. Loop over
             the contents of the ID code set, find the coverage for
             each item in the set, and display the coverage.
             ./
             for ( i = 0;  i < card_c( &ids );  i++  )
             {
                /.
                Find the coverage window for the current frame. 
                Empty the coverage window each time so we don't
                include data for the previous frame.
                ./
                obj  =  SPICE_CELL_ELEM_I( &ids, i );

                scard_c  ( 0,        &cover );
                pckcov_c ( pck, obj, &cover );

                /.
                Get the number of intervals in the coverage window.
                ./
                niv = wncard_c ( &cover );

                /.
                Display a simple banner.
                ./
                printf ( "%s\n", "========================================" );

                printf ( "Coverage for frame %ld\n", obj );

                /.
                Convert the coverage interval start and stop times to TDB
                calendar strings.
                ./
                for ( j = 0;  j < niv;  j++  )
                {
                   /.
                   Get the endpoints of the jth interval.
                   ./
                   wnfetd_c ( &cover, j, &b, &e );

                   /.
                   Convert the endpoints to TDB calendar
                   format time strings and display them.
                   ./
                   timout_c ( b, 
                              "YYYY MON DD HR:MN:SC.### (TDB) ::TDB",  
                              TIMLEN,
                              timstr                                  );

                   printf ( "\n"
                            "Interval:  %ld\n"
                            "Start:     %s\n",
                            j,
                            timstr            );

                   timout_c ( e, 
                              "YYYY MON DD HR:MN:SC.### (TDB) ::TDB",  
                              TIMLEN,
                              timstr                                  );
                   printf ( "Stop:      %s\n", timstr );

                }

             }
             return ( 0 );
          } 
 

   2) Find the coverage for the frame designated by `idcode' 
      provided by the set of PCK files loaded via a metakernel. 
      (The metakernel must also specify a leapseconds kernel.) 
        
         #include <stdio.h>
         #include "SpiceUsr.h"

         int main()
         {

            /.
            Local parameters
            ./
            #define  FILSIZ         256
            #define  LNSIZE         81 
            #define  MAXCOV         100000
            #define  WINSIZ         ( 2 * MAXCOV )
            #define  TIMLEN         51

            /.
            Local variables
            ./
            SPICEDOUBLE_CELL        ( cover, WINSIZ );

            SpiceBoolean            found;

            SpiceChar               file    [ FILSIZ ];
            SpiceChar               idch    [ LNSIZE ];
            SpiceChar               meta    [ FILSIZ ];
            SpiceChar               source  [ FILSIZ ];
            SpiceChar               timstr  [ TIMLEN ];
            SpiceChar               type    [ LNSIZE ];

            SpiceDouble             b;
            SpiceDouble             e;

            SpiceInt                count;
            SpiceInt                handle;
            SpiceInt                i;
            SpiceInt                idcode;
            SpiceInt                niv;


            /.
            Prompt for the metakernel name; load the metakernel.
            The metakernel lists the PCK files whose coverage
            for `idcode' we'd like to determine.  The metakernel
            must also specify a leapseconds kernel.
            ./
            prompt_c ( "Name of metakernel > ", FILSIZ, meta );
            furnsh_c ( meta );

            /.
            Get the ID code of interest. 
            ./
            prompt_c ( "Enter ID code      > ", LNSIZE, idch );
            prsint_c ( idch,  &idcode );

            /.
            Find out how many kernels are loaded.  Loop over the
            kernels:  for each loaded PCK file, add its coverage
            for `idcode', if any, to the coverage window.
            ./
            ktotal_c ( "PCK", &count );

            for ( i = 0;  i < count;  i++  )
            {
               kdata_c  ( i,     "PCK",   FILSIZ,  LNSIZE,   FILSIZ, 
                          file,  type,    source,  &handle,  &found );

               pckcov_c ( file,  idcode,  &cover );
            }

            /.
            Display results. 

            Get the number of intervals in the coverage window.
            ./
            niv = wncard_c ( &cover );

            /.
            Display a simple banner.
            ./
            printf ( "\nCoverage for frame %ld\n", idcode );

            /.
            Convert the coverage interval start and stop times to TDB
            calendar strings.
            ./
            for ( i = 0;  i < niv;  i++  )
            {
               /.
               Get the endpoints of the ith interval.
               ./
               wnfetd_c ( &cover, i, &b, &e );

               /.
               Convert the endpoints to TDB calendar
               format time strings and display them.
               ./
               timout_c ( b, 
                          "YYYY MON DD HR:MN:SC.### (TDB) ::TDB",  
                          TIMLEN,
                          timstr                                  );

               printf ( "\n"
                        "Interval:  %ld\n"
                        "Start:     %s\n",
                        i,
                        timstr            );

               timout_c ( e, 
                          "YYYY MON DD HR:MN:SC.### (TDB) ::TDB",  
                          TIMLEN,
                          timstr                                  );
               printf ( "Stop:      %s\n", timstr );

            }
            return ( 0 );
         }


 
-Restrictions
 
   1) If an error occurs while this routine is updating the window 
      `cover', the window may be corrupted. 
 
-Literature_References
 
   None. 
 
-Author_and_Institution
 
   N.J. Bachman   (JPL) 
 
-Version
 
   -CSPICE Version 1.0.1, 01-JUL-2014 (NJB)

       Updated index entries.

   -CSPICE Version 1.0.0, 30-NOV-2007 (NJB)

-Index_Entries
 
   get coverage window for binary pck reference frame
   get coverage start and stop time for binary pck frame 

-&
*/

{ /* Begin pckcov_c */


   /*
   Participate in error tracing.
   */
   if ( return_c() )
   {
      return; 
   }
   chkin_c ( "pckcov_c" );


   /*
   Check the input string `pck' to make sure the pointer is non-null 
   and the string length is non-zero.
   */
   CHKFSTR ( CHK_STANDARD, "pckcov_c", pck );
   
   /*
   Make sure cell data type is d.p. 
   */
   CELLTYPECHK ( CHK_STANDARD, "pckcov_c", SPICE_DP, cover );

   /*
   Initialize the cell if necessary. 
   */
   CELLINIT ( cover );   

   /*
   Call the f2c'd Fortran routine.
   */
   pckcov_ ( ( char       * ) pck,
             ( integer    * ) &idcode,
             ( doublereal * ) (cover->base),
             ( ftnlen       ) strlen(pck)   );

   /*
   Sync the output cell. 
   */
   if ( !failed_c() )
   {
      zzsynccl_c ( F2C, cover );
   }


   chkout_c ( "pckcov_c" );

} /* End pckcov_c */
示例#3
0
   void frmnam_c ( SpiceInt      frcode,
                   SpiceInt      lenout,
                   SpiceChar *   frname  )
/*

-Brief_I/O
 
   VARIABLE  I/O  DESCRIPTION 
   --------  ---  -------------------------------------------------- 
   frcode     I   an integer code for a reference frame 
   lenout     I   Maximum length of output string.
   frname     O   the name associated with the reference frame. 
 
-Detailed_Input
 
   frcode         is an integer code for a reference frame. 
 
   lenout         is the maximum number of characters that can be 
                  accommodated in the output string.  This count 
                  includes room for the terminating null character.
                  For example, if the maximum allowed length of the 
                  output string, including the terminating null, is 33
                  characters, then lenout should be set to 33.
 
-Detailed_Output
 
   frname      is the name associated with the reference frame. 
               It will be returned left-justified. 
 
               If frcode is not recognized as the name of a 
               known reference frame, frname will be returned 
               as an empty string. 
 
               If frname is not sufficiently long to hold the 
               name, it will be truncated on the right. 
 
               All reference frame names are 32 or fewer characters 
               in length.  Thus declaring frname to be SpiceChar[33] 
               will ensure that the returned name will not be 
               truncated. 
 
-Parameters
 
   None. 
 
-Exceptions
 
   1) If frcode is not recognized as the name of a known reference
      frame, frname will be returned as a blank. 
 
   2) If the output string pointer is null, the error SPICE(NULLPOINTER)
      is signaled.
      
   3) If the output string has length less than two characters, it 
      is too short to contain one character of output data plus a null  
      terminator, so it cannot be passed to the underlying Fortran 
      routine.  In this event, the error SPICE(STRINGTOOSHORT) is
      signaled.
      
   4) If the length of frname (indicated by lenout) is at least two
      characters but not large enough to contain the output string, 
      the output string will be truncated on the right. 
 
-Files
 
   None. 
 
-Particulars
 
   This routine retrieves the name of a reference frame associated 
   with a SPICE frame ID code. 
 
   The ID codes stored locally are scanned for a match with frcode. 
   If a match is found, the name stored locally will be returned 
   as the name for the frame. 
 
   If frcode is not a member of the list of internally stored 
   ID codes, the kernel pool will be examined to see if the 
   variable 
 
      FRAME_idcode_NAME 
 
   is present (where idcode is the decimal character equivalent 
   of frcode).  If the variable is located and it has both 
   character type and dimension 1, the string value of the 
   kernel pool variable is returned as the name of the reference 
   frame. 
 
   Note that because the local information is always examined 
   first and searches of the kernel pool are performed only 
   after exhausting local information, it is not possible to 
   override the local name for any reference frame that is 
   known by this routine. 
 
-Examples
 
   Suppose you needed to create a message concerning a reference 
   frame and wish to use the name of the frame in the message. 
   Suppose further that you have only the frame ID code at your 
   disposal.  You can capture the frame name using this routine 
   as shown here. 
 
      #include "SpiceUsr.h"   
           .
           .
           .
      #define NAMELEN         33
      
      SpiceChar               frname [NAMELEN];
      SpiceInt                frcode;

 
      frmnam_c ( frcode, NAMELEN, frname );
 
      if ( iswhsp_c(frname) )  
      { 
         sprintf ( frname, "%ld", frcode );
      }

      printf ( "Concerning reference frame: %s\n", frname );
 
        [Print the rest of your message.]
        
 
-Restrictions
 
   None. 
 
-Literature_References
 
   None. 
 
-Author_and_Institution
 
   W.L. Taber      (JPL) 
   B.V. Semenov    (JPL) 
   N.J. Bachman    (JPL)
   
-Version
 
   -CSPICE Version 1.0.2, 08-JAN-2014 (BVS) 

       Fixed typo in Examples (frname_c -> frmnam_c). Reordered
       header sections.

   -CSPICE Version 1.0.1, 26-MAR-2003 (NJB) 

       Fixed description of exception (4):  replaced "lenout-1"
       with "lenout."  Removed spurious word "clock" from string
       description.

   -CSPICE Version 1.0.0, 13-AUG-2001 (NJB) (WLT)

-Index_Entries
 
   Frame idcode to frame name translation   

-&
*/

{ /* Begin frmnam_c */


   /*
   Participate in error tracing.
   */
   chkin_c ( "frmnam_c" );

   /*
   Make sure the output frmnam has at least enough room for one output
   character and a null terminator.  Also check for a null pointer.
   */
   CHKOSTR ( CHK_STANDARD, "frmnam_c", frname, lenout );


   /*
   Do the conversion.
   */
   frmnam_ ( ( integer * ) &frcode, 
             ( char    * ) frname, 
             ( ftnlen    ) lenout-1 );
      
   /*
   Convert the Fortran string to a C string by placing a null
   after the last non-blank character.  This operation is valid
   whether or not the CSPICE routine signaled an error.
   */
   F2C_ConvertStr ( lenout, frname );


   chkout_c ( "frmnam_c" );

} /* End frmnam_c */
示例#4
0
   void getelm_c ( SpiceInt         frstyr,
                   SpiceInt         lineln,
                   const void     * lines,
                   SpiceDouble    * epoch,
                   SpiceDouble    * elems   ) 
/*

-Brief_I/O
 
   VARIABLE  I/O  DESCRIPTION 
   --------  ---  -------------------------------------------------- 
   frstyr     I   Year of earliest representable two-line elements.
   lineln     I   Length of strings in lines array.
   lines      I   A pair of "lines" containing two-line elements.
   epoch      O   The epoch of the elements in seconds past J2000. 
   elems      O   The elements converted to SPICE units. 
 
-Detailed_Input
 
   frstyr    is the first year possible for two line elements. Since
             two line elements allow only two digits for the year, some
             conventions must be followed concerning which century the
             two digits refer to.  frstyr is the year of the earliest
             representable elements. The two-digit year is mapped to
             the year in the interval from frstyr to frstyr + 99 that
             has the same last two digits as the two digit year in the
             element set.  For example if frstyr is set to 1960  then
             the two digit years are mapped as shown in the table
             below:
 
             Two-line         Maps to 
             element year 
             
                00            2000 
                01            2001 
                02            2002 
                 .              . 
                 .              . 
                 .              . 
                58            2058 
                59            2059 
               -------------------- 
                60            1960 
                61            1961 
                62            1962 
                 .              . 
                 .              . 
                 .              . 
                99            1999 
 
              Note that if Space Command should decide to represent
              years in 21st century as 100 + the last two digits of the
              year (for example: 2015 is represented as 115) instead of
              simply dropping the first two digits of the year, this
              routine will correctly map the year as long as you set
              frstyr to some value between 1900 and 1999.
 
   lines      is a pair of lines of text that comprise a Space command
              ``two-line element'' set.  lines should be declared
              
                 SpiceChar lines[2][lineln];

              These text lines should be the same as they are presented
              in the two-line element files available from Space
              Command (formerly NORAD). Below is an example of a
              two-line set for TOPEX.
 
   TOPEX 
   1 22076U 92052A   97173.53461370 -.00000038  00000-0  10000-3 0   594 
   2 22076  66.0378 163.4372 0008359 278.7732  81.2337 12.80930736227550 
 
 
                 
 
-Detailed_Output
 
   epoch      is the epoch of the two line elements supplied via 
              the input array lines.  Epoch is returned in TDB 
              seconds past J2000. 
 
   elems      is an array containing the elements from the two line 
              set supplied via the array lines.  The elements are 
              in units suitable for use by the CSPICE routine 
              ev2lin_. 
 
              Also note that the elements XNDD6O and BSTAR 
              incorporate the exponential factor present in the 
              input two line elements in LINES.  (See particulars 
              below. 
 
                  ELEMS [ 0 ] = XNDT2O in radians/minute**2 
                  ELEMS [ 1 ] = XNDD6O in radians/minute**3 
                  ELEMS [ 2 ] = BSTAR 
                  ELEMS [ 3 ] = XINCL  in radians 
                  ELEMS [ 4 ] = XNODEO in radians 
                  ELEMS [ 5 ] = EO 
                  ELEMS [ 6 ] = OMEGAO in radians 
                  ELEMS [ 7 ] = XMO    in radians 
                  ELEMS [ 8 ] = XNO    in radians/minute 
                  ELEMS [ 9 ] = EPOCH of the elements in seconds 
                                past ephemeris epoch J2000. 
 
-Parameters
 
   None. 
 
-Exceptions
 
   No checking of the inputs is performed in this routine. However, this
   routine does call other CSPICE routines. If one of these routines
   detects an error it will diagnose it and signal an error.
 
-Files
 
   You must have loaded a SPICE leapseconds kernel into the 
   kernel pool prior to caling this routine. 
 
-Particulars
 
   This routine parses a Space Command Two-line element set and returns
   the orbital elements properly scaled and in units suitable for use
   by other SPICE software.  Input elements look like the following
 
--------------------------------------------------------------------- 
1 22076U 92052A   97173.53461370 -.00000038  00000-0  10000-3 0   594 
2 22076  66.0378 163.4372 0008359 278.7732  81.2337 12.80930736227550 
--------------------------------------------------------------------- 
^ 
123456789012345678901234567890123456789012345678901234567890123456789 
         1         2         3         4         5         6 
 
   The ``raw'' elements in the first and second lines are marked below.
   Note that in several instances exponents and decimal points are
   implied.  Also note that input units are degrees, degrees/day**n and
   revolutions/day.
 
 
                    DAY OF YEAR             NDD60    BSTAR 
                    vvvvvvvvvvvv            vvvvvv   vvvvvv 
--------------------------------------------------------------------- 
1 22076U 92052A   97173.53461370 -.00000038  00000-0  10000-3 0   594 
--------------------------------------------------------------------- 
                  ^^             ^^^^^^^^^^       ^^       ^^ 
                  YEAR             NDT20          IEXP     IBEXP 
 
 
 
   The ``raw'' elements in the second line are marked below 
                 NODE0            OMEGA             N0 
                 vvvvvvvv         vvvvvvvv          vvvvvvvvvvv 
--------------------------------------------------------------------- 
2 22076  66.0378 163.4372 0008359 278.7732  81.2337 12.80930736227550 
--------------------------------------------------------------------- 
        ^^^^^^^^          ^^^^^^^          ^^^^^^^^ 
        Inclination       Eccentricity     M0 
 
   This routine extracts these values ``inserts'' the implied 
   decimal points and exponents and then converts the inputs 
   to units of radians, radians/minute, radians/minute**2, and 
   radians/minute**3 
 
-Examples
 
   Suppose you have a set of two-line elements and an array containing
   the related geophysical constants necessary to evaluate a state.
   The example below shows how you can use this routine together with
   the routine EV2LIN to propagate a state to an epoch of interest.
 
      #include <string.h>
      #include <stdio.h>
      #include "SpiceUsr.h"
      
      SpiceDouble         et;
      SpiceDouble         epoch;
      SpiceInt            frstyr;
          .
          .
          .
      /.
      The parameters below will make it easier to make assignments 
      to the array GEOPHS required by EV2LIN. 
 
         J2  --- location of J2 
         J3  --- location of J3 
         J4  --- location if J4 
         KE  --- location of KE = sqrt(GM) in eart-radii**1.5/MIN 
         QO  --- location of upper bound of atmospheric model in KM 
         SO  --- location of lower bound of atmospheric model in KM 
         ER  --- location of earth equatorial radius in KM. 
         AE  --- location of distance units/earth radius 
      ./
      
      #define  J2 0   
      #define  J3 1   
      #define  J4 2    
      #define  KE 3   
      #define  QO 4   
      #define  SO 5   
      #define  ER 6   
      #define  AE 7  
 
      /.
      We set the lower bound for the years to be the beginning 
      of the space age. 
      ./
      frstyr  =  1957;
 
      /.
      Read in the next two lines from the text file that contains 
      the two-line elements.  We assume that file has been opened 
      properly and that we have set the ``file pointer'' to the 
      correct location for reading the next set of elements. 
      ./
      
      for ( i = 0; i < 2; i++ )
      {
         fgets ( line[i], lineln, textfile );
         line[i][ strlen(line[i]) ] = '\0';
      }

      getelm_c ( frstyr, lineln, line, &epoch, elems ); 
 
 
      /.
      Set up the geophysical quantities.  At last check these 
      were the values used by Space Command. 
      ./
      
      geophs[ J2 ] =    1.082616e-3; 
      geophs[ J3 ] =   -2.53881e-6; 
      geophs[ J4 ] =   -1.65597e-6; 
      geophs[ KE ] =    7.43669161e-2; 
      geophs[ QO ] =  120.0; 
      geophs[ SO ] =   78.0; 
      geophs[ ER ] = 6378.135; 
      geophs[ AE ] =    1.0; 
      
      
      /.
      Now propagate the state using ev2lin_ to the epoch of 
      interest. 
      ./
      ev2lin_ ( &et, geophs, elems, state ); 
 
 
-Restrictions
 
  The format of the two-line elements suffer from a "millenium"
  problem---only two digits are used for the year of the elements. It
  is not clear how Space Command will deal with this problem as the
  year 2000 comes and goes.  We hope that by adjusting the input frstyr
  you should be able to use this routine well into the 21st century.
  However, since we can't predict how others will resolve the millenium
  problem we can't be sure that our approach will be addequate to deal
  with the problem.
 
  The approach taken to mapping the two-digit year to the full year is
  given by the code below. Here, yr is the integer obtained by parsing
  the two-digit year from the first line of the elements.
 
      begyr = (frstyr/100)*100; 
      year  = begyr + yr;
 
      if ( year < frstyr )  
      {
         year += 100;
      }
 
   This mapping will be changed if future two-line element
   representations make this method of computing the full year
   inaccurate.
 
-Literature_References
 
   None. 
 
-Author_and_Institution
 
   N.J. Bachman    (JPL)
   W.L. Taber      (JPL) 
 
-Version

   -CSPICE Version 1.0.1, 15-NOV-2007 (EDW)
   
      Minor edits to example section; the getelm_c call lacked
      the 'lineln' argument, the use of 'et' implied a pointer
      rather than a value.

   -CSPICE Version 1.0.0, 06-AUG-1999 (NJB) (WLT)

-Index_Entries
 
   Parse two-line elements 
 
-&
*/

{ /* Begin getelm_c */


   /*
   Local constants
   */
   #define NELTS           2
   
   
   /*
   Local variables
   */
   SpiceChar            ** cvalsPtr;
   SpiceChar             * fCvalsArr;

   SpiceInt                i;
   SpiceInt                fCvalsLen;

   SpiceStatus             status;

   /*
   Participate in error tracing.
   */
   chkin_c ( "getelm_c" );


   /*
   Check the input line array for null pointer of insufficient string
   length.
   */
   CHKOSTR ( CHK_STANDARD, "getelm_c", lines, lineln );


   /*
   Convert the input string array to a Fortran-style string array.

   We'll first allocate an array of character pointers to index
   the values, initialize this array, and use it to produce
   a dynamically allocated array of Fortran-style strings.
   */

   cvalsPtr = ( SpiceChar ** ) malloc ( NELTS * sizeof(SpiceChar *) );

   if ( cvalsPtr == 0 )
   {
      setmsg_c ( "Failure on malloc call to create pointer array "
                 "for line values."                              );
      sigerr_c ( "SPICE(MALLOCFAILED)"                           );
      chkout_c ( "getelm_c"                                      );
      return;
   }
   
   for ( i = 0;  i < NELTS;  i++  )
   {
      cvalsPtr[i] =  (SpiceChar *)lines  +  ( i * lineln );
   }
   
   status = C2F_CreateStrArr (  NELTS, 
                                ( ConstSpiceChar ** ) cvalsPtr, 
                                &fCvalsLen, 
                                &fCvalsArr                      );
  /* fCvalsArr[2*fCvalsLen] = '\0'; */
   
   if ( status == SPICEFAILURE )
   {
      free ( cvalsPtr );
      
      setmsg_c ( "C to Fortran string array conversion for `lines' "
                 "failed."                                           );
      sigerr_c ( "SPICE(STRINGCONVERROR)"                            );
      chkout_c ( "getelm_c"                                          );
      return;
   }
   
   /*
   Call the f2c'd routine.
   */
   getelm_ (  ( integer    * ) &frstyr,
              ( char       * ) fCvalsArr,
              ( doublereal * ) epoch,
              ( doublereal * ) elems,
              ( ftnlen       ) fCvalsLen  );
   
   /*
   Clean up all of our dynamically allocated arrays.
   */
   free ( cvalsPtr  );
   free ( fCvalsArr );


   chkout_c ( "getelm_c" );

} /* End getelm_c */
示例#5
0
文件: nplnpt_c.c 项目: Dbelsa/coft
   void nplnpt_c ( ConstSpiceDouble    linpt  [3],
                   ConstSpiceDouble    lindir [3],
                   ConstSpiceDouble    point  [3],
                   SpiceDouble         pnear  [3],
                   SpiceDouble       * dist       ) 

/*

-Brief_I/O
 
   Variable  I/O  Description 
   --------  ---  -------------------------------------------------- 
   linpt, 
   lindir     I   Point on a line and the line's direction vector. 
   point      I   A second point. 
   pnear      O   Nearest point on the line to point. 
   dist       O   Distance between point and pnear. 
 
-Detailed_Input
 
   linpt 
   lindir         are, respectively, a point and a direction vector 
                  that define a line in 3-dimensional space.  The 
                  line is the set of points 
 
                     linpt   +   t * lindir 
 
                  where t is any real number. 
 
   point          is a point in 3-dimensional space. 
 
-Detailed_Output
 
   pnear          is the nearest point on the input line to the input 
                  point. 
 
   dist           is the distance between the input line and input 
                  point. 
 
-Parameters
 
   None. 
 
-Exceptions
 
   1)  If the line direction vector lindir is the zero vector, the 
       error SPICE(ZEROVECTOR) is signaled. 
 
-Files
 
   None. 
 
-Particulars
 
   For every line L and point P, there is a unique closest point 
   on L to P.  Call this closest point C.  It is always true that 
   P - C  is perpendicular to L, and the length of P - C is called 
   the "distance" between P and L. 
 
-Examples
 
   1)  Suppose a line passes through the point ( 1, 2, 3 ) and 
       has direction vector ( 0, 1, 1 ).  We wish to find the 
       closest point on the line to the point ( -6, 9, 10 ).  We 
       can use the code fragment 
 
          #include "SpiceUsr.h"
               .
               .
               .
          LINPT[0]   =  1.0; 
          LINPT[1]   =  2.0; 
          LINPT[2]   =  3.0; 
 
          LINDIR[0]  =  0.0; 
          LINDIR[1]  =  1.0; 
          LINDIR[2]  =  1.0; 
 
          POINT[0]   = -6.0; 
          POINT[1]   =  9.0; 
          POINT[2]   = 10.0; 
 
          nplnpt_c ( linpt, lindir, point, pnear, &dist );
 
 
       After the call, pnear will take the value 
 
          ( 1., 9., 10. ); 
 
       dist will be 7.0. 
 
-Restrictions
 
   None. 
 
-Literature_References
 
   None. 
 
-Author_and_Institution
 
   N.J. Bachman   (JPL) 
 
-Version
 
   -CSPICE Version 1.0.0, 16-AUG-1999 (NJB)

-Index_Entries
 
   distance between point and line 
   nearest point on line to point 
 
-&
*/

{ /* Begin nplnpt_c */

 
   /*
   Local variables
   */
   SpiceDouble             trans [3];
 


   /*
   We need a real direction vector to work with.
   */
   if (  vzero_c (lindir)  )
   {
      chkin_c  ( "nplnpt_c"                           );
      setmsg_c ( "Direction vector must be non-zero." );
      sigerr_c ( "SPICE(ZEROVECTOR)"                  );
      chkout_c ( "nplnpt_c"                           );
      return;
   }
 
 
   /*
   We translate line and input point so as to put the line through
   the origin.  Then the nearest point on the translated line to the
   translated point TRANS is the projection of TRANS onto the line.
   */
   
   vsub_c  ( point,  linpt,  trans );
   vproj_c ( trans,  lindir, pnear );
   vadd_c  ( pnear,  linpt,  pnear );
 
   *dist = vdist_c ( pnear,  point );


} /* End nplnpt_c */
示例#6
0
void gfrr_c ( ConstSpiceChar     * target,
              ConstSpiceChar     * abcorr,
              ConstSpiceChar     * obsrvr,
              ConstSpiceChar     * relate,
              SpiceDouble          refval,
              SpiceDouble          adjust,
              SpiceDouble          step,
              SpiceInt             nintvls,
              SpiceCell          * cnfine,
              SpiceCell          * result  )

/*

-Brief_I/O

   Variable  I/O  Description
   --------  ---  --------------------------------------------------
   SPICE_GF_CNVTOL   P   Convergence tolerance
   target            I   Name of the target body.
   abcorr            I   Aberration correction flag.
   obsrvr            I   Name of the observing body.
   relate            I   Relational operator.
   refval            I   Reference value.
   adjust            I   Adjustment value for absolute extrema searches.
   step              I   Step size used for locating extrema and roots.
   nintvls           I   Workspace window interval count.
   cnfine           I-O  SPICE window to which the search is confined.
   result            O   SPICE window containing results.

-Detailed_Input

   target      is the name of a target body. The target body is
               an ephemeris object; its trajectory is given by
               SPK data.

               The string `target' is case-insensitive, and leading
               and trailing blanks in `target' are not significant.
               Optionally, you may supply a string containing the
               integer ID code for the object. For example both
               "MOON" and "301" are legitimate strings that indicate
               the Moon is the target body.

               The target and observer define a position vector which
               points from the observer to the target; the time derivative
               length of this vector is the "range rate" that serves as
               the subject of the search performed by this routine.


   abcorr      indicates the aberration corrections to be applied to
               the observer-target state vector to account for
               one-way light time and stellar aberration.

               Any aberration correction accepted by the SPICE
               routine spkezr_c is accepted here. See the header
               of spkezr_c for a detailed description of the
               aberration correction options. For convenience,
               the options are listed below:

                  "NONE"     Apply no correction.

                  "LT"       "Reception" case:  correct for
                             one-way light time using a Newtonian
                             formulation.

                  "LT+S"     "Reception" case:  correct for
                             one-way light time and stellar
                             aberration using a Newtonian
                             formulation.

                  "CN"       "Reception" case:  converged
                             Newtonian light time correction.

                  "CN+S"     "Reception" case:  converged
                             Newtonian light time and stellar
                             aberration corrections.

                  "XLT"      "Transmission" case:  correct for
                             one-way light time using a Newtonian
                             formulation.

                  "XLT+S"    "Transmission" case:  correct for
                             one-way light time and stellar
                             aberration using a Newtonian
                             formulation.

                  "XCN"      "Transmission" case:  converged
                             Newtonian light time correction.

                  "XCN+S"    "Transmission" case:  converged
                             Newtonian light time and stellar
                             aberration corrections.

               Case and blanks are not significant in the string
               `abcorr'.

   obsrvr      is the name of the observing body. The observing body is
               an ephemeris object; its trajectory is given by SPK
               data. `obsrvr' is case-insensitive, and leading and
               trailing blanks in `obsrvr' are not significant.
               Optionally, you may supply a string containing the
               integer ID code for the object. For example both "MOON"
               and "301" are legitimate strings that indicate the Moon
               is the observer.

   relate      is a relational operator used to define a constraint
               on observer-target range rate. The result window found
               by this routine indicates the time intervals where
               the constraint is satisfied. Supported values of
               `relate' and corresponding meanings are shown below:

                  ">"      Distance is greater than the reference
                           value `refval'.

                  "="      Distance is equal to the reference
                           value `refval'.

                  "<"      Distance is less than the reference
                           value `refval'.


                 "ABSMAX"  Distance is at an absolute maximum.

                 "ABSMIN"  Distance is at an absolute  minimum.

                 "LOCMAX"  Distance is at a local maximum.

                 "LOCMIN"  Distance is at a local minimum.

              The caller may indicate that the region of interest
              is the set of time intervals where the quantity is
              within a specified distance of an absolute extremum.
              The argument `adjust' (described below) is used to
              specify this distance.

              Local extrema are considered to exist only in the
              interiors of the intervals comprising the confinement
              window:  a local extremum cannot exist at a boundary
              point of the confinement window.

              Case is not significant in the string `relate'.

    refval    is the reference value used together with the argument
              `relate' to define an equality or inequality to be
              satisfied by the range rate between the specified target
              and observer. See the discussion of `relate' above for
              further information.

              The units of `refval' are km/sec.

   adjust     is a parameter used to modify searches for absolute
              extrema: when `relate' is set to "ABSMAX" or "ABSMIN" and
              `adjust' is set to a positive value, gfdist_c will find
              times when the observer-target range rate is within
              `adjust' km/sec of the specified extreme value.

              If `adjust' is non-zero and a search for an absolute
              minimum `min' is performed, the result window contains
              time intervals when the observer-target range rate has
              values between `min' and min+adjust.

              If the search is for an absolute maximum `max', the
              corresponding range is from max-adjust to `max'.

              `adjust' is not used for searches for local extrema,
              equality or inequality conditions.

   step       is the step size to be used in the search. `step' must
              be short enough for a search using this step size
              to locate the time intervals where the specified
              range rate function is monotone increasing or
              decreasing. However, `step' must not be *too* short, or
              the search will take an unreasonable amount of time.

              The choice of `step' affects the completeness but not
              the precision of solutions found by this routine; the
              precision is controlled by the convergence tolerance.
              See the discussion of the parameter SPICE_GF_CNVTOL for
              details.

              `step' has units of TDB seconds.

   nintvls    is a parameter specifying the number of intervals that
              can be accommodated by each of the dynamically allocated
              windows used internally by this routine. `nintvls' should
              be at least as large as the number of intervals within
              the search region on which the specified range rate
              function is monotone increasing or decreasing. See
              the Examples section below for code examples illustrating
              the use of this parameter.

   cnfine     is a SPICE window that confines the time period over
              which the specified search is conducted. `cnfine' may
              consist of a single interval or a collection of
              intervals.

              In some cases the confinement window can be used to
              greatly reduce the time period that must be searched
              for the desired solution. See the Particulars section
              below for further discussion.

              See the Examples section below for a code example
              that shows how to create a confinement window.

-Detailed_Output

   cnfine     is the input confinement window, updated if necessary
              so the control area of its data array indicates the
              window's size and cardinality. The window data are
              unchanged.


   result     is the window of intervals, contained within the
              confinement window `cnfine', on which the specified
              constraint is satisfied.

              If `result' is non-empty on input, its contents will be
              discarded before 'gfrr_c' conducts its search.

              `result' must be declared with sufficient size to capture
              the full set of time intervals within the search region
              on which the specified constraint is satisfied.

              If the search is for local extrema, or for absolute
              extrema with `adjust' set to zero, then normally each
              interval of `result' will be a singleton: the left and
              right endpoints of each interval will be identical.

              If no times within the confinement window satisfy the
              constraint, `result' will be returned with a cardinality
              of zero.

-Parameters

   SPICE_GF_CNVTOL

              is the convergence tolerance used for finding endpoints
              of the intervals comprising the result window.
              SPICE_GF_CNVTOL is used to determine when binary searches
              for roots should terminate: when a root is bracketed
              within an interval of length SPICE_GF_CNVTOL, the root is
              considered to have been found.

              The accuracy, as opposed to precision, of roots found
              by this routine depends on the accuracy of the input
              data. In most cases, the accuracy of solutions will be
              inferior to their precision.

              SPICE_GF_CNVTOL is declared in the header file SpiceGF.h.

-Exceptions

   1)  In order for this routine to produce correct results,
       the step size must be appropriate for the problem at hand.
       Step sizes that are too large may cause this routine to miss
       roots; step sizes that are too small may cause this routine
       to run unacceptably slowly and in some cases, find spurious
       roots.

       This routine does not diagnose invalid step sizes, except
       that if the step size is non-positive, an error is signaled
       by a routine in the call tree of this routine.

   2)  Due to numerical errors, in particular,

          - Truncation error in time values
          - Finite tolerance value
          - Errors in computed geometric quantities

       it is *normal* for the condition of interest to not always be
       satisfied near the endpoints of the intervals comprising the
       result window.

       The result window may need to be contracted slightly by the
       caller to achieve desired results. The SPICE window routine
       wncond_c can be used to contract the result window.

   3)  If an error (typically cell overflow) occurs while performing
       window arithmetic, the error will be diagnosed by a routine
       in the call tree of this routine.

   4)  If the relational operator `relate' is not recognized, an
       error is signaled by a routine in the call tree of this
       routine.

   5)  If the aberration correction specifier contains an
       unrecognized value, an error is signaled by a routine in the
       call tree of this routine.

   6)  If 'adjust' is negative, the error SPICE(VALUEOUTOFRANGE) will
       signal from a routine in the call tree of this routine.

       A non-zero value for 'adjust' when 'relate' has any value other than
       "ABSMIN" or "ABSMAX" causes the error SPICE(INVALIDVALUE) to
       signal from a routine in the call tree of this routine.

   7)  If either of the input body names do not map to NAIF ID
       codes, an error is signaled by a routine in the call tree of
       this routine.

   8)  If required ephemerides or other kernel data are not
       available, an error is signaled by a routine in the call tree
       of this routine.

   9)  If the workspace interval count is less than 1, the error
       SPICE(VALUEOUTOFRANGE) will be signaled.

   10) If the required amount of workspace memory cannot be
       allocated, the error SPICE(MALLOCFAILURE) will be
       signaled.

   11) If any input string argument pointer is null, the error
       SPICE(NULLPOINTER) will be signaled.

   12) If any input string argument is empty, the error
       SPICE(EMPTYSTRING) will be signaled.

   13) If either input cell has type other than SpiceDouble,
       the error SPICE(TYPEMISMATCH) is signaled.

-Files

   Appropriate kernels must be loaded by the calling program before
   this routine is called.

   The following data are required:

      - SPK data: ephemeris data for target and observer for the
        time period defined by the confinement window must be
        loaded. If aberration corrections are used, the states of
        target and observer relative to the solar system barycenter
        must be calculable from the available ephemeris data.
        Typically ephemeris data are made available by loading one
        or more SPK files via furnsh_c.

   In all cases, kernel data are normally loaded once per program
   run, NOT every time this routine is called.

-Particulars

   This routine determines if the caller-specified constraint condition
   on the geometric event (range rate) is satisfied for any time intervals
   within the confinement window 'cnfine'. If one or more such time
   intervals exist, those intervals are added to the 'result' window.

   This routine provides a simpler, but less flexible interface
   than does the routine gfevnt_c for conducting the searches for
   observer-target range rate value events. Applications that require
   support for progress reporting, interrupt handling, non-default step
   or refinement functions, or non-default convergence tolerance should
   call gfevnt_c rather than this routine.

   Below we discuss in greater detail aspects of this routine's
   solution process that are relevant to correct and efficient
   use of this routine in user applications.


   The Search Process
   ==================

   Regardless of the type of constraint selected by the caller, this
   routine starts the search for solutions by determining the time
   periods, within the confinement window, over which the specified
   range rate function is monotone increasing and monotone decreasing.
   Each of these time periods is represented by a SPICE window. Having
   found these windows, all of the range rate function's local extrema
   within the confinement window are known. Absolute extrema then can
   be found very easily.

   Within any interval of these "monotone" windows, there will be at
   most one solution of any equality constraint. Since the boundary
   of the solution set for any inequality constraint is contained in
   the union of

      - the set of points where an equality constraint is met
      - the boundary points of the confinement window

   the solutions of both equality and inequality constraints can be
   found easily once the monotone windows have been found.


   Step Size
   =========

   The monotone windows (described above) are found via a two-step
   search process. Each interval of the confinement window is
   searched as follows: first, the input step size is used to
   determine the time separation at which the sign of the rate of
   change of range rate  will be sampled. Starting at
   the left endpoint of an interval, samples will be taken at each
   step. If a change of sign is found, a root has been bracketed; at
   that point, the time at which the range rate is zero can be
   found by a refinement process, for example, via binary search.

   Note that the optimal choice of step size depends on the lengths
   of the intervals over which the range rate function is monotone:
   the step size should be shorter than the shortest of these
   intervals (within the confinement window).

   The optimal step size is *not* necessarily related to the lengths
   of the intervals comprising the result window. For example, if
   the shortest monotone interval has length 10 days, and if the
   shortest result window interval has length 5 minutes, a step size
   of 9.9 days is still adequate to find all of the intervals in the
   result window. In situations like this, the technique of using
   monotone windows yields a dramatic efficiency improvement over a
   state-based search that simply tests at each step whether the
   specified constraint is satisfied. The latter type of search can
   miss solution intervals if the step size is longer than the
   shortest solution interval.

   Having some knowledge of the relative geometry of the target and
   observer can be a valuable aid in picking a reasonable step size.
   In general, the user can compensate for lack of such knowledge by
   picking a very short step size; the cost is increased computation
   time.

   Note that the step size is not related to the precision with which
   the endpoints of the intervals of the result window are computed.
   That precision level is controlled by the convergence tolerance.


   Convergence Tolerance
   =====================

   As described above, the root-finding process used by this routine
   involves first bracketing roots and then using a search process to
   locate them.  "Roots" include times when extrema are attained and
   times when the geometric quantity function is equal to a reference
   value or adjusted extremum. All endpoints of the intervals comprising
   the result window are either endpoints of intervals of the confinement
   window or roots.

   Once a root has been bracketed, a refinement process is used to
   narrow down the time interval within which the root must lie.
   This refinement process terminates when the location of the root
   has been determined to within an error margin called the
   "convergence tolerance." The convergence tolerance used by this
   routine is set via the parameter SPICE_GF_CNVTOL.

   The value of SPICE_GF_CNVTOL is set to a "tight" value so that the
   tolerance doesn't limit the accuracy of solutions found by this
   routine. In general the accuracy of input data will be the limiting
   factor.

   The user may change the convergence tolerance from the default
   SPICE_GF_CNVTOL value by calling the routine gfstol_c, e.g.

      gfstol_c( tolerance value in seconds )

   Call gfstol_c prior to calling this routine. All subsequent
   searches will use the updated tolerance value.

   Searches over time windows of long duration may require use of
   larger tolerance values than the default: the tolerance must be
   large enough so that it, when added to or subtracted from the
   confinement window's lower and upper bounds, yields distinct time
   values.

   Setting the tolerance tighter than SPICE_GF_CNVTOL is unlikely to be
   useful, since the results are unlikely to be more accurate.
   Making the tolerance looser will speed up searches somewhat,
   since a few convergence steps will be omitted. However, in most
   cases, the step size is likely to have a much greater effect
   on processing time than would the convergence tolerance.


   The Confinement Window
   ======================

   The simplest use of the confinement window is to specify a time
   interval within which a solution is sought. However, the
   confinement window can, in some cases, be used to make searches
   more efficient. Sometimes it's possible to do an efficient search
   to reduce the size of the time period over which a relatively
   slow search of interest must be performed.

   Consider the following example: suppose one wishes to find the
   times when the range rate between Io and the Earth attains a global
   minimum over some (lengthy) time interval. There is one local
   minimum every few days. The required step size for this search
   must be smaller than the shortest interval on which the range rate
   is monotone increasing or decreasing; this step size will be less
   than half the average time between local minima. However, we know
   that a global minimum can't occur when the Jupiter-Sun-Earth
   angle is greater than 90 degrees. We can use a step size of a
   half year to find the time period, within our original time
   interval, during which this angle is less than 90 degrees; this
   time period becomes the confinement window for our Earth-Io
   range rate search. This way we've used a quick (due to the large
   step size) search to cut out about half of the search period over
   which we must perform a slower search using a small step size.

-Examples

   The numerical results shown for these examples may differ across
   platforms. The results depend on the SPICE kernels used as
   input, the compiler and supporting libraries, and the machine
   specific arithmetic implementation.

      Use the meta-kernel shown below to load the required SPICE
      kernels.

         KPL/MK

         File name: standard.tm

         This meta-kernel is intended to support operation of SPICE
         example programs. The kernels shown here should not be
         assumed to contain adequate or correct versions of data
         required by SPICE-based user applications.

         In order for an application to use this meta-kernel, the
         kernels referenced here must be present in the user's
         current working directory.

         The names and contents of the kernels referenced
         by this meta-kernel are as follows:

            File name                     Contents
            ---------                     --------
            de421.bsp                     Planetary ephemeris
            pck00009.tpc                  Planet orientation and
                                          radii
            naif0009.tls                  Leapseconds

         \begindata

            KERNELS_TO_LOAD = ( 'de421.bsp',
                                'pck00009.tpc',
                                'naif0009.tls'  )

         \begintext

   Example:

      Determine the time windows from January 1, 2007 UTC to
      April 1, 2007 UTC for which the sun-moon range rate satisfies the
      relation conditions with respect to a reference value of
      0.3365 km/s radians (this range rate known to occur within the
      search interval). Also determine the time windows corresponding
      to the local maximum and minimum range rate, and the absolute
      maximum and minimum range rate during the search interval.

      #include <stdio.h>
      #include <stdlib.h>
      #include <string.h>

      #include "SpiceUsr.h"

      #define       MAXWIN    20000
      #define       TIMFMT    "YYYY-MON-DD HR:MN:SC.###"
      #define       TIMLEN    41
      #define       NLOOPS    7

      int main( int argc, char **argv )
         {

         /.
         Create the needed windows. Note, one window
         consists of two values, so the total number
         of cell values to allocate is twice
         the number of intervals.
         ./
         SPICEDOUBLE_CELL ( result, 2*MAXWIN );
         SPICEDOUBLE_CELL ( cnfine, 2        );

         SpiceDouble       begtim;
         SpiceDouble       endtim;
         SpiceDouble       step;
         SpiceDouble       adjust;
         SpiceDouble       refval;
         SpiceDouble       beg;
         SpiceDouble       end;

         SpiceChar         begstr [ TIMLEN ];
         SpiceChar         endstr [ TIMLEN ];

         SpiceChar       * target = "MOON";
         SpiceChar       * abcorr = "NONE";
         SpiceChar       * obsrvr = "SUN";

         SpiceInt          count;
         SpiceInt          i;
         SpiceInt          j;

         ConstSpiceChar * relate [NLOOPS] = { "=",
                                              "<",
                                              ">",
                                              "LOCMIN",
                                              "ABSMIN",
                                              "LOCMAX",
                                              "ABSMAX",
                                            };

         /.
         Load kernels.
         ./
         furnsh_c( "standard.tm" );

         /.
         Store the time bounds of our search interval in
         the cnfine confinement window.
         ./
         str2et_c( "2007 JAN 01", &begtim );
         str2et_c( "2007 APR 01", &endtim );

         wninsd_c ( begtim, endtim, &cnfine );

         /.
         Search using a step size of 1 day (in units of seconds).
         The reference value is .3365 km/s. We're not using the
         adjustment feature, so we set 'adjust' to zero.
         ./
         step   = spd_c();
         adjust = 0.;
         refval = .3365;

         for ( j = 0;  j < NLOOPS;  j++ )
            {

            printf ( "Relation condition: %s \n",  relate[j] );

            /.
            Perform the search. The SPICE window 'result' contains
            the set of times when the condition is met.
            ./
            gfrr_c ( target,
                     abcorr,
                     obsrvr,
                     relate[j],
                     refval,
                     adjust,
                     step,
                     MAXWIN,
                     &cnfine,
                     &result );

            count = wncard_c( &result );

            /.
            Display the results.
            ./
            if (count == 0 )
               {
               printf ( "Result window is empty.\n\n" );
               }
            else
               {
               for ( i = 0;  i < count;  i++ )
                  {

                  /.
                  Fetch the endpoints of the Ith interval
                  of the result window.
                  ./
                  wnfetd_c ( &result, i, &beg, &end );

                  timout_c ( beg, TIMFMT, TIMLEN, begstr );
                  timout_c ( end, TIMFMT, TIMLEN, endstr );

                  printf ( "Start time, drdt = %s \n", begstr );
                  printf ( "Stop time,  drdt = %s \n", endstr );

                  }

               }

            printf("\n");

            }

         return( 0 );
         }


   The program outputs:

      Relation condition: =
      Start time, drdt = 2007-JAN-02 00:35:19.574
      Stop time,  drdt = 2007-JAN-02 00:35:19.574
      Start time, drdt = 2007-JAN-19 22:04:54.899
      Stop time,  drdt = 2007-JAN-19 22:04:54.899
      Start time, drdt = 2007-FEB-01 23:30:13.428
      Stop time,  drdt = 2007-FEB-01 23:30:13.428
      Start time, drdt = 2007-FEB-17 11:10:46.540
      Stop time,  drdt = 2007-FEB-17 11:10:46.540
      Start time, drdt = 2007-MAR-04 15:50:19.929
      Stop time,  drdt = 2007-MAR-04 15:50:19.929
      Start time, drdt = 2007-MAR-18 09:59:05.959
      Stop time,  drdt = 2007-MAR-18 09:59:05.959

      Relation condition: <
      Start time, drdt = 2007-JAN-02 00:35:19.574
      Stop time,  drdt = 2007-JAN-19 22:04:54.899
      Start time, drdt = 2007-FEB-01 23:30:13.428
      Stop time,  drdt = 2007-FEB-17 11:10:46.540
      Start time, drdt = 2007-MAR-04 15:50:19.929
      Stop time,  drdt = 2007-MAR-18 09:59:05.959

      Relation condition: >
      Start time, drdt = 2007-JAN-01 00:00:00.000
      Stop time,  drdt = 2007-JAN-02 00:35:19.574
      Start time, drdt = 2007-JAN-19 22:04:54.899
      Stop time,  drdt = 2007-FEB-01 23:30:13.428
      Start time, drdt = 2007-FEB-17 11:10:46.540
      Stop time,  drdt = 2007-MAR-04 15:50:19.929
      Start time, drdt = 2007-MAR-18 09:59:05.959
      Stop time,  drdt = 2007-APR-01 00:00:00.000

      Relation condition: LOCMIN
      Start time, drdt = 2007-JAN-11 07:03:58.988
      Stop time,  drdt = 2007-JAN-11 07:03:58.988
      Start time, drdt = 2007-FEB-10 06:26:15.439
      Stop time,  drdt = 2007-FEB-10 06:26:15.439
      Start time, drdt = 2007-MAR-12 03:28:36.404
      Stop time,  drdt = 2007-MAR-12 03:28:36.404

      Relation condition: ABSMIN
      Start time, drdt = 2007-JAN-11 07:03:58.988
      Stop time,  drdt = 2007-JAN-11 07:03:58.988

      Relation condition: LOCMAX
      Start time, drdt = 2007-JAN-26 02:27:33.766
      Stop time,  drdt = 2007-JAN-26 02:27:33.766
      Start time, drdt = 2007-FEB-24 09:35:07.816
      Stop time,  drdt = 2007-FEB-24 09:35:07.816
      Start time, drdt = 2007-MAR-25 17:26:56.150
      Stop time,  drdt = 2007-MAR-25 17:26:56.150

      Relation condition: ABSMAX
      Start time, drdt = 2007-MAR-25 17:26:56.150
      Stop time,  drdt = 2007-MAR-25 17:26:56.150

-Restrictions

   1) The kernel files to be used by this routine must be loaded
      (normally using the CSPICE routine furnsh_c) before this
      routine is called.

   2) This routine has the side effect of re-initializing the
      range rate quantity utility package. Callers may themselves
      need to re-initialize the range rate quantity utility
      package after calling this routine.

-Literature_References

   None.

-Author_and_Institution

   N.J. Bachman   (JPL)
   E.D. Wright    (JPL)

-Version

   -CSPICE Version 1.0.1, 28-FEB-2013 (NJB) (EDW)

      Header was updated to discuss use of gfstol_c.

      Edit to comments to correct search description.

      Edits to Example section, proper description of "standard.tm"
      meta kernel.

   -CSPICE Version 1.0.0, 26-AUG-2009 (EDW) (NJB)

-Index_Entries

 GF range rate search

-&
*/

{   /* Begin gfrr_c */

    /*
    Local variables
    */
    doublereal            * work;

    static SpiceInt         nw = SPICE_GF_NWRR;
    SpiceInt                nBytes;

    /*
    Participate in error tracing.
    */

    chkin_c ( "gfrr_c" );

    /*
    Make sure cell data types are d.p.
    */
    CELLTYPECHK2 ( CHK_STANDARD, "gfrr_c", SPICE_DP, cnfine, result );

    /*
    Initialize the input cells if necessary.
    */
    CELLINIT2 ( cnfine, result );

    /*
    Check the input strings to make sure each pointer is non-null
    and each string length is non-zero.
    */
    CHKFSTR ( CHK_STANDARD, "gfrr_c", target );
    CHKFSTR ( CHK_STANDARD, "gfrr_c", abcorr );
    CHKFSTR ( CHK_STANDARD, "gfrr_c", obsrvr );
    CHKFSTR ( CHK_STANDARD, "gfrr_c", relate );

    /*
    Check the workspace size; some mallocs have a violent
    dislike for negative allocation amounts. To be safe,
    rule out a count of zero intervals as well.
    */

    if ( nintvls < 1 )
    {
        setmsg_c ( "The specified workspace interval count # was "
                   "less than the minimum allowed value of one (1)." );
        errint_c ( "#",  nintvls                              );
        sigerr_c ( "SPICE(VALUEOUTOFRANGE)"                   );
        chkout_c ( "gfrr_c"                                   );
        return;
    }

    /*
    Allocate the workspace. 'nintvls' indicates the maximum number of
    intervals returned in 'result'. An interval consists of
    two values.
    */

    nintvls = 2 * nintvls;

    nBytes  = ( nintvls + SPICE_CELL_CTRLSZ ) * nw * sizeof(SpiceDouble);

    work    = (doublereal *) alloc_SpiceMemory( nBytes );

    if ( !work )
    {
        setmsg_c ( "Workspace allocation of # bytes failed due to "
                   "malloc failure"                               );
        errint_c ( "#",  nBytes                                   );
        sigerr_c ( "SPICE(MALLOCFAILED)"                          );
        chkout_c ( "gfrr_c"                                       );
        return;
    }

    /*
    Let the f2'd routine do the work.
    */

    gfrr_( ( char          * ) target,
           ( char          * ) abcorr,
           ( char          * ) obsrvr,
           ( char          * ) relate,
           ( doublereal    * ) &refval,
           ( doublereal    * ) &adjust,
           ( doublereal    * ) &step,
           ( doublereal    * ) (cnfine->base),
           ( integer       * ) &nintvls,
           ( integer       * ) &nw,
           ( doublereal    * ) work,
           ( doublereal    * ) (result->base),
           ( ftnlen          ) strlen(target),
           ( ftnlen          ) strlen(abcorr),
           ( ftnlen          ) strlen(obsrvr),
           ( ftnlen          ) strlen(relate) );

    /*
    De-allocate the workspace.
    */
    free_SpiceMemory( work );

    /*
    Sync the output cell.
    */
    if ( !failed_c() )
    {
        zzsynccl_c ( F2C, result ) ;
    }

    ALLOC_CHECK;

    chkout_c ( "gfrr_c" );

} /* End gfrr_c */
示例#7
0
   void vprjp_c ( ConstSpiceDouble    vin   [3],
                  ConstSpicePlane   * plane,
                  SpiceDouble         vout  [3] ) 

/*

-Brief_I/O
 
   Variable  I/O  Description 
   --------  ---  -------------------------------------------------- 
   vin        I   Vector to be projected. 
   plane      I   A CSPICE plane onto which vin is projected. 
   vout       O   Vector resulting from projection. 
 
-Detailed_Input
 
   vin            is a 3-vector that is to be orthogonally projected 
                  onto a specified plane. 
 
   plane          is a CSPICE plane that represents the geometric 
                  plane onto which vin is to be projected. 
 
-Detailed_Output
 
   vout           is the vector resulting from the orthogonal 
                  projection of vin onto plane.  vout is the closest 
                  point in the specified plane to vin. 
 
-Parameters
 
   None. 
 
-Exceptions
 
   1)  Invalid input planes are diagnosed by the routine pl2nvc_c, 
       which is called by this routine. 
 
-Files
 
   None. 
 
-Particulars
 
   Projecting a vector v orthogonally onto a plane can be thought of 
   as finding the closest vector in the plane to v.  This `closest 
   vector' always exists; it may be coincident with the original 
   vector. 
 
   Two related routines are vprjpi_c, which inverts an orthogonal 
   projection of a vector onto a plane, and vproj_c, which projects 
   a vector orthogonally onto another vector. 
 
-Examples
 
   1)   Find the closest point in the ring plane of a planet to a 
        spacecraft located at positn (in body-fixed coordinates). 
        Suppose the vector normal is normal to the ring plane, and 
        that origin, which represents the body center, is in the 
        ring plane.  Then we can make a `plane' with the code 
 
           pnv2pl_c ( origin, normal, &plane ); 
 
        can find the projection by making the call 
 
           vprjp_c ( positn, &plane, proj ); 
 
-Restrictions
 
   None. 
 
-Literature_References
 
   [1] `Calculus and Analytic Geometry', Thomas and Finney. 
 
-Author_and_Institution
 
   N.J. Bachman   (JPL) 
 
-Version
 
   -CSPICE Version 1.0.0, 05-MAR-1999 (NJB)

-Index_Entries
 
   vector projection onto plane 
 
-&
*/

{ /* Begin vprjp_c */


   /*
   Local variables
   */
   SpiceDouble             constant;
   SpiceDouble             normal    [3];


   /*
   Participate in error tracing.
   */

   if ( return_c() ) 
   {
      return;
   }
   
   chkin_c ( "vprjp_c" );


   /*
   Obtain a unit vector normal to the input plane, and a constant
   for the plane.
   */
   pl2nvc_c ( plane, normal, &constant );
 
   
   /*
   Let the notation < a, b > indicate the inner product of vectors
   a and b.

   vin differs from its projection onto plane by some multiple of
   normal.  That multiple is


             < vin - vout, normal >                 *  normal

      =   (  < vin, normal > - < vout, normal >  )  *  normal

      =   (  < vin, normal > - const             )  *  normal


   Subtracting this multiple of normal from vin yields vout.
   */
 
   vlcom_c (  1.0,
              vin,
              constant - vdot_c ( vin, normal ),
              normal,
              vout                              );
 
 
   chkout_c ( "vprjp_c" );

} /* End vprjp_c */
示例#8
0
文件: ckcov_c.c 项目: haisamido/GMAT
   void ckcov_c ( ConstSpiceChar    * ck,
                  SpiceInt            idcode,
                  SpiceBoolean        needav,
                  ConstSpiceChar    * level,
                  SpiceDouble         tol,
                  ConstSpiceChar    * timsys,
                  SpiceCell         * cover   ) 
/*

-Brief_I/O
 
   Variable  I/O  Description 
   --------  ---  -------------------------------------------------- 
   ck         I   Name of CK file. 
   idcode     I   ID code of object. 
   needav     I   Flag indicating whether angular velocity is needed. 
   level      I   Coverage level:  "SEGMENT" OR "INTERVAL". 
   tol        I   Tolerance in ticks. 
   timsys     I   Time system used to represent coverage. 
   cover     I/O  Window giving coverage for `idcode'. 
 
-Detailed_Input
 
   ck             is the name of a C-kernel. 
    
   idcode         is the integer ID code of an object, normally a
                  spacecraft structure or instrument, for which
                  pointing data are expected to exist in the specified
                  CK file.
 
   needav         is a logical variable indicating whether only
                  segments having angular velocity are to be considered
                  when determining coverage.  When `needav' is
                  SPICETRUE, segments without angular velocity don't
                  contribute to the coverage window; when `needav' is
                  SPICEFALSE, all segments for `idcode' may contribute
                  to the coverage window.
 
 
   level          is the level (granularity) at which the coverage 
                  is examined.  Allowed values and corresponding 
                  meanings are: 
 
                     "SEGMENT"    The output coverage window contains
                                  intervals defined by the start and
                                  stop times of segments for the object
                                  designated by `idcode'.
 
                     "INTERVAL"   The output coverage window contains
                                  interpolation intervals of segments
                                  for the object designated by
                                  `idcode'.  For type 1 segments, which
                                  don't have interpolation intervals,
                                  each epoch associated with a pointing
                                  instance is treated as a singleton
                                  interval; these intervals are added
                                  to the coverage window.

                                  All interpolation intervals are
                                  considered to lie within the segment
                                  bounds for the purpose of this
                                  summary:  if an interpolation
                                  interval extends beyond the segment
                                  coverage interval, only its
                                  intersection with the segment
                                  coverage interval is considered to
                                  contribute to the total coverage.
 
   tol            is a tolerance value expressed in ticks of the
                  spacecraft clock associated with IDCODE.  Before each
                  interval is inserted into the coverage window, the
                  interval is intersected with the segment coverage
                  interval, then if the intersection is non-empty, it
                  is expanded by `tol': the left endpoint of the
                  intersection interval is reduced by `tol' and the
                  right endpoint is increased by `tol'. Adjusted
                  interval endpoints, when expressed as encoded SCLK,
                  never are less than zero ticks.  Any intervals that
                  overlap as a result of the expansion are merged.
 
                  The coverage window returned when tol > 0 indicates
                  the coverage provided by the file to the CK readers
                  ckgpav_c and ckgp_c when that value of `tol' is
                  passed to them as an input.
 
               
   timsys         is a string indicating the time system used in the
                  output coverage window.  `timsys' may have the
                  values:
  
                      "SCLK"    Elements of `cover' are expressed in 
                                encoded SCLK ("ticks"), where the 
                                clock is associated with the object 
                                designated by `idcode'. 
 
                      "TDB"     Elements of `cover' are expressed as 
                                seconds past J2000 TDB. 
 
 
   cover          is an initialized CSPICE window data structure.
                  `cover' optionally may contain coverage data on
                  input; on output, the data already present in `cover'
                  will be combined with coverage found for the object
                  designated by `idcode' in the file `ck'.
 
                  If `cover' contains no data on input, its size and
                  cardinality still must be initialized.
 
-Detailed_Output
 
   cover          is a CSPICE window data structure which represents
                  the merged coverage for `idcode'. When the coverage
                  level is "INTERVAL", this is the set of time
                  intervals for which data for `idcode' are present in
                  the file `ck', merged with the set of time intervals
                  present in `cover' on input.  The merged coverage is
                  represented as the union of one or more disjoint time
                  intervals.  The window `cover' contains the pairs of
                  endpoints of these intervals.
 
                  When the coverage level is "SEGMENT", `cover' is
                  computed in a manner similar to that described above,
                  but the coverage intervals used in the computation
                  are those of segments rather than interpolation
                  intervals within segments.  
 
                  When `tol' is > 0, the intervals comprising the
                  coverage window for `idcode' are expanded by `tol'
                  and any intervals overlapping as a result are merged.
                  The resulting window is returned in `cover'. The
                  expanded window in no case extends beyond the segment
                  bounds in either direction by more than `tol'.
 
                  The interval endpoints contained in `cover' are
                  encoded spacecraft clock times if `timsys' is "SCLK";
                  otherwise the times are converted from encoded
                  spacecraft clock to seconds past J2000 TDB.
 
                  See the Examples section below for a complete example
                  program showing how to retrieve the endpoints from
                  `cover'.
                                     
-Parameters
 
   None. 
 
-Exceptions
 
   1)  If the input file has transfer format, the error  
       SPICE(INVALIDFORMAT) is signaled. 
 
   2)  If the input file is not a transfer file but has architecture 
       other than DAF, the error SPICE(BADARCHTYPE) is signaled. 
 
   3)  If the input file is a binary DAF file of type other than 
       CK, the error SPICE(BADFILETYPE) is signaled. 
 
   4)  If the CK file cannot be opened or read, the error will 
       be diagnosed by routines called by this routine. The output 
       window will not be modified. 
 
   5)  If the size of the output window argument `cover' is 
       insufficient to contain the actual number of intervals in the 
       coverage window for `idcode', the error will be diagnosed by 
       routines called by this routine.   
 
   6)  If `tol' is negative, the error SPICE(VALUEOUTOFRANGE) is 
       signaled. 
 
   7)  If `level' is not recognized, the error SPICE(INVALIDOPTION) 
       is signaled. 
 
   8)  If `timsys' is not recognized, the error SPICE(INVALIDOPTION) 
       is signaled. 
 
   9)  If a time conversion error occurs, the error will be  
       diagnosed by a routine in the call tree of this routine. 
 
   10) If the output time system is TDB, the CK subsystem must be 
       able to map `idcode' to the ID code of the associated 
       spacecraft clock.  If this mapping cannot be performed, the 
       error will be diagnosed by a routine in the call tree of this 
       routine. 
  
   11) The error SPICE(EMPTYSTRING) is signaled if any of the input
       strings `ck', `level', or `timsys' do not contain at least one
       character, since such an input string cannot be converted to a
       Fortran-style string in this case.
      
   12) The error SPICE(NULLPOINTER) is signaled if the if any of the input
       strings `ck', `level', or `timsys' are null.


-Files
 
   This routine reads a C-kernel. 
 
   If the output time system is "TDB", then a leapseconds kernel 
   and an SCLK kernel for the spacecraft clock associated with 
   `idcode' must be loaded before this routine is called. 
 
   If the ID code of the clock associated with `idcode' is not  
   equal to  
 
      idcode / 1000 
 
   then the kernel variable  
 
      CK_<idcode>_SCLK 
  
   must be present in the kernel pool to identify the clock 
   associated with `idcode'.  This variable must contain the ID code 
   to be used for conversion between SCLK and TDB. Normally this 
   variable is provided in a text kernel loaded via furnsh_c. 
 
-Particulars
 
   This routine provides an API via which applications can determine 
   the coverage a specified CK file provides for a specified 
   object. 
 
-Examples
 
   1)  Display the interval-level coverage for each object in a
       specified CK file. Use tolerance of zero ticks. Do not request
       angular velocity. Express the results in the TDB time system.
 
       Find the set of objects in the file. Loop over the contents of
       the ID code set:  find the coverage for each item in the set and
       display the coverage.


          #include <stdio.h>
          #include "SpiceUsr.h"

          int main()
          {

             /.
             Local parameters
             ./
             #define  FILSIZ         256
             #define  MAXIV          100000
             #define  WINSIZ         ( 2 * MAXIV )
             #define  TIMLEN         51
             #define  MAXOBJ         1000

             /.
             Local variables
             ./
             SPICEDOUBLE_CELL        ( cover, WINSIZ );
             SPICEINT_CELL           ( ids,   MAXOBJ );

             SpiceChar               ck      [ FILSIZ ];
             SpiceChar               lsk     [ FILSIZ ];
             SpiceChar               sclk    [ FILSIZ ];
             SpiceChar               timstr  [ TIMLEN ];

             SpiceDouble             b;
             SpiceDouble             e;

             SpiceInt                i;
             SpiceInt                j;
             SpiceInt                niv;
             SpiceInt                obj;


             /.
             Load a leapseconds kernel and SCLK kernel for output time
             conversion.  Note that we assume a single spacecraft clock is
             associated with all of the objects in the CK.
             ./
             prompt_c ( "Name of leapseconds kernel > ", FILSIZ, lsk );
             furnsh_c ( lsk );

             prompt_c ( "Name of SCLK kernel        > ", FILSIZ, sclk );
             furnsh_c ( sclk );

             /.
             Get name of CK file.
             ./
             prompt_c ( "Name of CK file            > ", FILSIZ, ck );

             /.
             Find the set of objects in the CK file. 
             ./
             ckobj_c ( ck, &ids );

             /.
             We want to display the coverage for each object. Loop over
             the contents of the ID code set, find the coverage for
             each item in the set, and display the coverage.
             ./
             for ( i = 0;  i < card_c( &ids );  i++  )
             {
                /.
                Find the coverage window for the current object. 
                Empty the coverage window each time so we don't
                include data for the previous object.
                ./
                obj  =  SPICE_CELL_ELEM_I( &ids, i );

                scard_c ( 0,  &cover );  
                ckcov_c ( ck,          obj,  SPICEFALSE, 
                          "INTERVAL",  0.0,  "TDB",       &cover );

                /.
                Get the number of intervals in the coverage window.
                ./
                niv = wncard_c( &cover );

                /.
                Display a simple banner.
                ./
                printf ( "%s\n", "========================================" );

                printf ( "Coverage for object %ld\n", obj );

                /.
                Convert the coverage interval start and stop times to TDB
                calendar strings.
                ./
                for ( j = 0;  j < niv;  j++  )
                {
                   /.
                   Get the endpoints of the jth interval.
                   ./
                   wnfetd_c ( &cover, j, &b, &e );

                   /.
                   Convert the endpoints to TDB calendar
                   format time strings and display them.
                   ./
                   timout_c ( b, 
                              "YYYY MON DD HR:MN:SC.###### (TDB) ::TDB",  
                              TIMLEN,
                              timstr                                    );

                   printf ( "\n"
                            "Interval:  %ld\n"
                            "Start:     %s\n",
                            j,
                            timstr            );

                   timout_c ( e, 
                              "YYYY MON DD HR:MN:SC.###### (TDB) ::TDB",  
                              TIMLEN,
                              timstr                                    );
                   printf ( "Stop:      %s\n", timstr );

                }
                printf ( "%s\n", "========================================" );

             }
             return ( 0 );
          } 


   2)  Find the segment-level coverage for the object designated by
       IDCODE provided by the set of CK files loaded via a metakernel.
       (The metakernel must also specify leapseconds and SCLK kernels.)
       Use tolerance of zero ticks. Do not request angular velocity.
       Express the results in the TDB time system.
 

          #include <stdio.h>
          #include "SpiceUsr.h"

          int main()
          {

             /.
             Local parameters
             ./
             #define  FILSIZ         256
             #define  LNSIZE         81 
             #define  MAXCOV         100000
             #define  WINSIZ         ( 2 * MAXCOV )
             #define  TIMLEN         51

             /.
             Local variables
             ./
             SPICEDOUBLE_CELL        ( cover, WINSIZ );

             SpiceBoolean            found;

             SpiceChar               file    [ FILSIZ ];
             SpiceChar               idch    [ LNSIZE ];
             SpiceChar               meta    [ FILSIZ ];
             SpiceChar               source  [ FILSIZ ];
             SpiceChar               timstr  [ TIMLEN ];
             SpiceChar               type    [ LNSIZE ];

             SpiceDouble             b;
             SpiceDouble             e;

             SpiceInt                count;
             SpiceInt                handle;
             SpiceInt                i;
             SpiceInt                idcode;
             SpiceInt                niv;


             /.
             Prompt for the metakernel name; load the metakernel.
             The metakernel lists the CK files whose coverage
             for `idcode' we'd like to determine.  The metakernel
             must also specify a leapseconds kernel and an SCLK
             kernel for the clock associated with `idcode'.
             ./
             prompt_c ( "Name of metakernel > ", FILSIZ, meta );
             furnsh_c ( meta );

             /.
             Get the ID code of interest. 
             ./
             prompt_c ( "Enter ID code      > ", LNSIZE, idch );
             prsint_c ( idch,  &idcode );

             /.
             Find out how many kernels are loaded.  Loop over the
             kernels:  for each loaded CK file, add its coverage
             for `idcode', if any, to the coverage window.
             ./
             ktotal_c ( "CK", &count );

             for ( i = 0;  i < count;  i++  )
             {
                kdata_c  ( i,           "CK",     FILSIZ,  
                           LNSIZE,      FILSIZ,   file,  
                           type,        source,   &handle,     &found );

                ckcov_c  ( file,        idcode,   SPICEFALSE,
                           "SEGMENT",   0.0,      "TDB",       &cover );
             }

             /.
             Display results. 

             Get the number of intervals in the coverage window.
             ./
             niv = wncard_c( &cover );

             /.
             Display a simple banner.
             ./
             printf ( "\nCoverage for object %ld\n", idcode );

             /.
             Convert the coverage interval start and stop times to TDB
             calendar strings.
             ./
             for ( i = 0;  i < niv;  i++  )
             {
                /.
                Get the endpoints of the ith interval.
                ./
                wnfetd_c ( &cover, i, &b, &e );

                /.
                Convert the endpoints to TDB calendar
                format time strings and display them.
                ./
                timout_c ( b, 
                           "YYYY MON DD HR:MN:SC.###### (TDB) ::TDB",  
                           TIMLEN,
                           timstr                                  );

                printf ( "\n"
                         "Interval:  %ld\n"
                         "Start:     %s\n",
                         i,
                         timstr            );

                timout_c ( e, 
                           "YYYY MON DD HR:MN:SC.###### (TDB) ::TDB",  
                           TIMLEN,
                           timstr                                  );
                printf ( "Stop:      %s\n", timstr );

             }
             return ( 0 );
          }


-Restrictions
 
   1) When this routine is used to accumulate coverage for `idcode' 
      provided by multiple CK files, the inputs `needav', `level', `tol', 
      and `timsys'  must have the same values for all files in order 
      for the result to be meaningful. 
 
-Literature_References
 
   None. 
 
-Author_and_Institution
 
   N.J. Bachman   (JPL) 
 
-Version
 
   -CSPICE Version 1.0.1, 30-NOV-2007 (NJB)

       Corrected bug in first example program in header:
       program now empties result window prior to collecting
       data for each object. Updated examples to use wncard_c 
       rather than card_c. Updated second example to demonstrate
       segment-level summary capability.

   -CSPICE Version 1.0.0, 07-JAN-2005 (NJB)

-Index_Entries
 
   get coverage window for ck object 
 
-&
*/

{ /* Begin ckcov_c */


   /*
   Local variables 
   */
   logical                 need;


   /*
   Participate in error tracing.
   */
   if ( return_c() )
   {
      return; 
   }
   chkin_c ( "ckcov_c" );

   /*
   Check the input string `ck' to make sure the pointer is non-null 
   and the string length is non-zero.
   */
   CHKFSTR ( CHK_STANDARD, "ckcov_c", ck );
   
   /*
   Check the input string `level' to make sure the pointer is non-null 
   and the string length is non-zero.
   */
   CHKFSTR ( CHK_STANDARD, "ckcov_c", level );

   /*
   Check the input string `timsys' to make sure the pointer is non-null 
   and the string length is non-zero.
   */
   CHKFSTR ( CHK_STANDARD, "ckcov_c", timsys );

   /*
   Make sure cell data type is d.p. 
   */
   CELLTYPECHK ( CHK_STANDARD, "ckcov_c", SPICE_DP, cover );

   /*
   Initialize the cell if necessary. 
   */
   CELLINIT ( cover );   

   /*
   Call the f2c'd Fortran routine.
   */
   need = needav;

   ckcov_ ( ( char       * ) ck,
            ( integer    * ) &idcode,
            ( logical    * ) &need,
            ( char       * ) level,
            ( doublereal * ) &tol,
            ( char       * ) timsys,
            ( doublereal * ) (cover->base),
            ( ftnlen       ) strlen(ck),
            ( ftnlen       ) strlen(level),
            ( ftnlen       ) strlen(timsys)  );

   /*
   Sync the output cell. 
   */
   if ( !failed_c() )
   {
      zzsynccl_c ( F2C, cover );
   }

   chkout_c ( "ckcov_c" );

} /* End ckcov_c */
示例#9
0
   void qcktrc_c ( SpiceInt     tracelen,
                   SpiceChar  * trace    )

/*

-Brief_I/O
 
   VARIABLE  I/O  DESCRIPTION 
   --------  ---  -------------------------------------------------- 
   tracelen   I   Maximum length of output traceback string.
   trace      O   A traceback string. 
   SPICE_ERROR_MAXMOD   
              P   Maximum traceback module count.
   SPICE_ERROR_MODLEN 
              P   Maximum module name length. 
   SPICE_ERROR_TRCLEN
              P   Maximum length of output traceback string.

-Detailed_Input
 
   None. 
 
-Detailed_Output
 
   trace          is a list of module names, delimited by the string, 
                  " --> ".  An example would be
 
                     "SPUD --> SPAM --> FOOBAR". 
 
                  The maximum length of the returned string is given
                  by the parameter SPICE_ERROR_TRCLEN. The value of this
                  parameter includes room for the terminating null.

                  In general, the meaning of the trace is as follows:
 
                  The first name in the list is the name of the first
                  module to check in (that hasn't yet checked out). The
                  last name is the name of the module at the end of the
                  call chain; this is the last module that checked in.
 
                  The meaning of the traceback depends on the state 
                  of the error handling mechanism.  There are two 
                  cases: 
 
                     1)  In RETURN mode, when an error is signaled, the
                         traceback at that point is saved. trcdep_c,
                         trcnam_c, and qcktrc_c return values
                         pertaining to the saved traceback.
 
                     2)  In all other modes, the traceback represents
                         the CURRENT call chain. trcdep_c, trcnam_c,
                         and qcktrc_c return values pertaining to the
                         current trace representation.
 
                  Any module names exceeding SPICE_ERROR_MODLEN
                  characters in length are truncated on the right.
 
-Parameters
 
   The following parameters are declared in the header file SpiceErr.h:


   SPICE_ERROR_MAXMOD    is the maximum number of module names that can
                         be accommodated in the SPICE trace stack; this
                         is the maximum number of names that can appear
                         in the output traceback.

   SPICE_ERROR_MODLEN    is the maximum module name length that can be
                         accommodated by this routine. 

   SPICE_ERROR_TRCLEN    is the maximum length of the string returned
                         by this routine. The value of this parameter
                         includes room for the terminating null.
 
-Exceptions
 
   1)  If the output string pointer is null, the error SPICE(NULLPOINTER)
       will be signaled.


   2)  If the output string has length less than 2 characters, the error
       SPICE(STRINGTOOSHORT) will be signaled.
 
-Files
 
   None. 
 
-Particulars
 
   This routine is part of the CSPICE error handling mechanism. 
 
-Examples
 
   1) Deliberately generate a SPICE error to demonstrate use of 
      this routine together with trcnam_c. We'll attempt to look up 
      a state vector via spkezr_c without first having loaded any
      SPK files.


      Example code begins here.
 

         #include <stdio.h>
         #include "SpiceUsr.h"

         int main()
         {
            /.
            Local constants 
            ./
            #define ACTION          "RETURN"

            /.
            Local variables 
            ./   
            SpiceChar             * abcorr;
            SpiceChar               trace  [ SPICE_ERROR_TRCLEN ];
            SpiceChar             * obsrvr;
            SpiceChar             * frame;
            SpiceChar             * target;

            SpiceDouble             et;
            SpiceDouble             lt;
            SpiceDouble             state [6];

            /.
            Set error handling action to RETURN so that this program
            won't terminate when a SPICE error is signaled. Note that
            the input string length argument is unused for a "SET"
            operation.
            ./
            erract_c ( "SET", 0, ACTION );

            /.
            Generate a SPICE error: call spkezr_c without first having
            loaded an SPK file. 
            ./ 
            et     = 0.0;
            target = "Moon";
            obsrvr = "Earth";
            frame  = "J2000";
            abcorr = "NONE";

            spkezr_c ( target, et, frame, abcorr, obsrvr, state, &lt );

            if ( failed_c() ) 
            {
               /.
               An error has been signaled. Fetch and display
               the traceback.
               ./
               qcktrc_c ( SPICE_ERROR_TRCLEN, trace );

               printf ( "Traceback: \n%s\n", trace );
               /.
               Reset the error status so that CSPICE can resume normal
               operation. 
               ./
               reset_c();
            }

            return ( 0 );
         }

      When this program was executed on a PC/Linux/gcc platform, the
      output (which has been reformatted to fit in the available 
      space in this header) was:


         ====================================================================
         ============

         Toolkit version: N0065

         SPICE(NOLOADEDFILES) --

         At least one SPK file needs to be loaded by SPKLEF before beginning 
         a search.

         A traceback follows.  The name of the highest level module is first.
         spkezr_c --> SPKEZR --> SPKEZ --> SPKGEO --> SPKSFS

         ====================================================================
         ============
         Traceback:
         spkezr_c --> SPKEZR --> SPKEZ --> SPKGEO --> SPKSFS


-Restrictions
 
   1) It is assumed no module names exceed SPICE_ERROR_MODLEN
      characters in length. 
 
-Literature_References
 
   None. 
 
-Author_and_Institution
 
   N.J. Bachman    (JPL) 
   K.R. Gehringer  (JPL) 
 
-Version
 
   -CSPICE Version 1.0.0, 05-NOV-2013 (NJB) (KRG)

-Index_Entries
 
   get quick traceback 
 
-&
*/

{ /* Begin qcktrc_c */

 
   /*
   This routine does not check in unless an input error occurs.
   */


   /* 
   Make sure the output string has at least enough room for one output
   character and a null terminator. Also check for a null pointer.

   We don't use the usual CHKOSTR macro here because we must reset
   the error status before signaling an error.
   */
   if ( trace == NULL )
   {
      reset_c  ();

      chkin_c  ( "qcktrc_c"                                   );
      setmsg_c ( "The output string pointer 'trace' is null." );
      sigerr_c ( "SPICE(NULLPOINTER)"                         );
      chkout_c ( "qcktrc_c"                                   );
      return;
   }

   if ( tracelen < 2 )
   {
      reset_c  ();

      chkin_c  ( "qcktrc_c"                                     );
      setmsg_c ( "The output string 'trace' has length #; the "
                 "minimum allowed length is 2 characters."      );
      errint_c ( "#",  tracelen                                 );
      sigerr_c ( "SPICE(STRINGTOOSHORT)"                        );
      chkout_c ( "qcktrc_c"                                     );
      return;
   }


   /*
   Fetch the traceback. 
   */
   qcktrc_ ( ( char       * ) trace,
             ( ftnlen       ) tracelen-1 );

   /*
   Convert the output name string to a null-terminated,
   C style string. 
   */
   F2C_ConvertStr ( tracelen, trace );


} /* End qcktrc_c */
示例#10
0
文件: gfuds_c.c 项目: haisamido/GMAT
   void gfuds_c (  void             ( * udfunc ) ( SpiceDouble       et,
                                                   SpiceDouble     * value ),

                   void             ( * udqdec ) ( void ( * udfunc ) 
                                                        ( SpiceDouble   et,
                                                          SpiceDouble * value ),

                                                   SpiceDouble       et,
                                                   SpiceBoolean    * isdecr ),

                   ConstSpiceChar     * relate,
                   SpiceDouble          refval,
                   SpiceDouble          adjust,
                   SpiceDouble          step,
                   SpiceInt             nintvls,
                   SpiceCell          * cnfine,
                   SpiceCell          * result )

/*

-Brief_I/O
 
   VARIABLE  I/O  DESCRIPTION
   --------  ---  --------------------------------------------------

   udfunc     I   Name of the routine that computes the scalar value
                  of interest at some time.
   udqdec     I   Name of the routine that computes whether the 
                  current state is decreasing.
   relate     I   Operator that either looks for an extreme value
                  (max, min, local, absolute) or compares the
                  geometric quantity value and a number.
   refval     I   Value used as reference for geometric quantity 
                  condition.
   adjust     I   Allowed variation for absolute extremal 
                  geometric conditions.
   step       I   Step size used for locating extrema and roots.
   nintvls    I   Workspace window interval count
   cnfine    I-O  SPICE window to which the search is restricted.
   result     O   SPICE window containing results.
 
-Detailed_Input

   udfunc     the name of the external routine that returns the 
              value of the scalar quantity of interest at time ET.
              The calling sequence for "udfunc" is:

                 udfunc ( et, &value )

              where:

                 et      an input double precision value 
                         representing the TDB ephemeris seconds time 
                         at which to determine the scalar value.

                 value   is the value of the geometric quantity 
                         at 'et'.

   udqdec     the name of the external routine that determines if
              the scalar quantity calculated by "udfunc" is decreasing.

              The calling sequence:

                 udqdec ( et, &isdecr )

              where:

                 et       an input double precision value representing
                          the TDB ephemeris seconds time at at which
                          to determine the time derivative of 'udfunc'.

                 isdecr   a logical variable indicating whether
                          or not the scalar value returned by udfunc
                          is decreasing. 'isdecr' returns true if the 
                          time derivative of "udfunc" at 'et' is negative.

   relate     the scalar string comparison operator indicating 
              the numeric constraint of interest. Values are:
     
                 ">"       value of scalar quantity greater than some
                           reference (refval).
     
                 "="       value of scalar quantity equal to some
                           reference (refval).
     
                 "<"       value of scalar quantity less than some
                           reference (refval).
     
                 "ABSMAX"  The scalar quantity is at an absolute
                           maximum.
     
                 "ABSMIN"  The scalar quantity is at an absolute
                            minimum.
     
                 "LOCMAX"  The scalar quantity is at a local 
                           maximum.
     
                 "LOCMIN"  The scalar quantity is at a local 
                           minimum.
     
              The caller may indicate that the region of interest
              is the set of time intervals where the quantity is
              within a specified distance of an absolute extremum.
              The argument 'adjust' (described below) is used to
              specified this distance.
     
              Local extrema are considered to exist only in the
              interiors of the intervals comprising the confinement
              window:  a local extremum cannot exist at a boundary
              point of the confinement window.
     
              relate is insensitive to case, leading and 
              trailing blanks.

   refval    is the reference value used to define an equality or
              inequality to  satisfied by the scalar quantity.
              The units of refval are those of the scalar quantity.

   adjust     the amount by which the quantity is allowed to vary
              from an absolute extremum.
                  
              If the search is for an absolute minimum is performed, 
              the resulting window contains time intervals when the 
              geometric quantity value has values between ABSMIN and 
              ABSMIN + adjust.
     
              If the search is for an absolute maximum, the
              corresponding range is  between ABSMAX - adjust and
              ABSMAX.
     
              'adjust' is not used for searches for local extrema,
              equality or inequality conditions and must have value
              zero for such searches.

   step       the double precision time step size to use in 
              the search.

              'step' must be short enough to for a search using this
              step size to locate the time intervals where the
              scalar quantity function is monotone increasing or
              decreasing. However, 'step' must not be *too* short,
              or the search will take an 

              The choice of 'step' affects the completeness but not
              the precision of solutions found by this routine; the
              precision is controlled by the convergence tolerance.
              See the discussion of the parameter SPICE_GF_CNVTOL for
              details.

              'step' has units of TDB seconds.

   nintvls    an integer value specifying the number of intervals in the 
              the internal workspace array used by this routine. 'nintvls'
              should be at least as large as the number of intervals
              within the search region on which the specified observer-target
              vector coordinate function is monotone increasing or decreasing. 
              It does no harm to pick a value of 'nintvls' larger than the
              minimum required to execute the specified search, but if chosen 
              too small, the search will fail.

   cnfine     a double precision SPICE window that confines the time
              period over which the specified search is conducted.
              cnfine may consist of a single interval or a collection
              of intervals. 

              In some cases the confinement window can be used to
              greatly reduce the time period that must be searched
              for the desired solution. See the Particulars section
              below for further discussion.
              
              See the Examples section below for a code example 
              that shows how to create a confinement window.

-Detailed_Output
 
   cnfine     is the input confinement window, updated if necessary
              so the control area of its data array indicates the
              window's size and cardinality. The window data are
              unchanged.

   result     is a SPICE window representing the set of time 
              intervals, within the confinement period, when the 
              specified geometric event occurs. 
 
              If `result' is non-empty on input, its contents 
              will be discarded before gfuds_c conducts its 
              search. 
 
-Parameters
 
   None.
 
-Exceptions 

   1)  In order for this routine to produce correct results, 
       the step size must be appropriate for the problem at hand. 
       Step sizes that are too large may cause this routine to miss 
       roots; step sizes that are too small may cause this routine 
       to run unacceptably slowly and in some cases, find spurious 
       roots. 
 
       This routine does not diagnose invalid step sizes, except 
       that if the step size is non-positive, an error is signaled 
       by a routine in the call tree of this routine. 
 
   2)  Due to numerical errors, in particular, 
 
          - Truncation error in time values 
          - Finite tolerance value 
          - Errors in computed geometric quantities 
 
       it is *normal* for the condition of interest to not always be 
       satisfied near the endpoints of the intervals comprising the 
       result window. 
 
       The result window may need to be contracted slightly by the 
       caller to achieve desired results. The SPICE window routine 
       wncond_c can be used to contract the result window. 
 
   3)  If an error (typically cell overflow) occurs while performing  
       window arithmetic, the error will be diagnosed by a routine 
       in the call tree of this routine. 
 
   4)  If the relational operator `relate' is not recognized, an  
       error is signaled by a routine in the call tree of this 
       routine. 
       
   5)  If 'adjust' is negative, the error SPICE(VALUEOUTOFRANGE) will
       signal from a routine in the call tree of this routine. 

       A non-zero value for 'adjust' when 'relate' has any value other than 
       "ABSMIN" or "ABSMAX" causes the error SPICE(INVALIDVALUE) to
       signal from a routine in the call tree of this routine. 
  
   6)  If required ephemerides or other kernel data are not 
       available, an error is signaled by a routine in the call tree 
       of this routine. 
 
   7)  If the workspace interval count is less than 1, the error
       SPICE(VALUEOUTOFRANGE) will be signaled.

   8)  If the required amount of workspace memory cannot be
       allocated, the error SPICE(MALLOCFAILURE) will be
       signaled.

   9)  If any input string argument pointer is null, the error
       SPICE(NULLPOINTER) will be signaled.

   10) If any input string argument is empty, the error 
       SPICE(EMPTYSTRING) will be signaled.

   11) If either input cell has type other than SpiceDouble,
       the error SPICE(TYPEMISMATCH) is signaled.

-Files

   Appropriate kernels must be loaded by the calling program before
   this routine is called.

   If the scalar function requires access to ephemeris data:

      - SPK data: ephemeris data for any body over the
        time period defined by the confinement window must be
        loaded. If aberration corrections are used, the states of
        target and observer relative to the solar system barycenter
        must be calculable from the available ephemeris data.
        Typically ephemeris data are made available by loading one
        or more SPK files via furnsh_c.

      - If non-inertial reference frames are used, then PCK
        files, frame kernels, C-kernels, and SCLK kernels may be
        needed.

   In all cases, kernel data are normally loaded once per program
   run, NOT every time this routine is called.

-Particulars

   This routine provides a simpler, but less flexible interface
   than does the routine zzgfrel_ for conducting searches for events
   corresponding to an arbitrary user defined scalar quantity 
   function. Applications that require support for progress 
   reporting, interrupt handling, non-default step or refinement
   functions, or non-default convergence tolerance should call
   zzgfrel_ rather than this routine.

   This routine determines a set of one or more time intervals
   within the confinement window when the  scalar function
   satisfies a caller-specified constraint. The resulting set of
   intervals is returned as a SPICE window.

   udqdec Default Template
   =======================

   The user must supply a routine to determine whether sign of the
   time derivative of udfunc is positive or negative at 'et'. For
   cases where udfunc is numerically well behaved, the user
   may find it convenient to use a routine based on the below
   template. uddc_c determines the truth of the expression

      d (udfunc)
      --         < 0
      dt

   using the library routine uddf_c to numerically calculate the
   derivative of udfunc using a three-point estimation. Use
   of gfdecr requires only changing the "udfunc" argument
   to that of the user provided scalar function passed to gfuds_c
   and defining the differential interval size, 'dt'. Please see 
   the Examples section for an example of gfdecr use.

   void gfdecr ( SpiceDouble et, SpiceBoolean * isdecr )
      {

      SpiceDouble         dt = h, double precision interval size;

      uddc_c( udfunc, uddf_c, et, dt, isdecr );

      return;
      }

   Below we discuss in greater detail aspects of this routine's
   solution process that are relevant to correct and efficient
   use of this routine in user applications.

   The Search Process
   ==================
   
   Regardless of the type of constraint selected by the caller, this
   routine starts the search for solutions by determining the time
   periods, within the confinement window, over which the specified
   scalar function is monotone increasing and monotone
   decreasing. Each of these time periods is represented by a SPICE
   window. Having found these windows, all of the quantity
   function's local extrema within the confinement window are known.
   Absolute extrema then can be found very easily. 
   
   Within any interval of these "monotone" windows, there will be at
   most one solution of any equality constraint. Since the boundary
   of the solution set for any inequality constraint is the set 
   of points where an equality constraint is met, the solutions of
   both equality and inequality constraints can be found easily
   once the monotone windows have been found.

   Step Size
   =========

   The monotone windows (described above) are found using a two-step
   search process. Each interval of the confinement window is
   searched as follows: first, the input step size is used to
   determine the time separation at which the sign of the rate of
   change of quantity function will be sampled. Starting at
   the left endpoint of an interval, samples will be taken at each
   step. If a change of sign is found, a root has been bracketed; at
   that point, the time at which the time derivative of the quantity 
   function is zero can be found by a refinement process, for 
   example, using a binary search.
   
   Note that the optimal choice of step size depends on the lengths
   of the intervals over which the quantity function is monotone:
   the step size should be shorter than the shortest of these
   intervals (within the confinement window).
   
   The optimal step size is *not* necessarily related to the lengths
   of the intervals comprising the result window. For example, if
   the shortest monotone interval has length 10 days, and if the
   shortest result window interval has length 5 minutes, a step size
   of 9.9 days is still adequate to find all of the intervals in the
   result window. In situations like this, the technique of using
   monotone windows yields a dramatic efficiency improvement over a
   state-based search that simply tests at each step whether the
   specified constraint is satisfied. The latter type of search can
   miss solution intervals if the step size is shorter than the
   shortest solution interval.

   Having some knowledge of the relative geometry of the targets and 
   observer can be a valuable aid in picking a reasonable step size. 
   In general, the user can compensate for lack of such knowledge by 
   picking a very short step size; the cost is increased computation 
   time. 

   Note that the step size is not related to the precision with which
   the endpoints of the intervals of the result window are computed.
   That precision level is controlled by the convergence tolerance.
   
   
   Convergence Tolerance
   =====================

   Once a root has been bracketed, a refinement process is used to 
   narrow down the time interval within which the root must lie. 
   This refinement process terminates when the location of the root 
   has been determined to within an error margin called the 
   "convergence tolerance." The convergence tolerance used by this 
   routine is set via the parameter SPICE_GF_CNVTOL. 

   The value of SPICE_GF_CNVTOL is set to a "tight" value so that the 
   tolerance doesn't become the limiting factor in the accuracy of 
   solutions found by this routine. In general the accuracy of input 
   data will be the limiting factor. 
   
   Making the tolerance tighter than SPICE_GF_CNVTOL is unlikely to 
   be useful, since the results are unlikely to be more accurate. 
   Making the tolerance looser will speed up searches somewhat, 
   since a few convergence steps will be omitted. However, in most 
   cases, the step size is likely to have a much greater affect 
   on processing time than would the convergence tolerance.


   The Confinement Window 
   ====================== 
   
   The simplest use of the confinement window is to specify a time 
   interval within which a solution is sought. However, the 
   confinement window can, in some cases, be used to make searches 
   more efficient. Sometimes it's possible to do an efficient search 
   to reduce the size of the time period over which a relatively 
   slow search of interest must be performed. 

-Examples

   The numerical results shown for these examples may differ across
   platforms. The results depend on the SPICE kernels used as
   input, the compiler and supporting libraries, and the machine 
   specific arithmetic implementation. 

   Conduct a search on the range-rate of the vector from the Sun
   to the Moon. Define a function to calculate the value.

   Use the meta-kernel shown below to load the required SPICE
   kernels.

         KPL/MK

         File name: standard.tm

         This meta-kernel is intended to support operation of SPICE
         example programs. The kernels shown here should not be
         assumed to contain adequate or correct versions of data
         required by SPICE-based user applications.

         In order for an application to use this meta-kernel, the
         kernels referenced here must be present in the user's
         current working directory.


         \begindata

            KERNELS_TO_LOAD = ( 'de414.bsp',
                                'pck00008.tpc',
                                'naif0009.tls'  )

         \begintext

   Code:

   #include <stdio.h>
   #include <stdlib.h>
   #include <string.h>

   #include "SpiceUsr.h"
   #include "SpiceZfc.h"
   #include "SpiceZad.h"


   #define       MAXWIN    20000
   #define       TIMFMT    "YYYY-MON-DD HR:MN:SC.###"
   #define       TIMLEN    41
   #define       NLOOPS    7

   void    gfq     ( SpiceDouble et, SpiceDouble * value );
   void    gfdecrx ( void ( * udfunc ) ( SpiceDouble    et,
                                         SpiceDouble  * value ),
                     SpiceDouble    et, 
                     SpiceBoolean * isdecr );

   doublereal dvnorm_(doublereal *state);


   int main( int argc, char **argv )
      {

      /.
      Create the needed windows. Note, one interval
      consists of two values, so the total number
      of cell values to allocate is twice
      the number of intervals.
      ./
      SPICEDOUBLE_CELL ( result, 2*MAXWIN );
      SPICEDOUBLE_CELL ( cnfine, 2        );

      SpiceDouble       begtim;
      SpiceDouble       endtim;
      SpiceDouble       step;
      SpiceDouble       adjust;
      SpiceDouble       refval;
      SpiceDouble       beg;
      SpiceDouble       end;

      SpiceChar         begstr [ TIMLEN ];
      SpiceChar         endstr [ TIMLEN ];
      
      SpiceInt          count;
      SpiceInt          i;
      SpiceInt          j;

      ConstSpiceChar * relate [NLOOPS] = { "=",
                                           "<",
                                           ">",
                                           "LOCMIN",
                                           "ABSMIN",
                                           "LOCMAX",
                                           "ABSMAX"
                                         };

      printf( "Compile date %s, %s\n\n", __DATE__, __TIME__ );

      /.  
      Load kernels.
      ./
      furnsh_c( "standard.tm" );
   
      /.  
      Store the time bounds of our search interval in the 'cnfine' 
      confinement window.
      ./
      str2et_c( "2007 JAN 01", &begtim );
      str2et_c( "2007 APR 01", &endtim );
   
      wninsd_c ( begtim, endtim, &cnfine );

      /.  
      Search using a step size of 1 day (in units of seconds). The reference
      value is .3365 km/s. We're not using the adjustment feature, so
      we set 'adjust' to zero.
      ./
      step   = spd_c();
      adjust = 0.;
      refval = .3365;

      for ( j = 0;  j < NLOOPS;  j++ )
         {

         printf ( "Relation condition: %s \n",  relate[j] );

         /.
         Perform the search. The SPICE window 'result' contains 
         the set of times when the condition is met. 
         ./

         gfuds_c ( gfq, 
                   gfdecrx,
                   relate[j],
                   refval,
                   adjust,
                   step,
                   MAXWIN,
                   &cnfine,
                   &result );

         count = wncard_c( &result );

         /.
         Display the results.
         ./
         if (count == 0 ) 
            {
            printf ( "Result window is empty.\n\n" );
            }
         else
            {
            for ( i = 0;  i < count;  i++ )
               {

               /.
               Fetch the endpoints of the Ith interval
               of the result window.
               ./
               wnfetd_c ( &result, i, &beg, &end );

               timout_c ( beg, TIMFMT, TIMLEN, begstr ); 
               timout_c ( end, TIMFMT, TIMLEN, endstr );

               printf ( "Start time, drdt = %s \n", begstr );
               printf ( "Stop time,  drdt = %s \n", endstr );

               }
               
            }

         printf("\n");
         
         }

      kclear_c();
      return( 0 );
      }



   /.
   The user defined functions required by GFUDS.
      
      gfq    for udfunc
      gfdecr for udqdec
   ./



   /.
   -Procedure Procedure gfq
   ./

   void gfq ( SpiceDouble et, SpiceDouble * value )

   /.
   -Abstract

      User defined geometric quantity function. In this case,
      the range from the sun to the Moon at TDB time 'et'.
   
   ./
      {
      
      /. Initialization ./
      SpiceInt             targ   = 301;
      SpiceInt             obs    = 10;

      SpiceChar          * ref    = "J2000";
      SpiceChar          * abcorr = "NONE";

      SpiceDouble          state [6];
      SpiceDouble          lt;

      /.
      Retrieve the vector from the Sun to the Moon in the J2000 
      frame, without aberration correction.
      ./
      spkez_c ( targ, et, ref, abcorr, obs, state, &lt );

      /.
      Calculate the scalar range rate corresponding the
     'state' vector.   
      ./

      *value = dvnorm_( state );

      return;
      }



   /.
   -Procedure gfdecrx
   ./
   
   void gfdecrx ( void ( * udfunc ) ( SpiceDouble    et,
                                      SpiceDouble  * value ),
                  SpiceDouble    et, 
                  SpiceBoolean * isdecr )

   /.
   -Abstract

      User defined function to detect if the function derivative
      is negative (the function is decreasing) at TDB time 'et'.
   ./
      {
         
      SpiceDouble         dt = 10.;
     
      /.
      Determine if "udfunc" is decreasing at 'et'.

      uddc_c - the GF function to determine if
                 the derivative of the user defined
                 function is negative at 'et'.

      uddf_c   - the SPICE function to numerically calculate the 
                 derivative of 'udfunc' at 'et' for the 
                 interval [et-dt, et+dt].
      ./

      uddc_c( udfunc, et, dt, isdecr );

      return;
      }


   The program outputs:

      Relation condition: = 
      Start time, drdt = 2007-JAN-02 00:35:19.574 
      Stop time,  drdt = 2007-JAN-02 00:35:19.574 
      Start time, drdt = 2007-JAN-19 22:04:54.899 
      Stop time,  drdt = 2007-JAN-19 22:04:54.899 
      Start time, drdt = 2007-FEB-01 23:30:13.428 
      Stop time,  drdt = 2007-FEB-01 23:30:13.428 
      Start time, drdt = 2007-FEB-17 11:10:46.540 
      Stop time,  drdt = 2007-FEB-17 11:10:46.540 
      Start time, drdt = 2007-MAR-04 15:50:19.929 
      Stop time,  drdt = 2007-MAR-04 15:50:19.929 
      Start time, drdt = 2007-MAR-18 09:59:05.959 
      Stop time,  drdt = 2007-MAR-18 09:59:05.959 
      
      Relation condition: < 
      Start time, drdt = 2007-JAN-02 00:35:19.574 
      Stop time,  drdt = 2007-JAN-19 22:04:54.899 
      Start time, drdt = 2007-FEB-01 23:30:13.428 
      Stop time,  drdt = 2007-FEB-17 11:10:46.540 
      Start time, drdt = 2007-MAR-04 15:50:19.929 
      Stop time,  drdt = 2007-MAR-18 09:59:05.959 
      
      Relation condition: > 
      Start time, drdt = 2007-JAN-01 00:00:00.000 
      Stop time,  drdt = 2007-JAN-02 00:35:19.574 
      Start time, drdt = 2007-JAN-19 22:04:54.899 
      Stop time,  drdt = 2007-FEB-01 23:30:13.428 
      Start time, drdt = 2007-FEB-17 11:10:46.540 
      Stop time,  drdt = 2007-MAR-04 15:50:19.929 
      Start time, drdt = 2007-MAR-18 09:59:05.959 
      Stop time,  drdt = 2007-APR-01 00:00:00.000 
      
      Relation condition: LOCMIN 
      Start time, drdt = 2007-JAN-11 07:03:58.988 
      Stop time,  drdt = 2007-JAN-11 07:03:58.988 
      Start time, drdt = 2007-FEB-10 06:26:15.439 
      Stop time,  drdt = 2007-FEB-10 06:26:15.439 
      Start time, drdt = 2007-MAR-12 03:28:36.404 
      Stop time,  drdt = 2007-MAR-12 03:28:36.404 
      
      Relation condition: ABSMIN 
      Start time, drdt = 2007-JAN-11 07:03:58.988 
      Stop time,  drdt = 2007-JAN-11 07:03:58.988 
      
      Relation condition: LOCMAX 
      Start time, drdt = 2007-JAN-26 02:27:33.766 
      Stop time,  drdt = 2007-JAN-26 02:27:33.766 
      Start time, drdt = 2007-FEB-24 09:35:07.816 
      Stop time,  drdt = 2007-FEB-24 09:35:07.816 
      Start time, drdt = 2007-MAR-25 17:26:56.150 
      Stop time,  drdt = 2007-MAR-25 17:26:56.150 
      
      Relation condition: ABSMAX 
      Start time, drdt = 2007-MAR-25 17:26:56.150 
      Stop time,  drdt = 2007-MAR-25 17:26:56.150 

-Restrictions

   1) Any kernel files required by this routine must be loaded
      before this routine is called.

-Literature_References

   None.

-Author_and_Institution

   N.J. Bachman   (JPL)
   E.D. Wright    (JPL)
 
-Version

   -CSPICE Version 1.0.0, 22-FEB-2010 (EDW) 

-Index_Entries

   GF user defined scalar function search

-&
*/

  { /* Begin gfuds_c */

   /*
   Local variables 
   */
   
   doublereal              * work;

   static SpiceInt           nw = SPICE_GF_NWMAX;

   SpiceInt                  nBytes;


   /*
   Participate in error tracing.
   */
   if ( return_c() )
     {
      return;
      }
   chkin_c ( "gfuds_c" );


   /*
   Make sure cell data types are d.p. 
   */
   CELLTYPECHK2 ( CHK_STANDARD, "gfuds_c", SPICE_DP, cnfine, result );

   /* 
   Initialize the input cells if necessary. 
   */
   CELLINIT2 ( cnfine, result );

   /*
   Check the other input strings to make sure each pointer is non-null 
   and each string length is non-zero.
   */
   CHKFSTR ( CHK_STANDARD, "gfuds_c", relate );

   /*
   Store the input function pointers so these functions can be
   called by the GF adapters. 
   */
   zzadsave_c ( UDFUNC,  (void *)(udfunc)  );
   zzadsave_c ( UDQDEC,  (void *)(udqdec)  );

   /*
   Check the workspace size; some mallocs have a violent
   dislike for negative allocation amounts. To be safe,
   rule out a count of zero intervals as well.
   */

   if ( nintvls < 1 )
      {
      setmsg_c ( "The specified workspace interval count # was "
                 "less than the minimum allowed value of one (1)." );
      errint_c ( "#",  nintvls                              );
      sigerr_c ( "SPICE(VALUEOUTOFRANGE)"                   );
      chkout_c ( "gfuds_c"                                  );
      return;
      } 
      

   /*
   Allocate the workspace. 'nintvls' indicates the maximum number of
   intervals returned in 'result'. An interval consists of
   two values.
   */

   nintvls = 2 * nintvls;
   
   nBytes = (nintvls + SPICE_CELL_CTRLSZ ) * nw * sizeof(SpiceDouble);

   work   = (doublereal *) alloc_SpiceMemory( nBytes );

   if ( !work ) 
      {
      setmsg_c ( "Workspace allocation of # bytes failed due to "
                 "malloc failure"                               );
      errint_c ( "#",  nBytes                                   );
      sigerr_c ( "SPICE(MALLOCFAILED)"                          );
      chkout_c ( "gfuds_c"                                      );
      return;
      }


   /*
   Let the f2c'd routine do the work. 

   We pass the adapter functions, not those provided as inputs,
   to the f2c'd routine:

      zzadfunc_c  adapter for  udfunc
      zzadqdec_c     ''        udqdec

   */

   (void) gfuds_( ( U_fp            ) zzadfunc_c,
                  ( U_fp            ) zzadqdec_c,
                  ( char          * ) relate,
                  ( doublereal    * ) &refval,
                  ( doublereal    * ) &adjust,
                  ( doublereal    * ) &step,
                  ( doublereal    * ) (cnfine->base),
                  ( integer       * ) &nintvls,
                  ( integer       * ) &nw,
                  ( doublereal    * ) work,
                  ( doublereal    * ) (result->base),
                  ( ftnlen          ) strlen(relate) );


   /*
   Always free dynamically allocated memory.
   */
   free_SpiceMemory( work );

   /*
   Sync the output cell.
   */
   if ( !failed_c() )
     {
     zzsynccl_c ( F2C, result );
     }

   ALLOC_CHECK;

   chkout_c ( "gfuds_c" );

   } /* End gfuds_c */
示例#11
0
   int zzgfdsps_ ( integer  * nlead,
                   char     * string,
                   char     * fmt,
                   integer  * ntrail,
                   ftnlen     stringLen,
                   ftnlen     fmtLen     ) 

/*

-Brief_I/O
 
 
   VARIABLE  I/O  DESCRIPTION 
   --------  ---  -------------------------------------------------- 
   nlead      I   Number of leading blank lines to write. 
   string     I   The string to display. 
   fmt        I   Format in which the string is to be written. 
   ntrail     I   Number of trailing blank lines to write. 
   stringLen  I   Length of input argument `string'.
   fmtLen     I   Length of input argument `fmt'.
 
-Detailed_Input
 
   nlead          is the number of blank lines to write before 
                  writing the output text string. 
 
   string         is a message to be displayed on the standard 
                  output stream. This is a Fortran-style string
                  without a terminating null character.
 
   fmt            is a Fortran format specification used to write 
                  the output string. This is a Fortran-style string
                  without a terminating null character.
 
                  FMT may be left to default ("A"), or may be used 
                  to control the length of the string ("A10"). 

                  **NOTE**: this argument is provided only for
                  compatibility with the Fortran version of this
                  routine; the argument is currently ignored.
 
   ntrail         is the number of blank lines to write after 
                  writing the output text string. 

   stringLen      is the length of the input string `string'.

   fmtLen         is the length of the input string `fmt'.
 
-Detailed_Output
 
   None. This program has no output arguments but writes to the 
   standard output stream. 
 
-Parameters
 
   None. 
 
-Exceptions
 
   1) If an error occurs when this routine attempts to 
      allocate memory dynamically, the error will be
      diagnosed by routines in the call tree of this routine.
 
   2) If the either of the input arguments `nlead' or `ntrail' 
      is non-positive, then no leading or trailing blank 
      lines will be written, respectively. This case is not 
      considered an error. 
 
-Files
 
   None. 
 
-Particulars
 
   This is an overlay routine for the f2c'd routine zzgfdsps_;
   as such, this routine has an f2c-style calling sequence.

   CSPICE GF routines should call this routine rather than
   zzgfdsps_.

   Since ANSI C supports the cursor control capabilities required
   for GF progress reporting, it's not necessary to rely on ANSI
   control sequences to effect cursor control.

   This routine supports the default GF progress report display. 
   Output is written to the standard output stream; normally this 
   results in output on a terminal window. 
 
   After the output line is written, this routine moves the cursor 
   up and to the first column, so a subsequent call will overwrite 
   output from the current call. 
 
-Examples 
 
   See calls made to this routine by the entry points of 
   zzgfrpwrk. 
 
-Restrictions
 
   The input Fortran format argument is ignored.
 
-Literature_References
 
   None. 
 
-Author_and_Institution
 
   N.J. Bachman     (JPL) 
 
-Version
 
   -CSPICE Version 1.0.0, 27-FEB-2009 (NJB)

-Index_Entries
 
   GF output progress report string 
 
-&
*/

{ /* Begin zzgfdsps_ */


   /*
   Local variables
   */      
   SpiceChar             * CFmtPtr;
   SpiceChar             * CStringPtr;

   SpiceInt                i;
   SpiceInt                nl;
   SpiceInt                nt;
   SpiceInt                outlen;
 

   /*
   Participate in error tracing.
   */
   chkin_c ( "zzgfdsps_" );

   /*
   The input strings are Fortran-style; they're not 
   null-terminated. Convert these to C-style strings
   so we can work with them. We'll need to use dynamic
   memory to hold the C-style strings. 
   */
   F2C_CreateStr_Sig ( stringLen, string, &CStringPtr );
   
   if ( failed_c() ) 
   {
      /*
      The CSPICE string utilities do their own clean-up of
      allocated memory, so we won't attempt to free the
      C string. 
      */
      chkout_c ( "zzgfdsps_" );

      return (-1);
   }

   F2C_CreateStr_Sig ( fmtLen, fmt, &CFmtPtr );

   if ( failed_c() ) 
   {
      /*
      Failure at this point requires that we free the previous,
      successfully allocated string. 
      */
      free ( CStringPtr );

      chkout_c ( "zzgfdsps_" );

      return(-1);
   }

   /*
   Display any blank lines indicated by `nlead'. 
   */

   nl = *nlead;
   nt = *ntrail;

 
   for ( i = 0;  i < nl; i++ )
   {
      putc ( '\n', stdout );
   }

   /*
   Save the length of the output string. 
   */
   outlen = strlen( CStringPtr );

   /*
   Write the string to standard output without a trailing newline
   character. 
   */   
   printf ( "%s", CStringPtr );  


   /*
   Force a write of any buffered, unwritten output data. 

   Without this call, progress report updates may not be displayed in a
   timely fashion. There can be a long pause, followed by an
   announcement that the task is 100% done. This behavior rather
   defeats the purpose of the report.
   */
   fflush ( stdout );

   /*
   Back up the cursor to the start of the line. 
   */
   for ( i = 0; i < outlen; i++ )
   {
      putc ( '\b', stdout );
   }

   /*
   Display any blank lines indicated by `ntrail'. 
   */
   for ( i = 0;  i < nt; i++ )
   {
      putc ( '\n', stdout );
   }

   /*
   Free the dynamically allocated strings. 
   */
   free ( CStringPtr );
   free ( CFmtPtr    );
   
   chkout_c ( "zzgfdsps_" );

   return ( 0 );


} /* End zzgfdsps_ */
示例#12
0
文件: psv2pl_c.c 项目: Dbelsa/coft
   void psv2pl_c ( ConstSpiceDouble    point[3],
                   ConstSpiceDouble    span1[3],
                   ConstSpiceDouble    span2[3],
                   SpicePlane        * plane    ) 
/*

-Brief_I/O
 
   Variable  I/O  Description 
   --------  ---  -------------------------------------------------- 
   point, 
   span1, 
   span2      I   A point and two spanning vectors defining a plane. 
   plane      O   A CSPICE plane representing the plane. 
 
-Detailed_Input
 
   point, 
   span1, 
   span2          are, respectively, a point and two spanning vectors 
                  that define a geometric plane in three-dimensional 
                  space. The plane is the set of vectors 
 
                     point   +   s * span1   +   t * span2 
 
                  where s and t are real numbers.  The spanning 
                  vectors span1 and span2 must be linearly 
                  independent, but they need not be orthogonal or 
                  unitized. 
 
-Detailed_Output
 
   plane          is a CSPICE plane that represents the geometric 
                  plane defined by point, span1, and span2. 
 
-Parameters
 
   None. 
 
-Exceptions
 
   1)  If span1 and span2 are linearly dependent, then the vectors 
       point, span1, and span2 do not define a plane.  The error 
       SPICE(DEGENERATECASE) is signaled. 
 
-Files
 
   None. 
 
-Particulars
 
   CSPICE geometry routines that deal with planes use the `plane' 
   data type to represent input and output planes.  This data type 
   makes the subroutine interfaces simpler and more uniform. 
 
   The CSPICE routines that produce CSPICE planes from data that 
   define a plane are: 
 
      nvc2pl_c ( Normal vector and constant to plane ) 
      nvp2pl_c ( Normal vector and point to plane    ) 
      psv2pl_c ( Point and spanning vectors to plane ) 
 
   The CSPICE routines that convert CSPICE planes to data that 
   define a plane are: 
 
      pl2nvc_c ( Plane to normal vector and constant ) 
      pl2nvp_c ( Plane to normal vector and point    ) 
      pl2psv_c ( Plane to point and spanning vectors ) 
 
   Any of these last three routines may be used to convert this 
   routine's output, plane, to another representation of a 
   geometric plane. 
 
-Examples
 
   1)  Project a vector v orthogonally onto a plane defined by 
       point, span1, and span2.  proj is the projection we want; it 
       is the closest vector in the plane to v. 
 
          psv2pl_c ( point,  span1,   span2,  &plane ); 
          vprjp_c  ( v,      &plane,  proj           );
 
 
   2)  Find the plane determined by a spacecraft's position vector 
       relative to a central body and the spacecraft's velocity 
       vector.  We assume that all vectors are given in the same 
       coordinate system. 
 
          /.
          pos is the spacecraft's position, relative to 
          the central body.  vel is the spacecraft's velocity 
          vector.  pos is a point (vector, if you like) in 
          the orbit plane, and it is also one of the spanning 
          vectors of the plane. 
          ./
          psv2pl_c ( pos, pos, vel, &plane );
           
 
-Restrictions
 
   None. 
 
-Literature_References
 
   [1] `Calculus and Analytic Geometry', Thomas and Finney. 
 
-Author_and_Institution
 
   N.J. Bachman   (JPL) 
 
-Version
 
   -CSPICE Version 1.0.0, 05-MAR-1999 (NJB)

-Index_Entries
 
   point and spanning vectors to plane 
 
-&
*/

{ /* Begin psv2pl_c */



   /*
   This routine checks in only if an error is discovered.
   */

   if ( return_c () ) 
   {
      return;
   }

   /*
   Find the unitized cross product of SPAN1 and SPAN2; this is our
   unit normal vector, or possibly its inverse.
   */
   ucrss_c (  span1,  span2,  plane->normal  );

   if (  vzero_c ( plane->normal )  )
   {
      chkin_c  ( "psv2pl_c"                       );
      setmsg_c ( "Spanning vectors are parallel." );
      sigerr_c ( "SPICE(DEGENERATECASE)"          );
      chkout_c ( "psv2pl_c"                       );
      return;
   }
 
 
   /*
   Find the plane constant corresponding to the unit normal
   vector we've found.
   */
   plane->constant  =  vdot_c ( plane->normal, point );
 
 
   /*
   The constant should be the distance of the plane from the
   origin.  If the constant is negative, negate both it and the
   normal vector.
   */
      
   if ( plane->constant  <  0. ) 
   {
      plane->constant  =   - (plane->constant);
      
      vminus_c ( plane->normal, plane->normal );
   }


} /* End psv2pl_c */
示例#13
0
   void wninsd_c ( SpiceDouble     left,
                   SpiceDouble     right,
                   SpiceCell     * window ) 

/*

-Brief_I/O
 
   VARIABLE  I/O  DESCRIPTION 
   --------  ---  -------------------------------------------------- 
   left, 
   right      I   Left, right endpoints of new interval. 
   window    I,O  Input, output window. 
 
-Detailed_Input
 
   left, 
   right       are the left and right endpoints of the interval 
               to be inserted. 

   window      on input, is a CSPICE window containing zero or more 
               intervals. 
 
               window must be declared as a double precision
               SpiceCell.

-Detailed_Output
 
   window      on output, is the original window following the 
               insertion of the interval from left to right. 
 
-Parameters
 
   None. 
 
-Exceptions
 
   1) If the input window does not have double precision type,
      the error SPICE(TYPEMISMATCH) is signaled.

   2) If left is greater than right, the error SPICE(BADENDPOINTS) is 
      signaled. 
 
   3) If the insertion of the interval causes an excess of elements, 
      the error SPICE(WINDOWEXCESS) is signaled. 
 
-Files
 
   None. 
 
-Particulars
 
   This routine inserts the interval from left to right into the 
   input window. If the new interval overlaps any of the intervals 
   in the window, the intervals are merged. Thus, the cardinality 
   of the input window can actually decrease as the result of an 
   insertion. However, because inserting an interval that is 
   disjoint from the other intervals in the window can increase the 
   cardinality of the window, the routine signals an error. 
 
   No other CSPICE unary window routine can increase the number of
   intervals in the input window.

-Examples
 
    Let window contain the intervals 
 
       [ 1, 3 ]  [ 7, 11 ]  [ 23, 27 ] 
 
    Then the following series of calls 
 
       wninsd_c ( 5.0,  5.0, &window )                  (1) 
       wninsd_c ( 4.0,  8.0, &window )                  (2) 
       wninsd_c ( 0.0, 30.0, &window )                  (3) 
 
    produces the following series of windows 

       [ 1,  3 ]  [ 5,  5 ]  [  7, 11 ]  [ 23, 27 ]     (1) 
       [ 1,  3 ]  [ 4, 11 ]  [ 23, 27 ]                 (2) 
       [ 0, 30 ]                                        (3) 
 
-Restrictions
 
   None. 
 
-Literature_References
 
   None. 
 
-Author_and_Institution
 
   N.J. Bachman    (JPL) 
   K.R. Gehringer  (JPL) 
   H.A. Neilan     (JPL) 
   W.L. Taber      (JPL) 
   I.M. Underwood  (JPL) 
 
-Version
 
   -CSPICE Version 1.0.0, 29-JUL-2002 (NJB) (KRG) (HAN) (WLT) (IMU)

-Index_Entries
 
   insert an interval into a d.p. window 
 
-&
*/

{ /* Begin wninsd_c */


   /*
   Standard SPICE error handling. 
   */

   if ( return_c() )
   {
      return;
   }
   chkin_c ( "wninsd_c" );


   /*
   Make sure cell data type is d.p. 
   */
   CELLTYPECHK ( CHK_STANDARD, "wninsd_c", SPICE_DP, window );


   /*
   Initialize the cell if necessary. 
   */
   CELLINIT ( window );
   

   /*
   Let the f2c'd routine do the work. 
   */
   wninsd_ ( (doublereal * )  &left,
             (doublereal * )  &right,
             (doublereal * )  (window->base) );

   /*
   Sync the output cell. 
   */
   if ( !failed_c() )
   {
      zzsynccl_c ( F2C, window );
   }


   chkout_c ( "wninsd_c" );

} /* End wninsd_c */
示例#14
0
   void vprjpi_c ( ConstSpiceDouble    vin    [3],
                   ConstSpicePlane   * projpl,
                   ConstSpicePlane   * invpl,
                   SpiceDouble         vout   [3],
                   SpiceBoolean      * found       ) 

/*

-Brief_I/O
 
   Variable  I/O  Description 
   --------  ---  -------------------------------------------------- 
   vin        I   The projected vector. 
   projpl     I   Plane containing vin. 
   invpl      I   Plane containing inverse image of vin. 
   vout       O   Inverse projection of vin. 
   found      O   Flag indicating whether vout could be calculated. 
 
-Detailed_Input
 
   vin, 
   projpl, 
   invpl          are, respectively, a 3-vector, a CSPICE plane 
                  containing the vector, and a CSPICE plane 
                  containing the inverse image of the vector under 
                  orthogonal projection onto projpl. 
 
-Detailed_Output
 
   vout           is the inverse orthogonal projection of vin.  This 
                  is the vector lying in the plane invpl whose 
                  orthogonal projection onto the plane projpl is 
                  vin.  vout is valid only when found (defined below) 
                  is SPICETRUE. Otherwise, vout is undefined. 
 
   found          indicates whether the inverse orthogonal projection 
                  of vin could be computed.  found is SPICETRUE if so, 
                  SPICEFALSE otherwise. 
 
-Parameters
 
   None. 
 
-Exceptions
 
   1)  If the geometric planes defined by projpl and invpl are 
       orthogonal, or nearly so, the inverse orthogonal projection 
       of vin may be undefined or have magnitude too large to 
       represent with double precision numbers.  In either such 
       case, found will be set to SPICEFALSE. 
 
   2)  Even when found is SPICETRUE, vout may be a vector of extremely 
       large magnitude, perhaps so large that it is impractical to 
       compute with it.  It's up to you to make sure that this 
       situation does not occur in your application of this routine. 
 
-Files
 
   None. 
 
-Particulars
 
   Projecting a vector orthogonally onto a plane can be thought of 
   as finding the closest vector in the plane to the original vector. 
   This `closest vector' always exists; it may be coincident with the 
   original vector.  Inverting an orthogonal projection means finding 
   the vector in a specified plane whose orthogonal projection onto 
   a second specified plane is a specified vector.  The vector whose 
   projection is the specified vector is the inverse projection of 
   the specified vector, also called the `inverse image under 
   orthogonal projection' of the specified vector.  This routine 
   finds the inverse orthogonal projection of a vector onto a plane. 
 
   Related routines are vprjp_c, which projects a vector onto a plane 
   orthogonally, and vproj_c, which projects a vector onto another 
   vector orthogonally. 
 
-Examples
 
   1)   Suppose 
 
           vin    =  ( 0.0, 1.0, 0.0 ), 
 
        and that projpl has normal vector 
 
           projn  =  ( 0.0, 0.0, 1.0 ). 
 
        Also, let's suppose that invpl has normal vector and constant 
 
           invn   =  ( 0.0, 2.0, 2.0 ) 
           invc   =    4.0. 
 
        Then vin lies on the y-axis in the x-y plane, and we want to 
        find the vector vout lying in invpl such that the orthogonal 
        projection of vout the x-y plane is vin.  Let the notation 
        < a, b > indicate the inner product of vectors a and b. 
        Since every point x in invpl satisfies the equation 
 
           <  x,  (0.0, 2.0, 2.0)  >  =  4.0, 
 
        we can verify by inspection that the vector 
 
           ( 0.0, 1.0, 1.0 ) 
 
        is in invpl and differs from vin by a multiple of projn.  So 
 
           ( 0.0, 1.0, 1.0 ) 
 
        must be vout. 
 
        To find this result using CSPICE, we can create the 
        CSPICE planes projpl and invpl using the code fragment 
 
           nvp2pl_c  ( projn,  vin,  &projpl ); 
           nvc2pl_c  ( invn,   invc, &invpl  ); 
 
        and then perform the inverse projection using the call 
 
           vprjpi_c ( vin, &projpl, &invpl, vout );
 
        vprjpi_c will return the value 
 
           vout = ( 0.0, 1.0, 1.0 );
 
-Restrictions
 
   None. 
 
-Literature_References
 
   [1] `Calculus and Analytic Geometry', Thomas and Finney. 
 
-Author_and_Institution
 
   N.J. Bachman   (JPL) 
 
-Version
 
   -CSPICE Version 1.1.0, 05-APR-2004 (NJB)
 
      Computation of LIMIT was re-structured to avoid
      run-time underflow warnings on some platforms.

   -CSPICE Version 1.0.0, 05-MAR-1999 (NJB)

-Index_Entries
 
   vector projection onto plane inverted 
 
-&
*/


/*
-Revisions

   -CSPICE Version 1.1.0, 05-APR-2004 (NJB)

      Computation of LIMIT was re-structured to avoid run-time
      underflow warnings on some platforms. In the revised code,
      BOUND/dpmax_c() is never scaled by a number having absolute value
      < 1.

-&
*/


{ /* Begin vprjpi_c */

   /*
   Local constants
   */
 
   /*
   BOUND is used to bound the magnitudes of the numbers that we
   try to take the reciprocal of, since we can't necessarily invert
   any non-zero number.  We won't try to invert any numbers with
   magnitude less than
 
      BOUND / dpmax_c()
 
   BOUND is chosen somewhat arbitrarily....
   */
   
   #define BOUND      10.0
 


   /*
   Local variables
   */
   SpiceDouble             denom;
   SpiceDouble             invc;
   SpiceDouble             invn   [3];
   SpiceDouble             limit;
   SpiceDouble             mult;
   SpiceDouble             numer;
   SpiceDouble             projc;
   SpiceDouble             projn  [3];



   /*
   Participate in error tracing.
   */
   
   if ( return_c() ) 
   {  
      return;
   }
   
   chkin_c ( "vprjpi_c" );

 
   /*
   Unpack the planes.
   */
   pl2nvc_c ( projpl, projn, &projc );
   pl2nvc_c ( invpl,  invn,  &invc  );
 
   /*
   We'll first discuss the computation of VOUT in the nominal case,
   and then deal with the exceptional cases.

   When projpl and invpl are not orthogonal to each other, the
   inverse projection of vin will differ from vin by a multiple of
   projn, the unit normal vector to projpl.  We find this multiple
   by using the fact that the inverse projection vout satisfies the
   plane equation for the inverse projection plane invpl.

      We have

         vout = vin  +  mult * projn;                           (1)

      since vout satisfies

         < vout, invn >  =  invc

      we must have

         <  vin  +  mult * projn,  invn  > = invc

      which in turn implies


                   invc  -  < vin, invn >
         mult  =  ------------------------.                     (2)
                      < projn, invn >

      Having mult, we can compute vout according to equation (1).

   Now, if the denominator in the above expression for mult is zero
   or just too small, performing the division would cause a
   divide-by-zero error or an overflow of mult.  In either case, we
   will avoid carrying out the division, and we'll set found to
   SPICEFALSE.
   
 
   Compute the numerator and denominator of the right side of (2).
   */
   
   numer  =  invc - vdot_c ( vin,   invn );
   denom  =         vdot_c ( projn, invn );
   
 
   /*
   If the magnitude of the denominator is greater than
   
                         BOUND
      limit  =  abs (  ---------- * numer  ),
                        dpmax_c()

   we can safely divide the numerator by the denominator, and the
   magnitude of the result will be no greater than

       dpmax_c()
      ----------- .
        BOUND

   Note that we have ruled out the case where numer and denom are
   both zero by insisting on strict inequality in the comparison of
   denom and limit:
   */
 
   if ( fabs(numer) < 1.0 )
   {
      limit  =  fabs ( BOUND / dpmax_c() );
   }
   else
   {
      limit  =  fabs (  ( BOUND / dpmax_c() ) * numer  );
   }
 
   *found  =  ( fabs (denom) > limit );
   
   
   if ( *found )  
   {
      /*
      We'll compute vout after all.
      */
      mult = numer / denom;

      vlcom_c ( 1.0, vin, mult, projn, vout );
   }


   chkout_c ( "vprjpi_c" );

} /* End vprjpi_c */
示例#15
0
void kdata_c ( SpiceInt          which,
               ConstSpiceChar  * kind,
               SpiceInt          fillen,
               SpiceInt          typlen,
               SpiceInt          srclen,
               SpiceChar       * file,
               SpiceChar       * filtyp,
               SpiceChar       * source,
               SpiceInt        * handle,
               SpiceBoolean    * found  )
/*

-Brief_I/O

   VARIABLE  I/O  DESCRIPTION
   --------  ---  --------------------------------------------------
   which      I   Index of kernel to fetch from the list of kernels.
   kind       I   The kind of kernel to which fetches are limited.
   fillen     I   Available space in output file string.
   typlen     I   Available space in output kernel type string.
   srclen     I   Available space in output source string.
   file       O   The name of the kernel file.
   filtyp     O   The type of the kernel.
   source     O   Name of the source file used to load file.
   handle     O   The handle attached to file.
   found      O   SPICETRUE if the specified file could be located.

-Detailed_Input

   which      is the number of the kernel to fetch (matching the
              type specified by kind) from the list of kernels that
              have been loaded through the entry point furnsh_c but
              that have not been unloaded through the entry point
              unload_c.

              The range of which is 0 to count-1, where count is
              the number of kernels loaded via furnsh_c.  This
              count may be obtained by calling ktotal_c.  See the
              Examples section for an illustrative code fragment.


   kind       is a list of types of kernels to be considered when
              fetching kernels from the list of loaded kernels. KIND
              should consist of a list of words of kernels to
              examine.  Recognized types are

                 SPK  --- All SPK files are counted in the total.
                 CK   --- All CK files are counted in the total.
                 PCK  --- All binary PCK files are counted in the
                          total.
                 EK   --- All EK files are counted in the total.
                 TEXT --- All text kernels that are not meta-text
                          kernels are included in the total.
                 META --- All meta-text kernels are counted in the
                          total.
                 ALL  --- Every type of kernel is counted in the
                          total.

               kind is case insensitive.  If a word appears in kind
               that is not one of those listed above it is ignored.

               See the entry point ktotal_c for examples of the use
               of kind.

   fillen      is the amount of available space in the output file
               string, including room for the terminating null.
               Normally, this is the declared length of the output
               string.

   typlen      is the amount of available space in the output kernel
               type string.

   srclen      is the amount of available space in the output kernel
               source string.


-Detailed_Output


   file        is the name of the file having index which in the
               sequence of files of type kind currently loaded via
               furnsh_c.  file will be blank if there is no such kernel
               is loaded.

   filtyp      is the type of the kernel specified by file.  filtyp
               will be empty if there is no file matching the
               specification of which and kind.

   source      is the name of the source file that was used to
               specify file as one to load.  If file was loaded
               directly via a call to furnsh_c, source will be empty.
               If there is no file matching the specification of
               which and kind, source will be empty.

   handle      is the handle attached to file if it is a binary
               kernel.  If file is a text kernel or meta-text kernel
               handle will be zero.  If there is no file matching
               the specification of which and kind, handle will be
               set to zero.

   found       is returned SPICETRUE if a file matching the
               specification of which and kind exists.  If there is no
               such file, found will be set to SPICEFALSE.

-Parameters

   None.

-Exceptions

   1) If a file is not loaded matching the specification of which
      and kind, found will be SPICEFALSE; file, filtyp, and source
      will be empty and handle will be set to zero.

   2) If any input or output character argument pointer is null, the
      error SPICE(NULLPOINTER) will be signaled.

   3) If any of the output string length arguments are less than 1, the
      error SPICE(STRINGTOOSHORT) will be signaled.

   4) If any output string has length at least 1 but is too short to
      contain the output string, the corresponding is truncated on the
      right.  The output string is still null-terminated.

-Files

   None.

-Particulars

   This entry point allows you to determine which kernels have
   been loaded via furnsh_c and to obtain information sufficient
   to directly query those files.

-Examples

   The following example shows how you could print a summary
   of SPK files that have been loaded through the interface
   furnsh_c.

      #include <stdio.h>
      #include "SpiceUsr.h"

      #define  FILLEN   128
      #define  TYPLEN   32
      #define  SRCLEN   128

      SpiceInt        which;
      SpiceInt        count;
      SpiceInt        handle;

      SpiceChar       file  [FILLEN];
      SpiceChar       filtyp[TYPLEN];
      SpiceChar       source[SRCLEN];

      SpiceBoolean    found;

      int main()
         {
         furnsh_c( "/kernels/standard.tm" );

         ktotal_c ( "spk", &count );

         if ( count == 0 )
            {
            printf ( "No SPK files loaded at this time.\n" );
            }
         else
            {
            printf ( "The loaded SPK files are: \n\n" );
            }

         for ( which = 0;  which < count;  which++ )
            {
            kdata_c ( which,  "spk",    FILLEN,   TYPLEN, SRCLEN,
                      file,   filtyp,  source,  &handle,  &found );
            printf ( "%s\n",  file   );
            }

         }

-Restrictions

   None.

-Literature_References

   None.

-Author_and_Institution

   N.J. Bachman    (JPL)
   W.L. Taber      (JPL)

-Version

   -CSPICE Version 1.1.3, 02-MAY-2008 (EDW)

      standard.ker renamed standard.tm

   -CSPICE Version 1.1.2, 05-SEP-2007 (EDW)

      Expanded Examples section to a full, compilable program.

   -CSPICE Version 1.1.1, 29-DEC-2004 (LSE)

      Corrected example code to match routine's argument list.
      (2 arguments reversed)

   -CSPICE Version 1.1.0, 02-FEB-2003 (EDW)

      Corrected example code to match routine's argument list.

   -CSPICE Version 1.0.0, 12-SEP-1999 (NJB) (WLT)

-Index_Entries

   Retrieve information on loaded SPICE kernels

-&
*/

{   /* Begin kdata_c */


    /*
    Local variables
    */
    logical                 fnd;


    /*
    Participate in error tracing.
    */
    chkin_c ( "kdata_c" );


    /*
    Check the input string kind to make sure the pointer is non-null
    and the string length is non-zero.
    */
    CHKFSTR ( CHK_STANDARD, "kdata_c", kind );


    /*
    Make sure the output string file has at least enough room for one
    output character and a null terminator.  Also check for a null
    pointer.
    */
    CHKOSTR ( CHK_STANDARD, "kdata_c", file, fillen );


    /*
    Make sure the output string filtyp has at least enough room for one
    output character and a null terminator.  Also check for a null
    pointer.
    */
    CHKOSTR ( CHK_STANDARD, "kdata_c", filtyp, typlen );


    /*
    Make sure the output string source has at least enough room for one
    output character and a null terminator.  Also check for a null
    pointer.
    */
    CHKOSTR ( CHK_STANDARD, "kdata_c", source, srclen );


    /*
    Map the input index from C to Fortran style.
    */

    which++;


    /*
    Call the f2c'd routine.
    */
    kdata_ (  ( integer   * ) &which,
              ( char      * ) kind,
              ( char      * ) file,
              ( char      * ) filtyp,
              ( char      * ) source,
              ( integer   * ) handle,
              ( logical   * ) &fnd,
              ( ftnlen      ) strlen(kind),
              ( ftnlen      ) fillen-1,
              ( ftnlen      ) typlen-1,
              ( ftnlen      ) srclen-1     );


    /*
    Convert the output strings from Fortran style to C style.  Set
    the SpiceBoolean output found flag.
    */
    F2C_ConvertStr( fillen, file   );
    F2C_ConvertStr( typlen, filtyp );
    F2C_ConvertStr( srclen, source );

    *found = fnd;


    chkout_c ( "kdata_c" );

} /* End kdata_c */
示例#16
0
   void dtpool_c ( ConstSpiceChar   * name,
                   SpiceBoolean     * found,
                   SpiceInt         * n,
                   SpiceChar          type [1] ) 

/*

-Brief_I/O
 
   VARIABLE  I/O  DESCRIPTION 
   --------  ---  -------------------------------------------------- 
   name       I   Name of the variable whose value is to be returned. 
   found      O   True if variable is in pool. 
   n          O   Number of values returned for name. 
   type       O   Type of the variable:  'C', 'N', or 'X' 
 
-Detailed_Input
 
   name       is the name of the variable whose values are to be 
              returned. 
  
-Detailed_Output
 
 
   found      is SPICETRUE if the variable is in the pool;
              SPICEFALSE if it is not. 
 
   n          is the number of values associated with name. 
              If name is not present in the pool n will be returned 
              with the value 0. 
 
   type       is a single character indicating the type of the variable
              associated with name. 
 
                  'C' if the data is character data 
                  'N' if the data is numeric. 
                  'X' if there is no variable name in the pool. 
 
-Parameters
 
   None. 
 
-Exceptions
 
   1) If the name requested is not in the kernel pool, found 
      will be set to SPICEFALSE, n to zero and type to 'X'. 
 
   2) If the input string pointer is null, the error SPICE(NULLPOINTER) 
      will be signaled.
      
   3) If the input string has length zero, the error SPICE(EMPTYSTRING) 
      will be signaled.
      
 
-Files
 
   None. 
 
-Particulars
 
   This routine allows you to determine whether or not a kernel 
   pool variable is present and to determine its size and type 
   if it is. 
 
 
-Examples
 
 
   The following code fragment demonstrates how to determine the 
   properties of a stored kernel variable. 
 
      #include <stdio.h>
      #include "SpiceUsr.h"
            .
            .
            .
      dtpool_c ( varnam, &found, &n, &type );
 
      if ( found ) 
      {
         printf ( "\n"
                  "Properties of variable %s:\n"
                  "\n"
                  "   Size: %d\n",
                  varnam,
                  n                           );
         
         if ( type == 'C' )
         {
            printf ( "   Type:  Character\n" );
         }
         else
         {
            printf ( "   Type:  Numeric\n" );
         }
      }
      
      else
      { 
         printf ( "%s is not present in the kernel pool.\n", varnam );
      } 
 
 
-Restrictions
 
   None. 
 
-Literature_References
 
   None. 
 
-Author_and_Institution
 
   W.L. Taber  (JPL) 
 
-Version
 
   -CSPICE Version 1.1.0, 17-OCT-1999 (NJB)  
   
      Local type logical variable now used for found flag used in
      interface of dtpool_.
            
   -CSPICE Version 1.0.0, 10-MAR-1999 (NJB)

-Index_Entries
 
   return summary information about a kernel pool variable
 
-&
*/

{ /* Begin dtpool_c */

   /*
   Local variables
   */
   logical                 fnd;
   
   
   /*
   Participate in error tracing.
   */
   chkin_c ( "dtpool_c" );


   /*
   Check the input string name to make sure the pointer is non-null
   and the string length is non-zero.
   */
   CHKFSTR ( CHK_STANDARD, "dtpool_c", name );


   /*
   Call the f2c'd routine.
   */
   dtpool_ ( ( char     * ) name,
             ( logical  * ) &fnd,
             ( integer  * ) n,
             ( char     * ) type,
             ( ftnlen     ) strlen(name), 
             ( ftnlen     ) 1             );
   
   /*
   Assign the SpiceBoolean found flag.
   */
   
   *found = fnd;
   
   
   chkout_c ( "dtpool_c" );

} /* End dtpool_c */
示例#17
0
文件: dafrfr_c.c 项目: Dbelsa/coft
   void dafrfr_c ( SpiceInt     handle,
                   SpiceInt     lenout,
                   SpiceInt   * nd,
                   SpiceInt   * ni,
                   SpiceChar  * ifname,
                   SpiceInt   * fward,
                   SpiceInt   * bward,
                   SpiceInt   * free    ) 

/*

-Brief_I/O
 
   Variable  I/O  Description 
   --------  ---  -------------------------------------------------- 
   handle     I   Handle of an open DAF file. 
   lenout     I   Available room in the output string `ifname'.
   nd         O   Number of double precision components in summaries. 
   ni         O   Number of integer components in summaries. 
   ifname     O   Internal file name. 
   fward      O   Forward list pointer. 
   bward      O   Backward list pointer. 
   free       O   Free address pointer. 
 
-Detailed_Input
 
   handle         is the handle assigned to a DAF file opened for 
                  reading. 

   lenout         is the maximum number of characters that can be 
                  accommodated in the output string `ifname'. This count 
                  includes room for the terminating null character.
                  DAF internal file names may contain up to 60 
                  characters, so lenout normally should be set to 61.

-Detailed_Output
 
   nd, 
   ni          are the numbers of double precision and integer 
               components, respectively, in each array summary in 
               the specified file. 
 
   ifname      is the internal file name stored in the first 
               (or file) record of the specified file. `ifname'
               should be declared with the length specified by
               `lenout'.
 
   fward       is the forward list pointer. This points to the 
               first summary record in the file. (Records between 
               the first record and the first summary record are 
               reserved when the file is created, and are invisible 
               to DAF routines.) 

               DAF list pointers are actually Fortran record numbers,
               and as such, start at one.
 
   bward       is the backward list pointer. This points 
               to the final summary record in the file. 

 
   free        is the free address pointer. This contains the 
               first free address in the file. (That is, the 
               initial address of the next array to be added 
               to the file.)  

               `free' is a DAF address; for compatiblity with
               SPICELIB, the range of DAF addresses starts at 1.
 
-Parameters
 
   None. 
 
-Exceptions
 
   1) If the handle passed to this routine is not the handle of an 
      open DAF file, the error will be signaled by a routine called 
      by this routine. 
 
   2) If the specified DAF file is not open for read access, the 
      error will be diagnosed by a routine called by this routine. 
 
   3) If the specified record cannot (for some reason) be read, 
      the error SPICE(DAFFRNOTFOUND) is signaled. 
 
-Files
 
   The input `handle' should refer to a DAF file open for read
   or write access.
 
-Particulars
 
   The file record of a DAF is the only record that contains 
   any global information about the file. This record is created 
   when the file is created, and is updated only when new arrays 
   are added. 
 
   Like character records, file records are not buffered. 
 
-Examples
 
   In the following example, the file record of a DAF is read
   to determine the first free address in the file.
 
      #include <stdio.h>
      #include "SpiceUsr.h"

      int main ( int argc, char ** argv )
      {
         #define IFNLEN   61

         SpiceChar               ifname[IFNLEN];

         SpiceInt                bward;
         SpiceInt                free;
         SpiceInt                fward;
         SpiceInt                handle;
         SpiceInt                nd;
         SpiceInt                ni;

         dafopr_c ( argv[1], &handle );

         dafrfr_c ( handle, IFNLEN, &nd, &ni, ifname, &fward, &bward, &free );

         printf ( "First free DAF address is %ld.\n", free );

         return ( 0 );
      } 

 
-Restrictions
 
   None. 
 
-Literature_References

   None.

-Author_and_Institution
 

   N.J. Bachman    (JPL)
   K.R. Gehringer  (JPL) 
   I.M. Underwood  (JPL) 
 
-Version
 
   -CSPICE Version 1.0.0, 17-JUN-2009 (NJB) (KRG) (IMU)

-Index_Entries
 
   read daf file record 
 
-&
*/

{ /* Begin dafrfr_c */

   /*
   Participate in error tracing.
   */
   chkin_c ( "dafrfr_c" );

   dafrfr_ ( (integer *) &handle,
             (integer *) nd,
             (integer *) ni,
             (char    *) ifname,
             (integer *) fward,
             (integer *) bward,
             (integer *) free,
             (ftnlen   ) lenout-1 );
  
   /*
   Convert the internal file name to a C-style string. 
   */
   F2C_ConvertStr ( lenout, ifname );


   chkout_c ( "dafrfr_c" );

} /* End dafrfr_c */
示例#18
0
   void spkw09_c ( SpiceInt             handle,
                   SpiceInt             body,
                   SpiceInt             center, 
                   ConstSpiceChar     * frame,
                   SpiceDouble          first,
                   SpiceDouble          last,
                   ConstSpiceChar     * segid,
                   SpiceInt             degree,
                   SpiceInt             n,
                   ConstSpiceDouble     states[][6],
                   ConstSpiceDouble     epochs[]     )
/*

-Brief_I/O
 
   Variable  I/O  Description 
   --------  ---  -------------------------------------------------- 
   handle     I   Handle of an SPK file open for writing. 
   body       I   NAIF code for an ephemeris object. 
   center     I   NAIF code for center of motion of body. 
   frame      I   Reference frame name. 
   first      I   Start time of interval covered by segment. 
   last       I   End time of interval covered by segment. 
   segid      I   Segment identifier. 
   degree     I   Degree of interpolating polynomials. 
   n          I   Number of states. 
   states     I   Array of states. 
   epochs     I   Array of epochs corresponding to states. 
   maxdeg     P   Maximum allowed degree of interpolating polynomial. 
 
-Detailed_Input
 
   handle         is the file handle of an SPK file that has been 
                  opened for writing. 
 
   body           is the NAIF integer code for an ephemeris object 
                  whose state relative to another body is described 
                  by the segment to be created. 
 
   center         is the NAIF integer code for the center of motion 
                  of the object identified by body. 
 
   frame          is the NAIF name for a reference frame 
                  relative to which the state information for body 
                  is specified. 
 
   first, 
   last           are, respectively, the start and stop times of 
                  the time interval over which the segment defines 
                  the state of body. 
 
   segid          is the segment identifier.  An SPK segment 
                  identifier may contain up to 40 characters. 
 
   degree         is the degree of the Lagrange polynomials used to 
                  interpolate the states.  All components of the 
                  state vectors are interpolated by polynomials of 
                  fixed degree. 
 
   n              is the number of states in the input state vector 
                  array. 
 
   states         contains a time-ordered array of geometric states 
                  ( x, y, z, dx/dt, dy/dt, dz/dt, in kilometers and 
                  kilometers per second ) of body relative to center, 
                  specified relative to frame. 
 
   epochs         is an array of epochs corresponding to the members 
                  of the state array.  The epochs are specified as 
                  seconds past J2000, TDB. 
 
-Detailed_Output
 
   None.  See $Particulars for a description of the effect of this 
   routine. 
 
-Parameters
 
   MAXDEG         is the maximum allowed degree of the interpolating 
                  polynomial.  If the value of MAXDEG is increased, 
                  the CSPICE routine spkpvn_ must be changed 
                  accordingly.  In particular, the size of the 
                  record passed to spkrNN_ and spkeNN_ must be 
                  increased, and comments describing the record size 
                  must be changed. 
                  
                  The current value of MAXDEG is 15.
 
-Exceptions
 
   If any of the following exceptions occur, this routine will return 
   without creating a new segment. 
 
   1)  If frame is not a recognized name, the error 
       SPICE(INVALIDREFFRAME) is signaled. 
 
   2)  If the last non-blank character of segid occurs past index 40, 
       the error SPICE(SEGIDTOOLONG) is signaled. 
 
   3)  If segid contains any nonprintable characters, the error 
       SPICE(NONPRINTABLECHARS) is signaled. 
 
   4)  If degree is not at least 1 or is greater than MAXDEG, the 
       error SPICE(INVALIDDEGREE) is signaled. 
 
   5)  If the number of states n is not at least degree+1, the error 
       SPICE(TOOFEWSTATES) will be signaled. 
 
   6)  If first is greater than or equal to last then the error 
       SPICE(BADDESCRTIMES) will be signaled. 
 
   7)  If the elements of the array epochs are not in strictly 
       increasing order, the error SPICE(TIMESOUTOFORDER) will be 
       signaled. 
 
   8)  If the first epoch epochs[0] is greater than first, the error 
       SPICE(BADDESCRTIMES) will be signaled. 
 
   9)  If the last epoch epochs[n] is less than last, the error 
       SPICE(BADDESCRTIMES) will be signaled. 
 
   10) If either the input frame or segment ID string pointer is null,
       the error SPICE(NULLPOINTER) is signaled.
   
   11) If either the input frame or segment ID string is empty,
       the error SPICE(EMPTYSTRING) is signaled.
   
-Files
 
   A new type 9 SPK segment is written to the SPK file attached 
   to handle. 
 
-Particulars
 
   This routine writes an SPK type 09 data segment to the open SPK 
   file according to the format described in the type 09 section of 
   the SPK Required Reading. The SPK file must have been opened with 
   write access. 
 
-Examples
 
   Suppose that you have states and are prepared to produce 
   a segment of type 09 in an SPK file. 
 
   The following code fragment could be used to add the new segment 
   to a previously opened SPK file attached to HANDLE. The file must 
   have been opened with write access. 
 
      #include "SpiceUsr.h"
           .
           .
           .
        
      /.
      Create a segment identifier. 
      ./
      #define  SEGID  "MY_SAMPLE_SPK_TYPE_9_SEGMENT" 
 
        
      /.
      Write the segment. 
      ./
        
      spkw09_c ( handle,  body,    center,  frame, 
                 first,   last,    segid,   degree, 
                 n,       states,  epochs          );
 
-Restrictions
 
   None. 
 
-Literature_References
 
   None. 
 
-Author_and_Institution
 
   K.R. Gehringer (JPL) 
   N.J. Bachman   (JPL) 
   J.M. Lynch     (JPL) 
   W.L. Taber     (JPL) 
 
-Version
 
   -CSPICE Version 1.0.0, 21-JUN-1999 (KRG) (NJB) (JML) (WLT)

-Index_Entries
 
   write spk type_9 ephemeris data segment 
 
-&
*/

{ /* Begin spkw09_c */



   /*
   Participate in error tracing.
   */
   chkin_c ( "spkw09_c" );


   /*
   Check the input strings to make sure the pointers
   are non-null and the string lengths are non-zero.
   */
   CHKFSTR ( CHK_STANDARD, "spkw09_c", frame );
   CHKFSTR ( CHK_STANDARD, "spkw09_c", segid );
 

   /*
   Write the segment. 
   */
   spkw09_ ( ( integer    * ) &handle,
             ( integer    * ) &body,
             ( integer    * ) &center,
             ( char       * ) frame,
             ( doublereal * ) &first,
             ( doublereal * ) &last,
             ( char       * ) segid,
             ( integer    * ) &degree,
             ( integer    * ) &n,
             ( doublereal * ) states,
             ( doublereal * ) epochs,
             ( ftnlen       ) strlen(frame),
             ( ftnlen       ) strlen(segid)  );


   chkout_c ( "spkw09_c" );

} /* End spkw09_c */
示例#19
0
文件: spkw02_c.c 项目: haisamido/GMAT
   void spkw02_c ( SpiceInt                handle,
                   SpiceInt                body,
                   SpiceInt                center,
                   ConstSpiceChar        * frame,
                   SpiceDouble             first,
                   SpiceDouble             last,
                   ConstSpiceChar        * segid,
                   SpiceDouble             intlen,
                   SpiceInt                n,
                   SpiceInt                polydg,
                   ConstSpiceDouble        cdata [],
                   SpiceDouble             btime     )

/*

-Brief_I/O
 
   Variable  I/O  Description 
   --------  ---  -------------------------------------------------- 
   handle     I   Handle of an SPK file open for writing. 
   body       I   Body code for ephemeris object. 
   center     I   Body code for the center of motion of the body. 
   frame      I   The reference frame of the states. 
   first      I   First valid time for which states can be computed. 
   last       I   Last valid time for which states can be computed. 
   segid      I   Segment identifier. 
   intlen     I   Length of time covered by logical record. 
   n          I   Number of coefficient sets. 
   polydg     I   Chebyshev polynomial degree. 
   cdata      I   Array of Chebyshev coefficients. 
   btime      I   Begin time of first logical record. 
 
-Detailed_Input
 
   handle         DAF handle of an SPK file to which a type 2 segment 
                  is to be added.  The SPK file must be open for 
                  writing. 
 
   body           NAIF integer code for an ephemeris object whose 
                  state relative to another body is described by the 
                  segment to be created. 
 
   center         NAIF integer code for the center of motion of the 
                  object identified by body. 
 
   frame          NAIF name for a reference frame relative to which 
                  the state information for body is specified. 
 
   first, 
   last           Start and stop times of the time interval over 
                  which the segment defines the state of body. 
 
   segid          Segment identifier.  An SPK segment identifier may 
                  contain up to 40 characters. 
 
   intlen         Length of time, in seconds, covered by each set of 
                  Chebyshev polynomial coefficients (each logical 
                  record).  Each set of Chebyshev coefficients must 
                  cover this fixed time interval, intlen. 
 
   n              Number of sets of Chebyshev polynomial coefficients 
                  for coordinates (number of logical records) to be 
                  stored in the segment.  There is one set of 
                  Chebyshev coefficients for each time period. 
 
   polydg         Degree of each set of Chebyshev polynomials, i.e. 
                  the number of Chebyshev coefficients per coordinate 
                  minus one. 
 
   cdata          Array containing all the sets of Chebyshev 
                  polynomial coefficients to be placed in the 
                  segment of the SPK file.  The coefficients are 
                  stored in cdata in order as follows: 
 
                     the (degree + 1) coefficients for the first 
                     coordinate of the first logical record 
 
                     the coefficients for the second coordinate 
 
                     the coefficients for the third coordinate 
 
                     the coefficients for the first coordinate for 
                     the second logical record, ... 
 
                     and so on. 
 
 
   btime          Begin time (seconds past J2000 TDB) of first set 
                  of Chebyshev polynomial coefficients (first 
                  logical record).  first is an appropriate value 
                  for btime. 
 
-Detailed_Output
 
   None. 
 
-Parameters
 
   None. 
 
-Exceptions
 
   1) If the number of sets of coefficients is not positive 
      SPICE(NUMCOEFFSNOTPOS) is signalled. 
 
   2) If the interval length is not positive, SPICE(INTLENNOTPOS) 
      is signalled. 
 
   3) If the integer code for the reference frame is not recognized, 
      SPICE(INVALIDREFFRAME) is signalled. 
 
   4) If segment stop time is not greater then the begin time, 
       SPICE(BADDESCRTIMES) is signalled. 
 
   5) If the start time of the first record is not less than 
      or equal to the descriptor begin time, SPICE(BADDESCRTIMES) 
      is signalled. 
 
   6) If the end time of the last record is not greater than 
      or equal to the descriptor end time, SPICE(BADDESCRTIMES) is 
      signalled. 
 
   7) The error SPICE(EMPTYSTRING) is signaled if either input
      string does not contain at least one character, since the
      input strings cannot be converted to a Fortran-style string
      in this case.
      
   8) The error SPICE(NULLPOINTER) is signaled if either input string
      pointer is null.

-Files
 
   A new type 2 SPK segment is written to the SPK file attached 
   to handle. 
 
-Particulars
 
   This routine writes an SPK type 2 data segment to the designated 
   SPK file, according to the format described in the SPK Required 
   Reading. 
 
   Each segment can contain data for only one target, central body, 
   and reference frame.  The Chebyshev polynomial degree and length 
   of time covered by each logical record are also fixed.  However, 
   an arbitrary number of logical records of Chebyshev polynomial 
   coefficients can be written in each segment.  Minimizing the 
   number of segments in an SPK file will help optimize how the SPICE 
   system accesses the file. 
 
-Examples
 
   Suppose that you have sets of Chebyshev polynomial coefficients 
   in an array CDATA pertaining to the position of the moon (NAIF ID 
   = 301), relative to the Earth-moon barycenter (NAIF ID = 3), in 
   the J2000 reference frame, and want to put these into a type 2 
   segment in an existing SPK file.  The following code could be used 
   to add one new type 2 segment.  To add multiple segments, put the 
   call to spkw02_c in a loop. 
 
      #include "SpiceUsr.h"
           .
           .
           .
           
      /.
      First open the SPK file and get a handle for it. 
      ./
      spkopa_c ( spknam, &handle ); 

      /.
      Create a segment identifier. 
      ./
      segid = "MY_SAMPLE_SPK_TYPE_2_SEGMENT";

      /.
      Write the segment. 
      ./
      spkw02_c ( handle, 301,    3,      "J2000", 
                 first,  last,   segid,  intlen, 
                 n,      polydg, cdata,  btime   ); 

      /.
      Close the file. 
      ./
      spkcls_c ( handle );
      
 
-Restrictions
 
   None. 
 
-Literature_References
 
   None. 
 
-Author_and_Institution
 
   N.J. Bachman   (JPL)
   K.S. Zukor     (JPL) 
 
-Version
 
   -CSPICE Version 1.0.0, 21-JUL-1999 (NJB) (KSZ)

-Index_Entries
 
   write spk type_2 data segment 
 
-&
*/

{ /* Begin spkw02_c */

   /*
   Participate in error tracing.
   */
   chkin_c ( "spkw02_c" );

 
   /*
   Check the input strings to make sure the pointers
   are non-null and the string lengths are non-zero.
   */
   CHKFSTR ( CHK_STANDARD, "spkw02_c", frame );
   CHKFSTR ( CHK_STANDARD, "spkw02_c", segid );
 

   /*
   Write the segment. 
   */
   
   spkw02_ ( ( integer    * ) &handle,
             ( integer    * ) &body,
             ( integer    * ) &center,
             ( char       * ) frame,
             ( doublereal * ) &first,
             ( doublereal * ) &last,
             ( char       * ) segid,
             ( doublereal * ) &intlen,
             ( integer    * ) &n,
             ( integer    * ) &polydg,
             ( doublereal * ) cdata,
             ( doublereal * ) &btime,
             ( ftnlen       ) strlen(frame),
             ( ftnlen       ) strlen(segid)  );


   chkout_c ( "spkw02_c" );

} /* End spkw02_c */
示例#20
0
文件: zzadstep_c.c 项目: Dbelsa/coft
   int zzadstep_c ( doublereal  * time,
                    doublereal  * step  ) 

/*

-Brief_I/O
 
   VARIABLE  I/O  DESCRIPTION 
   --------  ---  -------------------------------------------------- 
   time       I   Time from which the next step will be taken. 
   step       O   Time step to take. 
 
-Detailed_Input
  
   time     is the input start time from which the algorithm is to
            search forward for a state transition. `time' is expressed
            as seconds past J2000 TDB.  
 

-Detailed_Output  
 
   step     is the output step size. `step' is the value stored via the
            last call to gfsstp_c. Units are TDB seconds.
 
-Parameters
 
   None. 
 
-Exceptions
 
   1) A run-time error will result if this routine is called before
      a valid pointer to a CSPICE-style GF step size function has
      been stored via a call to zzadsave_c.

      The argument list of the stored function must match that of
      gfstep_c.
 
-Files
 
   None. 
 
-Particulars
 
   This routine is meant to be passed to f2c'd Fortran GF code
   that requires a step size function input argument. The argument
   list of this routine matches that of the f2c'd routine

      gfstep_

   This routine calls the CSPICE-style stepsize function passed
   into a CSPICE wrapper for an intermediate-level GF function.
   A pointer to this step size function must be stored via
   a call to zzadsave_c before this routine is called.

   When set properly, `step' indicates how far to advance `time' so
   that `time' and `time+step' may bracket a state transition and
   definitely do not bracket more than one state transition.

   The calling application can change the step size value via the entry
   point gfsstp_c.
 
-Examples
 
   None. 
 
-Restrictions
 
   1) This function is intended only for internal use by GF routines.   
 
-Literature_References
 
   None. 
 
-Author_and_Institution
 
   N.J. Bachman   (JPL)
   L.S. Elson     (JPL)
   W.L. Taber     (JPL) 
   I.M. Underwood (JPL) 
   E.D. Wright    (JPL)  
 
-Version
 
   -CSPICE Version 1.0.0, 24-MAR-2008 (NJB)

-Index_Entries
 
   adapter for gf step size function
 

-&
*/

{ /* Begin zzadstep_c */


   /*
   Local variables 
   */
   void           ( * fPtr ) ( SpiceDouble,
                               SpiceDouble * );


   /*
   Participate in error tracing.
   */

   if ( return_c() )
   {
      return ( 0 );
   }
   chkin_c ( "zzadstep_c" );

   /*
   Retrieve the stored pointer for the passed-in function; cast
   the pointer from (void *) to that of a function whose argument
   list matches that of gfstep_c.
   */

   fPtr = (  void (*) (SpiceDouble, SpiceDouble*)  )  zzadget_c ( UDSTEP );

   /*
   Call the stored function. 
   */
   
   (*fPtr) ( (SpiceDouble)(*time), (SpiceDouble *)step );


   chkout_c ( "zzadstep_c" );

   return ( 0 );

} /* End zzadstep_c */
示例#21
0
文件: spk14b_c.c 项目: Dbelsa/coft
   void spk14b_c (  SpiceInt           handle,
                    ConstSpiceChar   * segid,
                    SpiceInt           body,
                    SpiceInt           center,
                    ConstSpiceChar   * frame,
                    SpiceDouble        first,
                    SpiceDouble        last,
                    SpiceInt           chbdeg  )
/*

-Brief_I/O
 
   VARIABLE  I/O  DESCRIPTION 
   --------  ---  -------------------------------------------------- 
   handle     I   The handle of an SPK file open for writing. 
   segid      I   The string to use for segment identifier. 
   body       I   The NAIF ID code for the body of the segment. 
   center     I   The center of motion for body. 
   frame      I   The reference frame for this segment. 
   first      I   The first epoch for which the segment is valid. 
   last       I   The last epoch for which the segment is valid. 
   chbdeg     I   The degree of the Chebyshev Polynomial used. 
 
-Detailed_Input
 
   handle         is the file handle of an SPK file that has been 
                  opened for writing. 
 
   segid          is the segment identifier. An SPK segment identifier 
                  may contain up to 40 printing ASCII characters. 
 
   body           is the NAIF ID for the body whose states are 
                  to be recorded in an SPK file. 
 
   center         is the NAIF ID for the center of motion associated 
                  with body. 
 
   frame          is the reference frame that states are referenced to, 
                  for example "J2000". 
 
   first          is the starting epoch, in TDB seconds past J2000, for 
                  the ephemeris data to be placed into the segment. 
 
   last           is the ending epoch, in TDB seconds past J2000, for 
                  the ephemeris data to be placed into the segment. 
 
   chbdeg         is the degree of the Chebyshev Polynomials used to 
                  represent the ephemeris information stored in the 
                  segment. 
 
-Detailed_Output
 
   None.          The input data is used to create the segment summary 
                  for the segment being started in the SPK file 
                  associated with handle. 
 
                  See the Particulars section for details about the 
                  structure of a type 14 SPK segment. 
 
-Parameters
 
   None.
    
-Particulars
 
   This routine begins writing a type 14 SPK segment to the open SPK 
   file that is associated with handle. The file must have been 
   opened with write access. 
 
   This routine is one of a set of three routines for creating and 
   adding data to type 14 SPK segments. These routines are: 
 
      spk14b_c: Begin a type 14 SPK segment. This routine must be 
                called before any data may be added to a type 14 
                segment. 
 
      spk14a_c: Add data to a type 14 SPK segment. This routine may be 
                called any number of times after a call to spk14b_c to 
                add type 14 records to the SPK segment that was 
                started. 
 
      spk14e_c: End a type 14 SPK segment. This routine is called to 
                make the type 14 segment a permanent addition to the 
                SPK file. Once this routine is called, no further type 
                14 records may be added to the segment. A new segment 
                must be started. 
 
   A type 14 SPK segment consists of coefficient sets for fixed order 
   Chebyshev polynomials over consecutive time intervals, where the 
   time intervals need not all be of the same length. The Chebyshev 
   polynomials represent the position, X, Y, and Z coordinates, and 
   the velocities, dX/dt, dY/dt, and dZ/dt, of body relative to 
   center. 
 
   The ephemeris data supplied to the type 14 SPK writer is packed 
   into an array as a sequence of records, 
 
      ----------------------------------------------------- 
      | Record 1 | Record 2 | ... | Record N-1 | Record N | 
      ----------------------------------------------------- 
 
   with each record has the following format. 
 
         ------------------------------------------------ 
         |  The midpoint of the approximation interval  | 
         ------------------------------------------------ 
         |  The radius of the approximation interval    | 
         ------------------------------------------------ 
         |  chbdeg+1 coefficients for the X coordinate  | 
         ------------------------------------------------ 
         |  chbdeg+1 coefficients for the Y coordinate  | 
         ------------------------------------------------ 
         |  chbdeg+1 coefficients for the Z coordinate  | 
         ------------------------------------------------ 
         |  chbdeg+1 coefficients for the X velocity    | 
         ------------------------------------------------ 
         |  chbdeg+1 coefficients for the Y velocity    | 
         ------------------------------------------------ 
         |  chbdeg+1 coefficients for the Z velocity    | 
         ------------------------------------------------ 
 
-Examples
 
   Assume we have the following for each of the examples that 
   follow. 
 
      handle   is the handle of an SPK file opened with write 
               access. 
 
      segid    is a character string of no more than 40 characters 
               which provides a pedigree for the data in the SPK 
               segment we will create. 
 
      body     is the NAIF ID code for the body whose ephemeris 
               is to be placed into the file. 
 
      center   is the center of motion for the ephemeris of body. 
 
      reffrm   is the name of the SPICE reference frame for the 
               ephemeris. 
 
      first    is the starting epoch, in seconds past J2000, for 
               the ephemeris data to be placed into the segment. 
 
      last     is the ending epoch, in seconds past J2000, for 
               the ephemeris data to be placed into the segment. 
 
   Example 1: 
 
      For this example, we also assume that: 
 
         n        is the number of type 14 records that we want to 
                  put into a segment in an SPK file. 
 
         recrds   contains n type 14 records packaged for the SPK 
                  file. 
 
         etstrt   contains the initial epochs for each of the 
                  records contained in RECRDS, where 
 
                     etstrt[i] < etstrt[i+1], i = 0, n-2 
 
                     etstrt[1] <= first, etstrt[n-1] < last 
 
                     etstrt[i+1], i = 0, n-2, is the ending epoch for 
                     record i as well as the initial epoch for record 
                     i+1. 
 
      Then the following code fragment demonstrates how to create a 
      type 14 SPK segment if all of the data for the segment is 
      available at one time. 
 
         #include "SpiceUsr.h"
            .
            .
            .
         
         #define SPK  "example.bsp"
            
         /.
         If the segment is to be appended to an existing file, open
         that file for "append" access.  Otherwise, create a new file.
         ./
         
         if ( exists_c(SPK) )
         {
            spkopa_c ( SPK, &handle );
         } 
         else
         {
            /.
            New files are supplied with an internal file name.  
            Comment area space may be reserved at this time; the
            units are characters.
            ./
            ifname = "Sample type 14 SPK file.";
            ncomch = 1024;
            
            spkopn_c ( SPK, ifname, ncomch, &handle );
         }
          
          
         /.
         Begin the segment. 
         ./
         spk14b_c ( handle, segid, body, center, reffrm, 
                    first,  last,  chbdeg               );
       
         /.
         Add the data to the segment all at once. 
         ./
         spk14a_c ( handle, n, recrds, etstrt ); 
      
         /.
         End the segment, making the segment a permanent addition 
         to the SPK file. 
         ./
         spk14e_c ( handle ); 
         
             .
             .
             .
         /.
         After all segments have been loaded, close the SPK file.
         ./
         spkcls_c ( handle );
         
 
   Example 2: 
 
      In this example we want to add type 14 SPK records, as described
      above in the Particulars section, to the segments being written
      as they are generated.  The ability to write the records in this
      way is useful if computer memory is limited. It may also be
      convenient from a programming perspective to write the records
      one at a time.
 
      For this example, assume that we want to generate n type 14 SPK 
      records, one for each of n time intervals, writing them all to 
      the same segment in the SPK file. Let 
 
         n        be the number of type 14 records that we want to 
                  generate and put into a segment in an SPK file. 
 
         record   be an array with enough room to hold a single type 
                  14 record, i.e. record should have dimension at 
                  least 6 * (chbdeg + 1 ) + 2. 
 
         start    be an array of n times that are the beginning 
                  epochs for each of the intervals of interest. The 
                  times should be in increasing order and the start 
                  time for the first interval should equal the 
                  starting time for the segment. 
 
                     start[i] < start[i+1], i = 0, n-2 
 
                     start[0] = first 
 
         stop     be an array of n times that are the ending epochs 
                  for each of the intervals of interest. The times 
                  should be in increasing order and the stop time for 
                  interval i should equal the start time for interval 
                  i+1, i.e., we want to have continuous coverage in 
                  time across all of the records. Also, the stop time 
                  for the last interval should equal the ending time 
                  for the segment. 
 
                     stop[i]   < stop [i+1], i = 0, n-2 
 
                     stop[i]   = start[i+1], i = 0, n-2 
 
                     stop[n-1] = last 
 

         genrec( time1, time2, record ) 
 
                  be a subroutine that generates a type 14 SPK record 
                  for a time interval specified by time1 and time2. 
 

      Then the following code fragment demonstrates how to create a 
      type 14 SPK segment if all of the data for the segment is not 
      available at one time. 
 
         #include "SpiceUsr.h"
            .
            .
            .
        
         /.
         Begin the segment. 
         ./
         spk14b_c ( handle, segid, body, center, reffrm, 
                    first,  last,  chbdeg                ); 
 
        
         /.
         Generate the records and write them to the segment in the 
         SPK file one at at time. 
         ./   
         
         for ( i = 0;  i < n;  i++ )
         {
            genrec   ( start[i],    stop[i], record  ); 
            spk14a_c ( handle,   1, record,  start+i );
         }
 
         /.
         End the segment, making the segment a permanent addition 
         to the SPK file. 
         ./   
         spk14e_c ( handle );
         
 
-Restrictions
 
   The SPK file must be open with write access. 
 
   Only one segment may be written to a particular SPK file at a 
   time. All of the data for the segment must be written and the 
   segment must be ended before another segment may be started in 
   the file. 
 
-Exceptions
 
   1) If the degree of the Chebyshev Polynomial to be used for this 
      segment is negative, the error SPICE(INVALIDARGUMENT) will 
      be signaled. 
 
   2) Errors in the structure or content of the inputs other than the 
      degree of the Chebyshev Polynomial are diagnosed by routines 
      called by this one. 
 
   3) File access errors are diagnosed by routines in the call tree 
      of this routine. 
 
   4) If either the input frame or segment ID string pointer is null,
      the error SPICE(NULLPOINTER) is signaled.
   
   5) If either the input frame or segment ID string is empty,
      the error SPICE(EMPTYSTRING) is signaled.
   
-Files
 
   See handle in the Detailed_Input section. 
 
-Author_and_Institution
 
   N.J. Bachman        (JPL)
   K.R. Gehringer      (JPL) 
 
-Literature_References
 
   None. 
 
-Version
 
   -CSPICE Version 1.0.1, 30-OCT-2006 (BVS)

      Deleted "inertial" from the FRAME description in the Brief_I/O
      section of the header.

   -CSPICE Version 1.0.0, 29-JUL-1999 (NJB) (KRG)

-Index_Entries
 
   begin writing a type_14 spk segment 
 
-&
*/

{ /* Begin spk14b_c */


   /*
   Participate in error tracing.
   */
   chkin_c ( "spk14b_c" );


   /*
   Check the input strings to make sure the pointers
   are non-null and the string lengths are non-zero.
   */
   CHKFSTR ( CHK_STANDARD, "spk14b_c", frame );
   CHKFSTR ( CHK_STANDARD, "spk14b_c", segid );


   /*
   Call the f2c'd routine.
   */
   spk14b_ (  ( integer     * ) &handle,
              ( char        * ) segid,
              ( integer     * ) &body, 
              ( integer     * ) &center, 
              ( char        * ) frame, 
              ( doublereal  * ) &first, 
              ( doublereal  * ) &last, 
              ( integer     * ) &chbdeg,
              ( ftnlen        ) strlen(segid),
              ( ftnlen        ) strlen(frame)   );
               

   chkout_c ( "spk14b_c" );

} /* End spk14b_c */
示例#22
0
   void prsdp_c ( ConstSpiceChar     * string,
                  SpiceDouble        * dpval  )

/*

-Brief_I/O

   Variable  I/O  Description
   --------  ---  --------------------------------------------------
   string     I   String representing a d.p. number.
   dpval      O   D.p. value obtained by parsing string.

-Detailed_Input

   string         is a string representing a double precision
                  number.  Any string acceptable to the CSPICE
                  routine nparsd.c is allowed.

-Detailed_Output

   dpval          is the double precision number obtained by parsing
                  string.

-Parameters

   None.

-Exceptions

 
   1) If the input string pointer is null, the error 
      SPICE(NULLPOINTER) will be signaled.
       
   2) If the input string does not contain at least one character, 
      the error SPICE(EMPTYSTRING) will be signaled.

   3) If the input string cannot be parsed, the error
      SPICE(NOTADPNUMBER) is signalled.

-Files

   None.

-Particulars

   The purpose of this routine is to enable safe parsing of double
   precision numbers without the necessity of in-line error checking.
   This routine is based on the CSPICE routine nparsd.c.

-Examples

   See the routine NPARSD for an examples of allowed strings.

-Restrictions

   None.

-Literature_References

   None.

-Author_and_Institution

   N.J. Bachman       (JPL)

-Version

   -CSPICE Version 1.1.2, 26-AUG-1999 (NJB)  
   
      Header was updated to list string exceptions.
   
   -CSPICE Version 1.1.1, 25-MAR-1998 (EDW)
     
      Minor corrections to header.

   -CSPICE Version 1.1.0, 08-FEB-1998 (NJB)

      References to C2F_CreateStr_Sig were removed; code was
      cleaned up accordingly.  String checks are now done using
      the macro CHKFSTR.

   -CSPICE Version 1.0.0, 25-OCT-1997

      Based on SPICELIB Version 1.0.0, 22-JUL-1997 (NJB)

-Index_Entries

   parse d.p. number with encapsulated error handling

-&
*/

{ /* Begin prsdp_c */

   /*
   Participate in error handling.
   */
   chkin_c ( "prsdp_c");


   /*
   Check the input string to make sure the pointer is non-null
   and the string length is non-zero.
   */
   CHKFSTR ( CHK_STANDARD, "prsdp_c", string );


   prsdp_ ( ( char         * ) string,
            ( doublereal   * ) dpval,
            ( ftnlen         ) strlen(string)  );


   chkout_c ( "prsdp_c");

} /* End prsdp_c */
示例#23
0
   void gfsstp_c ( SpiceDouble  step ) 

/*

-Brief_I/O
 
   VARIABLE  I/O  DESCRIPTION 
   --------  ---  -------------------------------------------------- 
   step       I   Time step to take. 
 
-Detailed_Input
 
   step      is the output step size to be returned by the next call 
             to gfstep_c. Units are TDB seconds. 
 
             `step' is used in the GF search root-bracketing process.
             `step' indicates how far to advance the gfstep_c input
             argument `time' so that `time' and time+step may bracket a
             state transition and definitely do not bracket more than
             one state transition.
 
-Detailed_Output
 
   None. 
 
-Parameters
 
   None. 
 
-Exceptions
 
   1) If the input step size is non-positive, the error 
      SPICE(INVALIDSTEP) is signaled. The stored step value  
      is not updated. 
 
-Files
 
   None. 
 
-Particulars
 
   This routine sets the step size to be returned by the
   next call to gfstep_c.
 
-Examples
 

   1) User applications can pass gfstep_c to mid-level GF API routines 
      expecting a step size routine as an input argument. Before such
      a call is made, the value of the step to be returned by gfstep_c
      must be set via a call to this routine.

      For example, the GF API routine gfocce_c can be called as shown 
      in the code fragment below.
      
            /.
            Select a twenty-second step. We'll ignore any occultations
            lasting less than 20 seconds.
            ./
            step = 20.0;
            gfsstp_c ( step );

            /.
            Perform the search.
            ./
            gfocce_c ( "ANY",                            
                       "MOON",     "ellipsoid",  "IAU_MOON", 
                       "SUN",      "ellipsoid",  "IAU_SUN",  
                       "LT",       "EARTH",      CNVTOL,    
                       gfstep_c,   gfrefn_c,     rpt,       
                       gfrepi_c,   gfrepu_c,     gfrepf_c, 
                       bail,       gfbail_c,     cnfine,   
                       &result                              );   
 
-Restrictions
 
   None.
 
-Literature_References
 
   None. 
 
-Author_and_Institution
 
   N.J. Bachman   (JPL)
   W.L. Taber     (JPL) 
   I.M. Underwood (JPL) 
   L.S. Elson     (JPL) 
   E.D. Wright    (JPL)  
 
-Version
 
   -CSPICE Version 2.0.1, 15-APR-2009 (LSE) (NJB)

-Index_Entries
 
   GF set constant step size
-&
*/

{ /* Begin gfsstp_c */

 

   /*
   Participate in error tracing.
   */

   if ( return_c() )
   {
      return;
   }

   chkin_c ( "gfsstp_c" );

   /*
   Let the f2c'd routine do the work.
   */

   gfsstp_ (  (doublereal * ) &step );

   chkout_c ( "gfsstp_c" );

} /* End gfsstp_c */
示例#24
0
   void spk14e_c ( SpiceInt   handle ) 

/*

-Brief_I/O
 
   VARIABLE  I/O  DESCRIPTION 
   --------  ---  -------------------------------------------------- 
   handle     I   The handle of an SPK file open for writing. 
 
-Detailed_Input
 
   handle   is the file handle of an SPK file that has been 
            opened for writing, and to which a type 14 segment is 
            being written. 
 
-Detailed_Output
 
   None.    The type 14 segment in the SPK file associated with 
            handle will be ended, making the addition of the data 
            to the file permanent. 
 
            See the Particulars section for details about the 
            structure of a type 14 SPK segment. 
 
-Parameters
 
   None. 
 
-Particulars
 
   This routine ends a type 14 SPK segment which is being written to 
   the SPK file associated with handle. Ending the SPK segment is a 
   necessary step in the process of making the data a permanent part 
   of the SPK file. 
 
   This routine is one of a set of three routines for creating and 
   adding data to type 14 SPK segments. These routines are: 
 
      spk14b_c: Begin a type 14 SPK segment. This routine must be 
                called before any data may be added to a type 14 
                segment. 
 
      spk14a_c: Add data to a type 14 SPK segment. This routine may be 
                called any number of times after a call to SPK14B to 
                add type 14 records to the SPK segment that was 
                started. 
 
      spk14e_c: End a type 14 SPK segment. This routine is called to 
                make the type 14 segment a permanent addition to the 
                SPK file. Once this routine is called, no further type 
                14 records may be added to the segment. A new segment 
                must be started. 
 
   A type 14 SPK segment consists of coefficient sets for fixed order 
   Chebyshev polynomials over consecutive time intervals, where the 
   time intervals need not all be of the same length. The Chebyshev 
   polynomials represent the position, X, Y, and Z coordinates, and 
   the velocities, dX/dt, dY/dt, and dZ/dt, of a body relative to a
   center of motion. 
 
   The ephemeris data supplied to the type 14 SPK writer routines is 
   packed into an array as a sequence of logical records, 
 
      ----------------------------------------------------- 
      | Record 1 | Record 2 | ... | Record N-1 | Record N | 
      ----------------------------------------------------- 
 
   with each record has the following format. 
 
      ------------------------------------------------ 
      |  the midpoint of the approximation interval  | 
      ------------------------------------------------ 
      |   the radius of the approximation interval   | 
      ------------------------------------------------ 
      |  CHBDEG+1 coefficients for the X coordinate  | 
      ------------------------------------------------ 
      |  CHBDEG+1 coefficients for the Y coordinate  | 
      ------------------------------------------------ 
      |  CHBDEG+1 coefficients for the Z coordinate  | 
      ------------------------------------------------ 
      |   CHBDEG+1 coefficients for the X velocity   | 
      ------------------------------------------------ 
      |   CHBDEG+1 coefficients for the Y velocity   | 
      ------------------------------------------------ 
      |   CHBDEG+1 coefficients for the Z velocity   | 
      ------------------------------------------------ 
 
-Examples
 
   Assume we have the following for each of the examples that 
   follow. 
 
      handle   is the handle of an SPK file opened with write 
               access. 
 
      segid    is a character string of no more than 40 characters 
               which provides a pedigree for the data in the SPK 
               segment we will create. 
 
      body     is the NAIF ID code for the body whose ephemeris 
               is to be placed into the file. 
 
      center   is the center of motion for the ephemeris of body. 
 
      reffrm   is the name of the SPICE reference frame for the 
               ephemeris. 
 
      first    is the starting epoch, in seconds past J2000, for 
               the ephemeris data to be placed into the segment. 
 
      last     is the ending epoch, in seconds past J2000, for 
               the ephemeris data to be placed into the segment. 
 
   Example 1: 
 
      For this example, we also assume that: 
 
         n        is the number of type 14 records that we want to 
                  put into a segment in an SPK file. 
 
         recrds   contains n type 14 records packaged for the SPK 
                  file. 
 
         etstrt   contains the initial epochs for each of the 
                  records contained in RECRDS, where 
 
                     etstrt[i] < etstrt[i+1], i = 0, n-2 
 
                     etstrt[1] <= first, etstrt[n-1] < last 
 
                     etstrt[i+1], i = 0, n-2, is the ending epoch for 
                     record i as well as the initial epoch for record 
                     i+1. 
 
      Then the following code fragment demonstrates how to create a 
      type 14 SPK segment if all of the data for the segment is 
      available at one time. 
 
         #include "SpiceUsr.h"
            .
            .
            .
         
         #define SPK  "example.bsp"
            
         /.
         If the segment is to be appended to an existing file, open
         that file for "append" access.  Otherwise, create a new file.
         ./
         
         if ( exists_c(SPK) )
         {
            spkopa_c ( SPK, &handle );
         } 
         else
         {
            /.
            New files are supplied with an internal file name.  
            Comment area space may be reserved at this time; the
            units are characters.
            ./
            ifname = "Sample type 14 SPK file.";
            ncomch = 1024;
            
            spkopn_c ( SPK, ifname, ncomch, &handle );
         }
          
          
         /.
         Begin the segment. 
         ./
         spk14b_c ( handle, segid, body, center, reffrm, 
                    first,  last,  chbdeg               );
       
         /.
         Add the data to the segment all at once. 
         ./
         spk14a_c ( handle, n, recrds, etstrt ); 
      
         /.
         End the segment, making the segment a permanent addition 
         to the SPK file. 
         ./
         spk14e_c ( handle ); 
         
             .
             .
             .
         /.
         After all segments have been loaded, close the SPK file.
         ./
         spkcls_c ( handle );
         
 
   Example 2: 
 
      In this example we want to add type 14 SPK records, as described
      above in the Particulars section, to the segments being written
      as they are generated.  The ability to write the records in this
      way is useful if computer memory is limited. It may also be
      convenient from a programming perspective to write the records
      one at a time.
 
      For this example, assume that we want to generate n type 14 SPK 
      records, one for each of n time intervals, writing them all to 
      the same segment in the SPK file. Let 
 
         n        be the number of type 14 records that we want to 
                  generate and put into a segment in an SPK file. 
 
         record   be an array with enough room to hold a single type 
                  14 record, i.e. record should have dimension at 
                  least 6 * (chbdeg + 1 ) + 2. 
 
         start    be an array of n times that are the beginning 
                  epochs for each of the intervals of interest. The 
                  times should be in increasing order and the start 
                  time for the first interval should equal the 
                  starting time for the segment. 
 
                     start[i] < start[i+1], i = 0, n-2 
 
                     start[0] = first 
 
         stop     be an array of n times that are the ending epochs 
                  for each of the intervals of interest. The times 
                  should be in increasing order and the stop time for 
                  interval i should equal the start time for interval 
                  i+1, i.e., we want to have continuous coverage in 
                  time across all of the records. Also, the stop time 
                  for the last interval should equal the ending time 
                  for the segment. 
 
                     stop[i]   < stop [i+1], i = 0, n-2 
 
                     stop[i]   = start[i+1], i = 0, n-2 
 
                     stop[n-1] = last 
 

         genrec( time1, time2, record ) 
 
                  be a subroutine that generates a type 14 SPK record 
                  for a time interval specified by time1 and time2. 
 

      Then the following code fragment demonstrates how to create a 
      type 14 SPK segment if all of the data for the segment is not 
      available at one time. 
 
         #include "SpiceUsr.h"
            .
            .
            .
        
         /.
         Begin the segment. 
         ./
         spk14b_c ( handle, segid, body, center, reffrm, 
                    first,  last,  chbdeg                ); 
 
        
         /.
         Generate the records and write them to the segment in the 
         SPK file one at at time. 
         ./   
         
         for ( i = 0;  i < n;  i++ )
         {
            genrec   ( start[i],    stop[i], record  ); 
            spk14a_c ( handle,   1, record,  start+i );
         }
 
         /.
         End the segment, making the segment a permanent addition 
         to the SPK file. 
         ./   
         spk14e_c ( handle );
 
-Restrictions
 
   1) The type 14 SPK segment being closed must have been started by 
      the routine spk14b_c, the routine which begins a type 14 SPK 
      segment. 
 
-Exceptions
 
   None. 
 
-Files
 
   See the argument handle. 
 
-Author_and_Institution
 
   N.J. Bachman        (JPL)
   K.R. Gehringer      (JPL) 
 
-Literature_References
 
   None. 
 
-Version
 
   -CSPICE Version 1.0.1, 16-JAN-2003 (EDW)

       Trivial correction to the header.

   -CSPICE Version 1.0.0, 29-JUL-1999 (NJB) (KRG)

-Index_Entries
 
   end a type_14 spk segment 
 
-&
*/

{ /* Begin spk14e_c */


   /*
   Participate in error tracing.
   */
   chkin_c ( "spk14e_c" );


   spk14e_ ( ( integer * ) &handle );
   

   chkout_c ( "spk14e_c" );

} /* End spk14e_c */
示例#25
0
文件: cklpf_c.c 项目: Dbelsa/coft
   void cklpf_c ( ConstSpiceChar * filename,
                  SpiceInt       * handle    )

/*

-Brief_I/O
 
   Variable  I/O  Description 
   --------  ---  -------------------------------------------------- 
   filename   I   Name of the CK file to be loaded. 
   handle     O   Loaded file's handle. 
 
-Detailed_Input
 
   filename   is the name of a C-kernel file to be loaded. 
 
-Detailed_Output
 
   handle     is an integer handle assigned to the file upon loading. 
              Almost every other CK routine will subsequently use 
              this number to refer to the file. 
 
-Parameters
 
   ftsize     is the maximum number of pointing files that can 
              be loaded by CKLPF at any given time for use by the 
              readers. 
 
-Exceptions
 
   1) If an attempt is made to load more files than is specified 
      by the parameter ftsize, the error "SPICE(CKTOOMANYFILES)" 
      is signalled. 
 
   2) If an attempt is made to open more DAF files than is specified 
      by the parameter ftsize in DAFAH, an error is signalled by a 
      routine that this routine calls. 
 
   3) If the file specified by filename can not be opened, an error 
      is signalled by a routine that this routine calls. 
 
   4) If the file specified by filename has already been loaded, 
      it will become the "last-loaded" file.  (The readers 
      search the last-loaded file first.) 
 
-Files
 
   The C-kernel file specified by filename is loaded.  The file is 
   assigned an integer handle by CKLPF.  Other CK routines will refer 
   to this file by its handle. 
 
-Particulars
 
   See Particulars in ckbsr. 
 
   If there is room for a new file, CKLPF opens the file for 
   reading.  This routine must be called prior to a call to CKGP or 
   CKGPAV. 
 
   CK readers search files loaded with CKLPF in the reverse order 
   in which they were loaded.  That is, last-loaded files are 
   searched first. 
 
-Examples

   ck_kern  = "/kernels/mpf/ck/lander_nominal.bck";
   cklpf_c ( ck_kern, &hand );

   Also see the Example in ckbsr.for. 
 
-Restrictions
 
   None. 
 
-Literature_References
 
   None. 
 
-Author_and_Institution

   J.M. Lynch     (JPL) 
   J.E. McLean    (JPL) 
   M.J. Spencer   (JPL) 
   R.E. Thurman   (JPL) 
   I.M. Underwood (JPL) 
   E.D. Wright    (JPL) 
   B.V. Semenov   (JPL)
   
-Version
 
   -CSPICE Version 2.0.1, 31-JAN-2008 (BVS)

       Removed '-Revisions' from the header.

   -CSPICE Version 2.0.0, 08-FEB-1998 (NJB)  
   
       Input argument filename changed to type ConstSpiceChar *;
       name was changed to "filename" from "fname."
   
       References to C2F_CreateStr_Sig were removed; code was
       cleaned up accordingly.  String checks are now done using
       the macro CHKFSTR.
       
   -CSPICE Version 1.0.0, 25-OCT-1997 (EDW)

-Index_Entries
 
   load ck pointing file 
 
-& 
*/

{ /* Begin spklef_c */


   /*
   Participate in error tracing.
   */
   chkin_c ( "cklpf_c" );


   /*
   Check the input string filename to make sure the pointer is non-null 
   and the string length is non-zero.
   */
   CHKFSTR ( CHK_STANDARD, "cklpf_c", filename );
   

   /*
   Call the f2c'd Fortran routine.
   */
   cklpf_ ( ( char     * )  filename, 
            ( integer  * )  handle, 
            ( ftnlen     )  strlen(filename) );


   chkout_c ( "cklpf_c" );   

} /* end cklpf_c */
示例#26
0
   void spkcls_c ( SpiceInt handle ) 

/*

-Brief_I/O
 
   VARIABLE  I/O  DESCRIPTION 
   --------  ---  -------------------------------------------------- 
   handle     I   Handle of the SPK file to be closed. 
 
-Detailed_Input
 
   handle     The handle of the SPK file that is to be closed. 
 
-Detailed_Output
 
   None. 
 
-Parameters
 
   None. 
 
-Exceptions
 
   1) If there are no segments in the file, the error 
      SPICE(NOSEGMENTSFOUND) will be signaled. 
 
-Files
 
   See argument handle. 
 
-Particulars
 
   Close the SPK file attached to handle. 
 
-Examples
 
   Suppose that you want to create a new SPK file called "new.spk" 
   that contains a single type 5 SPK segment and has room for at 
   least 5000 comment characters. The following code fragment should 
   take care of this for you, assuming that all of the variables 
   passed to the SPK type 5 segment writer have appropriate values 
   and no errors occur. 
 
      #include "SpiceUsr.h"
         .
         .
         . 
      name   = "new.spk";
      ifname = "Test SPK file";
 
      spkopn_c ( name, ifname, 5000,  &handle ); 
      spkw05   ( handle, objid, cntrid, cframe, etbeg, 
                 etend, segmid, cntrgm, nstate, state, 
                 epoch                                 );
      spkcls_c ( handle );
 
-Restrictions
 
   None. 
 
-Author_and_Institution
 
   F.S. Turner        (JPL)
 
-Literature_References
 
   None. 
 
-Version
 
   -CSPICE Version 1.0.0, 16-MAR-1999 (FST)

-Index_Entries
 
   close an spk file 
 
-&
*/

{ /* Begin spkcls_c */

   /*
   Participate in error tracing.
   */

   chkin_c ( "spkcls_c" );

   spkcls_ ( ( integer * ) &handle );

   chkout_c ( "spkcls_c" );

} /* End spkcls_c */
示例#27
0
   SpiceDouble vdotg_c ( ConstSpiceDouble   * v1,
                         ConstSpiceDouble   * v2,
                         SpiceInt             ndim )
/*

-Brief_I/O

   VARIABLE  I/O  DESCRIPTION
   --------  ---  --------------------------------------------------
    v1        I     First vector in the dot product.
    v2        I     Second vector in the dot product.
    ndim      I     Dimension of v1 and v2.

   The function returns the value of the dot product of v1 and v2.

-Detailed_Input

   v1      This may be any double precision vector of arbitrary
           dimension.

   v2      This may be any double precision vector of arbitrary
           dimension.

-Detailed_Output

   The function returns the value of the dot product of v1 and v2.

-Parameters

   None.

-Particulars

   vdotg_c calculates the dot product of v1 and v2 by a simple
   application of the definition.  No error checking is
   performed to prevent or recover from numeric overflow.

-Examples

   Suppose that given two n-dimensional vectors, we want to change
   one of the vectors until the two vectors are perpendicular.
   The following code fragment demonstrates the use of vdot_c to do
   so.

    dot = vdotg_c ( v1, v2, ndim );

    while ( dot != 0. )
       {

         /. change one of the vectors ./
                  ....

        dot = vdotg_c ( v1, v2, ndim );
       }


-Restrictions

   The user is responsible for determining that the vectors v1 and
   v2 are not so large as to cause numeric overflow.  In most cases
   this won't present a problem.

-Exceptions

   1)  If ndim is not physically realistic, greater than zero, a
       BADDIMENSION error is signaled.  The value 0. is returned.

-Files

   None.

-Author_and_Institution

   W.M. Owen       (JPL)
   E.D. Wright     (JPL)

-Literature_References

   None.

-Version

   -CSPICE Version 1.1.0, 22-OCT-1998 (NJB)

      Made input vectors const.  Converted check-in style to discovery.

   -CSPICE Version 1.0.0, 31-MAR-1998   (EDW)

-Index_Entries

   dot product of n-dimensional vectors

-&
*/

{ /* Begin vdotg_c */

   /*
   Local variables
   */

   SpiceInt                i;
   SpiceDouble             dot;


   /*
   Use discovery check-in.
   */


   /* Initialize dot to zero. */
   
   dot  = 0.;


   /* Check ndim is cool.  Dimension is positive definite. */
   
   if ( ndim <= 0 )
      {
      
      chkin_c    ( "vdotg_c"                                      );
      SpiceError ( "Vector dimension less than or equal to zero",
                   "BADDIMENSION"                                 );
      chkout_c   ( "vdotg_c"                                      );
      return     ( 0.                                             );
      
      }


   /* Do the calculation.  Not very involved. */
   
   for ( i = 0; i < ndim; i++ )
      {
      dot += v1[i] * v2[i];
      }


   /* Return the value. */

   return dot;
   

} /* End vdotg_c */
示例#28
0
   void drdpgr_c ( ConstSpiceChar  * body,
                   SpiceDouble       lon,
                   SpiceDouble       lat,
                   SpiceDouble       alt,
                   SpiceDouble       re,
                   SpiceDouble       f,
                   SpiceDouble       jacobi[3][3] ) 

/*

-Brief_I/O
 
   Variable  I/O  Description 
   --------  ---  -------------------------------------------------- 
   body       I   Name of body with which coordinates are associated. 
   lon        I   Planetographic longitude of a point (radians). 
   lat        I   Planetographic latitude of a point (radians). 
   alt        I   Altitude of a point above reference spheroid. 
   re         I   Equatorial radius of the reference spheroid. 
   f          I   Flattening coefficient. 
   jacobi     O   Matrix of partial derivatives. 
 
-Detailed_Input
 
   body       Name of the body with which the planetographic 
              coordinate system is associated. 
 
              `body' is used by this routine to look up from the 
              kernel pool the prime meridian rate coefficient giving 
              the body's spin sense.  See the Files and Particulars 
              header sections below for details. 
 
   lon        Planetographic longitude of the input point.  This is 
              the angle between the prime meridian and the meridian 
              containing the input point.  For bodies having 
              prograde (aka direct) rotation, the direction of 
              increasing longitude is positive west:  from the +X 
              axis of the rectangular coordinate system toward the 
              -Y axis.  For bodies having retrograde rotation, the 
              direction of increasing longitude is positive east: 
              from the +X axis toward the +Y axis. 
 
              The earth, moon, and sun are exceptions: 
              planetographic longitude is measured positive east for 
              these bodies. 
 
              The default interpretation of longitude by this 
              and the other planetographic coordinate conversion 
              routines can be overridden; see the discussion in 
              Particulars below for details. 
 
              Longitude is measured in radians. On input, the range 
              of longitude is unrestricted. 
 
   lat        Planetographic latitude of the input point.  For a 
              point P on the reference spheroid, this is the angle 
              between the XY plane and the outward normal vector at 
              P. For a point P not on the reference spheroid, the 
              planetographic latitude is that of the closest point 
              to P on the spheroid. 
 
              Latitude is measured in radians.  On input, the 
              range of latitude is unrestricted.  
 
   alt        Altitude of point above the reference spheroid. 
              Units of `alt' must match those of `re'. 
 
   re         Equatorial radius of a reference spheroid.  This 
              spheroid is a volume of revolution:  its horizontal 
              cross sections are circular.  The shape of the 
              spheroid is defined by an equatorial radius `re' and 
              a polar radius `rp'.  Units of `re' must match those of  
              `alt'. 
 
   f          Flattening coefficient =  
 
                 (re-rp) / re 
 
              where `rp' is the polar radius of the spheroid, and the 
              units of `rp' match those of `re'. 
 
-Detailed_Output
 
   JACOBI     is the matrix of partial derivatives of the conversion 
              from planetographic to rectangular coordinates.  It 
              has the form 
 
                 .-                              -. 
                 |  DX/DLON   DX/DLAT   DX/DALT   | 
                 |  DY/DLON   DY/DLAT   DY/DALT   | 
                 |  DZ/DLON   DZ/DLAT   DZ/DALT   | 
                 `-                              -' 
 
              evaluated at the input values of `lon', `lat' and `alt'. 
 
-Parameters
 
   None. 
 
-Exceptions
 
   1) If the body name `body' cannot be mapped to a NAIF ID code, 
      and if `body' is not a string representation of an integer, 
      the error SPICE(IDCODENOTFOUND) will be signaled. 
 
   2) If the kernel variable   
 
         BODY<ID code>_PGR_POSITIVE_LON 
 
      is present in the kernel pool but has a value other 
      than one of 
 
          'EAST' 
          'WEST' 
 
      the error SPICE(INVALIDOPTION) will be signaled.  Case 
      and blanks are ignored when these values are interpreted. 
 
   3) If polynomial coefficients for the prime meridian of `body' 
      are not available in the kernel pool, and if the kernel 
      variable BODY<ID code>_PGR_POSITIVE_LON is not present in 
      the kernel pool, the error SPICE(MISSINGDATA) will be signaled. 
       
   4) If the equatorial radius is non-positive, the error 
      SPICE(VALUEOUTOFRANGE) is signaled. 
 
   5) If the flattening coefficient is greater than or equal to one, 
      the error SPICE(VALUEOUTOFRANGE) is signaled. 

   6) The error SPICE(EMPTYSTRING) is signaled if the input
      string `body' does not contain at least one character, since the
      input string cannot be converted to a Fortran-style string in
      this case.
      
   7) The error SPICE(NULLPOINTER) is signaled if the input string
      pointer `body' is null.
 
-Files
 
   This routine expects a kernel variable giving body's prime 
   meridian angle as a function of time to be available in the 
   kernel pool.  Normally this item is provided by loading a PCK 
   file.  The required kernel variable is named  
 
      BODY<body ID>_PM  
 
   where <body ID> represents a string containing the NAIF integer  
   ID code for `body'.  For example, if `body' is "JUPITER", then  
   the name of the kernel variable containing the prime meridian  
   angle coefficients is  
 
      BODY599_PM 
 
   See the PCK Required Reading for details concerning the prime 
   meridian kernel variable. 
 
   The optional kernel variable  
    
      BODY<body ID>_PGR_POSITIVE_LON 
 
   also is normally defined via loading a text kernel. When this 
   variable is present in the kernel pool, the prime meridian 
   coefficients for `body' are not required by this routine. See the 
   Particulars section below for details. 
 
-Particulars
 
   It is often convenient to describe the motion of an object in the 
   planetographic coordinate system.  However, when performing 
   vector computations it's hard to beat rectangular coordinates. 
 
   To transform states given with respect to planetographic 
   coordinates to states with respect to rectangular coordinates, 
   one makes use of the Jacobian of the transformation between the 
   two systems. 
 
   Given a state in planetographic coordinates 
 
      ( lon, lat, alt, dlon, dlat, dalt ) 
 
   the velocity in rectangular coordinates is given by the matrix 
   equation: 
 
                  t          |                                  t 
      (dx, dy, dz)   = jacobi|              * (dlon, dlat, dalt) 
                             |(lon,lat,alt) 
 
 
   This routine computes the matrix  
 
            | 
      jacobi| 
            |(lon,lat,alt) 
 
 
   In the planetographic coordinate system, longitude is defined 
   using the spin sense of the body.  Longitude is positive to the 
   west if the spin is prograde and positive to the east if the spin 
   is retrograde.  The spin sense is given by the sign of the first 
   degree term of the time-dependent polynomial for the body's prime 
   meridian Euler angle "W":  the spin is retrograde if this term is 
   negative and prograde otherwise.  For the sun, planets, most 
   natural satellites, and selected asteroids, the polynomial 
   expression for W may be found in a SPICE PCK kernel. 
 
   The earth, moon, and sun are exceptions: planetographic longitude 
   is measured positive east for these bodies. 
 
   If you wish to override the default sense of positive longitude 
   for a particular body, you can do so by defining the kernel 
   variable 
 
      BODY<body ID>_PGR_POSITIVE_LON 
 
   where <body ID> represents the NAIF ID code of the body. This 
   variable may be assigned either of the values 
 
      'WEST' 
      'EAST' 
 
   For example, you can have this routine treat the longitude 
   of the earth as increasing to the west using the kernel 
   variable assignment 
 
      BODY399_PGR_POSITIVE_LON = 'WEST' 
       
   Normally such assignments are made by placing them in a text 
   kernel and loading that kernel via furnsh_c. 
 
   The definition of this kernel variable controls the behavior of 
   the CSPICE planetographic routines 
 
      pgrrec_c 
      recpgr_c 
      dpgrdr_c 
      drdpgr_c 
 
   It does not affect the other CSPICE coordinate conversion 
   routines. 
 
-Examples
 
   Numerical results shown for this example may differ between 
   platforms as the results depend on the SPICE kernels used as 
   input and the machine specific arithmetic implementation. 
 

     Find the planetographic state of the earth as seen from 
     Mars in the J2000 reference frame at January 1, 2005 TDB. 
     Map this state back to rectangular coordinates as a check. 


           #include <stdio.h>
           #include "SpiceUsr.h"

           int main()
        {
           /.
           Local variables 
           ./
           SpiceDouble             alt;
           SpiceDouble             drectn [3];
           SpiceDouble             et;
           SpiceDouble             f;
           SpiceDouble             jacobi [3][3];
           SpiceDouble             lat;
           SpiceDouble             lon;
           SpiceDouble             lt;
           SpiceDouble             pgrvel [3];
           SpiceDouble             radii  [3];
           SpiceDouble             re;
           SpiceDouble             rectan [3];
           SpiceDouble             rp;
           SpiceDouble             state  [6];

           SpiceInt                n;


           /.
           Load a PCK file containing a triaxial
           ellipsoidal shape model and orientation
           data for Mars.
           ./
           furnsh_c ( "pck00008.tpc" );

           /.
           Load an SPK file giving ephemerides of earth and Mars.
           ./
           furnsh_c ( "de405.bsp" );

           /.
           Load a leapseconds kernel to support time conversion.
           ./
           furnsh_c ( "naif0007.tls" );

           /.
           Look up the radii for Mars.  Although we
           omit it here, we could first call badkpv_c
           to make sure the variable BODY499_RADII
           has three elements and numeric data type.
           If the variable is not present in the kernel
           pool, bodvrd_c will signal an error.
           ./
           bodvrd_c ( "MARS", "RADII", 3, &n, radii );

           /.
           Compute flattening coefficient.
           ./
           re  =  radii[0];
           rp  =  radii[2];
           f   =  ( re - rp ) / re;

           /.
           Look up the geometric state of earth as seen from Mars at
           January 1, 2005 TDB, relative to the J2000 reference
           frame.
           ./
           str2et_c ( "January 1, 2005 TDB", &et);

           spkezr_c ( "Earth", et,    "J2000", "LT+S",    
                      "Mars",  state, &lt              );

           /.
           Convert position to planetographic coordinates.
           ./
           recpgr_c ( "mars", state, re, f, &lon, &lat, &alt );

           /.
           Convert velocity to planetographic coordinates.
           ./

           dpgrdr_c ( "MARS",  state[0],  state[1],  state[2],    
                      re,      f,         jacobi               );

           mxv_c ( jacobi, state+3, pgrvel );


           /.
           As a check, convert the planetographic state back to
           rectangular coordinates.
           ./
           pgrrec_c ( "mars", lon, lat, alt, re, f, rectan );
           drdpgr_c ( "mars", lon, lat, alt, re, f, jacobi );

           mxv_c ( jacobi, pgrvel, drectn );

           printf ( "\n"
                    "Rectangular coordinates:\n"
                    "\n"
                    "  X (km)                 = %18.9e\n"
                    "  Y (km)                 = %18.9e\n"
                    "  Z (km)                 = %18.9e\n"
                    "\n"
                    "Rectangular velocity:\n"
                    "\n"
                    "  dX/dt (km/s)           = %18.9e\n"
                    "  dY/dt (km/s)           = %18.9e\n"
                    "  dZ/dt (km/s)           = %18.9e\n"
                    "\n"
                    "Ellipsoid shape parameters:\n"
                    "\n"
                    "  Equatorial radius (km) = %18.9e\n"
                    "  Polar radius      (km) = %18.9e\n"
                    "  Flattening coefficient = %18.9e\n"
                    "\n"
                    "Planetographic coordinates:\n"
                    "\n"
                    "  Longitude (deg)        = %18.9e\n"
                    "  Latitude  (deg)        = %18.9e\n"
                    "  Altitude  (km)         = %18.9e\n"
                    "\n"
                    "Planetographic velocity:\n"
                    "\n"
                    "  d Longitude/dt (deg/s) = %18.9e\n"
                    "  d Latitude/dt  (deg/s) = %18.9e\n"
                    "  d Altitude/dt  (km/s)  = %18.9e\n"
                    "\n"
                    "Rectangular coordinates from inverse mapping:\n"
                    "\n"
                    "  X (km)                 = %18.9e\n"
                    "  Y (km)                 = %18.9e\n"
                    "  Z (km)                 = %18.9e\n"
                    "\n"
                    "Rectangular velocity from inverse mapping:\n"
                    "\n"
                    "  dX/dt (km/s)           = %18.9e\n"
                    "  dY/dt (km/s)           = %18.9e\n"
                    "  dZ/dt (km/s)           = %18.9e\n"
                    "\n",
                    state [0],
                    state [1],
                    state [2],
                    state [3],
                    state [4],
                    state [5],
                    re,
                    rp,
                    f,
                    lon / rpd_c(),
                    lat / rpd_c(),
                    alt,
                    pgrvel[0]/rpd_c(),
                    pgrvel[1]/rpd_c(),
                    pgrvel[2],
                    rectan [0],
                    rectan [1],
                    rectan [2],
                    drectn [0],
                    drectn [1],
                    drectn [2]                );

           return ( 0 );
        }

     Output from this program should be similar to the following
     (rounding and formatting differ across platforms):


        Rectangular coordinates:

          X (km)                 =    1.460397325e+08
          Y (km)                 =    2.785466068e+08
          Z (km)                 =    1.197503153e+08

        Rectangular velocity:

          dX/dt (km/s)           =   -4.704288238e+01
          dY/dt (km/s)           =    9.070217780e+00
          dZ/dt (km/s)           =    4.756562739e+00

        Ellipsoid shape parameters:

          Equatorial radius (km) =    3.396190000e+03
          Polar radius      (km) =    3.376200000e+03
          Flattening coefficient =    5.886007556e-03

        Planetographic coordinates:

          Longitude (deg)        =    2.976676591e+02
          Latitude  (deg)        =    2.084450403e+01
          Altitude  (km)         =    3.365318254e+08

        Planetographic velocity:

          d Longitude/dt (deg/s) =   -8.357386316e-06
          d Latitude/dt  (deg/s) =    1.593493548e-06
          d Altitude/dt  (km/s)  =   -1.121443268e+01

        Rectangular coordinates from inverse mapping:

          X (km)                 =    1.460397325e+08
          Y (km)                 =    2.785466068e+08
          Z (km)                 =    1.197503153e+08

        Rectangular velocity from inverse mapping:

          dX/dt (km/s)           =   -4.704288238e+01
          dY/dt (km/s)           =    9.070217780e+00
          dZ/dt (km/s)           =    4.756562739e+00

 
-Restrictions
 
   None. 
 
-Literature_References
 
   None. 
 
-Author_and_Institution
 
   N.J. Bachman   (JPL) 
   W.L. Taber     (JPL) 
 
-Version
 
   -CSPICE Version 1.0.0, 26-DEC-2004 (NJB) (WLT)

-Index_Entries
 
   Jacobian of rectangular w.r.t. planetographic coordinates 
 
-&
*/

{ /* Begin drdpgr_c */


   /*
   Participate in error tracing.
   */
   if ( return_c()  )
   {
      return; 
   }
   chkin_c ( "drdpgr_c" );


   /*
   Check the input string body to make sure the pointer is non-null 
   and the string length is non-zero.
   */
   CHKFSTR ( CHK_STANDARD, "drdpgr_c", body );
   

   /*
   Call the f2c'd Fortran routine.
   */
   drdpgr_ ( ( char       * ) body,
             ( doublereal * ) &lon,
             ( doublereal * ) &lat,
             ( doublereal * ) &alt,
             ( doublereal * ) &re,
             ( doublereal * ) &f,
             ( doublereal * ) jacobi,
             ( ftnlen       ) strlen(body)  );

   /*
   Convert Jacobian matrix to row-major order. 
   */
   xpose_c ( jacobi, jacobi );


   chkout_c ( "drdpgr_c" );

} /* End drdpgr_c */
示例#29
0
   void ckw01_c ( SpiceInt            handle, 
                  SpiceDouble         begtim,
                  SpiceDouble         endtim,
                  SpiceInt            inst,
                  ConstSpiceChar    * ref,
                  SpiceBoolean        avflag,
                  ConstSpiceChar    * segid, 
                  SpiceInt            nrec,
                  ConstSpiceDouble    sclkdp [],
                  ConstSpiceDouble    quats  [][4],
                  ConstSpiceDouble    avvs   [][3]  )
/*

-Brief_I/O
 
   Variable  I/O  Description 
   --------  ---  -------------------------------------------------- 
   handle     I   Handle of an open CK file. 
   begtim     I   The beginning encoded SCLK of the segment. 
   endtim     I   The ending encoded SCLK of the segment. 
   inst       I   The NAIF instrument ID code. 
   ref        I   The reference frame of the segment. 
   avflag     I   True if the segment will contain angular velocity. 
   segid      I   Segment identifier. 
   nrec       I   Number of pointing records. 
   sclkdp     I   Encoded SCLK times. 
   quats      I   Quaternions representing instrument pointing. 
   avvs       I   Angular velocity vectors. 
 
-Detailed_Input
 
   handle     is the handle of the CK file to which the segment will 
              be written. The file must have been opened with write 
              access. 
 
   begtim     is the beginning encoded SCLK time of the segment. This 
              value should be less than or equal to the first time in 
              the segment. 
 
   endtim     is the encoded SCLK time at which the segment ends. 
              This value should be greater than or equal to the last 
              time in the segment. 
 
   inst       is the NAIF integer ID code for the instrument. 
 
   ref        is a character string which specifies the  
              reference frame of the segment. This should be one of 
              the frames supported by the SPICELIB routine NAMFRM 
              which is an entry point of FRAMEX. 
 
   avflag     is a logical flag which indicates whether or not the 
              segment will contain angular velocity. 
 
   segid      is the segment identifier.  A CK segment identifier may 
              contain up to 40 characters, excluding the terminating
              null.
 
   nrec       is the number of pointing instances in the segment. 
 
   sclkdp     are the encoded spacecraft clock times associated with 
              each pointing instance. These times must be strictly 
              increasing. 
 
   quats      is an array of SPICE-style quaternions representing a
              sequence of C-matrices. See the discussion of "Quaternion
              Styles" in the Particulars section below.
 
   avvs       are the angular velocity vectors (optional). 
 
              If avflag is FALSE then this array is ignored by the 
              routine, however it still must be supplied as part of 
              the calling sequence. 
 
-Detailed_Output
 
   None.  See Files section. 
 
-Parameters
 
   None. 
 
-Exceptions
 
   1)  If handle is not the handle of a C-kernel opened for writing 
       the error will be diagnosed by routines called by this 
       routine. 
 
   2)  If segid is more than 40 characters long, the error 
       SPICE(SEGIDTOOLONG) is signaled. 
 
   3)  If segid contains any nonprintable characters, the error 
       SPICE(NONPRINTABLECHARS) is signaled. 
 
   4)  If the first encoded SCLK time is negative then the error 
       SPICE(INVALIDSCLKTIME) is signaled. If any subsequent times 
       are negative the error SPICE(TIMESOUTOFORDER) is signaled. 
 
   5)  If the encoded SCLK times are not strictly increasing, 
       the error SPICE(TIMESOUTOFORDER) is signaled. 
 
   6)  If begtim is greater than sclkdp[0] or endtim is less than 
       sclkdp[nrec-1], the error SPICE(INVALIDDESCRTIME) is 
       signaled. 
 
   7)  If the name of the reference frame is not one of those 
       supported by the SPICELIB routine NAMFRM, the error 
       SPICE(INVALIDREFFRAME) is signaled. 
 
   8)  If nrec, the number of pointing records, is less than or 
       equal to 0, the error SPICE(INVALIDNUMRECS) is signaled. 
 
   9)  If any quaternion has magnitude zero, the error
       SPICE(ZEROQUATERNION) is signaled.


-Files
 
   This routine adds a type 1 segment to a C-kernel.  The C-kernel 
   may be either a new one or an existing one opened for writing. 
 
-Particulars
 
   For a detailed description of a type 1 CK segment please see the 
   CK Required Reading. 
 
   This routine relieves the user from performing the repetitive 
   calls to the DAF routines necessary to construct a CK segment. 
 

   Quaternion Styles
   -----------------

   There are different "styles" of quaternions used in
   science and engineering applications. Quaternion styles
   are characterized by

      - The order of quaternion elements

      - The quaternion multiplication formula

      - The convention for associating quaternions
        with rotation matrices

   Two of the commonly used styles are

      - "SPICE"

         > Invented by Sir William Rowan Hamilton
         > Frequently used in mathematics and physics textbooks

      - "Engineering"

         > Widely used in aerospace engineering applications


   CSPICE function interfaces ALWAYS use SPICE quaternions.
   Quaternions of any other style must be converted to SPICE
   quaternions before they are passed to CSPICE functions.


   Relationship between SPICE and Engineering Quaternions
   ------------------------------------------------------

   Let M be a rotation matrix such that for any vector V,

      M*V

   is the result of rotating V by theta radians in the
   counterclockwise direction about unit rotation axis vector A.
   Then the SPICE quaternions representing M are

      (+/-) (  cos(theta/2),
               sin(theta/2) A(1),
               sin(theta/2) A(2),
               sin(theta/2) A(3)  )

   while the engineering quaternions representing M are

      (+/-) ( -sin(theta/2) A(1),
              -sin(theta/2) A(2),
              -sin(theta/2) A(3),
               cos(theta/2)       )

   For both styles of quaternions, if a quaternion q represents
   a rotation matrix M, then -q represents M as well.

   Given an engineering quaternion

      QENG   = ( q0,  q1,  q2,  q3 )

   the equivalent SPICE quaternion is

      QSPICE = ( q3, -q0, -q1, -q2 )


   Associating SPICE Quaternions with Rotation Matrices
   ----------------------------------------------------

   Let FROM and TO be two right-handed reference frames, for
   example, an inertial frame and a spacecraft-fixed frame. Let the
   symbols

      V    ,   V
       FROM     TO

   denote, respectively, an arbitrary vector expressed relative to
   the FROM and TO frames. Let M denote the transformation matrix
   that transforms vectors from frame FROM to frame TO; then

      V   =  M * V
       TO         FROM

   where the expression on the right hand side represents left
   multiplication of the vector by the matrix.

   Then if the unit-length SPICE quaternion q represents M, where

      q = (q0, q1, q2, q3)

   the elements of M are derived from the elements of q as follows:

        +-                                                         -+
        |           2    2                                          |
        | 1 - 2*( q2 + q3 )   2*(q1*q2 - q0*q3)   2*(q1*q3 + q0*q2) |
        |                                                           |
        |                                                           |
        |                               2    2                      |
    M = | 2*(q1*q2 + q0*q3)   1 - 2*( q1 + q3 )   2*(q2*q3 - q0*q1) |
        |                                                           |
        |                                                           |
        |                                                   2    2  |
        | 2*(q1*q3 - q0*q2)   2*(q2*q3 + q0*q1)   1 - 2*( q1 + q2 ) |
        |                                                           |
        +-                                                         -+

   Note that substituting the elements of -q for those of q in the
   right hand side leaves each element of M unchanged; this shows
   that if a quaternion q represents a matrix M, then so does the
   quaternion -q.

   To map the rotation matrix M to a unit quaternion, we start by
   decomposing the rotation matrix as a sum of symmetric
   and skew-symmetric parts:

                                      2
      M = [ I  +  (1-cos(theta)) OMEGA  ] + [ sin(theta) OMEGA ]

                   symmetric                   skew-symmetric


   OMEGA is a skew-symmetric matrix of the form

                 +-             -+
                 |  0   -n3   n2 |
                 |               |
       OMEGA  =  |  n3   0   -n1 |
                 |               |
                 | -n2   n1   0  |
                 +-             -+

   The vector N of matrix entries (n1, n2, n3) is the rotation axis
   of M and theta is M's rotation angle.  Note that N and theta
   are not unique.

   Let

      C = cos(theta/2)
      S = sin(theta/2)

   Then the unit quaternions Q corresponding to M are

      Q = +/- ( C, S*n1, S*n2, S*n3 )

   The mappings between quaternions and the corresponding rotations
   are carried out by the CSPICE routines

      q2m_c {quaternion to matrix}
      m2q_c {matrix to quaternion}

   m2q_c always returns a quaternion with scalar part greater than
   or equal to zero.


   SPICE Quaternion Multiplication Formula
   ---------------------------------------

   Given a SPICE quaternion

      Q = ( q0, q1, q2, q3 )

   corresponding to rotation axis A and angle theta as above, we can
   represent Q using "scalar + vector" notation as follows:

      s =   q0           = cos(theta/2)

      v = ( q1, q2, q3 ) = sin(theta/2) * A

      Q = s + v

   Let Q1 and Q2 be SPICE quaternions with respective scalar
   and vector parts s1, s2 and v1, v2:

      Q1 = s1 + v1
      Q2 = s2 + v2

   We represent the dot product of v1 and v2 by

      <v1, v2>

   and the cross product of v1 and v2 by

      v1 x v2

   Then the SPICE quaternion product is

      Q1*Q2 = s1*s2 - <v1,v2>  + s1*v2 + s2*v1 + (v1 x v2)

   If Q1 and Q2 represent the rotation matrices M1 and M2
   respectively, then the quaternion product

      Q1*Q2

   represents the matrix product

      M1*M2


-Examples
 
  
   This example writes a type 1 C-kernel segment for the 
   Galileo scan platform to a previously opened file attached to 
   handle. 
 
      /.
      Include CSPICE interface definitions.
      ./
      #include "SpiceUsr.h"
                .
                .
                .
      /.
      Assume arrays of quaternions, angular velocities, and the 
      associated SCLK times are produced elsewhere. 
      ./
                . 
                . 
                . 
      /.
      The subroutine ckw01_c needs the following items for the 
      segment descriptor: 
      
         1) SCLK limits of the segment. 
         2) Instrument code. 
         3) Reference frame. 
         4) The angular velocity flag. 
      ./
      
      begtim  = (SpiceChar *) sclk[0]; 
      endtim  = (SpiceChar *) sclk[nrec-1];
 
      inst    = -77001;
      ref     = "J2000";
      avflag  = SPICETRUE;
      segid   = "GLL SCAN PLT - DATA TYPE 1"; 
 
      /.
      Write the segment. 
      ./
      ckw01_c ( handle,  begtim,  endtim,  inst,  ref,  avflag, 
                segid,   nrec,    sclkdp,  quats, avvs         );
                
                . 
                . 
                . 
             
      /.
      After all segments are written, close the C-kernel.
      ./
      ckcls_c ( handle );
      
 
-Restrictions
 
   None. 
 
-Literature_References
 
   None. 
 
-Author_and_Institution
 
   K.R. Gehringer  (JPL) 
   N.J. Bachman    (JPL) 
   J.M. Lynch      (JPL) 
 
-Version

   -CSPICE Version 2.0.0, 01-JUN-2010 (NJB)

      The check for non-unit quaternions has been replaced
      with a check for zero-length quaternions. (The
      implementation of the check is located in ckw01_.)

   -CSPICE Version 1.3.2, 27-FEB-2008 (NJB)

      Updated header; added information about SPICE 
      quaternion conventions.

   -CSPICE Version 1.3.1, 12-JUN-2006 (NJB)

      Corrected typo in example, the sclk indexes for the begtim
      and endtim assignments used FORTRAN convention.
 
   -CSPICE Version 1.3.0, 28-AUG-2001 (NJB)

      Changed prototype:  inputs sclkdp, quats, and avvs are now
      const-qualified.  Implemented interface macros for casting 
      these inputs to const.
            
   -CSPICE Version 1.2.0, 02-SEP-1999 (NJB)  
   
      Local type logical variable now used for angular velocity
      flag used in interface of ckw01_.
            
   -CSPICE Version 1.1.0, 08-FEB-1998 (NJB)  
   
      References to C2F_CreateStr_Sig were removed; code was
      cleaned up accordingly.  String checks are now done using
      the macro CHKFSTR.
       
   -CSPICE Version 1.0.0, 25-OCT-1997 (NJB)
   
      Based on SPICELIB Version 2.0.0, 28-DEC-1993 (WLT)

-Index_Entries
 
   write ck type_1 pointing data segment 
 
-&
*/

{ /* Begin ckw01_c */


   /*
   Local variables
   */
   logical                 avf;
   
   
   /*
   Participate in error handling.
   */
   chkin_c ( "ckw01_c" );

 
   /*
   Check the input strings to make sure the pointers
   are non-null and the string lengths are non-zero.
   */
   CHKFSTR ( CHK_STANDARD, "ckw01_c", ref   );
   CHKFSTR ( CHK_STANDARD, "ckw01_c", segid );
 
   /*
   Get a type logical copy of the a.v. flag.
   */
   avf = avflag;
   
 
   /*
   Write the segment.  Note that the quaternion and angular velocity
   arrays DO NOT require transposition!
   */

   ckw01_( ( integer    * ) &handle, 
           ( doublereal * ) &begtim, 
           ( doublereal * ) &endtim, 
           ( integer    * ) &inst, 
           ( char       * ) ref, 
           ( logical    * ) &avf, 
           ( char       * ) segid, 
           ( integer    * ) &nrec, 
           ( doublereal * ) sclkdp,
           ( doublereal * ) quats, 
           ( doublereal * ) avvs, 
           ( ftnlen       ) strlen(ref), 
           ( ftnlen       ) strlen(segid)  );


   chkout_c ( "ckw01_c" );

} /* End ckw01_c */
示例#30
0
void pcpool_c ( ConstSpiceChar  * name,
                SpiceInt          n,
                SpiceInt          lenvals,
                const void      * cvals    )
/*

-Brief_I/O

   VARIABLE  I/O  DESCRIPTION
   --------  ---  --------------------------------------------------
   name       I   The kernel pool name to associate with cvals.
   n          I   The number of values to insert.
   lenvals    I   The lengths of the strings in the array cvals.
   cvals      I   An array of strings to insert into the kernel pool.

-Detailed_Input

   name       is the name of the kernel pool variable to associate
              with the values supplied in the array cvals. 'name' is
              restricted to a length of 32 characters or less.

   n          is the number of values to insert into the kernel pool.

   lenvals    is the length of the strings in the array cvals,
              including the null terminators.

   cvals      is an array of strings to insert into the kernel
              pool.  cvals should be declared as follows:

                 char  cvals[n][lenvals];

-Detailed_Output

   None.

-Parameters

   None.

-Exceptions

   1) If name is already present in the kernel pool and there
      is sufficient room to hold all values supplied in values,
      the old values associated with name will be overwritten.

   2) If there is not sufficient room to insert a new variable
      into the kernel pool and name is not already present in
      the kernel pool, the error SPICE(KERNELPOOLFULL) is
      signaled by a routine in the call tree to this routine.

   3) If there is not sufficient room to insert the values associated
      with name, the error SPICE(NOMOREROOM) will be signaled.

   4) If either input string pointer is null, the error
      SPICE(NULLPOINTER) will be signaled.

   5) If the input string name has length zero, the error
      SPICE(EMPTYSTRING) will be signaled.

   6) If the input cvals string length is less than 2, the error
      SPICE(STRINGTOOSHORT) will be signaled.

   7) The error 'SPICE(BADVARNAME)' signals if the kernel pool
      variable name length exceeds 32.

-Files

   None.

-Particulars

   This entry point provides a programmatic interface for inserting
   character data into the SPICE kernel pool without reading an
   external file.

-Examples

   The following example program shows how a topocentric frame for a
   point on the surface of the earth may be defined at run time using
   pcpool_c, pdpool_c, and pipool_c.  In this example, the surface
   point is associated with the body code 300000.  To facilitate
   testing, the location of the surface point coincides with that of
   the DSN station DSS-12; the reference frame MYTOPO defined here
   coincides with the reference frame DSS-12_TOPO.

      #include <stdio.h>
      #include "SpiceUsr.h"

      int main()
      {
         /.
         The first angle is the negative of the longitude of the
         surface point; the second angle is the negative of the
         point's colatitude.
         ./
         SpiceDouble             angles [3]      =  { -243.1945102442646,
                                                       -54.7000629043147,
                                                       180.0              };

         SpiceDouble             et              =    0.0;
         SpiceDouble             rmat   [3][3];

         SpiceInt                axes   [3]      =  { 3, 2, 3 };
         SpiceInt                center          =    300000;
         SpiceInt                frclass         =    4;
         SpiceInt                frclsid         =    1500000;
         SpiceInt                frcode          =    1500000;

         /.
         Define the MYTOPO reference frame.

         Note that the third argument in the pcpool_c calls is
         the length of the final string argument, including the
         terminating null character.
         ./
         pipool_c ( "FRAME_MYTOPO",            1,     &frcode   );
         pcpool_c ( "FRAME_1500000_NAME",      1, 7,  "MYTOPO"  );
         pipool_c ( "FRAME_1500000_CLASS",     1,     &frclass  );
         pipool_c ( "FRAME_1500000_CLASS_ID",  1,     &frclsid  );
         pipool_c ( "FRAME_1500000_CENTER",    1,     &center   );

         pcpool_c ( "OBJECT_300000_FRAME",     1, 7,  "MYTOPO"  );

         pcpool_c ( "TKFRAME_MYTOPO_RELATIVE", 1, 7,  "ITRF93"  );
         pcpool_c ( "TKFRAME_MYTOPO_SPEC",     1, 7,  "ANGLES"  );
         pcpool_c ( "TKFRAME_MYTOPO_UNITS",    1, 8,  "DEGREES" );
         pipool_c ( "TKFRAME_MYTOPO_AXES",     3,     axes      );
         pdpool_c ( "TKFRAME_MYTOPO_ANGLES",   3,     angles    );

         /.
         Load a high precision binary earth PCK. Also load a
         topocentric frame kernel for DSN stations. The file names
         shown here are simply examples; users should replace these
         with the names of appropriate kernels.
         ./
         furnsh_c ( "earth_000101_060207_051116.bpc" );
         furnsh_c ( "earth_topo_050714.tf"           );

         /.
         Look up transformation from DSS-12_TOPO frame to MYTOPO frame.
         This transformation should differ by round-off error from
         the identity matrix.
         ./
         pxform_c ( "DSS-12_TOPO", "MYTOPO", et, rmat );

         printf   ( "\n"
                    "DSS-12_TOPO to MYTOPO transformation at "
                    "et %23.16e = \n"
                    "\n"
                    "    %25.16f  %25.16f  %25.16f\n"
                    "    %25.16f  %25.16f  %25.16f\n"
                    "    %25.16f  %25.16f  %25.16f\n",
                    et,
                    rmat[0][0],  rmat[0][1],  rmat[0][2],
                    rmat[1][0],  rmat[1][1],  rmat[1][2],
                    rmat[2][0],  rmat[2][1],  rmat[2][2]       );

         return ( 0 );
      }


-Restrictions

   None.

-Literature_References

   None.

-Author_and_Institution

   N.J. Bachman    (JPL)
   W.L. Taber      (JPL)

-Version

   -CSPICE Version 1.3.3,  17-JAN-2014 (NJB)

      Updated Index_Entries section.

   -CSPICE Version 1.3.2,  10-FEB-2010 (EDW)

      Added mention of the restriction on kernel pool variable
      names to 32 characters or less.

      Reordered header sections to conform to SPICE convention.

   -CSPICE Version 1.3.1, 17-NOV-2005 (NJB)

      Replaced code fragment in Examples section of header with
      smaller, complete program.

   -CSPICE Version 1.3.0, 12-JUL-2002 (NJB)

      Call to C2F_CreateStrArr_Sig replaced with call to C2F_MapStrArr.

   -CSPICE Version 1.2.0, 28-AUG-2001 (NJB)

      Const-qualified input array cvals.

   -CSPICE Version 1.1.0, 14-FEB-2000 (NJB)

       Calls to C2F_CreateStrArr replaced with calls to error-signaling
       version of this routine:  C2F_CreateStrArr_Sig.

   -CSPICE Version 1.0.0, 18-JUN-1999 (NJB) (WLT)

-Index_Entries

   Set the value of a character_variable in the kernel_pool

-&
*/

{   /* Begin pcpool_c */


    /*
    Local variables
    */
    SpiceChar             * fCvalsArr;

    SpiceInt                fCvalsLen;


    /*
    Participate in error tracing.
    */
    chkin_c ( "pcpool_c" );

    /*
    Check the input kernel variable name to make sure the pointer is
    non-null and the string length is non-zero.
    */
    CHKFSTR ( CHK_STANDARD, "pcpool_c", name );


    /*
    Make sure the input string pointer for the cvals array is non-null
    and that the length lenvals is sufficient.
    */
    CHKOSTR ( CHK_STANDARD, "pcpool_c", cvals, lenvals );


    /*
    Create a Fortran-style string array.
    */
    C2F_MapStrArr ( "pcpool_c",
                    n, lenvals, cvals, &fCvalsLen, &fCvalsArr );

    if ( failed_c() )
    {
        chkout_c ( "pcpool_c" );
        return;
    }


    /*
    Call the f2c'd routine.
    */
    pcpool_ (  ( char       * ) name,
               ( integer    * ) &n,
               ( char       * ) fCvalsArr,
               ( ftnlen       ) strlen(name),
               ( ftnlen       ) fCvalsLen     );


    /*
    Free the dynamically allocated array.
    */
    free ( fCvalsArr );


    chkout_c ( "pcpool_c" );

} /* End pcpool_c */