Scripting with GoQat - 1

GoQat can automate repetitive tasks using its task queue. But you can also write your own scripts to be executed from the task queue to modify and control GoQat's behaviour. Scripts can be written in the language of your choice to make GoQat truly flexible and powerful.

Since scripts are called from GoQat's task queue, so let's see how to do that first.

Calling a script from the task queue

Start by connecting your camera to GoQat. Select the device on the Cameras menu and open it from the Cameras tab. Now go to the Tasks tab and click the 'Edit tasks...' button to open the tasks editing window. Enter an exposure time in the 'Seconds' field near the top of the window (1 second will do):


You may also wish to set an appropriate value for the chip temperature, or else select 'Ignore cooling' on GoQat's Camera tab. Click the 'Expose' button to add the Expose task to the queue. You don't need to mount the camera to a telescope but it will be more fun if you can attach something like a camera lens. Otherwise a piece of card will do to vary the amount of light entering the camera.

Now we are going to add a script to the queue. GoQat lets you execute scripts asynchronously with the ExecAsync task or synchronously with the Exec task. Asynchronous script execution occurs while the remainder of the task queue is executing, whereas synchronous execution delays the task queue until the script has finished. This is the most interesting case because the script can pass values back to GoQat to modify execution of the task queue. Some example scripts are installed by default in /usr/local/share/GoQat/data/examples. Click on the script file chooser button in the task editing window and pick demo1.sh. Then click 'Exec' to add this to the queue as a synchronous script:


To execute the task queue, click 'Play' at the bottom of the Tasks tab. First GoQat will run the Expose task and take a camera exposure. Then it will run the demo1.sh script. All this script does is take the input values that GoQat gives it and returns them to GoQat to display in the log window. Open the script with your favourite editor and have a look to see what it does - it's divided into various sections. The variable assignment section assigns the values that GoQat passes to the script to named variables. The next section is where you enter your own script commands - in this case it's a bash script, but you could write one in another language if you choose. In the final section, you pass any results from the script back to GoQat. These can be comments to be displayed in the log window, parameter values, or workspace variables to be stored between invocations of the script (see below).

If you scroll up GoQat's log window when the script has run you will find 'Expose_seconds', 'Expose_H1', 'Expose_V1', 'Expose_H2', 'Expose_V2' amongst other things. These are the camera exposure time and the bottom left and top right coordinates of the exposed area of the chip. You will also see 'Expose_min_grey', 'Expose_max_grey', 'Expose_mean_grey' and 'Expose_mode_grey'. These are the minimum, maximum, mean and modal (most likely) values in the image. They are available only for greyscale, not colour, images.

So far, this is informative but not particularly useful. So how do we make it a bit more exciting? What if we could automatically adjust the exposure time to get a well-exposed image?

Auto-exposure with GoQat - part 1

So, what might a well-exposed image be? Perhaps we would like to pass a value to the script to tell it the maximum value that we want in the exposure. Let's see how to do that.

On the Tasks tab, select the Exec task and click the 'Delete task' button. Open the task editing window if it isn't already and enter a value for the SetParam task. This is going to be the maximum we'd like in the exposure, so pick something like 55000 for a 16-bit camera, for example. We're going to pass this to the script as parameter 0, so enter '0' in the box next to the '%' symbol and then click the 'SetParam' button. (GoQat refers to the user-defined parameters by a '%' followed by the parameter number, from 0 to 9):


Now load the demo2.sh script as an Exec task, just as you did for demo1.sh. The task queue should now contain an Expose task, a SetParam task and an Exec task. Click the 'Play' button to execute the task queue.

If the modal (most likely) value in the image is greater than the maximum value, GoQat will display a message from the script in the log window to say that the image might be saturated. Otherwise, if the maximum value in the image is greater than the user-specified value for parameter 0, GoQat will say that the highest values in the exposure might be clipped (i.e. be limited at the greatest possible value). If neither of those conditions is met, the image must be fine, so GoQat will tell you that it is perfect! Experiment by sliding a piece of card in front of the camera, or adjust the aperture if you have attached a lens.

Here's an example with an image of a vase illuminated by a lamp (the lamp is reflected in the window - it's dark outside). The GoQat's log file output is shown below each image. The messages from the script are displayed in bright green.

Saturated:


Possibly clipped:


Perfect: