IMAGE

image col|{numexpr}, row|{numexpr} [, cols|{numexpr}, rows|{numexpr}], "file" | {expr} [,color], [,nocache] [,option code] [,shade percent] [,gamma gamma] [,rotate rotate][,page pagenum|{expr} [,link "url"|{urlexpr}] [,linkopt "urlopts"|{urloptexpr}]

The image command is used to print an image file specified by file or the expr which resolves to a file name to each page when the output position is the column and row indicated. This option is typically used to add graphic logos to forms. The column and row can be specified with decimal fractions to 1/100 character.

The optional cols and rows parameters are used in most circumstances. Specifically, they are not used for native PCL images (.pcl or .rtl files), or for raw Zebra images (.zpl). In those cases, the columns and rows options are ignored. For Postscript and PDF images, and for images that are scaled and converted for use in PCL output, columns and rows are required. If not supplied in those circumstances, then each defaults to the cols and rows that measure one inch. It is generally advisable to include these parameters to ensure that all versions of output will produce the desired size whenever possible.

If used, numexpr is a Business Basic expression that generates a numeric value for the column, row, columns, or rows.

If expr is used, then it should be a valid Business Basic expression that resolves to a string value, which will be interpreted as the file name as each copy prints.

Images typically require some degree of processing or parsing during a print job. To avoid extra overhead for images that are used repeatedly, the final images are cached for reuse in later jobs. However, in some cases it may be preferable to avoid caching images. For example, signature images are often used only once, and caching them would waste space and cache management processing time. To turn off caching of an image, use the nocache option. Note that cached images that remain unused for a period of time (defined by imageage=days in uf100d.ini) are removed from the cache file (images.dat) automatically.

The color option indicates that a color image should be produced. The –ci and –color command line options set the color option on by default for all images. This option is ignored when printing native format images, such as .pcl or .rtl images, but it may determine what file name substitutions might occur in some output formats.

The shade option can be used to apply shading to the image to reduce it's intensity and allow other data to show through the image. In PDF output, transparency must be enabled for this to work.

The gamma value can be used to modify the colors when an image is being converted to native format. Images that contain RGB color information often display differently on different devices and as a result can appear darker or lighter than expected when printed. A gamma value greater than 1 lightens an image, while a value less than 1 darkens it. This value is passed to the conversion program (Image Magick or the Windows Support Server). It is ignored when using image files that are already in native format for the output.

Rotation can occur when an image is being converted to native format. This value is passed to the conversion program (Image Magick or the Windows Support Server). It is ignored when using image files that are already in native format for the output.

The page option is supported for PDF images and PDF output. See the discussion below.

Image handling varies considerably based on the output format, and the type of image provided to the image command. Image files can be considered "native", meaning they can be inserted by UnForm directly into the output with little or no processing, or they can be other image formats that require conversion first. Conversion is automatic, assuming either Image Magick or the Windows Support Server are configured and available for UnForm's use.

The publisher also maintains an image conversion tool at http://unform.com. This tool allows users to upload images in non-native format and produce native images for use within UnForm jobs.

UnForm considers an image with a .pcl, .prn, or .rtl extension to be a native PCL image. These images are parsed to remove PCL instructions that could cause a page eject, and positioning code is inserted at runtime to place the image in the correct location on the page. Otherwise, the image is passed through to the output unchanged.

If an image is not in native PCL format, such as a .jpg or .tif file, then it must be converted at runtime to PCL format. During this conversion process, the image is also scaled to the size required. The conversion and scaling process is accomplished with Image Magick, if configured in the uf100d.ini file, or via the Windows Support Server, if configured in uf100d.ini or with a sshost() code block command. Internally, the image is first converted to a bitmap in color or black and white format, and then resolved into a PCL image internally.

Some PCL images contain width and height information. However, since passing through a width and height would apply a default crop size to any additional image without width and height information, UnForm strips out this width and height coding. Unfortunately, color PCL images must contain width and height information to prevent the printer from displaying a black band from the right edge of the image to the right margin. Therefore, when printing to a color printer, UnForm must pass the image width and height coding to the printer. To trigger this parsing behavior, you can do one of two things: add a "color" option to the image command, or add a –gw, -ci, or –color option to the UnForm command line.

One side effect of passing this coding through is that you can't also use images that do not have size information. Generally, this means you can't mix color and black and white PCL image files in the same job.

If the row is 0 or 255, then UnForm will apply no positioning to the output. In this case, the positioning desired should be present in the file. UnForm will scan the file, looking for image information and possibly position data. Just that information will be sent to the output device. If the row is greater than 0 and less than 255, then UnForm will ignore any positioning that might be contained in the image file, and instead place the upper left corner of the image where specified. This feature only works with pcl images that include positioning data.

If UnForm is producing PDF output, and the image file name ends in .pcl, .prn, or .rtl, then the file name is modified to have a .pdf extension automatically. This allows a single fixed file name to accommodate both laser and PDF output without special logic.

Because PDF files can contain various image formats, including full-color (24-bit) jpeg files, and supports both color and black and white image data, UnForm goes through several logical steps to determine how best to insert the image.

•	If the image file extension is .pcl, .prn, or .rtl, UnForm instead looks for a file of the same name, but with a .pdf extension. If the file is not found, a warning error is issued and no image is produced. Otherwise, native .pdf handling is performed.

•

If the image is in .pdf format, and the 'page n' option is not used, UnForm parses the file for the first image on the first page, and inserts that image object in the output. Note that UnForm's parser supports PDF files revision 1.4 and below.

If the 'page n' option is used, then UnForm will use Ghostscript 8.10 or higher to produce a scaled image of the specified page. This page image will be in either color or black and white format, depending on whether color or black and white image output is being produced. If Ghostscript is not configured in the uf100d.ini file or via the Windows Support Server, this option results in a warning message and no page image is produced.

•

If the image command or command line indicates color output, and the image file extension is jpg or jpeg, Unform checks its size and colors setting. If it is a 24-bit jpeg file and its size is no more than 50% larger than the specified size (based on cols and rows), then the file is inserted directly into the output.

•	If no conversion facilities are available (no Image Magick configuration and no Windows Support Server), and the image is a 24-bit jpeg file, it is inserted into the output.

•	UnForm attempts to convert and scale the image file into either a black and white pdf image, or a 24-bit color jpeg image, depending on the whether the output is color or not.

PostScript image output must be in either eps or jpeg format. Black and white laser printers do not support jpeg images. Color laser printers support both eps files and both gray scale (8-bit) and color (24-bit) jpeg images.

•	If the image file extension is .pcl, .prn, or .rtl, then the file name is modified to have either a .eps extension (for black and white output) or a .jpg extension (for color output). If the file exists, the new file name is processed.

•	Other image formats are converted to jpeg or a black and white PostScript raster image, using either Image Magick or the Windows Support Server. If these facilities are not available, a warning error is issued and the image is not inserted.

The file name can start with "http://" or "https://" to refer to it as a URL rather than an embedded file. The link and linkopt options can be used to specify a URL hyperlink value, and HTML <a> tag options, respectively, to make the image a hyperlink.

UnForm scans the first block of the file to determine if it is a native ZPL image file. ZPL images begin with the characters "~DG" followed by some comma-delimited data. If so, the image is inserted in the output.

If the file is not a native ZPL image, UnForm attempts to convert it to a bitmap using Image Magick or the Windows Support Server, and then to a ZPL image. During this process, the image is scaled to the size specified by the cols and rows parameters. If the conversion fails, then a warning error is issued and no image is inserted.

image .5,1.25,"/usr/UnForm/logo.pcl" will place the raster image contained in the named file at column .5, row 1.25.

image {icol},{irow},{icols},{irows},{logo$} will place an image file specified in the variable logo$ at the position specified by the variables icol and irow. If used in a pdf driver or when automated conversion and scaling is invoked, the variables icols and irows would specify the image size (more specifically, its bounding box) in columns and rows. All the variables would have to be created in a code block, such as prejob{} or prepage{}.