Python TANGO server

This is the python Tango devices server by the ESRF team.

This server provides a main device for the standard camera control, a camera specific device for the camera configuration and a set of “plugin” devices for extra operations or just to export some subset of interface.

Thanks to the Lima framework, the control can be achieved through a common device as well as some features like calculations. The configuration of the detector is done by the specific detector device. At ESRF we decided to develop the Tango devices only in python language which implies that all the detector C++ interfaces have been wrapped to python modules.

Main device: LimaCCDs

LimaCCDs is the generic device and it provides a unique interface to control any of the supported cameras. One can find below the commands, the attributes and the proporties.

To run a LimaCCDs server you will need at least to configure the LimaCameraType property. This property will tell to the LimaCCDs server which camera you want to run, then it will try to create the corresponding camera device (see the camera device chapter below for detailed list).

Property

Property name Mandatory Default value Description
LimaCameraType Yes N/A The camera type: e.g. Maxipix
NbProcessingThread No 1 The max number of thread for processing. Can be used to improve the performance when more than 1 task (plugin device) is activated
AccThresholdCallbackModule No “” Plugin file name which manages threshold
ConfigurationFilePath No ~/lima_<serv-name>.cfg The default configuration file path
ConfigurationDefaultName No “default” Your default configuration name

Commands

Command name Arg. in Arg. out Description
Init DevVoid DevVoid Do not use
State DevVoid DevLong Return the device state
Status DevVoid DevString Return the device state as a string
getAttrStringValueList DevString: Attribute name DevVarStringArray: String value list Return the authorized string value list for a given attribute name
prepareAcq DevVoid DevVoid Prepare the camera for a new acquisition, has to be called each time a parameter is set.
startAcq DevVoid DevVoid Start the acquisition
stopAcq DevVoid DevVoid Stop the acquisition
setImageHeader DevVarStringArray: Array of string header DevVoid
Set the image header:
  • [0]=”ImageId0 delimiter imageHeader0,
  • [1] = ImageId1 delimiter imageHeader1..
getImage DevLong: Image number(0-N) DevVarCharArray: Image data Return the image data in raw format (char array)
getBaseImage DevLong: Image number(0-N) DevVarCharArray: Image data Return the base image data in raw format (char array). Base image is the raw image before processing
readImage DevLong: Image number(0-N) DevEncoded: Encoded image Return the image in encoded format of type “DATA_ARRAY” (see DevEncoded DATA_ARRAY)
writeImage DevLong: Image number(0-N) DevVoid Save manually an image
readAccSaturatedImageCounter DevLong: Image number(0-N) DevVarUShortArray: Image counter The image counter
readAccSaturatedImageCounter DevLong: Image number DevVarUShortArray: Image counter The image counter
readAccSaturatedSumCounter DevLong: from image id DevVarLongArray: result number of result for each images,sum counter of raw image #0 of image #0,sum counter of raw image #1 of image #0,...
setAccSaturatedMask DevString DevVoid Full path of mask file, use empty string (“”) to unset the mask
closeShutterManual DevVoid DevVoid Only if the camera has this capability
openShutterManual DevVoid DevVoid Only if the camera has this capability
reset DevVoid DevVoid Reset the camera to factory setting
getPluginNameFromType DevString DevString Return the device name corresponding to the passed plugin named (.e.g FlatField)
configStore DevVarStringArray:config name,module1, module2, ... , modulen DevVoid Store (im memory) a current config with name and for the listed modules (e.g. Acquisition, Image, RoiCounters, Saving ...). See the config_available_name and config_available_module attributes for full list.
configApply DevString: config name DevVoid Apply the named config
configPop DevVoid DevVoid Pop the named config from the list
configDelete DevVoid DevVoid Delete the named config
configFileSave DevVoid DevVoid Save all the config into file (see properties for config file name)
configFileLoad DevVoid DevVoid Load the configs from file

Attributes

You will here a long list of attributes, this reflects the richness of the LIMA library. We organized them in modules which correspond to specific functions. A function module is identified by an attribute name prefix (excepted for informationnal attributes), for instance the Acquisition module attributes are always named acq_<attr-name>. The available modules are :

  • General Information
  • Status (prefix last_ and ready_)
  • Acquisition (prefix acq_ for most of them sorry)
  • Accumulation (prefix acc_)
  • Saving (prefix saving_)
  • Image (prefix image_)
  • Shutter (prefix shutter_)
  • Debug (prefix debug_)
  • Video (prefix video_)
  • Shared Memory (prefix shared_memory_)
  • Configuration (prefix config_)

Many attributes are of type DevString and they have a fixed list of possible values. you can get the list by calling the special command getAttrStringValueList. Because a camera cannot support some attribute values , the command getAttrStringValueList will give you the the value list for the camera. For instance the attribute video_mode supports up to 14 different video formats, but a camera can only supports few of them.

