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: Sun Nov 23 12:35:26 2014.
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.
CATEGORY:
Imaging
CALLING SEQUENCE:
IMAGE_DISPLAY, Data, Object_ref
INPUTS:
Data: A 2-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.
OPTIONAL OUTPUTS:
Object_ref:
The object reference for the resulting IMAGE_DISPLAY object. This
is useful for controlling the IMAGE_DISPLAY object from other
routines.
PROCEDURE:
This procedure simply create a new object of class IMAGE_DISPLAY.
See the documentation for the IMAGE_DISPLAY class library for more information.
EXAMPLE:
IDL> a = DIST(512)
IDL> image_display, a
MODIFICATION HISTORY:
Written by: Mark Rivers (3-DEC-1998)
(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.
CATEGORY:
Imaging
CALLING SEQUENCE:
obj = OBJ_NEW('IMAGE_DISPLAY', Data)
INPUTS:
Data: A 2-D array 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 xsize of Data.
YDIST: An array containing the user units ("distance") of the
Y axis pixels. Dimensions must be same as ysize of Data.
MIN: The minimum display intensity. Default=min(Data).
MAX: The maximum display intensity. Default=max(Data).
TITLE: The title to give the display window.
SUBTITLE: The subtitle to give the display window.
ORDER: The order in which to display the image.
0=bottom to top
1=top to bottom
Default = !ORDER system variable when this function is called.
OUTPUTS:
This function returns 1 to indicate that the object was successfully
created.
EXAMPLE:
IDL> a = DIST(512)
IDL> obj = OBJ_NEW('IMAGE_DISPLAY', a)
MODIFICATION HISTORY:
Written by: Mark Rivers (3-DEC-1998)
3-APR-1999 MLR Fixed so that it will reform input array if it is
greater than 2-D but with some dimensions=1,
e.g. Data = intarr(100,1,100), which happens
frequently when extracting slices from 3-D data
23-SEP-1999 MN Added code to write JPEG file
12-APR-2001 MLR Added cleanup code so that the image_display object and all
pointers are free when the user closes the window.
11-JUN-2001 MN Added dropdown menu for output types (JPEG, BMP, PNG), and
added 'title' and 'subtitle' keywords which are
displayed in the window title
17-JAN-2001 MLR Delete line that called "a2f". Line did nothing and a2f
is not needed.
27-APR-2002 MLR Added order keywords to write_jpeg and write_png so images
are correct side up.
Fixed bug in plotting vertical column profile if self.image_window.order=1, thanks
to Peter Vontobel of Swiss Light Source.
4-JUN-2002 MLR Added "title" keyword to image_display::display_image
and "leave_mouse" keyword to other routines. These
changes allow tomo_display:: to scroll though 2-D
slices in a 3-D volume quickly and easily.
27-APR-2006 MLR Added "tiff" output option
21-NOV-2007 MLR Added order keyword and order widget, no longer use !order except at startup
Added RETAIN keyword to SCALE_IMAGE, to preserve zoom, center and intensity
scaling.
Added autoscale widget for automatically scaling display range.
(See image_display__define.pro)
NAME:
IMAGE_DISPLAY::SCALE_IMAGE
PURPOSE:
This routine displays a new image in an existing IMAGE_DISPLAY object.
CATEGORY:
Imaging
CALLING SEQUENCE:
image_data->SCALE_IMAGE, Data
INPUTS:
Data: A 2-D array to be displayed
KEYWORD PARAMETERS:
XDIST: An array containing the user units ("distance") of the
X axis pixels. Dimensions must be same as xsize of Data.
YDIST: An array containing the user units ("distance") of the
Y axis pixels. Dimensions must be same as ysize of Data.
MIN: The minimum display intensity. Default=min(Data).
MAX: The maximum display intensity. Default=max(Data).
ZOOM: A scaler or 2-element (X,Y) array of integer zoom factors.
Default = 1 in each direction. ZOOM=2 will zoom 2X in both
directions, ZOOM=[1,2] will zoom 1X in X, 2X in Y.
CENTER: The location where the center of the image should be located
in the display window.
The default is the center of the display window.
CENTER=[200,300] will center the image at X=200, Y=300
NOERASE: Set this flag to not erase the window before displaying the
image. Allows multiple images to share a window.
INTERPOLATE: Zoom the image by interpolation rather than replication.
REPLICATE: Zoom the image by replication rather than interpolation.
TITLE: The title to give the display window.
SUBTITLE: The subtitle to give the display window.
ORDER: The order in which to display the image.
0=bottom to top
1=top to bottom
Default = Existing order
LEAVE_MOUSE: Set this keyword to not move the mouse to the center of the
new image display.
RETAIN: Set this keyword to not reset the zoom and intensity scaling when
when the new data are displayed. This requires that the dimensions
of the image be the same as the image currently displayed.
MODIFICATION HISTORY:
Written by: Mark Rivers (3-DEC-1998)
20-Nov-2007 MLR Added ORDER and RETAIN keywords.
EXAMPLE:
IDL> a = DIST(512)
IDL> obj = OBJ_NEW('IMAGE_DISPLAY', a)
IDL> obj->SCALE_IMAGE, a+100, /RETAIN
(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 MPEG file on disk (deprecated)
- To an MP4 file on disk
- To a series of JPEG files on disk
- To a series of TIFF files on disk
CATEGORY:
Image display.
CALLING SEQUENCE:
MAKE_MOVIE, Volume
INPUTS:
Volume: A 3-D array of any numeric data type. This input is ignored if the FILE
keyword is used.
KEYWORD PARAMETERS:
FILE:
The name of a file to be used as input, rather than passing the Volume array.
This file is read with READ_TOMO_VOLUME().
BUFFER_SIZE:
When reading a large file from disk with the FILE keyword, this keyword
controls the size of the memory buffer used for reading the file. If the size
of the file is larger than the buffer size then the file is read in "chunks".
This allows displaying files larger than the physical or virtual memory of
the system would otherwise permit. The units are voxels, not bytes.
The default is to read the entire file.
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 MPEG_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.
MPEG_FILE:
The name of an MPEG 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 MPEG file.
NOTE: IDL requires a special (free) license upgrade to write MPEG
files. See the IDL Web site for details.
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 and MPEG files.
See the help for WRITE_JPEG for more information on using this
keyword for JPEG files.
See the help for MPEG_OPEN for more information on using this
keyword for MPEG files. For MPEG files this keyword is only allowed
for IDL 5.4 and higher.
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, MPEG, 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 of the
preprocessing operation. 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, MPEG_FILE
or MP4_FILE is used.
SIDE EFFECTS:
Displays images on the screen using the IDL TV procedure, or writes output
to disk if JPEG_FILE, 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 MPEG file, an MP4 file, or to a series of JPEG or TIFF files.
EXAMPLE:
; 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 MPEG 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, mpeg_file='movie1.mpeg'
; 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'
; Create a series of JPEG files of disk file scanning through the first dimension
; of the array, forcing the white level to be 5000. Set a buffer size of
; 200,000,000 voxels (400MB for 16 bit data)
MAKE_MOVIE, file='my_volume.dat', max=5000, index=1, jpeg_file='my_volume_X', $
buffer_size=2e8
MODIFICATION HISTORY:
Written by: Mark Rivers, April 26, 1999. Merged previous routines
TOMO_MOVIE and WRITE_MPEG
June 27, 2000 MLR Changed position of label slightly for legibility
Sep. 29, 2000 MLR Added JPEG_FILE and QUALITY keywords.
Feb. 27, 2001 MLR Added COLOR keyword for color JPEG and MPEG files.
Made QUALITY keyword apply to MPEG files if the IDL version
is 5.4 or higher.
Nov. 5, 2001 MLR Added the FILE and BUFFER_SIZE keywords.
Nov. 22, 2001 MLR Added the ABORT_WIDGET and STATUS_WIDGET keywords
Nov. 24, 2001 MLR Added the WINDOW keyword
Apr. 26, 2002 MLR Worked around bug in MPEG_PUT, movies were upside down relative
to on-screen and JPEG files.
Jan. 9, 2004 MLR Added TIFF_FILE keyword
Nov. 30, 2004 MLR Put MPEG and JPEG output through lookup table if COLOR=0.
(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)