This page was created by the IDL library routine
mk_html_help. For more information on
this routine, refer to the IDL Online Help Navigator
or type:
? mk_html_help
at the IDL command line prompt.
Last modified: Mon Oct 30 12:26:32 2006.
NAME:
display_mda
PURPOSE:
This procedure:
- Creates an EPICS_SSCAN object
- Reads an EPICS MDA scan file with epics_sscan::read_mda
- Displays the data in the file with epics_sscan::display
- Optionally returns an object reference to the EPICS_SSCAN object
CATEGORY:
EPICS scanning tools.
CALLING SEQUENCE:
display_mda, Filename, Scan
INPUTS:
Filename: The name of the MDA file to read.
KEYWORDS:
Passes all keywords to the epics_sscan::display procedure,
and/or to the iPlot or iImage tool via _EXTRA.
OPTIONAL OUTPUTS:
Scan
An object reference to the EPICS_SSCAN object.
PROCEDURE:
This is a very simple procedure. It simply does the following:
Scan = obj_new('epics_sscan')
Scan->read_mda, file
Scan->display, _extra=extra
RESTRICTIONS:
While this procedure is easy to use, users need to be aware that
calling it repeatedly without destroying the returned
objects will lead to memory leaks. This may be acceptable for
interactive use, but software written to use the EPICS_SSCAN class
should create objects sparingly and use the epics_sscan::read_mda
and epics_sscan::display methods directly, rather than calling
this procedure.
EXAMPLE:
IDL> display_mda, s, '2idd_0087.mda', detector=[4,5,6,7], /grid
IDL> s->print, /all
MODIFICATION HISTORY:
Written by: Mark Rivers, Nov. 8, 2003
(See display_mda.pro)
NAME:
epics_sscan::display
PURPOSE:
This procedure displays scan data using the IDL iTools.
If the resulting data (after application of any keywords) is 1-D, then
an iPlot tool is created or modified.
If the resulting data is 2-d then an iImage tool is created. This
display can be interactively modified to display contours and/or
surfaces.
CATEGORY:
EPICS scanning tools.
CALLING SEQUENCE:
scan->display
KEYWORD PARAMETERS:
SCAN:
The scan to display.
Default is the innermost scan in this scan object.
Passed to epics_sscan::getData().
POSITIONER:
The number of the positioner to display.
Passed to epics_sscan::getData().
DETECTOR:
The number of the detector(s) to display.
Passed to epics_sscan::getData().
ALL:
Set this flag to display all of the detectors for this
scan. Passed to epics_sscan::getData()
[X,Y,Z]RANGE:
Used this keyword to restrict the range of array elements display in
the X, Y, or Z dimensions. Passed to epics_sscan::getData()
[X,Y,Z]TOTAL:
Set this flag to sum over the array elements in the X, Y, or Z
dimensions. Passed to epics_sscan::getData()
GRID:
Set this flag to display multiple detectors in separate dataspaces
within this iTool, layed out in a grid format.
If this keyword is not specified, and there are multiple detectors
selected then the iTool /OVERPLOT keyword is used. For 1-D data this
results in multiple traces on the same plot, which each done in a
different color and plot symbol. For 2-D data the images are plotted
on top of one another. To browse through the images use the right mouse
button in the image or Visualization Browser to change this display
order (Send to Back, etc.).
IMAGE:
Set this flag to display 2-D data with iImage. This is the default.
SURFACE:
Set this flag to display 2-D data with iSurface.
CONTOUR:
Set this flag to display 2-D data with iContour.
Other:
Any unrecognized keywords will be passed to the iPlot or iImage
procedures via the _EXTRA mechanism. This allows one to specify,
for example, /VIEW_NEXT, to put the display in an existing iTool
rather than creating a new one.
RESTRICTIONS:
The display is currently limited to 1-D and 2-D data. Slices or
sums of 3-D or 4-D data can be displayed in 1-D or 2-D using the
[X,Y,Z]RANGE and/or [X,Y,Z]TOTAL keywords.
A plot legend should be automatically created for 1-D data with
multiple detectors. I don't know how to do this yet. However, it
is easy to manually create a legend: click in the dataspace (away
from any curves) and then use Insert/Legend from the menu.
An image title should be automatically placed above each image.
I don't know how to do this yet. Titles can be added manually with
the annotation tools.
EXAMPLE:
IDL> s=read_mda('2idd_0087.mda')
IDL> s->display ; Displays the first detector in scan2
IDL> s->display, /all, /grid ; Note this takes a minute or so, since
; 47 images are created in one iTool
IDL> s->display, detector=10, /ytotal ; 1-D plot of sum over all rows
IDL> s->display, scan=1, /view_next ; Plot of outer scan, same window
MODIFICATION HISTORY:
Written by: Mark Rivers, Nov. 8, 2003
(See epics_sscan__define.pro)
NAME:
epics_sscan::getData
PURPOSE:
This function returns the positioner and detector information for a scan.
The information is returned as an array of {epics_sscanPositioner}
and {epics_sscanDetector} structures. The subset of the data to be returned
can be specified.
CATEGORY:
EPICS scanning tools.
CALLING SEQUENCE:
Result = scan->getData(PositionArray, DetectorArray)
KEYWORD PARAMETERS:
SCAN:
The scan for which information will be returned.
Passed to epics_sscan::getPositioner() and epics_sscan::getDetector().
POSITIONER:
The number of the positioner to return.
Passed to epics_sscan::getPositioner().
DETECTOR:
The number of the detector to return.
Passed to epics_sscan::getDetector().
ALL:
Set this flag to return an array of all of the detectors for this
scan. Passed to epics_sscan::getDetector()
[X,Y,Z]RANGE:
Use this keyword to restrict the range of array elements returned in
the X, Y, or Z dimensions. 3-D arrays indices are defined as [X,Y,Z].
[X,Y,Z]RANGE can each be either:
- A scalar, in which case a single array element is returned in
that direction. This will reduce the rank of the detector data
by 1.
- A 2-element array, in which case a range of array elements are
returned in that direction. If both elements of the array are
the same it is equivalent to specifying a scalar for that keyword.
[X,Y,Z]TOTAL:
Set this flag to sum over the array elements in the X, Y, or Z
dimensions. The summation is performed after application of the
[X,Y,Z]RANGE keyword, so it is possible to sum over a restricted
range of array elements. Each use of this keyword will reduce the
rank of the detector data by 1. It will also change which positioner
arrays are returned, since positioner arrays are not returned for
axes with only one element.
OUTPUTS:
This function returns a status flag, 0 for success, -1 for failure.
The positioner information is returned in the PositionArray parameter
as array of {epics_sscanPositioner} structures.
The detector information is returned in the DetectorArray parameter
as array of {epics_sscanDetector} structures.
EXAMPLE:
IDL> s=read_mda('2idd_0087.mda')
IDL> status=s->getData(p, d, scan=2, /all)
IDL> print, p[0].description, ' ', p[1].description
PM500_X PM500_Y
IDL> help, d
D STRUCT = -> EPICS_SSCANDETECTOR Array[47]
IDL> status=s->getData(p, d, scan=2, detector=10, /ytotal, yrange=[10,20])
IDL> help, *d.pData
<PtrHeapVar74409> FLOAT = Array[41]
MODIFICATION HISTORY:
Written by: Mark Rivers, Nov. 8, 2003
(See epics_sscan__define.pro)
NAME:
epics_sscan::getDetector
PURPOSE:
This function returns the detector information for a scan.
The information is returned as an array of {epics_sscanDetector}
structures.
CATEGORY:
EPICS scanning tools.
CALLING SEQUENCE:
Result = scan->getDetector()
KEYWORD PARAMETERS:
SCAN:
The scan for which detector information will be returned.
The default is the innermost scan. Valid range=1 to the "rank" of
the overall dataset, e.g. 1 for a 1-D scan, 2 for a 2-D scan, etc.
DETECTOR:
The number of the detector to return. Valid range=1 to number of
detectors in this scan. Default=1, the first detector for this
scan.
ALL:
Set this flag to return an array of all of the detectors for this
scan.
COPY:
Set this flag to return a copy of the detector data, rather than
having the pointer in the {epics_sscanDetector} structure point to
the original data in the epics_sscan object. Set this flag if you
will be modifying the data.
OUTPUTS:
This function returns an array of {epics_sscanDetector}
structures. The number of elements in this array will be 1 by default,
or if the DETECTOR keyword is specified. If the ALL keyword is specified
then the array dimension will be the total number of detectors in this scan.
EXAMPLE:
IDL> s=read_mda('2idd_0087.mda')
IDL> d=s->getDetector(scan=2, detector=6)
IDL> print, (*d.pData)[5:7,6:8]
49.0000 54.0000 60.0000
51.0000 39.0000 61.0000
64.0000 45.0000 51.0000
IDL> print, d.name
2idd:mca1.R1
MODIFICATION HISTORY:
Written by: Mark Rivers, Nov. 8, 2003
(See epics_sscan__define.pro)
NAME:
epics_sscan::getFileHeader
PURPOSE:
This procedure returns a structure of type {epics_sscanFileHeader}.
Using this structure users can write IDL software to retrieve all of
the data from the epics_sscan object, and hence from an MDA file.
This structure contains pointers to an array of {epics_sscanScanHeader}
structures, which contain the headers and pointers to the data for each
scan (1 to rank).
CATEGORY:
EPICS scanning tools.
CALLING SEQUENCE:
fileHeader = scan->getFileHeader()
EXAMPLE:
IDL> s=read_mda('2idd_0087.mda')
IDL> h=s->getFileHeader()
IDL> help, /structure, h
** Structure EPICS_SSCANFILEHEADER, 9 tags, length=44, data length=42:
FILENAME STRING '2idd_0087.mda'
VERSION FLOAT 1.30000
NUMBER LONG 87
RANK INT 2
PDIMS POINTER <PtrHeapVar4>
ISREGULAR LONG 1
NUMEXTRA LONG 43
PSCANHEADER POINTER <PtrHeapVar2>
PEXTRAPVS POINTER <PtrHeapVar112>
IDL> print, 'dims=', *h.pDims
dims= 41 41
IDL> help, /structure, (*h.pScanHeader)[0]
** Structure EPICS_SSCANSCANHEADER, 12 tags, length=64, data length=62:
RANK INT 2
NPTS LONG 41
CPT LONG 41
PSCANPOINTERS POINTER <PtrHeapVar5>
NAME STRING '2idd:scan2'
TIMESTAMP STRING 'Jun 19, 2003 23:59:05.085430051'
NUMPOSITIONERS LONG 1
NUMDETECTORS LONG 8
NUMTRIGGERS LONG 1
PPOSITIONERS POINTER <PtrHeapVar6>
PDETECTORS POINTER <PtrHeapVar8>
PTRIGGERS POINTER <PtrHeapVar17>
MODIFICATION HISTORY:
Written by: Mark Rivers, Nov. 8, 2003
(See epics_sscan__define.pro)
NAME:
epics_sscan::getPositioner
PURPOSE:
This function returns the positioner information for a scan.
The information is returned as an array of {epics_sscanPositioner}
structures.
CATEGORY:
EPICS scanning tools.
CALLING SEQUENCE:
Result = scan->getPositioner()
KEYWORD PARAMETERS:
SCAN:
The scan for which positioner information will be returned.
The default is the innermost scan. Valid range=1 to the "rank" of
the overall dataset, e.g. 1 for a 1-D scan, 2 for a 2-D scan, etc.
POSITIONER:
The number of the positioner to return. Valid range=1 to number of
positioners in this scan. Default=1, the first positioner for this
scan.
ALL:
Set this flag to return an array of all of the positioners for this
scan.
COPY:
Set this flag to return a copy of the positioner data, rather than
having the pointer in the {epics_sscanPositioner} structure point to
the original data in the epics_sscan object. Set this flag if you
will be modifying the data.
OUTPUTS:
This function returns an array of {epics_sscanPositioner}
structures. The number of elements in this array will be 1 by default,
or if the POSITIONER keyword is specified. If the ALL keyword is specified
then the array dimension will be the total number of positioners in this scan.
If there are no positioners for this scan, this function will return
a new {epics_sscanPositioner} structure, with the data set to the array
index in the data, e.g [0,1,2,3,..NPTS-1]
EXAMPLE:
IDL> s=read_mda('2idd_0087.mda')
IDL> p=s->getPositioner(scan=2)
IDL> print, *p.pData
-10.000000 -9.5000000 -9.0000000 -8.5000000 -8.0000000 -7.5000000 -7.0000000
-6.5000000 -6.0000000 -5.5000000 -5.0000000 -4.5000000 -4.0000000 -3.5000000 -3.0000000
-2.5000000 -2.0000000 -1.5000000 -1.0000000 -0.50000000 0.00000000 0.50000000 1.0000000
1.5000000 2.0000000 2.5000000 3.0000000 3.5000000 4.0000000 4.5000000 5.0000000
5.5000000 6.0000000 6.5000000 7.0000000 7.5000000 8.0000000 8.5000000 9.0000000
9.5000000 10.000000
IDL> print, p.description
PM500_X
MODIFICATION HISTORY:
Written by: Mark Rivers, Nov. 8, 2003
(See epics_sscan__define.pro)
NAME:
epics_sscan::print
PURPOSE:
This procedure converts scan data to ASCII format. It can be saved
in a file, and/or displayed in a text window. The default is to print
only header information to a temporary file, and then display that file
in a window using the IDL XDISPLAYFILE procedure. Keywords can be used
to control what information is output, the name of the output file, and
whether the file is displayed.
CATEGORY:
EPICS scanning tools.
CALLING SEQUENCE:
scan->print
KEYWORD PARAMETERS:
POSITIONER:
Set this flag to output the positioner data.
DETECTOR:
Set this flag to output the detector data.
EXTRAPVS:
Set this flag to output the extra PV data.
ALL:
Equivalent to /POSITIONERS, /DETECTORS, /EXTRAPVS
OUTPUT:
Set this keyword to the name of an output to write the ASCII
data to. Don't forget to use /ALL if you want to dump the entire
scan.
DISPLAY:
Set this flag to display the output file in a window using XDISPLAYFILE.
The default is DISPLAY=1 if the OUTPUT keyword is not specified, and
DISPLAY=0 if the output keyword is specified.
EXAMPLE:
IDL> s=read_mda('2idd_0087.mda')
IDL> s->print ; Display the header information to a window
IDL> s->print, /all ; Display everything to a window
IDL> s->print, /all, output='2idd_0087.ASCII'
MODIFICATION HISTORY:
Written by: Mark Rivers, Nov. 8, 2003
(See epics_sscan__define.pro)
NAME:
epics_sscan::print_columns
PURPOSE:
This procedure converts scan data to ASCII column format. epics_sscan::print
is intended mainly for human-readable display, while epics_sscan::print_column
is more suitable for exporting data to other programs, such as spreadsheets.
CATEGORY:
EPICS scanning tools.
CALLING SEQUENCE:
scan->print_columns
KEYWORD PARAMETERS:
SCAN:
The scan to display.
Default is the innermost scan in this scan object.
Passed to epics_sscan::getData().
POSITIONER:
The number of the positioner to display.
Passed to epics_sscan::getData().
DETECTOR:
The number of the detector(s) to display.
Passed to epics_sscan::getData().
[X,Y,Z]RANGE:
Used this keyword to restrict the range of array elements display in
the X, Y, or Z dimensions. Passed to epics_sscan::getData()
[X,Y,Z]TOTAL:
Set this flag to sum over the array elements in the X, Y, or Z
dimensions. Passed to epics_sscan::getData()
DELIMITER:
The delimiter between fields in the output. Default=' '.
OUTPUT:
Set this keyword to the name of an output to write the ASCII
column data to.
DISPLAY:
Set this flag to display the output file in a window using XDISPLAYFILE.
The default is DISPLAY=1 if the OUTPUT keyword is not specified, and
DISPLAY=0 if the output keyword is specified.
EXAMPLE:
IDL> s=read_mda('2idd_0087.mda')
IDL> s->print_columns, scan=1, positioners=1 ; Display all detectors for the first scan.
MODIFICATION HISTORY:
Written by: Mark Rivers, Oct. 10, 2006
(See epics_sscan__define.pro)
NAME:
epics_sscan::read_mda
PURPOSE:
This procedure reads an MDA file into an epics_sscan object.
CATEGORY:
EPICS scanning tools.
CALLING SEQUENCE:
scan->read_mda, Filename
INPUTS:
Filename: The name of the MDA file to read.
EXAMPLE:
IDL> s=obj_new('epics_sscan')
IDL> s->read_mda, '2idd_0087.mda'
IDL> s->display ; Displays the first detector in scan2
MODIFICATION HISTORY:
Written by: Mark Rivers, Nov. 8, 2003
(See epics_sscan__define.pro)
NAME:
epics_sscan__define
PURPOSE:
This procedure defines the EPICS_SSCAN class.
The EPICS_SSCAN class is designed to do the following:
- Provide an object-oriented interface to standard EPICS scans, enabling
user written software to easily access scan header information and data.
- Provide an easy way to read MDA files written by the saveData function
in synApps.
- Provide an easy way to get scan data into the IDL iTools system.
iTools provide easy to use interfaces for visualizing data, zooming
in, adding annotation, and producing publication quality plots.
- Provide a way to convert binary scan files (e.g. MDA) into ASCII
The initial implementation of EPICS_SSCAN only reads MDA files.
Future enhancements may add a channel-access interface for reading scans
from the IOC directly. Additional file readers (e.g. Nexus) may be
added.
CATEGORY:
EPICS scanning tools.
CALLING SEQUENCE:
This routine cannot be called directly. It is called indirectly as follows:
scan = OBJ_NEW('EPICS_SSCAN')
DATA STRUCTURES:
This class defines a number of IDL structure types to store the scan
information. These structures map closely to the structure of EPICS scans
and MDA data files. However, they are not limited to MDA files, they could
be used to contain data from any EPICS scan.
The fields described below for these structures are guaranteed to be
present. More fields may be added in the future as the EPICS_SSCAN
class is enhanced.
The top-level data structure is the {epics_sscanFileHeader}. There is
only one of these structures in an EPICS_SSCAN object. It can be returned
with the epics_sscan::getFileHeader method. With this structure all of
the information in the scan can be retrieved.
This structure is defined as follows:
{epics_sscanFileHeader, $ ; Defines the overall scan data set
fileName: '', $ ; Contains name of file read with ::read_mda
version: 0., $ ; File version. 1.3 for current files.
number: 0L, $ ; Scan number
rank: 0S, $ ; Rank of outermost scan (1 for 1-D, 2 for 2-D, etc.)
pDims: ptr_new(), $ ; Pointer to array of scan dimensions
isRegular: 0L, $ ; Don't know what this means yet
numExtra: 0L, $ ; Number of extra PVs
pScanHeader: ptr_new(), $ ; Pointer to array of {epics_sscanScanHeader} structures
; Array dimensions = "rank"
pExtraPVs: ptr_new() $ ; Pointer to array of {epics_sscanExtraPV} structures
; Array dimensions = "numExtra"
}
The next structure is the {epics_sscanScanHeader}. It describes a
single scan. {epics_sscanFileHeader} points to an array of these.
This structure is defined as follows:
{epics_sscanScanHeader, $ ; Defines a single scan.
rank: 0S, $ ; Rank of this scan (1 for 1-D, 2 for 2-D, etc.)
npts: 0L, $ ; Number of points in this scan
cpt: 0L, $ ; Current point. Less than npts if scan is incomplete.
pScanPointers: ptr_new(), $ ; Pointers to offsets in file where scans start.
name: '', $ ; Name of this scan. This seems wrong in MDA files.
timeStamp: '', $ ; Time when scan completed
numPositioners: 0L, $ ; Number of positioners
numDetectors: 0L, $ ; Number of detectors
numTriggers: 0L, $ ; Number of detector triggers
pPositioners: ptr_new(), $ ; Pointer to array of {epics_sscanPositioner}
; Array dimensions = "numPositioners"
pDetectors: ptr_new(), $ ; Pointer to array of {epics_sscanDetector}
; Array dimensions = "numDetectors"
pTriggers: ptr_new() $ ; Pointer to array of {epics_sscanTrigger}
; Array dimensions = "numTriggers"
}
The next structure is the {epics_sscanScanPositioner}. It describes a
single positioner. {epics_sscanScanHeader} points to an array of these.
This structure is defined as follows:
{epics_sscanPositioner, $ ; Defines a positioner
number: 0L, $ ; Index number
name: '', $ ; PV name
description: '', $ ; Description string
stepMode: '', $ ; Step mode (LINEAR, TABLE, etc.)
units: '', $ ; Units string
readbackName: '', $ ; PV name of readback
readbackDescription: '', $ ; Readback description
readbackUnits: '', $ ; Readback units
pData: ptr_new() $ ; Pointer to positioner data array.
; Array type=DOUBLE
; Array dimensions = "npts" for this scan
}
The next structure is the {epics_sscanScanDetector}. It describes a
single detector. {epics_sscanScanHeader} points to an array of these.
This structure is defined as follows:
{epics_sscanDetector, $ ; Defines a detector
number: 0L, $ ; Index number
name: '', $ ; PV name
description: '', $ ; Description string
units: '', $ ; Units string
pData: ptr_new() $ ; Pointer to detector data
; Array type=FLOAT
; Array dimensions=(N, M, ...) where N
; is npts for this scan, M is npts for
; next outer scan, etc.
}
The next structure is the {epics_sscanScanTrigger}. It describes a
single detector trigger. {epics_sscanScanHeader} points to an array of these.
This structure is defined as follows:
scanTrigger = $
{epics_sscanTrigger, $ ; Defines a scan trigger
number: 0L, $ ; Index number
name: '', $ ; PV name
command: 0. $ ; Command value written to PV to trigger
}
The final structure is the {epics_sscanScanExtraPV}. It describes a
single extra PV. {epics_sscanFileHeader} points to an array of these.
This structure is defined as follows:
extraPV = $
{epics_sscanExtraPV, $ ; Defines an "extra" PV stored with scan
name: '', $ ; PV name
description: '', $ ; Description string
type: 0L, $ ; Data type (see db_access.h for defs)
count: 0L, $ ; Number of values
units: '', $ ; Units string
pValue: ptr_new() $ ; Pointer to value
}
EXAMPLE:
IDL> s=obj_new('epics_sscan')
IDL> s->read_mda, '2idd_0087.mda'
IDL> h=s->getFileHeader()
MODIFICATION HISTORY:
Written by: Mark Rivers, Nov. 8, 2003
(See epics_sscan__define.pro)
NAME:
read_mda
PURPOSE:
This function:
- Creates an EPICS_SSCAN object
- Reads an EPICS MDA scan file
- Returns an object reference to the EPICS_SSCAN object
CATEGORY:
EPICS scanning tools.
CALLING SEQUENCE:
scan = read_mda(Filename)
INPUTS:
Filename: The name of the MDA file to read.
OUTPUTS:
This function returns an object reference to the EPICS_SSCAN object.
PROCEDURE:
This is a very simple function. It simply does the following:
s = obj_new('epics_sscan')
s->read_mda, file
return, s
RESTRICTIONS:
While this function is easy to use, users need to be aware that
calling this function repeatedly without destroying the returned
objects will lead to memory leaks. This may be acceptable for
interactive use, but software written to use the EPICS_SSCAN class
should create objects sparingly and use the epics_sscan::read_mda
method directly, rather than calling this function.
EXAMPLE:
IDL> s=read_mda('2idd_0087.mda')
IDL> s->display, detector=[4,5,6,7], /grid
MODIFICATION HISTORY:
Written by: Mark Rivers, Nov. 8, 2003
(See read_mda.pro)