« Using the simdata plugin for data playback | EDGE User’s Guide | CSV Formatted Data With the Simdata Plugin »

This is the new API file reference documentation for versions of EDGE 2.1 and above. For older versions, see this page.

The API file is a file used to map graphics nodes to simulation variables. There are two types of mappings: direct mappings, and transforms.

Direct mappings have the following syntax:

<node_name> <simulation_variable_name> <node_dof>  <destination units>  write <scale_factor>

As an example:

STATUS_DYN_OV     graphics.chutes.out.pos[0]   x      M   write  1.0

This will convert the value found in "graphics.chutes.out.pos[0]" to meters (if necessary), and then drive the "x" DOF of node "STATUS_DYN_OV" with it.

An example of an orbital body mapping:

ISS_SIM_POS  graphics.orbital.element[5].out.ecef_to_gmf.location[0]  x   in   write  1.0
 ISS_SIM_POS  graphics.orbital.element[5].out.ecef_to_gmf.location[1]  y   in   write  1.0
 ISS_SIM_POS  graphics.orbital.element[5].out.ecef_to_gmf.location[2]  z   in   write  1.0
 ISS_SIM_ATT  graphics.orbital.element[5].out.ecef_to_gmf.euler_angles[0]  pitch  d   write  1.0
 ISS_SIM_ATT  graphics.orbital.element[5].out.ecef_to_gmf.euler_angles[1]  yaw    d   write  1.0
 ISS_SIM_ATT  graphics.orbital.element[5].out.ecef_to_gmf.euler_angles[2]  roll   d   write  1.0

The simdata plugin will look at two units:

• the source unit: the unit specified in the header file that says in what the unit the simulation variable is recorded in
• the destination unit: the unit specified in the API file (see above) that says in what unit the variable should be converted to

Getting unit declarations that work well using both comm and the simdata plugin can sometimes get a bit hairy. Here is our suggestion to avoid the most headaches:

• Keep data declared in the sim in meters (the variables you are recording… nothing else matters here), even if it is just data such as on/off flags that doesn't represent distances.
• Convert distances and angles to inches and degrees using the API file as shown in the example above
• Use meters ("M") in the api file when the data in the node is just being used for flags or other data that you don't want converted. By using "M" as the unit (as in the STATUS_DYN_OV example above), the parser sees the same unit as the input unit in the header file and no conversion is performed.

An API transform calls a function to convert input parameters from the sim to output parameters mapped to node names.

transform <transform_function> <transform_library>
 in <type> <alias1> = <param1>
 in <type> <alias2> = <param2>
 &hellip;
 out <type> <nodespec1> = <alias1>
 out <type> <nodespec2> = <alias2>
 &hellip;

As an example: calling an orbital transform for the CM

transform orbital_transform_ecef orbital_transform.so
 in vec3 cm = cev_cm_veh.body.core.mass.properties.cm
 in vec3 inertial_pos = cev_cm_veh.body.core.orbit.trans.inertial_pos
 in mat3 T_struct_inertial = cev_cm_veh.body.core.orbit.rot.T_struct_inertial
 in mat3 T_structure_body = cev_cm_veh.body.core.orbit.rot.T_structure_body
 in mat3 rnp = env.bodies.body[3].state.rnp.out.RNP
 in mat3 T_lvlh_inrtl = cev_cm_veh.pdyn.post_rot.T_lvlh_inrtl
 out vec3 CEV_CM_SIM_POS.xyz = pos
 out vec3 CEV_CM_SIM_ATT.pyr = att
 out vec3 CEV_CM_COM_POS.xyz = lvlh_pos
 out vec3 CEV_CM_LVLH_ATT.pyr = lvlh_att

Acceptable types are "double", "vec3", and "mat3" for a double parameter, a 3-vector, or a 3×3 matrix, respectively. Parameters of type vec3 have their names expanded with indices, so that foo maps to the three variables foo[0], foo1, and foo2. Similarly, mat3's are expanded to nine variables — foo[0][0]-foo[2][2].

Input and output aliases are intended to be short names that are referenced within a transform. This way, transforms can be written generically using aliases like "cm" for center of mass rather than specifying the specific variable to be transformed. In the stock distribution, for example, there is only one orbital transform function which is applied to the CM, SM, stages, etc. Within a transform function, variables are referred to by their aliases. For example, the following transform takes an input value aliased as "pitch" specified in radians, and transforms it to an output also aliased as "pitch" specified in degrees:

#include <cmath>
 void mytransform(Values& in, Values& out)
 {
     out["pitch"] = in["pitch"] * 180/M_PI;
 }

The corresponding API file might look like this:

transform mytransform mytransform.so
 in pitch = some.var.from.the.sim.pitch
 out SOMENODE.pitch = pitch

EDGE node values are specified as NODE.parameter (e.g. NODE.x, NODE.pitch). There are two additional convenience nodespecs. NODE.xyz maps a vector of 3 values to the x,y, and z components of NODE, while NODE.pyr maps a vector of 3 values to the pitch, yaw, and roll components respectively.

« Using the simdata plugin for data playback | EDGE User’s Guide | CSV Formatted Data With the Simdata Plugin »