Specifying Images in SASGRAPH Programs
Specifying Images in SAS/GRAPH Programs
SAS/GRAPH software enables you to display images as part of your graph. You can place an image in the background area of a graph, in the backplane of graphs that support frames , or on the bars of two-dimensional bar charts . You can also apply images at specified graph-coordinate positions using the Annotate facility or the DATA Step Graphics Interface (DSGI).
The images you add to your graphs can be SAS files or external files in a wide range of image formats. If you wish to withold images from your graphics output, you can specify the NOIMAGEPRINT graphics option.
Image File Types Supported by SAS/GRAPH
For displaying images in your graphs, SAS/GRAPH software supports the following image file types:
| File Type | Description |
|---|---|
| BMP (Microsoft Windows Device Independent Bitmap) | supports color-mapped and true color images stored as uncompressed or run-length encoded. BMPwasdevelopedbyMicrosoftCorporationfor storing images under Windows 3.0. |
| CAT (SAS Catalog IMAGE entry) | supports color-mapped images as well as true color images. The images can be optionally compressed. |
| DIB (Microsoft Windows Device Independent Bitmap) | see the description of BMP. |
| EMF (Microsoft NT Enhanced Metafile) | supported under Windows 95, Windows 98, Windows 2000, and Windows NT. |
| GIF (Graphics Interchange Format) | supports only color-mapped images. GIF is owned by CompuServe, Inc. |
| JPEG (Joint Photographic Experts Group ) | supports compression of images with the use of JPEG File Interchange Format (JFIF) software. JFIF software is developed by the Independent Joint Photographic Experts Group. |
| PBM (Portable Bitmap Utilities) | supports gray, color, RGB, and bitmap files. The Portable Bitmap Utilities is a set of free utility programs that were primarily developed by Jeff Poskanzer. |
| PCD (Photo CD) | Kodak Photo CD format which supports multiple image resolutions . |
| PCL (Printer Control Language) | developed by HP. |
| PCX (PC Paintbrush) | supports bitmap, color-map, and true color images. PCX and PC Paintbrush are owned by Zsoft Corporation. |
| PNG (Portable Network Graphic) | supports truecolor , gray-scale , and 8-bit images. |
| PS (PostScript Image File Format) | the Image classes use only PostScript image operators. A level II PS printer is required for color images. PostScript was developed by Adobe Systems, Inc. |
| TGA (Targa) | supports both true color images and color-mapped images; however, the current release of the Image classes supports only true color TGA files. Targa is owned by Truevision, Inc. |
| TIFF (Tagged Image File Format) | internally supports a number of compression types and image types, including bitmap, color-map, gray-scale, and true color. TIFF was developed by Aldus Corporation and Microsoft Corporation and is used by a wide variety of applications. |
| WMF (Microsoft Windows Metafile) | supported only under Microsoft Windows operating systems. |
| XBM (X Window Bitmaps) | supports bitmap images only. XBM is owned by MIT X Consortium. |
| XPM (X Window Pixmap) | is an extended version of XBM that supports color bitmaps. |
| XWD (X Window Dump) | supports all X visual types (bitmap, color-map, and true color.) XWD is owned by MIT X Consortium. |
Reading and Writing Image File Types
The image file types supported by SAS/GRAPH may be supported for reading or writing. In addition, all SAS/GRAPH supported file types can be printed. The printed output s appearance is dependent on the driver that is selected. See Image Formats for Reading on page 108 and Image Formats for Writing on page 110 for more information on specific file type capabilities and attributes.
When you are reading some images, the FORMAT= attribute is required. See Including the FORMAT= attribute on page 108 for more information. Some of the file types that require the FORMAT= attribute are only supported by certain hosts. Image File Types Supported Only on Certain Hosts on page 113 contains information on these file types, the reader and writer attributes, and the host support.
If you are using SAS/GRAPH on the z/OS platform, you must be running the UNIX System Services Hierarchical File System (HFS) to read and write image files.
Including the FORMAT= attribute
When you are reading images, include the FORMAT= attribute if
-
you are reading a format supported only on certain hosts. See Image File Types Supported Only on Certain Hosts on page 113 for more information.
-
images reside in SAS catalogs.
-
images are read from a system pipe.
FORMAT= is not required in other cases, but it is always more efficient to specify it.
Image Formats for Reading
The following table describes the attributes for the image readers that are supported by SAS/GRAPH:
| File Type | Reader Attributes | Comment | |
|---|---|---|---|
| BMP | FORMAT=BMP | ||
| COMPRESS=NONE COMPRESS=RLE | is the default. Sets compression to run-length encoded. | ||
| CAT | FORMAT=CAT | ||
| DIB | FORMAT=DIB | is supported only by Windows NT, Window 2000, and Windows XP. | |
| EMF | FORMAT=EMF | is supported only by Windows NT, Window 2000, and Windows XP. | |
| GIF | FORMAT=GIF | ||
| JFIF | FORMAT=JFIF | required for reading JPEG files that use JPEG File Interchange Format (JFIF). | |
| DCT= mode | selects specific type of Discrete Cosine Transform (DCT) to use when processing the image; mode can be | ||
| |||
| GRAYSCALE | produces a gray-scale image even if the JPEG file is in color. This is useful for viewing on monochrome displays. The reader runs noticeably faster in this mode. | ||
| VERSION | prints the version number and copyright messages for the Independent JPE Group s JFIF software to the log. | ||
| FAST | enables certain recommended processing options for fast, low quality output; equivalent to enabling ONEPASS, DITHER=ORDERED, COLORS=216, NOSMOOTH, and DCT=FAST. | ||
| NOSMOOTH | uses a faster, lower quality, upsampling routine. | ||
| ONEPASS | uses a one-pass color quantization instead of the standard two-pass quantization. The one-pass method is faster and needs less memory, but it produces a lower-quality image. This attribute is ignored unless you also specify the COLORS attribute. ONEPASS is always enabled for gray-scale output. | ||
| COLORS= n | reduces the number of colors in the image to at most n colors; n must be in the range 2...256. | ||
| SCALE_RATIO= n | scales the output image by a factor of 1/ n . Currently the scale factor must be 1/1, 1/2, 1/4, or 1/8. This is useful when processing a large image and only a smaller version is needed, as the reader is much faster when scaling down the output. | ||
| DITHER= mode | selects the specific type of dithering to use color quantization; mode can be | ||
| |||
| PBM | FORMAT=PBM | ||
| PCD | FORMAT=PCD | specifies photo CD format. FORMAT=PCD RES= specifies the image resolution to be read. Photo CD images have multiple resolution images in each image. Values are: | |
| BASE/64 | 64x96 | ||
| BASE/16 | 128x192 | ||
| BASE/4 | 256x384 | ||
| BASE | 512x768 (default) | ||
| 4BASE | 1024x1536 | ||
| 16BASE | 2048x3072. | ||
| PCX | FORMAT=PCX | is not supported for writing. | |
| PNG | FORMAT=PNG | ||
| TGA | FORMAT=TGA | ||
| TIFF | FORMAT=TIFF | ||
| XBM | FORMAT=XBM | ||
| XPM | FORMAT=XPM | is supported only under the X Windows System under UNIX. | |
| XWD | FORMAT=XWD | ||
Image Formats for Writing
The following table describes the attributes for the image writers that are supported by SAS/GRAPH:
| File Type | Writer Attributes | Comment |
|---|---|---|
| BMP | FORMAT=BMP | |
| CAT | FORMAT=CAT | |
| COMPRESS=G3FAX | sets compression to FAX CCITT Group 3 for monochrome black-and-white images (depth of 1) only. | |
| COMPRESS=G4FAX | sets compression to FAX CCITT Group4 for monochrome black-and-white images (depth of 1) only. | |
| DESC= | enables description for catalog description | |
| DIB | FORMAT=DIB | is supported only by Windows NT, Window 2000, and Windows XP. |
| EMF | FORMAT=EMF | is supported only by Windows 95, Windows 98, Windows 2000, and Windows NT. |
| GIF | FORMAT=GIF | |
| JFIF | FORMAT=JFIF | is required for writing JPEG files that use JPEG File Interchange Format (JFIF). |
| DCT= mode | selects specific type of Discrete Cosine Transform (DCT) to use when processing the image; mode can be | |
| ||
| GRAYSCALE | produces a gray-scale image even if the JPEG file is in color. This is useful for viewing on monochrome displays. The writer runs noticeably faster in this mode. | |
| VERSION | prints the version number and copyright messages for the Independent JPE Group s JFIF software to the log. | |
| FAST | enables certain recommended processing options for fast, low quality output; equivalent to enabling ONEPASS, DITHER=ORDERED, COLORS=216, NOSMOOTH, and DCT=FAST. | |
| NOSMOOTH | uses a faster, lower quality, upsampling routine. | |
| ONEPASS | uses a one-pass color quantization instead of the standard two-pass quantization. The one-pass method is faster and needs less memory, but it produces a lower-quality image. This attribute is ignored unless you also specify the COLORS attribute. ONEPASS is always enabled for gray-scale output. | |
| COLORS= n | reduces the number of colors in the image to at most n colors; n must be in the range 2...256. | |
| SCALE_RATIO= n | scales the output image by a factor of 1/ n . Currently the scale factor must be 1/1, 1/2, 1/4, or 1/8. This is useful when processing a large image and only a smaller version is needed, as the writer is much faster when scaling down the output. | |
| DITHER= mode | selects the specific type of dithering to use color quantization; mode can be | |
| ||
| PBM | FORMAT=PBM | |
| COMPRESS=NONE | creates a text PBM file. | |
| COMPRESS=BINARY RAW | if either of these values is specified, creates a PBM file of reduced size by packing the pixels as binary data (when FORMAT=PBM is specified, output is produced by default as if one of these values is specified). | |
| PCL | FORMAT=PCL | |
| DPI= num | specifies the number of dots per inch to use to calculate the visual size of the image on the PostScript page in the output file. The default is 300. For example, a 600-pixel by 600-pixel image appears as a 2-inch by 2-inch image on the PostScript page if you use the default setting. | |
| EPS | does not reset the printer margins; use to embed an image into another PCL document | |
| PNG | FORMAT=PNG | |
| PS | FORMAT=PS | |
| COMPRESS=NONE | is the default for color images. | |
| COMPRESS=RLE | sets compression to run-length encoded; default for gray-scale images. | |
| DPI= num | specifies the number of dots per inch to use to calculate the visual size of the image on the PostScript page in the output file. The default is 300. For example, a 600-pixel by 600-pixel image appears as a 2-inch by 2-inch image on the PostScript page if you use the default setting. | |
| EPS | does not reset the printer margins; used to embed an image in another PCL document. | |
| PREVIEW | specifies whether a scaled-down, 1 “bit, black-and-white preview image is written into the encapsulation header. The preview image enables this file to be written by software (such as SAS) that doesn t support a real PostScript writer. | |
| PREWIDTH= x PREHEIGHT= y | sets the size of the preview image in pixels if PREVIEW is specified (default: 25% of original size). | |
| XSCALE | directly sets width scaling in points (1/72 inch). Default: calculate it. | |
| YSCALE | directly sets height scaling in points (1/72 inch). Default: calculate it. | |
| PAGEX | sets output page width in points (1/72 inch). Default: 612 (a typical 8.5 “inch page). | |
| PAGEY | sets output page height in points (1/72 inch). Default: 792(atypical11 “inchpage). | |
| NOFIT | turns off the default of scaling an oversized image down to fit the page. Must be used with XSCALE and YSCALE. Although this option is still supported in this release, the PAGEFIT option will replace it. | |
| PAGEFIT |
| |
| This option replaces the NOFIT option. | ||
| TIFF | FORMAT=TIFF | |
| COMPRESS=NONE | is the default | |
| COMPRESS=G3FAX | sets compression to FAX CCITT Group 3 for monochrome black-and-white (depth of 1) images only. | |
| COMPRESS=G4FAX | sets compression to FAX CCITT Group 4 for monochrome black-and-white (depth of 1) images only. | |
| WMF | FORMAT=WMF | is supported only under Windows operating systems. |
| XBM | FORMAT=XBM | is supported for writing only from interactive windows under UNIX. |
| XPM | FORMAT=XPM | is supported only under the X Windows System under UNIX. |
Image File Types Supported Only on Certain Hosts
Some file types are only supported by certain hosts. You must include a FORMAT= attribute when you are reading or writing the following image file types shown in the following table:
| File Type | Reader Attributes | Writer Attributes | Host |
|---|---|---|---|
| DIB | FORMAT=DIB | FORMAT=DIB | Windows NT, Window 2000, and Windows XP |
| EMF | FORMAT=EMF | FORMAT=EMF | Windows NT, Window 2000, and Windows XP |
| WMF | FORMAT=WMF | Windows operating systems | |
| XBM | FORMAT=XBM | interactive windows under UNIX | |
| XPM | FORMAT=XPM | FORMAT=XPM | X Windows System under UNIX |
Placing a Background Image
Any SAS/GRAPH procedure that produces a picture can place an image on the graph s background area. To place an image on the graph background, use the IBACK= option on a GOPTIONS statement. On IBACK=, specify either the full path to the image file in quotation marks, or a fileref that has been defined to point to the image file as follows :
goptions iback= external-image-file ;
Image File Types Supported by SAS/GRAPH on page 106 shows the image file formats that you can use. Disabling and Enabling Image Output on page 120 shows how to suppress the image output without removing the imaging code from your SAS/GRAPH program; for example, you might want to suppress the image when printing the graph.
By default, the image is tiled on the background, which means that the image is copied as many times as needed to fill the background area. You can specify IMAGESTYLE=FIT on the GOPTIONS statement to stretch the image so that a single image fits within the entire background area:
goptions iback= external-image-file imagestyle=fit;
After fitting the image, you can tile subsequent images by resetting the GOPTIONS statement or by specifying IMAGESTYLE=TILE. The following graphs illustrate the use of tiled versus stretched images.
The following example displays an image behind a pie chart. Because the IMAGESTYLE option is not used, the image is tiled in the background area.
goptions reset=all ctitle=cx90d0d9 ftitle=swissb ctext=white htext=0.85 htitle=2.5 ftext=swissb colors=(cx00cccc cxcd0369 cx5b768d cx594f4a cx008080 cxff8f71) iback= external-image-file ; title Projected Automobile Sales; data sales; length month $ 9; input month amount; datalines; January 200 February 145 March 220 April 180 May 155 June 250 ; proc gchart; pie month / freq=amount value=inside noheading coutline=black; run; quit;
The preceding program generates the following graph, which illustrates the tiling of an image to fill an area.
Figure 6.2: Pie Chart with a Tiled Image in the Background
Adding the IMAGESTYLE=FIT goption to the preceding program generates the following graphics output, where a single instance of the image is stretched to fit the background of the graph:
Figure 6.3: Pie Chart with a Stretched Image in the Background
Placing a Backplane Image on Graphs with Frames
Procedures GCHART, GPLOT, GRADAR, and GSLIDE support frames, which are the backplanes behind the graphs. Each of these procedures enables you to place an image on the backplane.
To place an image on the backplane of a graph that supports frames, specify the IFRAME= option on the procedure that generates the graph. On the IFRAME= option, specify either the full path to the image file in quotation marks, or a fileref that has been defined to point to the image file as follows:
iframe= fileref external-image-file
Image File Types Supported by SAS/GRAPH on page 106 shows the image file formats that you can use. Disabling and Enabling Image Output on page 120 shows how to suppress the image output without removing the imaging code from your SAS/GRAPH program; for example, you might want to suppress the image when printing the graph.
By default, the image is tiled on the backplane, which means that the image is copied as many times as needed to fill the backplane.
To stretch a single instance of the image to fill the backplane, specify IMAGESTYLE=FIT as follows:
iframe=fileref external-image-file imagestyle=fit;
To switch from a single fitted image back to a series of tiled images, you can specify IMAGESTYLE=TILE.
The following example displays an image on the backplane of a horizontal bar chart. Because the IMAGESTYLE= option is not used, the image is tiled by default.
goptions reset=all ctitle=cx000080 ftitle=swissb ctext=black htext=0.85 htitle=2.5 ftext=swissb cback=cxf7e1c2; title Projected Automobile Sales; data sales; length month $ 9; input month amount; datalines; January 200 February 145 March 220 April 180 May 155 June 250 ; pattern1 value=solid color=cxcd0369; axis1 width=1.5 major=(width=1.5) label=(h=1 Number of Cars) noplane; axis2 width=1.5 major=(width=1.5) label=(h=1 Month) noplane; proc gchart; hbar3d month / freq=amount nostats axis=axis1 maxis=axis2 iframe= external-image-file coutline=black; run; quit;
Placing Images on the Bars of Two-Dimensional Bar Charts
Using the PATTERN statement, you can place images on the two-dimensional bars of graphs that are generated by the GCHART procedure s HBAR or VBAR statements. To place an image on a two-dimensional bar, use the IMAGE= option on a PATTERN statement. On the IMAGE= option, specify the image file as follows:
pattern image= fileref external-image-file ;
Image File Types Supported by SAS/GRAPH on page 106 shows the image file formats that you can use. Disabling and Enabling Image Output on page 120 shows how to suppress the image output without removing the imaging code from your SAS/GRAPH program; for example, you might want to suppress the image when printing the graph.
By default, the image is tiled on the bar, which means that the image is copied as many times as needed to fill the bar area. You can specify IMAGESTYLE=FIT on the PATTERN statement to stretch a single instance of the image to fit the dimensions of the bar, as follows:
pattern image= external-image-file imagestyle=fit;
After fitting the image, you can tile subsequent images by resetting the PATTERN statement or by specifying IMAGESTYLE=TILE.
Note: Images are only supported on the bars that are generated by the HBAR and VBAR statements. If an image is specified on a PATTERN statement that is used with another type of chart, then the PATTERN statement is ignored and default pattern rotation is affected. For example, if you submit a PIE statement when an image has been specified on PATTERN, the default fill pattern is used for the pie slices; however, rather than rotating that pattern through the colors list, each slice in the pie displays the fill pattern in the same color.
The following example generates a bar chart that shows the sales for different automobile manufacturers. The bars that represent the sales figures for each manufacturer display a model vehicle for that manufacturer. Because IMAGESTYLE=FIT is not specified, each image is tiled on the bar that displays it.
goptions reset=all ctitle=cx000080 ftitle=swissb ctext=black htext=0.85 htitle=2.5 ftext=swissb cback=cxf7e1c2; title Projected Automobile Sales; data sales; length Month $ 9 Manufacturer $ 10; input Month amount Manufacturer; datalines; January 100 Nissan February 80 Nissan March 210 Nissan April 201 Nissan January 400 Dodge February 90 Dodge March 220 Dodge April 202 Dodge January 300 Cheverolet February 70 Cheverolet March 230 Cheverolet April 203 Cheverolet January 200 Ford February 100 Ford March 240 Ford April 204 Ford ; run; pattern1 image= external-image-file ; /* corvette image */ pattern2 image= external-image-file ; /* viper image */ pattern3 image= external-image-file ; /* mustang image */ pattern4 image= external-image-file ; /* nissan image */ axis1 label=(h=1 Number of Cars); proc gchart; vbar month / freq=amount coutline=black subgroup=Manufacturer axis=axis1 cframe=olive; run; quit;
Using Annotate to Display an Image
The Annotate facility enables you to display an image at the coordinate location that you specify with the X and Y variables. To display an image, specify the file specification for the image file in quotation marks on the IMGPATH variable, set the image coordinates with the X and Y variables , and then call the IMAGE function, as shown in the following example. One corner of the image is located by the current X and Y position, and the opposite corner is located by the X and Y variables that are associated with the IMGPATH variable.
x=10; y=5; function=move; output; x=35; y=15; imgpath= external-image-file ; style = fit; function=image; output;
The code above draws an image from (10,5) to (35,15).
By default, the image is tiled, which means that it is copied as many times as needed to fill the area. To stretch the image so that a single image fits within the area, set the STYLE variable equal to fit , as shown in the code above.
Image File Types Supported by SAS/GRAPH on page 106 shows the image file formats that you can use. Disabling and Enabling Image Output on page 120 shows how to suppress the image output without removing the imaging code from your SAS/GRAPH program; for example, you might want to suppress the image when printing the graph.
Here is a complete example:
goptions reset=all cback=olive; data wrldtotl; length company $ 10; input company $ 1-10 mean 12-15; datalines; Nissan 550 Cheverolet 571 Ford 137 Dodge 273 Honda 546 Saturn 430 ; run; data wrldanno; length function style color $ 8 text $ 20 image $ 50; retain line 0 xsys ysys 2 hsys 3 x 8; set wrldtotl end=end; function=move; x=x+8; y=20; output; if company=Nissan then imgpath= external-image-file ; /* Nissan image */ else if company=Cheverolet then imgpath= external-image-file ; /* Corvette image */ else if company=Ford then imgpath= external-image-file ; /* Mustang image */ else if company=Dodge then imgpath= external-image-file ; /* Viper image */ else if company=Honda then imgpath= external-image-file ; /* Honda image */ else if company=Saturn then imgpath= external-image-file ; /* Saturn image */ function=image; y=y+(mean); x=x+9; output; function=label; y=0; x=x-4; size=3.5; position=E; style=swiss; color=blue; text=company; output; function=move; y=y+(mean)-3; output; function=label; x=x-1; text=left(put(mean,3.)); position=5; style=swiss; size=7; color=red; output; if end then do; function=move; x=10; y=20; output; function=draw; x=90; y=20; line=1; size=.5; color=blue; output; function=label; x=50; y=95; text=Projected Sales; xsys=3; ysys=3; position=5; style=swissb; size=7; color= ; output; x=92; y=5; size=3; style=swiss; output; function=frame; color=blue; when=b; style=empty; output; end; run; proc ganno annotate=wrldanno datasys; run; quit;
Using DSGI to Display an Image
Using the DATA Step Graphics Interface (DSGI), you can display an image in a designated position. To display an image, specify the file specification for the image file in quotation marks on the GDRAW (IMAGE ,...) function as follows:
rc=gdraw(image, external-image-file , 20, 20, 40, 40, fit);
The code above displays the image in the screen coordinates (20, 20) to (40, 40). The last parameter indicates how to display the image. The following keywords are available:
| fit | fits the image within the specified area. This stretches the image, if necessary. |
| tile | tiles the image within the specified area. This copies the image as many times as needed to fit the area. |
Image File Types Supported by SAS/GRAPH on page 106 shows the image file formats that you can use. Disabling and Enabling Image Output on page 120 shows how to suppress the image output without removing the imaging code from your SAS/GRAPH program; for example, you might want to suppress the image when printing the graph.
Here is a complete example:
goptions reset=all; title DGSI with image; footnote dsgi with image option; data image; rc=ginit(); rc=graph(clear); rc=gdraw(image, external-image-file , 5, 5, 90, 90,fit); rc=graph(update); rc=gterm(); run; quit;
Disabling and Enabling Image Output
The NOIMAGEPRINT graphics option disables image output as follows:
goptions noimageprint;
NOIMAGEPRINT can be useful for printing output without images. To enable image output, reset the GOPTIONS statement or specify the IMAGEPRINT graphics option.
