PYME.Acquire.microscope module

class PYME.Acquire.microscope.StateHandler(key, getFcn=None, setFcn=None, needCamRestart=False)

Bases: object

Define a state-change handler for a give state key, based on supplied get and set functions which interact with the underlying hardware.

This wrapper class serves two functions - a) allowing the get and set methods to be stored under a single dictionary key in the StateManager, and b) making sure a signal is fired when the state changes.

Parameters:

key : string

The hardware key - e.g. “Positioning.x”, or “Lasers.405.Power”. This will also be how the hardware state is recorder in the metadata.

getFcn : function

The function to call to get the value of the parameter. Should take one parameter which is the value to get

setFcn : function

The function to call to set the value of the parameter. Should take one parameter which is the value to set. Not providing a setFcn results in a read-only property.

needCamRestart : bool

Does this absolutely need a camera restart (e.g. we are changing which camera we are using). Will override other preferences.

Methods

setValue(value[, force]) Set the state of the controlled hardware to the given value and fire a signal.
setValue(value, force=False)

Set the state of the controlled hardware to the given value and fire a signal. The underlying function will not be called if old and new values are the same unless force=True.

class PYME.Acquire.microscope.StateManager(scope, handlers={})

Bases: object

Manages object (microscope) state by calling an appropriate state-handler for a given key.

Looks and behaves like a dictionary to the user, with individual pieces of hardware registering themselves to handle individual keys.

Methods

keys()
registerChangeListener(key, callback) Registers a function to be called when the state of a particular key changes.
registerHandler(key[, getFcn, setFcn, ...]) Register a harware key and the ascociated handlers
setItem(key, value[, stopCamera, force]) Set the value of one of our hardware components
setItems(stateDict[, stopCamera, force, ...]) Set multiple items at once - see setItem for details.
update(state) Update state from a dictionary
keys()
registerChangeListener(key, callback)

Registers a function to be called when the state of a particular key changes.

The key and value are provided as keyword arguments to the callback the callback should accept have the signature callback(**kwargs), or callback(key, value, **kwargs). Other keyword arguments might also be given.

registerHandler(key, getFcn=None, setFcn=None, needCamRestart=False)

Register a harware key and the ascociated handlers

Parameters:

key : string

The hardware key - e.g. “Positioning.x”, or “Lasers.405.Power”. This will also be how the hardware state is recorder in the metadata.

getFcn : function

The function to call to get the value of the parameter. Should take one parameter which is the value to get

setFcn : function

The function to call to set the value of the parameter. Should take one parameter which is the value to set. Not providing a setFcn results in a read-only property.

needCamRestart : bool

Does this absolutely need a camera restart (e.g. we are changing which camera we are using). Will override other preferences.

Notes

There are a few conventions and special key names which should be observed as this is how the camera will find hardware.

  • Keys should be hierachial, separated by dots
  • Piezos and stages should start with “Positioning.”, followed by an axis name, and use um as a unit.
  • Lasers should start with “Laser.” and define both “<lasername>.Power” and “<lasername>.On” (this is to allow lasers with external switches/shutters as well as )
setItem(key, value, stopCamera=False, force=False)

Set the value of one of our hardware components

Parameters:

key : string

The parameter identifier - e.g. “Positioning.x”

value : object

The value to set. This can be anything the registered handler understands but designing the handlers to accept something which is easily converted to text for the Metadata (see PYME.IO.MetaDataHandler) is advised.

stopCamera : bool

Should we stop the camera before setting the value and restart afterwards. Useful for things like integration time which might not be able to be changed on the fly, but also potentially as a way of achieving hardware synchronization.

force : bool

Whether we should call the set method even if the current state is already the desired state.

setItems(stateDict, stopCamera=False, force=False, ignoreMissing=False)

Set multiple items at once - see setItem for details.

Parameters:

stateDict : dictionary (or dictionary like object)

a dictionary of key : value pairs for each piece of hardware which wants to be updated.

stopCamera : bool

Should we stop the camera before setting the values and restart afterwards? Useful for things like integration time which might not be able to be changed on the fly, but also potentially as a way of achieving hardware synchronization.

force : bool

