Data Format and Input

In this section we will discuss how Partiview data is formatted and take you through the steps necessary to display data in Partiview. Note that we give a step-by-step recipe of this information in “Importing Your Data.”

Test Data Files

Now that we have seen the Test Data set in Partiview, let's look at the actual files that make up the data set to understand how the files are formatted. A listing of files can be found in Table 2.1. Data files in Partiview can have any extension; however, we recommend using .speck for data files and .cf for config files. There can be a separate label file as well with the extension .label, but these data can also appear in the .speck file, creating less files to clutter your folders.

test.speck

If you open this file in a simple text editor, you will find some commands along with the data listing. The test.speck file should be in the mandata folder, which is in the data folder located where you are running Partiview.

Looking at that file, you will see a number of lines throughout the file that begin with the ‘#’ symbol. As many programmers will recognize, this indicates a comment in the file, a line that will be ignored by Partiview and is useful for comments and notes. Data in Partiview take the form:

x y z datavar0 datavar1 ... datavarN

where x, y, and z are the 3-D coordinates of the point and the datavars are pre-defined data variables that are used to describe the point, such as luminosity, color, etc. These data variables are not necessary though; Partiview will take files with just x, y, z data.

In test.speck we define one data variable called txnum which is the texture number assigned to that point. While they are all the same for each point, we need to specify a texture number to load an image (or texture) on a polygon. It should be noted, however, that the first three columns of any data file are reserved for x, y, and z. Therefore, column 4 will be data variable (or datavar) 0, if it exists.

The first line of this file (after commented lines) reads

datavar 0 txnum

By issuing this command in the data file, we are setting a data variable called txnum to data variable 0 which is column 4 in the data file. The datavar command is used to define any data that we want associated with each x, y, z point. For example, in a stellar data set one may want to include information on each star's brightness, its color, and its luminosity. This is possible by writing those attributes to your data file and defining them using the datavar command.

While we have defined column 0 to be this variable called txnum, we need to explicitly tell Partiview which column contains the texturing information. This is done in the next line with the texturevar command, which sets the value to txnum, the data variable assigned to represent the texture number for each particle. Finally, we need to associate the value of the txnum to an image. Using the texture Data Command, we assign a texture number of 1 (corresponding to the values in column 4) to a file called halo.sgi.

test.label

The label file is just what you might imagine it to be, a file containing labeling information. As we stated earlier in this section, labeling information can be placed in a .speck file, reducing the clutter in your file system. However, for large data sets, it makes sense to have a separate .label file to keep your data better organized. In Partiview, the text command is used to place text at a specified point. A label takes the form

x y z text yourlabel

where x, y, and z are the location of the label and yourlabel is the label for that point. The label can have spaces, commas, and other non-alphanumeric characters.

test.cf

The test.cf file is the config file for the Test Data. Config files are composed of Partiview commands that are read and executed at start-up. These commands load the data, configure the data display, and set various Partiview preferences.

If you inspect the test.cf file, you will notice the first two lines (that are not comments) are the commands that read in the data using the include data command. Note that many of these commands begin with the word eval. The eval command is the necessary prefix for a Control Command if you wish to issue it within a data file, rather than interactively at the Command Line. We discuss the difference between Control Commands and Data Commands in the section about loading data. We will discuss the commands you see in this file throughout this chapter.

Adding Data in Partiview

While we touched on the topic of loading data earlier in this guide, we will offer a more through discussion here. Let's start from scratch with an empty canvas, if you will. Start Partiview without any data by either double-clicking on the partiview executable file or running it in a shell.

Adding Data Manually

In Partiview, data can be manually added at the Command Line via the command:

add x y z

Of course, when data are read in via a file, which is the primary way in which you will want to import data, you need not preface it with the add command . However, because we are executing a Data Command at the Partiview Command Line, the add preface is required (as it is for all Data Commands issued from the Command Line). Try adding a few data points in Partiview by entering these commands.

add 1 1 1 add -1 -1 -1 add 0.5 0.5 0.5 add -0.5 -0.5 -0.5

