tomoscan.tomoscan

Software for tomography scanning with EPICS

Classes

TomoScan

Base class for tomography scanning with EPICS.

Functions:

tomoscan

exception tomoscan.tomoscan.CameraTimeoutError

Bases: Exception

Exception raised when the camera times out during a scan.

exception tomoscan.tomoscan.FileOverwriteError

Bases: Exception

Exception raised when a file would be overwritten.

exception tomoscan.tomoscan.ScanAbortError

Bases: Exception

Exception raised when user wants to abort a scan.

class tomoscan.tomoscan.TomoScan(pv_files, macros)

Bases: object

Base class used for tomography scanning with EPICS

Parameters

• pv_files (list of str) – List of files containing EPICS pvNames to be used.

• macros (dict) – Dictionary of macro definitions to be substituted when reading the pv_files

abort_scan()

Aborts a scan that is running and performs the operations needed when a scan is aborted.

This does the following:

• Sets scan_is_running, a flag that is checked in wait_camera_done(). If wait_camera_done() finds the flag set then it raises a ScanAbortError exception.

• Stops the rotation motor.

• Stops the file saving plugin.

begin_scan()

Performs the operations needed at the very start of a scan.

This base class method does the following:

• Sets the status string in the ScanStatus PV.

• Stops the camera acquisition.

• Calls set_exposure_time()

• Copies the FilePath and FileName PVs to the areaDetector file plugin.

• Sets class variables with the important scan parameters

• Checks whether the file that will be saved by the file plugin already exists. If it does, and if the OverwriteWarning PV is ‘Yes’ then it opens a dialog box asking the user if they want to overwrite the file. If they answer ‘No’ then a FileOverwriteError exception is raised.

It is expected that most derived classes will override this method. In most cases they should first call this base class method, and then perform any beamline-specific operations.

check_pvs_connected()

Checks whether all EPICS PVs are connected.

Returns

bool – True if all PVs are connected, otherwise False.

close_shutter()

Closes the shutter to collect dark fields.

The value in the CloseShutterValue PV is written to the CloseShutter PV.

collect_dark_fields()

Collects dark field data

This base class method does the following:

• Sets the scan status message

• Calls close_shutter()

• Sets the HDF5 data location for dark fields

• Sets the FrameType to “DarkField”

Derived classes must override this method to actually collect the dark fields. In most cases they should call this base class method first and then perform the beamline-specific operations.

collect_flat_fields()

Collects flat field data

This base class method does the following:

• Sets the scan status message

• Calls open_shutter()

• Calls move_sample_out()

• Sets the HDF5 data location for flat fields

• Sets the FrameType to “FlatField”

Derived classes must override this method to actually collect the flat fields. In most cases they should call this base class method first and then perform the beamline-specific operations.

collect_projections()

Collects projection data

This base class method does the following:

• Sets the scan status message

• Calls open_shutter()

• Calls move_sample_in()

• Sets the HDF5 data location for projection data

• Sets the FrameType to “Projection”

Derived classes must override this method to actually collect the projections. In most cases they should call this base class method first and then perform the beamline-specific operations.

compute_frame_time()

Computes the time to collect and readout an image from the camera.

This method is used to compute the time between triggers to the camera. This can be used, for example, to configure a trigger generator or to compute the speed of the rotation stage.

The calculation is camera specific. The result can depend on the actual exposure time of the camera, and on a variety of camera configuration settings (pixel binning, pixel bit depth, video mode, etc.)

The current version only supports the Point Grey Grasshopper3 GS3-U3-23S6M. The logic for additional cameras should be added to this function in the future if the camera is expected to be used at more than one beamline. If the camera is only to be used at a single beamline then the code should be added to this method in the derived class

Returns

float – The frame time, which is the minimum time allowed between triggers for the value of the ExposureTime PV.

copy_file_path()

Copies the FilePath PV to file plugin FilePath

copy_file_path_exists()

Copies the file plugin FilePathExists_RBV PV to FilePathExists

end_scan()

Performs the operations needed at the very end of a scan.

This base class method does the following:

• Sets the status string in the ScanStatus PV.

• If the ReturnRotation PV is Yes then it moves the rotation motor back to the position defined by the RotationStart PV. It does not wait for the move to complete.

• Sets the StartScan PV to 0. This PV is an EPICS busy record. Normally EPICS clients that start a scan with the StartScan PV will wait for StartScan to return to 0, often using the ca_put_callback() mechanism.

It is expected that most derived classes will override this method. In most cases they should first perform any beamline-specific operations and then call this base class method. This ensures that the scan is really complete before StartScan is set to 0.

