Acquisition hooks

Acquisition hooks allow custom code to be injected at specific points in the acquisition process. This could be used, for example, to:

Execute arbitrary code during the acquisition cycle
Modify or delete acquisition events on-the-fly
Communicate with external devices for Hardware Triggering and Sequencing

Types of Hooks

There are three types of hooks, each executed at a different point in the acquisition cycle:

pre_hardware_hook: Executed before hardware updates
post_hardware_hook: Executed after hardware updates, just before image capture
post_camera_hook: Executed after the camera has been instructed to take images or wait for an external trigger

Basic Usage

The simplest hook is a function that takes a single argument (the current acquisition event):

def hook_fn(event):
    # Custom code here
    return event

with Acquisition(directory='/path/to/saving/dir', name='acquisition_name',
                 post_hardware_hook_fn=hook_fn) as acq:
    # Acquisition code here

Modifying or Deleting Events

Hooks can modify or delete events by returning a modified event or not returning an event:

def hook_fn(event):
    if some_condition:
        return modified_event
    # Delete event by not returning anything

The effect of modifying or deleting events depends on the hook’s position in the acquisition cycle. For example:

post_camera_hook_fn: Modifications have no effect as hardware movement and camera activation have already occurred.
pre_hardware_hook_fn: Changes are fully applied. For example, modifying the z-position will cause the microscope to adjust its focus accordingly before image capture.