James Parkhurst - 2013-04-17

DXTBX

Sweep

The sweep object provides the high level interface to the dxtbx module. An example using the Sweep class can be found in the attached file.

The sweep object is instantiated using the SweepFactory method and by supplying either a single image filename or a list of filenames. If a list of filenames is provided, the sweep is created using just those images. If a single image filename is provided as a string, other images with similiar filenames are matched and included in the sweep.

>>> from dxtbx.sweep import SweepFactory
>>> sweep = SweepFactory.sweep(filenames)

Accessing experimental models

The sweep object provides access to the experimental models through the use of getter methods as shown below.

>>> beam = sweep.get_beam()
>>> detector = sweep.get_detector()
>>> gonio = sweep.get_goniometer()
>>> scan = sweep.get_scan()

Sweep data

The main motivation of the sweep class is to provide easy access to the image data. A sweep is conceptually similiar to a python list in that it is a list of image frames. In general, we can't read in a whole list of images and store them in a list due to memory constraints.

The sweep covers a set of contiguous image, the range of these images can be accessed as shown below.

>>> print sweep
[0, 1, 2, 3, 4, 5, 6, 7, 8]

>>> print sweep.indices()
[0, 1, 2, 3, 4, 5, 6, 7, 8]

>>> print sweep.get_array_range()
(0, 9)

Sweeps can also be sliced like a python arrays to produce sub-sweeps that can be used to access a sub-set of the images contained in the whole sweep. Each sub-sweep contains a reference to the same SweepReader object as the sweep from which they were derived. 

>>> sub_sweep = sweep[3:6]
>>> print sub_sweep
[3, 4, 5]

>>> print sub_sweep.indices()
[3, 4, 5]

>>> print sub_sweep.get_array_range()
(3, 6)

Accessing sweep image data

The image data contained in the sweep can be accessed simply by iterating through the sweep as you would a normal python list. The sweep class also provides a len method so that the length of the sweep can be queried the same as a python list. The image data is returned as a 2D flex array.

>>> # Iterate throug images in sweep
>>> print len(sweep)
>>> for image in sweep:
      print image

<scitbx_array_family_flex_ext.int object at 0xdcd130>
<scitbx_array_family_flex_ext.int object at 0x19d9f50>
<scitbx_array_family_flex_ext.int object at 0xdcd100>
<scitbx_array_family_flex_ext.int object at 0x19d49d0>
<scitbx_array_family_flex_ext.int object at 0x19d5030>
<scitbx_array_family_flex_ext.int object at 0x19d96a0>
<scitbx_array_family_flex_ext.int object at 0x19d47a0>
<scitbx_array_family_flex_ext.int object at 0x19d79c0>
<scitbx_array_family_flex_ext.int object at 0x19d9da0>

Extracting a 3D volume

The sweep object also provides a method to directly extract a 3D image volume. If the method is called with no arguments, then all the images in the sweep are read and returned as a 3D image volume. This is generally not recommented for large sweeps that cannot be held fully in memory but can be useful for small sub-sweeps.

The second usage of the method is to supply the range of pixels to extract. If the method is called with a two element tuple, the argument is interpreted as (image0, imageN) and a volume containing the images within that range is returned. If the method is called with a six element tuple, the argument is interpreted as (image0, imageN, slow0, slowN, fast0, fastN) and a volume containing that sub-set of the image volume is returned. If a range greater than the range of the image volume is supplied, the range is truncated. 

>>> # Extract a volume from all images in sweep
>>> volume = sweep.to_array()
>>> print volume.all()
(9, 2527, 2463)

>>> # Extract a volume from a sub-set of images
>>> volume = sweep.to_array((2, 7))
>>> print volume.all()
(5, 2527, 2463)

>>> # Do the same as above but using a sub-sweep
>>> volume = sweep[2:7].to_array()
>>> print volume.all()
(5, 2527, 2463)

>>> # Extract a sub-set of the image volume
>>> volume = sweep.to_array((2, 7, 100, 200, 100, 300))
>>> print volume.all()
(5, 100, 200)

Low-level sweep reader interface

The sweep object also provides access to the lower-level sweep reader object used to actually read the sweep data.

The sweep reader provides functionality to cache a certain number of images for fast reading of recently used images. The number of images to cache can be get/set using get/set_max_cache. The images currently in the cache can also be accessed by the cached() member function.

>>> # Get the image cache
>>> print sweep.reader().get_max_cache()
1

>>> # Set the image cache
>>> sweep.reader().set_max_cache(10)

>>> # Get the currently cached images
>>> print sweep.reader().cached()
[0, 1, 2, 3, 4, 5, 6, 7, 8]

The sweep reader also provides access to the format class and template string should they be needed.

>>> # Get the format class
>>> print sweep.reader().get_format()
<class 'dxtbx.format.FormatCBFMiniPilatus.FormatCBFMiniPilatus'>

>>> # Get the template string
>>> print sweep.reader().get_template()
/home/upc86896/Projects/cctbx/sources/dials_regression/centroid_test_data/centroid_####.cbf
 

Last edit: James Parkhurst 2013-04-17