fly_scan()

Performs the operations for a tomography fly scan, i.e. with continuous rotation.

This base class method does the following:

• Moves the rotation motor to position defined by the RotationStart PV.

• Calls begin_scan()

• If the DarkFieldMode PV is ‘Start’ or ‘Both’ calls collect_dark_fields()

• If the FlatFieldMode PV is ‘Start’ or ‘Both’ calls collect_flat_fields()

• Calls collect_projections()

• If the FlatFieldMode PV is ‘End’ or ‘Both’ calls collect_flat_fields()

• If the DarkFieldMode PV is ‘End’ or ‘Both’ calls collect_dark_fields()

• Calls end_scan

If there is either CameraTimeoutError exception or ScanAbortError exception during the scan, it jumps immediate to calling end_scan() and returns.

It is not expected that most derived classes will need to override this method, but they are free to do so if required.

load_configuration(file_name)

Loads a configuration from a file into the EPICS PVs.

Parameters

file_name (str) – The name of the file to save to.

move_sample_in()

Moves the sample to the in beam position for collecting projections.

The in-beam position is defined by the SampleInX and SampleInY PVs.

Which axis to move is defined by the FlatFieldAxis PV, which can be X, Y, or Both.

move_sample_out()

Moves the sample to the out of beam position for collecting flat fields.

The out of beam position is defined by the SampleOutX and SampleOutY PVs.

Which axis to move is defined by the FlatFieldAxis PV, which can be X, Y, or Both.

open_shutter()

Opens the shutter to collect flat fields or projections.

The value in the OpenShutterValue PV is written to the OpenShutter PV.

pv_callback(pvname=None, value=None, char_value=None, **kw)

Callback function that is called by pyEpics when certain EPICS PVs are changed

The PVs that are handled are:

• StartScan : Calls run_fly_scan()

• AbortScan : Calls abort_scan()

• MoveSampleIn : Runs MoveSampleIn() in a new thread.

• MoveSampleOut : Runs MoveSampleOut() in a new thread.

• ExposureTime : Runs set_exposure_time() in a new thread.

• FilePath : Runs copy_file_path in a new thread.

• FPFilePathExists : Runs copy_file_path_exists in a new thread.

• FPWriteStatus: Runs abort_scan()

read_pv_file(pv_file_name, macros)

Reads a file containing a list of EPICS PVs to be used by TomoScan.

Parameters

• pv_file_name (str) – Name of the file to read

• macros (dict) – Dictionary of macro substitution to perform when reading the file

reset_watchdog()

Sets the watchdog timer to 5 every 3 seconds

run_fly_scan()

Runs fly_scan() in a new thread.

save_configuration(file_name)

Saves the current configuration PVs to a file.

A new dictionary is created, containing the key for each PV in the config_pvs dictionary and the current value of that PV. This dictionary is written to the file in JSON format.

Parameters

file_name (str) – The name of the file to save to.

set_exposure_time(exposure_time=None)

Sets the camera exposure time.

The exposure_time is written to the camera’s AcquireTime PV.

Parameters

exposure_time (float, optional) – The exposure time to use. If None then the value of the ExposureTime PV is used.

set_scan_exposure_time(exposure_time=None)

Sets the camera exposure time during the scan.

The exposure_time is written to the camera’s AcquireTime PV.

Parameters

exposure_time (float, optional) – The exposure time to use. If None then the value of the ExposureTime PV is used.

show_pvs()

Prints the current values of all EPICS PVs in use.

The values are printed in three sections:

• config_pvs : The PVs that are part of the scan configuration and are saved by save_configuration()

• control_pvs : The PVs that are used for EPICS control and status, but are not saved by save_configuration()

• pv_prefixes : The prefixes for PVs that are used for the areaDetector camera, file plugin, etc.

signal_handler(sig, frame)

Calls abort_scan when ^C is typed

update_status(start_time)

When called updates ImagesCollected, ImagesSaved, ElapsedTime, and RemainingTime.

Parameters

start_time (time) – Start time to calculate elapsed time.

Returns

elapsed_time (float) – Elapsed time to be used for time out.

wait_camera_done(timeout)

Waits for the camera acquisition to complete, or for abort_scan() to be called.

While waiting this method periodically updates the status PVs ImagesCollected, ImagesSaved, ElapsedTime, and RemainingTime.

Parameters

timeout (float) – The maximum number of seconds to wait before raising a CameraTimeoutError exception.

Raises

• ScanAbortError – If abort_scan() is called

• CameraTimeoutError – If acquisition has not completed within timeout value.