1 /* 2 3 -Procedure pgrrec_c ( Planetographic to rectangular ) 4 5 -Abstract 6 7 Convert planetographic coordinates to rectangular coordinates. 8 9 -Disclaimer 10 11 THIS SOFTWARE AND ANY RELATED MATERIALS WERE CREATED BY THE 12 CALIFORNIA INSTITUTE OF TECHNOLOGY (CALTECH) UNDER A U.S. 13 GOVERNMENT CONTRACT WITH THE NATIONAL AERONAUTICS AND SPACE 14 ADMINISTRATION (NASA). THE SOFTWARE IS TECHNOLOGY AND SOFTWARE 15 PUBLICLY AVAILABLE UNDER U.S. EXPORT LAWS AND IS PROVIDED "AS-IS" 16 TO THE RECIPIENT WITHOUT WARRANTY OF ANY KIND, INCLUDING ANY 17 WARRANTIES OF PERFORMANCE OR MERCHANTABILITY OR FITNESS FOR A 18 PARTICULAR USE OR PURPOSE (AS SET FORTH IN UNITED STATES UCC 19 SECTIONS 2312-2313) OR FOR ANY PURPOSE WHATSOEVER, FOR THE 20 SOFTWARE AND RELATED MATERIALS, HOWEVER USED. 21 22 IN NO EVENT SHALL CALTECH, ITS JET PROPULSION LABORATORY, OR NASA 23 BE LIABLE FOR ANY DAMAGES AND/OR COSTS, INCLUDING, BUT NOT 24 LIMITED TO, INCIDENTAL OR CONSEQUENTIAL DAMAGES OF ANY KIND, 25 INCLUDING ECONOMIC DAMAGE OR INJURY TO PROPERTY AND LOST PROFITS, 26 REGARDLESS OF WHETHER CALTECH, JPL, OR NASA BE ADVISED, HAVE 27 REASON TO KNOW, OR, IN FACT, SHALL KNOW OF THE POSSIBILITY. 28 29 RECIPIENT BEARS ALL RISK RELATING TO QUALITY AND PERFORMANCE OF 30 THE SOFTWARE AND ANY RELATED MATERIALS, AND AGREES TO INDEMNIFY 31 CALTECH AND NASA FOR ALL THIRD-PARTY CLAIMS RESULTING FROM THE 32 ACTIONS OF RECIPIENT IN THE USE OF THE SOFTWARE. 33 34 -Required_Reading 35 36 KERNEL 37 NAIF_IDS 38 PCK 39 40 -Keywords 41 42 CONVERSION 43 COORDINATES 44 GEOMETRY 45 MATH 46 47 */ 48 49 #include "SpiceUsr.h" 50 #include "SpiceZfc.h" 51 #include "SpiceZmc.h" 52 53 pgrrec_c(ConstSpiceChar * body,SpiceDouble lon,SpiceDouble lat,SpiceDouble alt,SpiceDouble re,SpiceDouble f,SpiceDouble rectan[3])54 void pgrrec_c ( ConstSpiceChar * body, 55 SpiceDouble lon, 56 SpiceDouble lat, 57 SpiceDouble alt, 58 SpiceDouble re, 59 SpiceDouble f, 60 SpiceDouble rectan[3] ) 61 62 /* 63 64 -Brief_I/O 65 66 VARIABLE I/O DESCRIPTION 67 -------- --- -------------------------------------------------- 68 body I Body with which coordinate system is associated. 69 lon I Planetographic longitude of a point (radians). 70 lat I Planetographic latitude of a point (radians). 71 alt I Altitude of a point above reference spheroid. 72 re I Equatorial radius of the reference spheroid. 73 f I Flattening coefficient. 74 rectan O Rectangular coordinates of the point. 75 76 -Detailed_Input 77 78 body Name of the body with which the planetographic 79 coordinate system is associated. 80 81 `body' is used by this routine to look up from the 82 kernel pool the prime meridian rate coefficient giving 83 the body's spin sense. See the Files and Particulars 84 header sections below for details. 85 86 lon Planetographic longitude of the input point. This is 87 the angle between the prime meridian and the meridian 88 containing the input point. For bodies having 89 prograde (aka direct) rotation, the direction of 90 increasing longitude is positive west: from the +X 91 axis of the rectangular coordinate system toward the 92 -Y axis. For bodies having retrograde rotation, the 93 direction of increasing longitude is positive east: 94 from the +X axis toward the +Y axis. 95 96 The earth, moon, and sun are exceptions: 97 planetographic longitude is measured positive east for 98 these bodies. 99 100 The default interpretation of longitude by this 101 and the other planetographic coordinate conversion 102 routines can be overridden; see the discussion in 103 Particulars below for details. 104 105 Longitude is measured in radians. On input, the range 106 of longitude is unrestricted. 107 108 lat Planetographic latitude of the input point. For a 109 point P on the reference spheroid, this is the angle 110 between the XY plane and the outward normal vector at 111 P. For a point P not on the reference spheroid, the 112 planetographic latitude is that of the closest point 113 to P on the spheroid. 114 115 Latitude is measured in radians. On input, the 116 range of latitude is unrestricted. 117 118 alt Altitude of point above the reference spheroid. 119 Units of `alt' must match those of `re'. 120 121 re Equatorial radius of a reference spheroid. This 122 spheroid is a volume of revolution: its horizontal 123 cross sections are circular. The shape of the 124 spheroid is defined by an equatorial radius `re' and 125 a polar radius `rp'. Units of `re' must match those of 126 `alt'. 127 128 f Flattening coefficient = 129 130 (re-rp) / re 131 132 where `rp' is the polar radius of the spheroid, and the 133 units of `rp' match those of `re'. 134 135 -Detailed_Output 136 137 rectan The rectangular coordinates of the input point. See 138 the discussion below in the Particulars header section 139 for details. 140 141 The units associated with `rectan' are those associated 142 with the inputs `alt' and `re'. 143 144 -Parameters 145 146 None. 147 148 -Exceptions 149 150 1) If the body name `body' cannot be mapped to a NAIF ID code, 151 and if `body' is not a string representation of an integer, 152 the error SPICE(IDCODENOTFOUND) will be signaled. 153 154 2) If the kernel variable 155 156 BODY<ID code>_PGR_POSITIVE_LON 157 158 is present in the kernel pool but has a value other 159 than one of 160 161 'EAST' 162 'WEST' 163 164 the error SPICE(INVALIDOPTION) will be signaled. Case 165 and blanks are ignored when these values are interpreted. 166 167 3) If polynomial coefficients for the prime meridian of `body' 168 are not available in the kernel pool, and if the kernel 169 variable BODY<ID code>_PGR_POSITIVE_LON is not present in 170 the kernel pool, the error SPICE(MISSINGDATA) will be signaled. 171 172 4) If the equatorial radius is non-positive, the error 173 SPICE(VALUEOUTOFRANGE) is signaled. 174 175 5) If the flattening coefficient is greater than or equal to one, 176 the error SPICE(VALUEOUTOFRANGE) is signaled. 177 178 6) The error SPICE(EMPTYSTRING) is signaled if the input 179 string `body' does not contain at least one character, since the 180 input string cannot be converted to a Fortran-style string in 181 this case. 182 183 7) The error SPICE(NULLPOINTER) is signaled if the input string 184 pointer `body' is null. 185 186 -Files 187 188 This routine expects a kernel variable giving body's prime 189 meridian angle as a function of time to be available in the 190 kernel pool. Normally this item is provided by loading a PCK 191 file. The required kernel variable is named 192 193 BODY<body ID>_PM 194 195 where <body ID> represents a string containing the NAIF integer 196 ID code for `body'. For example, if `body' is "JUPITER", then 197 the name of the kernel variable containing the prime meridian 198 angle coefficients is 199 200 BODY599_PM 201 202 See the PCK Required Reading for details concerning the prime 203 meridian kernel variable. 204 205 The optional kernel variable 206 207 BODY<body ID>_PGR_POSITIVE_LON 208 209 also is normally defined via loading a text kernel. When this 210 variable is present in the kernel pool, the prime meridian 211 coefficients for `body' are not required by this routine. See the 212 Particulars section below for details. 213 214 -Particulars 215 216 Given the planetographic coordinates of a point, this routine 217 returns the body-fixed rectangular coordinates of the point. The 218 body-fixed rectangular frame is that having the X-axis pass 219 through the 0 degree latitude 0 degree longitude direction, the 220 Z-axis pass through the 90 degree latitude direction, and the 221 Y-axis equal to the cross product of the unit Z-axis and X-axis 222 vectors. 223 224 The planetographic definition of latitude is identical to the 225 planetodetic (also called "geodetic" in SPICE documentation) 226 definition. In the planetographic coordinate system, latitude is 227 defined using a reference spheroid. The spheroid is 228 characterized by an equatorial radius and a polar radius. For a 229 point P on the spheroid, latitude is defined as the angle between 230 the X-Y plane and the outward surface normal at P. For a point P 231 off the spheroid, latitude is defined as the latitude of the 232 nearest point to P on the spheroid. Note if P is an interior 233 point, for example, if P is at the center of the spheroid, there 234 may not be a unique nearest point to P. 235 236 In the planetographic coordinate system, longitude is defined 237 using the spin sense of the body. Longitude is positive to the 238 west if the spin is prograde and positive to the east if the spin 239 is retrograde. The spin sense is given by the sign of the first 240 degree term of the time-dependent polynomial for the body's prime 241 meridian Euler angle "W": the spin is retrograde if this term is 242 negative and prograde otherwise. For the sun, planets, most 243 natural satellites, and selected asteroids, the polynomial 244 expression for W may be found in a SPICE PCK kernel. 245 246 The earth, moon, and sun are exceptions: planetographic longitude 247 is measured positive east for these bodies. 248 249 If you wish to override the default sense of positive longitude 250 for a particular body, you can do so by defining the kernel 251 variable 252 253 BODY<body ID>_PGR_POSITIVE_LON 254 255 where <body ID> represents the NAIF ID code of the body. This 256 variable may be assigned either of the values 257 258 'WEST' 259 'EAST' 260 261 For example, you can have this routine treat the longitude 262 of the earth as increasing to the west using the kernel 263 variable assignment 264 265 BODY399_PGR_POSITIVE_LON = 'WEST' 266 267 Normally such assignments are made by placing them in a text 268 kernel and loading that kernel via furnsh_c. 269 270 The definition of this kernel variable controls the behavior of 271 the CSPICE planetographic routines 272 273 pgrrec_c 274 recpgr_c 275 dpgrdr_c 276 drdpgr_c 277 278 It does not affect the other CSPICE coordinate conversion 279 routines. 280 281 -Examples 282 283 Numerical results shown for this example may differ between 284 platforms as the results depend on the SPICE kernels used as 285 input and the machine specific arithmetic implementation. 286 287 288 1) Find the rectangular coordinates of the point having Mars 289 planetographic coordinates: 290 291 longitude = 90 degrees west 292 latitude = 45 degrees north 293 altitude = 300 km 294 295 296 #include <stdio.h> 297 #include "SpiceUsr.h" 298 299 int main() 300 { 301 /. 302 Local variables 303 ./ 304 SpiceDouble alt; 305 SpiceDouble f; 306 SpiceDouble lat; 307 SpiceDouble lon; 308 SpiceDouble radii [3]; 309 SpiceDouble re; 310 SpiceDouble rectan [3]; 311 SpiceDouble rp; 312 313 SpiceInt n; 314 315 316 /. 317 Load a PCK file containing a triaxial 318 ellipsoidal shape model and orientation 319 data for Mars. 320 ./ 321 furnsh_c ( "pck00008.tpc" ); 322 323 /. 324 Look up the radii for Mars. Although we 325 omit it here, we could first call badkpv_c 326 to make sure the variable BODY499_RADII 327 has three elements and numeric data type. 328 If the variable is not present in the kernel 329 pool, bodvrd_c will signal an error. 330 ./ 331 bodvrd_c ( "MARS", "RADII", 3, &n, radii ); 332 333 /. 334 Compute flattening coefficient. 335 ./ 336 re = radii[0]; 337 rp = radii[2]; 338 f = ( re - rp ) / re; 339 340 /. 341 Do the conversion. Note that we must provide 342 longitude and latitude in radians. 343 ./ 344 lon = 90.0 * rpd_c(); 345 lat = 45.0 * rpd_c(); 346 alt = 3.e2; 347 348 pgrrec_c ( "mars", lon, lat, alt, re, f, rectan ); 349 350 351 printf ( "\n" 352 "Planetographic coordinates:\n" 353 "\n" 354 " Longitude (deg) = %18.9e\n" 355 " Latitude (deg) = %18.9e\n" 356 " Altitude (km) = %18.9e\n" 357 "\n" 358 "Ellipsoid shape parameters:\n" 359 "\n" 360 " Equatorial radius (km) = %18.9e\n" 361 " Polar radius (km) = %18.9e\n" 362 " Flattening coefficient = %18.9e\n" 363 "\n" 364 "Rectangular coordinates:\n" 365 "\n" 366 " X (km) = %18.9e\n" 367 " Y (km) = %18.9e\n" 368 " Z (km) = %18.9e\n" 369 "\n", 370 lon / rpd_c(), 371 lat / rpd_c(), 372 alt, 373 re, 374 rp, 375 f, 376 rectan[0], 377 rectan[1], 378 rectan[2] ); 379 380 return ( 0 ); 381 } 382 383 384 Output from this program should be similar to the following 385 (rounding and formatting differ across platforms): 386 387 388 Planetographic coordinates: 389 390 Longitude (deg) = 9.000000000e+01 391 Latitude (deg) = 4.500000000e+01 392 Altitude (km) = 3.000000000e+02 393 394 Ellipsoid shape parameters: 395 396 Equatorial radius (km) = 3.396190000e+03 397 Polar radius (km) = 3.376200000e+03 398 Flattening coefficient = 5.886007556e-03 399 400 Rectangular coordinates: 401 402 X (km) = 1.604650025e-13 403 Y (km) = -2.620678915e+03 404 Z (km) = 2.592408909e+03 405 406 407 408 2) Below is a table showing a variety of rectangular coordinates 409 and the corresponding Mars planetographic coordinates. The 410 values are computed using the reference spheroid having radii 411 412 Equatorial radius: 3397 413 Polar radius: 3375 414 415 Note: the values shown above may not be current or suitable 416 for your application. 417 418 419 Corresponding rectangular and planetographic coordinates are 420 listed to three decimal places. 421 422 rectan[0] rectan[1] rectan[2] lon lat alt 423 ------------------------------------------------------------------ 424 3397.000 0.000 0.000 0.000 0.000 0.000 425 -3397.000 0.000 0.000 180.000 0.000 0.000 426 -3407.000 0.000 0.000 180.000 0.000 10.000 427 -3387.000 0.000 0.000 180.000 0.000 -10.000 428 0.000 -3397.000 0.000 90.000 0.000 0.000 429 0.000 3397.000 0.000 270.000 0.000 0.000 430 0.000 0.000 3375.000 0.000 90.000 0.000 431 0.000 0.000 -3375.000 0.000 -90.000 0.000 432 0.000 0.000 0.000 0.000 90.000 -3375.000 433 434 435 436 3) Below we show the analogous relationships for the earth, 437 using the reference ellipsoid radii 438 439 Equatorial radius: 6378.140 440 Polar radius: 6356.750 441 442 Note the change in longitudes for points on the +/- Y axis 443 for the earth vs the Mars values. 444 445 rectan[0] rectan[1] rectan[2] lon lat alt 446 ------------------------------------------------------------------ 447 6378.140 0.000 0.000 0.000 0.000 0.000 448 -6378.140 0.000 0.000 180.000 0.000 0.000 449 -6388.140 0.000 0.000 180.000 0.000 10.000 450 -6368.140 0.000 0.000 180.000 0.000 -10.000 451 0.000 -6378.140 0.000 270.000 0.000 0.000 452 0.000 6378.140 0.000 90.000 0.000 0.000 453 0.000 0.000 6356.750 0.000 90.000 0.000 454 0.000 0.000 -6356.750 0.000 -90.000 0.000 455 0.000 0.000 0.000 0.000 90.000 -6356.750 456 457 458 -Restrictions 459 460 None. 461 462 -Author_and_Institution 463 464 C.H. Acton (JPL) 465 N.J. Bachman (JPL) 466 H.A. Neilan (JPL) 467 B.V. Semenov (JPL) 468 W.L. Taber (JPL) 469 470 -Literature_References 471 472 None. 473 474 -Version 475 476 -CSPICE Version 1.0.0, 26-DEC-2004 (CHA) (NJB) (HAN) (BVS) (WLT) 477 478 -Index_Entries 479 480 convert planetographic to rectangular coordinates 481 482 -& 483 */ 484 485 { /* Begin pgrrec_c */ 486 487 488 /* 489 Participate in error tracing. 490 */ 491 if ( return_c() ) 492 { 493 return; 494 } 495 chkin_c ( "pgrrec_c" ); 496 497 498 /* 499 Check the input string body to make sure the pointer is non-null 500 and the string length is non-zero. 501 */ 502 CHKFSTR ( CHK_STANDARD, "pgrrec_c", body ); 503 504 505 /* 506 Call the f2c'd Fortran routine. 507 */ 508 pgrrec_ ( ( char * ) body, 509 ( doublereal * ) &lon, 510 ( doublereal * ) &lat, 511 ( doublereal * ) &alt, 512 ( doublereal * ) &re, 513 ( doublereal * ) &f, 514 ( doublereal * ) rectan, 515 ( ftnlen ) strlen(body) ); 516 517 518 519 chkout_c ( "pgrrec_c" ); 520 521 } /* End pgrrec_c */ 522