Graphics.DspDrawstar - lordmundi/wikidoctest GitHub Wiki

Dsp Drawstar

Author: Andrew Rhodes

On this page… (hide)

  1. 1. Background
    1. 1.1 Stellar Aberration
    2. 1.2 Star Catalog
  2. 2. Necessary Files
    1. 2.1 Plugin Code
    2. 2.2 Star Catalog
    3. 2.3 Vertex Shader
    4. 2.4 TCL Script
    5. 2.5 Default Shaders
  3. 3. Configuration and Setup
    1. 3.1 User Config Files
    2. 3.2 Trajectory CSV Files
    3. 3.3 Trajectory API Files
  4. 4. Building
    1. 4.1 EDGE v2.3
    2. 4.2 EDGE v2.4.1

1.  Background

1.1  Stellar Aberration

Stellar aberration is an apparent displacement of stars from their true location due to effects of special relativity. Stars are always producing light, but by the time that light reaches the viewer, the star has moved to a new location. Thus our estimated star location is not the current true location. The effects are on the order of velocity / speed_of_light. Stellar aberration is important to characterize because it will apparently displace the star location in an image by a single pixel or more (for the Orion EM1 OpNav camera)! One pixel may not seem significant, but it is 5 times the allowable error budget for centroiding stars in the image (for this mission).

1.2  Star Catalog

Star catalogs contain information on star locations and other attributes for a given day and time. For example, the Hipparcos catalog is for April 2nd, 1991 at 2.5625 TT. The problem with the stars is that the move over time. So when we see the stars today, that is not where they appeared in 1991, or even yesterday. Therefore, it is important that you process your star catalog for the specific date and time in which you plan to run your simulation. If you are simulating a trajectory on October 8th, 2018, then the star catalog must be processed for the same date. Of course, this is only if you are attempting precision camera calibration with the stars.

2.  Necessary Files

2.1  Plugin Code

The dsp_drawstar.c plugin that is natively include in EDGE v2.4 was slightly modified to read in a few ways. This code attached here is the new drawstar plugin with the changes. Place this plugin in the src.dist/plugins/ directory.

I modified the way that the plugin reads the star catalog. I also added enough variables and commands to pass the vehicle velocity along to the vertex shader. More specifically, I've added

Line 346: static float cube_velocity3 = {0.0, 0.0, 0.0};

Line 373: static GLint velocity_location = 0;

Line 741: DOUG_glUniform3fARB( velocity_location, cube_velocity[0], cube_velocity1, cube_velocity2);

Line 920: sscanf( pc, "lf, %f", &ra, &dec, &mag );

Line 2009: velocity_location = DOUG_glGetUniformLocationARB(ShaderProgram, "velocity");

Line 2023: /* || velocity_location == −1 */

Notice that Line 2023 is commented out. If the default shader is being used, then velocity data is not being used, and this would cause EDGE to stop running. I left it as reference, so that no one else tried to add it in the future. I also commented out reference to star hash_id and name, both elements in the STAR structure. They weren't being used, and I didn't add them in the new star catalog

2.2  Star Catalog

The catalog called stars.bsc that is included in EDGE will not function with the modifications to this plugin. Please use this catalog of stars with the plugin. I was forced to save it as a .txt file, but make sure that the extension matches that which is written in the Stars Config file (referenced below). It is a comma separated text file of star magnitude, right ascension, and declination written in the format

Star_Ra, Star_Dec, StarMag

The catalog included in EDGE does not have a known epoch. The catalog given in this section is the Hipparcos star catalog for 8th October, 2018. If you are attempting to display stars on a certain day and time, then this catalog will need to be rewritten with your specific data.

Place the star catalog in the models/ directory.

2.3  Vertex Shader

All the heavy lifting of applying stellar aberration to the stars is performed in the vertex shader. I've called this shader "stellar_aberration_stars.vs". Please download it here. I was forced to save it as a text file, but please change the extension to .vs when using in EDGE.

Place this shader in the userdata/shaders/ directory.

2.4  TCL Script

The tcl script is responsible for continually retrieving the vehicle velocity from the trajectory file and feeding it to the drawstar plugin. It is titled "StellarAberration.tcl" and is included here.

Place this file in the userdata/scripts/ directory.

2.5  Default Shaders

If you are working in EDGE v2.4, then disregard this section. I took the dsp_drawstar.c plugin from EDGE v2.4 and moved it to EDGE v2.3 so I also needed to move the default shaders. The plugin looks for the default star shaders in the src.dist/plugins/examples/ directory. So download the c version of the Vertex Shader and the c version of the Fragment Shader and place in the src.dist/plugins/examples/ directory.

3.  Configuration and Setup

Now that the proper files are placed in your EDGE version, they must be included in the operation path for them to be used.

3.1  User Config Files

There are a few user config files that must be modified to include the new files.

Stars Config

If you have uploaded a new star catalog, or used the one included in this document, you will need to inform EDGE which star catalog to use. Go to the configs/ directory and open "stars.cfg". Then in the command_line section, change it to the location of your star catalog which should look something like this

command_line

