Database API¶

ClickPoints comes with a powerful API which enables access from within python to ClickPoints Projects which are stored in a .cdb ClickPoints SQLite database.

To get started reading and writing to a database use:

import clickpoints
db = clickpoints.DataFile("project.cdb")

This will open an existing project file called project.cdb.

Note

The Examples section demonstrates the use of the API with various examples and provides a good starting point to write custom evaluations.

Attention

To be able to use the API, the clickpoints package has to be installed! If a ImportError: No module named clickpoints error is raised, you have to install the package first. Go to clickpointspackage in your clickpoints directory and execute python setup.py develop there.

Database Models¶

The .cdb file consists of multiple SQL tables in which it stores its information. Each table is represented in the API as a peewee model. Users which are not familiar can use the API without any knowledge of peewee, as the API provides all functions necessary to access the data. For each table a get (retrieve entries), set (add and change entries) and delete (remove entries) function is provided. Functions with a plural name always work on multiple entries at once and all arguments can be provided as single values or arrays if multiple entries should be affected.

The tables are: Meta, Path, Image, Offset, Track, MarkerType, Marker, Line, Rectangle, Mask, MaskType, Annotation, Tag, TagAssociation.

class Meta¶

Stores key value pairs containing meta information for the ClickPoints project.

Attributes:

key (str, unique) - the key
value (str) - the value for the key

class Path¶

Stores a path. Referenced by each image entry.

Attributes:

path (str, unique) - the path
images (list of Image ) - the images with this path.

class Image¶

Stores an image.

Attributes:

filename (str, unique) - the name of the file.
ext (str) - the extension of the file.
frame (int) - the frame of the file (0 for images, >= 0 for images from videos).
external_id (int) - the id of the file entry of a corresponding external database. Only used when ClickPoints is started from an external database.
timestamp (datetime) - the timestamp associated to the image.
sort_index (int, unique) - the index of the image. The number shown in ClickPoints next to the time line.
width (int) - None if it has not be set, otherwise the width of the image.
height (int) - None if it has not be set, otherwise the height of the image.
path ( Path ) - the linked path entry containing the path to the image.
offset ( Offset ) - the linked offset entry containing the offsets stored for this image.
markers (list of Marker ) - a list of marker entries for this image.
lines (list of Line ) - a list of line entries for this image.
rectangles (list of Rectangle ) - a list of rectangle entries for this image.
mask ( Mask ) - the mask entry associated with the image.
data (array) - the image data as a numpy array. Data will be loaded on demand and cached.
data8 (array, uint8) - the image data converted to unsigned 8 bit integers.
getShape() (list) - a list containing height and width of the image. If they are not stored in the database yet, the image data has to be loaded.

class Offset¶

Offsets associated with an image.

Attributes:

image ( Image ) - the associated image entry.
x (int) - the x offset
y (int) - the y offset

class Track¶

A track containing multiple markers.

Attributes:

style (str) - the style for this track.
text (str) - an additional text associated with this track. It is displayed next to the markers of this track in ClickPoints.
hidden (bool) - whether the track should be displayed in ClickPoints.
points (array) - an Nx2 array containing the x and y coordinates of the associated markers.
points_corrected (array) - an Nx2 array containing the x and y coordinates of the associated markers corrected by the offsets of the images.
markers (list of Marker ) - a list containing all the associated markers.
times (list of datetime) - a list containing the timestamps for the images of the associated markers.
frames (list of int) - a list containing all the frame numbers for the images of the associated markers.
image_ids (list of int) - a list containing all the ids for the images of the associated markers.

class MarkerType¶

A marker type.

Attributes:

name (str, unique) - the name of the marker type.
color (str) - the color of the marker in HTML format, e.g. #FF0000 (red).
mode (int) - the mode, hast to be either: TYPE_Normal, TYPE_Rect, TYPE_Line or TYPE_Track
style (str) - the style of the marker type.
text (str) - an additional text associated with the marker type. It is displayed next to the markers of this type in ClickPoints.
hidden (bool) - whether the markers of this type should be displayed in ClickPoints.
markers (list of Marker ) - a list containing all markers of this type. Only for TYPE_Normal and TYPE_Track.
lines (list of Line ) - a list containing all lines of this type. Only for TYPE_Line.
markers (list of Rectangle ) - a list containing all rectangles of this type. Only for TYPE_Rect.

class Marker¶

A marker.

Attributes:

image ( Image ) - the image entry associated with this marker.
x (int) - the x coordinate of the marker.
y (int) - the y coordinate of the marker.
type ( MarkerType ) - the marker type.
processed (bool) - a flag that is set to 0 if the marker is manually moved in ClickPoints, it can be set from an add-on if the add-on has already processed this marker.
style (str) - the style definition of the marker.
text (str) - an additional text associated with the marker. It is displayed next to the marker in ClickPoints.
track ( Track ) - the track entry the marker belongs to. Only for TYPE_Track.
correctedXY() (array) - the marker position corrected by the offset of the image.
pos() (array) - an array containing the coordinates of the marker: [x, y].

