ethoscope.core package¶
Module contents¶
This module is the core of the ethoscope. It defines the building bricks at the basis of the package.
Overview:
Monitor
is the most important class. It glues together all the other elements of the package in order to perform (video tracking, interacting , data writing and drawing).TrackingUnit
are internally used by monitor. They forces to conceptually treat each ROI independently.ROI
formalise and facilitates the use of Region Of Interests.variables
are custom types of variables that result from tracking and interacting.DataPoint
stores efficiently Variables.
ethoscope.core.monitor module¶
-
class
ethoscope.core.monitor.
Monitor
(camera, tracker_class, rois=None, stimulators=None, *args, **kwargs)[source]¶ Bases:
object
Class to orchestrate the tracking of multiple objects. It performs, in order, the following actions:
- Requesting raw frames (delegated to
BaseCamera
) - Cutting frame portions according to the ROI layout (delegated to
TrackingUnit
). - Detecting animals and computing their positions and other variables (delegated to
BaseTracker
). - Using computed variables to interact physically (i.e. feed-back) with the animals (delegated to
BaseStimulator
). - Drawing results on a frame, optionally saving video (delegated to
BaseDrawer
). - Saving the result of tracking in a database (delegated to
ResultWriter
).
Parameters: - camera (
BaseCamera
) – a camera object responsible of acquiring frames and associated time stamps - tracker_class (class) – The algorithm that will be used for tracking. It must inherit from
BaseTracker
- rois (list(
ROI
)) – A list of region of interest. - stimulators (list(
BaseInteractor
) – The class that will be used to analyse the position of the object and interact with the system/hardware. - args – additional arguments passed to the tracking algorithm
- kwargs – additional keyword arguments passed to the tracking algorithm
-
last_positions
¶ Returns: The last positions (and other recorded variables) of all detected animals Return type: dict
-
last_time_stamp
¶ Returns: The time, in seconds, since monitoring started running. It will be 0 if the monitor is not running yet. Return type: float
-
run
(result_writer=None, drawer=None)[source]¶ Runs the monitor indefinitely.
Parameters: - result_writer (
ResultWriter
) – A result writer used to control how data are saved. None means no results will be saved. - drawer (
BaseDrawer
) – A drawer to plot the data on frames, display frames and/or save videos. None means none of the aforementioned actions will performed.
- result_writer (
- Requesting raw frames (delegated to
ethoscope.core.tracking_unit module¶
-
class
ethoscope.core.tracking_unit.
TrackingUnit
(tracking_class, roi, stimulator=None, *args, **kwargs)[source]¶ Bases:
object
Class instantiating a tracker(
BaseTracker
), and linking it with an individual ROI(ROI
) and stimulator(BaseStimulator
). Typically, several TrackingUnit objects are built internally by a Monitor(Monitor
).Parameters: - tracker_class (class) – The algorithm that will be used for tracking. It must inherit from
BaseTracker
- roi (
ROI
.) – A region of interest. - stimulator (
BaseStimulator
.) – an object used to physically interact with the detected animal. - args – additional arguments passed to the tracking algorithm.
- kwargs – additional keyword arguments passed to the tracking algorithm.
-
get_last_positions
(absolute=False)[source]¶ The last position of the animal monitored by this TrackingUnit
Parameters: absolute – Whether the position should be relative to the top left corner of the raw frame (true), or to the top left of the used ROI (false). Returns: A container with the last variable recorded for this roi. Return type: DataPoint
-
stimulator
¶ Returns: A reference to the stimulator used by this TrackingUnit Return type: BaseStimulator
- tracker_class (class) – The algorithm that will be used for tracking. It must inherit from
ethoscope.core.roi module¶
-
class
ethoscope.core.roi.
ROI
(polygon, idx, value=None, orientation=None, regions=None)[source]¶ Bases:
object
Class to define a region of interest(ROI). Internally, ROIs are single polygons. At the moment, they cannot have any holes. The polygon defining the ROI is used to draw a mask to exclude off-target pixels (so cross-ROI info).
Parameters: -
apply
(img)[source]¶ Cut an image where the ROI is defined.
Parameters: img ( ndarray
) – An image. Typically either one or three channels uint8.Returns: a tuple containing the resulting cropped image and the associated mask (both have the same dimension). Return type: ( ndarray
,ndarray
)
-
get_feature_dict
()[source]¶ Returns: A dictionary of freatures for this roi. It containes the folowing fields: - “x”
- “y”
- “w”
- “h”
- “value”
- “idx”
Return type: dict
-
offset
¶ Returns: the x,y offset of the ROI compared to the frame it was build on. Return type: (int,int)
-
rectangle
¶ Returns: The upright bounding rectangle to the ROI formatted (x,y,w,h). Where x and y are to coordinates of the top left corner Return type: (int,int,int,int)
-
value
¶ Returns: the value of a ROI
-
ethoscope.core.variables module¶
-
class
ethoscope.core.variables.
BaseBoolVariable
[source]¶ Bases:
ethoscope.core.variables.BaseIntVariable
Abstract type encoding boolean values. Internally stored as int as bool type cannot be derived.
-
functional_type
= 'bool'¶
-
sql_data_type
= 'BOOLEAN'¶
-
-
class
ethoscope.core.variables.
BaseDistanceIntVar
[source]¶ Bases:
ethoscope.core.variables.BaseIntVariable
Abstract type encoding variables representing distances.
-
functional_type
= 'distance'¶
-
-
class
ethoscope.core.variables.
BaseIntVariable
[source]¶ Bases:
int
Template class for defining arbitrary variable types. Each class derived from this one should at least define the three following attributes:
- sql_data_type, The MySQL data type. This allows to use minimal space to save data points.
- header_name, The name of this variable. this will be used as the column name in the result table, so it must be unique.
- functional_type, A keyword defining what type of variable this is. For instance “distance”, “angle” or “proba”. this allow specific post-processing per functional type.
-
functional_type
= None¶
-
header_name
= None¶
-
sql_data_type
= 'SMALLINT'¶
-
class
ethoscope.core.variables.
BaseRelativeVariable
[source]¶ Bases:
ethoscope.core.variables.BaseDistanceIntVar
Abstract type encoding distance variables that can be expressed relatively to an origin. They converted to absolute using information form the ROI.
-
class
ethoscope.core.variables.
HeightVariable
[source]¶ Bases:
ethoscope.core.variables.BaseDistanceIntVar
Type storing the height of a detected object.
-
header_name
= 'h'¶
-
-
class
ethoscope.core.variables.
IsInferredVariable
[source]¶ Bases:
ethoscope.core.variables.BaseBoolVariable
Type encoding whether a data point is inferred (from past values) or observed; 0 or 1, respectively.
-
header_name
= 'is_inferred'¶
-
-
class
ethoscope.core.variables.
Label
[source]¶ Bases:
ethoscope.core.variables.BaseIntVariable
Type encoding a discrete label when several objects, in the same ROI, are detected.
-
functional_type
= 'label'¶
-
header_name
= 'label'¶
-
-
class
ethoscope.core.variables.
PhiVariable
[source]¶ Bases:
ethoscope.core.variables.BaseIntVariable
Type encoding the angle of a detected object, in degrees.
-
functional_type
= 'angle'¶
-
header_name
= 'phi'¶
-
-
class
ethoscope.core.variables.
WidthVariable
[source]¶ Bases:
ethoscope.core.variables.BaseDistanceIntVar
Type storing the width of a detected object.
-
header_name
= 'w'¶
-
-
class
ethoscope.core.variables.
XPosVariable
[source]¶ Bases:
ethoscope.core.variables.BaseRelativeVariable
Type storing the X position of a detected object.
-
header_name
= 'x'¶
-
-
class
ethoscope.core.variables.
XYDistance
[source]¶ Bases:
ethoscope.core.variables.BaseIntVariable
Type storing distance moved between two consecutive observations. Log10 x 1000 is used so that floating point distance is stored as an int.
-
functional_type
= 'relative_distance_1e6'¶
-
header_name
= 'xy_dist_log10x1000'¶
-
-
class
ethoscope.core.variables.
YPosVariable
[source]¶ Bases:
ethoscope.core.variables.BaseRelativeVariable
Type storing the Y position of a detected object.
-
header_name
= 'y'¶
-
-
class
ethoscope.core.variables.
mLogLik
[source]¶ Bases:
ethoscope.core.variables.BaseIntVariable
Type representing a log likelihood. It should be multiplied by 1000 to be stored as an int.
-
functional_type
= 'proba'¶
-
header_name
= 'mlog_L_x1000'¶
-
ethoscope.core.data_point module¶
-
class
ethoscope.core.data_point.
DataPoint
(data)[source]¶ Bases:
collections.OrderedDict
A container to store variables. It derived from
OrderedDict
. Variables are accessible by header name, which is an individual identifier of a variable type (seeBaseIntVariable
):>>> from ethoscope.core.variables import DataPoint, XPosVariable, YPosVariable, HeightVariable >>> y = YPosVariable(18) >>> x = XPosVariable(32) >>> data = DataPoint([x,y]) >>> print data["x"] >>> h = HeightVariable(3) >>> data.append(h) >>> print data
Parameters: data (list( BaseIntVariable
)) – a list of data points-
append
(item)[source]¶ Add a new variable in the DataPoint The order is preserved.
Parameters: - item – A variable to be added.
- item –
BaseIntVariable
Returns:
-