azlcpo_c |

Table of contents## Procedureazlcpo_c ( AZ/EL, constant position observer state ) void azlcpo_c ( ConstSpiceChar * method, ConstSpiceChar * target, SpiceDouble et, ConstSpiceChar * abcorr, SpiceBoolean azccw, SpiceBoolean elplsz, ConstSpiceDouble obspos [3], ConstSpiceChar * obsctr, ConstSpiceChar * obsref, SpiceDouble azlsta [6], SpiceDouble * lt ) ## AbstractReturn the azimuth/elevation coordinates of a specified target relative to an "observer," where the observer has constant position in a specified reference frame. The observer's position is provided by the calling program rather than by loaded SPK files. ## Required_ReadingFRAMES PCK SPK TIME ## KeywordsCOORDINATES EPHEMERIS ## Brief_I/OVARIABLE I/O DESCRIPTION -------- --- -------------------------------------------------- method I Method to obtain the surface normal vector. target I Name of target ephemeris object. et I Observation epoch. abcorr I Aberration correction. azccw I Flag indicating how azimuth is measured. elplsz I Flag indicating how elevation is measured. obspos I Observer position relative to center of motion. obsctr I Center of motion of observer. obsref I Body-fixed, body-centered frame of observer's center. azlsta O State of target with respect to observer, in azimuth/elevation coordinates. lt O One way light time between target and observer. ## Detailed_Inputmethod is a short string providing parameters defining the computation method to be used to obtain the surface normal vector that defines the local zenith. Parameters include, but are not limited to, the shape model used to represent the body's surface of observer's center of motion. The only choice currently supported is "ELLIPSOID" The intercept computation uses a triaxial ellipsoid to model the body's surface of the observer's center of motion. The ellipsoid's radii must be available in the kernel pool. Neither case nor white space are significant in `method'. For example, the string " eLLipsoid " is valid. In a later Toolkit release, this argument will be used to invoke a wider range of surface representations. For example, it will be possible to represent the target body's surface using a digital shape model. target is the name of a target body. Optionally, you may supply the ID code of the object as an integer string. For example, both "EARTH" and "399" are legitimate strings to supply to indicate the target is Earth. Case and leading and trailing blanks are not significant in the string `target'. et is the ephemeris time at which the state of the target relative to the observer is to be computed. `et' is expressed as seconds past J2000 TDB. `et' refers to time at the observer's location. abcorr is a short string that indicates the aberration corrections to be applied to the observer-target state to account for one-way light time and stellar aberration. `abcorr' may be any of the following: "NONE" Apply no correction. Return the geometric state of the target relative to the observer. The following values of `abcorr' apply to the "reception" case in which photons depart from the target's location at the light-time corrected epoch et-lt and *arrive* at the observer's location at `et': "LT" Correct for one-way light time (also called "planetary aberration") using a Newtonian formulation. This correction yields the state of the target at the moment it emitted photons arriving at the observer at `et'. The light time correction uses an iterative solution of the light time equation. The solution invoked by the "LT" option uses one iteration. "LT+S" Correct for one-way light time and stellar aberration using a Newtonian formulation. This option modifies the state obtained with the "LT" option to account for the observer's velocity relative to the solar system barycenter. The result is the apparent state of the target---the position and velocity of the target as seen by the observer. "CN" Converged Newtonian light time correction. In solving the light time equation, the "CN" correction iterates until the solution converges. "CN+S" Converged Newtonian light time and stellar aberration corrections. The following values of `abcorr' apply to the "transmission" case in which photons *depart* from the observer's location at `et' and arrive at the target's location at the light-time corrected epoch et+lt: "XLT" "Transmission" case: correct for one-way light time using a Newtonian formulation. This correction yields the state of the target at the moment it receives photons emitted from the observer's location at `et'. "XLT+S" "Transmission" case: correct for one-way light time and stellar aberration using a Newtonian formulation This option modifies the state obtained with the "XLT" option to account for the observer's velocity relative to the solar system barycenter. The position component of the computed target state indicates the direction that photons emitted from the observer's location must be "aimed" to hit the target. "XCN" "Transmission" case: converged Newtonian light time correction. "XCN+S" "Transmission" case: converged Newtonian light time and stellar aberration corrections. Neither special nor general relativistic effects are accounted for in the aberration corrections applied by this routine. Case and leading and trailing blanks are not significant in the string `abcorr'. azccw is a flag indicating how the azimuth is measured. If `azccw' is SPICETRUE, the azimuth increases in the counterclockwise direction; otherwise it increases in the clockwise direction. elplsz is a flag indicating how the elevation is measured. If `elplsz' is SPICETRUE, the elevation increases from the XY plane toward +Z; otherwise toward -Z. obspos is the fixed (constant) geometric position of an observer relative to its center of motion `obsctr', expressed in the reference frame `obsref'. `obspos' does not need to be located on the surface of the object centered at `obsctr'. Units are always km. obsctr is the name of the center of motion of `obspos'. The ephemeris of `obsctr' is provided by loaded SPK files. Optionally, you may supply the integer ID code for the object as an integer string. For example both "MOON" and "301" are legitimate strings that indicate the moon is the center of motion. Case and leading and trailing blanks are not significant in the string `obsctr'. obsref is the name of the body-fixed, body-centered reference frame associated with the observer's center of motion, relative to which the input position `obspos' is expressed. The observer has constant position relative to its center of motion in this reference frame. Case and leading and trailing blanks are not significant in the string `obsref'. ## Detailed_Outputazlsta is a state vector representing the position and velocity of the target relative to the specified observer, corrected for the specified aberrations and expressed in azimuth/elevation coordinates. The first three components of `azlsta' represent the range, azimuth and elevation of the target's position; the last three components form the corresponding velocity vector: azlsta = ( r, az, el, dr/dt, daz/dt, del/dt ) The position component of `azlsta' points from the observer's location at `et' to the aberration-corrected location of the target. Note that the sense of the position vector is independent of the direction of radiation travel implied by the aberration correction. The velocity component of `azlsta' is the derivative with respect to time of the position component of `azlsta'. Azimuth, elevation and its derivatives are measured with respect to the axes of the local topocentric reference frame. See the -Particulars section for the definition of this reference frame. The azimuth is the angle between the projection onto the local topocentric principal (X-Y) plane of the vector from the observer's position to the target and the principal axis of the reference frame. The azimuth is zero on the +X axis. The elevation is the angle between the vector from the observer's position to the target and the local topocentric principal plane. The elevation is zero on the plane. Units are km for `r', radians for `az' and `el', km/sec for dr/dt, and radians/sec for daz/dt and del/dt. The range of `az' is [0, 2*pi] and the range of `el' is [-pi/2, pi/2]. The way azimuth and elevation are measured depend respectively on the value of the logical flags `azccw' and `elplsz'. See the description of these input arguments for details. lt is the one-way light time between the observer and target in seconds. If the target state is corrected for aberrations, then `lt' is the one-way light time between the observer and the light time corrected target location. ## ParametersNone. ## Exceptions1) If either the name of the center of motion or the target cannot be translated to its NAIF ID code, an error is signaled by a routine in the call tree of this routine. 2) If the reference frame `obsref' is not recognized, the error SPICE(UNKNOWNFRAME) is signaled by a routine in the call tree of this routine. A frame name may fail to be recognized because a required frame specification kernel has not been loaded; another cause is a misspelling of the frame name. 3) If the reference frame `obsref' is not centered at the observer's center of motion `obsctr', the error SPICE(INVALIDFRAME) is signaled by a routine in the call tree of this routine. 4) If the radii of the center of motion body are not available from the kernel pool, an error is signaled by a routine in the call tree of this routine. 5) If the size of the `obsctr' body radii kernel variable is not three, an error is signaled by a routine in the call tree of this routine. 6) If any of the three `obsctr' body radii is less-than or equal to zero, an error is signaled by a routine in the call tree of this routine. 7) If the ratio of the longest to the shortest radii is large enough so that arithmetic expressions involving its squared value may overflow, an error is signaled by a routine in the call tree of this routine. 8) If the radii of the center of motion body and the axes of `obspos' have radically different magnitudes so that arithmetic overflow may occur during the computation of the nearest point of the observer on the center of motion's reference ellipsoid, an error is signaled by a routine in the call tree of this routine. Note that even if there is no overflow, if the ratios of the radii lengths, or the ratio of the magnitude of `obspos' and the shortest radius vary by many orders of magnitude, the results may have poor precision. 9) If the computation `method' is not recognized, the error SPICE(INVALIDMETHOD) is signaled by a routine in the call tree of this routine. 10) If the loaded kernels provide insufficient data to compute the requested state vector, an error is signaled by a routine in the call tree of this routine. 11) If an error occurs while reading an SPK or other kernel file, the error is signaled by a routine in the call tree of this routine. 12) If the aberration correction `abcorr' is not recognized, an error is signaled by a routine in the call tree of this routine. 13) If `target' is on the Z-axis ( x = 0 and y = 0 ) of the local topocentric frame centered at `obspos', an error is signaled by a routine in the call tree of this routine. See item 2 in the -Restrictions section for further details. 14) If any of the `method', `target', `abcorr', `obsctr' or `obsref' input string pointers is null, the error SPICE(NULLPOINTER) is signaled. 15) If any of the `method', `target', `abcorr', `obsctr' or `obsref' input strings has zero length, the error SPICE(EMPTYSTRING) is signaled. ## FilesAppropriate kernels must be loaded by the calling program before this routine is called. The following data are required: - SPK data: ephemeris data for the observer center and target must be loaded. If aberration corrections are used, the states of the observer center and target relative to the solar system barycenter must be calculable from the available ephemeris data. Typically ephemeris data are made available by loading one or more SPK files using furnsh_c. - Shape and orientation data: if the computation method is specified as "Ellipsoid," triaxial radii for the center body must be loaded into the kernel pool. Typically this is done by loading a text PCK file via furnsh_c. Additionally, rotation data for the body-fixed, body-centered frame associated with the observer's center of motion must be loaded. These may be provided in a text or binary PCK file. In some cases these data may be provided by a CK file. The following data may be required: - Frame data: if a frame definition not built into SPICE is required, for example to convert the observer-target state to the body-fixed body-centered frame, that definition must be available in the kernel pool. Typically frame definitions are supplied by loading a frame kernel using furnsh_c. - Additional kernels: if a CK frame is used in this routine's state computation, then at least one CK and corresponding SCLK kernel is required. If dynamic frames are used, additional SPK, PCK, CK, or SCLK kernels may be required. In all cases, kernel data are normally loaded once per program run, NOT every time this routine is called. ## ParticularsThis routine computes azimuth/elevation coordinates of a target as seen from an observer whose trajectory is not provided by SPK files. Observers supported by this routine must have constant position with respect to a specified center of motion, expressed in a caller-specified reference frame. The state of the center of motion relative to the target must be computable using loaded SPK data. This routine is suitable for computing the azimuth/elevation coordinates and its derivatives of target ephemeris objects, as seen from landmarks on the surface of an extended object, in cases where no SPK data are available for those landmarks. The azimuth/elevation coordinates are defined with respect to the observer's local topocentric reference frame. This frame is generally defined as follows: - the +Z axis is aligned with the surface normal outward vector at the observer's location; - the +X axis is aligned with the component of the +Z axis of the body-fixed reference frame orthogonal to the outward normal vector, i.e. the +X axis points towards the body's North pole; - the +Y axis completes the right-handed system. For observers located on the +Z axis of the body-fixed frame designated by `obsref', the following definition of the local topocentric reference frame is used by this routine: - the +Z axis is aligned with the surface normal outward vector at the observer's location; - the +X axis aligned with the +X axis of the body-fixed reference frame; - the +Y axis completes the right-handed system. In both cases, the origin of the local topocentric frame is the observer's location. ## ExamplesThe numerical results shown for this example may differ across platforms. The results depend on the SPICE kernels used as input, the compiler and supporting libraries, and the machine specific arithmetic implementation. 1) Find the azimuth/elevation state of Venus as seen from the DSS-14 station at a given epoch first using the position of the station given as a vector in the ITRF93 frame and then using the data provided in the kernel pool for the DSS-14 station. Task description ================ In this example, we will obtain the apparent state of Venus as seen from DSS-14 station in the DSS-14 topocentric reference frame. For this computation, we'll use the DSS-14 station's location given as a vector in the ITRF93 frame. Then we will compute same apparent state using spkpos_c to obtain a Cartesian state vector, after which we will transform the vector coordinates to azimuth, elevation and range and their derivatives using recazl_c and dazldr_c. In order to introduce the usage of the logical flags `azccw' and `elplsz', we will request the azimuth to be measured clockwise and the elevation positive towards the +Z axis of the DSS-14_TOPO reference frame. Results from the two computations will not agree exactly because of time-dependent differences in the orientation, relative to the ITRF93 frame, of the topocentric frame centered at DSS-14. This orientation varies with time due to movement of the station, which is affected by tectonic plate motion. The computation using ## Restrictions1) This routine may not be suitable for work with stars or other objects having large distances from the observer, due to loss of precision in position vectors. 2) The Jacobian matrix of the transformation from rectangular to azimuth/elevation coordinates has a singularity for points located on the Z-axis ( x = 0 and y = 0 ) of the local topocentric frame centered at `obspos'; therefore the derivative of the azimuth/elevation coordinates cannot be computed for those points. A user who wishes to compute the azimuth/elevation coordinates, without their derivatives, of `target' as seen from `obspos' at the input time `et', for those cases when `target' is located along the local topocentric Z-axis, could do so by executing the following calls: spkcpo_c ( target, et, obsref, "OBSERVER", abcorr, obspos, obsctr, obsref, state, < ); range = vnorm_c ( state ); By definition, the azimuth is zero and the elevation is either pi/2 if `elplsz' is SPICETRUE, or -pi/2 otherwise. ## Literature_ReferencesNone. ## Author_and_InstitutionJ. Diaz del Rio (ODC Space) ## Version-CSPICE Version 1.0.0, 01-NOV-2021 (JDR) ## Index_EntriesAZ/EL_coordinates relative to constant_position_observer AZ/EL_coordinates w.r.t. constant_position surface_point AZ/EL_coordinates relative to surface_point extended_object AZ/EL_coordinates relative to landmark on extended_object |

Fri Dec 31 18:41:01 2021