Index Page
Windows Required Reading

Table of Contents 


   Windows Required Reading
      Abstract
      Introduction
         Basic Concepts
      The window data type
      References

   Window Functions
      Initialization Functions
      Unary Functions
      Binary Functions
      Complement Functions
      Comparison Functions

   Summary

   Appendix: Document Revision History
         Febuary 6, 2009 (EDW)


Top

Windows Required Reading




Last revised on 2010 MAY 18 by B. V. Semenov.



Top

Abstract



SPICE Toolkits define the SPICE data type "window" for use in the manipulation of continuous intervals on the real line. Corresponding window functions in Mice are designed to simplify the use of this data type.



Top

Introduction



An interval is an ordered pair of numbers, 

   [ a(i), b(i) ]
such that 

   a(i)  <  b(i)
         -
The intervals within a window are both ordered and disjoint. That is, the beginning of each interval is greater than the end of the previous interval: 

   b(i)  <  a(i+1)
This restriction is enforced primarily because it allows efficient window operations.

The intervals stored in windows typically represent intervals of time (seconds, days, or centuries past a reference epoch). However, windows can represent any kinds of intervals.



Top

Basic Concepts



``size'' - The number of elements stored in a SPICE window

``cardinality'' - A synonym for ``size.''

``measure'' - the measure of an interval is the length of the interval, that is the difference of its endpoints: 

   m(i) = b(i) - a(i)
Note that the singleton interval 

   [ a(i), a(i) ]
has measure zero. The window 

   [1,2], [4,9], [16,16]
contains intervals of measure 1, 5, and 0 respectively.

The concept of measure extends readily to the gaps between adjacent intervals. In the example above, the window contains gaps of measure 2 and 7. Intervals separated by gaps of measure zero or less are said to overlap. Overlapping intervals created by the window functions are merged as soon as they are created.

Finally, the measure of a window is the sum of the measures of its intervals. In the example above, the measure of the window is 6. Note that a floating point window containing only singletons has measure zero.



Top

The window data type



The Mice implementation of SPICE windows consists of double precision Nx1 arrays with N an even or zero value. Mice windows lack a constant size as the windows interfaces dynamically adjust window size before return. Therefore the SPICE concept of window cardinality degenerates to size.

Recall,the intervals in a SPICE window are sorted in ascending order, without duplicates.

Direct assignment of windows data, i.e. assigning data to a window without use of a window interface, is trivial in MATLAB, but NAIF recommends the user call the Mice interfaces to affect window data as the interfaces include data error checks and ensure proper form of the window.

In some cases use of windows requires a direct assignment, e.g. define an empty Mice window 

   >> window = zeros(0,1)
 
   window =
 
      Empty matrix: 0-by-1
If you decide to create a window by direct assignment rather than using the cspice_wninsd call, NAIF suggests a particular style when assigning window data for ease of readability.

Create a window composed of the intervals: 

      [ 1, 3 ] [ 7, 11 ] [ 23, 27 ]

   >> window = [ [ 1; 3 ];  [ 7; 11 ];  [ 23; 27 ] ]
 
   window =
 
        1
        3
        7
       11
       23
       27


Top

References



[1]

Mice Required Reading (mice.req).


Top

Window Functions




The window functions in Mice fall into the following categories.

    -- Initialization

    -- Unary

    -- Binary

    -- Complement

    -- Comparison



Top

Initialization Functions



cspice_wnvald takes as input a double precision SPICE cell containing pairs of endpoints and validates it to form a window. The calling sequence is shown below. 

   window_f = cspice_wnvald(window)
On input, `window', is an Nx1 double precision array; similar to a SPICE window in that it contains a set of intervals defining a set of windows but perhaps not properly ordered.

cspice_wnvald signals a SPICE error if the left endpoint of any interval is greater than the corresponding right endpoint.

Building a large window is done most efficiently by assigning the window elements and then calling cspice_wnvald. Building up the window by repeated insertion requires repeated ordering operations; cspice_wnvald does a single ordering operation.



Top

Unary Functions



Each unary function operates on a single window. Six unary operations are supported, each of which operates on the contents of the input window. The output window can overwrite any input window. 

   window_f = cspice_wncond( left, right, window)  { Contract }
 
   window_f = cspice_wnexpd( left, right, window)  { Expand }
 
   window_f = cspice_wnextd( side, window)         { Extract }
 
   window_f = cspice_wnfild( sml, window)          { Fill }
 
   window_f = cspice_wnfltd( sml, window)          { Filter }
 
   window   = cspice_wninsd( left, right, ...
                             [window_i] )          { Insert }
 
              Note, [window_i] indicates an optional argument.
cspice_wninsd inserts the interval whose endpoints are `left' and `right' into `window'. If the input interval overlaps any of the intervals in the window, the intervals are merged. Thus, the cardinality of `window' can actually decrease as the result of an insertion.

cspice_wnexpd and cspice_wncond expand (lengthen) and contract (shorten) each of the intervals in `window'. The adjustments are not necessarily symmetric. That is, cspice_wnexpd works by subtracting `left' units from the left endpoint of each interval and adding `right' units to the right endpoint of each interval. cspice_wncond is the same as `exp' with the signs of the arguments reversed, and is primarily provided for clarity in coding. (Expansion by negative increments is a messy concept.) Intervals are merged when expansion causes them to overlap. Intervals are dropped when they are contracted by amounts greater than their measures.

cspice_wnfltd and cspice_wnfild remove small intervals and small gaps between adjacent intervals. Both functions take as input a minimum measure, `small'. cspice_wnfltd filters out (drops) intervals with measures less than or equal to `small', while cspice_wnfild merges adjacent intervals separated by gaps with measures less than or equal to `small'.

Depending on the value of `side', cspice_wnextd extracts the left or right endpoints of each interval in `window'. The resulting window contains only the singleton intervals 

   [ a(1), a(1) ], ..., [ a(n), a(n) ]
