Graphics.ExampleDrivingOfPlanetsWithRecordedData - lordmundi/wikidoctest GitHub Wiki
Example Driving of Planets with Recorded Data
« EDGE 3D TV Tutorial | EDGE User’s Guide | Setting up a Control Node »
Introduction
This is a brief tutorial showing how you might do a simple driving of planet bodies in EDGE using some recorded data from a simulation. This is meant only as a starting point as your simulation may want to make more frames available in graphics or use different frames. But hopefully this tutorial will spark ideas on how you might format your data or API file to get to the visualization you need for your simulation.
CSV files
One of the data formats that the simdata plugin supports reading is comma separated data. It is a super-simple text based format and you can read more about it here. We are using this format in this tutorial because it seems that any simulation could be adapted to output data in this format for post-sim visualization with EDGE graphics.
Simdata Plugin
Since we are visualizing our data after the simulation has run, we refer to that as "post-sim" visualization. To do this, we use the features of the simdata plugin and its associated GUI. If you are unfamiliar with using the simdata plugin, you can read the following wiki articles to understand how we will be using it:
Seeing the Data
Start a new Userdata directory
If you are unfamiliar with the userdata directory, you can read about it here. Basically, it is a directory to keep all of the settings for a project so that it isn't mixed in with the EDGE product (which would make upgrades messy and hard). For this tutorial, you should copy the included template directory called "userdata" to a new directory called "userdata.planet_example" or something similar and then make your customizations inside that directory. If you are running on linux or mac, you will select this userdata directory before running by setting the environment variable $USERDATA before you run. If you are windows, the easiest way to select a different userdata directory is probably to duplicate the .bat file and edit it to use your new directory rather than the included template directory.
Downloading Example Files
The first step in this tutorial is to download the two example files we will be using. The first is a csv file that has the actual data with the recording of the variables for the planets in it. The second is the API file which maps a variable in the data file to a field in a node inside the graphics. For example, the pitch value of node A might be mapped to the variable in the simulation "node_A_pitch_value". You can read the API file reference linked to in the section above to understand more about how API files work.
You can download these two files below. Place them in your "userdata.planet_example/sim_data" directory.
Visualize the Data with the Simdata Plugin
Run EDGE using the "run_graphics" startup script for your platform while pointing to your new userdata.planet_example directory. You should see the standard default camera view looking at ISS and a docking capsule with the Earth in the background. Click on "Options→Sim-Data Dlg…" The simdata gui will appear. The first thing we want to select is the API file so click the API File text to the left of the field and then click "Browse". Navigate to the API file you downloaded (which should be in your $USERDATA/sim_data directory) and select it.
Next you will select the data file to use. Click the "Data Source" text, then select the "Recorded" sub-menu. The previous directory you used for the API file will probably be remembered, so you may see your .csv file available in the quick menu. Select it and it will load the data. If you don't see it in the quick list, feel free to click "Browse" and navigate to it just as you did for the API file. If you don't see it in the directory when you browse to it, make sure the file filter at the bottom of the browsing window is set to "CSV Files (*.csv)".
Now that the data is loaded, use the VCR controls to play the data. The play button will start playing through the data at 1X playback speed. The radio buttons above allow you to switch this to 2X, 4X, or any custom speed you wish. You can also drag the slider back and forth, set begin and end marks, repeat between the begin and end marks, etc.
Understanding Frames and the Data
What Are We Seeing?
This data is not accurate! It doesn't represent anything validated or tested in any way - it is simply meant to be some example data for learning purposes. With that out of the way, this data has some example motion of the Earth, Moon, and Sun around an Earth inertial frame and is recorded at about 3000x realtime. So, playing the data at 1X represents roughly 3000x realtime.
NOTE: Most nodes in EDGE are in the PYR sequence/order but some nodes, such as EARTH_BODY_REF, are in a PRY order (or potentially other orders). Be sure to calculate your Euler angle data to be in the same order as the node order. You can either change the order of the node you are working with, or change the calculation of your data. To change the order of a node, you can edit your BASE_STATE or you can change the order through a tcl command and then save the state. See the UsingTheDougNodeTclCommand page to see how to get or set the node Euler angle order.
Playing the data, you will see the lighting changing on the earth as the sun and stars go by due to the Earth rotation. You can see the data going into these nodes by clicking "Edit→Nodes" then clicking the "All" button and typing EARTH_BODY_REF into the search box at the bottom. Double click on the node entry called EARTH_BODY_REF and you will see the data for that node. If your data is playing, you will see the rotation of the Earth being updated from the data. Similarly, search for the MOON node and see the data going into it. You will notice that its position and rotation are being updated from the data. This is because the root frame we are driving the planets from is located at the center of the Earth. This explains why the driving of the EARTH_BODY_REF node has zeroes for the position data and is updating rotation only. See the following diagram to understand how the tree is structured and the nodes being driven in the example:
When you first start playing the data looking through the default camera, you might notice that the Earth is not turning below the ISS and space vehicle. The sun and stars and moon are going around the earth, but the earth isn't turning. This is because the camera you are looking through, called "CM_Cam", is linked to the command module of that space vehicle, which is linked to the EARTH_CENTER node. Since the Earth is rotating, and the camera is linked to it, the camera will move with the Earth and no relative motion will be apparent.
Flying the Camera Out
Often times you will want to take a camera and fly it far distances. Using the standard key controls defined in the User's Guide, you can fly around small distances easily. To fly long distances, you will want to use Speedfly which is also discussed in the User's Guide. This will let you get full views of a planet and watch the terminator move from the lighting change, for example. If you assign the "MoonCam" camera by right clicking on the view, clicking "Assign Camera", then selecting "MoonCam", you will see a view that is attached to the MOON node. Fly this camera out using the speedfly keys ("+" and "-" on the keyboard to scale the translation rates up and down) until you can see the terminator. Now, dragging the simdata slider back and forth you should be able to see motion of this terminator due to the motion of the Moon around the Earth.
Re-linking the Camera
As mentioned in a previous section, the default camera of CM_Cam is linked to the Earth, so it doesn't see the Earth turning when the data is played. To understand this further, trying linking the camera to NULL. You can do this by clicking "Edit→Nodes", searching for the node "CM_Cam", double clicking it, then changing the Parent field at the bottom to "NULL". Once you do this, you will see the Earth rotation in the CM_Cam node since it is no longer attached to the Earth in the scene.
Examining the Data File
Open up the .csv file in a text editor and you will see that it basically consists of a header row that says the variable names. Please read the CSV article linked to above to better understand the format, but in general, the first row is the main thing to get correct in order for things to work in EDGE. The first variable name that represents the time values should always be the "sys.exec.out.time {s}" string. After that, the variable names can be whatever you like. The unit specification in the braces {} is the specification for what unit is recorded in the file (or the input unit if it helps to think of it that way). In the API file, there is another unit specification - this is the output unit. Simdata will do its best to convert from the input unit to the output unit for you. For example, if your data has angles recorded in radians, then generate the .csv file and put the unit specification for the field to be "{r}" and in the API file, specify the output unit to be "d". This way, simdata will automatically provide a radians to degrees conversion for you. Similarly, another common conversion is input data recorded in meters "{m}" and output to graphics via the api file in inches "in". You can see examples of this in the example data delivered with EDGE in the sim_data directory. There is an example .csv file in there as well as the cev_graphics.api file. In addition to the files provided in this tutorial, those can provide another example that can be helpful.
Make Navigation to the Data Files Quicker
Navigating to the $USERDATA/sim_data directory might be a pain when you restart graphics. The good news is you can default this directory inside your $USERDATA/user.cfg file. At the top of this file, in the DEFINES block, you can define a variable called SIM_DATA_DIR which is the default directory that the simdata gui will look for API and Data files. If you assign this to your ${USERDATA}/sim_data directory (which is commented out for you at the top of user.cfg usually), then this will make picking the API and Data files much quicker when you restart graphics.
Next Steps
Generating Your Own Data
One obvious next step from this tutorial is to take your program or simulation that is propagating the planetary bodies and configure it to output the time based data in the same format as the example file. Take care to make the header row correct and get the right units in the header row and API file, and it should be pretty easy.
Driving More Planet Bodies
Other simulations might want to drive more planetary bodies such as Mars, Jupiter, Mars moons, asteroids, etc. You would likely need to add in nodes and possibly models to visually represent these bodies in graphics.
Adding Nodes for Inertial Frames
Another thing you might want if you have a simulation driving planetary bodies is additional nodes representing the inertial frames of these bodies. For example, you may have a node called MOON_INERTIAL which represents an inertial frame for the moon that is driven with respect to your frame of reference, and then another "BODY_REF" frame which is parented to the inertial node which has the rotational component to get from the inertial node to the body node. For this setup you would need to add in nodes for all your inertial nodes and then reparent the planet-fixed frames to these inertial nodes. Once you make these inertial nodes you can manually reparent the body nodes to them using the node edit dialog and then click "File→Save State" to save off this new tree state with the modified parenting. Then, in your $USERDATA/user.cfg file you can specify the "BASE_STATE" define to point to your modified state as the state used on startup, that way the modified topology is used anytime you use that userdata directory.
Driving With Live Simulation Data
This example is visualizing data after a simulation has finished executing and has recorded the data to a file. Another potential next step is to communicate out these planet frame positions to the graphics in real-time and update the graphics as the sim executes. This could be useful if there is hardware or a human in-the-loop with the simulation. There are many ways you can hook up a simulation to the graphics, including using the DCOMM library, writing a custom socket communication in a tcl script, writing socket communication in a C plugin, using the simdata live simulation connection and extending the source code to work with your simulation data, and possibly others.
« EDGE 3D TV Tutorial | EDGE User’s Guide | Setting up a Control Node »