Reference

class bluesky_darkframes.DarkFramePreprocessor(*, dark_plan, detector, max_age, locked_signals=None, limit=None, stream_name='dark')

A plan preprocessor that ensures each Run records a dark frame.

Specifically this adds a new Event stream, named ‘dark’ by default. It inserts one Event with a reading that contains a ‘dark’ frame. The same reading may be used across multiple runs, depending on the rules for when a dark frame is taken.

Parameters:

dark_plan: callable

Expected siganture: dark_plan(detector) -> snapshot_device

The old signature dark_plan() -> snapshot_device is accepted but will issue a warning.

detector: Device

max_age: float

Time after which a fresh dark frame should be acquired

locked_signals: Iterable, optional

Any changes to these signals invalidate the current dark frame and prompt us to take a new one. Typical examples would be exposure time or gain, anything that changes the expected dark frame.

limit: integer or None, optional

Number of dark frames to cache. If None, do not limit.

stream_name: string, optional

Event stream name for dark frames. Default is ‘dark’.

__call__(plan)

Preprocessor: Takes in a plan and creates a modified plan.

This inserts messages to add extra readings to the plan. First, it decides whether it needs to trigger the detector to get a fresh reading or whether it can use a cached reading.

add_snapshot(snapshot, state=None)

Add a darkframe.

Parameters:

snapshot: SnapshotDevice

state: dict, optional

Mapping each of the names of the locked_signals (if any) to its value when the snapshot was taken. When snapshots are accessed via get_snapshot(state), the states will be compared via ==.

property cache

A read-only view of the cached dark frames.

Each key is a frozendict mapping each of the names of the locked_signals (if any) to its value at the time the dark frame was taken.

Each value has the structure (creation_time, snapshot) where creation_time is the UNIX epoch time that the dark frame was taken and snapshot is a SnapshotDevice instance.

The cache is ordered. When an item is accessed, it is moved to the front. If limit is set, items will be removed from the end as needed to abide by the limit.

Whenver the cache is updated or accessed, any items whose creation_time is more than max_age seconds ago are culled.

clear()

Clear all cached darkframes.

disable()

Make this preprocessor a no-op.

See also

DarkFramePreprocessor.enable()

enable()

Counterpart to diasble().

See also

DarkFramePreprocessor.disable()

get_snapshot(state)

Access a darkframe.

Parameters:

state: dict

Mapping each of the names of the locked_signals (if any) to its value.

class bluesky_darkframes.DarkSubtraction(field, light_stream_name='primary', dark_stream_name='dark', pedestal=100)

Document router to do in-place background subtraction.

Expects that the events are filled.

The values in (light_stream_name, field) are replaced with

np.clip(light - np.clip(dark - pedestal, 0), 0)

Adds the key f’{self.field}_is_background_subtracted’ to the ‘light_stream_name’ stream and a configuration key for the pedestal value.

Parameters:

fieldstr

The name of the field to do the background subtraction on.

This field must contain the light-field values in the ‘light-stream’ and the background images in the ‘dark-stream’

light_stream_namestr, optional

The stream that contains the exposed images that need to be background subtracted.

defaults to ‘primary’

dark_stream_namestr, optional

The stream that contains the background dark images.

defaults to ‘dark’

pedestalint, optional

Pedestal to add to the data to make sure subtracted result does not fall below 0.

This is actually pre subtracted from the dark frame for efficiency.

Defaults to 100.

class bluesky_darkframes.SnapshotDevice(device)

A mock Device that stashes a snapshot of another Device for later reading

Parameters:

device: Device

This object from the suitcase.tiff_series library is used in the usage example:

class suitcase.tiff_series.Serializer(directory, file_prefix='{start[uid]}-', astype='uint16', bigtiff=False, byteorder=None, imagej=False, *, event_num_pad=5, **kwargs)

Serialize a stream of documents to a series of TIFF files.

This creates a file named: <directory>/<file_prefix>{stream_name}-{field}-{image_number}.tiff for every Event stream and field that contains 2D ‘image-like’ data.

Warning

This process explicitly ignores all data that is not 2D and does not include any metadata in the output file.

Note

This can alternatively be used to write data to generic buffers rather than creating files on disk. See the documentation for the directory parameter below.

Parameters:

directorystring, Path or Manager.

For basic uses, this should be the path to the output directory given as a string or Path object. Use an empty string '' to place files in the current working directory.

In advanced applications, this may direct the serialized output to a memory buffer, network socket, or other writable buffer. It should be an instance of suitcase.utils.MemoryBufferManager and suitcase.utils.MultiFileManager or any object implementing that interface. See the suitcase documentation (http://nsls-ii.github.io/suitcase) for details.

file_prefixstr, optional

The first part of the filename of the generated output files. This string may include templates as in {start[proposal_id]}-{start[sample_name]}-, which are populated from the RunStart (start), EventDescriptor (descriptor) or Event (event) documents. The default value is {start[uid]}- which is guaranteed to be present and unique. A more descriptive value depends on the application and is therefore left to the user. Two additional template parameters {stream_name} and {field} are supported. These will be replaced with stream name and detector name, respectively.

astypenumpy dtype

The image array is converted to this type before being passed to tifffile. The default is 16-bit integer ('uint16') since many image viewers cannot open higher bit depths. This parameter may be given as a numpy dtype object (numpy.uint32) or the equivalent string ('uint32').

bigtiffboolean, optional

Passed into tifffile.TiffWriter. Default False.

byteorderstring or None, optional

Passed into tifffile.TiffWriter. Default None.

imagej: boolean, optional

Passed into tifffile.TiffWriter. Default False.

event_num_padint, optional

The number of 0s to left-pad the event number to in the filename.

**kwargskwargs

kwargs to be passed to tifffile.TiffWriter.write.