ALBULA  4.0.1
dectris.albula.DImageSeries Class Reference

class DImageSeries provides access to image series, which may reside in a series of single image files or in one hdf5 container file. More...

Public Member Functions

def DImageSeries (listsize=0)
 Access to list of images that contains at most listsize (infinite) images if listsize > 0 (listsize == 0). More...
 
def DImageSeries (fileName)
 Construct readonly DImageSeries from hdf5 file or arbitrary file of a set of image files following the name pattern /path/to/image<Number>.suffix. More...
 
def open (listsize=0)
 Access to list of images that contains at most listsize (infinite) images if listsize > 0 (listsize == 0). More...
 
def open (fileName)
 Access to an image series of single image files or one container file (hdf5). More...
 
def blocking ()
 Returns True if blocking mode is on else false. More...
 
def setBlocking (blocking, timeout=0)
 Set blocking mode when trying to access resources of the series that are still absent (e.g. a missing image file). More...
 
def front ()
 front element on the DImage series It is guaranteed that for the returned image optionalData().pixel_mask() is set. More...
 
def popFront ()
 Removes first image of the list. More...
 
def pushBack (img)
 If accommodating a list of of DImage objects, add image at the end of the list. More...
 
def size ()
 number of images the series contains. More...
 
def first ()
 index of the first image More...
 
def last ()
 index of the last image More...
 
def at (index)
 Identical to DImageSeries[n]. More...
 
def neXus ()
 If the underlying data is a Hdf5 container return its NeXus tree, else raise DRuntimeException. More...
 
def empty ()
 Indicates if front() is valid. More...
 
def update ()
 Scan the resource (e.g. the hdf5 file) for new images. More...
 
def pathToImage (index)
 Throws DRuntimeException if operation does not make sense (e.g. on a image list). More...
 

Detailed Description

class DImageSeries provides access to image series, which may reside in a series of single image files or in one hdf5 container file.

In addition DImageSeries may accomodate a list of separated DImage objects. A series of single image files is accessed by passing the path to any of the files as fileName argument to the constructor or to open(). All images belonging to the same series are assumed to follow the name pattern /path/to/image<Number>.<suffix>, where <Number> runs from a minimum to a maximum value. <suffix> identifies the file format. Currently cbf, tif and edf files taken by Pilatus detectors are supported. Hdf5 files are opend by passing their paths as fileName argument to the constructor or to open(). DImageSeries objects accomodating a series of files or a hdf5 file are read only. I.e. pushBack() throws a DRuntimeException. If an integer size is passed as listsize argument to the constructor or to open(), DImageSeries behaves like a list of DImage objects, which may be pushed at one end via pushBack() and popped from the other end via popFront(). Random access is still possible via at() or the [] operator.

class DImageSeries provides the following operations:

DImageSeries[ index ]
\brief Random access to the DImages
\anchor DImageSeries_operator_at
If n is not a valid index the method may either block (if blocking())
or a DOutOfRangeException is thrown. If blocking and operation timed out
a DTimeoutException is thrown.
It is guaranteed that in the returned image optionalData().pixel_mask() is set.
\param n Index of the image to load. The index of the series does not
         neccessarily start from 0. Query the first index via first().
\return DImage

Constructor & Destructor Documentation

◆ DImageSeries() [1/2]

def dectris.albula.DImageSeries.DImageSeries (   listsize = 0)

Access to list of images that contains at most listsize (infinite) images if listsize > 0 (listsize == 0).

Parameters
listsizemaximum number of images the list can contain. If listsize == 0 the list can contain an infinite number of images.

◆ DImageSeries() [2/2]

def dectris.albula.DImageSeries.DImageSeries (   fileName)

Construct readonly DImageSeries from hdf5 file or arbitrary file of a set of image files following the name pattern /path/to/image<Number>.suffix.

Member Function Documentation

◆ at()

def dectris.albula.DImageSeries.at (   index)

Identical to DImageSeries[n].

◆ blocking()

def dectris.albula.DImageSeries.blocking ( )

Returns True if blocking mode is on else false.

See setBlocking().

Returns
True or False

◆ empty()

def dectris.albula.DImageSeries.empty ( )

Indicates if front() is valid.

Returns
True or False

◆ first()

def dectris.albula.DImageSeries.first ( )

index of the first image

◆ front()

def dectris.albula.DImageSeries.front ( )

front element on the DImage series It is guaranteed that for the returned image optionalData().pixel_mask() is set.

Returns
front image

◆ last()

def dectris.albula.DImageSeries.last ( )

index of the last image

◆ neXus()

def dectris.albula.DImageSeries.neXus ( )

If the underlying data is a Hdf5 container return its NeXus tree, else raise DRuntimeException.

Returns
DNeXusTree of Hdf5 container.

◆ open() [1/2]

def dectris.albula.DImageSeries.open (   fileName)

Access to an image series of single image files or one container file (hdf5).

fileName may be an hdf5 file or arbitrary file of a set of image files following the name pattern /path/to/image<Number>.suffix. Returns the index by which the data is accessed (i.e. <Number>). E.g.\

i = container.open("/path/to/img_00005.cbf")
# i == 5
img = container[i]
Parameters
fileNameString. Path to the image file
Returns
Index by which the data is accessed

◆ open() [2/2]

def dectris.albula.DImageSeries.open (   listsize = 0)

Access to list of images that contains at most listsize (infinite) images if listsize > 0 (listsize == 0).

Parameters
listsizemaximum number of images the list can contain. If listsize == 0 the list can contain an infinite number of images.

◆ pathToImage()

def dectris.albula.DImageSeries.pathToImage (   index)

Throws DRuntimeException if operation does not make sense (e.g. on a image list).

Else returns the path to the image file index points to.

Parameters
indexInteger
Returns
String

◆ popFront()

def dectris.albula.DImageSeries.popFront ( )

Removes first image of the list.

◆ pushBack()

def dectris.albula.DImageSeries.pushBack (   img)

If accommodating a list of of DImage objects, add image at the end of the list.

Else throws DRuntimeException.

Parameters
imgDImage

◆ setBlocking()

def dectris.albula.DImageSeries.setBlocking (   blocking,
  timeout = 0 
)

Set blocking mode when trying to access resources of the series that are still absent (e.g. a missing image file).

Caveat: There is no way to figure out when writing to a file ALBULA is waiting for is finished. Hence write image first to a temporary file and rename it atomically to fileName. (rename, mv are atomic operations on unix systems)

Parameters
blockingTrue or False, e.g. block if image file trying to get access to is absent or return immediately.
timeouttimeout in milliseconds ( timeout == 0: return immediately, timeout < 0: wait forever )

◆ size()

def dectris.albula.DImageSeries.size ( )

number of images the series contains.

Returns
size

◆ update()

def dectris.albula.DImageSeries.update ( )

Scan the resource (e.g. the hdf5 file) for new images.