IMAGE_READ Function

Reads an image file and returns an image associative array.

Tip: 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.

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')