[Spice_discussion] Creating frames in programs

[Nat Bachman]

Hi Darren,

There are two different basic approaches (which of course have many
possible variations) I know of to use SPICE to create two-vector
frames in your application code:

  1) Define a rotation matrix that maps vectors from a specified
     base frame to a specified two-vector frame.  For this,
     all you need is one call to the SPICE routine TWOVEC.

     The disadvantage of this approach is that SPICE doesn't
     "know about" this frame, so you can't refer to it in
     calls to SPICE routines such as SPKEZR or PXFORM.

  2) Create a two-vector frame definition and insert it into
     the kernel pool via the SPICE subroutine API.  To see how do this,
     see the headers of LMPOOL or PCPOOL.  In SPICELIB, these are entry
     points of POOL.

     The advantage of this approach is that you can create
     frames on the fly that SPICE will recognize.

     The disadvantages of this approach are:

        - It's somewhat awkward to implement.  (However, I used this
          technique (using LMPOOL) to create literally hundreds of
          thousands of frame definitions while testing the dynamic frame
          capability, so I can vouch for its utility.)

        - It's somewhat dangerous:  any kernel unload operation
          that affects the kernel pool will wipe out your
          definitions.  It's best not to mix kernel load/unload
          operations with insertions into the kernel pool; if you
          can get all of your kernels loaded first, it simplifies
          matters.

          If necessary, see the headers with the SPICELIB routine KEEPER
          (of which FURNSH and UNLOAD are entry points) for a detailed
          discussion of kernel loading and unloading.  However, it's
          wise IMO to avoid complications in this area.

        - You can run out of space in the kernel pool if you use
          too many frames without deleting any of the definitions
          you've created.

          When you delete a frame definition, you must do so
          completely:  leaving some of the frame definition's kernel
          variables in the pool can affect future frame definitions
          if you re-use frame names or ID codes.  For example, if
          you fail to delete the "rotation state" assignment for
          frame 'F' having ID code n, and then re-use that name/ID
          combination, and if the new definition doesn't include a
          rotation state specification (which is optional for two-vector
          frames), the old rotation state specification is inherited by
          the new frame.

        - It can make debugging more difficult:  if something is
          wrong with your frame definition, you have no visible
          record of it unless you write code to create such a
          record (or use a debugger).

          BTW, one common but difficult-to-find problem that occurs with
          two-vector frames is loss of precision in the frame definition
          due to the unexpectedly nearly parallel defining vectors.  It's
          important to make sure the defining vectors are never close
          to parallel (or anti-parallel) over the whole time range for which
          the frame is used.

          Another problem to look for is frame definition syntax errors
          which would have been caught by the text kernel parsing code 
that you've
          bypassed.  It's important to carefully test any new code that 
creates
          the frame definitions.


Please let me know if this answer missed the mark, or if you have further
questions about SPICE.

  -Nat Bachman (JPL/NAIF)

  Nathaniel.Bachman at jpl.nasa.gov


Wade, Darren W wrote:

>I've read through the frames documentation and while it extensively
>covers creating a frame text kernel, I see no discussion on how one
>would go about creating a frame (specifically two vector) in code.  Is
>there documentation somewhere that describes this process?
>
>Darren Wade
>_______________________________________________
>Spice_discussion mailing list
>Spice_discussion at naif.jpl.nasa.gov
>http://naif.jpl.nasa.gov/mailman/listinfo/spice_discussion
>  
>