You will notice that nothing happened. This is because you need to tell Partiview about the display characteristics of these points, specifically, how bright they are. All display parameters have defaults and the default for a particle's luminosity is zero. You can confirm this by typing lum at the Command Line. This will report the current luminosity, which should read “lum-by 0 [0..0 mean 0],” a zero value for the luminosity. You may set the luminosity to a constant value by typing the command

lum const 500

You may need to fly away from the Point of Interest a little to see all the points, which should form a line of four blue points.

Reading Data from a File

While instructive, it is inefficient to type in all your points at the Command Line. So, let's read some data from a prepared data file. We will read in the file complex.speck, the complex version of the Test Data. First, we need to specify a file path, telling Partiview where the data files are.

**Figure 3.2:** The hierarchy of files and folders in the Partiview User's Guide data set.

The Complex Data can be found in the mandata folder, which is located one directory level down from the directory that contains both the data folder and the partiview executable (see Figure 3.4).

Once you have the data prepared (which has already been done in this case), step one involves telling Partiview where the data files are located. This is accomplished using the filepath command . Because this is a Data Command, you must preface this command with add if you're going to use it interactively at the Partiview Command Line. Now that we know where the files are, we can issue the command

add filepath ./data/mandata

(NOTE: You may need to type the entire path to the folder, e.g., /Users/youraccount/partiview/data/mandata.)

This command will set the file path to include all files in the mandata directory.

Rather than read the data into the same data group that contains those points we just entered, let's read the data into a new group. A new data group may be created using the gN command . Let's call this data group “complex” and define it in Partiview this way:

g2=complex

You may have noticed the Group Buttons pop on, displaying buttons for both the original data you entered manually, group 1, and your new group, complex. Assuming the complex group is the active group (which you can confirm under the Groups Menu where you should see [g2]), we can then read in the data. Let's use the read command to import the data file complex.speck

read complex.speck

Upon reading this file, you will see that the labels pop on, but there are no data represented in the view (no points or polygons). If you look at the data file, you will see that we have combined the labels into the .speck file, rather than have two separate files. So you've just seen the labels pop on in the display, but there are no points drawn yet. Let's first adjust the look of the labels, then work on displaying the data points.

Once you fly away from the data cube, you will notice that the labels are so small that you can't read them. Let's see what their current size is and adjust them using the lsize command. First, see what the current size is by issuing the lsize command without any arguments. Partiview should report 0.05 (the default size). This size is in the units of your coordinate system (if our data set is in meters, then the label height will be 0.05 meters). Change the size by typing the command

lsize *1.1

Once you enter this command, keep hitting the [Enter] key until you reach the desired size; you are multiplying the size each time by 1.1. You can turn off the label axes (the individual axes on each label) by typing

laxes off

To clarify things, turn the group 1 data off. You can do this by left-clicking on the g1 button, or typing g1 off in the Command Line. However you choose to turn the group off, be sure the complex data group (group 2) remains the the active data group. (If it isn't the active group, just right-click on its group button.) As a first step toward displaying points, let's give these data a constant luminosity of 1000 using the command

lum const 1000

The points appear, but seem to be randomly colored; let's see how Partiview is coloring the points by typing the color command without any arguments. It should report the following: “coloring-by 1(coloridx) 0.. 6 mean 2.19,” meaning that Partiview is using data variable 1 called coloridx for the color information. In Partiview, the default is to use the 5th column (or data variable 1) for coloring the particles and the 4th column (data variable 0) for luminosity information. Let's see what data variables are available to us by typing

datavar

This will report all the data variables defined in the data file, which you can see in the complex.speck file. You may want to increase the size of the Console Window or use the scroll bar to see the full report. We see that the color information is in datavar 1 and is called coloridx. Even though Partiview has set that column to be the default color column, let's explicitly tell Partiview that we want to use the data variable coloridx to color our particles. We can use the color datavar command for this

color coloridx

Upon issuing that command, the colors didn't change, so we were right in assuming Partiview was using the coloridx column to color the points. For more information on coloring objects, see “Coloring Particles and Objects.”

We have now read in a data set and loaded it into a new data group. Let's now discuss, in detail, what data groups are, how to create them, and how to manipulate data within them.