PHOTO_READ Function
Reads image files or a series of image files and returns an image associative array or a list array containing the image associative arrays.
 
note
The PHOTO routines are only available on 64-bit PV-WAVE.
Usage
image = PHOTO_READ(filename)
Input Parameters
filename — A string or string array 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.
 
note
If filename is a string array, the Series keyword must be set.
For more information on creating a string array containing the names of all files matching a specified file description, please see the FINDFILE Function.
Keywords
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 read with PHOTO_READ 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 sub-images one at a time.
File_Type — A string specifying the default file type. Valid values are:
 
BMP
JPG
PNG
TIF
DICM
MIFF
SUN
XWD
GIF
PCD
TGA
XPM
JPEG
PCX
TIFF
XBM
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' or 'plane' — The RGB pixel array arrangement is (xy3) for 3 image-interleaved channels of x-by-y pixels.
'row' or 'line' — The RGB pixel array arrangement is (x3y) for 3 row-interleaved channels of x-by-y pixels.
'pixel' or 'none' — The RGB pixel array arrangement is (3xy) 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.
Invalid — (Output) Returns a PV-WAVE variable indicating success or failure when reading a set of images with the Series keyword.
Possible values are:
*–1 — All images successfully read.
*INT array — One or more images could not be read. The INT array contains the indices of the unread images in the returned LIST of images.
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.
ROI — Array, specifying the region of interest, in pixels, to extract from an image file. ROI = [x_pos, y_pos, num_x, num_y]
Series — If set, PHOTO_READ returns a list array containing the image associative arrays matching the string array input for filename. Images in the string array must be of the same width, height, and class.
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 or a list of image associative arrays. The status field contains a value indicating the success or failure of the function.
*< 0 — Indicates an error reading the file or a bad file type.
*0 — Indicates a successful read.
Discussion
Refer to the PHOTO_CREATE Function for detailed information on the structure of the image associative array.
 
note
When you read a DICOM file with PHOTO_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.
Table 13-4: File Name Formats for PHOTO lists the file formats that you can read and write using PHOTO_READ and PHOTO_WRITE functions, respectively.
 
File Name Formats for PHOTO
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 sub-images one at a time. 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
 
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.
* PV-WAVE is based in part on the work of the Independent JPEG Group.
Most image files have an encoded ID number to identify the file format. When PHOTO_READ reads an image file, it determines the type of file according to the rules of precedence used by the function PHOTO_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 PHOTO_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 PHOTO_WRITE Function.
Example 1
; Reads the file teluride24.jpg and returns an
; image associative array.
 
 teluride = PHOTO_READ(!Dir + '/demo/gallery3/data/teluride24.jpg')
Example 2
; Reads the sorted series of files IM-0042-*.tif in the
; data directory. Returns a list array containing the  
; image associative arrays.
 
CD, !Dir + '/demo/gallery3/data/', Current=curr_dir
filenames = FINDFILE('IM-0042*.tif')
filenames = SORTDIM(filenames,0)
image = PHOTO_READ(filenames, /Series)
CD, curr_dir
Example 3
; Reads and displays the series of files IM-0042-*.tif in the  
; data directory. Returns a list array containing the image 
; associative arrays and displays the reversed results 
; with a 0.5 second frame-to-frame delay.
 
CD, !Dir + '/demo/gallery3/data/', Current=curr_dir
filenames = FINDFILE('IM-0042*.tif')
filenames = REVERSE(SORTDIM(filenames,0), 1)
image = PHOTO_READ(filenames, /Series)
CD, curr_dir
PHOTO_DISPLAY, image, /Series, Delay=0.5
Example 4
; This example demonstrates the use of the Invalid keyword to 
; identify and locate images which were not successfully read.
 
CD, !Dir + '/demo/gallery3/data/', Current=curr_dir
filenames = FINDFILE('IM-0042*.tif')
filenames = REVERSE(SORTDIM(filenames,0), 1)
image = PHOTO_READ(filenames, /Series, Invalid=outvar)
 
; All the images were read successfully so Invalid returns a -1.
 
INFO, outvar
 
; PV-WAVE prints:
; OUTVAR INT = -1
 
; Put two unreadable files in the list of filenames at positions 4 
; and 7.
 
filenames(4) = "doesntExist.tif"
filenames(7) = "doesntExistEither.tif"
image = PHOTO_READ(filenames, /Series, Invalid=outvar, Quiet=3)
INFO, outvar & PM, outvar
 
; PV-WAVE prints
; OUTVAR INT = Array(2)
;      4
;      7
 
INFO, /Full, image(outvar)
 
; PV-WAVE prints
; <Expression> LIST = List(2)
;      AS. ARR = Associative Array(2)
;           status LONG = -9
;           comments STRING = 'Unable to read file: doesntExist.tif'
;      AS. ARR = Associative Array(2)
;           status LONG = -9
;          comments STRING = 'Unable to read file: doesntExistEither.tif'
Example 5
; Reads the file dna.miff and returns an
; image associative array with a ROI extracted.
 
dna = PHOTO_READ(!Dir + '/demo/gallery3/data/dna.miff', ROI=[600,400,100,100])
See Also
System Variables: !Quiet