IMAGE_WRITE Function

Reference Guide > I–L Routines > IMAGE_WRITE Function

Writes the contents of a PV-WAVE image associative array to a file in the specified image format.

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

status = IMAGE_WRITE(filename, image)

Input Parameters

filename—A string specifying the pathname and filename of the image file to write. This parameter can also be a null string (see Discussion).

image—An image associative array.

Returned Value

status—A value indicating the success or failure of the function.

< 0—Indicates an error, such as an invalid input array. An informational message describing the error is also output to the screen.

0—Indicates a successful write.

Keywords

Compress—If zero, and if the requested image file type allows compression, the image file is written in compressed form. (See Discussion.)

File_type—A string specifying an image file type. Valid values are:

BMP	MIFF	TGA	XWD
DICM	PCD	TIFF	XPM
GIF	PCX	TIFF16	XBM
JPEG	PNG	TIF
JPG	SUN	GEOTIFF

Refer to File Name Formats for IMAGE for more information about the valid image file types.

MapColors—When this keyword is set and a colormap is present in the image associative array PV-WAVE maps the colormap into the pixel array when it writes the image out, potentially changing the pixel data. This affects only 24-bit RGB images. By default, the colormap in the image associative array is ignored when 24-bit RGB images are written out.

Overwrite—If the specified file already exists, overwrite it.

Quality—Sets the quality level of JPEG compression. (Default: 100)

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.

Verbose—If nonzero, information about the written image is displayed.

Discussion

Before writing a file, the IMAGE_WRITE function checks to make sure that the input array is a valid image associative array, and that the keys of the array contain data consistent with the expected values. Refer to the IMAGE_CREATE function for detailed information on the structure of the image associative array.

File Name Formats for IMAGE lists file formats that you can write and read using the IMAGE_WRITE and IMAGE_READ functions, respectively. The table also shows the conversions that are performed on particular file types.

note	The input parameter, image, must be created with either the IMAGE_READ or IMAGE_CREATE routine.

The rules of precedence for determining the file type are:

1. Use the value of the File_Type keyword.

2. Use the suffix given as part of the filename given in the filename parameter. The suffix will be recognized if it is for one of the supported file types.

3. Use file type specified in the file_type key of image associative array.

4. Use the suffix given in the file_name key of the image associative array.

If the filename parameter is a null string, the filename is taken from the file_name key of the image associative array. In this case, the filename suffix will be changed to match the file type as determined by the rules of precedence above.

note	You can use the File_Type keyword to convert image files from one format to another. For example, if you read a JPEG file, you can convert it to a Sun Rasterfile by writing it with the following command:

status = IMAGE_WRITE('', image, File_Type = 'SUN')

If the image has been created from the file picture.jpeg, this command will write a file picture.sun.

Compression Algorithms lists the available compression algorithms.

Table 10-5: Compression Algorithms
Supported Image File Types	Compression Algorithm
BMP, PCX	RLE
JPEG, PCD, XPM, XBM	JPEG
TIFF, PNG	Zip
MIFF, TGA, SUN, XWD	None
GIF	LZW

DICOM notes

If File_Type is set to ‘DICM’ and the 'Comments' key of the image associative array is an empty string, IMAGE_WRITE adds the valid File Meta Information and the DICOM tags to the 'Comments' key. The content of this header is the following ASCII DICOM tags representation stored in a string array.

(0002,0000) FileMetaInformationGroupLength

(0002,0001) FileMetaInformationVersion

(0002,0002) MediaStorageSOPClassUID

(0002,0003) MediaStorageSOPInstanceUID

(0002,0010) TransferSyntaxUID

(0002,0012) ImplementationClassUID

(0002,0013) ImplementationVersionName

(0002,0016) SourceApplicationEntityTitle

(0002,0100) PrivateInformationCreatorUID

(0002,0102) PrivateInformation

(0008,0016) SOPClassUID

(0008,0018) SOPInstanceUID

(0008,0064) ConversionType

(0020,000D) StudyInstanceUID

(0020,000E) SeriesInstanceUID

(0028,0002) SamplesPerPixel

(0028,0004) PhotometricInterpretation

(0028,0006) Planar Configuration

(0028,0010) Rows

(0028,0011) Columns

(0028,0030) PixelSpacing

(0028,0100) BitsAllocated

(0028,0101) BitsStored

(0028,0102) HighBit

(0028,0103) PixelRepresentation

(7FE0,0010) PixelData

note

If you are using the tag (0028,0006) Planar Configuration when creating 24-bit colored DICM images, use either of the following values:

If the value is 0, then they are grouped by location, e.g.:

RGBRGBRGBRGBRGB

If the value is 1, then they are grouped by sample, e.g.:

RRRRR......GGGGG.......BBBBB.....

Saving an XPM file as a TGA file

Reading a 24-bit XPM file on Unix and writing it as a TGA file results in the image being flipped along the X axis.

Example

This example writes image file flowers.sun in Sun Rasterfile format, in the current directory.

; Reads the file veggies.jpg and returns the

; image associative array.

veggies = IMAGE_READ(!Dir + '/demo/gallery3/data/veggies.jpg')

; Create an image file in Sun Rasterfile format.

status = IMAGE_WRITE('veggies.sun', veggies)