Attribute name RW Type Description
GENERAL INFORMATION
lima_type ro DevString LImA camera type: Maxipix,Pilatus,Frelon,Pco, Basler ...
camera_type ro DevString like lima_type but in upper-case !!
camera_pixelsize ro DevDouble[x,y] The camera pixel size in x and y dimension
camera_model ro DevString Camera model return by the detector layer:.e.g. 5x1- TPX1
plugin_type_list rw    
write_statistic ro DevDouble[] Performance writing time for last images in second.
STATUS
last_base_image_ready ro DevLong The last base (before treatment) ready
last_image_ready ro DevLong The last acquired image number, ready for reading
last_image_saved ro DevLong The last saved image number
last_image_acquired ro DevLong The last acquired image number
last_counter_ready ro DevLong Tell which image counter is last ready
ready_for_next_image ro DevBoolean True after a camera readout, otherwise false. Can be used for fast synchronisation with trigger mode (internal or external).
ready_for_next_acq ro DevBoolean True after end of acquisition, otherwise false.
ACQUISITION
acq_status ro DevString Acquisition status: Ready, Running, Fault or Configuration
acq_mode rw DevString
Acquisition mode:
  • Single, default mode one frame per image
  • Concatenation, frames are concatenated in image
  • Accumulation, powerful mode to avoid saturation of the pixel, the exposure is shared by multiple frames, see acc_ attributes for more
acq_nb_frames rw DevLong Number of frames to be acquired, Default is 1 frame
acq_trigger_mode rw DevString
Trigger mode:
  • Internal_trigger, the software trigger, start the acquisition immediately after an acqStart() call, all the acq_nb_frames are acquired in an sequence.
  • External_trigger, wait for an external trigger signal to start the an acquisition for the acq_nb_frames number of frames.
  • External_trigger_multi, as the previous mode except that each frames need a new trigger input (e.g. for 4 frames 4 pulses are waiting for)
  • Internal_trigger_multi, as for internal_trigger except that for each frame the acqStart() has to called once.
  • External_gate, wait for a gate signal for each frame, the gate period is the exposure time.
  • External_start_stop
latency_time rw DevDouble Latency time in second between two frame acquisitions, can not be zero, the minimum time corresponds to the readout time of the detector.
valid_ranges ro DevDouble[4] min exposure, max exposure, min latency, max latency
concat_nb_frames rw DevLong The nb of frames to concatenate in one image
acq_expo_time rw DevDouble The exposure time of the image, Default is 1 second
ACCUMULATION
acc_expotime ro DevDouble The effective accumulation total exposure time.
acc_nb_frames ro DevLong The calculated accumulation number of frames per image.
acc_max_expotime rw DevDouble The maximum exposure time per frame for accumulation
acc_time_mode rw DevString
Accumulation time mode:
  • Live,acq_expo_time = acc_live_time
  • Real,acq_expo_time = acc_dead_time + acc_live_time