class Line¶

A line.

Attributes:

image ( Image ) - the image entry associated with this line.
x1 (int) - the first x coordinate of the line.
y1 (int) - the first y coordinate of the line.
x2 (int) - the second x coordinate of the line.
y2 (int) - the second y coordinate of the line.
type ( MarkerType ) - the marker type.
processed (bool) - a flag that is set to 0 if the line is manually moved in ClickPoints, it can be set from an add-on if the add-on has already processed this line.
style (str) - the style definition of the line.
text (str) - an additional text associated with the line. It is displayed next to the line in ClickPoints.
correctedXY() (array) - the line positions corrected by the offset of the image.
pos() (array) - an array containing the coordinates of the line: [x, y].
length (float) - the length of the line in pixel.

class Rectangle¶

A rectangle.

Attributes:

image ( Image ) - the image entry associated with this rectangle.
x (int) - the x coordinate of the rectangle.
y (int) - the y coordinate of the rectangle.
width (int) - the width of the rectangle.
height (int) - the height of the rectangle.
type ( MarkerType ) - the marker type.
processed (bool) - a flag that is set to 0 if the rectangle is manually moved in ClickPoints, it can be set from an add-on if the add-on has already processed this line.
style (str) - the style definition of the rectangle.
text (str) - an additional text associated with the rectangle. It is displayed next to the rectangle in ClickPoints.
correctedXY() (array) - the rectangle positions corrected by the offset of the image.
pos() (array) - an array containing the coordinates of the rectangle: [x, y].
slice_x() (slice) - a slice object to use the rectangle to cut out a region of an image
slice_y() (slice) - a slice object to use the rectangle to cut out a region of an image
area() (float) - the area of the rectangle

class Mask¶

A mask entry.

Attributes:

image ( Image ) - the image entry associated with this marker.
data (array) - the mask image as a numpy array. Mask types are stored by their index value.

class MaskType¶

A mask type.

Attributes:

name (str) - the name of the mask type.
color (str) - the color of the mask type in HTML format, e.g. #FF0000 (red).
index (int) - the integer value used to represent this type in the mask.

class Annotation¶

An annotation.

Attributes:

image ( Image ) - the image entry associated with this annotation.
timestamp (datetime) - the timestamp of the image linked to the annotation.
comment (str) - the text of the comment.
rating (int) - the value added to the annotation as rating.
tags (list of Tag ) - the tags associated with this annotation.

class Tag¶

A tag for an Annotation.

Attributes:

name (str) - the name of the tag.
annotations (list of Annotation ) - the annotations associated with this tag.

class TagAssociation¶

A link between a Tag and an Annotation

Attributes:

annotation ( Annotation ) - the linked annotation.
tag ( Tag ) - the linked tag.

DataFile¶

class clickpoints.DataFile(database_filename=None, mode='r')[source]¶

The DataFile class provides access to the .cdb file format in which ClickPoints stores the data for a project.

Parameters:	database_filename (string) – the filename to open mode (string, optional) – can be ‘r’ (default) to open an existing database and append data to it or ‘w’ to create a new database. If the mode is ‘w’ and the database already exists, it will be deleted and a new database will be created.

deleteAnnotations(image=None, frame=None, filename=None, timestamp=None, comment=None, rating=None, id=None)[source]¶

Delete all Annotation entries with the given criteria.

Parameters:	image (int, `Image`, array_like, optional) – the image/images for which the annotations should be retrieved. If omitted, frame numbers or filenames should be specified instead. frame (int, array_like, optional) – frame number/numbers of the images, which annotations should be returned. If omitted, images or filenames should be specified instead. filename (string, array_like, optional) – filename of the image/images, which annotations should be returned. If omitted, images or frame numbers should be specified instead. timestamp (datetime, array_like, optional) – timestamp/s of the annotations. comment (string, array_like, optional) – the comment/s of the annotations. rating (int, array_like, optional) – the rating/s of the annotations. id (int, array_like, optional) – id/ids of the annotations.
Returns:	rows – the number of affected rows.
Return type:	int

deleteImages(filename=None, path=None, frame=None, external_id=None, timestamp=None, width=None, height=None, id=None)[source]¶

Delete all Image entries with the given criteria.

Parameters:	filename (string, array_like, optional) – the filename/filenames of the image (including the extension) path (string, int, `Path`, array_like optional) – the path string, id or entry of the image to insert frame (int, array_like, optional) – the number/numbers of frames the images have external_id (int, array_like, optional) – an external id/ids for the images. Only necessary if the annotation server is used timestamp (datetime object, array_like, optional) – the timestamp/timestamps of the images width (int, array_like, optional) – the width/widths of the images height (int, optional) – the height/heights of the images id (int, array_like, optional) – the id/ids of the images
Returns:	rows – the number of affected rows.
Return type:	int

