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.
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 2 3 4 5 6 7 | [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.
- name -
- file -
file=Addon.py
Defines the filename of the python file that contains the add-on class.
- file -
- 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).
- icon -
- 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.
- image -
- 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.
- description -
- requirements -
requirements=xlwt,skimage
Define the packages that this add-on needs. Multiple packages have to be separated by a komma.
- requirements -
Script File¶
The script file has to contain a class called Addon
which is derived
from a prototype Add-on class:
1 2 3 4 5 6 7 8 9 10 11 | 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.
-
markerRemoveEvent
(entry)¶ A marker (line or rectangle) was removed to the current image.
-
markerMoveEvent
(entry)¶ A marker (line or rectangle) was moved.
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.