Let's place a module on the canvas. To do this, we first locate the Category that contains the module and click its name once. We want the Import and Export category. When you've clicked its name, you'll see a list of Import and Export Tools. Click once on the word Import in the Tool list. Release the mouse button, move the mouse over the blank canvas and click once again. This should place an Import module on the canvas. Or click on tool, drag to canvas and click again.

Import on canvas

In the illustration, you see that my Import module is currently selected, shown as white bars on the top and bottom. If you click anywhere on the blank canvas, the module will become unselected. To select it again, click on the label "Import" on the module, or anywhere on the box except for the tab. When it's selected, you can perform operations such as dragging the module somewhere else on the canvas, or deleting it (use VPE: Edit: Delete).

There's something else to note here: the first tab on the top left of Import is a different shade (cyan) than the teal color of the other tabs. This is an indication from DX that this input tab requires a value for the DX program to be able to execute properly.

To find out what kind of value we need to supply, do one of the following:

• Double-click on the module label (Import)
• Click once to select the module, then choose Edit: Configuration…
• Ctrl-F

Any of these techniques should open the Configuration Dialog Box for the Import module. (Double-clicking, as always, is faster but may be difficult for newcomers to master.)

With the Configuration Dialog Box …quot;CDB, for short…quot;open, you can see a list of Inputs and Outputs. The list is in vertical order, corresponding to the tabs on the module itself as shown in left to right order. So, the first item on the list ("name") corresponds to the cyan colored tab on the module. If the CDB blocks your view of the module, just drag its title bar to relocate it.

The Input names are rather terse and you may still wonder what you are supposed to give Import for the "name". To get a bit more prompting, hit the Description… button at the bottom of the CDB. This opens a longer description of the inputs and outputs and you can read that the "name" input should be a filename. Close the Description box and find the Value input area for the "name" input (currently it displays "(none)"). Select all the text and type "watermolecule.dx" and hit Enter to make the new text take the place of the old.

Import with filename

Notice that when you hit Enter, two important things happened. First, within the text entry itself, your input cursor (I-beam) jumped outside the quotes. This is very important to remember, because if you simply typed new text but did not press Enter, the new text is not yet being seen by the dialog box. There are numerous other places within DX where you must enter text, then press Enter to make the change take effect. Get in the habit now to save confusion later. Within CDBs, you can also press the Apply button. This forces updates but leaves the CDB open in case you want to make more changes.

Secondly, look at the Import module on the canvas. Now, the first tab is turned down, no longer cyan. This means you have successfully satisfied the first required input by providing a filename. There is no guarantee that the filename is correctly spelled, or that the file even exists, but DX is happy in its blissful ignorance of such mundane matters. Don't worry: you'll hear about it later if you screwed up.

I've made an assumption here, that you earlier set the environment variable $DXDATA to include the dxsamples-x.x/data directory where watermolecule.dx resides. If you did not, then you must elaborate the filename to include the entire absolute path (no regular expression syntax permitted).

You press the OK button in the CDB to close the dialog and accept the changes you've made, or Cancel to close without making changes (if you do, the tab pops up and you can start over). Press OK.

We have Import but no form of output in our program. As I mentioned, we most often would like to see an Image, so the logical module is found under the category Rendering: Image. Place an Image on the canvas below Import. (Hereafter my writing convention is Category: Tool, e.g., Rendering: Image; while this is like my convention for Menu: Item, I think the context will make things clear).

Image shows that it requires an input as well. This time, double-clicking is not the appropriate thing to do. There are a few special modules, Image among them, for which double-clicking the module has a special meaning. In Image's case, double-click is a shortcut to pop open the Image window and bring it to the top of the window stack. But since there's nothing to make an Image of yet, it's just a black empty space.

If you opened the image window, click on the VPE window's title bar to bring it back to the top, move the mouse cursor over the cyan colored input tab on Image, and hold the left mouse button down. You see the word "object" appear on the module. This technique works on any tab on any module, and in fact, is just the same as the name you would see in the module's CDB. It's a quick cheat-sheet reminder.