deleteLines(image=None, frame=None, filename=None, x1=None, y1=None, x2=None, y2=None, type=None, processed=None, text=None, id=None)[source]¶

Delete all Line entries with the given criteria.

Parameters:	image (int, `Image`, array_like, optional) – the image/s of the lines. frame (int, array_like, optional) – the frame/s of the images of the lines. filename (string, array_like, optional) – the filename/s of the images of the lines. x1 (int, array_like, optional) – the x coordinate/s of the start of the lines. y1 (int, array_like, optional) – the y coordinate/s of the start of the lines. x2 (int, array_like, optional) – the x coordinate/s of the end of the lines. y2 (int, array_like, optional) – the y coordinate/s of the end of the lines. type (string, `MarkerType`, array_like, optional) – the marker type/s (or name/s) of the lines. processed (int, array_like, optional) – the processed flag/s of the lines. text (string, array_like, optional) – the text/s of the lines. id (int, array_like, optional) – the id/s of the lines.
Returns:	rows – the number of affected rows.
Return type:	int

deleteMarkerTypes(name=None, color=None, mode=None, text=None, hidden=None, id=None)[source]¶

Delete all MarkerType entries from the database, which match the given criteria.

Parameters:	name (str, array_like, optional) – the name of the type color (str, array_like, optional) – hex code string for rgb color of style “#00ff3f” mode (int, array_like, optional) – mode of the marker type (marker 0, rect 1, line 2, track 4) text (str, array_like, optional) – display text hidden (bool, array_like, optional) – whether the types should be displayed in ClickPoints id (int, array_like, optional) – id of the `MarkerType` object
Returns:	entries – nr of deleted entries
Return type:	int

deleteMarkers(image=None, frame=None, filename=None, x=None, y=None, type=None, processed=None, track=None, text=None, id=None)[source]¶

Delete all Marker entries with the given criteria.

Parameters:	image (int, `Image`, array_like, optional) – the image/s of the markers. frame (int, array_like, optional) – the frame/s of the images of the markers. filename (string, array_like, optional) – the filename/s of the images of the markers. x (int, array_like, optional) – the x coordinate/s of the markers. y (int, array_like, optional) – the y coordinate/s of the markers. type (string, `MarkerType`, array_like, optional) – the marker type/s (or name/s) of the markers. processed (int, array_like, optional) – the processed flag/s of the markers. track (int, `Track`, array_like, optional) – the track id/s or instance/s of the markers. text (string, array_like, optional) – the text/s of the markers. id (int, array_like, optional) – the id/s of the markers.
Returns:	rows – the number of affected rows.
Return type:	int

deleteMaskTypes(name=None, color=None, index=None, id=None)[source]¶

Delete all MaskType entries from the database, which match the given criteria.

Parameters:	name (string, array_like, optional) – the name/names of the mask types. color (string, array_like, optional) – the color/colors of the mask types. index (int, array_like, optional) – the index/indices of the mask types, which is used for painting this mask types. id (int, array_like, optional) – the id/ids of the mask types.

deleteMasks(image=None, frame=None, filename=None, id=None)[source]¶

Delete all Mask entries with the given criteria.

See also: getMask(), getMasks(), setMask().

Parameters:

image (int, Image, array_like, optional) – the image/images for which the mask should be deleted. If omitted, frame numbers or filenames should be specified instead.
frame (int, array_like, optional) – frame number/numbers of the images, which masks should be deleted. If omitted, images or filenames should be specified instead.
filename (string, array_like, optional) – filename of the image/images, which masks should be deleted. If omitted, images or frame numbers should be specified instead.
id (int, array_like, optional) – id/ids of the masks.

deletePaths(path_string=None, base_path=None, id=None)[source]¶

Delete all Path entries with the given criteria.

Parameters:	path_string (string, optional) – the string/s specifying the paths. base_path (string, optional) – return only paths starting with the base_path string. id (int, optional) – the id/s of the paths.
Returns:	rows – the number of affected rows.
Return type:	int

deleteRectangles(image=None, frame=None, filename=None, x=None, y=None, width=None, height=None, type=None, processed=None, text=None, id=None)[source]¶

Delete all Rectangle entries with the given criteria.

Parameters:	image (int, `Image`, array_like, optional) – the image/s of the rectangles. frame (int, array_like, optional) – the frame/s of the images of the rectangles. filename (string, array_like, optional) – the filename/s of the images of the rectangles. x (int, array_like, optional) – the x coordinate/s of the upper left corner/s of the rectangles. y (int, array_like, optional) – the y coordinate/s of the upper left corner/s of the rectangles. width (int, array_like, optional) – the width/s of the rectangles. height (int, array_like, optional) – the height/s of the rectangles. type (string, `MarkerType`, array_like, optional) – the marker type/s (or name/s) of the rectangles. processed (int, array_like, optional) – the processed flag/s of the rectangles. text (string, array_like, optional) – the text/s of the rectangles. id (int, array_like, optional) – the id/s of the rectangles.
Returns:	rows – the number of affected rows.
Return type:	int

