SECTION 2.14 - THE IMAGE DISPLAY VIEW-OBJECT ROUTINES
2.14.1 INTRODUCTION
The image view-object is designed ,in particular,for displaying film or image-plate images used in Protein Crystallography. It may be used for measuring spot positions and has facilities for overlaying symbols or other vectors on top of the displayed image. A magnifying window within the view-object shows a magnified version of a portion of the image from the main image display area. The image may also be zoomed. A control panel allows for a series of adjustments to the display.The following sets of routines are available:
Creating and Handling an Image Display View-Object
2.14.2 CREATING AND HANDLING AN IMAGE DISPLAY VIEW-OBJECT
2.14.2.1 Introduction
The following routines are available:
Create an image view-object - xdl_image
Get selected pixel position - xdl_image_getpix
Get pixel position from an overlay - xdl_image_getpix_ovly
Get selected rectangle - xdl_image_getrect
Get display settings - xdl_image_settings
Reset current display settings - xdl_image_reset
Set local axis names - xdl_image_axnames
Display the image now - xdl_image_display_now
Set background image - xdl_image_background
Set a new image - xdl_image_newimg
Reset overlay offset values - xdl_image_ovly_offset
Reset an overlay colour - xdl_image_set_colour
Reset user defined colour map - xdl_image_set_colormap
Store and display an overlay symbol - xdl_image_symbol
Store and display overlay symbols - xdl_image_symbols
Clear overlay symbols - xdl_image_clear_symbols
Delete an overlay symbol - xdl_image_del_symbol
Store and display an overlay vector - xdl_image_vect
Store and display overlay vectors - xdl_image_vects
Store and display overlay vectors - xdl_image_vects_pos
Store and display overlay boxes - xdl_image_boxes
Clear overlay vectors - xdl_image_clear_vectors
Delete an overlay vector - xdl_image_del_vect
Output a text string - xdl_image_text
Delete a text string - xdl_image_del_text
Clear all text strings - xdl_image_clear_text
Reset active strip message - xdl_image_input_message
Calculate the size requirements - xdl_image_getsize
2.14.2.2 Create an image view-object - xdl_image
The routine xdl_image (xdlf_image) is used to create a new image view object. The parameters give details of the image to be displayed.
Fortran call:
CALL XDLF_IMAGE (IVH, IVHPARENT, IX, IY, ICSET, IMGDATA, ITYPE,
+ NS_RAS, NF_RAS, NF_OFF,
+ IO_AX1, IO_AX2, NREQ_AX1, NREQ_AX2, NCMP,
+ IORDER, JORDER,
+ MINVAL, MAXVAL, MINTHR, MAXTHR, MINW, MINH,
+ IBG, IOVLY, ICONTRAST, IDISP_NOW, IERR)
Parameters:
IVH (R) View-object handle (see vh)
IVHPARENT (R) View-object handle for parent 0=none
(see vh_parent)
IX (R) X position (may be -1 if no parent) (see x)
IY (R) Y position (may be -1 if no parent) (see y)
ICSET (R) Colorset number (see cset)
IMGDATA (R) Array holding the full image data (see imgdata)
ITYPE (R) 1 = unsigned byte data
2 = unsigned two-byte data (i2)
3 = signed integer data
4 = 'squashed i2' data (if stored I<0
ipix = -i*8
5 = 'squashed i2' data if stored I<0
ipix = (I+32768)*8
6 = 'squashed i2' data if stored I<0
ipix = (I+32768)*32
7 = 'squashed i2' data if stored I<0
ipix = -(I+1)*256 + 32768
(see type)
NS_RAS (R) Number of rasters in image along slow axis
(see ns_ras)
NF_RAS (R) Number of rasters in image along fast axis
(see nf_ras)
NF_OFF (R) Number of rasters offset between rows of stored
image data (see nf_off)
IO_AX1 (R) Origin (local axis 1) pixel for section to be
displayed (see o_ax1) (from 1 upwards)
IO_AX2 (R) Origin (local axis 2) pixel for section to be
displayed (see o_ax2) (from 1 upwards)
NREQ_AX1 (R) Size of section required along local axis 1
(see nreq_ax1)
NREQ_AX2 (R) Size of section required along local axis 2
(see nreq_ax2)
NCMP (R) No. of pixels to compress into one pixel
along each axis (if NCMP>0, pixel averaging will
be done; give -NCMP to sample rather than average
(quicker)) (see ncmp)
IORDER (R) Order of the data in the input image
with respect to two local axes ax1, ax2 e.g.
(xf, yf) as a number from 1 to 8.
1 +ax1 slow +ax2 fast (+xf, +yf)
2 +ax1 slow -ax2 fast (+xf, -yf)
3 -ax1 slow +ax2 fast (-xf, +yf)
4 -ax1 slow -ax2 fast (-xf, -yf)
5 +ax2 slow +ax1 fast (+yf, +xf)
6 +ax2 slow -ax1 fast (+yf, -xf)
7 -ax2 slow +ax1 fast (-yf, +xf)
8 -ax2 slow -ax1 fast (-yf, -xf)
JORDER (R) Display order with respect to the two
local axes (1 to 8) along the X-windows
axes X horizontal (left to right), Y vertical
(top to bottom ) with origin at top left
1 +ax1 X (horiz) +ax2 Y (vert) (+xf, +yf)
2 +ax1 X (horiz) -ax2 Y (vert) (+xf, -yf)
3 -ax1 X (horiz) +ax2 Y (vert) (-xf, +yf)
4 -ax1 X (horiz) -ax2 Y (vert) (-xf, -yf)
5 +ax2 X (horiz) +ax1 Y (vert) (+yf, +xf)
6 +ax2 X (horiz) -ax1 Y (vert) (+yf, -xf)
7 -ax2 X (horiz) +ax1 Y (vert) (-yf, +xf)
8 -ax2 X (horiz) -ax1 Y (vert) (-yf, -xf)
(2 was standard for Laue programs)
MINVAL (R) Minimum pixel value present (see min_val)
MAXVAL (R) Maximum pixel value present (see max_val)
MINTHR (R) Minimum threshold for scaling
(see min_thresh)
MAXTHR (R) Maximum threshold for scaling
(see max_thresh)
MINW (R) Min. width for view-object or 0 (see min_width)
MINH (R) Min. height for view-object or 0 (see min_height)
IBG (R) =0 no background choice menu,
=1 background choice menu (Set background via
xdlf_image_background
(see bg_typ)
IOVLY (R) = 1 Overlay options are on/off/offset
= 2 Overlay options are on/off/1 on/2 on
(see ovly_typ)
ICONTRAST (R) Start contrast value 1-1024
IDISP_NOW (R) Display now flag =1 to display immediately; =0
to wait fo a call to XDLF_IMAGE_DISPLAY_NOW
before displaying (to enable other parameters
to be set first) (see disp_now)
IERR (W) Returns status from xdl_image call
'C' call:
int xdl_image (vh, vh_parent, x, y, cset, imgdata, type,
ns_ras, nf_ras, nf_off,
o_ax1, o_ax2, nreq_ax1, nreq_ax2, ncmp_in,
iorder, jorder,
min_val, max_val, min_thresh, max_thresh,
min_width, min_height, bg_typ, ovly_typ,
contrast, disp_now)
Parameters:
int vh; /* User selected view-object handle (R)*/
int vh_parent; /* View-object handle for the parent base frame,
if 0 then a base level frame is created to
enclose the image plate image view-object
(R)*/
int x; /* x coordinate for the view-object.
If no parent may be -1 to give default x (R)*/
int y; /* y coordinate for the view-object.
If no parent may be -1 to give default y (R)*/
int cset; /* Number of the colorset to be used for the
image display; must have 72 or more
colorcells allocated (R)*/
char *imgdata; /* Pointer to the image data in byte, i2 or int
format as indicated by the 'type' parameter.
The image data must remain in place as long
as the view object is being used as it will
be accessed again if the scaling thresholds
etc. are changed. (R)*/
int type; /* 1 = unsigned byte data
2 = unsigned two-byte data
3 = signed integer data
4 = 'squashed i2' data (if stored I<0
ipix = -i*8
5 = 'squashed i2' data if stored I<0
ipix = (I+32768)*8
6 = 'squashed i2' data if stored I<0
ipix = (I+32768)*32
7 = 'squashed i2' data if stored I<0
ipix = -(I+1)*256 + 32768
(R) */
int ns_ras; /* No. of rasters in slow moving direction of
full image (R)*/
int nf_ras; /* No. of rasters in fast moving direction of
full image (R)*/
int nf_off; /* Offset between the start of each stored
image row in fast axis rasters (to allow
storage of image in a pre-dimensioned 2-D
array (length of 2'nd dimension in 'C' and
1'st dimension in Fortran)) (R)*/
int o_ax1; /* The local 'ax1' (e.g.xf) origin pixel number
(pixels numbered from 1 up) for the section of
image to be displayed (R)*/
int o_ax2; /* The local 'ax2' (e.g. yf) origin pixel number
(pixels numbered from 1 up) for the section of
image to be displayed (R)*/
int nreq_ax1; /* Requested size along the first local axis
(ax1) of the section of the image to be
displayed; the actual size may be reduced by
up to ncmp-1 pixels if nreq_ax1 is not a
multiple of ncmp (see below). The actual size
will be ncmp*(nreq_ax1/ncmp) (R)*/
int nreq_ax2; /* Requested size along the second local axis
(ax2) of the section of the image to be
displayed; the actual size may be reduced by
up to ncmp-1 pixels if nreq_ax2 is not a
multiple of ncmp (see below). The actual size
will be ncmp*(nreq_ax2/ncmp) (R)*/
int ncmp_in; /* The number of image pixels in both axis
direction to be combined into 1 pixel in the
displayed image (e.g. 4 will reduce a
2400x2400 image to a 600x600 image. Give
-ncmp if compression by sampling rather than
averaging required (R) */
int iorder; /* Order of the data in the input image
with respect to two local axes ax1, ax2 e.g.
(xf, yf) as a number from 1 to 8.
1 +ax1 slow +ax2 fast (+xf, +yf)
2 +ax1 slow -ax2 fast (+xf, -yf)
3 -ax1 slow +ax2 fast (-xf, +yf)
4 -ax1 slow -ax2 fast (-xf, -yf)
5 +ax2 slow +ax1 fast (+yf, +xf)
6 +ax2 slow -ax1 fast (+yf, -xf)
7 -ax2 slow +ax1 fast (-yf, +xf)
8 -ax2 slow -ax1 fast (-yf, -xf)
(R)*/
int jorder; /* Display order with respect to the two
local axes (1 to 8) along the X-windows
axes X horizontal, Y vertical with origin
at top left
+ax1 X (horiz) +ax2 Y (vert) (+xf, +yf)
2 +ax1 X (horiz) -ax2 Y (vert) (+xf, -yf)
3 -ax1 X (horiz) +ax2 Y (vert) (-xf, +yf)
4 -ax1 X (horiz) -ax2 Y (vert) (-xf, -yf)
5 +ax2 X (horiz) +ax1 Y (vert) (+yf, +xf)
6 +ax2 X (horiz) -ax1 Y (vert) (+yf, -xf)
7 -ax2 X (horiz) +ax1 Y (vert) (-yf, +xf)
8 -ax2 X (horiz) -ax1 Y (vert) (-yf, -xf)
(2 was standard for Laue programs)
(R) */
int min_val; /* Minimum value of a pixel in the image.
Used as a lower limit for min_thresh (R)*/
int max_val; /* Maximum value of a pixel in the image.
Used as upper limit for max_thresh. (R)*/
int min_thresh; /* Minimum threshold value for the initial
intensity scaling. min_val<=min_thesh<max_val.
(R)*/
int max_thresh; /* Maximum threshold value for the initial
intensity scaling.
min_thresh<max_thresh<=max_val. (R)*/
int min_width; /* minimum width for the displayed view-object.
The program will calculate the required width
for the view-object based on the image width,
the space required for the magnified image,
slider bars, menus etc. If this is less than
min_width then min_width will be used and the
view-object will be set out as appropriate.
(R)*/
int min_height; /* minimum height for the displayed view object.
cf min_width (R) */
int bg_typ; /* =0 no background choice menu,
=1 background choice menu (Set background via
xdl_image_background routine) (R)*/
int ovly_typ; /* = 1 Overlay options are on/off/offset.
= 2 Overlay options are on/off/1 on/2 on.
Two separate sets of overlay symbols may
be drawn.
In case 1, the offset only applies to
to overlay 1; In case 2 no offsetting is
done but it is possible to switch between
the two overlays. (R)*/
int contrast; /* Starting contrast value (1-1024) (R)*/
int disp_now; /* = 1 display image when this routine has been
called.
= 0 do not display yet, wait for other
parameters to be set (e.g. contrast,
colour options) and a call to the
xdl_image_display_now routine (R)*/
Return: Status flag =0 OK, >0 error
bit 0 set: Requested parent not found in view-objects list
bit 1 set: Unable to allocate memory for global data area
bit 2 set: Unable to allocate memory for internal image
data
bit 4 set: Unable to allocate memory for magnifying window
image areas.
bit 5 set: Unable to allocate memory for compress array
2.14.2.3 Get selected pixel position - xdl_image_getpix
The routine xdl_image_getpix (xdlf_image_getpix) is used to return the last selected input pixel (spot) position to the calling program. It will normally be called after the return from a call to xdl_get_events (xdlf_get_events) indicates that an image view-object has returned input.
Fortran call:
CALL XDLF_IMAGE_GETPIX (IVH, IAX1PIX, IAX2PIX, IERR)
Parameters:
IVH (R) View-object handle (see vh)
IAX1PIX (W) Returns local axis 1 pixel position
(see ax1pix_img)
IAX2PIX (W) Returns local axis 2 pixel position
(see ax2pix_img)
IERR (W) Returns status from xdl_image_getpix call
'C' call: int xdl_image_getpix (vh, ax1pix_img, ax2pix_img)
Parameters:
int vh; /* View-object handle (R)*/
int *ax1pix_img; /* Returns the local axis 1 pixel position
(from 1 up - refers to complete uncompressed
image) (W) */
int *ax2pix_img; /* Returns the local axis 2 pixel position (W) */
Return: Status = 0 OK, >0 error
bit 0 set: View-object handle not found
bit 1 set: View handle does not match view object
2.14.2.4 Get pixel position from an overlay - xdl_image_getpix_ovly
The routine xdl_image_getpix_ovly (xdlf_image_getpix_ovly) is used to return the last selected input pixel (e.g. symbol) position from an overlay to the calling program. It differs from xdl_image_getpix (xdlf_image_getpix) in that it makes an allowance for any offsetting of the overlay currently in force. It will normally be called after the return from a call to xdl_get_events (xdlf_get_events) indicates that an image view-object has returned input.
Fortran call:
CALL XDLF_IMAGE_GETPIX_OVLY (IVH, IOV, IXPIX, IYPIX, IERR)
Parameters:
IVH (R) View-object handle (see vh)
IOV (R) Overlay number (1 o 2) (see ov_num)
IAX1PIX (W) Returns local axis 1 pixel position
(see ax1pix_img)
IAX2PIX (W) Returns local axis 2 pixel position
(see ax2pix_img)
IERR (W) Returns status from xdl_image_getpix_ovly call
'C' call: int xdl_image_getpix_ovly (vh, ov_num, ax1pix_img, ax2pix_img)
Parameters:
int vh; /* View-object handle (R)*/
int ov_num; /* Overlay number (1 or 2)
Note: Overlay 2 is never offset.
Overlay 1 will be offset if the overlay type
is on/off/offset and the offset option has
been selected (R)*/
int *ax1pix_img; /* Returns the local axis 1 pixel position (from 1 up
- refers to complete uncompressed image); any
overlay offset is subtracted from the value before
it is returned (W) */
int *ax2pix_img; /* Returns the local axis 2 pixel position (W) */
Return: Status = 0 OK, >0 error
bit 0 set: View-object handle not found
bit 1 set: View handle does not match view object
2.14.2.5 Get selected rectangle - xdl_image_getrect
The routine xdl_image_getrect (xdlf_image_getrect) is used to return the last selected rectangle coordinates in pixels to the calling program. It will normally be called after the return from a call to xdl_get_events (xdlf_get_events) indicates that an image view-object has returned input.
Fortran call:
CALL XDLF_IMAGE_GETRECT (IVH, IAX1PIX1, IAX2PIX1,
+ IAX1PIX2, IAX2PIX2, IVECT, ICOLR, IOV, IERR)
Parameters:
IVH (R) View-object handle (see vh)
IAX1PIX1 (W) Returns 1'st local axis 1 pixel position
(see ax1pix_dn)
IAX2PIX1 (W) Returns 1'st local axis 2 pixel position
(see ax2pix_dn)
IAX1PIX2 (W) Returns 2'nd local axis 1 pixel position
(see ax1pix_up)
IAX2PIX2 (W) Returns 2'nd local axis 2 pixel position
(see ax2pix_up)
IVECT (R) Vector identifier for drawing box at selected
position (1-65535); 0 if no box is to be
drawn (see also description of
xdlf_image_drawvect routine)
ICOLR (R) Vector colour (1 to 6) if needed (see color)
IOV (R) Overlay number 1 or 2 if needed (see ov_num)
IERR (W) Returns status from xdl_image_getrect call
'C' call:
int xdl_image_getrect (vh, ax1pix_dn, ax2pix_dn, ax1pix_up, ax2pix_up,
vect_id, color, ov_num)
Parameters:
int vh; /* View-object handle (R)*/
int *ax1pix_dn; /* Returns the local axis 1 pixel position (from 1 up
- refers to complete uncompressed image) of rectangle
corner where Button1 was pressed (W) */
int *ax2pix_dn; /* Returns the local axis 2 pixel position where Button1
was pressed (W) */
int *ax1pix_up; /* Returns the local axis 1 pixel position (from 1 up
- refers to complete uncompressed image) of rectangle
corner where Button1 was released (W) */
int *ax2pix_up; /* Returns the local axis 2 pixel position where Button1
was released (W) */
int vect_id; /* Vector identifier (1-65535) to draw a box on the
image display at the selected rectangle position;
0 if no box is to be drawn. (see xdl_image_vect) */
int color; /* Overlay colour type 1 to 6; Red, Yellow, Green, Cyan,
Blue, Magenta (by default) if needed*/
int ov_num; /* Overlay number 1 or 2 (R) if needed*/
Return: Status = 0 OK, >0 error
bit 0 set: View-object handle not found
bit 1 set: View handle does not match view object
2.14.2.6 Get display settings - xdl_image_settings
The routine xdl_image_settings (xdlf_image_settings) is used to obtain the current display settings so that they can be used for example for the display of another image.
Fortran call:
CALL XDLF_IMAGE_SETTINGS (IVH, MIN_THR, MAX_THR, MONO_THR,
+ ICONTRAST, ICOLOR_OPT, IOVLY_OPT,
+ IBG_OPT, MAG_OPT, ISHOW_INT, IERR)
Parameters:
IVH (R) View-object handle (see vh)
MIN_THR (W) Returns the minimum scaling threshold
(see min_thr)
MAX_THR (W) Returns the maximum scaling threshold
(see max_thr)
MONO_THR (W) Returns the current threshold for monochome
display 0-63 (see mono_thr)
ICONTRAST (W) Returns the contrast value 1-1024 (see contrast)
ICOLOR_OPT (W) Returns the colour choice option 1-7 for colour,
1-2 for monochrome (see color_opt)
IOVLY_OPT (W) Returns overlay option 1-3 or 1-4 (see ovly_opt)
IBG_OPT (W) Returns the background option 1-3 (see bg_opt)
MAG_OPT (W) Returns the current magnification option 1-7
for colour or 1-10 for monochrome (see mag_opt)
ISHOW_INT (W) Returns flag for whether intensity values are
to be shown on zooming 0-1 (see show_int)
IERR (W) Returns status from xdl_image_settings call
'C' call:
int xdl_image_settings (vh, min_thr, max_thr, mono_thr, contrast,
color_opt, ovly_opt, bg_opt, mag_opt, show_int)
Parameters:
int vh; /* View-object handle (R)*/
int *min_thr; /* Returns the minimum scaling threshold (W) */
int *max_thr; /* Returns the maximum scaling threshold (W) */
int *mono_thr; /* Returns the current threshold for monochome
display 0-63 (W)*/
int *contrast; /* Returns the contrast value 1-1024 (W) */
int *color_opt; /* Returns the colour choice option 1-7 for colour,
1-2 for monochrome (W) */
int *ovly_opt; /* Returns overlay option 1-3 or 1-4 (W) */
int *bg_opt; /* Returns the background option 1-3 (W) */
int *mag_opt; /* Returns the current magnification option 1-7
for colour or 1-10 for monochrome (W) */
int *show_int; /* Returns flag for whether intensity values are to be
shown on zooming 0-1 (W) */
Return: Status = 0 OK, >0 error
bit 0 set: View-object handle not found
bit 1 set: View handle does not match view object
2.14.2.7 Reset current display settings - xdl_image_reset
The routine xdl_image_reset (xdlf_image_reset) is used to set new values for the display settings such as the scaling thresholds, contrast level and colour options.
Fortran call:
CALL XDLF_IMAGE_RESET (IVH, MIN_THR, MAX_THR, MONO_THR,
+ ICONTRAST, ICOLOR_OPT, IOVLY_OPT,
+ IBG_OPT, MAG_OPT, ISHOW_INT, IERR)
Parameters:
IVH (R) View-object handle (see vh)
MIN_THR (R) Sets the minimum scaling threshold (see min_thr)
MAX_THR (R) Sets the maximum scaling threshold (see max_thr)
MONO_THR (R) Sets the current threshold for monochome
display 0-63 (see mono_thr)
ICONTRAST (R) Sets the contrast value 1-1024 (see contrast)
ICOLOR_OPT (R) Sets the colour choice option 1-7 for colour,
1-2 for monochrome (see color_opt)
1 = Black on white
2 = White on black
3 = Yellow if sat.
4 = Colour 1
5 = Colour 2
6 = User defined
7 = Random
IOVLY_OPT (R) Sets overlay option 1-3 or 1-4 (see ovly_opt)
1'st case 1=on, 2=off, 3=offset
2'nd case 1=on, 2=off, 3=ov1 on, 4=ov2 on
IBG_OPT (R) Sets the background option 1-3 (see bg_opt)
1=included, 2=subtracted, 3=background only
MAG_OPT (R) Sets the current magnification option 1-7
for colour or 1-10 for monochrome (see mag_opt)
1=x2, 2=x3, 3=X4, 4=x5, 5=x6, 6=x7, 7=x8
8=x3G, 9=x6G, 10=x9G (monochrome simulated gray)
ISHOW_INT (R) Sets flag for whether intensity values are
to be shown on zooming 0-1 0=no, 1-yes
(see show_int)
IERR (W) Returns status from xdl_image_reset call
'C' call:
int xdl_image_reset (vh, min_thr, max_thr, mono_thr, contrast,
color_opt, ovly_opt, bg_opt, mag_opt, show_int)
Parameters:
int vh; /* View-object handle (R)*/
int min_thr; /* Sets the minimum scaling threshold (ignore if <=
-10,000,000) (R) */
int max_thr; /* Sets the maximum scaling threshold (ignore if <=
-10,000,000 (R) */
int mono_thr; /* Sets the current threshold for monochome
display 0-63 (ignore if < 0) (R)*/
int contrast; /* Sets the contrast value 1-1024 (R) */
int color_opt; /* Sets the colour choice option 1-7
1-7 for colour, 1-2 for monochrome (ignore if < 0)
1 = Black on white
2 = White on black
3 = Yellow if sat.
4 = Colour 1
5 = Colour 2
6 = User defined
7 = Random
(R) */
int ovly_opt; /* Sets overlay option 1-3 (overlay type 1 on
initial call or 1-4 for overlay type 2 on
initial call to xdl_image.
1'st case 1=on, 2=off, 3=offset
2'nd case 1=on, 2=off, 3=ov1 on, 4=ov2 on
(ignore if < 0)
(R) */
int bg_opt; /* Sets the background option 1-3 (ignore if < 0)
1=included, 2=subtracted, 3=background only (R) */
int mag_opt; /* Sets the current magnification option 1-7
for colour or 1-10 for monochrome (ignore if < 0)
1=x2, 2=x3, 3=X4, 4=x5, 5=x6, 6=x7, 7=x8
8=x3G, 9=x6G, 10=x9G (monochrome simulated gray)
(R) */
int show_int; /* Sets flag for whether intensity values are to be
shown on zooming 0-1 0=no, 1=yes (ignore if < 0)
(R) */
Return: Status = 0 OK, >0 error
bit 0 set: View-object handle not found
bit 1 set: View handle does not match view object
2.14.2.8 Set local axis names - xdl_image_axnames
The routine xdl_image_axnames (xdlf_image_axnames) is used to reset the names of the local axes (the default starting values are 'ax1' and 'ax2' for the two axes.
Fortran call:
CALL XDLF_IMAGE_AXNAMES (IVH, XDLSTR(NAME1), LEN1,
+ XDLSTR(NAME2), LEN2, IERR)
Parameters:
IVH (R) View-object handle (see vh)
NAME1 (R) Character string containing the name of the 1'st
local axis (max 4 characters in length)
** Pass address using the XDLSTR function **
LEN1 (R) Length of the name string - must be >0
(cf len1) (max 4 chars)
NAME2 (R) Character string containing the name of the 2'nd
local axis (max 4 characters in length)
** Pass address using the XDLSTR function **
LEN2 (R) Length of the name string - must be >0
(cf len1) (max 4 chars)
IERR (W) Returns status from xdl_image_axnames call
'C' call: int xdl_image_axnames (vh, name1, len1, name2, len2)
Parameters:
int vh; /* View-object handle (R)*/
char *name1; /* Name of 1'st local axis (max 4 chars long) (R)*/
int len1; /* Length of name (may give 0 if a null terminated string
is passed) (R)*/
char *name2; /* Name of 2'nd local axis (max 4 chars long) (R)*/
int len2; /* Length of name (may give 0 if a null terminated string
is passed) (R)*/
Return: Status = 0 OK, >0 error
bit 0 set: View-object handle not found
bit 1 set: View handle does not match view object
2.14.2.9 Display the image now - xdl_image_display_now
The routine xdl_image_display_now (xdlf_image_display_now) is used to display the image. It will normally be used if non-default display settings are required and disp_now (IDISP_NOW) was set to zero on the initial call to xdl_image (xdlf_image)
Fortran call:
CALL XDLF_IMAGE_DISPLAY_NOW (IVH, IERR)
Parameters: IVH (R) View-object handle (see vh) IERR (W) Returns status from xdl_image_display_now call
'C' call: int xdl_image_display_now (vh)
Parameters: int vh; /* View-object handle (R)*/
Return: Status = 0 OK, >0 error
bit 0 set: View-object handle not found
bit 1 set: View handle does not match view object
2.14.2.10 Set background image - xdl_image_background
The routine xdl_image_background (xdlf_image_background) is used to pass a background image to the image view-object. This has the same data order as the original image but is compressed by a factor (bg_cmp (IBG_CMP)) in the direction of both image axes. If bg_typ (IBG) was set to 1 when the xdl_image (xdlf_image) routine was called then the background options will be handled via the background choice menu on the control panel; otherwise the background image will be ignored.
Fortran call:
CALL XDLF_IMAGE_BACKGROUND (IVH, IBGDATA, IBG_CMP, NF_BGOFF)
Parameters:
IVH (R) View-object handle (see vh)
IBGDATA (R) Array holding background image data (same format
and size as for a compressed image as described
in the call to the main xdlf_image routine.)
(e.g. pass as in integer array with the data
packed as needed)
Note: a compressed background image is given
here even if a full image was passed to the
main routine.
(bg_data)
IBG_CMP (R) Compression factor in background image (fast & slow
axes )
NF_BGOFF (R) Offset in pixels between stored rows of background
image (to allow for storage in pre-dimensioned 2-D
arrays.
IERR (W) Returns status from xdl_film_background call
'C' call: int xdl_image_background (vh, bg_data, bg_cmp, nf_bgoff)
Parameters:
int vh; /* View-object handle (R)*/
char * bg_data; /* Background image data; the size of the image is the
size of the compressed image passed to the
xdl_image routine (or formed by it from the full
image). The data format is the same as for the main
image. (R)*/
int bg_cmp; /* Compression factor in background image (fast & slow
axes (R)*/
int nf_bgoff; /* Offset in pixels between stored rows of background
image (to allow for storage in pre-dimensioned 2-D
arrays (R)*/
Return: Status = 0 OK, >0 error
bit 0 set: View-object handle not found
bit 1 set: View handle does not match view object
2.14.2.11 Set a new image - xdl_image_newimg
The routine xdl_film_newimg (xdlf_image_newimg) is used to reset the image in the display to a new image. This image must be of the same type and have the same dimensions as the original image.
Fortran call:
CALL XDLF_IMAGE_NEWIMG (IVH, IMGDATA, IDISP_NOW, IERR)
Parameters:
IVH (R) View-object handle (see vh)
IMGDATA (R) Array holding compressed data (e.g. pass as an
integer array with data packed as needed)
(see imgdata)
IDISP_NOW (R) Display flag =1 display immediately, =0 wait for
XDLF_IMAGE_DISPLAY_NOW call
IERR (W) Returns status from xdl_image_newimg call
'C' call: int xdl_image_newimg (vh, imgdata, disp_now)
Parameters:
int vh; /* View-object handle (R)*/
char *imgdata; /* The new image (see xdl_image call for
full details (R)*/
int disp_now; /* Display now flag =1, =0 wait for
xdl_image_display_now call (R)*/
Return: Status = 0 OK, >0 error
bit 0 set: View-object handle not found
bit 1 set: View handle does not match view object
2.14.2.12 Reset overlay offset values - xdl_image_ovly_offset
The routine xdl_image_ovly_offset (xdlf_image_ovly_offset) is used to reset the amount by which an overlay is offset when the overlay offset option is selected via the image view-object control panel. The default when the image view-object is created is four pixels on the main image display area to the left and down (xoff=-4, yoff=4).
Fortran call:
CALL XDLF_IMAGE_OVLY_OFFSET (IVH, IXOFF, IYOFF, IERR)
Parameters: IVH (R) View-object handle (see vh) IXOFF (R) Overlay x offset (see xoff) IYOFF (R) Overlay y offset (see yoff) IERR (W) Returns status from xdl_image_ovly_offset call
'C' call: int xdl_image_ovly_offset (vh, xoff, yoff)
Parameters:
int vh; /* View-object handle (R)*/
int xoff; /* New x overlay offset (in pixels of main film
display) (R)*/
int yoff; /* New y overlay offset (R) */
Return: Status = 0 OK, >0 error
bit 0 set: View-object handle not found
bit 1 set: View handle does not match view object
2.14.2.13 Reset an overlay colour - xdl_image_set_colour
The routine xdl_image_set_colour (xdlf_image_set_colour) is used to reset one of the 6 colours used for the overlay symbols to a user selected colour or the colour used to indicate the position of a 'frozen' magnifying window.
Fortran call:
CALL XDLF_IMAGE_SET_COLOUR (IVH, ICOLR, IRED, IGREEN,
+ IBLUE, IERR)
Parameters: IVH (R) View-object handle (see vh) ICOLR (R) Overlay colour number (1 to 7) (see icolr) IRED (R) Red component 0 to 65535 (see red) IGREEN (R) Green component 0 to 65535 (see green) IBLUE (R) Blue component 0 to 65535 (see blue) IERR (W) Returns status from xdl_image_set_colour call
'C' call: int xdl_image_set_colour (vh, icolr, red, blue, green)
Parameters:
int vh; /* View-object handle (R)*/
int icolr; /* Overlay colour number 1 to 6 for symbols or 7
for the magnifying window position indicating
box (R)*/
int red; /* Red component 0 to 65535 (R)*/
int green; /* Green component 0 to 65535 (R)*/
int blue; /* Blue component 0 to 65535 (R)*/
Return: Status = 0 OK, >0 error
bit 0 set: View-object handle not found
bit 1 set: View handle does not match view object
2.14.2.14 Reset user defined colour map - xdl_image_set_colormap
The routine xdl_image_set_colormap (xdlf_image_set_colormap) is used to reset the 'user defined' 64 colour colour map used to display the image. The use of the map is selected via the colour choice menu on the image view object. Note that the contrast slider will have no effect when the user defined colour map is selected.
Fortran call:
CALL XDLF_IMAGE_SET_COLORMAP (IVH, IRED, IGREEN,
+ IBLUE, IERR)
Parameters:
IVH (R) View-object handle (see vh)
IRED(64) (R) 64 Red components 0 to 65535 (see red)
IGREEN(64) (R) 64 Green components 0 to 65535 (see green)
IBLUE(64) (R) 64 Blue components 0 to 65535 (see blue)
IERR (W) Returns status from xdl_image_set_colormap
call
'C' call: int xdl_image_set_colormap (vh, red, green, blue)
Parameters: int vh; /* View-object handle (R)*/ int red[]; /* 64 Red components 0 to 65535 (R)*/ int green[]; /* 64 Green components 0 to 65535 (R)*/ int blue[]; /* 64 Blue components 0 to 65535 (R)*/
Return: Status = 0 OK, >0 error
bit 0 set: View-object handle not found
bit 1 set: View handle does not match view object
2.14.2.15 Store and display an overlay symbol - xdl_image_symbol
The routine xdl_image_symbol (xdlf_image_symbol) is used to store details of an overlay symbol and to display that symbol if overlays are currently being displayed. Two sets of overlay symbols may be stored. (If many symbols are to be added then, if possible, use the routine xdl_image_symbols (xdlf_image_symbols) instead)
Fortran call:
CALL XDLF_IMAGE_SYMBOL (IVH, IAX1PIX, IAX2PIX, ISYMB,
+ ICOLR, IOV, IERR)
Parameters:
IVH (R) View-object handle (see vh)
IAX1PIX (R) Local axis 1 pixel position in full image
(see ax1_pixel)
IAX2PIX (R) Local axis 2 pixel position in full image
(see ax2_pixel)
ISYMB (R) Symbol type (see symbol)
ICOLR (R) Symbol colour (1 to 6) (see color)
IOV (R) Overlay number 1 or 2 (see ov_num)
IERR (W) Returns status from xdl_image_symbol call
'C' call: int xdl_image_symbol (vh, ax1_pixel, ax2_pixel, symbol, color, ov_num)
Parameters:
int vh; /* View-object handle (R)*/
int ax1_pixel; /* The local axis 1 pixel position (from 1 up
- refers to complete uncompressed image (R) */
int ax2_pixel; /* The local axis 2 pixel position (R) */
int symbol; /* The symbol type
= 1 to 10 vertical cross - increasing size
1 to 19 pixels
in steps of 2.
= 11 to 20 cross - increasing size 1 to 19 pixels
height.
= 21 to 30 square - increasing size 1 to 19 pixels.
Note: 1, 11 and 21 are single points */
int color; /* Overlay colour type 1 to 6; Red, Yellow, Green, Cyan,
Blue, Magenta (by default)*/
int ov_num; /* Overlay number 1 or 2 (R)*/
Return: Status = 0 OK, >0 error
bit 0 set: View-object handle not found
bit 1 set: View handle does not match view object
bit 2 set: Unable to allocate additional space for
storing the new symbol's details
2.14.2.16 Store and display overlay symbols - xdl_image_symbols
The routine xdl_image_symbols (xdlf_image_symbols) is used to store details of overlay symbols and to display those symbols if overlays are currently being displayed. The symbols are added to an internal symbols list and then sorted. Use this routine when possible if may symbols are to be added rather than using individual calls to xdl_image_symbol (xdlf_image_symbol). Two sets of overlay symbols may be used.
Fortran call:
CALL XDLF_IMAGE_SYMBOLS (IVH, NSYMB, IAX1PIX, IAX2PIX, ISYMB,
+ ICOLR, IOV, NT, IERR)
Parameters:
IVH (R) View-object handle (see vh)
NSYMB (R) No. of symbols to store (see nsymb)
IAX1PIX (R) Array of local axis 1 pixel positions in full
image (NSYMB values) (see ax1_pixel)
IAX2PIX (R) Array of local axis 2 pixel positions in full
image (NSYMB values) (see ax2_pixel)
ISYMB (R) Array of Symbol types or Symbol type as indicated
by NT (see symbol)
ICOLR (R) Array of Symbol colours or Symbol colour as
indicated by NT (1 to 6) (see color)
IOV (R) Array of overlay numbers (1 or 2) or overlay
number as indicated by NT (see ov_num)
NT (R) =1 give a single symbol type, colour and overlay
number
=0 give arrays of NSYMB symbols, colours and overlay
numbers (see nt)
IERR (W) Returns status from xdl_image_symbol call
'C' call:
int xdl_image_symbols (vh, nsymb, ax1_pixel, ax2_pixel, symbol, color,
ov_num, nt)
Parameters:
int vh; /* View-object handle (R)*/
int nsymb; /* The number of symbols to be added */
int ax1_pixel[]; /* Array of local axis 1 pixel positions (from 1 up
- refers to complete uncompressed image) (R) */
int ax2_pixel[]; /* Array of local axis 2 pixel positions (R) */
int symbol[]; /* Array of symbol types (nsymb values or 1 value, see nt)
= 1 to 10 vertical cross - increasing size
1 to 19 pixels
in steps of 2.
= 11 to 20 cross - increasing size 1 to 19 pixels
height.
= 21 to 30 square - increasing size 1 to 19 pixels.
Note: 1, 11 and 21 are single points (R) */
int color[]; /* Array of Overlay colour types (nsymb values or 1 value,
see nt)
1 to 6; Red, Yellow, Green, Cyan,Blue, Magenta
(by default but may be reset) (R)*/
int ov_num[]; /* Array of overlay numbers (1 or 2) (nsymb values or 1
value, see nt) (R)*/
int nt; /* =0 give nsymb values for symbol types and colours
=1 give a single value for the symbol type and colour
and use this for all the symbols being added (R)*/
Return: Status = 0 OK, >0 error
bit 0 set: View-object handle not found
bit 1 set: View handle does not match view object
bit 2 set: Unable to allocate additional space for
storing the new symbol's details
2.14.2.17 Clear overlay symbols - xdl_image_clear_symbols
The routine xdl_image_clear_symbols (xdlf_image_clear_symbols) is used to clear all overlay symbols from the symbols list and from the display.
Fortran call:
CALL XDLF_IMAGE_CLEAR_SYMBOLS (IVH, IERR)
Parameters:
IVH (R) View-object handle (see vh)
IERR (W) Returns status from xdl_image_clear_symbols
call
'C' call: int xdl_image_clear_symbols (vh)
Parameters: int vh; /* View-object handle (R)*/
Return: Status = 0 OK, >0 error
bit 0 set: View-object handle not found
bit 1 set: View handle does not match view object
2.14.2.18 Delete an overlay symbol - xdl_image_del_symbol
The routine xdl_image_del_symbol (xdlf_image_del_symbol) is used to delete an overlay symbol from the symbols list and remove it from the display. If there are many symbols to delete it may be quicker to clear all symbols (xdl_image_clear_symbols (xdlf_image_clear_symbols)) and create a new list using xdl_image_symbols (xdlf_image_symbols)
Fortran call:
CALL XDLF_IMAGE_DEL_SYMBOL (IVH, IAX1PIX, IAX2PIX, ISYMB,
+ ICOLR, IOV, IERR)
Parameters:
IVH (R) View-object handle (see vh)
IAX1PIX (R) Local axis 1 pixel position of symbol (full
image pixel numbering) (see ax1_pixel)
IAX2PIX (R) Local axis 2 pixel position (see ax2_pixel)
ISYMB (R) If > 0, only delete the symbol if it is of the
type ISYMB (see symbol)
ICOLR (R) If > 0, only delete the symbol if it is of the
colour ICOLR (see color)
IOV (R) If > 0, only delete the symbol if it is of the
overlay number IOV (see ov_num)
IERR (W) Returns status from xdl_image_del_symbol call
'C' call:
int xdl_image_del_symbol (vh, ax1_pixel, ax2_pixel, symbol, color,
ov_num)
Parameters:
int vh; /* View-object handle (R)*/
int ax1_pixel; /* Local axis 1 pixel position of the symbol (from 1 up
- refers to complete uncompressed image) (R)*/
int ax2_pixel; /* Local axis 2 pixel position of the symbol (from 1 up
- refers to complete uncompressed image) (R)*/
int symbol; /* If > 0 then only delete the symbol if it is of the
type 'symbol' (see xdl_image_symbol routine for
details of symbol types) (R)*/
int color; /* If > 0 then only delete the symbol if it is of the
colour 'color' (see xdl_image_symbol routine
for details of the colour types) (R)*/
int ov_num; /* If > 0 then only delete the symbol if it is of
the overlay number ov_num (1 or 2) (R)*/
Return: Status = 0 OK, >0 error
bit 0 set: View-object handle not found
bit 1 set: View handle does not match view object
bit 2 set; Symbol not found
2.14.2.19 Store and display an overlay vector - xdl_image_vect
The routine xdl_image_vect (xdlf_image_vect) is used to store details of an overlay vector and to display that vector if overlays are currently being displayed. Two sets of overlay vectors may be stored. The user supplies a vector identifier number for a vector and this is used to identify a vector or set of vectors for deletion if required.
Fortran call:
CALL XDLF_IMAGE_VECT (IVH, IVECT, IAX1PIX1, IAX2PIX1,
+ IAX1PIX2, IAX2PIX2,
+ ICOLR, IOV, MAGUPD, IERR)
Parameters:
IVH (R) View-object handle (see vh)
IVECT (R) User selected number to identify vector
(0-65535). The same number may be used
for more than one vector to identify a
set of vectors (see vect_id)
IAX1PIX1 (R) Local axis 1 start pixel position in full image
(see ax1_1_pixel)
IAX2PIX1 (R) Local axis 2 start pixel position in full image
(see ax2_1_pixel)
IAX1PIX2 (R) Local axis 1 end pixel position in full image
(see ax2_2_pixel)
IAX2PIX2 (R) Local axis 2 end pixel position in full image
(see ax2_2_pixel)
ICOLR (R) Vector colour (1 to 6) (see color)
IOV (R) Overlay number 1 or 2 (see ov_num)
MAGUPD (R) =1 Update magnifying window and flush X buffer
after drawing vector,
=0 do not (see magw_upd)
IERR (W) Returns status from xdl_image_vect call
'C' call:
int xdl_image_vect (vh, vect_id, ax1_1_pixel, ax2_1_pixel,
ax1_2_pixel, ax2_2_pixel, color, ov_num, magw_upd)
Parameters:
int vh; /* View-object handle (R)*/
int vect_id; /* User selected number to identify vector (0-65535).
The same number may be used for more than one vector to
identify a set of vectors (R)*/
int ax1_1_pixel; /* The vector start local axis 1 pixel position (from 1
up - refers to complete uncompressed image (R) */
int ax2_1_pixel; /* The vector start local axis 2 pixel position (R) */
int ax1_2_pixel; /* The vector end local axis 1 pixel position (R) */
int ax2_2_pixel; /* The vector end local axis 2 pixel position (R) */
int color; /* Overlay colour type 1 to 6; Red, Yellow, Green, Cyan,
Blue, Magenta (by default)*/
int ov_num; /* Overlay number 1 or 2 (R)*/
int magw_upd; /* =1 Update the magnifying window and flush X buffer
after drawing the vector; this should be used
when a single vector is drawn or when the final
vector of a series of vectors is drawn.
=0 Do not; this enables a series of vectors to be
drawn much more rapidly; it should be used when
a series of vectors is to be drawn for all but
the final vector (R)*/
Return: Status = 0 OK, >0 error
bit 0 set: View-object handle not found
bit 1 set: View handle does not match view object
bit 2 set: Unable to allocate additional space for
storing the new vector's details
2.14.2.20 Store and display overlay vectors - xdl_image_vects
The routine xdl_image_vects (xdlf_image_vects) is used to store details of a set of overlay vectors and to display those vectors if overlays are currently being displayed. Two sets of overlay vectors may be stored. The user supplies a vector identifier set number for the vectors and this is used to identify the set of vectors for deletion if required.
Fortran call:
CALL XDLF_IMAGE_VECTS (IVH, IVECT, NUM_VECT, IAX1PIX1, IAX2PIX1,
+ IAX1PIX2, IAX2PIX2,
+ ICOLR, IOV, MAGUPD, IERR)
Parameters:
IVH (R) View-object handle (see vh)
IVECT (R) User selected number to identify vector set
(0-65535). (see vect_id)
NUM_VECT (R) The number of vectors
IAX1PIX1 (R) Local axis 1 start pixel positions in full image
(see ax1_1_pixel) (array of NUM_VECT values)
IAX2PIX1 (R) Local axis 2 start pixel positions in full image
(see ax2_1_pixel) (array of NUM_VECT values)
IAX1PIX2 (R) Local axis 1 end pixel positions in full image
(see ax2_2_pixel) (array of NUM_VECT values)
IAX2PIX2 (R) Local axis 2 end pixel positions in full image
(see ax2_2_pixel) (array of NUM_VECT values)
ICOLR (R) Vector colour (1 to 6) (see color)
IOV (R) Overlay number 1 or 2 (see ov_num)
MAGUPD (R) =1 Update magnifying window after drawing vector,
=0 do not (see magw_upd)
IERR (W) Returns status from xdl_image_vects call
'C' call:
int xdl_image_vects (vh, vect_id, num_vect, ax1_1_pixel, ax2_1_pixel,
ax1_2_pixel, ax2_2_pixel, color, ov_num, magw_upd)
Parameters:
int vh; /* View-object handle (R)*/
int vect_id; /* User selected number to identify vector (0-65535).
The same number may be used for more than one vector to
identify a set of vectors (R)*/
int num_vect; /* Number of vectors to be added */
int *ax1_1_pixel; /* The vector start local axis 1 pixel positions (from 1
up - refers to complete uncompressed image
(array of num_vect values (R) */
int *ax2_1_pixel; /* The vector start local axis 2 pixel positions
(array of num_vect values (R) */
int *ax1_2_pixel; /* The vector end local axis 1 pixel positions
(array of num_vect values (R) */
int *ax2_2_pixel; /* The vector end local axis 2 pixel positions
(array of num_vect values (R) */
int color; /* Overlay colour type 1 to 6; Red, Yellow, Green, Cyan,
Blue, Magenta (by default)*/
int ov_num; /* Overlay number 1 or 2 (R)*/
int magw_upd; /* =1 Update the magnifying window after drawing the
vectors; this should be used when all the
required vectors have been defined.
=0 Do not (R) */
Return: Status = 0 OK, >0 error
bit 0 set: View-object handle not found
bit 1 set: View handle does not match view object
bit 2 set: Unable to allocate additional space for
storing the new vector's details
2.14.2.21 Store and display overlay vectors - xdl_image_vects_pos
The routine xdl_image_vects_pos (xdlf_image_vects_pos) is used to store details of a set of overlay vectors and to display those vectors if overlays are currently being displayed. Two sets of overlay vectors may be stored. The user supplies a vector identifier set number for the vectors and this is used to identify the set of vectors for deletion if required. In contrast to xdl_image_vects (xdlf_image_vects) which always positions the vector ends at the centre of a displayed pixel, this routine allows the user some further options for positioning the vector ends with respect to the displayed pixels.
Fortran call:
CALL XDLF_IMAGE_VECTS_POS (IVH, IVECT, NUM_VECT,
+ IAX1PIX1, IAX2PIX1,
+ IAX1PIX2, IAX2PIX2,
+ IAX1POS1, IAX2POS1,
+ IAX1POS2, IAX2POS2,
+ ICOLR, IOV, MAGUPD, IERR)
Parameters:
IVH (R) View-object handle (see vh)
IVECT (R) User selected number to identify vector set
(0-65535). (see vect_id)
NUM_VECT (R) The number of vectors
IAX1PIX1 (R) Local axis 1 start pixel positions in full image
(see ax1_1_pixel) (array of NUM_VECT values)
IAX2PIX1 (R) Local axis 2 start pixel positions in full image
(see ax2_1_pixel) (array of NUM_VECT values)
IAX1PIX2 (R) Local axis 1 end pixel positions in full image
(see ax2_2_pixel) (array of NUM_VECT values)
IAX2PIX2 (R) Local axis 2 end pixel positions in full image
(see ax2_2_pixel) (array of NUM_VECT values)
IAX1POS1 (R) Position option flags for local axis 1 start pixels
(array of NUM_VECT values)
IAX2POS1 (R) Position option flags for local axis 2 start pixels
(array of NUM_VECT values)
IAX1POS2 (R) Position option flags for local axis 1 end pixels
(array of NUM_VECT values)
IAX2POS2 (R) Position option flags for local axis 2 end pixels
(array of NUM_VECT values)
ICOLR (R) Vector colour (1 to 6) (see color)
IOV (R) Overlay number 1 or 2 (see ov_num)
MAGUPD (R) =1 Update magnifying window after drawing vector,
=0 do not (see magw_upd)
IERR (W) Returns status from xdl_image_vects_pos call
Note: Position flags = 0 Centre of displayed pixel
=-1 Low side of displayed pixel
=+1 High side of displayed pixel
=-2 Just outside low side
=+2 Just outside high side
'C' call:
int xdl_image_vects_pos (vh, vect_id, num_vect, ax1_1_pixel, ax2_1_pixel,
ax1_2_pixel, ax2_2_pixel, ax1_1_pos, ax2_1_pos,
ax1_2_pos, ax2_2_pos, color, ov_num, magw_upd)
Parameters:
int vh; /* View-object handle (R)*/
int vect_id; /* User selected number to identify vector (0-65535).
The same number may be used for more than one vector to
identify a set of vectors (R)*/
int num_vect; /* Number of vectors to be added */
int *ax1_1_pixel; /* The vector start local axis 1 pixel positions (from 1
up - refers to complete uncompressed image
(array of num_vect values (R) */
int *ax2_1_pixel; /* The vector start local axis 2 pixel positions
(array of num_vect values (R) */
int *ax1_2_pixel; /* The vector end local axis 1 pixel positions
(array of num_vect values (R) */
int *ax2_2_pixel; /* The vector end local axis 2 pixel positions
(array of num_vect values (R) */
int *ax1_1_pos; /* Position option flags for local axis 1 start pixels
(array of num_vect values (R) */
int *ax2_1_pos; /* Position option flags for local axis 2 start pixels
(array of num_vect values (R) */
int *ax1_2_pos; /* Position option flags for local axis 1 end pixels
(array of num_vect values (R) */
int *ax2_2_pos; /* Position option flags for local axis 2 end pixels
(array of num_vect values (R) */
int color; /* Overlay colour type 1 to 6; Red, Yellow, Green, Cyan,
Blue, Magenta (by default)*/
int ov_num; /* Overlay number 1 or 2 (R)*/
int magw_upd; /* =1 Update the magnifying window after drawing the
vectors; this should be used when all the
required vectors have been defined.
=0 Do not (R) */
/* Note: Position flags = 0 Centre of displayed pixel
=-1 Low side of displayed pixel
=+1 High side of displayed pixel
=-2 Just outside low side
=+2 Just outside high side */
Return: Status = 0 OK, >0 error
bit 0 set: View-object handle not found
bit 1 set: View handle does not match view object
bit 2 set: Unable to allocate additional space for
storing the new vector's details
2.14.2.22 Store and display overlay boxes - xdl_image_boxes
The routine xdl_image_boxes (xdlf_image_boxes) is used to store details of a set of overlay boxes surrounding a rectangle of pixels and to display those boxes if overlays are currently being displayed. The routine saves each box as a set of vectors (see also xdl_image_vect and xdlf_image_vect etc.). The user supplies a vector identifier set number for the box vectors and this is used to identify the set of vectors for deletion if required.
Fortran call:
CALL XDLF_IMAGE_BOXES (IVH, IVECT, NUM_BOX, IAX1PIX1, IAX2PIX1,
+ IAX1PIX2, IAX2PIX2, IPOS,
+ ICOLR, IOV, MAGUPD, IERR)
Parameters:
IVH (R) View-object handle (see vh)
IVECT (R) User selected number to identify vector set associated
with the boxes (0-65535). (see vect_id)
NUM_BOX (R) The number of boxes
IAX1PIX1 (R) Local axis 1 start corner pixel positions in full image
(see ax1_1_pixel) (array of NUM_BOX values)
IAX2PIX1 (R) Local axis 2 start corner pixel positions in full image
(see ax2_1_pixel) (array of NUM_BOX values)
IAX1PIX2 (R) Local axis 1 end corner pixel positions in full image
(see ax2_2_pixel) (array of NUM_BOX values)
IAX2PIX2 (R) Local axis 2 end corner pixel positions in full image
(see ax2_2_pixel) (array of NUM_BOX values)
IPOS (R) = 1 position just within pixel boundaries
= 2 position just outside pixel boundaries
ICOLR (R) Vector colour (1 to 6) (see color)
IOV (R) Overlay number 1 or 2 (see ov_num)
MAGUPD (R) =1 Update magnifying window after drawing vector,
=0 do not (see magw_upd)
IERR (W) Returns status from xdl_image_boxes call
'C' call:
int xdl_image_boxes (vh, vect_id, num_box, ax1_1_pixel, ax2_1_pixel,
ax1_2_pixel, ax2_2_pixel, ipos,
color, ov_num, magw_upd)
Parameters:
int vh; /* View-object handle (R)*/
int vect_id; /* User selected number to identify vector (0-65535).
The same number may be used for more than one vector to
identify a set of vectors (R)*/
int num_box; /* Number of boxes to be added */
int *ax1_1_pixel; /* The vector start corner local axis 1 pixel positions
(from 1 up - refers to complete uncompressed image
(array of num_box values (R) */
int *ax2_1_pixel; /* The vector startcorner local axis 2 pixel positions
(array of num_box values (R) */
int *ax1_2_pixel; /* The vector end corner local axis 1 pixel positions
(array of num_box values (R) */
int *ax2_2_pixel; /* The vector end corner local axis 2 pixel positions
(array of num_box values (R) */
int ipos; /* = 1 position just within pixel boundaries
= 2 position just outside pixel boundaries (R) */
int color; /* Overlay colour type 1 to 6; Red, Yellow, Green, Cyan,
Blue, Magenta (by default)*/
int ov_num; /* Overlay number 1 or 2 (R)*/
int magw_upd; /* =1 Update the magnifying window after drawing the
boxes; this should be used when all the
required boxes have been defined.
=0 Do not (R) */
Return: Status = 0 OK, >0 error
bit 0 set: View-object handle not found
bit 1 set: View handle does not match view object
bit 2 set: Unable to allocate additional space for
storing the new vector's details
2.14.2.23 Clear overlay vectors - xdl_image_clear_vectors
The routine xdl_image_clear_vects (xdlf_image_clear_vects) is used to clear all overlay vectors from the vectors list and from the display.
Fortran call:
CALL XDLF_IMAGE_CLEAR_VECTS (IVH, IERR)
Parameters:
IVH (R) View-object handle (see vh)
IERR (W) Returns status from xdl_image_clear_vects
call
'C' call: int xdl_image_clear_vects (vh)
Parameters: int vh; /* View-object handle (R)*/
Return: Status = 0 OK, >0 error
bit 0 set: View-object handle not found
bit 1 set: View handle does not match view object
2.14.2.24 Delete an overlay vector - xdl_image_del_vect
The routine xdl_image_del_vect (xdlf_image_del_vect) is used to delete an overlay vector (or set of vectors with a common vector identifier) from the vectors list and remove it (them) from the display. If there are many vectors to delete it may be quicker to clear all vectors (xdl_image_clear_vects (xdlf_image_clear_vects)) and create a new list using xdl_image_vect (xdlf_image_vect)
Fortran call:
CALL XDLF_IMAGE_DEL_VECT (IVH, IVECT, IERR)
Parameters:
IVH (R) View-object handle (see vh)
IVECT (R) The vector identifier of the vector or set of
vectors to be deleted (see vect_id)
IERR (W) Returns status from xdl_image_del_vect call
'C' call: int xdl_image_del_vect (vh, vect_id)
Parameters:
int vh; /* View-object handle (R)*/
int vect_id; /* Vector identifier for the vector or set of vectors
to be deleted (R) */
Return: Status = 0 OK, >0 error
bit 0 set: View-object handle not found
bit 1 set: View handle does not match view object
bit 2 set; Vector not found
2.14.2.25 Output a text string - xdl_image_text
The routine xdl_image_text (xdlf_image_text) is used to output a text string to the main display area.
Fortran call:
CALL XDLF_IMAGE_TEXT (IVH, ITEXT, IAX1PIXEL, IAX2PIXEL,
+ XDLSTR(STRING), LEN, ICOLOR, IFONT,
+ IBOLD, IOV_NUM, IERR)
Parameters:
IVH (R) View-object handle (see vh)
ITEXT (R) User selected text string identifier (used
to identify a string or set of strings for
deletion) (0-65535)
IAX1PIXEL (R) Pixel position wrt. local axis 1 for start of text
string output
IAX2PIXEL (R) Pixel position wrt. local axis 2 for start of text
string output
STRING (R) The text string
** Pass address using the XDLSTR function **
LEN (R) The length of the string; must be > 0 (cf len)
ICOLOR (R) Overlay colour type =0 for black or 1 to 6; Red,
Yellow, Green, Cyan, Blue, Magenta (by default)
IFONT (R) Font no. 1-5 very-small, small, medium, large,
very-large
IBOLD (R) = 0 normal text, =1 bold text
IOV_NUM (R) Overlay number 1 or 2
IERR (W) Returns status from xdl_image_text call
'C' call:
int xdl_image_text (vh, text_id, ax1_pixel, ax2_pixel, string, len,
color, font_type, bold, ov_num)
Parameters:
int vh; /* View-object handle (R)*/
int text_id; /* User selected text string identifier (used
to identify a string or set of strings for
deletion) (0-20000) (R) */
int ax1_pixel; /* Pixel position wrt. local axis 1 for start of text
string output (R)*/
int ax2_pixel; /* Pixel position wrt. local axis 2 for start of text
string output (R)*/
char * string; /* The text string */
int len; /* The length of the text string; may give 0 if the
string is null terminated (R)*/
int color; /* Overlay colour type =0 for black or 1 to 6; Red,
Yellow, Green, Cyan, Blue, Magenta (by default)*/
int font_type; /* Font type number 1-5, very-small, small, medium,
large, very-large (R)*/
int bold; /* =0 normal text, =1 bold text */
int ov_num; /* Overlay number 1 or 2 (R)*/
Return: Status = 0 OK, >0 error
bit 0 set: View-object handle not found
bit 1 set: View handle does not match view object
2.14.2.26 Delete a text string - xdl_image_del_text
The routine xdl_image_del_text (xdlf_image_del_text) is used to delete an overlay text string (or set of text strings with a common text identifier) from the text strings list and remove it (them) from the display. If there are many text strings to delete it may be quicker to clear all the text strings (xdl_image_clear_text (xdlf_image_clear_text)) and create a new set using xdl_image_text (xdlf_image_text)
Fortran call:
CALL XDLF_IMAGE_DEL_TEXT(IVH, ITEXT, IERR)
Parameters:
IVH (R) View-object handle (see vh)
ITEXT (R) The text string identifier of the text string
or set of text strings to be deleted (see text_id)
IERR (W) Returns status from xdl_image_del_text call
'C' call: int xdl_image_del_text (vh, text_id)
Parameters:
int vh; /* View-object handle (R)*/
int text_id; /* Text identifier for the text string or set of text
strings to be deleted (R) */
Return: Status = 0 OK, >0 error
bit 0 set: View-object handle not found
bit 1 set: View handle does not match view object
bit 2 set; Vector not found
2.14.2.27 Clear all text strings - xdl_image_clear_text
The routine xdl_image_clear_text (xdlf_image_clear_text) is used to clear (delete) all text strings which were previously output to the main display window.
Fortran call:
CALL XDLF_IMAGE_CLEAR_TEXT (IVH, IERR)
Parameters: IVH (R) View-object handle (see vh) IERR (W) Returns status from xdl_image_clear_text call
'C' call: int xdl_image_clear_text (vh)
Parameters: int vh; /* View-object handle (R)*/
Return: Status = 0 OK, >0 error
bit 0 set: View-object handle not found
bit 1 set: View handle does not match view object
2.14.2.28 Reset active strip message - xdl_image_input_message
The routine xdl_image_input_message (xdlf_image_input_message) is used to reset the message which will appear in the active strip when a pixel position or selected rectangle is to be input. When the image view-object is created, the default message is 'Input spot positions'.
Fortran call:
CALL XDLF_IMAGE_INPUT_MESSAGE (IVH, XDLSTR(MESSAGE),
+ LEN, IERR)
Parameters:
IVH (R) View-object handle (see vh)
MESSAGE (R) Character string containing the message
(see message)
** Pass address using the XDLSTR function **
LEN (R) Length of the message string - must be >0
(cf len) (max 60 chars)
IERR (W) Returns status from xdl_image_input_message
call
'C' call: int xdl_image_input_message (vh, message, len)
Parameters:
int vh; /* View-object handle (R)*/
char *message; /* Message string (max of 60 chars long) (R)*/
int len; /* Length of the message string; if 0 then length
will be found assuming a null terminated string
(R)*/
Return: Status = 0 OK, >0 error
bit 0 set: View-object handle not found
bit 1 set: View handle does not match view object
2.14.2.29 Calculate the size requirements - xdl_image_getsize
The routine xdl_image_getsize (xdlf_image_getsize) is used to calculate the size of an image view-object given the size of the image to be displayed.
Fortran call:
CALL XDLF_IMAGE_GETSIZE (NREQ_AX1, NREQ_AX2, IORDER, JORDER,
NCMP, IWIDTH, IHEIGHT)
Parameters:
NREQ_AX1 (R) Section size along local axis 1 (see nreq_ax1)
NREQ_AX2 (R) Section size along local axis 2 (see nreq_ax1)
IORDER (R) Image data order wrt. local axes (1-8)
(see XDLF_IMAGE routine)
JORDER (R) Display axis order wrt. local axes (1-8)
(see XDLF_IMAGE routine)
NCMP (R) No. of pixels compressed into 1 pixel
along each axis
IWIDTH (W) Returns the width required (see w)
IHEIGHT (W) Returns the height required (see h)
'C' call: void xdl_image_getsize (nreq_ax1, nreq_ax2, iorder, jorder, ncmp, w, h)
Parameters:
int nreq_ax1; /* Section size along local axis 1 (R) */
int nreq_ax2; /* Section size along local axis 2 (R) */
int iorder; /* Image data order wrt. local axes (1-8)
(see xdl_image routine) (R)*/
int jorder; /* Display axis order wrt. local axes (1-8)
(see xdl_image routine) (R)*/
int ncmp; /* No. of pixels compressed into 1 pixel
along each axis */
int *w; /* Returns the width required (W)*/
int *h; /* Returns the height required (W)*/
Return: None
John W. Campbell
CCLRC Daresbury Laboratory
Last update 4 Feb 1998