Add-on API

ClickPoints allows to easily write add-on scripts.

Note

The Add-ons 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.

File Location

The add-on files can be located in the ClickPoints add-on folder (/path-to-clickpoints/clickpoints/addons/) or in an externally folder and be imported manually on each use.

Furthermore, ClickPoints offers a way for python packages, to define ClickPoints addons. Therefore, place a file called __clickpoints_addon__.txt in the main folder of the package (usually the child folder of the folder where the setup.py is located). The __clickpoints_addon__.txt file can contain the path to the meta data file (ending in .txt) of the add-on. The paths are defined relative to the folder that contains the __clickpoints_addon__.txt file. A package can define multiple clickpoints add-ons, therefore, each line in __clickpoints_addon__.txt defines the relative path to an add-on.

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:

1[addon]
2name=My new Add-on
3file=Addon.py
4icon=fa.flask
5description=This add-on makes cool new things.
6image=Image.png
7requirements=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 a valid qtawesome icon name (see https://github.com/spyder-ide/qtawesome, e.g. it starts with 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:

 1import clickpoints
 2
 3class Addon(clickpoints.Addon):
 4    def __init__(self, *args, **kwargs):
 5        clickpoints.Addon.__init__(self, *args, **kwargs)
 6
 7        print("I am initialized with the database", self.db)
 8        print("and the ClickPoints interface", self.cp)
 9
10    def run(self, *args, **kwargs):
11        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 Tracking.

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:
markerRemoveEvent(entry)

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

Parameters:
markerMoveEvent(entry)

A marker (line or rectangle) was moved.

Parameters:
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)[source]
centerOn(x, y)[source]

Center the image view on the given coordinates.

Parameters

  • x (number) – the x coordinate

  • y (number) – the y coordinate

getCurrentFrame()[source]

Get the current ClickPoints frame.

Returns

frame – the currently selected frame in ClickPoints

Return type

int

getFrameRange()[source]

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

getImage()[source]

Get the current image displayed in ClickPoints.

Returns

image – the currently displayed image in ClickPoints

Return type

Image

hasTerminateSignal()[source]

Weather the run function is scheduled to stop

jumpFrames(value)[source]

Let ClickPoints jump the given amount of frames.

Parameters

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

jumpFramesWait(value)[source]

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)[source]

Let ClickPoints jump to the given frame.

Parameters

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

jumpToFrameWait(value)[source]

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

Parameters

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

reloadImage(frame_index=None, layer_id=None)[source]

Reloads the an image file in ClickPoints. Defaults to the current image.

Parameters

  • frame_index (int, optional) – the sort_index of the image to reload.

  • layer_id (int, optional) – the layer to reload.

reloadMarker(frame=None)[source]

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()[source]

Reloads the current mask file in ClickPoints.

reloadMaskTypes()[source]

Reloads the mask types.

reloadTracks()[source]

Reloads all tracks.

reloadTypes()[source]

Reloads the marker types.

save()[source]

Save currently usaved data in the current frame.

selectMarkerType(type)[source]

Select a given marker type in ClickPoints.

Parameters

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

setStatus(status=0)[source]

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()[source]

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.