deleteTags(name=None, id=None)[source]¶

Delete all Tag entries from the database, which match the given criteria. If no criteria a given, delete all.

See also: getTag(), getTags(), setTag().

Parameters:	name (string, array_like, optional) – the name/names of the `Tag`. id (int, array_like, optional) – the id/ids of the `Tag`.
Returns:	rows – number of rows deleted
Return type:	int

deleteTracks(type=None, text=None, hidden=None, id=None)[source]¶

Delete a single Track object specified by id or all Track object of an type

Parameters:	type (`MarkerType`, str, array_like, optional) – the marker type or name of the marker type text (str, array_like, optional) – the `Track` specific text entry hidden (bool, array_like, optional) – whether the tracks should be displayed in ClickPoints id (int, array_like, array_like, optional) – the `Track` ID
Returns:	rows – the number of affected rows.
Return type:	int

getAnnotation(image=None, frame=None, filename=None, id=None, create=False)[source]¶

Get the Annotation entry for the given image frame number or filename.

Parameters:	image (int, `Image`, optional) – the image for which the annotation should be retrieved. If omitted, frame number or filename should be specified instead. frame (int, optional) – frame number of the image, which annotation should be returned. If omitted, image or filename should be specified instead. filename (string, optional) – filename of the image, which annotation should be returned. If omitted, image or frame number should be specified instead. id (int, optional) – id of the annotation entry. create (bool, optional) – whether the annotation should be created if it does not exist. (default: False)
Returns:	annotation – the desired `Annotation` entry.
Return type:	`Annotation`

getAnnotations(image=None, frame=None, filename=None, timestamp=None, tag=None, comment=None, rating=None, id=None)[source]¶

Get all Annotation entries from the database, which match the given criteria. If no criteria a given, return all masks.

Parameters:	image (int, `Image`, array_like, optional) – the image/images for which the annotations should be retrieved. If omitted, frame numbers or filenames should be specified instead. frame (int, array_like, optional) – frame number/numbers of the images, which annotations should be returned. If omitted, images or filenames should be specified instead. filename (string, array_like, optional) – filename of the image/images, which annotations should be returned. If omitted, images or frame numbers should be specified instead. timestamp (datetime, array_like, optional) – timestamp/s of the annotations. tag (string, array_like, optional) – the tag/s of the annotations to load. comment (string, array_like, optional) – the comment/s of the annotations. rating (int, array_like, optional) – the rating/s of the annotations. id (int, array_like, optional) – id/ids of the annotations.
Returns:	entries – a query object containing all the matching `Annotation` entries in the database file.
Return type:	`Annotation`

getDbVersion()[source]¶

Returns the version of the currently opened database file.

Returns:	version – the version of the database
Return type:	string

getImage(frame=None, filename=None, id=None)[source]¶

Returns the Image entry with the given frame number.

Parameters:	frame (int, optional) – the frame number of the desired image, as displayed in ClickPoints. filename (string, optional) – the filename of the desired image. id (int, optional) – the id of the image.
Returns:	image – the image entry.
Return type:	`Image`

getImageIterator(start_frame=0, end_frame=None)[source]¶

Get an iterator to iterate over all Image entries starting from start_frame.

Parameters:	start_frame (int, optional) – start at the image with the number start_frame. Default is 0 end_frame (int, optional) – the last frame of the iteration (excluded). Default is None, the iteration stops when no more images are present.
Returns:	image_iterator – an iterator object to iterate over `Image` entries.
Return type:	iterator

Examples

import clickpoints

# open the database "data.cdb"
db = clickpoints.DataFile("data.cdb")

# iterate over all images and print the filename
for image in db.GetImageIterator():
    print(image.filename)

getImages(frame=None, filename=None, ext=None, external_id=None, timestamp=None, width=None, height=None, path=None, order_by='sort_index')[source]¶

Get all Image entries sorted by sort index. For large databases getImageIterator(), should be used as it doesn’t load all frames at once.

Parameters:	frame (int, array_like, optional) – the frame number/s of the image/s as displayed in ClickPoints (sort_index in the database). filename (string, array_like, optional) – the filename/s of the image/s. ext (string, array_like, optional) – the extension/s of the image/s. external_id (int, array_like, optional) – the external id/s of the image/s. timestamp (datetime, array_like, optional) – the timestamp/s of the image/s. width (int, array_like, optional) – the width/s of the image/s. height (int, array_like, optional) – the height/s of the image/s path (int, `Path`, array_like, optional) – the path/s (or path id/s) of the image/s order_by (string, optional) – sort by either ‘sort_index’ (default) or ‘timestamp’.
Returns:	entries – a query object containing all the `Image` entries in the database file.
Return type:	array_like

