Add-on API

ClickPoints allows to easily write add-on scripts.

Note

The Addons section demonstrates how the add-ons can be used and may serve as a good starting point to write custom add-ons.

The add-on consists of at least two files. A meta data file with .txt ending which contains basic information on the add-on and a script file providing an overloaded class of clickpoints.Addon as shown above.

Meta Data File

The file has to start with [addon] followed by lines with key and value pairs: A typical meta file looks like this:

[addon]
name=My new Add-on
file=Addon.py
icon=fa.flask
description=This add-on makes cool new things.
image=Image.png
requirements=xlwt

• name - name=My new Add-on

  Defines the name of the add-on. This name is displayed in ClickPoints in the add-on list.

• file - file=Addon.py

  Defines the filename of the python file that contains the add-on class.

• icon - icon=fa.flask

  Defines the icon of the add-on. It can be either a filename or fa. followed by the name of a font awesome icon see the font awesome iconlist.

• image - image=Image.png

  Defines the image of the add-on. The image will be displayed in ClickPoints in the add-on list directly above the description. The image should have a dimension of 300x160 pixel.

• description - description=This add-on makes cool new things.

  Defines a short description for the add-on. If a longer description is desired, a file called Desc.html next to the *.txt file can be used. This file supports rich text with an html subset defined by Qt Html Subset.

• requirements - requirements=xlwt,skimage

  Define the packages that this add-on needs. Multiple packages have to be separated by a komma.

Script File

The script file has to contain a class called Addon which is derived from a prototype Add-on class:

import clickpoints

class Addon(clickpoints.Addon):
    def __init__(self, *args, **kwargs):
        clickpoints.Addon.__init__(self, *args, **kwargs)

        print("I am initialized with the database", self.db)
        print("and the ClickPoints interface", self.cp)

    def run(self, *args, **kwargs):
        print("The user wants to run me")

This class will allow you to overload the init function were your add-on can set up its configuration, e.g. add some new marker types to ClickPoints.

To process data, you can overload the run function. Here the add-on can do it’s heavy work. Some caution has to be taken when executing interface actions, as run is called in a second thread to not block ClickPoints during its execution. For a good example of an add-on that uses the run function, refer to the Track Add-on.

But add-ons can also provide passive features that are not executed by a call of the run method, but rely on callbacks. Here a good example is the Measure Tool Add-on, which just reacts on the MarkerMoved callback.

The add-on class has two main member variables: self.db and self.cp.

• self.db is a DataFile instance which gives access to the ClickPoints database. For details on the interface see Database API.
• self.cp is a Commands instance which allows for communication with the ClickPoints interface.

Defining Options

Add-ons can define their own options that are saved in the database along the ClickPoints options. They are also included in the ClickPoints options menu and the export of options.

New options should be defined in the __init__ function of the add-on. Therefore, the add-on class has some methods to add, get and set options:

addOption(key, default, value_type="string", values=None, display_name="", hidden=False, tooltip="", min_value=None, max_value=None, value_count=1)

Define a new option value for the add-on.

Parameters:

• key (str) - the name of the option.
• default (str, int, float, list) - the default value for the option.
• value_type (str) - the type of the value, can be string, int, float, bool, choice
• values (list) - allowed values if the type is choice.
• display_name (str) - the name to display in the option menu.
• hidden (bool) - weather the option should be displayed in the option menu.
• tooltip (str) - the tooltip of the option in the option menu.
• min_value (number) - the minimal value for a int or float option.
• max_value (number) - the maximum value for a int or float option.
• decimals (number) - the number of decimals to allow for a float option.
• value_count (int) - it the option should accept a list of values. Only for int values.

getOption(key)

Return the current value of an option.

Parameters:

• key (str) - the name of the option.

setOption(key, value)

Set the current value of an option.

Parameters:

• key (str) - the name of the option.
• value (str, int, float, list) - the new value of the option.

getOptions()

Return a list of all options of this add-on. The list contains option objects with the following properties:

Properties:

