Index Page kplfrm_c

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

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

#### Procedure

       void kplfrm_c ( SpiceInt      frmcls,
                       SpiceCell   * idset   )

#### Abstract

       Return a SPICE set containing the frame IDs of all reference
       frames of a given class having specifications in the kernel pool.

#### Required_Reading

       CELLS
       FRAMES
       KERNEL
       NAIF_IDS
       SETS

#### Keywords

       FRAME
       SET
       UTILITY

#### Brief_I/O

       VARIABLE  I/O  DESCRIPTION
       --------  ---  --------------------------------------------------
       frmcls     I   Frame class.
       idset      O   Set of ID codes of frames of the specified class.

#### Detailed_Input

       frmcls         is an integer code specifying the frame class or
                      classes for which frame ID codes are requested. The
                      applicable reference frames are those having
                      specifications present in the kernel pool.

                      `frmcls' may designate a single class or "all
                      classes."

                      The headerfile SpiceFrm.h declares parameters
                      identifying frame classes. The supported values
                      and corresponding meanings of `frmcls' are

                         Parameter          Value    Meaning
                         ================   =====    =================
                         SPICE_FRMTYP_ALL     -1     All frame classes
                                                     specified in the
                                                     kernel pool. Class 1
                                                     is not included.

                         SPICE_FRMTYP_INERTL   1     Built-in inertial.
                                                     No frames will be
                                                     returned in the
                                                     output set.

                         SPICE_FRMTYP_PCK      2     PCK-based frame.

                         SPICE_FRMTYP_CK       3     CK-based frame.

                         SPICE_FRMTYP_TK       4     Fixed rotational
                                                     offset ("text
                                                     kernel") frame.

                         SPICE_FRMTYP_DYN      5     Dynamic frame.

#### Detailed_Output

       idset          is a SPICE set containing the ID codes of all
                      reference frames having specifications present in
                      the kernel pool and belonging to the specified
                      class or classes.

#### Parameters

       See the header file SpiceFrm.h.

#### Exceptions

       1)  If the input frame class argument is not defined in SpiceFrm.h,
           the error is diagnosed by a routine in the call tree of this
           routine.

       2)  If the size of `idset' is too small to hold the requested frame
           ID set, the error is diagnosed by a routine in the call tree of
           this routine.

       3)  Frames of class 1 may not be specified in the kernel pool.
           However, for the convenience of users, this routine does not
           signal an error if the input class is set to
           SPICE_FRMTYP_INERTL. In this case the output set will be empty.

       4)  This routine relies on the presence of just three kernel
           variable assignments for a reference frame in order to
           determine that that reference frame has been specified:

             FRAME_<frame name>       = <ID code>
             FRAME_<ID code>_NAME     = <frame name>

          and either

             FRAME_<ID code>_CLASS    = <class>

          or

             FRAME_<frame name>_CLASS = <class>

          It is possible for the presence of an incomplete frame
          specification to trick this routine into incorrectly
          deciding that a frame has been specified. This routine
          does not attempt to diagnose this problem.

#### Files

       1) Reference frame specifications for frames that are not
          built in are typically established by loading frame kernels.

#### Particulars

       This routine enables SPICE-based applications to conveniently
       find the frame ID codes of reference frames having specifications
       present in the kernel pool. Such frame specifications are
       introduced into the kernel pool either by loading frame kernels
       or by means of calls to the kernel pool "put" API routines

          pcpool_c
          pdpool_c
          pipool_c

       Given a reference frame's ID code, other attributes of the
       frame can be obtained via calls to the CSPICE APIs

          frmnam_c {Return a frame's name}
          frinfo_c {Return a frame's center, class, and class ID}

       This routine has a counterpart

          bltfrm_c

       which fetches the frame IDs of all built-in reference frames.

#### Examples

       1)  Display the IDs and names of all reference frames having
           specifications present in the kernel pool. Group the outputs
           by frame class. Also fetch and display the entire set of IDs
           and names using the parameter SPICE_FRMTYP_ALL.

           The meta-kernel used for this example is shown below. The
           Rosetta kernels referenced by the meta-kernel are available
           in the path

              pub/naif/ROSETTA/kernels/fk

           on the NAIF server. Older, but officially archived versions
           of these kernels are available in the path

              pub/naif/pds/data/ros-e_m_a_c-spice-6-v1.0/
              rossp_1000/DATA/FK

           The referenced PCK is available from the pck path under the
           generic_kernels path on the same server.

              KPL/MK

              \begindata

                 KERNELS_TO_LOAD = ( 'pck00010.tpc'
                                     'EARTHFIXEDITRF93.TF'
                                     'ROS_LUTETIA_RSOC_V03.TF'
                                     'ROS_V18.TF'
                                     'RSSD0002.TF'            )
              \begintext

           Program source code:

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

              int main()
              {
                 /.
                 Local parameters
                 ./
                 #define META            "kplfrm.tm"
                 #define FRNMLN          33
                 #define NFRAME          1000
                 #define LNSIZE          81

                 /.
                 Local variables
                 ./
                 SPICEINT_CELL           ( idset, NFRAME );

                 SpiceChar               frname  [ FRNMLN ];
                 SpiceChar               outlin  [ LNSIZE ];

                 SpiceInt                i;
                 SpiceInt                j;

                 /.
                 Load kernels that contain frame specifications.
                 ./
                 furnsh_c ( META );

                 /.
                 Fetch and display the frames of each class.
                 ./
                 for ( i = 1;  i <= 6;  i++ )
                 {
                    if ( i < 6 )
                    {
                       /.
                       Fetch the frames of class i.
                       ./
                       kplfrm_c ( i, &idset );

                       sprintf ( outlin,
                                 "Number of frames of class %d: %d",
                                 (int) i,
                                 (int) card_c(&idset)                );
                    }
                    else
                    {
                       /.
                       Fetch IDs of all frames specified in the kernel pool.
                       ./
                       kplfrm_c ( SPICE_FRMTYP_ALL, &idset );

                       sprintf ( outlin,
                                 "Number of frames in the kernel pool: %d",
                                 (int) card_c(&idset)                     );
                    }

                    /.
                    Display the fetched frame IDs and corresponding names.
                    ./
                    printf ( "\n"
                             "%s\n"
                             "   Frame IDs and names\n",
                             outlin                     );

                    for ( j = 0;  j < card_c(&idset);  j++ )
                    {
                       frmnam_c ( ((SpiceInt *)idset.data)[j], FRNMLN, frname );

                       printf ( "%12.0ld   %s\n",
                                ( (long) ((SpiceInt *)idset.data)[j] ),  frname );
                    }
                 }

                 return ( 0 );
              }

           The output from the program, when the program was linked
           against the N0064 CSPICE Toolkit, is shown below. The output
           shown here has been abbreviated.

              Number of frames of class 1: 0
                 Frame IDs and names

              Number of frames of class 2: 3
                 Frame IDs and names
                   1000012   67P/C-G_FIXED
                   2000021   LUTETIA_FIXED
                   2002867   STEINS_FIXED

              Number of frames of class 3: 7
                 Frame IDs and names
                   -226570   ROS_RPC_BOOM2
                   -226215   ROS_VIRTIS-M_SCAN
                   -226072   ROS_HGA_AZ
                   -226071   ROS_HGA_EL
                   -226025   ROS_SA-Y
                   -226015   ROS_SA+Y
                   -226000   ROS_SPACECRAFT

              Number of frames of class 4: 64
                 Frame IDs and names
                  -2260021   ROS_LUTETIA
                   -226999   ROSLND_LOCAL_LEVEL
                   -226900   ROSLND_LANDER
                   -226560   ROS_RPC_BOOM1

                      ...

                   -226030   ROS_MGA-S
                   -226020   ROS_SA-Y_ZERO
                   -226010   ROS_SA+Y_ZERO
                   1502010   HCI
                   1502301   LME2000
                   1503299   VME2000
                   1503499   MME2000

              Number of frames of class 5: 19
                 Frame IDs and names
                   -226967   2867/STEINS_CSO
                   -226945   45P/H-M-P_CSO
                   -226921   21/LUTETIA_CSO
                   -226920   21/LUTETIA_CSEQ
                   -226912   67P/C-G_CSO
                   -226910   67P/C-G_CSEQ
                   1500010   HEE
                   1500299   VSO
                   1500301   LSE
                   1500399   GSE
                   1500499   MME
                   1501010   HEEQ
                   1501299   VME
                   1501301   LME
                   1501399   EME
                   1501499   MME_IAU2000
                   1502399   GSEQ
                   1502499   MSO
                   1503399   ECLIPDATE

              Number of frames in the kernel pool: 93
                 Frame IDs and names
                  -2260021   ROS_LUTETIA
                   -226999   ROSLND_LOCAL_LEVEL
                   -226967   2867/STEINS_CSO
                   -226945   45P/H-M-P_CSO
                   -226921   21/LUTETIA_CSO

                      ...

                   1503299   VME2000
                   1503399   ECLIPDATE
                   1503499   MME2000
                   2000021   LUTETIA_FIXED
                   2002867   STEINS_FIXED

#### Restrictions

       1) This routine will work correctly if the kernel pool
          contains no invalid frame specifications. See the
          description of exception 4 above. Users must ensure
          that no invalid frame specifications are introduced
          into the kernel pool, either by loaded kernels or
          by means of the kernel pool "put" APIs.

#### Literature_References

       None.

#### Author_and_Institution

       N.J. Bachman    (JPL)

#### Version

       -CSPICE Version 1.0.1, 12-JUL-2016 (EDW)

          Edit to example program to use "%d" with explicit casts
          to int for printing SpiceInts with printf.

       -CSPICE Version 1.0.0, 22-MAY-2012 (NJB)

#### Index_Entries

       fetch names of reference_frames from the kernel_pool

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

    Wed Apr  5 17:54:37 2017