getLine(id)[source]¶

Retrieve an Line object from the database.

Parameters:	id (int) – the id of the line
Returns:	line – the `Line` with the desired id or None.
Return type:	`Line`

getLines(image=None, frame=None, filename=None, x1=None, y1=None, x2=None, y2=None, type=None, processed=None, text=None, id=None)[source]¶

Get all Line entries with the given criteria.

Parameters:	image (int, `Image`, array_like, optional) – the image/s of the lines. frame (int, array_like, optional) – the frame/s of the images of the lines. filename (string, array_like, optional) – the filename/s of the images of the lines. x1 (int, array_like, optional) – the x coordinate/s of the lines start. y1 (int, array_like, optional) – the y coordinate/s of the lines start. x2 (int, array_like, optional) – the x coordinate/s of the lines end. y2 (int, array_like, optional) – the y coordinate/s of the lines end. type (string, `MarkerType`, array_like, optional) – the marker type/s (or name/s) of the lines. processed (int, array_like, optional) – the processed flag/s of the lines. text (string, array_like, optional) – the text/s of the lines. id (int, array_like, optional) – the id/s of the lines.
Returns:	entries – a query object which contains all `Line` entries.
Return type:	array_like

getMarker(id)[source]¶

Retrieve an Marker object from the database.

Parameters:	id (int) – the id of the marker
Returns:	marker – the `Marker` with the desired id or None.
Return type:	`Marker`

getMarkerType(name=None, id=None)[source]¶

Retrieve an MarkerType object from the database.

Parameters:	name (str, optional) – the name of the desired type id (int, optional) – id of the `MarkerType` object
Returns:	entries – the `MarkerType` with the desired name or None.
Return type:	array_like

getMarkerTypes(name=None, color=None, mode=None, text=None, hidden=None, id=None)[source]¶

Retreive all MarkerType objects in the database.

Parameters:	name (str, array_like, optional) – the name of the type color (str, array_like, optional) – hex code string for rgb color of style “#00ff3f” mode (int, array_like, optional) – mode of the marker type (marker 0, rect 1, line 2, track 4) text (str, array_like, optional) – display text hidden (bool, array_like, optional) – whether the types should be displayed in ClickPoints id (int, array_like, optional) – id of the `MarkerType` object
Returns:	entries – a query object which contains all `MarkerType` entries.
Return type:	array_like

getMarkers(image=None, frame=None, filename=None, x=None, y=None, type=None, processed=None, track=None, text=None, id=None)[source]¶

Get all Marker entries with the given criteria.

Parameters:	image (int, `Image`, array_like, optional) – the image/s of the markers. frame (int, array_like, optional) – the frame/s of the images of the markers. filename (string, array_like, optional) – the filename/s of the images of the markers. x (int, array_like, optional) – the x coordinate/s of the markers. y (int, array_like, optional) – the y coordinate/s of the markers. type (string, `MarkerType`, array_like, optional) – the marker type/s (or name/s) of the markers. processed (int, array_like, optional) – the processed flag/s of the markers. track (int, `Track`, array_like, optional) – the track id/s or instance/s of the markers. text (string, array_like, optional) – the text/s of the markers. id (int, array_like, optional) – the id/s of the markers.
Returns:	entries – a query object which contains all `Marker` entries.
Return type:	array_like

getMask(image=None, frame=None, filename=None, id=None, create=False)[source]¶

Get the Mask entry for the given image frame number or filename.

Parameters:	image (int, `Image`, optional) – the image for which the mask should be retrieved. If omitted, frame number or filename should be specified instead. frame (int, optional) – frame number of the image, which mask should be returned. If omitted, image or filename should be specified instead. filename (string, optional) – filename of the image, which mask should be returned. If omitted, image or frame number should be specified instead. id (int, optional) – id of the mask entry. create (bool, optional) – whether the mask should be created if it does not exist. (default: False)
Returns:	mask – the desired `Mask` entry.
Return type:	`Mask`

getMaskType(name=None, color=None, index=None, id=None)[source]¶

Get a MaskType from the database.

Parameters:	name (string, optional) – the name of the mask type. color (string, optional) – the color of the mask type. index (int, optional) – the index of the mask type, which is used for painting this mask type. id (int, optional) – the id of the mask type.
Returns:	entries – the created/requested `MaskType` entry.
Return type:	`MaskType`

getMaskTypes(name=None, color=None, index=None, id=None)[source]¶

Get all MaskType entries from the database, which match the given criteria. If no criteria a given, return all mask types.

