Reference Guide > I–L Routines > IMAGE_READ Function
  
IMAGE_READ Function
Reads an image file and returns an image associative array.
 
note
If you have 64-bit PV-WAVE and need to read and write images up to 32-bits without constraints on data size, use the PHOTO OPI routines.
Usage
image = IMAGE_READ(filename)
Input Parameters
filename—A string containing the pathname and filename of an image file. System variables/logicals and special characters recognized by the operating system shell can be used in the path.
Keywords
 
note
If File_Type is TIFF16, all other keywords are ignored.
All_Subimages—If set, all subimages in the file are read and the Img_Count keyword is ignored. The first subimage in the file is read first, unless the Sub_Img keyword is also specified.
 
note
Multiple images being read with the IMAGE_READ function must all be of the same height, width, and class. If a file contains images of different heights, widths, and/or classes, use the Sub_Img option to read a sub-image one at a time.
Cmap_Compress—If set, and the colormap in the image file has unused entries, IMAGE_READ compresses the colormap to the minimum size and re-maps the pixel array.
File_Type—A string specifying the default file type. Valid values are:
 
BMP
MIFF
TGA
XWD
DICM
PCD
TIFF
XPM
GIF
PCX
TIFF16
XBM
JPEG
PNG
TIF
 
JPG
SUN
GEOTIFF
 
See the Discussion section for further details about these image types.
Intleave—A scalar string indicating the desired type of interleaving of 3D image arrays. (Default: pixel)
Valid strings and the corresponding interleaving methods are:
'image'—The RGB pixel array arrangement is (x, y, 3) for 3 image-interleaved channels of x-by-y pixels.
'row'—The RGB pixel array arrangement is (x, 3, y) for 3 row-interleaved channels of x-by-y pixels.
'pixel'—The RGB pixel array arrangement is (3, x, y) for 3 pixel-interleaved channels of x-by-y pixels.
Img_Count—An integer specifying the number of images to read from an array of images.
 
note
The Img_Count keyword is ignored if the All_Subimages keyword is set.
Quiet—Suppresses successive levels of error messages, depending on the value set. This keyword accepts the same integer values used with the system variable !Quiet.
Sub_Img—The index number (integer) of the first image to read from an array of images. (Default: 0, the first image)
 
note
If Sub_Img is used to request a subimage that is not in the image file, the status key of the returned image associative array is set to a negative number.
Verbose—If nonzero, any available information about the file is printed to the screen.
Returned Value
image—An image associative array.
Discussion
Refer to the IMAGE_CREATE function for detailed information on the structure of the image associative array.
 
note
When you read a DICOM file with IMAGE_READ, PV-WAVE converts the hexadecimal DICOM tags to a human-readable format and stores them in a string array in the ’comments’ key with the format (####,####) Value.
File Name Formats for IMAGE lists the file formats that you can read and write using IMAGE_READ and IMAGE_WRITE functions, respectively.
 
Table 10-4: File Name Formats for IMAGE
File type
Read/Write
Notes
BMP
RW
The BMP format currently supported for writing is version 4.
DICM
RW
Uses Sub_Img option to read a sub-image one at a time. All_Subimages option is not supported. Files read with the .dcm extension will have the File_Type set to 'DICM'.
GIF
RW
 
JPEG
JPG
RW
If your image associative array does not contain a colormap, the 2D image pixel array is preserved and a greyscale color map is added.
MIFF
RW
 
PCD
R
 
PCX
RW
 
PNG
RW
 
SUN
RW
 
TGA
RW
 
TIFF
TIF
RW
If the File_Type keyword is set to ‘TIFF16’, the pixels contained in the returned image associative array are LONGs instead of BYTEs. 16-bit TIFFs must have a PhotometricInterpretation tag value of 0 or 1 (MINISWHITE or MINISBLACK) to import properly. To display a 16-bit TIFF image, use TVSCL, image(‘pixels’), not IMAGE_DISPLAY. If the PhotometricInterpretation tag value is 1 and the image is displayed reversed, use the following statement to correct the pixel array:
image('pixels') = ROTATE(image('pixels') , 7)
GEOTIFF
R
 
XWD
RW
Not supported on Windows.
XPM
R
Not supported on Windows.
Converted to 24-bit direct color on read/write. (NOTE: In order to read an XPM file, the DISPLAY environment variable must be set.)
XBM
R
Reduces the image to monochrome (black and white) on write.
Most image files have an encoded ID number to identify the file format. When IMAGE_READ reads an image file, it determines the type of file according to the rules of precedence used by the function IMAGE_QUERY_FILE.
 
note
File type TGA does not have an encoded ID number. To read this type of file you must specify the File_type keyword or filename must have a .tga suffix.
If at least the first requested subimage in the image file is available, but the number of requested images exceeds the highest subimage number in the file, a warning message is displayed and the number of images in the file is returned in the img_count key of the returned image associative array.
When you read a DICOM file with IMAGE_READ, PV-WAVE converts the DICOM tags to a human-readable format and stores them in a string array in the ’comments’ key with the format (####,####) Value. PV-WAVE converts this string array back, updating the default DICOM tags to match the current status of the image, when you write the image with the IMAGE_WRITE Function.
Example 1
; Reads the file veggies.jpg and returns the
; image associative array. 
veggies = IMAGE_READ(!Dir + '/demo/gallery3/data/veggies.jpg')
Example 2
; This example shows how to read a TGA image file which has been
; saved as 'usa_map.tga.txt'. Since the filename extension does
; not reflect the correct image type the File_Type keyword is
; required to specify that this is a TGA file.
imagefile = !Data_Dir + '/usa_map.tga.txt'
usa_map = IMAGE_READ(imagefile, File_Type='TGA')
See Also
IMAGE_CREATE, IMAGE_DISPLAY, IMAGE_WRITE, DICM_TAG_INFO, TVSCL
System Variables:  !Quiet
Version 2017.0
Copyright © 2017, Rogue Wave Software, Inc. All Rights Reserved.