Whether we should call the set method even if the current state is already the desired state.

ignoreMissing : bool

Should we silently ignore keys that we don’t have handlers for. Used when setting state from e.g. sequence metadata which might have other irrelevent info.

update(state)

Update state from a dictionary

Parameters:

state : dict

A dictionary containing the new state

class PYME.Acquire.microscope.microscope

Bases: object

Attributes

pa property to catch access of what was previously called the scope.frameWrangler (the PreviewAcquisator)

Methods

AddVoxelSizeSetting(name, x, y) Adds a new voxel size setting.
EnableJoystick([enable])
GenStartMetadata(mdh) Collects the metadata we want to record at the start of a sequence
GetActiveCameraName() Get the name / key of the currently active camera
GetPixelSize() Get the (sample space) pixel size for the current camera
GetPos()
GetPosRange()
PanCamera(dx, dy) Moves / pans the stage my a given offset, in pixels relative to the camera, correcting for any differences in rotation and mirroring between camera and stage axes.
SetPos(**kwargs)
SetVoxelSize(voxelsizename[, camName]) Set the camera voxel size, from a pre-existing voxel size seting.
genStatus() Generate a status message.
initialize(init_script_name[, locals])
register_camera(cam, name[, port, rotate, ...])
register_piezo(piezo, axis_name[, ...]) Register a piezo with the microscope object
satCheck(source, **kwargs) Check to see if the current frame is saturated and stop the camera/
startFrameWrangler() Start the frame wrangler.
turnAllLasersOff() Turn all attached lasers off.
AddVoxelSizeSetting(name, x, y)

Adds a new voxel size setting.

The reason for multiple settings is to easily support switching between different cameras and/or optical configurations such as tube lenses, splitters, etc ...

Parameters:

name : string

The name to use for the new setting

x : float

the pixelsize along the x axis in um

y : float

the pixelsize along the y axis in um

EnableJoystick(enable=True)
GenStartMetadata(mdh)

Collects the metadata we want to record at the start of a sequence

Parameters:

mdh : object derived from PYME.IO.MetaDataHandler.MDHandlerBase

The metadata handler to which we should write our metadata

GetActiveCameraName()

Get the name / key of the currently active camera

GetPixelSize()

Get the (sample space) pixel size for the current camera

Returns:

pixelsize : tuple

the pixel size in the x and y axes, in um

GetPos()
GetPosRange()
PanCamera(dx, dy)

Moves / pans the stage my a given offset, in pixels relative to the camera, correcting for any differences in rotation and mirroring between camera and stage axes.

TODO: fix to use state based position setting

SetPos(**kwargs)
SetVoxelSize(voxelsizename, camName=None)

Set the camera voxel size, from a pre-existing voxel size seting.

Parameters:

voxelsizename : string

The name of the voxelsize setting to use. This should have been created using the AddVoxelSize function.

camName : string

The name of the camera to ascociate the setting with. If None, then the currently selected camera is used.

genStatus()

Generate a status message. TODO - move this to the GUI?

initialize(init_script_name, locals={})
pa

property to catch access of what was previously called the scope.frameWrangler (the PreviewAcquisator)

register_camera(cam, name, port='', rotate=False, flipx=False, flipy=False)
register_piezo(piezo, axis_name, multiplier=1, needCamRestart=False, channel=0)

Register a piezo with the microscope object

Parameters:

piezo : PYME.Acquire.Hardware.Piezos.base_piezo.PiezoBase instance

the piezo to register

axis_name : string

the axis name, e.g. ‘x’, ‘y’, ‘z’

multiplier : float, typically either 1 or -1

what to multiply the positions by to match the directionality in the displayed image and make panning etc work.

needCamRestart : bool

whether to restart the camera after changing the position (mostly for simulation and fake piezos)

satCheck(source, **kwargs)

Check to see if the current frame is saturated and stop the camera/ close the shutter if necessary

TODO: could use a rewrite / new inspection.

startFrameWrangler()

Start the frame wrangler. Gets called during post-init phase of aquiremainframe.

turnAllLasersOff()

Turn all attached lasers off.

TODO - does this fit with the new state based paradigm?