Adding Custom Code

ImageTank has a lot of built in functionality, and you can combine it to create complicated pipelines, but for cases that are either not representable or require too many steps you should consider creating an external program that ImageTank will call.

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.

ImageTank helps you to write the program in the following ways

• Comes with a source code library to write the ImageTank types to disk and to read them back. This is how the data is passed between ImageTank and your external program.
• Supports two languages – C++ and python. The C++ library is very mature, and the python library will be fleshed out and improved based on user feedback.
• Works with IDE’s for both languages. For C++ ImageTank assumes Xcode, and for python it assumes Visual Studio Code.
• ImageTank auto-generates all of the code needed to read and write the data objects. You specify the structure by using the side panel for the ImageTank action, and when you change the input or output you can ask ImageTank to recreate the interface.
• You can easily debug your code using the input variable(s) specified for the external program. That makes it easy to stop when the external program is not working properly and head into the IDE to debug.

The content below goes through how to create an external program, for python specific information click here.

Create a new program

Click on the Task entry in the toolbar. We will focus on the action here. This means a program that will run as needed and take input object(s) and return a single output. If you want to return more than one object use the Group object to combine them.

Once you have external programs you can select them from a menu (the Existing menu). Note that what you need to decide on now is what the return type is going to be. You can change that later. The most common types are listed at the top, but you can select from all of the available types by using the Create menu.

Setting input and output

When you create a new project a number of windows pop up, like shown in the following screenshot. You can get back to this by clicking on the side panel icon.

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. If you select python from the language menu you will create a folder that is set up for Visual Studio Code.

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/VSC 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.