CameraDrawBase

class CameraDrawBase[source]

Bases: object

Base class for defining custom camera draw on frame behavior.

Override this class to add or change the default drawing behavior on the camera feed for both BOX and CORRIDOR cameras.

You have access to self.task, so any variable or function defined in the task can be used to specify the drawing behavior to perform.

Two methods are called automatically on every frame:

draw(cam)

Uses cv2 to draw on cam.frame; changes go to disk and screen.

draw_preview(cam, painter)

Uses QPainter; goes to screen only — never saved to the video file.

The following cam attributes are updated every frame and available inside both methods:

Identity & state

  • cam.name — 'BOX' or 'CORRIDOR'.

  • cam.task_is_running — True if a task is active, False if not.

  • cam.view_detection — whether detection overlays are enabled in the GUI.

  • cam.tracking — whether animal position tracking is active (BOX only).

  • cam.color — Color.BLACK or Color.WHITE: which pixels to detect.

Frame data

  • cam.frame — current frame as a BGR numpy array (read/write).

  • cam.width, cam.height — frame dimensions in pixels.

  • cam.frame_number — frames captured since recording started.

  • cam.timing — milliseconds elapsed since recording started.

Session info

  • cam.filename — base name of the current video file (empty if not recording).

  • cam.trial — current trial number (0 if no task running or CORRIDOR camera).

  • cam.annotation — short text rendered on every frame at a fixed position in the status bar. Set it from a task with cam_box.write_text("reward"); it persists until changed. Also saved frame-by-frame to the session CSV, so it is useful for marking task events for post-hoc analysis.

  • cam.items_to_draw — plain dict for passing arbitrary data from the task to the drawing methods without coupling the task to this class. The task populates it at any point (e.g. cam_box.items_to_draw["target"] = (x, y, r)) and draw / draw_preview can read it to render complex overlays such as circles, custom shapes, or stimulus boundaries.

Detection areas

  • cam.number_of_areas — number of configurable areas (always 4).

  • cam.areas — list of [x1, y1, x2, y2] pixel coordinates per area.

  • cam.areas_active — bool list, whether each area is enabled.

  • cam.areas_allowed — bool list, whether animals are allowed in each area.

Detection results

  • cam.masks — grayscale numpy arrays with the thresholded mask per area.

  • cam.counts — detected pixel count per area.

  • cam.x_position, cam.y_position — tracked animal position in pixels (-1 if not detected).

Task access

  • self.task — the current task instance.

__init__() → None[source]

Methods

draw(cam: Camera) → None[source]

Default cv2 drawing — goes to disk and screen. Status texts and pixel counts always run for both cameras. Detection (thresholded mask + areas) is CORRIDOR-only here so it goes to disk. For BOX, detection goes to draw_preview (screen only).

Parameters:

cam – The camera instance.

draw_preview(cam: Camera, painter: QPainter) → None[source]

Default QPainter drawing — goes to screen only.

Parameters:

  • cam – The camera instance.

  • painter – Active QPainter on the preview widget.

write_status_texts(cam: Camera) → None[source]

Draws the text status bar background and writes filename/timing text.

write_pixel_detection_texts(cam: Camera) → None[source]

Writes pixel count for each active area onto the frame.

draw_detection_mask_corridor(cam: Camera) → None[source]

Blends the thresholded detection mask into the frame via cv2.

For black detection: darkens detected pixels using bitwise_and. For white detection: brightens detected pixels using bitwise_or.

draw_detection_areas_corridor(cam: Camera) → None[source]

Draws detection area rectangles onto the frame.

draw_detection_mask_box(cam: Camera, painter: QPainter, scale_x: float, scale_y: float) → None[source]

Draws thresholded detection masks via QPainter (screen only).

Converts each area’s grayscale mask to a semi-transparent RGBA QImage and draws it at the scaled position on the preview widget. Black detection → dark overlay where the animal is. White detection → bright overlay where the animal is.

draw_detection_areas_box(cam: Camera, painter: QPainter, scale_x: float, scale_y: float) → None[source]

Draws area rectangles (and X for NOT_ALLOWED areas) via QPainter.

draw_detection_position_box(cam: Camera, painter: QPainter, scale_x: float, scale_y: float) → None[source]

Draws a filled circle at the tracked animal position via QPainter.