{
                -plugin stars '-node STARS -viewdata_exp 38.0 -min_col 0.001 -input "${DOUG_HOME}/models/allstars.bsc"'
            }

Change the "allstars.bsc" to the name of you star catalog. Remember to follow the format stated above for the star catalog. The .bsc stands for bright star catalog, but it is simply a text file, so it could also have the extension .txt of you desired.

Fancy Stars Config

This file is where the user defines the vertex shader to use, if they are not using the default shader. As a reminder, the default shader does not display stars with stellar aberration. If you are not interested in applying stellar aberration to the stars, then use the default vertex shader included with EDGE (this requires no input from the user).

Go to the configs/directory and open "fancy_stars.cfg". In the command_line section add the new vertex shader as

command_line

{
	-vertex_shader ${USERDATA}/shaders/stellar_aberration_stars.vs
    }

This will change the selected shader to "stellar_aberration_stars.vs" instead of "default_stars.vs". If you want to use the default shader, but also don't want to delete this line, simply place the pound symbol (#) in front of the command like

command_line

{
	# -vertex_shader ${USERDATA}/shaders/stellar_aberration_stars.vs
    }

I suggest not loading this shader unless you actually want to use it. Technically, if you used this shader without velocity data, then it would effectively function the same as the default shader. No need to push your luck though.

User Config

This is where we will load the TCL script that continually loads the vehicle velocity to the drawstar plugin. Go to the userdata/ directory and open "user.cfg". Down near the bottom in the Display{ ENG_Graphics{ DOUG{ TCL{} } } } section add the tcl script. It will look like this

TCL

{
			Stellar_Aberration "${USERDATA}/scripts/StellarAberration.tcl"
                 }

Once again, if you don't want to load the tcl script, but also don't want to delete the line, then simply place a pound symbol (#) in front of the line. Again, I suggest not loading this tcl script unless you intend to use it.

User Models

To introduce vehicle velocity into the simulation, a new node was created to hold the velocity information. Go to the userdata/configs/ directory and open "user_models.cfg. Under the models sectioni in the DSP_CONFIG{} section, add the new model as

MODELS

{
				node(CUBE_VEL); xyz( 0.0, 0.0, 0.0 ); pyr( 0.0, 0.0, 0.0); parent(NULL);
            }

Notice that the node CUBE_VEL has components, x, y, z, p, y, and r, but no vx (x velocity), vy, or vz. Nodes in EDGE natively do not have velocity attributes. This is okay, we'll pretend that the x,y,z attributes stand for velocity. The reason that this node is placed here is because it is a system node, not a camera or model. In addition, the name of this node must match that of the node in Trajectory API File Section.

3.2  Trajectory CSV Files

A trajectory file gives a list of position and attitude values for objects in the simulation. In the case of the cube cam simulating the camera for Orion OpNav, the trajectory file includes positions and attitudes of the moon, earth, sun, and cube (Orion camera). To add information regarding the cube velocity, you should append three columns for the x, y, z velocities. These may have any name that you want, but must match the attribute names in the Trajectory API File section. Here is an example of what the attribute names should be

VEHICLE_HELIO_VX {m}, VEHICLE_HELIO_VY {m}, VEHICLE_HELIO_VZ {m}

This says that VEHICLE_HELIO_VX has units of {m}, which is meters. Obviously, the vehicle velocity is not in units of meters, but EDGE does not natively work with velocities. We must trick EDGE into thinking that this attribute is consistent with the simulation. The real units must ALWAYS have units of kilometers per second, but be listed as {m}. This is because I defined the speed of light in kilometers per second.

3.3  Trajectory API Files

The API files inform EDGE how to translate the trajectory .csv file into simulation variables. More information on how they function can be found on the API page. I will show here how to add the CUBE_VEL node to the .api file. Suppose the trajectory .csv file had three columns relating to vehicle velocity. Then in the corresponding rows in the .api file, it would have

CUBE_VEL VEHICLE_HELIO_VX x m write 1.0

CUBE_VEL VEHICLE_HELIO_VY y m write 1.0

CUBE_VEL VEHICLE_HELIO_VZ z m write 1.0

where CUBE_VEL is the node created in the user models, VEHICLE_HELIO_VX etc. are the attribute names included in the trajectory csv file, and m is the units of the item. Note that velocity doesn't actually have units of meters (m), but we trick EDGE into thinking that it does so that no transforms are applied to the attribute information. In fact, for the stellar aberration to be applied correctly, the vehicle velocity MUST be in kilometers per second. The node CUBE_VEL may be named whatever you desire, but it must be the same as the node name in User Models Section.

4.  Building

Since you added a new plugin to the EDGE distribution, you will need to recompile it. I assume you are working in Linux.

4.1  EDGE v2.3

If you took the dsp_drawstar.c plugin from EDGE v2.4 and moved it to EDGE v2.3 (like I did), then this is how you will compile EDGE with the new plugin. In a terminal, navigate to src.dist/plugins/ folder and type make. If you receive any errors, refer to the Release Notes.

4.2  EDGE v2.4.1

In a terminal, navigate to src.dist and type make. If you have any errors, refer to the Release Notes.