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: Fri Mar 31 16:20:51 2023.
NAME:
EPICS_AD_DISPLAY
PURPOSE:
This procedure is a general purpose routine to display EPICS arrays as
images.
It uses either the built-in IDL routine TV for simple image display, or our routine IMAGE_DISPLAY to perform interactive pan,
zoom and scroll, live update of row and column profiles, etc.
CATEGORY:
Imaging
CALLING SEQUENCE:
EPICS_AD_DISPLAY, ImagePV
INPUTS:
ImagePV: The base name of an areaDetector NDStdArrays object that contains the image data. This name is the
$(P)$(R) values passed to NDStdArrays.template when the EPICS database is loaded. This database
contains not only the image data itself, but also PVs that contain the image dimensions, etc.
PROCEDURE:
This procedure simply create a new object of class EPICS_AD_DISPLAY.
See the documentation for EPICS_AD_DISPLAY for more information.
PREBUILT VERSION:
In addition to the source code version of these files, the file epics_ad_display.sav
is included in the distribution tar file. This file can be run for free
(no IDL license needed) with the IDL Virtual Machine.
IMPORTANT NOTES:
The environment variable EZCA_IDL_SHARE must be set to point to the complete path
to the shareable library ezcaIDL.so (Linux, Unix, and Mac) or ezcaIDL.dll (Windows).
Note that the ezcaIDL shareable library or DLL must be built with EPICS R3.14 or later
in order to use arrays larger than 16000 bytes.
The environment variable EPICS_CA_MAX_ARRAY_BYTES must be set to at least the number
of bytes in the the image data array.
EXAMPLE:
IDL> epics_ad_display, 'GSE-PILATUS1:Image1:'
MODIFICATION HISTORY:
Written by: Mark Rivers (21-Jul-2007)
(See epics_ad_display.pro)
NAME:
EPICS_AD_DISPLAY::INIT
PURPOSE:
The EPICS_IMAGE_DISPLAY class provides a general purpose routine to display
EPICS arrays as images. It uses either TV for simple but fast display,
or IMAGE_DISPLAY to perform interactive pan,
zoom and scroll, live update of row and column profiles, etc.
This function initializes an object of class EPICS_AD_DISPLAY. It is
not called directly, but is called indirectly when a new object of
class EPICS_IMAGE_DISPLAY is created via OBJ_NEW('EPICS_IMAGE_DISPLAY')
The EPICS_AD_DISPLAY object creates simple GUI display which provides
widgets to control the EPICS PV to display, the number of rows and columns in
the images, inverting in the Y direction, enable/disable, and a status display.
EPICS_AD_DISPLAY waits new data for the EPICS array, and then displays the
new image.
CATEGORY:
Imaging
CALLING SEQUENCE:
obj = OBJ_NEW('EPICS_AD_DISPLAY', ImagePV)
INPUTS:
ImagePV: The base name of an areaDetector NDStdArrays object that contains the image data. This name is the
$(P)$(R) values passed to NDStdArrays.template when the EPICS database is loaded. This database
contains not only the image data itself, but also PVs that contain the image dimensions, etc.
In order to display images that contain more than 16000 bytes (which most images do!)
it is necessary that both the EPICS server (e.g. IOC) and the EPICS client
(i.e. ezcaIDL.so or ezcaIDL.dll) be built with EPICS 3.14 or later.
Furthermore, one must set the environment variable EPICS_CA_MAX_ARRAY_BYTES to be
at least the size of the image array data. This must be done on both the client and
server machines.
For example, with the Pilatus detector we typically set EPICS_CA_MAX_ARRAY_BYTES=500000.
OUTPUTS:
This function returns 1 to indicate that the object was successfully
created.
REQUIREMENTS:
This function requires IMAGE_DISPLAY__DEFINE.PRO,
GET_FONT_NAME.PRO, and ezcaIDL.
EZCA_IDL requires the shareable library (ezcaIDL.so or ezcaIDL.dll) that
contains the functions used to communicate with EPICS.
EXAMPLE:
IDL> obj = OBJ_NEW('EPICS_IMAGE_DISPLAY', 'GSE-PILATUS1:ImageData', nx=487, ny=195)
MODIFICATION HISTORY:
Written by: Mark Rivers (1-March-2008).
(See epics_ad_display__define.pro)
NAME:
IMAGE_DISPLAY
PURPOSE:
This procedure is a general purpose image display routine.
It allows interactive pan, zoom and scroll, live update of row and column profiles, etc.
CALLING SEQUENCE:
IMAGE_DISPLAY, DATA, KEYWORD=VALUE
INPUTS:
DATA:
A 2-D or 3-D array to be displayed
KEYWORD PARAMETERS:
This procedure simply passes all keywords to IMAGE_DISPLAY::INIT by
the keyword inheritence mechanism (_EXTRA).
See the documentation for IMAGE_DISPLAY::INIT for more information.
PROCEDURE:
This procedure simply create a new object of class IMAGE_DISPLAY.
See the documentation for the IMAGE_DISPLAY class library for more information.
(See image_display.pro)
NAME:
IMAGE_DISPLAY::INIT
PURPOSE:
This function initializes an object of class IMAGE_DISPLAY.
It is not called directly, but is called indirectly when a new object of
class IMAGE_DISPLAY is created via OBJ_NEW('IMAGE_DISPLAY')
The IMAGE_DISPLAY object is a GUI display which provides interactive
pan, zoom and scroll, live update of row and column profiles, etc.
CALLING SEQUENCE:
OBJ = OBJ_NEW('IMAGE_DISPLAY', DATA, KEYWORD=VALUE, ...)
INPUTS:
DATA:
A 2-D or 3-D array to be displayed.
If DATA is 3-D then widgets at the bottom of the GUI are used to select the direction (to be displayed X, Y, Z),
and the slice in that direction to be displayed.
KEYWORD PARAMETERS:
XSIZE:
The number of pixels horizontally in the image window.
Default is the greater of 400 pixels or the xsize of DATA.
YSIZE:
The number of pixels vertically in the image window.
Default is the greater of 400 pixels or the ysize of Data.
XDIST:
An array containing the user units ("distance") of the X axis pixels. Dimensions must be same as X size of DATA.
Default: Pixel number in X direction.
YDIST:
An array containing the user units ("distance") of the Y axis pixels. Dimensions must be same as Y size of DATA.
Default: Pixel number in Y direction.
ZDIST:
An array containing the user units ("distance") of the Z axis pixels. Dimensions must be same as Z size of DATA.
Default: Pixel number in Z direction.
Only used if data is 3-D.
MIN:
The minimum display intensity. Default=min(DATA).
MAX:
The maximum display intensity. Default=max(DATA).
TITLE:
The title to be displayed on the top of the main IMAGE_DISPLAY window.
ORDER:
The order in which to display the image.
0=bottom to top
1=top to bottom
Default = Existing order
OUTPUTS:
This function returns 1 to indicate that the object was successfully created.
(See image_display__define.pro)
NAME:
IMAGE_DISPLAY::NEW_IMAGE
PURPOSE:
This routine displays a new image in an existing image_display object.
CALLING SEQUENCE:
IMAGE_DISPLAY::NEW_IMAGE, DATA, XDIST=XDIST, YDIST=YDIST, MIN=MIN, MAX=MAX, TITLE=TITLE, ORDER=ORDER
INPUTS:
DATA: The 2-D image to display. It must have the same dimensions as the currently displayed image.
KEYWORD PARAMETERS:
XDIST:
An array containing the user units ("distance") of the X axis pixels. Dimensions must be same as xsize of DATA.
Default: Pixel number in X direction.
YDIST:
An array containing the user units ("distance") of the Y axis pixels. Dimensions must be same as ysize of DATA.
Default: Pixel number in Y direction.
MIN:
The minimum display intensity. Default=min(Data).
MAX:
The maximum display intensity. Default=max(Data).
TITLE:
The title to be displayed on the top of the main IMAGE_DISPLAY window.
ORDER:
The order in which to display the image.
0=bottom to top
1=top to bottom
Default = Existing order
PROCEDURE:
- Sets the image ORDER if specified.
- Sets XDIST and YDIST to the default or specified values.
- Deletes the existing IMAGE object and creates a new one.
- Deletes the existing row and column PLOT objects and creates new ones.
- Calls IMAGE_DISPLAY::SET_IMAGE_DATA to display the image and update the row and column profile plots
(See image_display__define.pro)
NAME:
IMAGE_DISPLAY::SET_IMAGE_DATA
PURPOSE:
This procedure is used to display a new 2-D slice.
It should only be called when the data is the same dimensions as the data
passed when the IMAGE_DISPLAY object was created, or when IMAGE_DISPLAY::NEW_IMAGE was called.
CALLING SEQUENCE:
IMAGE_DISPLAY::SET_IMAGE_DATA, DATA, TITLE=TITLE, MIN=MIN, MAX=MAX
INPUTS:
DATA: The 2-D image to display. It must have the same dimensions as the currently displayed image.
KEYWORD PARAMETERS
TITLE:
The title to be displayed on the top of the main IMAGE_DISPLAY window.
Default: 'IDL Image Display'
MIN:
The minimum intensity to be displayed. Values less than this are displayed as the first color table entry.
Default: current minimum display intensity is not changed.
MAX:
The maximum intensity to be displayed. Values greater than this are displayed as the last color table entry.
Default: current maximum display intensity is not changed.
PROCEDURE:
- Updates the actual min and max intensity widgets.
- Sets the displayed min and max values if specified
- Updates the displayed image
- Calls IMAGE_DISPLAY::PLOT_PROFILES to update the row and column profile plots
(See image_display__define.pro)
NAME:
MAKE_MOVIE
PURPOSE:
This procedure plays a 3-D array as a movie either:
- On the screen
- To an MP4 file on disk
- To a series of JPEG files on disk
- To a series of TIFF files on disk
CALLING SEQUENCE:
MAKE_MOVIE, VOLUME, KEYWORD=VALUE, ...
INPUTS:
VOLUME:
A 3-D array of any numeric data type. This input is ignored if the FILE keyword is used.
KEYWORD PARAMETERS:
MIN:
The minimum value of the data display range.
This sets the low end of the grey scale range.
All values less than this will be appear black when using a linear grey scale.
The default is the minimum value of the data in the entire Volume array.
MAX:
The maximum value of the data display range.
This sets the high end of the grey scale range.
All values greater than this will be appear white when using a linear grey scale.
The default is the maximum value of the data in the entire Volume array.
SCALE:
A scale factor to increase or decrease the size of the displayed images
relative to the size of the Volume array.
SCALE=2 will double the size of the displayed images,
SCALE=3 will display the images at 3 times their normal size, etc.
SCALE=-2 will display the images at half their normal size,
SCALE=-3 one-third their normal size, etc.
The default is 1, i.e. no scaling.
INDEX:
This keyword controls which dimension of the Volume array is animated.
Allowed values are 1, 2 and 3. The following table shows the result
of setting this keyword:
INDEX frame[i]
1 Volume[i,*,*]
2 Volume[*,i,*]
3 Volume[*,*,i]
The default is 3, i.e. the last dimension of the Volume array is the
one which is animated.
START:
The first frame to display. The default is 0.
STOP:
The last frame to display. The default is the highest value of the selected index.
STEP:
The array increment from one frame to the next. The default is 1.
WAIT:
The delay time from one frame to the next in floating point seconds.
The default is 0., i.e. frames are diplayed as fast as possible.
This keyword has no effect if the JPEG_FILE or MP4_FILE keywords are used.
WINDOW:
The window number if the movie is being displayed on the screen.
The window will be created to be exactly the right size to display the movie.
The default is 0.
MP4_FILE:
The name of an MP4 file to which the output should be written.
If this keyword is used then this procedure does not display its output on
the screen but rather creates an MP4 file.
MP4 files are written using the IDL WRITE_VIDEO procedure which was added in IDL 8.2.3.
JPEG_FILE:
The base name of an JPEG file to which the output should be written.
If this keyword is used then this procedure does not display its output on
the screen but rather creates a series of JPEG files.
A sequence number and the extension .jpg are appended to this base name.
The file names are thus of the form 'my_jpeg_name_0001.jpg', 'my_jpeg_name_0002.jpg', etc.
The system variable !order is used to determine whether the files are written bottom to
top or top to bottom.
TIFF_FILE:
The base name of an TIFF file to which the output should be written.
If this keyword is used then this procedure does not display its output on
the screen but rather creates a series of TIFF files.
A sequence number and the extension .tif are appended to this base name.
The file names are thus of the form 'my_jpeg_name_0001.tif', 'my_jpeg_name_0002.tif', etc.
The system variable !order is used to determine whether the files are written bottom to
top or top to bottom.
UNSCALED_TIFF
Set this flag to write unscaled TIFF files.
If this flag is not set then the TIFF files are scaled to 8-bits using the MIN and MAX.
If this flag is set then the TIFF files are unscaled, and their data type will be the same
as the input VOL array, for example 16-bit signed integers.
QUALITY:
The quality factor for JPEG files.
See the help for WRITE_JPEG for more information on using this keyword for JPEG files.
Default=90.
FPS
The Frames Per Second for MP4 files. This is passed as the VIDEO_FPS keyword to WRITE_VIDEO.
The default is 30.
BPS
The bits per second MP4 files. This is passed as the BIT_RATE keyword to WRITE_VIDEO.
This keyword controls the quality and size of the MP4 file.
Larger values (e.g. 1e6) produce larger files with higher quality,
while smaller values (e.g. 1e4) produce smaller files with lower quality.
Default=1e4.
For typical 16-bit tomography data this produces a file which is about 0.7% of the size of the original
with reasonably good quality.
BPS=1e5 produces a file that is about 7% of the original size with excellent quality.
COLOR
A flag which indicates that the JPEG, or MP4 output files should be in color,
using the current color table, rather than black and white.
LABEL:
A flag which indicates that the current frame number should be drawn as a label on the screen.
This is useful for determining which frames interesting features appear in,
for use later with IMAGE_DISPLAY or other routines.
STATUS_WIDGET:
The widget ID of a text widget used to display the status information.
If this is a valid widget ID then informational messages will be written to this widget.
ABORT_WIDGET
The widget ID of a widget used to abort the preprocessing operation.
If this is a valid widget ID then the "uvalue" of this widget will be
checked periodically.
If it is 1 then this routine will clean up and return immediately.
OUTPUTS:
This procedure does not return any output to IDL.
It displays images on the screen using the IDL TV procedure, or writes output to disk
if JPEG_FILE or MP4_FILE is used.
PROCEDURE:
This procedure converts each frame to an 8-bit array using the IDL BYTSCL
function and then either displays it on the screen using the TV procedure,
writes it to an MP4 file, or to a series of JPEG or TIFF files.
EXAMPLES:
; Display an array as a movie scanning through the first dimension of the
; array, forcing the black level to be 1000, and waiting 0.2 seconds between frames.
MAKE_MOVIE, Volume, index=1, wait=.2, min=1000
; Create an MP4 movie of an array scanning through the last dimension
; (default) of the array, forcing the white level to be 10000.
MAKE_MOVIE, Volume, max=10000, mp4_file='movie1.mp4'
; Create a series of JPEG files of an array scanning through the last dimension
; (default) of the array, forcing the white level to be 10000.
MAKE_MOVIE, Volume, max=10000, jpeg_file='my_jpegs'
(See make_movie.pro)
NAME:
VOLUME_RENDER
PURPOSE:
This procedure is a general purpose GUI-based volume rendering routine.
It allows setting of cutting planes, color and opacity tables, etc.
CATEGORY:
Imaging
CALLING SEQUENCE:
VOLUME_RENDER, Data
INPUTS:
Data: A 3-D BYTE array to be displayed
PROCEDURE:
This procedure is a GUI front-end for the IDLgrVolume object.
See the documentation on IDLgrVOLUME for more information.
RESTRICTIONS:
This procedure is a work in progress, and additional features will be added
as time permits. In particular a better opacity table editor is needed.
EXAMPLE:
IDL> a = bingen(200, 200, 200)
IDL> volume_render, a
MODIFICATION HISTORY:
Written by: Mark Rivers (12-MAR-1999)
This procedure was based on the d_volrendr.pro from the
IDL demos, generalized and with additional features
(See volume_render.pro)