Adding Custom Code

External programs are intended for the following cases

• An action is impossible to implement in ImageTank
• Might be possible, but very tedious to implement in ImageTank.
• You are creating a computational action that should run outside of ImageTank but you need to test, debug, explore. Allows you to not have to write input/output and diagnostic boilerplate.
• Want to run parameter studies on remote machine or a cluster.

There are two different ways to call your own code. These are referred to as Action and Task. Action is run automatically when you need the output, so they work similiarly to the built in actions. Tasks are geared towards longer executions, and you have to explicitly start them when you are ready.

At this point, this is for C++ programs, and uses Xcode as the environment to edit, debug and compile the program.

To disect the above window.

External Action

An external action takes any number of inputs from the workspace, but it returns a single object back. That means that when you start you should think about what the return value is. If you want to return multiple variables you can use the Group variable. If you only need to return a single number you do that by using the Group variable as well. The buttons at the top are shortcuts, the full list is available in the Create menu.

When you click on any of the shortcuts or select a menu entry a lot of windows pop up

There are three key parts to this side pop up. The top is where you define the input variables, you can add in parameters or drag in variables from the workspace to send them to your program.

The next tab that is open is the Program tab. This is where you create the program. You specify the project folder to save the project into and ImageTank will create an Xcode project.

At the bottom is the return type. For some types, like the Image type you need to specify the structure and that is done in the second pop-up.

You can modify any of this, even after you create the Xcode project. There are a number of actions to make it easy to update the code.

Existing Project

You set up a search path for projects. This way it is easy to find old programs and share code with others without requiring them to have the exact same folder structure.

Use the Existing menu to browse your project folder and select the project you want to use. All of the settings are copied and ImageTank indicates if the project has changed or needs to be recompiled.

External Task

You can create a Task that will work like you would expect a standard terminal program to work. You decide when to start the execution, and the program will use the current value of the input parameters. Once it has started you can modify the input but that will not automatically restart the task. ImageTank will constantly monitor the output from the task and update it in the background. More information.

The options here are similar, you can create a blank one or select an existing one. One big difference is that you don’t specify the output, that is picked up automatically after you run the program.

Choose between Action and Task

Some examples of how you would use these two approaches.

• If you want to define your own smoothing algorithm for an image, use the Action method.
• If you are solving an ODE and want to run multiple realizations use an Action method.
• If you want to run a time dependent PDE, that may take a while to run to completion, and you want to see a time evolution of a problem as the problem is running, use the Task method.
• If you want to create a tracker that takes in a time sequence of results and creates a combined path either as a single value or another time sequence use the Task method.

The C++ code assumes that you use the C++ library DTSource, that is included inside the ImageTank wrapper. This library is cross platform and doesn’t depend on any compiled library. Thus, you can then use this library more widely and independent of ImageTank. The library will make communication between ImageTank and your C++ code a lot easier. See the DTSource page to get more information.

Get Started

The simplest way to get started is to use the online examples. Search for external program in the Basic examples or the overall External Program category.

Open this and follow the steps.