Pipe Plugin

Please be sure to read the Overview page to get a general sense of if the Pipe RoboRealm Extension is a good fit for you.

Pipe programs communicate to/from RoboRealm using a windows named pipe. This communication mechanism is quicker than network based communication but also requires a unique pipe name that is shared system wide. If the pipe already exists RoboRealm will connect to that existing pipe otherwise it will run the specified program in expectation that it creates the pipe. This allows you to run your program from a debugged and have RoboRealm connect to that active process for debugging purposes.

To create your own pipe program to extend RoboRealm download our example pipe program. This example program (SwapColors) will swap the Red and Blue pixel colors in an effort to show how image modifications can be performed. Note that the download also includes the Socket and DLL example implementations. The example pipe program is in the single source file called main.cpp. The other files are used for VC++ project configuration.

You will need VC++ or other C++ compiler to build the program.

Note that a pre-built executable is in the Release subfolder.

To configure RoboRealm to use a pipe based program click on the Extensions->Pipe_Program module.

The following interface elements can be specified:

Name - indicates the name or function of the module. This name is used for display in the main RoboRealm program list area for easy identification and is also passed to the Pipe Program as a 'name' variable that indicates the desired functionality. Using the name variable you can use a single program to perform multiple tasks.

Program File - The name of the pipe program. This is a windows console executable program that should create and open a windows named pipe and begin listening on that pipe for data. Note that RoboRealm checks to see if the pipe exists and connects to it if it does. If not RoboRealm will execute the specified program in expectation that the pipe is created and active.

Program Arguments - You can specify arguments that are passed to the pipe based program that will appear in the argc and argv arguments of that program. This can be used to specify additional parameters to your program in order to customize as needed.

Pipe Name - The communications pipe's name that is used to transfer image pixels and data to and from your program. The default used is rrpipe.

Available Variables - Shows you the current RoboRealm variables that other modules have created. Note that the variables are NOT reset during each image call and thus can be used to save information from past images.

Returned Variables - Shows the variables that your pipe program has returned which were added to the RoboRealm variables.

Messages - Any system error messages. If your pipe program passes back the 'error' variable the contents are displayed in this text box.

Reload and Run - While RoboRealm attempts to keep the pipe connection open you may need to restart the pipe program due to failure of some kind.

To start the program specify the .exe file using the browse button. RoboRealm will start the program and pass variables and images to it for processing.

The data format used to pass the image and associated variables to both pipe and socket based programs is based on the a name value pair. The following is and example of the data stream:

5 width 4 320 6 height 4 240 5 image 6 230400 xxxxx ... 0

The pair format is

length of name | name | length of value | value | next length or 0 to end

and continues until a 0 or -1 is encountered. 0 means end of the current image step while -1 means end of program.

Note that all variable values are sent as text strings with the exception of width and height which are stored as a four byte number and the actual image which is composed on unsigned BGR pixel triplets.

Things to remember:

• Be sure to use a unique pipe name! If you create more than one Pipe program use a different pipe name or combine the two functions into a single pipe program.
• RoboRealm only processes images when needed! Thus if the RoboRealm window is hidden it will NOT process images and will not call your pipe program. If you are processing a static image RoboRealm will call your pipe module when refreshing part of the window.