Parameters:	name (string, array_like, optional) – the name/names of the mask types. color (string, array_like, optional) – the color/colors of the mask types. index (int, array_like, optional) – the index/indices of the mask types, which is used for painting this mask types. id (int, array_like, optional) – the id/ids of the mask types.
Returns:	entries – a query object containing all the matching `MaskType` entries in the database file.
Return type:	array_like

getMasks(image=None, frame=None, filename=None, id=None, order_by='sort_index')[source]¶

Get all Mask entries from the database, which match the given criteria. If no criteria a given, return all masks.

Parameters:	image (int, `Image`, array_like, optional) – the image/images for which the mask should be retrieved. If omitted, frame numbers or filenames should be specified instead. frame (int, array_like, optional) – frame number/numbers of the images, which masks should be returned. If omitted, images or filenames should be specified instead. filename (string, array_like, optional) – filename of the image/images, which masks should be returned. If omitted, images or frame numbers should be specified instead. id (int, array_like, optional) – id/ids of the masks. order_by (string, optional) – sorts the result according to sort paramter (‘sort_index’ or ‘timestamp’)
Returns:	entries – a query object containing all the matching `Mask` entries in the database file.
Return type:	`Mask`

getPath(path_string=None, id=None, create=False)[source]¶

Get a Path entry from the database.

Parameters:	path_string (string, optional) – the string specifying the path. id (int, optional) – the id of the path. create (bool, optional) – whether the path should be created if it does not exist. (default: False)
Returns:	path – the created/requested `Path` entry.
Return type:	`Path`

getPaths(path_string=None, base_path=None, id=None)[source]¶

Get all Path entries from the database, which match the given criteria. If no critera a given, return all paths.

Parameters:	path_string (string, path_string, optional) – the string/s specifying the path/s. base_path (string, optional) – return only paths starting with the base_path string. id (int, array_like, optional) – the id/s of the path/s.
Returns:	entries – a query object containing all the matching `Path` entries in the database file.
Return type:	array_like

getRectangle(id)[source]¶

Retrieve an Rectangle object from the database.

Parameters:	id (int) – the id of the rectangle.
Returns:	rectangle – the `Rectangle` with the desired id or None.
Return type:	`Rectangle`

getRectangles(image=None, frame=None, filename=None, x=None, y=None, width=None, height=None, type=None, processed=None, text=None, id=None)[source]¶

Get all Rectangle entries with the given criteria.

Parameters:	image (int, `Image`, array_like, optional) – the image/s of the rectangles. frame (int, array_like, optional) – the frame/s of the images of the rectangles. filename (string, array_like, optional) – the filename/s of the images of the rectangles. x (int, array_like, optional) – the x coordinate/s of the upper left corner/s of the rectangles. y (int, array_like, optional) – the y coordinate/s of the upper left corner/s of the rectangles. width (int, array_like, optional) – the width/s of the rectangles. height (int, array_like, optional) – the height/s of the rectangles. type (string, `MarkerType`, array_like, optional) – the marker type/s (or name/s) of the rectangles. processed (int, array_like, optional) – the processed flag/s of the rectangles. text (string, array_like, optional) – the text/s of the rectangles. id (int, array_like, optional) – the id/s of the rectangles.
Returns:	entries – a query object which contains all `Rectangle` entries.
Return type:	array_like

getTag(name=None, id=None)[source]¶

Get a specific Tag entry by its name or database ID

Parameters:	name (str) – name of the tag id (int) – id of `Tag` entry
Returns:	entries – requested object of class `Tag` or None
Return type:	`Tag`

getTags(name=None, id=None)[source]¶

Get all Tag entries from the database, which match the given criteria. If no criteria a given, return all.

See also: getTag(), setTag(), deleteTags().

Parameters:	name (string, array_like, optional) – the name/names of the `Tag`. id (int, array_like, optional) – the id/ids of the `Tag`.
Returns:	entries – a query object containing all the matching `Tag` entries in the database file.
Return type:	array_like

getTrack(id)[source]¶

Get a specific Track entry by its database ID.

See also: getTracks(), deleteTracks().

Parameters:	id (int) – id of the track
Returns:	entries – requested object of class `Track` or None
Return type:	`Track`

getTracks(type=None, text=None, hidden=None, id=None)[source]¶

Get all Track entries, optional filter by type

Parameters:	type (`MarkerType`, str, array_like, optional) – the marker type/types or name of the marker type for the track. text (str, array_like, optional) – the `Track` specific text entry hidden (bool, array_like, optional) – whether the tracks should be displayed in ClickPoints id (int, array_like, optional) – the `Track` ID
Returns:	entries – a query object which contains the requested `Track`.
Return type:	array_like

max_sql_variables()[source]¶

Get the maximum number of arguments allowed in a query by the current sqlite3 implementation. Based on `this question `_

Returns:	inferred SQLITE_MAX_VARIABLE_NUMBER
Return type:	int

