| Windows Required Reading |
Table of ContentsWindows Required Reading Abstract Introduction Basic Concepts The window data type References Window Procedures Initialization Procedures Unary Procedures Binary Procedures Complement Procedures Comparison Procedures Summary Appendix: Document Revision History Febuary 6, 2009 (EDW) Windows Required Reading
Abstract
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. Basic Concepts
``cardinality - The number of elements stored in a cell. ``cardinality'' describes how much of ``size'' is used. ``cardinality'' satisfies the relationship:
cardinality < 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 procedures 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. The window data type
The Icy implementation of SPICE windows consists of double precision cells created and initialized to empty using the cspice_celld function. Example:
;;
;; Define the cell 'win' to use as a window. Select a value
;; for the cell size.
;;
MAXSIZ = 8
;;
;; This window can hold eight (MAXSIZ = 8) double precision
;; values, thus four intervals.
;;
win = cspice_celld( MAXSIZ )
The cspice_celld call creates a cell as an anonymous IDL structure
assigned to variable `win' with maximum cardinality `MAXSIZE'.
The cell size, MAXSIZ, must have an even value to use the cell as a window. Two values defines a window interval, so a window of N intervals requires a cell of size 2*N. SPICE windows, when appearing as arguments to the Icy window functions, must have been created from the cspice_celld call. The cell structure has fields corresponding to a CSPICE SpiceCell format:
OFFSET A 9-vector of IDL_MEMINT offsets for each of the
structure fields with respect to the beginning of the
structure.
Element 0 of the array contains the offset to the DTYPE
field; element 1 of the array contains the offset to
the LENGTH field, etc.
This array has no function in a window sense.
The Icy windows implementation uses the 'OFFSET'
values to locate data fields within the IDL structure.
DTYPE Data type of cell: an integer scalar defining the type
of data stored in the cell data array.
LENGTH For character cells, the integer scalar declared length
of the cell's string array.
SIZE An integer scalar defining the maximum number of data
items that can be stored in the cell's data array.
CARD The cell's "cardinality": the integer scalar defining
the number of data items currently present in the cell
Note CARD <= SIZE.
This field has value 0 after cell creation.
ISSET A boolean scalar flag indicating whether the cell is a
SPICE set. Sets have no duplicate data items, and their
data items are stored in increasing order.
ADJUST A boolean scalar flag indicating whether the cell's
data area has adjustable size. Adjustable size cell
data areas are not currently implemented.
INIT A boolean scalar flag indicating whether the cell is
initialized.
BASE The array of type DTYPE with 'SIZE' + 'DATA' elements
(an N-vector, N = SIZE + DATA)
DATA The offset from the first element of the 'BASE' array
to the cell data. This field has value
SPICE_CELL_CTRLSZ (defined in SpiceCel.h), referred to
as the control segment size.
Any of the general cell procedures in Icy may be used with windows. For
example, the function cspice_cardd may be used to determine the number
of endpoints (that is, twice the number of intervals) in a window.
All errors are reported using standard Icy error handling. With the exception of the initialization procedures, all window procedures assume that input cells do contain valid windows---that is, ordered and distinct sets of endpoints. The windows subsystem may not signal errors resulting from attempts to operate on invalid windows. References
Window Procedures
Initialization Procedures
cspice_wnvald, size, n, windowOn input, `window' is a cell of size `size' containing `n' endpoints. During validation, the intervals are ordered, and overlapping intervals are merged. On output, the cardinality of `window' is the number of endpoints remaining, and the window is ready for use with any of the window procedures. Because validation is done in place, there is no chance of overflow. However, other errors may be detected. For example, if the left endpoint of any interval is greater than the corresponding right endpoint, cspice_wnvald signals an error. Validation is primarily useful for ordering and merging intervals added to a cell by cspice_appndd, or directly assigned to the cell. 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. Unary Procedures
cspice_wncond, left, right, window { Contract } cspice_wnexpd, left, right, window { Expand } cspice_wnextd, side, window { Extract } cspice_wnfild, small, window { Fill } cspice_wnfltd, small, window { Filter } cspice_wninsd, left, right, window { Insert }Each of the unary window procedures works in place. That is, only one window, `window', appears in each calling sequence, serving as both input and output. Windows whose original contents need to be preserved should be copied prior to calling any of the unary procedures. 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 procedures 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) ] Binary Procedures
cspice_wnunid, a, b, c { Union } cspice_wnintd, a, b, c { Intersection } cspice_wndifd, a, b, c { Difference }In contrast with the unary procedures, none of the binary procedures work in place. The output window, `c', must be distinct from both of the input windows, `a' and `b'. We will have more to say about this later on. 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. In each case, if the output window, `c', is not large enough to hold the result of the operation, as many intervals as will fit are inserted into the window, and a SPICE error is signaled. (You can control the effect of this error on your program; refer to Error Required Reading.) In each of the binary procedures, the output window must be distinct from both of the input windows. All three of the binary operations can, in principle, be performed in place, but not all can be performed efficiently. Consequently, for the sake of consistency, none of the procedures work in place. For example, the following calls are invalid.
cspice_wnintd, a, b, a cspice_wnintd, a, b, bIn each of the examples above, whether or not the procedure signals an error, the results will almost certainly be wrong. Nearly the same effect can be achieved, however, by placing the result into a temporary window, which can be immediately copied back into one of the input windows, as shown below.
cspice_wnintd, a, b, temp a = temp Complement Procedures
cspice_wncomd, left, right, a, c { Complement }As with the binary procedures, the output window, `c', must be distinct from 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 procedure 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. Comparison Procedures
cspice_wnelmd( point, window ) { Element } cspice_wnincd( left, right, window ) { Inclusion } cspice_wnreld( a, op, b ) { Relation } cspice_wnsumd, window, meas, avg, $ stddev, shortest, longest { 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 ofFor 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 folowing describes the relation of `shortest' and `longest' to the window data:
data_start = window.data
data_end = data_start + window.card - 1
array = window.base[ data_start:data_end]
The left endpoint of the shortest interval has value:
array[shortest]The right endpoint of the shortest interval has value:
array[shortest+1]The left endpoint of the longest interval has value:
array[longest]The right endpoint of the longest interval has value:
array[longest+1] Summary
Appendix: Document Revision HistoryFebuary 6, 2009 (EDW)
|