MarCCD X-ray Detector System

The MarCCD X-ray detectors are programmable cameras. Access to the camera is not done with EPICS. Instead, the camera host machine provides a TCP socket with a custom protocol for communication. The camera may be used as a standard Py4Syn ICountable, but instead of returning values to be plotted, the acquired images are stored into files.

The MarCCD Py4Syn class supports using software controlled shutters. The shutters supported can be one of two types: normal shutters and toggle shutters. Both shutters are accessed as EPICS PVs representing bits. The difference is that normal shutters have zero and one values to represent the open and closed states, while the toggle shutter uses one PV to toggle the shutter state and another to read back the current state.

Using EPICS MarCCD camera module

Usage of Python class for EPICS MarCCD cameras.

class py4syn.epics.MarCCDClass.MarCCD(mnemonic, address)

Class to control MarCCD cameras via TCP sockets.

Examples

>>> from shutil import move
>>> from py4syn.epics.MarCCDClass import MarCCD
>>> from py4syn.epics.ShutterClass import SimpleShutter
>>> 
>>> def getImage(host='localhost', port=2222, fileName='image.tif', shutter=''):
...     shutter = SimpleShutter(shutter, shutter)
...     camera = MarCCD(name, (host, port))
...     camera.setCountTime(10)
...     camera.startCount()
...     shutter.open()
...     camera.wait()
...     camera.stopCount()
...     shutter.close()
...     camera.writeImage('/remote/' + fileName)
...     move('/remote/' + fileName, '/home/user/' + fileName)
...     camera.close()
...
>>> def acquireSetWithCorrection(camera, shutter, exposure=10, count=10, prefix='data'):
...     try:
...         shutter.close()
...         camera.darkNoise()
...         camera.setCountTime(exposure)
...         camera.setSubScan(count=2)
...
...         for i in range(count):
...             remote = '/remote/%s-%02d.tif' % (prefix, i)
...             local = '/home/user/%s-%02d.tif' % (prefix, i)
...             camera.startCount()
...             shutter.open()
...             camera.wait()
...             camera.stopCount()
...             shutter.close()
...             camera.waitForIdle()
...             camera.startCount()
...             shutter.open()
...             camera.wait()
...             camera.stopCount()
...             shutter.close()
...             camera.dezinger()
...             camera.correct()
...             camera.writeImage(remote)
...             move(remote, local)
...     finally:
...         camera.close()
...         shutter.close()
...

Constructor See py4syn.epics.StandardDevice

Parameters:

mnemonic : string

Camera mnemonic

address : tuple

Camera host server Internet address

canMonitor()

Abstract method to check if the device can or cannot be used as monitor.

Returns:

out : bool

canStopCount()

Abstract method to check if the device can or cannot stop the count and return values.

Returns:

out : bool

close()

Cleans up and closes camera remote connection. This method must be called when finishing operation with the camera.

correct()

Queues image correction on the MarCCD server. After the image is corrected, it can be saved to a file.

There are three corrections applied: dark noise image subtraction, flat field correction and geometric correction. The dark noise correction uses a dark image to fix the reference (zero) intensity levels for each pixel. The flat field correction uses a bright image to correct the gain for each pixel. The geometric correction fixes distortion from the fiber optic taper.

Note

The dark noise image should be frequently generated. Use the method darkNoise() for that.

See: darkNoise()

darkNoise(delay=0)

Prepares a dark noise image to be used as a correction image by the server. One of the steps after acquiring an image is to correct it by subtracting the dark noise image from it. This method is used to generate the dark noise image to be used later in the acquisitions. The method must be called with the camera covered. A dark noise image must be generated at least once after starting the MarCCD server.

Note

The following guideline is available on the MarCCD user guide: “The background doesn’t have to be retaken for every data image taken, but generally should be retaken at the start of every new data set, or once every half hour, whichever is sooner (depending on the thermal stability of the hutch). For the MarCCD detector, if a mismatch in the level of the 4 quadrants of data frames is noticed, the bias is probably drifting and should be recollected (and maybe should be set to be collected more often).”

Parameters:

delay : float

The time for each background acquisition. The MarCCD camera can either be calibrated with a zero delay between the acquisitions (this is called a bias frame acquisition in MarCCD manual), or with a non-zero (a standard dark frame acquisition). Note that 2 background acquisitions are done. They are then passed through the dezinger algorithm, which averages and removes outlier spots in the image.

dezinger()

Apply the dezinger correction algorithm in 2 images and store the resulting image in the MarCCD server. The dezinger algorithm averages corresponding pixels from each image, but if they deviate too much, it discards the brighter one and keeps the lower value. This removes the “zingers”, bright spots in the image, which are not caused by the input light.

To be able to use the dezinger method, 2 images must be present in server memory. This can be accomplished by calling setSubScan() before the acquisition.

Note

The following guildeline is present in MarCCD manual: “Dezingering does require special care that the two images are truly identical (same X-ray dose, same movement of the sample, etc.); otherwise the statistical test will yield unpredictable results. In particular, if the X-ray beam is not constant intensity, or the sample is decaying, then the exposure times and diffractometer motions must compensate for that. If there are significant differences between the frames, then the artifacts created by dezingering may yield worse results than simply using normal, single-read images with zingers in them. Though they are not aethetically pleasing, some kinds of data analysis can tolerate many zingers.

Examples

>>> def acquireTwiceAndDezinger(marccd, time):
...     marccd.setCountTime(time)
...     marccd.setSubScan(count=2)
...     marccd.startCount()
...     marccd.wait()
...     marccd.stopCount()
...     marccd.waitForIdle()
...     marccd.startCount()
...     marccd.wait()
...     marccd.stopCount()
...     marccd.dezinger()
...

getState(timeout=60)