• key (str) - the name of the option.
• value (str, int, float, list) - the current value of the option.
• default (str, int, float, list) - the default value for the option.
• value_type (str) - the type of the value, can be string, int, float, bool, choice
• values (list) - allowed values if the type is choice.
• display_name (str) - the name to display in the option menu.
• hidden (bool) - weather the option should be displayed in the option menu.
• tooltip (str) - the tooltip of the option in the option menu.
• min_value (number) - the minimal value for a int or float option.
• max_value (number) - the maximum value for a int or float option.
• value_count (int) - it the option should accept a list of values. Only for int values.

Events

Events are actions that occur in the main ClickPoints program. The add-ons are notified for this events and can react to them.

markerAddEvent(entry)

A marker (line or rectangle) was added to the current image.

Parameters:

• entry ( Marker , Line , Rectangle ) - the new marker.

markerRemoveEvent(entry)

A marker (line or rectangle) was removed to the current image.

Parameters:

• entry ( Marker , Line , Rectangle ) - the removed marker.

markerMoveEvent(entry)

A marker (line or rectangle) was moved.

Parameters:

• entry ( Marker , Line , Rectangle ) - the moved marker.

buttonPressedEvent()

The button for this add-on was pressed. If not overloaded it will just call self.run_threaded() to executed the add-on’s self.run method in a new thread.

A typical overloading for gui based add-ons would be to call the self.show method:

def buttonPressedEvent(self):
    self.show()

zoomEvent(scale, pos)

The zoom of the ClickPoints window has changed.

Parameters:

• scale (number) - the new scale factor of the displayed image.
• pos (QPoint) - the origin point of the zoom. Typically the mouse cursor position.

frameChangedEvent()

The current frame in ClickPoints changed. Called when the image data is loaded, before it is displayed.

imageLoadedEvent(filename, framenumber)

The displayed image in ClickPoints changed. Called when the new image is loaded and displayed.

Parameters:

• filename (string) - the filename of the new image.
• framenumber (int) - the frame number of the new image.

keyPressEvent(event)

A key has been pressed in the ClickPoints window.

Parameters:

• event (QKeyEvent) - the key press event. With event.key() they key can be queried and compared to the key constants (see Qt::Key).

Commands

Add-ons have some basic functions to communicate with the main ClickPoints window. This interface is accessible through the self.cp class variable in the add-on class.

class clickpoints.Addon.Command(script_launcher=None, script=None)

centerOn(x, y)

Center the image view on the given coordinates.

Parameters:

• x (number) – the x coordinate
• y (number) – the y coordinate

getCurrentFrame()

Get the current ClickPoints frame.

Returns:frame – the currently selected frame in ClickPoints Return type:int

getFrameRange()

Get the current ClickPoints frame range from the start marker to the end marker.

Returns:range – the start and end marker position, as well, as the skip Return type:list

hasTerminateSignal()

Weather the run function is scheduled to stop

jumpFrames(value)

Let ClickPoints jump the given amount of frames.

Parameters:value (int) – the amount of frame which ClickPoints should jump.

jumpFramesWait(value)

Let ClickPoints jump the given amount of frames and wait for it to complete.

Parameters:value (int) – the amount of frames which ClickPoints should jump.

jumpToFrame(value)

Let ClickPoints jump to the given frame.

Parameters:value (int) – the frame to which ClickPoints should jump.

jumpToFrameWait(value)

Let ClickPoints jump to the given frame and wait for it to complete.

Parameters:value (int) – the frame to which ClickPoints should jump.

reloadMarker(frame=None)

Reloads the marker from the given frame in ClickPoints.

Parameters:frame (int) – the frame which ClickPoints should reload. Use None for the current frame.

reloadMask()

Reloads the current mask file in ClickPoints.

reloadMaskTypes()

Reloads the mask types.

reloadTracks()

Reloads all tracks.

reloadTypes()

Reloads the marker types.

save()

Save currently usaved data in the current frame.

selectMarkerType(type)

Select a given marker type in ClickPoints.

Parameters:type (MarkerType) – the marker type which should be selected.

setStatus(status=0)

Set the button state for the add-on.

Parameters:status (int) – the button can have three states, STATUS_Idle for an non active button, STATUS_Active for an active button and STATUS_Running for an active button with an hourglass symbol.

updateImageCount()

Notify ClickPoints that the count of images has changed. Has to be called when layers of images have changed or images have been added or removed.