Import and Export
Writes an image to a file.
WriteImage(image, name, format, frame);
|image||image or image series||none||the image to be written|
|format||string||"rgb" or input dependent||format of file|
|frame||integer||format dependent||frame to be written|
This module writes an image or series of images to disk.
|Note:||If you are using the Image tool, the functionality of this module is available in the Save Image... option of the Image window's File pull-down menu (see "Saving an Image" in IBM Visualization Data Explorer User's Guide).|
specifies the image to be written to a file on disk.
specifies the name of the file to be written to.
specifies the format in which the image is to be written. The image file format can be specified by the file extension in name or by format. If these specifications conflict, format takes precedence. If the format is one of RGB, R+G+B, YUV, or MIFF, and the given file exists, the image(s) are appended to the file. Otherwise, a new file is always created. The format parameter allows specification of gamma, compression, and quality for all format types. The default gamma is 2. (This is a change from previous releases for which gamma was always 1.) Compression and quality affect the compression used and the quality of the compression when writing ImageMagick supported formats. Refer to the ImageMagick documentation for formats that support compression and compression quality factors. See ImageMagick for an example. The format parameter also allows specification that a "delayed colors" image should be written, for all formats other than RGB, R+G+B, and YUV. See PostScript for a description of how to specify these two options.
specifies a frame number in the file on disk. The first frame of a disk file or series is frame number 0 (zero). Its interpretation varies with the format being used.
If the format is one of RGB, R+G+B, or YUV, then frame indicates the starting image frame in the disk file at which the given image or image series should be written. If the frame does not exist in the given file (this is the same as the file not existing), then the file is extended to contain the frames just before the indicated frame number. The contents of the frames that were created to extend the file are undefined. If frame is not provided, then the input image(s) are appended to an existing file. If the file does not exist it is created with the given image(s).
For the TIFF and PostScript formats, if frame is specified, it is used to modify the output file name. For example, if frame = n, the name is modified from name.tiff to name.n.tiff. If the image is a series, all frames will be written to this file.
See Table 9 for the recognized formats. PostScript** formats may include additional modifiers, separated from the format name by white space. See PostScript for the recognized modifiers. The following example sets the format to PostScript and specifies a page size of 4x5 and gamma=1.
WriteImage(y,name,"ps page=4x5 ");
The RGB ("rgb" and "r+g+b") and YUV formats allow an existing file to be modified, either by overwriting existing frames or by extending the number of frames in the file. The TIFF and PostScript formats do not support this capability. MIFF allows appending of images (but not overwriting of images).
Table 9 summarizes the characteristics of each format.
Descriptive sections follow the table.
Table 9. Format
Characteristics for WriteImage
|File Type||Format Specifier||Resulting File Extension(s)||Multiframe/ Series Data||Modify an Existing File|
|.rgb and .size
.r, .g, .b, and .size
|Color PostScript||"ps color"
|Gray PostScript||"ps gray"
|many different||"ImageMagick supported format"||many different||No||No|
rgb file format consists of two files, a binary name.rgb file that contains the image pixel values and a name.size file used to specify the image dimensions and the number of images contained in the name.rgb file. The name.size file contains a single line of ASCII text in the format "w×h×f," where w and h give the dimensions of each image and f indicates the number of images in the name.rgb file. The name.rgb file contains (red, green, blue) binary pixel values with 8 bits per color (24 bits/pixel). Pixels are read and written from the image in left-to-right, top-to-bottom order.
r+g+b format is similar to rgb format, except that the name.rgb file is replaced by three binary files, one for each color. The name.r file contains the red color values for all images, the name.g file contains the green color values for all images and the name.b file contains the blue color values for all images. Again, all color values are 8 bits (24 bits/pixel).
TIFF (tag image file format) files are binary files that contain 24 bits/pixel color resolution. For more information on TIFF files see Tag Image File Format Specification, Revision 5.0, available from Aldus Corporation or Microsoft Corporation.
PostScript format files are written out using PostScript's image (or color image) operator and require only PostScript Level 1 interpreter support. WriteImage supports four different varieties of PostScript. Images can be written out in either color or gray-scale and either "Encapsulated" or not. Color images are written out at 24 bits/pixel and gray-scale at 8 bits/pixel. Encapsulated PostScript is a format intended to be used when incorporating images into other documents. For this reason, the Encapsulated PostScript formats do not support series image input (i.e., only one image per file is acceptable). All PostScript output is run-length encoded to reduce the file size. (For more information on PostScript see PostScript Language Reference Manual, Second Edition; Addison-Wesley Publishing Company, 1990.)
By default, the image will be scaled and oriented to fill the current page size within the specified margin of the edge, while preserving the original aspect ratio of the image. That is, the image will be made as large as possible while maintaining the specified margin on at least one of the two dimensions. If Allow Rerendering is off, the pixels in the image will be sized appropriately to scale the image to fill the page, but the same number of pixels as in the currently displayed image will be used. If this results in a grainy image, set Allow Rerendering on, and enter a different Input image size. For example, if the displayed image is 640x480, and you want to double the resolution, just enter 1280 in the Input image size field and Data Explorer will recalculate the new value of y (960) and the new (higher) value for Output PPI. If dpi or width is specified, these specifications will override the autoscaling feature. It is typically only necessary to use the page and margin modifiers.
PostScript supports the following format modifiers:
WriteImage(y, name, "ps color page=4x5 orient=landscape");
If only width or height is specified (but not both), the original aspect ratio of the image is maintained. If both are specified, the image may be stretched.
is a run-length-encoded format that supports image sequences. Writing an image to an existing miff file name causes the image to be appended to the file. To start a new sequence you must delete the .miff file.
|ImageMagick supported format||With the ImageMagickTM libraries configured and compiled with DX, WriteImage can read and write a large number of image file formats. ImageMagick is a robust collection of tools and libraries to read, write, and manipulate an image in many image formats (over 68 major formats) including popular formats like TIFF, JPEG, PNG, PDF, PhotoCD, and GIF. The formats that can be written by WriteImage will depend on what functionality is compiled into ImageMagick.
WriteImage(y, name, "ImageMagick supported format gamma=2.2 compression=JPEG quality=90 resize=50");
Setting a quality sets the amount of compression for variable compression types such as JPEG.
Setting a resize value on the format will use the Lanczos interpolation function. The value represents the percentage of reduction (resize=50 sets it to 50%. A good value for anti-aliasing).
Note: If you are writing out images for use later from within Data Explorer, you will probably want to set gamma correction to 1 (the default is 2). Otherwise, images will be doubly gamma-corrected. (Gamma correction at display time can also be controlled using the DXGAMMA environment variable; see C.1 , "Environment Variables" in IBM Visualization Data Explorer User's Guide). For printing or viewing images in another package, use gamma appropriate for that device.