Image wants an "object". In DX, an Object is a very general classification. There are many different kinds of Objects. Image is reasonably flexible about the kinds of Objects you send it.

We've discussed two important Object types so far: Fields and Groups.

You saw in the sample nets we inspected earlier that modules pass information (in the form of Objects) through links or wires. These links will always emanate from a module's output(s), which are always located on the bottom of modules. The links travel from outputs to inputs which are always on the top. There is no gravity in DX, so even if a wire goes uphill, the data will still flow from output to input.

Let's try connecting Import to Image with a wire. Here's how:

1. Place the tip of the mouse cursor on the output tab of Import. Hold down the left mouse button.
2. Drag down to the input tab of Image. You should see a white line follow the mouse.
3. Release the mouse button with the cursor tip on top of Image's input tab. You should see a black link between the two tabs, and both tabs pop inward. Image's input tab turns green when the connection is made.
4. If this did not happen, try again until you get the precise motion of starting on an output tab and ending on an input tab.

Success? Well, maybe. There's a chance this program will run. In fact, it will generate an error, but I'm going to lead you into this trap so we can talk about some things that will be useful from here on. When you have the two modules linked, choose Execute: Execute Once (from the VPE menu bar). Watch the net as it begins to execute this program. If you entered the filename with the correct spelling, and the pathname if required, or no pathname if you set the environment variable correctly, then DX will locate the file and begin reading it in. During this time, the Import module's label glows green, as does the Execute menu itself. This is an indication that DX is doing something, and is usually a good sign.

If you made a mistake in the filename, or the file was not found, you got an error message in the Message Window. Read the error, and correct the situation by fixing the filename or adding the full path to the dxsamples-x.x/data directory before the filename, then Execute again. If you have just now decided to set the environment variable, you'll have to exit DX completely and restart it after the environment is updated. We'll wait for you. Tap, tap, tap.

OK. Import churned for a while and read the file in, then passed the information to Image. Image then tried to make sense of that information but balked and threw out an error message. What is it moaning about?

My first error

Read the message in the Message Window. You may have to bring the Message Window to the top if you lowered it earlier: the Windows menu offers Open Message Window for this purpose. You may also stretch the Message Window wider to read the whole error, or use the horizontal scrollbar.

The Message Window is where all errors (and other useful bits of info) are reported. The current error is bold-faced and highlighted. You know it's the current error because a couple lines earlier, the message says Begin Execution and that means that everything after that is the result of the most recent execution of the program. You should see an informational message about "opening file …/watermolecule.dx". Then the ERROR: Image: Display: Missing data: colors component is missing. You know which Image is complaining because the module label in the net corresponding to the error has turned a jaundiced shade of orange.

We know what a "Component" is. I mentioned the "colors" Component in passing earlier. The problem here is that the Field Object that describes the water molecule data set does not have any colors in it; if it did, they would reside in a "colors" Component. There are two ways (at least) to get colors into a Field. One is to have placed color information in the data file when you created the file, that is, prior to reading it into DX. Obviously, that didn't happen or we wouldn't have this error. The other is to add colors to the imported data using tools in DX. That's easy, fun, and profitable. Let's do it.

You can close or minimize the Message Window, or simply click on the VPE title bar to elevate the VPE. Here's what we are going to do. We've successfully imported the data: there's nothing wrong with the data per se. I can assure you that it has "positions", "connections" and "data" values. We need to add "colors" to this data Field before we can render the image in the Image module.

It should be apparent that we can't add colors after Image.

Why would that be illogical? Answer

You also cannot add information to a Field that doesn't yet exist, and until the Import is complete, there is no Field of data. Therefore, the "coloring" operation cannot take place before the Import within this program. That leaves one possible place for the coloring operation to go, and that's between the two modules on the canvas.

But we've wired them together. We have to break the connection to insert a new module between them. Here's how:

1. Place the tip of the mouse cursor on the input tab of Image.
2. This technique can only be done by starting on an input tab.
3. Depress the left mouse button and drag up.
4. Release the button when the mouse cursor is over empty space on the canvas. This should return you to the "unwired" condition.