acc_dead_time ro DevDouble Total accumulation dead time
acc_live_time ro DevDouble Total accumulation live time which corresponds to the detector total counting time.
acc_saturated_active rw DevBoolean To activate the saturation counters (i.e. readAccSaturated commands)
acc_saturated_threshold rw DevLong To fix the threshold for saturation counting
acc_saturated_cblevel rw DevLong Set at which level in the process task chain this task will be called (default is 0,ie before other calculation task(mask,bg,flatfield ...)
SAVING
saving_mode rw DevString
Saving mode:
  • Manual, no automatic saving, a command will be implemented in a next release to be able to save an acquired image.
  • Auto_Frame, Frames are automatically saved according the saving parameters (see below).
  • Auto_header, Frames are only saved when the setImageHeader() is called in order to set header information with image data.
saving_directory rw DevString The directory where to save the image files
saving_prefix rw DevString The image file prefix
saving_suffix rw DevString The image file suffix
saving_next_number rw DevLong

The image next number The full image file name is:

  • /saving_directory/saving_prefix+sprintf(“%04d”,saving_next_number)+saving_suffix
saving_format rw DevString
The data format for saving:
  • Raw, save in binary format
  • Edf, save in ESRF Data Format
  • edfgz (or edf.gz), EDF with gz compression
  • Tiff, The famous TIFF format
  • Cbf, save in CBF format (a compressed format for crystallography)
saving_overwrite_policy rw DevString
In case of existing files an overwite policy is mandatory:
  • Abort, if the file exists the saving is aborted
  • Overwrite, if the file exists it is overwritten
  • Append, if the file exists the image is append to the file
saving_frame_per_file rw DevLong Number of frames saved in each file
saving_common_header rw DevString[] Common header with multiple entries
saving_header_delimiter rw DevString[] The header delimiters, [0] = key header delimiter, [1] = entry header delimiter, [2] = image number header delimiter. Default : [0] = “=”, [1] = “n”, [2] = ”;”
IMAGE
image_type ro DevString
Return the current image data type, bit per pixel signed or unsigned:
  • Bpp8, Bpp8S, Bpp10, Bpp10S, Bpp12, Bpp12S, Bpp14,
  • Bpp14S, Bpp16, Bpp16S, Bpp32, Bpp32S , Bpp32F.
image_width ro DevLong Width size of the detector in pixel
image_height ro DevLong Height size of the detector in pixel
image_sizes ro DevULong[4] Signed(0-unsigned,1-signed), depth(nb bytes), width and height
image_roi rw DevLong[4] Region Of Interest on image, [0] = Begin X, [1] = End X, [2] Begin Y, [3] = End Y, default ROI is [0,0,0,0] (no ROI)
image_bin rw DevLong[2] Binning on image, [0] = Binning factor on X, [1] = Binning factor on Y. Default binning is 1 x 1
image_flip rw DevBoolean[2] Flip on the image, [0] = flip over X axis, [1] flip over Y axis. Default flip is False x False
image_rotation rw DevString Rotate the image: “0”, “90”, “180” or “270”
SHUTTER
shutter_mode rw DevString

Using the external shutter output to synchronize a shutter with the acquisition several modes are available:

  • Manual
  • Auto_frame, the output signal is activated for each individual frame of a sequence
  • Auto_sequence, the output signal is activated during the whole sequence
shutter_open_time rw DevDouble Delay (sec.) between the output shutter trigger and the beginning of the acquisition, if not null the shutter signal is set on before the acquisition is started.
shutter_close_time rw DevDouble Delay (sec.) between the shutter trigger and the end of the acquisition, if not null the shutter signal is set on before the end of the acquisition.
shutter_manual_state rw DevString To open/close manually the shutter (if Manual mode is supported, see shutter_mode)
DEBUG
debug_module_possible ro DevString[] Return the list of possible debug modules
debug_modules rw DevString[]
Set the debug module level of LImA:
  • “None”
  • “Common”
  • “Hardware”
  • “HardwareSerial”
  • “Control”
  • “Espia”
  • “EspiaSerial”
  • “Focla”
  • “Camera”
  • “CameraCom”
  • “Test”
  • “Application”
debug_types_possible ro DevString[] Return the list of the possible debug types
debug_types rw DevString[]
Set the debug type level of LImA:
  • “Fatal”
  • “Error”
  • “Warning”
  • “Trace”
  • “Funct”
  • “Param”
  • “Return”
  • “Always”
VIDEO
video_active rw DevBoolean Start the video mode (or not)
video_live rw DevBoolean Start the video streaming (or not)
video_exposure rw DevDouble The video exposure time (can be different to the acq_expo_time)
video_gain rw DevDouble The video gain (if supported by the hardware)
video_mode rw DevString
The video mode is the video format supported by the camera, it can be:
  • Y8, grey image 8bits
  • Y16, grey image 16bits
  • Y32, grey image 32bits
  • RGB555, color image RGB 555 encoding
  • RGB564, color image RGB 555 encoding
  • RGB24, color image RGB 24bits encoding
  • RGB32, color image RGB 32bits encoding
  • BGR24, color image BGR 24bits encoding
  • BGR32, color image BGR 32bits encoding
  • BAYER_RG8, color image BAYER RG 8bits encoding
  • BAYER_RG16, color image BAYER RG 16bits encoding
  • I420, color image I420 (or YUV420) planar encoding
  • YUV411, color image YUV411 planar encoding
  • YUV422, color image YUV422 planar encoding
  • YUV444, color image YUV444 planar encoding

Depending of your camera, the supported formats can be retrieve using the command getAttrStringValueList

video_roi rw DevLong[4] A ROI on the video image (independent of the image_roi attribute)
video_bin rw DevULong[2] A Binning on the video image (independt of the image_bin attribute)
video_last_image rw DevEncoded The last video image, in DevEncoded “VIDEO_IMAGE” format, and using the video_mode set, see the DevEncoded definition DevEncoded VIDEO_IMAGE
video_last_image_counter rw DevLong64 The image counter
SHARED MEMORY
shared_memory_names rw DevString[2] Firstname and surname of the SPS typed shared memory (default is LimaCCDs,<camera_type>)
shared_memory_active rw   Activate or not the shared memory. The shared memory is for image display
CONFIG
config_available_module ro DevString[] List of possible config modules,
config_available_name ro DevString[] List of existing config names

DevEncoded DATA_ARRAY

The DATA_ARRAY DevEncoded has been invented for special Tango client like SPEC. It is used by the readImage command. It can only embed raw data (no video data). The supported image format can be retrieve with the image_type attribute (Bpp8,Bpp8S, ..., Bpp16,..) This encoded format is very generic and it supports many different type of data from scalar to image stack (see DataArrayCategory enumerate C-type). The readImage command only supports Image data array category.

The DATA_ARRAY format is composed of a fixed header followed by the raw data. The header is a C-like structure, with little-endian byte order and no alignment:

# The DATA_ARRAY definition
struct {
    unsigned int       magic= 0x44544159; // magic key
    unsigned short     version;           // version, only 1 supported
    unsigned  short    header_size;       // size of the header
    DataArrayCategory  category;          // data array category, see DataArrayCategory enumerate
    DataArrayType      data_type;         // data type, see DataArrayType enumerate
    unsigned short     endianness;        // 0-little-endian, 1-big-endian
    unsigned short     nb_dim;            // number of dimension (0 to 7 max)e.g 2 for image
    unsigned short     dim[8];            // size for each dimension, e.g [width,height]
    unsigned int       dim_step[8];       // step size in pixel for each dimension, e.g [1,height]
} DATA_ARRAY_STRUCT;

enum DataArrayCategory {
    ScalarStack = 0;
    Spectrum;
    Image;
    SpectrumStack;
    ImageStack;
};

enum DataArrayType{
    DARRAY_UINT8 = 0;
    DARRAY_UINT16;
    DARRAY_UINT32;
    DARRAY_UINT64;
    DARRAY_INT8;
    DARRAY_INT16;
    DARRAY_INT32;
    DARRAY_INT64;
    DARRAY_FLOAT32;
    DARRAY_FLOAT64;
};

DevEncoded VIDEO_IMAGE

The VIDEO_IMAGE DevEncoded has been implemented for the video_last_image attribute to return the last image. It can embed any of the supported video format depending of the video_mode attribute value.

The VIDEO_IMAGE format is composed of a fixed header followed by the data. The header is a C-like structure, with big-endian byte order and no alignment:

struct {
    unsigned int     magic_number = 0x5644454f;
    unsigned short   version;        // only version 1 is supported
    unsigned short   image_mode;     // Y8,Y16,....
    long     long    frame_number;   // the frame number (counter)
    int              width;          // the frame width in pixel (horizontal size)
    int              height          // the frame height in pixel (vertical size)
    unsigned short   endianness;     // 0-little-endian, 1-big-endian
    unsigned short   header_size;    // this header size in byte
    unsigned short   padding[2];     // 4 bytes of padding (for alignment)
} VIDEO_IMAGE_STRUCT;

Camera devices

Each camera has a configuration device with its own property/attribute/command lists. The camera configuration device is supposed to give you access to the “private” parameters of the detector that LIMA does not need but you may want to set. For instance some detectors provides a temperature control with set-points and/or start/stop commands for a auxillary cooling system.

For more details about the camera device interface, please have a look on the following sections:

Plugin devices: software operation and extra interfaces

User-defined software plugins can be used to execute arbitrary image-based operations. An entry point in the control layer completely exports the ProcessLib functionality, allowing an external code to be called on every frame. The software operation can be implemented in C++ or Python.

The software operations on image are embedded into individual Tango devices and are available in the plugins/ directory. They are automatically exported by the LimaCCDs server.

The software operations are of two types, Sink or Link :
  • Link operation is supposed to modify the frame data, so it gets the frame data as input parameter and it will return a “corrected” image (e.g. Mask/Flatfield/BackgroundSubstraction).
  • Sink operation is taken the frame data as input parameter to apply some software operation in order to return new data like statistics, peak positions, alarm on saturation ... etc.

In addition to sink/link plugin device, a plugin can just be implemented to provide/export a subset of the Lima interface or a legacy interface for some specific client applications (e.g SPEC, LimaTacoCCD plugin).

Today there are about 8 standard plugin devices:

  • BackgroundSubstraction : link operation, to correct the frames with a background image (substraction)
  • FlatField: link operation to correct the frames with a flatfield image (divide + option normalisation)
  • Mask: link operation to mask pixels. Very useful if some pixel are not working properly and if you want to set then to a fix value or to zero.
  • PeakFinder: thanks to Teresa Numez from DESY, a sink operation which can detect diffraction peaks.
  • Roi2Spectrum: sink operation to apply ROI spectrum on the frames. You can define more than one spectra with ROI coordinates and by specifying in which direction you need to bin the values, vertical or horizontal.
  • RoiCounter: sink operation to get calculating statistics on image regions.
  • LimaTacoCCD: extra interface for TACO clients, it only provides commands (TACO does not have attribute !), it is still used at ESRF for SPEC.
  • LiveViewer: extra interface to provide a live view of the last acquired image, can be used from atkpanel.

If you need to implement your own plugin device we can provide you some example codes, use the mailing-list lima@esrf.fr to get help.