setAnnotation(image=None, frame=None, filename=None, timestamp=None, comment=None, rating=None, id=None)[source]¶

Insert or update an Annotation object in the database.

Parameters:	image (int, `Image`, optional) – the image of the annotation. frame (int, optional) – the frame of the images of the annotation. filename (string, optional) – the filename of the image of the annotation. timestamp (datetime, optional) – the timestamp of the annotation. comment (string, optional) – the text of the annotation. rating (int, optional) – the rating of the annotation. id (int, optional) – the id of the annotation.
Returns:	annotation – the created or changed `Annotation` item.
Return type:	`Annotation`

setImage(filename=None, path=None, frame=None, external_id=None, timestamp=None, width=None, height=None, id=None)[source]¶

Update or create new Image entry with the given parameters.

Parameters:	filename (string, optional) – the filename of the image (including the extension) path (string, int, `Path`, optional) – the path string, id or entry of the image to insert frame (int, optional) – the frame number if the image is part of a video external_id (int, optional) – an external id for the image. Only necessary if the annotation server is used timestamp (datetime object, optional) – the timestamp of the image width (int, optional) – the width of the image height (int, optional) – the height of the image id (int, optional) – the id of the image
Returns:	image – the changed or created `Image` entry
Return type:	`Image`

setLine(image=None, frame=None, filename=None, x1=None, y1=None, x2=None, y2=None, type=None, processed=None, style=None, text=None, id=None)[source]¶

Insert or update an Line object in the database.

Parameters:	image (int, `Image`, optional) – the image of the line. frame (int, optional) – the frame of the images of the line. filename (string, optional) – the filename of the image of the line. x1 (int, optional) – the x coordinate of the start of the line. y1 (int, optional) – the y coordinate of the start of the line. x2 (int, optional) – the x coordinate of the end of the line. y2 (int, optional) – the y coordinate of the end of the line. type (string, `MarkerType`, optional) – the marker type (or name) of the line. processed (int, optional) – the processed flag of the line. text (string, optional) – the text of the line. id (int, optional) – the id of the line.
Returns:	line – the created or changed `Line` item.
Return type:	`Line`

setLines(image=None, frame=None, filename=None, x1=None, y1=None, x2=None, y2=None, type=None, processed=None, style=None, text=None, id=None)[source]¶

Insert or update multiple Line objects in the database.

Parameters:	image (int, `Image`, array_like, optional) – the image/s of the lines. frame (int, array_like, optional) – the frame/s of the images of the lines. filename (string, array_like, optional) – the filename/s of the images of the lines. x1 (int, array_like, optional) – the x coordinate/s of the start of the lines. y1 (int, array_like, optional) – the y coordinate/s of the start of the lines. x2 (int, array_like, optional) – the x coordinate/s of the end of the lines. y2 (int, array_like, optional) – the y coordinate/s of the end of the lines. type (string, `MarkerType`, array_like, optional) – the marker type/s (or name/s) of the lines. processed (int, array_like, optional) – the processed flag/s of the lines. track (int, `Track`, array_like, optional) – the track id/s or instance/s of the lines. text (string, array_like, optional) – the text/s of the lines. id (int, array_like, optional) – the id/s of the lines.
Returns:	success – it the inserting was successful.
Return type:	bool

setMarker(image=None, frame=None, filename=None, x=None, y=None, type=None, processed=None, track=None, style=None, text=None, id=None)[source]¶

Insert or update an Marker object in the database.

Parameters:	image (int, `Image`, optional) – the image of the marker. frame (int, optional) – the frame of the images of the marker. filename (string, optional) – the filename of the image of the marker. x (int, optional) – the x coordinate of the marker. y (int, optional) – the y coordinate of the marker. type (string, `MarkerType`, optional) – the marker type (or name) of the marker. processed (int, optional) – the processed flag of the marker. track (int, `Track`, optional) – the track id or instance of the marker. text (string, optional) – the text of the marker. id (int, optional) – the id of the marker.
Returns:	marker – the created or changed `Marker` item.
Return type:	`Marker`

setMarkerType(name=None, color=None, mode=None, style=None, text=None, hidden=None, id=None)[source]¶

Insert or update an MarkerType object in the database.

Parameters:	name (str, optional) – the name of the type color (str, optional) – hex code string for rgb color of style “#00ff3f” mode (int, optional) – mode of the marker type (marker 0, rect 1, line 2, track 4) style (str, optional) – style string text (str, optional) – display text hidden (bool, optional) – whether the type should be displayed in ClickPoints id (int, optional) – id of the `MarkerType` object
Returns:	entries – the created `MarkerType` with the desired name or None.
Return type:	object

setMarkers(image=None, frame=None, filename=None, x=None, y=None, type=None, processed=None, track=None, style=None, text=None, id=None)[source]¶

Insert or update multiple Marker objects in the database.