or 

   [ b(1), b(1) ], ..., [ b(n), b(n) ]


Top

Binary Functions



Binary functions operate on two input windows to produce a third output window. Three major binary operations are supported. The calling sequences are shown below. 

   c = cspice_wnunid( a, b )    { Union }
 
   c = cspice_wnintd( a, b )    { Intersection }
 
   c = cspice_wndifd( a, b )    { Difference }
The output window, `c', may overwrite an input window, `a' or `b'.

cspice_wnunid places the union of `a' and `b' into `c'. The union of two windows contains every point that is contained in the first window, or in the second window, or in both windows.

cspice_wnintd places the intersection of `a' and `b' into `c'. The intersection of two windows contains every point that is contained in the first window AND in the second.

cspice_wndifd places the difference of `a' and `b' into `c'. The difference of two windows contains every point that is contained in the first window, but NOT in the second. 

 







Top


 Complement Functions




   cspice_wncomd determines the complement of a window with respect to an
   interval. The calling sequence is


 

   c = cspice_wncomd( left, right, a)   { Complement }


   The output window, `c', may overwrite the input window, `a'.


 
   Mathematically, the complement of a window contains those points that
   are not contained in the window. That is, the complement of the set of
   closed intervals


 

   [ a(1), b(1) ], [ a(2), b(2) ], ..., [ a(n), b(n) ]


   is the set of open intervals


 

   ( -inf, a(1) ), ( b(1), a(2) ), ..., ( b(n), +inf )


   Not all computer languages offer a satisfactory way to represent
   infinity, so cspice_wncomd must take the complement with respect to a
   finite interval.


 
   Since the results of a window function must be another window,
   cspice_wncomd returns the closure of the set theoretical complement. In
   short, the double precision complement of the window


 

   [ a(1), b(1) ], [ a(2), b(2) ], ..., [ a(n), b(n) ]


   with respect to the interval from `left' to `right' is the intersection
   of the windows


 

   ( -inf, a(1) ], [ b(1), a(2) ], ..., [ b(n), +inf )


   and [ `left', `right' ].


 
   Intervals of measure zero (singleton intervals) in the original window
   are replaced by gaps of measure zero, which are filled. Thus,
   complementing a window twice does not necessarily yield the original
   window.


 





Top


 Comparison Functions




   Comparison functions allow the contents of windows to be compared
   against the contents of other windows. There are four comparison
   functions: three logical functions and one function. The calling
   sequences are shown below.


 

   cspice_wnelmd( point, window )                    { Element }
 
   cspice_wnincd( left, right, window )              { Inclusion }
 
   cspice_wnreld( a, op, b )                         { Relation }
 
   [ meas, avg, stddev, ...
     shortest, longest ] = cspice_wnsumd( window )   { Summary }


   cspice_wnelmd returns true if the input point, `point', is an element of
   the input window, `window'---that is, whenever the point lies within one
   of the intervals of the window.


 
   Similarly, cspice_wnincd is true whenever the input interval, from
   `left' to `right', is included in the input window, `window'---that is,
   whenever the interval lies entirely within one of the intervals of the
   window.


 
   cspice_wnreld is true whenever a specified relationship between the
   input windows, `a' and `b', is satisfied. Each relationship corresponds
   to a comparison operator, `op'. The complete set of operators recognized
   by cspice_wnreld is shown below.


 

   '='          is equal to (contains the same intervals as)
   '<>'         is not equal to
   '<='         is a subset of
   '<'          is a proper subset of
   '>='         is a superset of
   '>'          is a proper superset of


   For example, the expression


 

   cspice_wnreld( needed, '<=', avail )
 


   is true whenever the window `needed' is a subset of the window `avail'.
   One window is a subset of another window if each of the intervals in the
   first window is included in one of the intervals in the second window.
   In addition, the first window is a proper subset of the second if the
   second window contains at least one point not contained in the first
   window. The following pairs of expressions are equivalent.


 

   cspice_wnreld( a, '>', b )
   cspice_wnreld( a, '<', b )
 
   cspice_wnreld( a, '>=', b )
   cspice_wnreld( a, '<=', b )


   cspice_wnsumd provides a summary of the input window, `window'. It
   computes the measure of the window, `meas', and the average, `avg', and
   standard deviation, `stddev', of the measures of the individual
   intervals in the window. It also returns the indices of the left
   endpoints of the shortest and longest intervals in the window. All of
   these quantities and indices are zero if the window contains no
   intervals.


 
   The following describes the relation of `shortest' and `longest' to the
   window data:


 
   The left endpoint of the shortest interval has value:


 

   window(shortest)


   The right endpoint of the shortest interval has value:


 

   window(shortest+1)


   The left endpoint of the longest interval has value:


 

   window(longest)


   The right endpoint of the longest interval has value:


 

   window(longest+1)







Top


 Summary





   The following is a summary of the window functions in Mice. (DP = double
   precision)


 























Top


 Appendix: Document Revision History










Top


 Febuary 6, 2009 (EDW)




   Document edited to conform to current NAIF format for Required Reading
   Documents. Added descriptions of Icy and Mice window implementations.