Returns the camera state. The state can be used to check for errors, to find out which operations are queued or being executed and if the server is busy interpreting a command.

The camera state is an integer with a 4-bit value, plus five 4-bit fields: acquire, read, correct, write and (highest) dezinger. The low 4-bit state value can be 0, for idle, 7 for bad request and 8 for busy. Each 4-bit field has 4 flags: queued (0x1), executing (0x2), error (0x4) and reserved (0x8). For example, the state 0x011200 means that a read is executing, a correction is queued and a write is queued. The state mask 0x444444 can be used to look for an error on any operation. The lowest field (state) uses the value 8 to indicate it’s busy processing a command, so state 0x8 means “interpreting command”.

Parameters:

timeout : float

Time to wait for camera answer

Returns:

`int`

getValue(**kwargs)

This is a dummy getValue method that always returns zero, which is part of the py4syn.epics.ICountable interface. The MarCCD does not return a value while scanning. Instead, it stores a file with the resulting image.

isCounting()

Abstract method to check if the device is counting or not.

Returns:

out : bool

setCountTime(t)

Sets the image acquisition time.

Parameters:

t : float

Acquisition time

setImageSize(width, height)

Chooses the acquired image size.

Parameters:

width: `int`

Image width. Must be either 512, 1024 or 2048 and must be the equal to the image height.

height: `int`

Image height. Must be either 512, 1024 or 2048 and must be the equal to the image width.

setPresetValue(channel, val)

Abstract method to set the preset count of a countable target device.

Parameters:

channel : int

The monitor channel number

val : int

The preset value

Returns:

out : None

setState(state, timeout=60)

Changes the camera state bit field. This method does not change the operating state, just the reported integer value. It is a helper method to deal with a quirk in the MarCCD server that makes the error and busy bits to get stuck and never reset. Usually the only value that makes sense for the state is zero, to clear all the bits.

See: getState()

Parameters:

state : int

Time to wait for camera answer

timeout : float

Time to wait for camera answer

setSubScan(count=2)

Configure the MarCCD object to know that each acquisition will be done in multiple steps. This effectivelly means that a series of acquisitions will be done in sequence, which will be processed together, resulting in a single final image. This method is mainly required for the dezinger() method to work.

Parameters:

count : int

Number of sub scans that will compose a single final image. Can be either 1, to disable sub scan logic, or 2, which will make stopCount() store images alternatedly in “scratch” (auxiliary) memory and “raw” (main) memory.

startCount()

Starts acquiring an image. This will acquire image data until asked to stop with stopCount().

Note

Due to way the camera protocol is currently implemented, this method ignores the configured acquisition count time. Because of that, the proper way to do a timed acquisition is to follow this method call with wait(), then immediatelly call stopCount(). The py4syn.utils.scan.scan() function in Py4Syn executes this method sequence.

See: setCountTime(), stopCount(), wait()

Examples

>>> def acquire(marccd, time):
...     marccd.setCountTime(time)
...     marccd.startCount()
...     marccd.wait()
...     marccd.stopCount()
...

stateRequest(request, timeout=60)

Helper method used to get or set camera state.

Parameters:

request : string

Command to be passed to the camera

timeout : float

Time to wait for camera answer

Returns:

`int`

stopCount()

Stops acquiring the image and stores it into server memory. The acquired image will be available to apply corrections and to be written to an output file.

If no call to startCount() was done before calling this method, then nothing is done.

wait()

Blocks until the configured count time passes since the call to startCount(). The time amount is configured with setCountTime(), or 1 second by default.

If an acquisition has not been started, this method returns immediatelly.

See: setCountTime(), startCount()

waitForIdle()

Blocks until the camera server is completely idle. This is required because the camera and the server are slow and certain operations, in particular, multiple sequential acquisitions would fail without waiting for some time. Acquiring two images and dezingering them only works with this method being called between the acquisitions.

waitForImage()

Blocks until the acquired image has been corrected and written to disk. This can be used any time after calling stopCount() to make sure file operations can be performed on the resulting image (copied, post-processed, etc.)

waitUntil(condition, timeout=60)

Blocks until the camera state asserts a certain condition. This method can be used to confirm that an operation has started, or if the camera is reporting an error. The condition is a bit mask with the same meanings as described in getState(). For example, calling this method with condition set to 0x20 blocks until an aquisition is executing.

This method detects errors automatically by raising an exception if any error bit is set.

See: getState()

Parameters:

condition : int

State condition mask. If any of the condition bits is set, the condition is considered to be true.

timeout : float

Time to wait for the condition to be deasserted

waitWhile(condition, timeout=60)

Blocks while the camera state asserts a certain condition. This method can be used to confirm that an operation has finished, or if the camera is reporting an error. The condition is a bit mask with the same meanings as described in getState(). For example, calling this method with condition set to 0x30 blocks while an aquisition is either queued or executing. Similarly, it’s possible to block while the camera server is either processing or writing the image with condition set to 0x333308.

This method detects errors automatically by raising an exception if any error bit is set.

See: getState()

Parameters:

condition : int

State condition mask. If any of the condition bits is set, the condition is considered to be true.

timeout : float

Time to wait for the condition to be deasserted

waitWhileOrUntil(condition, timeout=60, until=False)

Helper method that implements waitWhile() and waitUntil()

writeImage(fileName, wait=True)

Write the image stored in MarCCD server memory in a file. This method does not store the resulting image in the local machine. Since current MarCCD server protocol does not allow locally downloading the resulting image, this method only asks for the MarCCD camera server to store the image in a remote location. To make the file accessible locally, other means must be used, for example, by instructing the server to save the image in shared storage.

Parameters:

fileName : string

Target file name in remote MarCCD server

wait : bool

Set to True if the method should block until the image is written to disk