1 /* gffove.f -- translated by f2c (version 19980913).
2 You must link the resulting object file with the libraries:
3 -lf2c -lm (in that order)
4 */
5
6 #include "f2c.h"
7
8 /* Table of constant values */
9
10 static integer c__0 = 0;
11 static logical c_false = FALSE_;
12 static doublereal c_b16 = 1.;
13
14 /* $Procedure GFFOVE ( GF, is target in FOV? ) */
gffove_(char * inst,char * tshape,doublereal * raydir,char * target,char * tframe,char * abcorr,char * obsrvr,doublereal * tol,U_fp udstep,U_fp udrefn,logical * rpt,S_fp udrepi,U_fp udrepu,S_fp udrepf,logical * bail,L_fp udbail,doublereal * cnfine,doublereal * result,ftnlen inst_len,ftnlen tshape_len,ftnlen target_len,ftnlen tframe_len,ftnlen abcorr_len,ftnlen obsrvr_len)15 /* Subroutine */ int gffove_(char *inst, char *tshape, doublereal *raydir,
16 char *target, char *tframe, char *abcorr, char *obsrvr, doublereal *
17 tol, U_fp udstep, U_fp udrefn, logical *rpt, S_fp udrepi, U_fp udrepu,
18 S_fp udrepf, logical *bail, L_fp udbail, doublereal *cnfine,
19 doublereal *result, ftnlen inst_len, ftnlen tshape_len, ftnlen
20 target_len, ftnlen tframe_len, ftnlen abcorr_len, ftnlen obsrvr_len)
21 {
22 /* System generated locals */
23 integer i__1;
24
25 /* Local variables */
26 extern /* Subroutine */ int zzgffvin_(char *, char *, doublereal *, char *
27 , char *, char *, char *, ftnlen, ftnlen, ftnlen, ftnlen, ftnlen,
28 ftnlen);
29 extern /* Subroutine */ int zzgffvst_();
30 extern /* Subroutine */ int zzgfsolv_(U_fp, U_fp, U_fp, logical *, L_fp,
31 logical *, doublereal *, doublereal *, doublereal *, doublereal *,
32 logical *, U_fp, doublereal *);
33 integer i__;
34 extern /* Subroutine */ int chkin_(char *, ftnlen), errdp_(char *,
35 doublereal *, ftnlen);
36 extern integer sized_(doublereal *);
37 integer count;
38 doublereal start;
39 extern logical failed_(void);
40 extern /* Subroutine */ int scardd_(integer *, doublereal *);
41 extern integer wncard_(doublereal *);
42 doublereal finish;
43 extern /* Subroutine */ int setmsg_(char *, ftnlen), errint_(char *,
44 integer *, ftnlen);
45 extern logical return_(void);
46 extern /* Subroutine */ int sigerr_(char *, ftnlen), chkout_(char *,
47 ftnlen), wnfetd_(doublereal *, integer *, doublereal *,
48 doublereal *);
49
50 /* $ Abstract */
51
52 /* Determine time intervals when a specified target body or ray */
53 /* intersects the space bounded by the field-of-view (FOV) of a */
54 /* specified instrument. Report progress and handle interrupts if so */
55 /* commanded. */
56
57 /* $ Disclaimer */
58
59 /* THIS SOFTWARE AND ANY RELATED MATERIALS WERE CREATED BY THE */
60 /* CALIFORNIA INSTITUTE OF TECHNOLOGY (CALTECH) UNDER A U.S. */
61 /* GOVERNMENT CONTRACT WITH THE NATIONAL AERONAUTICS AND SPACE */
62 /* ADMINISTRATION (NASA). THE SOFTWARE IS TECHNOLOGY AND SOFTWARE */
63 /* PUBLICLY AVAILABLE UNDER U.S. EXPORT LAWS AND IS PROVIDED "AS-IS" */
64 /* TO THE RECIPIENT WITHOUT WARRANTY OF ANY KIND, INCLUDING ANY */
65 /* WARRANTIES OF PERFORMANCE OR MERCHANTABILITY OR FITNESS FOR A */
66 /* PARTICULAR USE OR PURPOSE (AS SET FORTH IN UNITED STATES UCC */
67 /* SECTIONS 2312-2313) OR FOR ANY PURPOSE WHATSOEVER, FOR THE */
68 /* SOFTWARE AND RELATED MATERIALS, HOWEVER USED. */
69
70 /* IN NO EVENT SHALL CALTECH, ITS JET PROPULSION LABORATORY, OR NASA */
71 /* BE LIABLE FOR ANY DAMAGES AND/OR COSTS, INCLUDING, BUT NOT */
72 /* LIMITED TO, INCIDENTAL OR CONSEQUENTIAL DAMAGES OF ANY KIND, */
73 /* INCLUDING ECONOMIC DAMAGE OR INJURY TO PROPERTY AND LOST PROFITS, */
74 /* REGARDLESS OF WHETHER CALTECH, JPL, OR NASA BE ADVISED, HAVE */
75 /* REASON TO KNOW, OR, IN FACT, SHALL KNOW OF THE POSSIBILITY. */
76
77 /* RECIPIENT BEARS ALL RISK RELATING TO QUALITY AND PERFORMANCE OF */
78 /* THE SOFTWARE AND ANY RELATED MATERIALS, AND AGREES TO INDEMNIFY */
79 /* CALTECH AND NASA FOR ALL THIRD-PARTY CLAIMS RESULTING FROM THE */
80 /* ACTIONS OF RECIPIENT IN THE USE OF THE SOFTWARE. */
81
82 /* $ Required_Reading */
83
84 /* CK */
85 /* FRAMES */
86 /* GF */
87 /* KERNEL */
88 /* NAIF_IDS */
89 /* PCK */
90 /* SPK */
91 /* TIME */
92 /* WINDOWS */
93
94 /* $ Keywords */
95
96 /* EVENT */
97 /* FOV */
98 /* GEOMETRY */
99 /* INSTRUMENT */
100 /* SEARCH */
101 /* WINDOW */
102
103 /* $ Declarations */
104 /* $ Abstract */
105
106 /* This file contains public, global parameter declarations */
107 /* for the SPICELIB Geometry Finder (GF) subsystem. */
108
109 /* $ Disclaimer */
110
111 /* THIS SOFTWARE AND ANY RELATED MATERIALS WERE CREATED BY THE */
112 /* CALIFORNIA INSTITUTE OF TECHNOLOGY (CALTECH) UNDER A U.S. */
113 /* GOVERNMENT CONTRACT WITH THE NATIONAL AERONAUTICS AND SPACE */
114 /* ADMINISTRATION (NASA). THE SOFTWARE IS TECHNOLOGY AND SOFTWARE */
115 /* PUBLICLY AVAILABLE UNDER U.S. EXPORT LAWS AND IS PROVIDED "AS-IS" */
116 /* TO THE RECIPIENT WITHOUT WARRANTY OF ANY KIND, INCLUDING ANY */
117 /* WARRANTIES OF PERFORMANCE OR MERCHANTABILITY OR FITNESS FOR A */
118 /* PARTICULAR USE OR PURPOSE (AS SET FORTH IN UNITED STATES UCC */
119 /* SECTIONS 2312-2313) OR FOR ANY PURPOSE WHATSOEVER, FOR THE */
120 /* SOFTWARE AND RELATED MATERIALS, HOWEVER USED. */
121
122 /* IN NO EVENT SHALL CALTECH, ITS JET PROPULSION LABORATORY, OR NASA */
123 /* BE LIABLE FOR ANY DAMAGES AND/OR COSTS, INCLUDING, BUT NOT */
124 /* LIMITED TO, INCIDENTAL OR CONSEQUENTIAL DAMAGES OF ANY KIND, */
125 /* INCLUDING ECONOMIC DAMAGE OR INJURY TO PROPERTY AND LOST PROFITS, */
126 /* REGARDLESS OF WHETHER CALTECH, JPL, OR NASA BE ADVISED, HAVE */
127 /* REASON TO KNOW, OR, IN FACT, SHALL KNOW OF THE POSSIBILITY. */
128
129 /* RECIPIENT BEARS ALL RISK RELATING TO QUALITY AND PERFORMANCE OF */
130 /* THE SOFTWARE AND ANY RELATED MATERIALS, AND AGREES TO INDEMNIFY */
131 /* CALTECH AND NASA FOR ALL THIRD-PARTY CLAIMS RESULTING FROM THE */
132 /* ACTIONS OF RECIPIENT IN THE USE OF THE SOFTWARE. */
133
134 /* $ Required_Reading */
135
136 /* GF */
137
138 /* $ Keywords */
139
140 /* GEOMETRY */
141 /* ROOT */
142
143 /* $ Restrictions */
144
145 /* None. */
146
147 /* $ Author_and_Institution */
148
149 /* N.J. Bachman (JPL) */
150 /* L.E. Elson (JPL) */
151 /* E.D. Wright (JPL) */
152
153 /* $ Literature_References */
154
155 /* None. */
156
157 /* $ Version */
158
159 /* - SPICELIB Version 2.0.0 29-NOV-2016 (NJB) */
160
161 /* Upgraded to support surfaces represented by DSKs. */
162
163 /* Bug fix: removed declaration of NVRMAX parameter. */
164
165 /* - SPICELIB Version 1.3.0, 01-OCT-2011 (NJB) */
166
167 /* Added NWILUM parameter. */
168
169 /* - SPICELIB Version 1.2.0, 14-SEP-2010 (EDW) */
170
171 /* Added NWPA parameter. */
172
173 /* - SPICELIB Version 1.1.0, 08-SEP-2009 (EDW) */
174
175 /* Added NWRR parameter. */
176 /* Added NWUDS parameter. */
177
178 /* - SPICELIB Version 1.0.0, 21-FEB-2009 (NJB) (LSE) (EDW) */
179
180 /* -& */
181
182 /* Root finding parameters: */
183
184 /* CNVTOL is the default convergence tolerance used by the */
185 /* high-level GF search API routines. This tolerance is */
186 /* used to terminate searches for binary state transitions: */
187 /* when the time at which a transition occurs is bracketed */
188 /* by two times that differ by no more than CNVTOL, the */
189 /* transition time is considered to have been found. */
190
191 /* Units are TDB seconds. */
192
193
194 /* NWMAX is the maximum number of windows allowed for user-defined */
195 /* workspace array. */
196
197 /* DOUBLE PRECISION WORK ( LBCELL : MW, NWMAX ) */
198
199 /* Currently no more than twelve windows are required; the three */
200 /* extra windows are spares. */
201
202 /* Callers of GFEVNT can include this file and use the parameter */
203 /* NWMAX to declare the second dimension of the workspace array */
204 /* if necessary. */
205
206
207 /* Callers of GFIDST should declare their workspace window */
208 /* count using NWDIST. */
209
210
211 /* Callers of GFSEP should declare their workspace window */
212 /* count using NWSEP. */
213
214
215 /* Callers of GFRR should declare their workspace window */
216 /* count using NWRR. */
217
218
219 /* Callers of GFUDS should declare their workspace window */
220 /* count using NWUDS. */
221
222
223 /* Callers of GFPA should declare their workspace window */
224 /* count using NWPA. */
225
226
227 /* Callers of GFILUM should declare their workspace window */
228 /* count using NWILUM. */
229
230
231 /* ADDWIN is a parameter used to expand each interval of the search */
232 /* (confinement) window by a small amount at both ends in order to */
233 /* accommodate searches using equality constraints. The loaded */
234 /* kernel files must accommodate these expanded time intervals. */
235
236
237 /* FRMNLN is a string length for frame names. */
238
239
240 /* FOVTLN -- maximum length for FOV string. */
241
242
243 /* Specify the character strings that are allowed in the */
244 /* specification of field of view shapes. */
245
246
247 /* Character strings that are allowed in the */
248 /* specification of occultation types: */
249
250
251 /* Occultation target shape specifications: */
252
253
254 /* Specify the number of supported occultation types and occultation */
255 /* type string length: */
256
257
258 /* Instrument field-of-view (FOV) parameters */
259
260 /* Maximum number of FOV boundary vectors: */
261
262
263 /* FOV shape parameters: */
264
265 /* circle */
266 /* ellipse */
267 /* polygon */
268 /* rectangle */
269
270
271 /* End of file gf.inc. */
272
273 /* $ Brief_I/O */
274
275 /* VARIABLE I/O DESCRIPTION */
276 /* -------- --- -------------------------------------------------- */
277 /* LBCELL P SPICE Cell lower bound. */
278 /* MAXVRT P Maximum number of FOV boundary vertices. */
279 /* INST I Name of the instrument. */
280 /* TSHAPE I Type of shape model used for target body. */
281 /* RAYDIR I Ray's direction vector. */
282 /* TARGET I Name of the target body. */
283 /* TFRAME I Body-fixed, body-centered frame for target body. */
284 /* ABCORR I Aberration correction flag. */
285 /* OBSRVR I Name of the observing body. */
286 /* TOL I Convergence tolerance in seconds. */
287 /* UDSTEP I Name of routine that returns a time step. */
288 /* UDREFN I Name of the routine that computes a refined time. */
289 /* RPT I Progress report flag. */
290 /* UDREPI I Function that initializes progress reporting. */
291 /* UDREPU I Function that updates the progress report. */
292 /* UDREPF I Function that finalizes progress reporting. */
293 /* BAIL I Logical indicating program interrupt monitoring. */
294 /* UDBAIL I Name of a routine that signals a program interrupt. */
295 /* CNFINE I SPICE window to which the search is restricted. */
296 /* RESULT O SPICE window containing results. */
297
298 /* $ Detailed_Input */
299
300 /* INST indicates the name of an instrument, such as a */
301 /* spacecraft-mounted framing camera, the field of view */
302 /* (FOV) of which is to be used for a target intersection */
303 /* search: times when the specified target intersects the */
304 /* region of space corresponding to the FOV are sought. */
305
306 /* INST must have a corresponding NAIF ID and a frame */
307 /* defined, as is normally done in a frame kernel. It */
308 /* must also have an associated reference frame and a FOV */
309 /* shape, boresight and boundary vertices (or reference */
310 /* vector and reference angles) defined, as is usually */
311 /* done in an instrument kernel. */
312
313 /* See the header of the SPICELIB routine GETFOV for a */
314 /* description of the required parameters associated with */
315 /* an instrument. */
316
317
318 /* TSHAPE is a string indicating the geometric model used to */
319 /* represent the location and shape of the target body. */
320 /* The target body may be represented by either an */
321 /* ephemeris object or a ray emanating from the observer. */
322
323 /* The supported values of TSHAPE are: */
324
325 /* 'ELLIPSOID' The target is an ephemeris object. */
326
327 /* The target's shape is represented */
328 /* using triaxial ellipsoid model, */
329 /* with radius values provided via the */
330 /* kernel pool. A kernel variable */
331 /* having a name of the form */
332
333 /* 'BODYnnn_RADII' */
334
335 /* where nnn represents the NAIF */
336 /* integer code associated with the */
337 /* body, must be present in the kernel */
338 /* pool. This variable must be */
339 /* associated with three numeric */
340 /* values giving the lengths of the */
341 /* ellipsoid's X, Y, and Z semi-axes. */
342
343 /* 'POINT' The target is an ephemeris object. */
344 /* The body is treated as a single */
345 /* point. */
346
347 /* 'RAY' The target is NOT an ephemeris */
348 /* object. Instead, the target is */
349 /* represented by the ray emanating */
350 /* from the observer's location and */
351 /* having direction vector RAYDIR. The */
352 /* target is considered to be visible */
353 /* if and only if the ray is contained */
354 /* within the space bounded by the */
355 /* instrument FOV. */
356
357 /* Case and leading or trailing blanks are not */
358 /* significant in the string TSHAPE. */
359
360
361 /* RAYDIR is the direction vector associated with a ray */
362 /* representing the target. RAYDIR is used if and only */
363 /* if TSHAPE (see description above) indicates the */
364 /* target is modeled as a ray. */
365
366
367 /* TARGET is the name of the target body, the appearances of */
368 /* which in the specified instrument's field of view are */
369 /* sought. The body must be an ephemeris object. */
370
371 /* Optionally, you may supply the integer NAIF ID code */
372 /* for the body as a string. For example both 'MOON' and */
373 /* '301' are legitimate strings that designate the Moon. */
374
375 /* Case and leading or trailing blanks are not */
376 /* significant in the string TARGET. */
377
378 /* The input argument TARGET is used if and only if the */
379 /* target is NOT modeled as ray, as indicated by the */
380 /* input argument TSHAPE. */
381
382 /* TARGET may be set to a blank string if the target is */
383 /* modeled as a ray. */
384
385
386 /* TFRAME is the name of the reference frame associated with the */
387 /* target. Examples of such names are 'IAU_SATURN' */
388 /* (for Saturn) and 'ITRF93' (for the Earth). */
389
390 /* If the target is an ephemeris object modeled as an */
391 /* ellipsoid, TFRAME must designate a body-fixed */
392 /* reference frame centered on the target body. */
393
394 /* If the target is an ephemeris object modeled as a */
395 /* point, TFRAME is ignored; TFRAME should be left blank. */
396
397 /* If the target is modeled as a ray, TFRAME may */
398 /* designate any reference frame. Since light time */
399 /* corrections are not supported for rays, the */
400 /* orientation of the frame is always evaluated at the */
401 /* epoch associated with the observer, as opposed to the */
402 /* epoch associated with the light-time corrected */
403 /* position of the frame center. */
404
405 /* Case and leading or trailing blanks bracketing a */
406 /* non-blank frame name are not significant in the string */
407 /* TFRAME. */
408
409
410 /* ABCORR indicates the aberration corrections to be applied */
411 /* when computing the target's position and orientation. */
412 /* The supported values of ABCORR depend on the target */
413 /* representation. */
414
415 /* If the target is represented by a ray, the aberration */
416 /* correction options are */
417
418 /* 'NONE' No correction. */
419 /* 'S' Stellar aberration correction, */
420 /* reception case. */
421 /* 'XS' Stellar aberration correction, */
422 /* transmission case. */
423
424 /* If the target is an ephemeris object, the aberration */
425 /* correction options are those supported by the SPICE */
426 /* SPK system. For remote sensing applications, where the */
427 /* apparent position and orientation of the target seen */
428 /* by the observer are desired, normally either of the */
429 /* corrections */
430
431 /* 'LT+S' */
432 /* 'CN+S' */
433
434 /* should be used. These and the other supported options */
435 /* are described below. */
436
437 /* Supported aberration correction options for */
438 /* observation (the case where radiation is received by */
439 /* observer at ET) are: */
440
441 /* 'NONE' No correction. */
442 /* 'LT' Light time only */
443 /* 'LT+S' Light time and stellar aberration. */
444 /* 'CN' Converged Newtonian (CN) light time. */
445 /* 'CN+S' CN light time and stellar aberration. */
446
447 /* Supported aberration correction options for */
448 /* transmission (the case where radiation is emitted from */
449 /* observer at ET) are: */
450
451 /* 'XLT' Light time only. */
452 /* 'XLT+S' Light time and stellar aberration. */
453 /* 'XCN' Converged Newtonian (CN) light time. */
454 /* 'XCN+S' CN light time and stellar aberration. */
455
456 /* For detailed information, see the geometry finder */
457 /* required reading, gf.req. */
458
459 /* Case, leading and trailing blanks are not significant */
460 /* in the string ABCORR. */
461
462
463 /* OBSRVR is the name of the body from which the target is */
464 /* observed. The instrument designated by INST is treated */
465 /* as if it were co-located with the observer. */
466
467 /* Optionally, you may supply the integer NAIF ID code */
468 /* for the body as a string. */
469
470 /* Case and leading or trailing blanks are not */
471 /* significant in the string OBSRVR. */
472
473
474 /* TOL is a tolerance value used to determine convergence of */
475 /* root-finding operations. TOL is measured in TDB */
476 /* seconds and must be greater than zero. */
477
478
479 /* UDSTEP is an externally specified routine that computes a */
480 /* time step used to find transitions of the state being */
481 /* considered. A state transition occurs where the state */
482 /* changes from being "visible" to being "not visible" or */
483 /* vice versa. */
484
485 /* This routine relies on UDSTEP returning step sizes */
486 /* small enough so that state transitions within the */
487 /* confinement window are not overlooked. */
488
489 /* The calling sequence for UDSTEP is: */
490
491 /* CALL UDSTEP ( ET, STEP ) */
492
493 /* where: */
494
495 /* ET is the input start time from which the */
496 /* algorithm is to search forward for a state */
497 /* transition. ET is expressed as seconds past */
498 /* J2000 TDB. ET is a DOUBLE PRECISION number. */
499
500 /* STEP is the output step size. STEP indicates */
501 /* how far to advance ET so that ET and */
502 /* ET+STEP may bracket a state transition and */
503 /* definitely do not bracket more than one */
504 /* state transition. STEP is a DOUBLE */
505 /* PRECISION number. Units are TDB seconds. */
506
507 /* If a constant step size is desired, the routine GFSTEP */
508 /* may be used. If GFSTEP is used, the step size must be */
509 /* set by calling GFSSTP prior to calling this routine. */
510
511
512 /* UDREFN is the name of the externally specified routine that */
513 /* refines the times that bracket a transition point. In */
514 /* other words, once a pair of times, T1 and T2, that */
515 /* bracket a state transition have been found, UDREFN */
516 /* computes an intermediate time T such that either */
517 /* [T1, T] or [T, T2] contains the time of the state */
518 /* transition. The calling sequence for UDREFN is: */
519
520 /* CALL UDREFN ( T1, T2, S1, S2, T ) */
521
522 /* where the inputs are: */
523
524 /* T1 is a time when the visibility state is S1. T1 */
525 /* is expressed as seconds past J2000 TDB. */
526
527 /* T2 is a time when the visibility state is S2. T2 */
528 /* is expressed as seconds past J2000 TDB. and */
529 /* is assumed to be larger than T1. */
530
531 /* S1 is the visibility state at time T1. S1 is a */
532 /* LOGICAL value. */
533
534 /* S2 is the visibility state at time T2. S2 is a */
535 /* LOGICAL value. */
536
537 /* The output is: */
538
539 /* T is the next time to check for a state */
540 /* transition. T is expressed as seconds past */
541 /* J2000 TDB and is between T1 and T2. */
542
543 /* If a simple bisection method is desired, the routine */
544 /* GFREFN may be used. */
545
546
547 /* RPT is a logical variable that controls whether */
548 /* progress reporting is enabled. When RPT is .TRUE., */
549 /* progress reporting is enabled and the routines */
550 /* UDREPI, UDREPU, and UDPREF (see descriptions below) */
551 /* are used to report progress. */
552
553
554 /* UDREPI is a user-defined subroutine that initializes a */
555 /* progress report. When progress reporting is */
556 /* enabled, UDREPI is called at the start */
557 /* of a search. The calling sequence of UDREPI is */
558
559 /* UDREPI ( CNFINE, SRCPRE, SRCSUF ) */
560
561 /* DOUBLE PRECISION CNFINE ( LBCELL : * ) */
562 /* CHARACTER*(*) SRCPRE */
563 /* CHARACTER*(*) SRCSUF */
564
565 /* where */
566
567 /* CNFINE */
568
569 /* is the confinement window and */
570
571 /* SRCPRE */
572 /* SRCSUF */
573
574 /* are prefix and suffix strings used in the progress */
575 /* report: these strings are intended to bracket a */
576 /* representation of the fraction of work done. For */
577 /* example, when the SPICELIB progress reporting functions */
578 /* are used, if SRCPRE and SRCSUF are, respectively, */
579
580 /* 'FOV search' */
581 /* 'done.' */
582
583 /* the progress report display at the end of the */
584 /* search will be: */
585
586 /* FOV search 100.00% done. */
587
588 /* The SPICELIB routine GFREPI may be used as the */
589 /* actual argument corresponding to UDREPI. If so, */
590 /* the SPICELIB routines GFREPU and GFREPF must be */
591 /* the actual arguments corresponding to UDREPU and */
592 /* UDREPF. */
593
594
595 /* UDREPU is a user-defined subroutine that updates the */
596 /* progress report for a search. The calling sequence */
597 /* of UDREPU is */
598
599 /* UDREPU ( IVBEG, IVEND, ET ) */
600
601 /* DOUBLE PRECISION IVBEG */
602 /* DOUBLE PRECISION IVEND */
603 /* DOUBLE PRECISION ET */
604
605 /* Here IVBEG, IVEND are the bounds of an interval that */
606 /* is contained in some interval belonging to the */
607 /* confinement window. The confinement window is */
608 /* associated with some root finding activity. It is used */
609 /* to determine how much total time is being searched in */
610 /* order to find the events of interest. */
611
612 /* ET is an epoch belonging to the interval [IVBEG, */
613 /* IVEND]. */
614
615 /* In order for a meaningful progress report to be */
616 /* displayed, IVBEG and IVEND must satisfy the following */
617 /* constraints: */
618
619 /* - IVBEG must be less than or equal to IVEND. */
620
621 /* - The interval [ IVBEG, IVEND ] must be contained in */
622 /* some interval of the confinement window. It can be */
623 /* a proper subset of the containing interval; that */
624 /* is, it can be smaller than the interval of the */
625 /* confinement window that contains it. */
626
627 /* - Over a search, the sum of the differences */
628
629 /* IVEND - IVBEG */
630
631 /* for all calls to this routine made during the search */
632 /* must equal the measure of the confinement window. */
633
634 /* The SPICELIB routine GFREPU may be used as the */
635 /* actual argument corresponding to UDREPU. If so, */
636 /* the SPICELIB routines GFREPI and GFREPF must be */
637 /* the actual arguments corresponding to UDREPI and */
638 /* UDREPF. */
639
640
641 /* UDREPF is a user-defined subroutine that finalizes a */
642 /* progress report. UDREPF has no arguments. */
643
644 /* The SPICELIB routine GFREPF may be used as the */
645 /* actual argument corresponding to UDREPF. If so, */
646 /* the SPICELIB routines GFREPI and GFREPU must be */
647 /* the actual arguments corresponding to UDREPI and */
648 /* UDREPU. */
649
650
651 /* BAIL is a logical variable indicating whether or not */
652 /* interrupt handling is enabled. When BAIL is */
653 /* set to .TRUE., the input function UDBAIL (see */
654 /* description below) is used to determine whether */
655 /* an interrupt has been issued. */
656
657
658 /* UDBAIL is the name of a user defined logical function that */
659 /* indicates whether an interrupt signal has been */
660 /* issued (for example, from the keyboard). UDBAIL */
661 /* has no arguments and returns a LOGICAL value. */
662 /* The return value is .TRUE. if an interrupt has */
663 /* been issued; otherwise the value is .FALSE. */
664
665 /* GFFOVE uses UDBAIL only when BAIL (see above) is set */
666 /* to .TRUE., indicating that interrupt handling is */
667 /* enabled. When interrupt handling is enabled, GFFOVE */
668 /* and routines in its call tree will call UDBAIL to */
669 /* determine whether to terminate processing and return */
670 /* immediately. */
671
672 /* If interrupt handing is not enabled, a logical */
673 /* function must still be passed to GFFOVE as */
674 /* an input argument. The SPICE function */
675
676 /* GFBAIL */
677
678 /* may be used for this purpose. */
679
680
681 /* CNFINE is a SPICE window that confines the time period over */
682 /* which the specified search is conducted. CNFINE may */
683 /* consist of a single interval or a collection of */
684 /* intervals. */
685
686 /* The endpoints of the time intervals comprising CNFINE */
687 /* are interpreted as seconds past J2000 TDB. */
688
689 /* See the Examples section below for a code example */
690 /* that shows how to create a confinement window. */
691
692 /* CNFINE must be initialized by the caller via the */
693 /* SPICELIB routine SSIZED. */
694
695 /* $ Detailed_Output */
696
697 /* RESULT is a SPICE window representing the set of time */
698 /* intervals, within the confinement period, when image */
699 /* of the target body is partially or completely within */
700 /* the specified instrument field of view. */
701
702 /* The endpoints of the time intervals comprising RESULT */
703 /* are interpreted as seconds past J2000 TDB. */
704
705 /* If RESULT is non-empty on input, its contents */
706 /* will be discarded before GFFOVE conducts its */
707 /* search. */
708
709 /* $ Parameters */
710
711 /* LBCELL is the lower bound for SPICE cell arrays. */
712
713
714 /* MAXVRT is the maximum number of vertices that may be used */
715 /* to define the boundary of the specified instrument's */
716 /* field of view. */
717
718 /* See INCLUDE file gf.inc for declarations and descriptions of */
719 /* parameters used throughout the GF system. */
720
721 /* $ Exceptions */
722
723 /* 1) In order for this routine to produce correct results, */
724 /* the step size must be appropriate for the problem at hand. */
725 /* Step sizes that are too large may cause this routine to miss */
726 /* roots; step sizes that are too small may cause this routine */
727 /* to run unacceptably slowly and in some cases, find spurious */
728 /* roots. */
729
730 /* This routine does not diagnose invalid step sizes, except */
731 /* that if the step size is non-positive, the error */
732 /* SPICE(INVALIDSTEPSIZE) will be signaled. */
733
734 /* 2) Due to numerical errors, in particular, */
735
736 /* - Truncation error in time values */
737 /* - Finite tolerance value */
738 /* - Errors in computed geometric quantities */
739
740 /* it is *normal* for the condition of interest to not always be */
741 /* satisfied near the endpoints of the intervals comprising the */
742 /* result window. */
743
744 /* The result window may need to be contracted slightly by the */
745 /* caller to achieve desired results. The SPICE window routine */
746 /* WNCOND can be used to contract the result window. */
747
748 /* 3) If the name of either the target or observer cannot be */
749 /* translated to a NAIF ID code, the error will be diagnosed by */
750 /* a routine in the call tree of this routine. */
751
752 /* 4) If the specified aberration correction is not a supported */
753 /* value for the target type (ephemeris object or ray), the */
754 /* error will be diagnosed by a routine in the call tree of this */
755 /* routine. */
756
757 /* 5) If the radii of a target body modeled as an ellipsoid cannot */
758 /* be determined by searching the kernel pool for a kernel */
759 /* variable having a name of the form */
760
761 /* 'BODYnnn_RADII' */
762
763 /* where nnn represents the NAIF integer code associated with */
764 /* the body, the error will be diagnosed by a routine in the */
765 /* call tree of this routine. */
766
767 /* 6) If the target body coincides with the observer body OBSRVR, */
768 /* the error will be diagnosed by a routine in the call tree of */
769 /* this routine. */
770
771 /* 7) If the body model specifier TSHAPE is not recognized, the */
772 /* error will be diagnosed by a routine in the call tree of this */
773 /* routine. */
774
775 /* 8) If a target body-fixed reference frame associated with a */
776 /* non-point target is not recognized, the error will be */
777 /* diagnosed by a routine in the call tree of this routine. */
778
779 /* 9) If a target body-fixed reference frame is not centered at */
780 /* the corresponding target body, the error will be */
781 /* diagnosed by a routine in the call tree of this routine. */
782
783 /* 10) If the instrument name INST does not have corresponding NAIF */
784 /* ID code, the error will be diagnosed by a routine in the call */
785 /* tree of this routine. */
786
787 /* 11) If the FOV parameters of the instrument are not present in */
788 /* the kernel pool, the error will be be diagnosed by routines */
789 /* in the call tree of this routine. */
790
791 /* 12) If the FOV boundary has more than MAXVRT vertices, the error */
792 /* will be be diagnosed by routines in the call tree of this */
793 /* routine. */
794
795 /* 13) If the instrument FOV is polygonal, and this routine cannot */
796 /* find a ray R emanating from the FOV vertex such that maximum */
797 /* angular separation of R and any FOV boundary vector is within */
798 /* the limit (pi/2)-SPICE_GF_MARGIN radians, the error will be */
799 /* diagnosed by a routine in the call tree of this routine. If */
800 /* the FOV is any other shape, the same error check will be */
801 /* applied with the instrument boresight vector serving the role */
802 /* of R. */
803
804 /* 14) If the loaded kernels provide insufficient data to compute a */
805 /* requested state vector, the error will be diagnosed by a */
806 /* routine in the call tree of this routine. */
807
808 /* 15) If an error occurs while reading an SPK or other kernel file, */
809 /* the error will be diagnosed by a routine in the call tree */
810 /* of this routine. */
811
812 /* 16) If the output SPICE window RESULT has insufficient capacity */
813 /* to contain the number of intervals on which the specified */
814 /* visibility condition is met, the error will be diagnosed */
815 /* by a routine in the call tree of this routine. If the result */
816 /* window has size less than 2, the error SPICE(WINDOWTOOSMALL) */
817 /* will be signaled by this routine. */
818
819 /* 17) If the convergence tolerance size is non-positive, the error */
820 /* SPICE(INVALIDTOLERANCE) will be signaled. */
821
822 /* 18) If the step size is non-positive, the error */
823 /* SPICE(INVALIDSTEP) will be signaled. */
824
825 /* 19) If the ray's direction vector is zero, the error */
826 /* SPICE(ZEROVECTOR) is signaled. */
827
828
829 /* $ Files */
830
831 /* Appropriate SPICE ernels must be loaded by the calling program */
832 /* before this routine is called. */
833
834 /* The following data are required: */
835
836 /* - SPK data: ephemeris data for target and observer that */
837 /* describes the ephemeris of these objects for the period */
838 /* defined by the confinement window, 'CNFINE' must be */
839 /* loaded. If aberration corrections are used, the states of */
840 /* target and observer relative to the solar system barycenter */
841 /* must be calculable from the available ephemeris data. */
842 /* Typically ephemeris data are made available by loading one */
843 /* or more SPK files via FURNSH. */
844
845 /* - Frame data: if a frame definition is required to convert */
846 /* the observer and target states to the body-fixed frame of */
847 /* the target, that definition must be available in the kernel */
848 /* pool. Typically the definitions of frames not already */
849 /* built-in to SPICE are supplied by loading a frame kernel. */
850
851 /* Data defining the reference frame associated with the */
852 /* instrument designated by INST must be available in the kernel */
853 /* pool. Additionally the name INST must be associated with an */
854 /* ID code. Normally these data are made available by loading */
855 /* a frame kernel via FURNSH. */
856
857 /* - IK data: the kernel pool must contain data such that */
858 /* the SPICELIB routine GETFOV may be called to obtain */
859 /* parameters for INST. Normally such data are provided by */
860 /* an IK via FURNSH. */
861
862 /* The following data may be required: */
863
864 /* - PCK data: bodies modeled as triaxial ellipsoids must have */
865 /* orientation data provided by variables in the kernel pool. */
866 /* Typically these data are made available by loading a text */
867 /* PCK file via FURNSH. */
868
869 /* Bodies modeled as triaxial ellipsoids must have semi-axis */
870 /* lengths provided by variables in the kernel pool. Typically */
871 /* these data are made available by loading a text PCK file via */
872 /* FURNSH. */
873
874 /* - CK data: if the instrument frame is fixed to a spacecraft, */
875 /* at least one CK file will be needed to permit transformation */
876 /* of vectors between that frame and both J2000 and the target */
877 /* body-fixed frame. */
878
879 /* - SCLK data: if a CK file is needed, an associated SCLK */
880 /* kernel is required to enable conversion between encoded SCLK */
881 /* (used to time-tag CK data) and barycentric dynamical time */
882 /* (TDB). */
883
884 /* - Since the input ray direction may be expressed in any */
885 /* frame, FKs, CKs, SCLK kernels, PCKs, and SPKs may be */
886 /* required to map the direction to the J2000 frame. */
887 /* Kernel data are normally loaded once per program run, NOT every */
888 /* time this routine is called. */
889
890 /* $ Particulars */
891
892 /* This routine determines a set of one or more time intervals */
893 /* within the confinement window when a specified ray or any portion */
894 /* of a specified target body appears within the field of view of a */
895 /* specified instrument. We'll use the term "visibility event" to */
896 /* designate such an appearance. The set of time intervals resulting */
897 /* from the search is returned as a SPICE window. */
898
899 /* This routine provides the SPICE GF system's most flexible */
900 /* interface for searching for FOV intersection events. */
901
902 /* Applications that require do not require support for progress */
903 /* reporting, interrupt handling, non-default step or refinement */
904 /* functions, or non-default convergence tolerance normally should */
905 /* call either GFTFOV or GFRFOV rather than this routine. */
906
907 /* Below we discuss in greater detail aspects of this routine's */
908 /* solution process that are relevant to correct and efficient use */
909 /* of this routine in user applications. */
910
911
912 /* The Search Process */
913 /* ================== */
914
915 /* The search for visibility events is treated as a search for state */
916 /* transitions: times are sought when the state of the target ray or */
917 /* body changes from "not visible" to "visible" or vice versa. */
918
919 /* Step Size */
920 /* ========= */
921
922 /* Each interval of the confinement window is searched as follows: */
923 /* first, the input step size is used to determine the time */
924 /* separation at which the visibility state will be sampled. */
925 /* Starting at the left endpoint of an interval, samples will be */
926 /* taken at each step. If a state change is detected, a root has */
927 /* been bracketed; at that point, the "root"--the time at which the */
928 /* state change occurs---is found by a refinement process, for */
929 /* example, via binary search. */
930
931 /* Note that the optimal choice of step size depends on the lengths */
932 /* of the intervals over which the visibility state is constant: */
933 /* the step size should be shorter than the shortest visibility event */
934 /* duration and the shortest period between visibility events, within */
935 /* the confinement window. */
936
937 /* Having some knowledge of the relative geometry of the target and */
938 /* observer can be a valuable aid in picking a reasonable step size. */
939 /* In general, the user can compensate for lack of such knowledge by */
940 /* picking a very short step size; the cost is increased computation */
941 /* time. */
942
943 /* Note that the step size is not related to the precision with which */
944 /* the endpoints of the intervals of the result window are computed. */
945 /* That precision level is controlled by the convergence tolerance. */
946
947
948 /* Convergence Tolerance */
949 /* ===================== */
950
951 /* The times of state transitions are called ``roots.'' */
952
953 /* Once a root has been bracketed, a refinement process is used to */
954 /* narrow down the time interval within which the root must lie. */
955 /* This refinement process terminates when the location of the root */
956 /* has been determined to within an error margin called the */
957 /* "convergence tolerance." */
958
959 /* The convergence tolerance used by high-level GF routines that */
960 /* call this routine is set via the parameter CNVTOL, which is */
961 /* declared in the INCLUDE file gf.inc. The value of CNVTOL is set */
962 /* to a "tight" value so that the tolerance doesn't become the */
963 /* limiting factor in the accuracy of solutions found by this */
964 /* routine. In general the accuracy of input data will be the */
965 /* limiting factor. */
966
967 /* Setting the input tolerance TOL tighter than CNVTOL is unlikely */
968 /* to be useful, since the results are unlikely to be more accurate. */
969 /* Making the tolerance looser will speed up searches somewhat, */
970 /* since a few convergence steps will be omitted. However, in most */
971 /* cases, the step size is likely to have a much greater effect on */
972 /* processing time than would the convergence tolerance. */
973
974
975 /* The Confinement Window */
976 /* ====================== */
977
978 /* The simplest use of the confinement window is to specify a time */
979 /* interval within which a solution is sought. However, the */
980 /* confinement window can, in some cases, be used to make searches */
981 /* more efficient. Sometimes it's possible to do an efficient search */
982 /* to reduce the size of the time period over which a relatively */
983 /* slow search of interest must be performed. For an example, see */
984 /* the program CASCADE in the GF Example Programs chapter of the GF */
985 /* Required Reading, gf.req. */
986
987 /* $ Examples */
988
989
990 /* The numerical results shown for these examples may differ across */
991 /* platforms. The results depend on the SPICE kernels used as */
992 /* input, the compiler and supporting libraries, and the machine */
993 /* specific arithmetic implementation. */
994
995
996 /* 1) Search for times when Saturn's satellite Phoebe is within */
997 /* the FOV of the Cassini narrow angle camera (CASSINI_ISS_NAC). */
998 /* To simplify the problem, restrict the search to a short time */
999 /* period where continuous Cassini bus attitude data are */
1000 /* available. */
1001
1002 /* Use default SPICELIB progress reporting. */
1003
1004 /* Use a step size of 1 second to reduce chances of missing */
1005 /* short visibility events and to make the search slow enough */
1006 /* so the progress report's updates are visible. */
1007
1008 /* Use the meta-kernel shown below to load the required SPICE */
1009 /* kernels. */
1010
1011
1012 /* KPL/MK */
1013
1014 /* File name: gftfov_ex1.tm */
1015
1016 /* This meta-kernel is intended to support operation of SPICE */
1017 /* example programs. The kernels shown here should not be */
1018 /* assumed to contain adequate or correct versions of data */
1019 /* required by SPICE-based user applications. */
1020
1021 /* In order for an application to use this meta-kernel, the */
1022 /* kernels referenced here must be present in the user's */
1023 /* current working directory. */
1024
1025 /* The names and contents of the kernels referenced */
1026 /* by this meta-kernel are as follows: */
1027
1028 /* File name Contents */
1029 /* --------- -------- */
1030 /* naif0009.tls Leapseconds */
1031 /* cpck05Mar2004.tpc Satellite orientation and */
1032 /* radii */
1033 /* 981005_PLTEPH-DE405S.bsp Planetary ephemeris */
1034 /* 020514_SE_SAT105.bsp Satellite ephemeris */
1035 /* 030201AP_SK_SM546_T45.bsp Spacecraft ephemeris */
1036 /* cas_v37.tf Cassini FK */
1037 /* 04135_04171pc_psiv2.bc Cassini bus CK */
1038 /* cas00084.tsc Cassini SCLK kernel */
1039 /* cas_iss_v09.ti Cassini IK */
1040
1041
1042 /* \begindata */
1043
1044 /* KERNELS_TO_LOAD = ( 'naif0009.tls', */
1045 /* 'cpck05Mar2004.tpc', */
1046 /* '981005_PLTEPH-DE405S.bsp', */
1047 /* '020514_SE_SAT105.bsp', */
1048 /* '030201AP_SK_SM546_T45.bsp', */
1049 /* 'cas_v37.tf', */
1050 /* '04135_04171pc_psiv2.bc', */
1051 /* 'cas00084.tsc', */
1052 /* 'cas_iss_v09.ti' ) */
1053 /* \begintext */
1054
1055
1056
1057 /* Example code begins here. */
1058
1059
1060 /* PROGRAM EX1 */
1061 /* IMPLICIT NONE */
1062 /* C */
1063 /* C SPICELIB functions */
1064 /* C */
1065 /* INTEGER WNCARD */
1066
1067 /* C */
1068 /* C SPICELIB default functions for */
1069 /* C */
1070 /* C - Interrupt handling (no-op function): GFBAIL */
1071 /* C - Search refinement: GFREFN */
1072 /* C - Progress report termination: GFREPF */
1073 /* C - Progress report initialization: GFREPI */
1074 /* C - Progress report update: GFREPU */
1075 /* C - Search step size "get" function: GFSTEP */
1076 /* C */
1077 /* EXTERNAL GFBAIL */
1078 /* EXTERNAL GFREFN */
1079 /* EXTERNAL GFREPF */
1080 /* EXTERNAL GFREPI */
1081 /* EXTERNAL GFREPU */
1082 /* EXTERNAL GFSTEP */
1083
1084 /* C */
1085 /* C Local parameters */
1086 /* C */
1087 /* CHARACTER*(*) META */
1088 /* PARAMETER ( META = 'gftfov_ex1.tm' ) */
1089
1090 /* CHARACTER*(*) TIMFMT */
1091 /* PARAMETER ( TIMFMT = */
1092 /* . 'YYYY-MON-DD HR:MN:SC.######::TDB (TDB)' ) */
1093
1094 /* INTEGER LBCELL */
1095 /* PARAMETER ( LBCELL = -5 ) */
1096
1097 /* INTEGER MAXWIN */
1098 /* PARAMETER ( MAXWIN = 10000 ) */
1099
1100 /* INTEGER CORLEN */
1101 /* PARAMETER ( CORLEN = 10 ) */
1102
1103 /* INTEGER BDNMLN */
1104 /* PARAMETER ( BDNMLN = 36 ) */
1105
1106 /* INTEGER FRNMLN */
1107 /* PARAMETER ( FRNMLN = 32 ) */
1108
1109 /* INTEGER SHPLEN */
1110 /* PARAMETER ( SHPLEN = 25 ) */
1111
1112 /* INTEGER TIMLEN */
1113 /* PARAMETER ( TIMLEN = 35 ) */
1114
1115 /* INTEGER LNSIZE */
1116 /* PARAMETER ( LNSIZE = 80 ) */
1117
1118 /* C */
1119 /* C Local variables */
1120 /* C */
1121 /* CHARACTER*(CORLEN) ABCORR */
1122 /* CHARACTER*(BDNMLN) INST */
1123 /* CHARACTER*(LNSIZE) LINE */
1124 /* CHARACTER*(BDNMLN) OBSRVR */
1125 /* CHARACTER*(BDNMLN) TARGET */
1126 /* CHARACTER*(FRNMLN) TFRAME */
1127 /* CHARACTER*(TIMLEN) TIMSTR ( 2 ) */
1128 /* CHARACTER*(SHPLEN) TSHAPE */
1129
1130 /* DOUBLE PRECISION CNFINE ( LBCELL : MAXWIN ) */
1131 /* DOUBLE PRECISION ENDPT ( 2 ) */
1132 /* DOUBLE PRECISION ET0 */
1133 /* DOUBLE PRECISION ET1 */
1134 /* DOUBLE PRECISION RAYDIR ( 3 ) */
1135 /* DOUBLE PRECISION RESULT ( LBCELL : MAXWIN ) */
1136 /* DOUBLE PRECISION TOL */
1137
1138 /* INTEGER I */
1139 /* INTEGER J */
1140 /* INTEGER N */
1141
1142 /* LOGICAL BAIL */
1143 /* LOGICAL RPT */
1144
1145 /* C */
1146 /* C Since we're treating the target as an ephemeris object, */
1147 /* C the ray direction is unused. We simply initialize the */
1148 /* C direction vector to avoid portability problems. */
1149 /* C */
1150 /* DATA RAYDIR / 3*0.D0 / */
1151
1152 /* C */
1153 /* C Load kernels. */
1154 /* C */
1155 /* CALL FURNSH ( META ) */
1156
1157 /* C */
1158 /* C Initialize windows. */
1159 /* C */
1160 /* CALL SSIZED ( MAXWIN, CNFINE ) */
1161 /* CALL SSIZED ( MAXWIN, RESULT ) */
1162
1163 /* C */
1164 /* C Insert search time interval bounds into the */
1165 /* C confinement window. */
1166 /* C */
1167 /* CALL STR2ET ( '2004 JUN 11 06:30:00 TDB', ET0 ) */
1168 /* CALL STR2ET ( '2004 JUN 11 12:00:00 TDB', ET1 ) */
1169
1170 /* CALL WNINSD ( ET0, ET1, CNFINE ) */
1171
1172 /* C */
1173 /* C Initialize inputs for the search. */
1174 /* C */
1175 /* INST = 'CASSINI_ISS_NAC' */
1176 /* TARGET = 'PHOEBE' */
1177 /* TSHAPE = 'ELLIPSOID' */
1178 /* TFRAME = 'IAU_PHOEBE' */
1179 /* ABCORR = 'LT+S' */
1180 /* OBSRVR = 'CASSINI' */
1181
1182 /* C */
1183 /* C Use a particularly short step size to make the progress */
1184 /* C report's updates visible. */
1185 /* C */
1186 /* C Pass the step size (1 second) to the GF default step size */
1187 /* C put/get system. */
1188 /* C */
1189 /* CALL GFSSTP ( 1.D0 ) */
1190
1191 /* C */
1192 /* C Set the convergence tolerance to 1 microsecond. */
1193 /* C */
1194 /* TOL = 1.D-6 */
1195
1196 /* C */
1197 /* C Use progress reporting; turn off interrupt handling. */
1198 /* C */
1199 /* RPT = .TRUE. */
1200 /* BAIL = .FALSE. */
1201
1202 /* WRITE (*,*) ' ' */
1203 /* WRITE (*, '(A)' ) 'Instrument: '//INST */
1204 /* WRITE (*, '(A)' ) 'Target: '//TARGET */
1205
1206 /* C */
1207 /* C Perform the search. */
1208 /* C */
1209 /* CALL GFFOVE ( INST, TSHAPE, RAYDIR, */
1210 /* . TARGET, TFRAME, ABCORR, OBSRVR, TOL, */
1211 /* . GFSTEP, GFREFN, RPT, GFREPI, GFREPU, */
1212 /* . GFREPF, BAIL, GFBAIL, CNFINE, RESULT ) */
1213
1214 /* N = WNCARD( RESULT ) */
1215
1216 /* IF ( N .EQ. 0 ) THEN */
1217
1218 /* WRITE (*, '(A)' ) 'No FOV intersection found.' */
1219
1220 /* ELSE */
1221
1222 /* WRITE (*, '(A)' ) */
1223 /* . ' Visibility start time Stop time' */
1224
1225 /* DO I = 1, N */
1226
1227 /* CALL WNFETD ( RESULT, I, ENDPT(1), ENDPT(2) ) */
1228
1229 /* DO J = 1, 2 */
1230 /* CALL TIMOUT ( ENDPT(J), TIMFMT, TIMSTR(J) ) */
1231 /* END DO */
1232
1233 /* LINE( :3) = ' ' */
1234 /* LINE(2: ) = TIMSTR(1) */
1235 /* LINE(37:) = TIMSTR(2) */
1236
1237 /* WRITE (*,*) LINE */
1238
1239 /* END DO */
1240
1241 /* END IF */
1242
1243 /* WRITE (*,*) ' ' */
1244 /* END */
1245
1246
1247 /* When this program was executed on a PC/Linux/g77 platform, the */
1248 /* final output (the progress report is overwritten when it is */
1249 /* updated, so only the final update is captured here) was: */
1250
1251
1252 /* Instrument: CASSINI_ISS_NAC */
1253 /* Target: PHOEBE */
1254
1255
1256 /* Target visibility search 100.00% done. */
1257
1258 /* Visibility start time Stop time */
1259 /* 2004-JUN-11 07:35:49.958590 (TDB) 2004-JUN-11 08:48:27.485965 (TDB) */
1260 /* 2004-JUN-11 09:03:19.767799 (TDB) 2004-JUN-11 09:35:27.634790 (TDB) */
1261 /* 2004-JUN-11 09:50:19.585474 (TDB) 2004-JUN-11 10:22:27.854254 (TDB) */
1262 /* 2004-JUN-11 10:37:19.332696 (TDB) 2004-JUN-11 11:09:28.116016 (TDB) */
1263 /* 2004-JUN-11 11:24:19.049484 (TDB) 2004-JUN-11 11:56:28.380304 (TDB) */
1264
1265
1266 /* 2) A variation of example (1): search the same confinement */
1267 /* window for times when a selected background star is visible. */
1268 /* We use the FOV of the Cassini ISS wide angle camera */
1269 /* (CASSINI_ISS_WAC) to enhance the probability of viewing the */
1270 /* star. */
1271
1272 /* The star we'll use has catalog number 6000 in the Hipparcos */
1273 /* Catalog. The star's J2000 right ascension and declination, */
1274 /* proper motion, and parallax are taken from that catalog. */
1275
1276 /* Use the meta-kernel from the first example. */
1277
1278 /* Example code begins here. */
1279
1280
1281 /* PROGRAM EX2 */
1282 /* IMPLICIT NONE */
1283 /* C */
1284 /* C SPICELIB functions */
1285 /* C */
1286 /* DOUBLE PRECISION J1950 */
1287 /* DOUBLE PRECISION J2000 */
1288 /* DOUBLE PRECISION JYEAR */
1289 /* DOUBLE PRECISION RPD */
1290
1291 /* INTEGER WNCARD */
1292
1293 /* C SPICELIB default functions for */
1294 /* C */
1295 /* C - Interrupt handling (no-op function): GFBAIL */
1296 /* C - Search refinement: GFREFN */
1297 /* C - Progress report termination: GFREPF */
1298 /* C - Progress report initialization: GFREPI */
1299 /* C - Progress report update: GFREPU */
1300 /* C - Search step size "get" function: GFSTEP */
1301 /* C */
1302 /* EXTERNAL GFBAIL */
1303 /* EXTERNAL GFREFN */
1304 /* EXTERNAL GFREPF */
1305 /* EXTERNAL GFREPI */
1306 /* EXTERNAL GFREPU */
1307 /* EXTERNAL GFSTEP */
1308
1309 /* C */
1310 /* C Local parameters */
1311 /* C */
1312 /* CHARACTER*(*) META */
1313 /* PARAMETER ( META = 'gftfov_ex1.tm' ) */
1314
1315 /* CHARACTER*(*) TIMFMT */
1316 /* PARAMETER ( TIMFMT = */
1317 /* . 'YYYY-MON-DD HR:MN:SC.######::TDB (TDB)' ) */
1318
1319
1320 /* DOUBLE PRECISION AU */
1321 /* PARAMETER ( AU = 149597870.693D0 ) */
1322
1323 /* INTEGER LBCELL */
1324 /* PARAMETER ( LBCELL = -5 ) */
1325
1326 /* INTEGER MAXWIN */
1327 /* PARAMETER ( MAXWIN = 10000 ) */
1328
1329 /* INTEGER CORLEN */
1330 /* PARAMETER ( CORLEN = 10 ) */
1331
1332 /* INTEGER BDNMLN */
1333 /* PARAMETER ( BDNMLN = 36 ) */
1334
1335 /* INTEGER FRNMLN */
1336 /* PARAMETER ( FRNMLN = 32 ) */
1337
1338 /* INTEGER SHPLEN */
1339 /* PARAMETER ( SHPLEN = 25 ) */
1340
1341 /* INTEGER TIMLEN */
1342 /* PARAMETER ( TIMLEN = 35 ) */
1343
1344 /* INTEGER LNSIZE */
1345 /* PARAMETER ( LNSIZE = 80 ) */
1346
1347 /* C */
1348 /* C Local variables */
1349 /* C */
1350 /* CHARACTER*(CORLEN) ABCORR */
1351 /* CHARACTER*(BDNMLN) INST */
1352 /* CHARACTER*(LNSIZE) LINE */
1353 /* CHARACTER*(BDNMLN) OBSRVR */
1354 /* CHARACTER*(FRNMLN) RFRAME */
1355 /* CHARACTER*(BDNMLN) TARGET */
1356 /* CHARACTER*(TIMLEN) TIMSTR ( 2 ) */
1357 /* CHARACTER*(SHPLEN) TSHAPE */
1358
1359 /* DOUBLE PRECISION CNFINE ( LBCELL : MAXWIN ) */
1360 /* DOUBLE PRECISION DEC */
1361 /* DOUBLE PRECISION DECEPC */
1362 /* DOUBLE PRECISION DECPM */
1363 /* DOUBLE PRECISION DECDEG */
1364 /* DOUBLE PRECISION DECDG0 */
1365 /* DOUBLE PRECISION DTDEC */
1366 /* DOUBLE PRECISION DTRA */
1367 /* DOUBLE PRECISION ENDPT ( 2 ) */
1368 /* DOUBLE PRECISION ET0 */
1369 /* DOUBLE PRECISION ET1 */
1370 /* DOUBLE PRECISION LT */
1371 /* DOUBLE PRECISION PARLAX */
1372 /* DOUBLE PRECISION PLXDEG */
1373 /* DOUBLE PRECISION POS ( 3 ) */
1374 /* DOUBLE PRECISION PSTAR ( 3 ) */
1375 /* DOUBLE PRECISION RA */
1376 /* DOUBLE PRECISION RADEG */
1377 /* DOUBLE PRECISION RADEG0 */
1378 /* DOUBLE PRECISION RAEPC */
1379 /* DOUBLE PRECISION RAPM */
1380 /* DOUBLE PRECISION RAYDIR ( 3 ) */
1381 /* DOUBLE PRECISION RESULT ( LBCELL : MAXWIN ) */
1382 /* DOUBLE PRECISION RSTAR */
1383 /* DOUBLE PRECISION T */
1384 /* DOUBLE PRECISION TOL */
1385
1386 /* INTEGER CATNO */
1387 /* INTEGER I */
1388 /* INTEGER J */
1389 /* INTEGER N */
1390
1391 /* LOGICAL BAIL */
1392 /* LOGICAL RPT */
1393
1394 /* C */
1395 /* C Load kernels. */
1396 /* C */
1397 /* CALL FURNSH ( META ) */
1398
1399 /* C */
1400 /* C Initialize windows. */
1401 /* C */
1402 /* CALL SSIZED ( MAXWIN, CNFINE ) */
1403 /* CALL SSIZED ( MAXWIN, RESULT ) */
1404
1405 /* C */
1406 /* C Insert search time interval bounds into the */
1407 /* C confinement window. */
1408 /* C */
1409 /* CALL STR2ET ( '2004 JUN 11 06:30:00 TDB', ET0 ) */
1410 /* CALL STR2ET ( '2004 JUN 11 12:00:00 TDB', ET1 ) */
1411
1412 /* CALL WNINSD ( ET0, ET1, CNFINE ) */
1413
1414 /* C */
1415 /* C Initialize inputs for the search. */
1416 /* C */
1417 /* INST = 'CASSINI_ISS_WAC' */
1418 /* TARGET = ' ' */
1419 /* TSHAPE = 'RAY' */
1420
1421 /* C */
1422 /* C Create a unit direction vector pointing from */
1423 /* C observer to star. We'll assume the direction */
1424 /* C is constant during the confinement window, and */
1425 /* C we'll use et0 as the epoch at which to compute the */
1426 /* C direction from the spacecraft to the star. */
1427 /* C */
1428 /* C The data below are for the star with catalog */
1429 /* C number 6000 in the Hipparcos catalog. Angular */
1430 /* C units are degrees; epochs have units of Julian */
1431 /* C years and have a reference epoch of J1950. */
1432 /* C The reference frame is J2000. */
1433 /* C */
1434 /* CATNO = 6000 */
1435
1436 /* PLXDEG = 0.000001056D0 */
1437
1438 /* RADEG0 = 19.290789927D0 */
1439 /* RAPM = -0.000000720D0 */
1440 /* RAEPC = 41.2000D0 */
1441
1442 /* DECDG0 = 2.015271007D0 */
1443 /* DECPM = 0.000001814D0 */
1444 /* DECEPC = 41.1300D0 */
1445
1446 /* RFRAME = 'J2000' */
1447
1448 /* C */
1449 /* C Correct the star's direction for proper motion. */
1450 /* C */
1451 /* C The argument t represents et0 as Julian years */
1452 /* C past J1950. */
1453 /* C */
1454 /* T = ET0/JYEAR() */
1455 /* . + ( J2000()- J1950() ) / 365.25D0 */
1456
1457 /* DTRA = T - RAEPC */
1458 /* DTDEC = T - DECEPC */
1459
1460 /* RADEG = RADEG0 + DTRA * RAPM */
1461 /* DECDEG = DECDG0 + DTDEC * DECPM */
1462
1463 /* RA = RADEG * RPD() */
1464 /* DEC = DECDEG * RPD() */
1465
1466 /* CALL RADREC ( 1.D0, RA, DEC, PSTAR ) */
1467
1468 /* C */
1469 /* C Correct star position for parallax applicable at */
1470 /* C the Cassini orbiter's position. (The parallax effect */
1471 /* C is negligible in this case; we're simply demonstrating */
1472 /* C the computation.) */
1473 /* C */
1474 /* PARLAX = PLXDEG * RPD() */
1475 /* RSTAR = AU / TAN(PARLAX) */
1476
1477 /* C */
1478 /* C Scale the star's direction vector by its distance from */
1479 /* C the solar system barycenter. Subtract off the position */
1480 /* C of the spacecraft relative to the solar system barycenter; */
1481 /* C the result is the ray's direction vector. */
1482 /* C */
1483 /* CALL VSCLIP ( RSTAR, PSTAR ) */
1484
1485 /* CALL SPKPOS ( 'CASSINI', ET0, 'J2000', 'NONE', */
1486 /* . 'SOLAR SYSTEM BARYCENTER', POS, LT ) */
1487
1488 /* CALL VSUB ( PSTAR, POS, RAYDIR ) */
1489
1490 /* C */
1491 /* C Correct the star direction for stellar aberration when */
1492 /* C we conduct the search. */
1493 /* C */
1494 /* ABCORR = 'S' */
1495 /* OBSRVR = 'CASSINI' */
1496
1497 /* C */
1498 /* C Use a particularly short step size to make the progress */
1499 /* C report's updates visible. */
1500 /* C */
1501 /* C Pass the step size (1 second) to the GF default step size */
1502 /* C put/get system. */
1503 /* C */
1504 /* CALL GFSSTP ( 1.D0 ) */
1505
1506 /* C */
1507 /* C Set the convergence tolerance to 1 microsecond. */
1508 /* C */
1509 /* TOL = 1.D-6 */
1510
1511 /* C */
1512 /* C Use progress reporting; turn off interrupt handling. */
1513 /* C */
1514 /* RPT = .TRUE. */
1515 /* BAIL = .FALSE. */
1516
1517
1518 /* WRITE (*,*) ' ' */
1519 /* WRITE (*,*) 'Instrument: '//INST */
1520 /* WRITE (*,*) 'Star''s catalog number: ', CATNO */
1521
1522 /* C */
1523 /* C Perform the search. */
1524 /* C */
1525 /* CALL GFFOVE ( INST, TSHAPE, RAYDIR, */
1526 /* . TARGET, RFRAME, ABCORR, OBSRVR, TOL, */
1527 /* . GFSTEP, GFREFN, RPT, GFREPI, GFREPU, */
1528 /* . GFREPF, BAIL, GFBAIL, CNFINE, RESULT ) */
1529
1530 /* N = WNCARD( RESULT ) */
1531
1532 /* IF ( N .EQ. 0 ) THEN */
1533
1534 /* WRITE (*,*) 'No FOV intersection found.' */
1535
1536 /* ELSE */
1537
1538 /* WRITE (*,*) */
1539 /* . ' Visibility start time Stop time' */
1540
1541 /* DO I = 1, N */
1542
1543 /* CALL WNFETD ( RESULT, I, ENDPT(1), ENDPT(2) ) */
1544
1545 /* DO J = 1, 2 */
1546 /* CALL TIMOUT ( ENDPT(J), TIMFMT, TIMSTR(J) ) */
1547 /* END DO */
1548
1549 /* LINE( :3) = ' ' */
1550 /* LINE(2: ) = TIMSTR(1) */
1551 /* LINE(37:) = TIMSTR(2) */
1552
1553 /* WRITE (*,*) LINE */
1554
1555 /* END DO */
1556
1557 /* END IF */
1558
1559 /* WRITE (*,*) ' ' */
1560 /* END */
1561
1562
1563 /* When this program was executed on a PC/Linux/g77 platform, the */
1564 /* output was: */
1565
1566
1567 /* Instrument: CASSINI_ISS_WAC */
1568 /* Star's catalog number: 6000 */
1569
1570 /* Target visibility search 100.00% done. */
1571
1572 /* Visibility start time Stop time */
1573 /* 2004-JUN-11 06:30:00.000000 (TDB) 2004-JUN-11 12:00:00.000000 (TDB) */
1574
1575
1576
1577 /* $ Restrictions */
1578
1579 /* The kernel files to be used by GFFOVE must be loaded (normally via */
1580 /* the SPICELIB routine FURNSH) before GFFOVE is called. */
1581
1582 /* $ Literature_References */
1583
1584 /* None. */
1585
1586 /* $ Author_and_Institution */
1587
1588 /* N.J. Bachman (JPL) */
1589 /* L.S. Elson (JPL) */
1590 /* E.D. Wright (JPL) */
1591
1592 /* $ Version */
1593
1594 /* - SPICELIB Version 1.0.1 17-JAN-2017 (NJB) (JDR) */
1595
1596 /* Fixed typo in second example program: initial letter */
1597 /* "C" indicating a comment line was in lower case. */
1598
1599 /* - SPICELIB Version 1.0.0 15-APR-2009 (NJB) (LSE) (EDW) */
1600
1601 /* -& */
1602 /* $ Index_Entries */
1603
1604 /* GF mid-level target in instrument FOV search */
1605
1606 /* -& */
1607 /* $ Revisions */
1608
1609 /* None. */
1610
1611 /* -& */
1612
1613 /* SPICELIB functions */
1614
1615
1616 /* External routines */
1617
1618
1619 /* Local parameters */
1620
1621
1622 /* STEP is a step size initializer for the unused, dummy step size */
1623 /* argument to ZZGFSOLV. The routine UDSTEP, which is passed to */
1624 /* ZZGFSOLV, will be used by that routine to obtain the step size. */
1625
1626
1627 /* CSTEP indicates whether a constant step size, provided */
1628 /* via the input argument STEP, is to be used by ZZGFSOLV. */
1629
1630
1631 /* Local variables */
1632
1633
1634 /* Standard SPICE error handling. */
1635
1636 if (return_()) {
1637 return 0;
1638 }
1639 chkin_("GFFOVE", (ftnlen)6);
1640
1641 /* Check the result window's size. */
1642
1643 if (sized_(result) < 2) {
1644 setmsg_("Result window size must be at least 2 but was #.", (ftnlen)
1645 48);
1646 i__1 = sized_(result);
1647 errint_("#", &i__1, (ftnlen)1);
1648 sigerr_("SPICE(WINDOWTOOSMALL)", (ftnlen)21);
1649 chkout_("GFFOVE", (ftnlen)6);
1650 return 0;
1651 }
1652
1653 /* Empty the RESULT window. */
1654
1655 scardd_(&c__0, result);
1656
1657 /* Check the convergence tolerance. */
1658
1659 if (*tol <= 0.) {
1660 setmsg_("Tolerance must be positive but was #.", (ftnlen)37);
1661 errdp_("#", tol, (ftnlen)1);
1662 sigerr_("SPICE(INVALIDTOLERANCE)", (ftnlen)23);
1663 chkout_("GFFOVE", (ftnlen)6);
1664 return 0;
1665 }
1666
1667 /* Note to maintenance programmer: most input exception checks are */
1668 /* delegated to ZZGFFVIN. If the implementation of that routine */
1669 /* changes, or if this routine is modified to call a different */
1670 /* routine in place of ZZGFFVIN, then the error handling performed */
1671 /* by ZZGFFVIN will have to be performed here or in a routine called */
1672 /* by this routine. */
1673
1674
1675 /* Initialize the visibility calculation. */
1676
1677 zzgffvin_(inst, tshape, raydir, target, tframe, abcorr, obsrvr, inst_len,
1678 tshape_len, target_len, tframe_len, abcorr_len, obsrvr_len);
1679 if (failed_()) {
1680 chkout_("GFFOVE", (ftnlen)6);
1681 return 0;
1682 }
1683
1684 /* Prepare the progress reporter if appropriate. */
1685
1686 if (*rpt) {
1687 (*udrepi)(cnfine, "Target visibility search ", "done.", (ftnlen)25, (
1688 ftnlen)5);
1689 }
1690
1691 /* Cycle over the intervals in the confinement window. */
1692
1693 count = wncard_(cnfine);
1694 i__1 = count;
1695 for (i__ = 1; i__ <= i__1; ++i__) {
1696
1697 /* Retrieve the bounds for the Ith interval of the confinement */
1698 /* window. Search this interval for visibility events. Union the */
1699 /* result with the contents of the RESULT window. */
1700
1701 wnfetd_(cnfine, &i__, &start, &finish);
1702 zzgfsolv_((U_fp)zzgffvst_, (U_fp)udstep, (U_fp)udrefn, bail, (L_fp)
1703 udbail, &c_false, &c_b16, &start, &finish, tol, rpt, (U_fp)
1704 udrepu, result);
1705 if (failed_()) {
1706 chkout_("GFFOVE", (ftnlen)6);
1707 return 0;
1708 }
1709 if (*bail) {
1710
1711 /* Interrupt handling is enabled. */
1712
1713 if ((*udbail)()) {
1714
1715 /* An interrupt has been issued. Return now regardless of */
1716 /* whether the search has been completed. */
1717
1718 chkout_("GFFOVE", (ftnlen)6);
1719 return 0;
1720 }
1721 }
1722 }
1723
1724 /* End the progress report. */
1725
1726 if (*rpt) {
1727 (*udrepf)();
1728 }
1729 chkout_("GFFOVE", (ftnlen)6);
1730 return 0;
1731 } /* gffove_ */
1732
1733