Parameters:	image (int, `Image`, array_like, optional) – the image/s of the markers. frame (int, array_like, optional) – the frame/s of the images of the markers. filename (string, array_like, optional) – the filename/s of the images of the markers. x (int, array_like, optional) – the x coordinate/s of the markers. y (int, array_like, optional) – the y coordinate/s of the markers. type (string, `MarkerType`, array_like, optional) – the marker type/s (or name/s) of the markers. processed (int, array_like, optional) – the processed flag/s of the markers. track (int, `Track`, array_like, optional) – the track id/s or instance/s of the markers. text (string, array_like, optional) – the text/s of the markers. id (int, array_like, optional) – the id/s of the markers.
Returns:	success – it the inserting was successful.
Return type:	bool

setMask(image=None, frame=None, filename=None, data=None, id=None)[source]¶

Update or create new Mask entry with the given parameters.

Parameters:	image (int, `Image`, optional) – the image for which the mask should be set. If omitted, frame number or filename should be specified instead. frame (int, optional) – frame number of the images, which masks should be set. If omitted, image or filename should be specified instead. filename (string, optional) – filename of the image, which masks should be set. If omitted, image or frame number should be specified instead. data (ndarray, optional) – the mask data of the mask to set. Must have the same dimensions as the corresponding image, but only one channel, and it should be using the data type uint8. id (int, optional) – id of the mask entry.
Returns:	mask – the changed or created `Mask` entry.
Return type:	`Mask`

setMaskType(name=None, color=None, index=None, id=None)[source]¶

Update or create a new a MaskType entry with the given parameters.

Parameters:	name (string, optional) – the name of the mask type. color (string, optional) – the color of the mask type. index (int, optional) – the index of the mask type, which is used for painting this mask type. id (int, optional) – the id of the mask type.
Returns:	entries – the changed or created `MaskType` entry.
Return type:	`MaskType`

setPath(path_string=None, id=None)[source]¶

Update or create a new Path entry with the given parameters.

Parameters:	path_string (string, optional) – the string specifying the path. id (int, optional) – the id of the paths.
Returns:	entries – the changed or created `Path` entry.
Return type:	`Path`

setRectangle(image=None, frame=None, filename=None, x=None, y=None, width=None, height=None, type=None, processed=None, style=None, text=None, id=None)[source]¶

Insert or update an Rectangle object in the database.

Parameters:	image (int, `Image`, optional) – the image of the rectangle. frame (int, optional) – the frame of the images of the rectangle. filename (string, optional) – the filename of the image of the rectangle. x (int, optional) – the x coordinate of the upper left corner of the rectangle. y (int, optional) – the y coordinate of the upper left of the rectangle. width (int, optional) – the width of the rectangle. height (int, optional) – the height of the rectangle. type (string, `MarkerType`, optional) – the marker type (or name) of the rectangle. processed (int, optional) – the processed flag of the rectangle. text (string, optional) – the text of the rectangle. id (int, optional) – the id of the rectangle.
Returns:	rectangle – the created or changed `Rectangle` item.
Return type:	`Rectangle`

setRectangles(image=None, frame=None, filename=None, x=None, y=None, width=None, height=None, type=None, processed=None, style=None, text=None, id=None)[source]¶

Insert or update multiple Rectangle objects in the database.

Parameters:	image (int, `Image`, array_like, optional) – the image/s of the rectangles. frame (int, array_like, optional) – the frame/s of the images of the rectangles. filename (string, array_like, optional) – the filename/s of the images of the rectangles. x (int, array_like, optional) – the x coordinate/s of the upper left corner/s of the rectangles. y (int, array_like, optional) – the y coordinate/s of the upper left corner/s of the rectangles. width (int, array_like, optional) – the width/s of the rectangles. height (int, array_like, optional) – the height/s of the rectangles. type (string, `MarkerType`, array_like, optional) – the marker type/s (or name/s) of the rectangles. processed (int, array_like, optional) – the processed flag/s of the rectangles. track (int, `Track`, array_like, optional) – the track id/s or instance/s of the rectangles. text (string, array_like, optional) – the text/s of the rectangles. id (int, array_like, optional) – the id/s of the rectangles.
Returns:	success – it the inserting was successful.
Return type:	bool

setTag(name=None, id=None)[source]¶

Set a specific Tag entry by its name or database ID

Parameters:	name (str) – name of the tag id (int) – id of `Tag` entry
Returns:	entries – object of class `Tag`
Return type:	`Tag`

setTrack(type, style=None, text=None, hidden=None, id=None, uid=None)[source]¶

Insert or update a Track object.

Parameters:	type (`MarkerType`, str) – the marker type or name of the marker type for the track. style – the `Track` specific style entry text – the `Track` specific text entry hidden – wether the track should be displayed in ClickPoints id (int, array_like) – the `Track` ID
Returns:	track – a new `Track` object
Return type:	track object