1 /* 2 3 -Procedure ilumin_c ( Illumination angles ) 4 5 -Abstract 6 7 Find the illumination angles (phase, solar incidence, and 8 emission) at a specified surface point of a target body. 9 10 This routine supersedes illum_c. 11 12 -Disclaimer 13 14 THIS SOFTWARE AND ANY RELATED MATERIALS WERE CREATED BY THE 15 CALIFORNIA INSTITUTE OF TECHNOLOGY (CALTECH) UNDER A U.S. 16 GOVERNMENT CONTRACT WITH THE NATIONAL AERONAUTICS AND SPACE 17 ADMINISTRATION (NASA). THE SOFTWARE IS TECHNOLOGY AND SOFTWARE 18 PUBLICLY AVAILABLE UNDER U.S. EXPORT LAWS AND IS PROVIDED "AS-IS" 19 TO THE RECIPIENT WITHOUT WARRANTY OF ANY KIND, INCLUDING ANY 20 WARRANTIES OF PERFORMANCE OR MERCHANTABILITY OR FITNESS FOR A 21 PARTICULAR USE OR PURPOSE (AS SET FORTH IN UNITED STATES UCC 22 SECTIONS 2312-2313) OR FOR ANY PURPOSE WHATSOEVER, FOR THE 23 SOFTWARE AND RELATED MATERIALS, HOWEVER USED. 24 25 IN NO EVENT SHALL CALTECH, ITS JET PROPULSION LABORATORY, OR NASA 26 BE LIABLE FOR ANY DAMAGES AND/OR COSTS, INCLUDING, BUT NOT 27 LIMITED TO, INCIDENTAL OR CONSEQUENTIAL DAMAGES OF ANY KIND, 28 INCLUDING ECONOMIC DAMAGE OR INJURY TO PROPERTY AND LOST PROFITS, 29 REGARDLESS OF WHETHER CALTECH, JPL, OR NASA BE ADVISED, HAVE 30 REASON TO KNOW, OR, IN FACT, SHALL KNOW OF THE POSSIBILITY. 31 32 RECIPIENT BEARS ALL RISK RELATING TO QUALITY AND PERFORMANCE OF 33 THE SOFTWARE AND ANY RELATED MATERIALS, AND AGREES TO INDEMNIFY 34 CALTECH AND NASA FOR ALL THIRD-PARTY CLAIMS RESULTING FROM THE 35 ACTIONS OF RECIPIENT IN THE USE OF THE SOFTWARE. 36 37 -Required_Reading 38 39 DSK 40 FRAMES 41 NAIF_IDS 42 PCK 43 SPK 44 TIME 45 46 -Keywords 47 48 ANGLES 49 GEOMETRY 50 ILLUMINATION 51 52 */ 53 54 #include "SpiceUsr.h" 55 #include "SpiceZfc.h" 56 #include "SpiceZmc.h" 57 #undef ilumin_c 58 59 ilumin_c(ConstSpiceChar * method,ConstSpiceChar * target,SpiceDouble et,ConstSpiceChar * fixref,ConstSpiceChar * abcorr,ConstSpiceChar * obsrvr,ConstSpiceDouble spoint[3],SpiceDouble * trgepc,SpiceDouble srfvec[3],SpiceDouble * phase,SpiceDouble * incdnc,SpiceDouble * emissn)60 void ilumin_c ( ConstSpiceChar * method, 61 ConstSpiceChar * target, 62 SpiceDouble et, 63 ConstSpiceChar * fixref, 64 ConstSpiceChar * abcorr, 65 ConstSpiceChar * obsrvr, 66 ConstSpiceDouble spoint [3], 67 SpiceDouble * trgepc, 68 SpiceDouble srfvec [3], 69 SpiceDouble * phase, 70 SpiceDouble * incdnc, 71 SpiceDouble * emissn ) 72 /* 73 74 -Brief_I/O 75 76 Variable I/O Description 77 -------- --- -------------------------------------------------- 78 method I Computation method. 79 target I Name of target body. 80 et I Epoch in TDB seconds past J2000 TDB. 81 fixref I Body-fixed, body-centered target body frame. 82 abcorr I Aberration correction flag. 83 obsrvr I Name of observing body. 84 spoint I Body-fixed coordinates of a target surface point. 85 trgepc O Target surface point epoch. 86 srfvec O Vector from observer to target surface point. 87 phase O Phase angle at the surface point. 88 incdnc O Solar incidence angle at the surface point. 89 emissn O Emission angle at the surface point. 90 91 -Detailed_Input 92 93 method is a short string providing parameters defining 94 the computation method to be used. In the syntax 95 descriptions below, items delimited by brackets 96 are optional. 97 98 `method' may be assigned the following values: 99 100 "ELLIPSOID" 101 102 The illumination angle computation uses a 103 triaxial ellipsoid to model the surface of the 104 target body. The ellipsoid's radii must be 105 available in the kernel pool. 106 107 108 "DSK/UNPRIORITIZED[/SURFACES = <surface list>]" 109 110 The illumination angle computation uses 111 topographic data to model the surface of the 112 target body. These data must be provided by 113 loaded DSK files. 114 115 The surface list specification is optional. The 116 syntax of the list is 117 118 <surface 1> [, <surface 2>...] 119 120 If present, it indicates that data only for the 121 listed surfaces are to be used; however, data 122 need not be available for all surfaces in the 123 list. If absent, loaded DSK data for any surface 124 associated with the target body are used. 125 126 The surface list may contain surface names or 127 surface ID codes. Names containing blanks must 128 be delimited by escaped double quotes, for example 129 130 "SURFACES = \"Mars MEGDR 128 PIXEL/DEG\"" 131 132 If multiple surfaces are specified, their names 133 or IDs must be separated by commas. 134 135 See the Particulars section below for details 136 concerning use of DSK data. 137 138 139 Neither case nor white space are significant in 140 `method', except within double-quoted strings 141 representing surface names. For example, the string 142 " eLLipsoid " is valid. 143 144 Within double-quoted strings representing surface names, 145 blank characters are significant, but multiple 146 consecutive blanks are considered equivalent to a single 147 blank. Case is not significant. So 148 149 \"Mars MEGDR 128 PIXEL/DEG\" 150 151 is equivalent to 152 153 \" mars megdr 128 pixel/deg \" 154 155 but not to 156 157 \"MARS MEGDR128PIXEL/DEG\" 158 159 160 target is the name of the target body. `target' is 161 case-insensitive, and leading and trailing blanks in 162 `target' are not significant. Optionally, you may 163 supply a string containing the integer ID code for 164 the object. For example both "MOON" and "301" are 165 legitimate strings that indicate the moon is the 166 target body. 167 168 169 et is the epoch, expressed as seconds past J2000 TDB, 170 for which the apparent illumination angles at the 171 specified surface point on the target body, as seen 172 from the observing body, are to be computed. 173 174 175 fixref is the name of the body-fixed, body-centered 176 reference frame associated with the target body. The 177 input surface point `spoint' and the output vector 178 `srfvec' are expressed relative to this reference 179 frame. The string `fixref' is case-insensitive, and 180 leading and trailing blanks in `fixref' are not 181 significant. 182 183 184 abcorr is the aberration correction to be used in computing 185 the position and orientation of the target body and 186 the location of the sun. 187 188 For remote sensing applications, where the apparent 189 illumination angles seen by the observer are desired, 190 normally either of the corrections 191 192 "LT+S" 193 "CN+S" 194 195 should be used. These and the other supported options 196 are described below. `abcorr' may be any of the 197 following: 198 199 "NONE" No aberration correction. 200 201 Let `lt' represent the one-way light time between the 202 observer and the input surface point `spoint' (note: NOT 203 between the observer and the target body's center). The 204 following values of `abcorr' apply to the "reception" 205 case in which photons depart from `spoint' at the 206 light-time corrected epoch et-lt and *arrive* at the 207 observer's location at `et': 208 209 "LT" Correct both the position of `spoint' as 210 seen by the observer, and the position of 211 the sun as seen by the target, for light 212 time. Correct the orientation of the 213 target for light time. 214 215 "LT+S" Correct both the position of `spoint' as 216 seen by the observer, and the position of 217 the sun as seen by the target, for light 218 time and stellar aberration. Correct the 219 orientation of the target for light time. 220 221 "CN" Converged Newtonian light time correction. 222 In solving the light time equations for 223 `spoint' and the sun, the "CN" correction 224 iterates until the solution converges. 225 226 "CN+S" Converged Newtonian light time and stellar 227 aberration corrections. This option 228 produces a solution that is at least as 229 accurate at that obtainable with the 230 "LT+S" option. Whether the "CN+S" solution 231 is substantially more accurate depends on 232 the geometry of the participating objects 233 and on the accuracy of the input data. In 234 all cases this routine will execute more 235 slowly when a converged solution is 236 computed. 237 238 The following values of `abcorr' apply to the 239 "transmission" case in which photons *arrive* at 240 `spoint' at the light-time corrected epoch et+lt and 241 *depart* from the observer's location at `et': 242 243 "XLT" "Transmission" case: correct for 244 one-way light time using a Newtonian 245 formulation. This correction yields the 246 illumination angles at the moment that 247 `spoint' receives photons emitted from the 248 observer's location at `et'. 249 250 The light time correction uses an 251 iterative solution of the light time 252 equation. The solution invoked by the 253 "XLT" option uses one iteration. 254 255 Both the target position as seen by the 256 observer, and rotation of the target 257 body, are corrected for light time. 258 259 "XLT+S" "Transmission" case: correct for 260 one-way light time and stellar 261 aberration using a Newtonian 262 formulation This option modifies the 263 angles obtained with the "XLT" option 264 to account for the observer's and 265 target's velocities relative to the 266 solar system barycenter (the latter 267 velocity is used in computing the 268 direction to the apparent illumination 269 source). 270 271 "XCN" Converged Newtonian light time 272 correction. This is the same as XLT 273 correction but with further iterations 274 to a converged Newtonian light time 275 solution. 276 277 "XCN+S" "Transmission" case: converged 278 Newtonian light time and stellar 279 aberration corrections. This option 280 produces a solution that is at least as 281 accurate at that obtainable with the 282 "XLT+S" option. Whether the "XCN+S" 283 solution is substantially more accurate 284 depends on the geometry of the 285 participating objects and on the 286 accuracy of the input data. In all 287 cases this routine will execute more 288 slowly when a converged solution is 289 computed. 290 291 292 Neither case nor white space are significant in 293 `abcorr'. For example, the string 294 295 "Lt + s" 296 297 is valid. 298 299 300 obsrvr is the name of the observing body. The observing body 301 is an ephemeris object: it typically is a spacecraft, 302 the earth, or a surface point on the earth. `obsrvr' is 303 case-insensitive, and leading and trailing blanks in 304 `obsrvr' are not significant. Optionally, you may 305 supply a string containing the integer ID code for 306 the object. For example both "MOON" and "301" are 307 legitimate strings that indicate the moon is the 308 observer. 309 310 `obsrvr' may be not be identical to `target'. 311 312 313 spoint is a surface point on the target body, expressed in 314 Cartesian coordinates, relative to the body-fixed 315 target frame designated by `fixref'. 316 317 `spoint' need not be visible from the observer's 318 location at the epoch `et'. 319 320 The components of `spoint' have units of km. 321 322 323 -Detailed_Output 324 325 326 trgepc is the "target surface point epoch." `trgepc' is defined 327 as follows: letting `lt' be the one-way light time 328 between the observer and the input surface point 329 `spoint', `trgepc' is either the epoch et-lt or `et' 330 depending on whether the requested aberration correction 331 is, respectively, for received radiation or omitted. 332 `lt' is computed using the method indicated by `abcorr'. 333 334 `trgepc' is expressed as seconds past J2000 TDB. 335 336 337 srfvec is the vector from the observer's position at `et' to 338 the aberration-corrected (or optionally, geometric) 339 position of `spoint', where the aberration corrections 340 are specified by `abcorr'. `srfvec' is expressed in the 341 target body-fixed reference frame designated by 342 `fixref', evaluated at `trgepc'. 343 344 The components of `srfvec' are given in units of km. 345 346 One can use the CSPICE function vnorm_c to obtain the 347 distance between the observer and `spoint': 348 349 dist = vnorm_c ( srfvec ); 350 351 The observer's position `obspos', relative to the 352 target body's center, where the center's position is 353 corrected for aberration effects as indicated by 354 `abcorr', can be computed via the call: 355 356 vsub_c ( spoint, srfvec, obspos ); 357 358 To transform the vector `srfvec' from a reference frame 359 `fixref' at time `trgepc' to a time-dependent reference 360 frame `ref' at time `et', the routine pxfrm2_c should be 361 called. Let `xform' be the 3x3 matrix representing the 362 rotation from the reference frame `fixref' at time 363 `trgepc' to the reference frame `ref' at time `et'. Then 364 `srfvec' can be transformed to the result `refvec' as 365 follows: 366 367 pxfrm2_c ( fixref, ref, trgepc, et, xform ); 368 mxv_c ( xform, srfvec, refvec ); 369 370 371 phase is the phase angle at `spoint', as seen from `obsrvr' at 372 time `et'. This is the angle between the spoint-obsrvr 373 vector and the spoint-sun vector. Units are radians. The 374 range of `phase' is [0, pi]. See Particulars below for a 375 detailed discussion of the definition. 376 377 378 solar is the solar incidence angle at `spoint', as seen from 379 `obsrvr' at time `et'. This is the angle between the 380 surface normal vector at `spoint' and the spoint-sun 381 vector. Units are radians. The range of `solar' is [0, 382 pi]. See Particulars below for a detailed discussion of 383 the definition. 384 385 386 emissn is the emission angle at `spoint', as seen from `obsrvr' 387 at time `et'. This is the angle between the surface 388 normal vector at `spoint' and the spoint-observer 389 vector. Units are radians. The range of `emissn' is [0, 390 pi]. See Particulars below for a detailed discussion of 391 the definition. 392 393 -Parameters 394 395 None. 396 397 -Exceptions 398 399 400 1) If the specified aberration correction is relativistic or 401 calls for stellar aberration but not light time correction, 402 the error SPICE(NOTSUPPORTED) is signaled. If the specified 403 aberration correction is any other unrecognized value, the 404 error will be diagnosed and signaled by a routine in the call 405 tree of this routine. 406 407 2) If either the target or observer input strings cannot be 408 converted to an integer ID code, the error SPICE(IDCODENOTFOUND) 409 is signaled. 410 411 3) If `obsrvr' and `target' map to the same NAIF integer ID code, 412 the error SPICE(BODIESNOTDISTINCT) is signaled. 413 414 4) If the input target body-fixed frame `fixref' is not 415 recognized, the error SPICE(NOFRAME) is signaled. A frame 416 name may fail to be recognized because a required frame 417 specification kernel has not been loaded; another cause is a 418 misspelling of the frame name. 419 420 5) If the input frame `fixref' is not centered at the target body, 421 the error SPICE(INVALIDFRAME) is signaled. 422 423 6) If the input argument `METHOD' is not recognized, the error 424 SPICE(INVALIDMETHOD) is signaled. 425 426 7) If insufficient ephemeris data have been loaded prior to 427 calling ilumin_c, the error will be diagnosed and signaled by a 428 routine in the call tree of this routine. Note that when 429 light time correction is used, sufficient ephemeris data must 430 be available to propagate the states of observer, target, and 431 the sun to the solar system barycenter. 432 433 8) If the computation method specifies an ellipsoidal target 434 shape and triaxial radii of the target body have not been 435 loaded into the kernel pool prior to calling ilumin_c, the 436 error will be diagnosed and signaled by a routine in the call 437 tree of this routine. 438 439 9) The target must be an extended body: if any of the radii of 440 the target body are non-positive, the error will be 441 diagnosed and signaled by routines in the call tree of this 442 routine. 443 444 10) If PCK or CK data specifying the target body-fixed frame 445 orientation have not been loaded prior to calling ilumin_c, 446 the error will be diagnosed and signaled by a routine in the 447 call tree of this routine. 448 449 11) If ``method'' specifies that the target surface is represented by 450 DSK data, and no DSK files are loaded for the specified 451 target, the error is signaled by a routine in the call tree 452 of this routine. 453 454 12) If `method' specifies that the target surface is represented 455 by DSK data, and data representing the portion of the surface 456 on which `spoint' is located are not available, an error will 457 be signaled by a routine in the call tree of this routine. 458 459 13) If `method' specifies that the target surface is represented 460 by DSK data, `spoint' must lie on the target surface, not above 461 or below it. A small tolerance is used to allow for round-off 462 error in the calculation determining whether `spoint' is on the 463 surface. If, in the DSK case, `spoint' is too far from the 464 surface, an error will be signaled by a routine in the call 465 tree of this routine. 466 467 If the surface is represented by a triaxial ellipsoid, `spoint' 468 is not required to be close to the ellipsoid; however, the 469 results computed by this routine will be unreliable if `spoint' 470 is too far from the ellipsoid. 471 472 -Files 473 474 Appropriate kernels must be loaded by the calling program before 475 this routine is called. 476 477 The following data are required: 478 479 - SPK data: ephemeris data for target, observer, and the 480 sun must be loaded. If aberration corrections are used, the 481 states of target, observer, and the sun relative to the solar 482 system barycenter must be calculable from the available 483 ephemeris data. Typically ephemeris data are made available by 484 loading one or more SPK files via furnsh_c. 485 486 - Target body orientation data: these may be provided in a text or 487 binary PCK file. In some cases, target body orientation may 488 be provided by one more more CK files. In either case, data 489 are made available by loading the files via furnsh_c. 490 491 - Shape data for the target body: 492 493 PCK data: 494 495 If the target body shape is modeled as an ellipsoid, 496 triaxial radii for the target body must be loaded into 497 the kernel pool. Typically this is done by loading a 498 text PCK file via furnsh_c. 499 500 Triaxial radii are also needed if the target shape is 501 modeled by DSK data, and the DSK NADIR method is 502 selected. 503 504 DSK data: 505 506 If the target shape is modeled by DSK data, DSK files 507 containing topographic data for the target body must be 508 loaded. If a surface list is specified, data for at 509 least one of the listed surfaces must be loaded. DSK 510 files are loaded via furnsh_c. 511 512 The following data may be required: 513 514 - Frame data: if a frame definition is required to convert the 515 observer and target states to the body-fixed frame of the 516 target, that definition must be available in the kernel 517 pool. Typically the definition is supplied by loading a 518 frame kernel via furnsh_c. 519 520 - Surface name-ID associations: if surface names are specified 521 in `method', the association of these names with their 522 corresponding surface ID codes must be established by 523 assignments of the kernel variables 524 525 NAIF_SURFACE_NAME 526 NAIF_SURFACE_CODE 527 NAIF_SURFACE_BODY 528 529 Normally these associations are made by loading a text 530 kernel containing the necessary assignments. An example 531 of such assignments is 532 533 NAIF_SURFACE_NAME += 'Mars MEGDR 128 PIXEL/DEG' 534 NAIF_SURFACE_CODE += 1 535 NAIF_SURFACE_BODY += 499 536 537 - SCLK data: if the target body's orientation is provided by 538 CK files, an associated SCLK kernel must be loaded. 539 540 In all cases, kernel data are normally loaded once per program 541 run, NOT every time this routine is called. 542 543 544 -Particulars 545 546 CSPICE contains four routines that compute illumination angles: 547 548 illumf_c (same as illumg_c, except that illumination 549 and visibility flags are returned) 550 551 illumg_c (same as this routine, except that the caller 552 specifies the illumination source) 553 554 ilumin_c (this routine) 555 556 illum_c (deprecated) 557 558 559 illumf_c is the most capable of the set. 560 561 562 Illumination angles 563 =================== 564 565 The term "illumination angles" refers to the following set of 566 angles: 567 568 569 phase angle Angle between the vectors from the 570 surface point to the observer and 571 from the surface point to the sun. 572 573 solar incidence angle Angle between the surface normal at 574 the specified surface point and the 575 vector from the surface point to the 576 sun. 577 578 emission angle Angle between the surface normal at 579 the specified surface point and the 580 vector from the surface point to the 581 observer. 582 583 The diagram below illustrates the geometric relationships 584 defining these angles. The labels for the incidence, emission, 585 and phase angles are "inc.", "e.", and "phase". 586 587 588 * 589 sun 590 591 surface normal vector 592 ._ _. 593 |\ /| sun vector 594 \ phase / 595 \ . . / 596 . . 597 \ ___ / 598 . \/ \/ 599 _\ inc./ 600 . / \ / 601 . | e. \ / 602 * <--------------- * surface point on 603 viewing vector target body 604 location to viewing 605 (observer) location 606 607 608 Note that if the target-observer vector, the target normal vector at 609 the surface point, and the target-sun vector are coplanar, then 610 phase is the sum of the incidence and emission angles. This rarely 611 occurs; usually 612 613 phase angle < solar incidence angle + emission angle 614 615 All of the above angles can be computed using light time 616 corrections, light time and stellar aberration corrections, or no 617 aberration corrections. In order to describe apparent geometry as 618 observed by a remote sensing instrument, both light time and 619 stellar aberration corrections should be used. 620 621 The way aberration corrections are applied by this routine 622 is described below. 623 624 Light time corrections 625 ====================== 626 627 Observer-target surface point vector 628 ------------------------------------ 629 630 Let `et' be the epoch at which an observation or remote 631 sensing measurement is made, and let et-lt ("lt" stands 632 for "light time") be the epoch at which the photons 633 received at `et' were emitted from the surface point `spoint'. 634 Note that the light time between the surface point and 635 observer will generally differ from the light time between 636 the target body's center and the observer. 637 638 639 Target body's orientation 640 ------------------------- 641 642 Using the definitions of `et' and `lt' above, the target body's 643 orientation at et-lt is used. The surface normal is 644 dependent on the target body's orientation, so the body's 645 orientation model must be evaluated for the correct epoch. 646 647 648 Target body -- sun vector 649 ------------------------- 650 651 The surface features on the target body near `spoint' will 652 appear in a measurement made at `et' as they were at et-lt. In 653 particular, lighting on the target body is dependent on the 654 apparent location of the sun as seen from the target body at 655 et-lt. So, a second light time correction is used to compute 656 the position of the sun relative to the surface point. 657 658 659 Stellar aberration corrections 660 ============================== 661 662 Stellar aberration corrections are applied only if 663 light time corrections are applied as well. 664 665 Observer-target surface point body vector 666 ----------------------------------------- 667 668 When stellar aberration correction is performed, the 669 direction vector `srfvec' is adjusted so as to point to the 670 apparent position of `spoint': considering `spoint' to be an 671 ephemeris object, `srfvec' points from the observer's 672 position at `et' to the light time and stellar aberration 673 corrected position of `spoint'. 674 675 Target body-sun vector 676 ---------------------- 677 678 The target body-sun vector is the apparent position of the 679 sun, corrected for light time and stellar aberration, as seen 680 from the target body at time et-lt. 681 682 683 Using DSK data 684 ============== 685 686 DSK loading and unloading 687 ------------------------- 688 689 DSK files providing data used by this routine are loaded by 690 calling furnsh_c and can be unloaded by calling unload_c or 691 kclear_c. See the documentation of furnsh_c for limits on numbers 692 of loaded DSK files. 693 694 For run-time efficiency, it's desirable to avoid frequent 695 loading and unloading of DSK files. When there is a reason to 696 use multiple versions of data for a given target body---for 697 example, if topographic data at varying resolutions are to be 698 used---the surface list can be used to select DSK data to be 699 used for a given computation. It is not necessary to unload 700 the data that are not to be used. This recommendation presumes 701 that DSKs containing different versions of surface data for a 702 given body have different surface ID codes. 703 704 705 DSK data priority 706 ----------------- 707 708 A DSK coverage overlap occurs when two segments in loaded DSK 709 files cover part or all of the same domain---for example, a 710 given longitude-latitude rectangle---and when the time 711 intervals of the segments overlap as well. 712 713 When DSK data selection is prioritized, in case of a coverage 714 overlap, if the two competing segments are in different DSK 715 files, the segment in the DSK file loaded last takes 716 precedence. If the two segments are in the same file, the 717 segment located closer to the end of the file takes 718 precedence. 719 720 When DSK data selection is unprioritized, data from competing 721 segments are combined. For example, if two competing segments 722 both represent a surface as a set of triangular plates, the 723 union of those sets of plates is considered to represent the 724 surface. 725 726 Currently only unprioritized data selection is supported. 727 Because prioritized data selection may be the default behavior 728 in a later version of the routine, the UNPRIORITIZED keyword is 729 required in the `method' argument. 730 731 732 Syntax of the `method' input argument 733 ----------------------------------- 734 735 The keywords and surface list in the `method' argument 736 are called "clauses." The clauses may appear in any 737 order, for example 738 739 "DSK/<surface list>/UNPRIORITIZED" 740 "DSK/UNPRIORITIZED/<surface list>" 741 "UNPRIORITIZED/<surface list>/DSK" 742 743 The simplest form of the `method' argument specifying use of 744 DSK data is one that lacks a surface list, for example: 745 746 "DSK/UNPRIORITIZED" 747 748 For applications in which all loaded DSK data for the target 749 body are for a single surface, and there are no competing 750 segments, the above string suffices. This is expected to be 751 the usual case. 752 753 When, for the specified target body, there are loaded DSK 754 files providing data for multiple surfaces for that body, the 755 surfaces to be used by this routine for a given call must be 756 specified in a surface list, unless data from all of the 757 surfaces are to be used together. 758 759 The surface list consists of the string 760 761 "SURFACES =" 762 763 followed by a comma-separated list of one or more surface 764 identifiers. The identifiers may be names or integer codes in 765 string format. For example, suppose we have the surface 766 names and corresponding ID codes shown below: 767 768 Surface Name ID code 769 ------------ ------- 770 "Mars MEGDR 128 PIXEL/DEG" 1 771 "Mars MEGDR 64 PIXEL/DEG" 2 772 "Mars_MRO_HIRISE" 3 773 774 If data for all of the above surfaces are loaded, then 775 data for surface 1 can be specified by either 776 777 "SURFACES = 1" 778 779 or 780 781 "SURFACES = "\"Mars MEGDR 128 PIXEL/DEG\"" 782 783 Escaped double quotes are used to delimit the surface name 784 because it contains blank characters. 785 786 To use data for surfaces 2 and 3 together, any 787 of the following surface lists could be used: 788 789 "SURFACES = 2, 3" 790 791 "SURFACES = \"Mars MEGDR 64 PIXEL/DEG\", 3" 792 793 "SURFACES = 2, Mars_MRO_HIRISE" 794 795 "SURFACES = \"Mars MEGDR 64 PIXEL/DEG\", Mars_MRO_HIRISE" 796 797 An example of a `method' argument that could be constructed 798 using one of the surface lists above is 799 800 "DSK/UNPRIORITIZED/SURFACES = \"Mars MEGDR 64 PIXEL/DEG\", 3" 801 802 803 Aberration corrections using DSK data 804 ------------------------------------- 805 806 For irregularly shaped target bodies, the distance between the 807 observer and the nearest surface intercept need not be a 808 continuous function of time; hence the one-way light time 809 between the intercept and the observer may be discontinuous as 810 well. In such cases, the computed light time, which is found 811 using an iterative algorithm, may converge slowly or not at all. 812 In all cases, the light time computation will terminate, but 813 the result may be less accurate than expected. 814 815 816 -Examples 817 818 The numerical results shown for this example may differ across 819 platforms. The results depend on the SPICE kernels used as 820 input, the compiler and supporting libraries, and the machine 821 specific arithmetic implementation. 822 823 1) Find the phase, solar incidence, and emission angles at the 824 sub-solar and sub-spacecraft points on Mars as seen from the Mars 825 Global Surveyor spacecraft at a specified UTC time. 826 827 Use both an ellipsoidal Mars shape model and topographic data 828 provided by a DSK file. For both surface points, use the "near 829 point" and "nadir" definitions for ellipsoidal and DSK shape 830 models, respectively. 831 832 Use converged Newtonian light time and stellar aberration 833 corrections. 834 835 The topographic model is based on data from the MGS MOLA DEM 836 megr90n000cb, which has a resolution of 4 pixels/degree. A 837 triangular plate model was produced by computing a 720 x 1440 838 grid of interpolated heights from this DEM, then tessellating 839 the height grid. The plate model is stored in a type 2 segment 840 in the referenced DSK file. 841 842 Use the meta-kernel shown below to load the required SPICE 843 kernels. 844 845 KPL/MK 846 847 File: ilumin_ex1.tm 848 849 This meta-kernel is intended to support operation of SPICE 850 example programs. The kernels shown here should not be 851 assumed to contain adequate or correct versions of data 852 required by SPICE-based user applications. 853 854 In order for an application to use this meta-kernel, the 855 kernels referenced here must be present in the user's 856 current working directory. 857 858 The names and contents of the kernels referenced 859 by this meta-kernel are as follows: 860 861 File name Contents 862 --------- -------- 863 de430.bsp Planetary ephemeris 864 mar097.bsp Mars satellite ephemeris 865 pck00010.tpc Planet orientation and 866 radii 867 naif0011.tls Leapseconds 868 mgs_ext12_ipng_mgs95j.bsp MGS ephemeris 869 megr90n000cb_plate.bds Plate model based on 870 MEGDR DEM, resolution 871 4 pixels/degree. 872 873 \begindata 874 875 KERNELS_TO_LOAD = ( 'de430.bsp', 876 'mar097.bsp', 877 'pck00010.tpc', 878 'naif0011.tls', 879 'mgs_ext12_ipng_mgs95j.bsp', 880 'megr90n000cb_plate.bds' ) 881 \begintext 882 883 884 885 Example code begins here. 886 887 888 /. 889 Program ilumin_ex1 890 ./ 891 892 #include <stdio.h> 893 #include "SpiceUsr.h" 894 895 int main() 896 { 897 898 /. 899 Local constants 900 ./ 901 #define META "ilumin_ex1.tm" 902 #define MTHLEN 81 903 #define NMETH 2 904 905 /. 906 Local variables 907 ./ 908 SpiceChar * abcorr; 909 SpiceChar * fixref; 910 SpiceChar ilumth [NMETH][MTHLEN] = 911 {"Ellipsoid", "DSK/Unprioritized" }; 912 913 SpiceChar * target; 914 SpiceChar * obsrvr; 915 SpiceChar submth [NMETH][MTHLEN] = 916 {"Near Point/Ellipsoid", "DSK/Nadir/Unprioritized" }; 917 918 SpiceChar * utc; 919 920 SpiceDouble et; 921 SpiceDouble srfvec [3]; 922 SpiceDouble sscemi; 923 SpiceDouble sscphs; 924 SpiceDouble sscpt [3]; 925 SpiceDouble sscsol; 926 SpiceDouble sslemi; 927 SpiceDouble sslphs; 928 SpiceDouble sslsol; 929 SpiceDouble ssolpt [3]; 930 SpiceDouble trgepc; 931 932 SpiceInt i; 933 934 935 /. 936 Load kernel files. 937 ./ 938 furnsh_c ( META ); 939 940 /. 941 Convert the UTC request time string to seconds past 942 J2000 TDB. 943 ./ 944 utc = "2003 OCT 13 06:00:00 UTC"; 945 946 str2et_c ( utc, &et ); 947 948 printf ( "\n" 949 "UTC epoch is %s\n", utc ); 950 951 952 /. 953 Assign observer and target names. The acronym MGS 954 indicates Mars Global Surveyor. See NAIF_IDS for a 955 list of names recognized by SPICE. 956 957 Also set the target body-fixed frame and 958 the aberration correction flag. 959 ./ 960 961 target = "Mars"; 962 obsrvr = "MGS"; 963 fixref = "IAU_MARS"; 964 abcorr = "CN+S"; 965 966 for ( i = 0; i < NMETH; i++ ) 967 { 968 /. 969 Find the sub-solar point on Mars as 970 seen from the MGS spacecraft at `et'. Use the 971 "near point" style of sub-point definition 972 when the shape model is an ellipsoid, and use 973 the "nadir" style when the shape model is 974 provided by DSK data. This makes it easy to 975 verify the solar incidence angle when 976 the target is modeled as an ellipsoid. 977 ./ 978 subslr_c ( submth[i], target, et, 979 fixref, abcorr, obsrvr, 980 ssolpt, &trgepc, srfvec ); 981 982 /. 983 Now find the sub-spacecraft point. 984 ./ 985 subpnt_c ( submth[i], target, et, 986 fixref, abcorr, obsrvr, 987 sscpt, &trgepc, srfvec ); 988 989 /. 990 Find the phase, solar incidence, and emission 991 angles at the sub-solar point on Mars as 992 seen from MGS at time `et'. 993 ./ 994 ilumin_c ( ilumth[i], target, 995 et, fixref, abcorr, 996 obsrvr, ssolpt, &trgepc, 997 srfvec, &sslphs, &sslsol, 998 &sslemi ); 999 1000 /. 1001 Do the same for the sub-spacecraft point. 1002 ./ 1003 ilumin_c ( ilumth[i], target, 1004 et, fixref, abcorr, 1005 obsrvr, sscpt, &trgepc, 1006 srfvec, &sscphs, &sscsol, 1007 &sscemi ); 1008 1009 /. 1010 Convert the angles to degrees and write them out. 1011 ./ 1012 sslphs *= dpr_c(); 1013 sslsol *= dpr_c(); 1014 sslemi *= dpr_c(); 1015 1016 sscphs *= dpr_c(); 1017 sscsol *= dpr_c(); 1018 sscemi *= dpr_c(); 1019 1020 printf ( "\n" 1021 " ilumin_c method: %s\n" 1022 " subpnt_c method: %s\n" 1023 " subslr_c method: %s\n" 1024 "\n" 1025 " Illumination angles at the " 1026 "sub-solar point:\n" 1027 "\n" 1028 " Phase angle (deg): %15.9f\n" 1029 " Solar incidence angle (deg): %15.9f\n" 1030 " Emission angle (deg): %15.9f\n", 1031 ilumth[i], 1032 submth[i], 1033 submth[i], 1034 sslphs, 1035 sslsol, 1036 sslemi ); 1037 1038 if ( i == 0 ) 1039 { 1040 printf ( " The solar incidence angle " 1041 "should be 0.\n" 1042 " The emission and phase " 1043 "angles should be equal.\n" ); 1044 } 1045 1046 printf ( "\n" 1047 " Illumination angles at the " 1048 "sub-s/c point:\n" 1049 "\n" 1050 " Phase angle (deg): %15.9f\n" 1051 " Solar incidence angle (deg): %15.9f\n" 1052 " Emission angle (deg): %15.9f\n", 1053 sscphs, 1054 sscsol, 1055 sscemi ); 1056 1057 if ( i == 0 ) 1058 { 1059 printf ( " The emission angle " 1060 "should be 0.\n" 1061 " The solar incidence " 1062 "and phase angles should be equal.\n" ); 1063 } 1064 } 1065 printf ( "\n" ); 1066 1067 return ( 0 ); 1068 } 1069 1070 1071 When this program was executed on a PC/Linux/gcc/64-bit platform, 1072 the output was: 1073 1074 1075 UTC epoch is 2003 OCT 13 06:00:00 UTC 1076 1077 ilumin_c method: Ellipsoid 1078 subpnt_c method: Near Point/Ellipsoid 1079 subslr_c method: Near Point/Ellipsoid 1080 1081 Illumination angles at the sub-solar point: 1082 1083 Phase angle (deg): 138.370270685 1084 Solar incidence angle (deg): 0.000000000 1085 Emission angle (deg): 138.370270685 1086 The solar incidence angle should be 0. 1087 The emission and phase angles should be equal. 1088 1089 Illumination angles at the sub-s/c point: 1090 1091 Phase angle (deg): 101.439331040 1092 Solar incidence angle (deg): 101.439331041 1093 Emission angle (deg): 0.000000002 1094 The emission angle should be 0. 1095 The solar incidence and phase angles should be equal. 1096 1097 ilumin_c method: DSK/Unprioritized 1098 subpnt_c method: DSK/Nadir/Unprioritized 1099 subslr_c method: DSK/Nadir/Unprioritized 1100 1101 Illumination angles at the sub-solar point: 1102 1103 Phase angle (deg): 138.387071677 1104 Solar incidence angle (deg): 0.967122745 1105 Emission angle (deg): 137.621480599 1106 1107 Illumination angles at the sub-s/c point: 1108 1109 Phase angle (deg): 101.439331359 1110 Solar incidence angle (deg): 101.555993667 1111 Emission angle (deg): 0.117861156 1112 1113 -Restrictions 1114 1115 None. 1116 1117 -Literature_References 1118 1119 None. 1120 1121 -Author_and_Institution 1122 1123 N.J. Bachman (JPL) 1124 B.V. Semenov (JPL) 1125 1126 -Version 1127 1128 1129 -CSPICE Version 2.0.0, 04-APR-2017 (NJB) 1130 1131 Corrected various header comment typos. 1132 1133 16-AUG-2016 (NJB) (BVS) 1134 1135 Updated to support DSK. 1136 1137 -CSPICE Version 1.0.2, 17-OCT-2011 (SCK) 1138 1139 References to the new pxfrm2_c routine were added 1140 to the Detailed Output section. 1141 1142 -CSPICE Version 1.0.1, 06-FEB-2009 (NJB) 1143 1144 Incorrect frame name fixfrm was changed to fixref in 1145 documentation. 1146 1147 In the header examples, meta-kernel names were updated to use 1148 the suffix 1149 1150 ".tm" 1151 1152 -CSPICE Version 1.0.0, 02-MAR-2008 (NJB) 1153 1154 -Index_Entries 1155 1156 illumination angles 1157 lighting angles 1158 phase angle 1159 solar incidence angle 1160 emission angle 1161 1162 -& 1163 */ 1164 1165 { /* Begin ilumin_c */ 1166 1167 1168 /* 1169 Participate in error tracing. 1170 */ 1171 chkin_c ( "ilumin_c" ); 1172 1173 1174 /* 1175 Check the input strings: target, fixref, abcorr, and obsrvr. Make 1176 sure none of the pointers are null and that each string contains at 1177 least one non-null character. 1178 */ 1179 CHKFSTR ( CHK_STANDARD, "ilumin_c", method ); 1180 CHKFSTR ( CHK_STANDARD, "ilumin_c", target ); 1181 CHKFSTR ( CHK_STANDARD, "ilumin_c", fixref ); 1182 CHKFSTR ( CHK_STANDARD, "ilumin_c", abcorr ); 1183 CHKFSTR ( CHK_STANDARD, "ilumin_c", obsrvr ); 1184 1185 /* 1186 Call the f2c'd routine. 1187 */ 1188 ilumin_ ( ( char * ) method, 1189 ( char * ) target, 1190 ( doublereal * ) &et, 1191 ( char * ) fixref, 1192 ( char * ) abcorr, 1193 ( char * ) obsrvr, 1194 ( doublereal * ) spoint, 1195 ( doublereal * ) trgepc, 1196 ( doublereal * ) srfvec, 1197 ( doublereal * ) phase, 1198 ( doublereal * ) incdnc, 1199 ( doublereal * ) emissn, 1200 ( ftnlen ) strlen(method), 1201 ( ftnlen ) strlen(target), 1202 ( ftnlen ) strlen(fixref), 1203 ( ftnlen ) strlen(abcorr), 1204 ( ftnlen ) strlen(obsrvr) ); 1205 1206 chkout_c ( "ilumin_c" ); 1207 1208 } /* End ilumin_c */ 1209