areaDetector Plugin NDPosPlugin

NDPosPlugin can be used to attach positional information to NDArrays in the form of NDAttributes. This plugin accepts an XML description of the position data and then attaches each position to NDArrays as they are passed through the plugin. Each position can contain a set of index values and each index is attached as a separate NDAttribute. The plugin operates using a FIFO and new positions can be added to the queue while the plugin is actively attaching position data. When used in conjunction with the HDF5 writer (NDFileHDF5) it is possible to store NDArrays in an arbitrary pattern within a multi-dimensional dataset.

The NDPosPlugin plugin is created with the NDPosPluginConfigure command, either from C/C++ or from the EPICS IOC shell.

NDPosPluginConfigure (const char *portName, int queueSize, int blockingCallbacks, 
                     const char *NDArrayPort, int NDArrayAddr, size_t maxMemory, 
                     int priority, int stackSize)
  

For details on the meaning of the parameters to this function refer to the detailed documentation on the NDPosPluginConfigure function in the NDPosPlugin.cpp documentation and in the documentation for the constructor for the NDPosPlugin class.

XML Defined Positions

The position data is supplied to the plugin as an XML description. The parameter NDPos_Filename can either accept the full path to an XML file with the position data description, or the XML can be injected directly into the parameter. There is a 1,000,000 byte limit on the parameter, but multiple injections can take place in sequence with each set of points appended to the FIFO.

The XML definition contains the following 4 main elements: dimensions, dimension, positions, and position.

• dimensions: Contains the dimension elements that provide the dimension name definitions
• dimension: The name of a dimension. This name is used for the NDAttribute name that is attached to the NDArray with position information.
• positions: Contains the position elements.
• position: Represent a single position to be added to the FIFO.

The XML can contain any number of dimension elements (grouped within the dimensions element), and each dimension must contain a single attribute name that names the particular dimension. Once the dimensions have been defined, the position elements are added. The XML can contain any number of position elements (grouped within the positions element). Each position element should have an attribute for each of the named dimensions with the value of the position for that dimension. An example of a simple XML description is presented below:

      
<pos_layout>
    <dimensions>
        <dimension name="x"></dimension>
        <dimension name="y"></dimension>
        <dimension name="z"></dimension>
    </dimensions>
    <positions>
        <position x="0" y="0" z="0"></position>
        <position x="0" y="0" z="1"></position>
        <position x="0" y="1" z="0"></position>
        <position x="0" y="1" z="1"></position>
        <position x="1" y="0" z="0"></position>
        <position x="1" y="0" z="1"></position>
        <position x="1" y="1" z="0"></position>
        <position x="1" y="1" z="1"></position>
    </positions>
</pos_layout>

In the example above, three dimensions have been defined (x, y and z). The positions are then defined with value for each dimension provided. This XML description will result in three NDAttriubtes being attached to each NDArray, with the names x, y and z respectively. The value of each of the NDAttributes will be set according to the position that is currently at the front of the FIFO.

A complete example XML layout file is provided in "ADCore/iocBoot/pos_plugin_demo.xml".

An XML schema is provided in "ADCore/iocBoot/pos_plugin_schema.xsd". The schema defines the syntax that is allowed in the user's XML definition. It can also be used with the 'xmllint' command to validate a user's XML definition:

xmllint --noout --schema ADCore/iocBoot/pos_plugin_schema.xsd /path/to/users/layout.xml

Using the plugin

The plugin offers two modes of operation: Discard and Keep. When executed in discard mode the plugin will throw away a position every time it is attached to an NDArray, and the FIFO will continue to decrease in size until it reaches zero. When executed in Keep mode the positions will still be sent in order but they will not be discarded. A parameter can be used to reset the current position to the start and then the same set can be reused. The position attachment can be started and stopped, and the FIFO can be cleared. A record of the number of positions in the FIFO, the current index and a string representation of the last position sent are provided through the parameter interface.

Frame Identification tracking

The plugin tracks frame information to ensure that the incoming frames are in the correct order and there are no missing or duplicated frames. This is achieved using three parameters, IDName, IDStart and IDDifference. The IDName tells the plugin which incoming attribute to use as the ID to track, or if it is left empty then the uniqueId member variable of the NDArray is used. The IDStart value informs this plugin of the first expected ID when the acquisition is started, and the IDDifference informs this plugin of the expected delta ID between each frame. An IDStart of 5 and IDDifference of 10 would result in the plugin expecting the following sequence of ID values attached to the incoming frames: 5,15,25,35... If incoming frames contain IDs that are greater than the expected ID then the plugin will print a warning and throw away any position information up until the expected ID matches the frame ID; this is a case where the frames are assumed to have been dropped. If incoming frames contain IDs that are less than the exptected ID then the plugin will print an error and drop the frames until the incoming frame ID matches the expected ID. This is a more serious case of the plugin dropping frames and this is why the error is printed. In both of these error situations the plugin will record the event into the corresponding counter and continue to process frames.

Parameters and Records