op_ima_obj_pos_get_time()
Abstract
Obtains the values of a site or antenna object’s global position-related attributes for the current simulation time or extrapolates their values for a future simulation time.
Syntax
op_ima_obj_pos_get_time (site_objid, time, lat_ptr, long_ptr, alt_ptr, x_ptr, y_ptr, z_ptr)
| Argument | Type | Description |
|---|---|---|
site_objid |
Objid |
object ID of the object-of-interest [A site object ID can be obtained from several KPs in the Id and Topo packages: op_topo_parent(), op_topo_child(), op_id_from_userid(), and op_id_from_name().] |
time |
double |
simulation time of interest |
lat_ptr |
double* |
latitude of the specified object (filled in by this KP) |
long_ptr |
double* |
longitude of the specified object (filled in by this KP) |
alt_ptr |
double* |
altitude of the specified object (filled in by this KP) |
x_ptr |
double* |
Cartesian X coordinate of the specified object (filled in by this KP) |
y_ptr |
double* |
Cartesian Y coordinate of the specified object (filled in by this KP) |
z_ptr |
double* |
Cartesian Z coordinate of the specified object (filled in by this KP) |
Return Type
Compcode
Completion code indicating whether the operation completed successfully.
This code can be compared to the two symbolic constants OPC_COMPCODE_SUCCESS and OPC_COMPCODE_FAILURE.
Example
/* This line assigns the ID of the parent node object (the object */
/* which contains this processor module) to the variable rx_node_id... */
rx_node_id = op_topo_parent (op_id_self ());
/* This line determines the ID of the subnet object... */
subnet_id = op_topo_parent (rx_node_id);
/* This line assigns the object ID of the transmitter node to the */
/* variable tx_node_id... */
tx_node_id = op_id_from_name (subnet_id, OPC_OBJTYPE_NODE_FIXED, "tx");
/* This line uses op_ima_obj_pos_get_time() to retrieve the transmitter */
/* node object’s global position values... */
comp_code = op_ima_obj_pos_get_time (tx_node_id, op_sim_time(), &latitude,
&longitude, &altitude, &x_pos, &y_pos, &z_pos);
Details
The position obtained by this KP is stated in terms of two coordinate systems:
- the geodetic coordinate system of {latitude / longitude / altitude}
- the geocentric coordinate system of {X / Y / Z}
The geodetic coordinate system has units of degrees (for latitude and longitude) and meters (for altitude). The geocentric coordinate system has units of meters for all three coordinates; this system is discussed extensively in “Geocentric Coordinate System“ on page 317. An invocation of this KP causes the Simulation Kernel to extrapolate the position of the specified object for the specified time; in the case of trajectory-based mobile or satellite sites, the position is looked up in a table and interpolated between the two closest points in time. Time must be at least equal to the current simulation time.
Mobile site position evaluation is not continuously or regularly performed by the Simulation Kernel; it only performs evaluations when required by the radio Transceiver Pipeline stages, when the position attributes are queried, or when this KP is invoked, thus reducing the computational overhead of a network with many mobile sites which communicate sparsely in time. In the case of vector-based mobile or satellite sites, site position is computed based on the bearing, ground speed, and ascent rate attributes.
Purpose
Provides a convenient mechanism to obtain all six global position-related attributes of a site (node or subnet) or antenna object from a single procedure invocation. The reason for having a special Ima package KP perform this operation is that the position attributes of an object have different interpretations depending on whether the object is within a subnet or not (for example, top-level sites have position attributes that are in terms of the geocentric coordinate system, but sites within subnets have position attributes that are in terms of a subnet-position relative Cartesian coordinate system). This KP converts the different types of position attributes into two common geocentric position coordinate sets.
Errors
- Program Abort: Segmentation violation. (due to an invalid coordinate pointer)
- Recoverable Error: Object ID (
<site_objid>) is out-of-range. - Recoverable Error: Object (
<site_objid>) has incorrect type; node or antenna objects are expected. - Recoverable Error: Object ID (
<site_objid>) refers to a restricted object. - Recoverable Error: Simulation time is past requested time (
<time>)
Reference
- Use the KP op_ima_obj_attr_get_dbl() to obtain a single position-related attribute of a site for the current simulation time.