1 /* 2 3 -Header_File SpiceGF.h ( CSPICE GF-specific definitions ) 4 5 -Abstract 6 7 Perform CSPICE GF-specific definitions. 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 GF 37 38 -Keywords 39 40 GEOMETRY 41 SEARCH 42 43 -Exceptions 44 45 None 46 47 -Files 48 49 None 50 51 -Particulars 52 53 This header defines macros that may be referenced in application 54 code that calls CSPICE GF functions. 55 56 57 Macros 58 ====== 59 60 Workspace parameters 61 -------------------- 62 63 CSPICE applications normally don't declare workspace arguments 64 and therefore don't directly reference workspace size parameters. 65 However, CSPICE GF APIs dealing with numeric constraints 66 dynamically allocate workspace memory; the amount allocated 67 depends on the number of intervals the workspace windows can 68 hold. This amount is an input argument to the GF numeric quantity 69 APIs. 70 71 The parameters below are used to calculate the amount of memory 72 required. Each workspace window contains 6 double precision 73 numbers in its control area and 2 double precision numbers for 74 each interval it can hold. 75 76 77 Name Description 78 ---- ---------- 79 SPICE_GF_NWMAX Maximum number of windows required for 80 a user-defined workspace array. 81 82 SPICE_GF_NWDIST Number of workspace windows used by 83 gfdist_c and the underlying SPICELIB 84 routine GFDIST. 85 86 SPICE_GF_NWILUM Number of workspace windows used by 87 gfilum_c and the underlying SPICELIB 88 routine GFILUM. 89 90 SPICE_GF_NWSEP Number of workspace windows used by 91 gfsep_c and the underlying SPICELIB 92 routine GFSEP. 93 94 SPICE_GF_NWRR Number of workspace windows used by 95 gfrr_c and the underlying SPICELIB 96 routine GFRR. 97 98 SPICE_GF_NWPA Number of workspace windows used by 99 gfpa_c and the underlying SPICELIB 100 routine GFPA. 101 102 103 Field of view (FOV) parameters 104 ------------------------------ 105 106 Name Description 107 ---- ---------- 108 SPICE_GF_MAXVRT Maximum allowed number of boundary 109 vectors for a polygonal FOV. 110 111 SPICE_GF_CIRFOV Parameter identifying a circular FOV. 112 113 SPICE_GF_ELLFOV Parameter identifying a elliptical FOV. 114 115 SPICE_GF_POLFOV Parameter identifying a polygonal FOV. 116 117 SPICE_GF_RECFOV Parameter identifying a rectangular FOV. 118 119 SPICE_GF_SHPLEN Parameter specifying maximum length of 120 a FOV shape name. 121 122 SPICE_GF_MARGIN is a small positive number used to 123 constrain the orientation of the 124 boundary vectors of polygonal FOVs. Such 125 FOVs must satisfy the following 126 constraints: 127 128 1) The boundary vectors must be 129 contained within a right circular 130 cone of angular radius less than 131 than (pi/2) - MARGIN radians; in 132 other words, there must be a vector 133 A such that all boundary vectors 134 have angular separation from A of 135 less than (pi/2)-MARGIN radians. 136 137 2) There must be a pair of boundary 138 vectors U, V such that all other 139 boundary vectors lie in the same 140 half space bounded by the plane 141 containing U and V. Furthermore, all 142 other boundary vectors must have 143 orthogonal projections onto a plane 144 normal to this plane such that the 145 projections have angular separation 146 of at least 2*MARGIN radians from 147 the plane spanned by U and V. 148 149 MARGIN is currently set to 1.D-12. 150 151 152 Occultation parameters 153 ---------------------- 154 155 SPICE_GF_ANNULR Parameter identifying an "annular 156 occultation." This geometric condition 157 is more commonly known as a "transit." 158 The limb of the background object must 159 not be blocked by the foreground object 160 in order for an occultation to be 161 "annular." 162 163 SPICE_GF_ANY Parameter identifying any type of 164 occultation or transit. 165 166 SPICE_GF_FULL Parameter identifying a full 167 occultation: the foreground body 168 entirely blocks the background body. 169 170 SPICE_GF_PARTL Parameter identifying an "partial 171 occultation." This is an occultation in 172 which the foreground body blocks part, 173 but not all, of the limb of the 174 background body. 175 176 177 178 Target shape parameters 179 ----------------------- 180 181 SPICE_GF_EDSHAP Parameter indicating a target object's 182 shape is modeled as an ellipsoid. 183 184 SPICE_GF_PTSHAP Parameter indicating a target object's 185 shape is modeled as a point. 186 187 SPICE_GF_RYSHAP Parameter indicating a target object's 188 "shape" is modeled as a ray emanating 189 from an observer's location. This model 190 may be used in visibility computations 191 for targets whose direction, but not 192 position, relative to an observer is 193 known. 194 195 SPICE_GF_SPSHAP Parameter indicating a target object's 196 shape is modeled as a sphere. 197 198 199 200 Search parameters 201 ----------------- 202 203 These parameters affect the manner in which GF searches are 204 performed. 205 206 SPICE_GF_ADDWIN is a parameter used in numeric quantity 207 searches that use an equality 208 constraint. This parameter is used to 209 expand the confinement window (the 210 window over which the search is 211 performed) by a small amount at both 212 ends. This expansion accommodates the 213 case where a geometric quantity is equal 214 to a reference value at a boundary point 215 of the original confinement window. 216 217 SPICE_GF_CNVTOL is the default convergence tolerance 218 used by GF routines that don't support a 219 user-supplied tolerance value. GF 220 searches for roots will terminate when a 221 root is bracketed by times separated by 222 no more than this tolerance. Units are 223 seconds. 224 225 Configuration parameter 226 ----------------------- 227 228 SPICE_GFEVNT_MAXPAR Parameter indicating the maximum number of 229 elements needed for the 'qnames' and 'q*pars' 230 arrays used in gfevnt_c. 231 232 SpiceChar qcpars[SPICE_GFEVNT_MAXPAR][LNSIZE]; 233 SpiceDouble qdpars[SPICE_GFEVNT_MAXPAR]; 234 SpiceInt qipars[SPICE_GFEVNT_MAXPAR]; 235 SpiceBoolean qlpars[SPICE_GFEVNT_MAXPAR]; 236 237 -Examples 238 239 None 240 241 -Restrictions 242 243 None. 244 245 -Literature_References 246 247 None. 248 249 -Author_and_Institution 250 251 N.J. Bachman (JPL) 252 L.S. Elson (JPL) 253 254 -Version 255 256 -CSPICE Version 2.1.1, 29-NOV-2016 (NJB) 257 258 Corrected description of parameter SPICE_GF_SPSHAP. 259 260 -CSPICE Version 2.1.0, 23-FEB-2012 (NJB) 261 262 Added parameters: 263 264 SPICE_GF_NWILUM 265 SPICE_GF_NWRR 266 SPICE_GF_NWPA 267 268 -CSPICE Version 2.0.0, 23-JUN-2009 (NJB) 269 270 Added parameter for maximum length of FOV shape string. 271 272 -CSPICE Version 1.0.0, 11-MAR-2009 (NJB) 273 274 */ 275 276 277 #ifndef HAVE_SPICE_GF_H 278 279 #define HAVE_SPICE_GF_H 280 281 282 /* 283 See the Particulars section above for parameter descriptions. 284 */ 285 286 /* 287 Workspace parameters 288 */ 289 #define SPICE_GF_NWMAX 15 290 #define SPICE_GF_NWDIST 5 291 #define SPICE_GF_NWILUM 5 292 #define SPICE_GF_NWSEP 5 293 #define SPICE_GF_NWRR 5 294 #define SPICE_GF_NWPA 5 295 296 297 /* 298 Field of view (FOV) parameters 299 */ 300 #define SPICE_GF_MAXVRT 10000 301 #define SPICE_GF_CIRFOV "CIRCLE" 302 #define SPICE_GF_ELLFOV "ELLIPSE" 303 #define SPICE_GF_POLFOV "POLYGON" 304 #define SPICE_GF_RECFOV "RECTANGLE" 305 #define SPICE_GF_SHPLEN 10 306 #define SPICE_GF_MARGIN ( 1.e-12 ) 307 308 309 /* 310 Occultation parameters 311 */ 312 #define SPICE_GF_ANNULR "ANNULAR" 313 #define SPICE_GF_ANY "ANY" 314 #define SPICE_GF_FULL "FULL" 315 #define SPICE_GF_PARTL "PARTIAL" 316 317 318 /* 319 Target shape parameters 320 */ 321 #define SPICE_GF_EDSHAP "ELLIPSOID" 322 #define SPICE_GF_PTSHAP "POINT" 323 #define SPICE_GF_RYSHAP "RAY" 324 #define SPICE_GF_SPSHAP "SPHERE" 325 326 327 /* 328 Search parameters 329 */ 330 #define SPICE_GF_ADDWIN 1.0 331 #define SPICE_GF_CNVTOL 1.e-6 332 333 334 /* 335 Configuration parameters. 336 */ 337 #define SPICE_GFEVNT_MAXPAR 10 338 339 340 #endif 341 342 343 /* 344 End of header file SpiceGF.h 345 */ 346