PHOTO_WRITE Function

Reference Guide > P Routines > PHOTO_WRITE Function

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

note	The PHOTO routines are only available on 64-bit PV-WAVE.

Usage

status = PHOTO_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

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

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

Refer to File Name Formats for PHOTO 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 set and the specified file already exists, overwrite it.

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, displays information about the written image.

Discussion

Before writing a file, the PHOTO_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 PHOTO_CREATE Function for detailed information on the structure of the associative array.

File Name Formats for PHOTO lists file formats that you can write and read using the PHOTO_WRITE and PHOTO_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 PHOTO_READ or PHOTO_CREATE.

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 = PHOTO_WRITE('', image, File_Type = 'SUN')

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

DICOM notes

If the File_Type keyword is set to ‘DICM’ and the 'Comments' key of the image associative array is an empty string, PHOTO_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 veggies.sun in Sun Rasterfile format, in the current directory.

; Reads the file veggies.jpg and returns the

; image associative array.

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

; Create an image file in Sun Rasterfile format.

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