pudu.utils

Shared utilities used across PUDU protocols.

  • Camera — captures images and records video via ffmpeg during OT-2 protocol runs.

  • SmartPipette — pipette wrapper that uses the Opentrons liquid-tracking API to compute safe aspiration heights for conical tubes, preventing tip plunging as tubes empty.

  • colors — list of 24 hex colour strings used to colour-code liquids in the Opentrons deck visualiser.

pudu.utils.colors = ['#4040BF', '#BF4040', '#40BF40', '#A640BF', '#BFBF40', '#BF7340', '#40BFBF', '#BF40A6', '#73BF40', '#4073BF', '#BF8C40', '#40BF73', '#7340BF', '#A6BF40', '#BF5940', '#40A6BF', '#BF4073', '#59BF40', '#BFA640', '#40BFA6', '#8CBF40', '#40BF59', '#40BF8C', '#BF40A6']

Built-in mutable sequence.

If no argument is given, the constructor creates a new empty list. The argument must be an iterable if specified.

class pudu.utils.Camera(video_size='320x240', picture_size='640x480', video_device='/dev/video0', storage_path='/data/user_storage')[source]

Bases: object

Camera class for handling picture and video capture during Opentrons protocols.

This class encapsulates all camera functionality including: - Taking snapshots at specific protocol steps - Recording video during protocol execution - Handling simulation mode gracefully - Managing ffmpeg processes

Parameters:

  • video_size (str)

  • picture_size (str)

  • video_device (str)

  • storage_path (str)

__init__(video_size='320x240', picture_size='640x480', video_device='/dev/video0', storage_path='/data/user_storage')[source]

Initialize Camera with configuration options.

Parameters:

  • video_size (str) – Resolution for video recording (default: “320x240”)

  • picture_size (str) – Resolution for picture capture (default: “640x480”)

  • video_device (str) – Video device path (default: “/dev/video0”)

  • storage_path (str) – Path where media files will be saved (default: “/data/user_storage”)

cleanup_ffmpeg_processes()[source]

Clean up any running ffmpeg processes using killall.

Return type:

None

capture_picture(protocol, when='image')[source]

Take a picture at a specific protocol step.

Parameters:

  • protocol – Opentrons protocol context

  • when (str) – Description of when the picture was taken (used in filename)

Returns:

Filename of captured image if successful, None if simulation or failed

Return type:

None

start_video(protocol)[source]

Start video recording.

Parameters:

protocol – Opentrons protocol context

Returns:

Video process handle if successful, None if simulation or failed

Return type:

None

stop_video(protocol)[source]

Stop video recording.

Parameters:

  • protocol – Opentrons protocol context

  • video_process – Video process to stop (uses active process if None)

Return type:

None

class pudu.utils.SmartPipette(pipette, protocol)[source]

Bases: object

Opentrons pipette wrapper that uses the API’s liquid-tracking system to compute safe aspiration heights for conical tubes.

For standard flat-bottom or round-bottom wells, SmartPipette behaves identically to the underlying pipette. For conical tubes (detected by labware name or the use flag), it queries the current liquid volume via well.current_liquid_volume() and converts that to a millimetre height, keeping the tip above the meniscus and away from the narrow tip of the cone.

This prevents the pipette tip from plunging into an empty tube or aspirating air when a tube is nearly empty — a common failure mode in protocols that dispense large total volumes from a single stock tube (e.g. LB distribution during plating).

__init__(pipette, protocol)[source]

Initialize SmartPipette.

Parameters:

  • pipette – A loaded Opentrons pipette instrument object.

  • protocol – The active ProtocolContext. Must support define_liquid (API level ≥ 2.14).

Raises:

RuntimeError – If the protocol context does not expose liquid tracking (API level too old).

is_conical_tube(well, use=False)[source]

Check if the well is from a conical tube labware or manually set as true

Parameters:

use (bool)

Return type:

bool

get_well_volume(well)[source]

Get current volume in well using pure API method

Return type:

float | None

get_well_height(well)[source]

Get current liquid height using pure API method (if available)

Return type:

float | None

get_conical_tube_aspiration_height(well)[source]

Calculate safe aspiration height for conical tubes using proven method Uses API liquid tracking to get current volume

Return type:

float

get_aspiration_location(well, use=False)[source]

Get intelligent aspiration location using API volume data and proven height calculation

Parameters:

use (bool)

Return type:

float

liquid_transfer(volume, source, destination, asp_rate=0.5, disp_rate=1.0, blow_out=True, touch_tip=False, mix_before=0.0, mix_after=0.0, mix_reps=3, new_tip=True, drop_tip=True, use=False)[source]

Transfer liquid using pure API liquid tracking for volume management

Returns:

True if transfer was successful, False if insufficient volume

Return type:

bool

Parameters: