Administration Guide : Command-line manual pages

IMAGETOX(1) manual page

Name

imagetox - convert/scale/display images

Synopsis

/usr/etc/appletalk/imagetox [-xfmt ] [-ccolorspace ] [-D | -ddbglev ] [-Poff ,len ] [-Iiprof ] [-Ri ] [-Z ]
[-Ooprof ] [-Xcropx ,y ,cropw ,h ] [-l ] [-N ] [-W [1]] [-Vfpovolume | -Ggreyfile -BB&Wfile ]
[-rdpi ] [-spercent ] [-wwidth ] [-hheight ] [-a ] [-A ] [-bcolor ] [-f ] [-i ] [-m ] [-n [m|c]] [-k ]
[-p ] [-t ] [-L ] [-T ] [-[CMYK ] | -Scolorname ] [-Epage ] [-uarg ] [-enaa ] [-Fxmpfile ] [-! ]
[-q ] [-Q[#] ] [-U ] [-v ] [-ycmyk2rgb-table ] [-zrgb2cmyk-table ] [-H ] [-3 ] filename

Description

The program imagetox reads filename, which must be an image in a format supported by FullPress, and converts that image into some other format, including displaying it on the server's window system (by default on Unix systems, the X11 server set by the DISPLAY environment variable, and on MSWindows systems, in a console Window). If a different output fmt is chosen, the converted image is written to Standard Output.

The supported output formats, set via the -x option, are:


x11Display on default X11 server (this is the default on Unix systems)
winDisplay on MSWin console (this is the default on MSWin systems)
eps *Encapsulated PostScript
tifTag Image File Format (TIFF)
tifzTag Image File Format (TIFF) with ZIP-compressed image data
gifCompuserve's Graphics Interchange Format
jpg *Native JPEG, ``lossy'' compression format
web *Either GIF (if image is masked or clipped) or JPEG
bmpMS Windows BitMaP (aka DIB) format
pngPortable Network Graphic format
infOnly prints information about the image (see INFO , below)
xmpOnly prints XMP metadata, if found in the image (or nothing).
The formats marked with `*' all take an optional number following the format (e.g. ``-x eps83''). This number sets a JPEG compression factor (normally off for EPS format). The JPEG compression factor is a number with a useful range between 5 and 95, where 5 creates a highly compressed image that doesn't look very much like the original, and 95 produces a less compressed image, but it will look very much like (but not exactly like) the original. If the jpg output format is requested, the default compression factor is 75. If the eps format is requested, a compression value of 0 is accepted, which will cause the output to be HEX encoded (instead of the default BINARY), but not JPEG compressed.

The colorspace of the output image is determined by three things: 1) the colorspace of the input image, 2) what colorspace(s) the output fmt supports, 3) either the colorspace supplied with the -c argument, or the colorspace implied by the output ICC profile oprof. If the options supplied create a colorspace clash, imagetox exits with an error code. The colorspaces accepted by the -c argument are: b/w, grey, rgb, cmyk and lab. The b/w colorspace will be promoted to grey if the output format doesn't support 1-bit, or the input pixel data is not 1-bit or if the image is scaled down. ICC color correction will only be performed if there is both an input profile (see -I below) and an output profile oprof (or output is LAB and there is an input profile).

Scaling

Images may be scaled (up or down) by supplying the -s option with the (floating point) percentage of the image size (in pixels) to output. You may scale to a specific width and/or height (also in pixels) with the -w and -h options (if only one of them is given, the aspect ratio of the image will be maintained - this is different behaviour than previous versions). Both width and height may also be specified as a range of the form min-max, to give upper and lower limits for the output dimensions. The image is scaled either up or down (after applying any percent scaling) to fit into the given pixel range. If both width and height ranges are given, and the image's pixel width is outside the width range, the height range will be ignored. If min is omitted, zero is assumed. Omitting max effectively disables any further downsampling. It is an error to give one absolute pixel dimension and one range.

Alternatively, scaling may be done by setting the output resolution to a dpi (dots per inch) with the -r option. If both a scaling factor and resolution is set, the image is scaled to the scaling factor, and the output resolution will be forced to the given dpi setting. With no scaling, the resolution can be negative, meaning it's a maximum setting. In this case the image will be scaled down only, and only if the input image's resolution is higher either horizontally or vertically.

When the output format is X11 window system, images larger (after scaling) than the size of the Display are further shrunk repeatedly by 50 percent in both their width and height until they are smaller than the display. This shrink-to-fit feature can be disabled by specifying the -f option on the command line.

Cropping

You may select a rectangular portion of an image to be extracted by giving the -X option. The argument specifies a rectangle on the source image, in pixels, numbered from (0,0), which is the pixel in the upper left corner of the image. Cropx (horizontal) and cropy (vertical) are the coordinates of the first pixel that will be placed in the upper-left corner of the output image. Cropw and croph give the number of pixels of the orignal image to include in the cropped image (width and height, respectively).

Other Options

-a
Only effective when both an absolute pixel width and height are requested, and causes the aspect ratio of the image to be maintained. White (or masked) pixels and/or lines are added, if necessary, to fill out the requested dimensions, keeping the image centered.
-A
Identical to the -a option, except instead of centering the resulting image, keep image on the top left and pad on the bottom or right to achieve requested dimensions while maintaining the aspect ratio.
-d
sets the debugging bit-mask to dblev. The debugging mask is documented in opidebug(5) .
-D
turns on all debugging bits.
-e
supplies items for IPTC/NAA record 2 data, for those output formats that support them. You can give multiple -e arguments, supplying different items each time. See the IPTC section below for more details.
-F
Supply XMP data to be written into the output image, if the output format supports it. If xmpfile is ``.'' any existing XMP in the input image is copied to output; otherwise xmpfile must contain a complete XMP packet (but no verification is performed). Currently, XMP data is supported writing TIF, JPEG, PNG and EPS formats and reading those plus PSD.
-I
sets an input ICC profile pathname, which overrides any other profile available for the image. See -O below for more ICC information.
-O
sets an output ICC profile pathname. This option enables ICC color correction if one of the following conditions is met (in order of precedence): 1) an input profile has been supplied with the -I option, 2) the image has an embedded profile, 3) a default profile exists for the image format and colorspace (in /var/adm/appletalk/coloropts), 4) the input image is in LAB colorspace. It is easy to set up conflicts if the output format does not support the colorspace implied by oprof, or if the input profile iprof does not match the colorspace of the image. Imagetox produces an error message and exits with an EINVAL error code if this happens. If ICC correction is performed and the output format supports it (only EPS, TIFF and JPEG do as of this writing), the oprof will be embedded in the output.
-R
Sets the Rendering Intent for ICC color conversion. Normally, the default Rendering Intent supplied in the profiles is used. It may be overridden with this flag, if the Profiles support the one requested. If the requested Rendering Intent isn't supported, the profiles' default is used. Current valid Rendering Intents are:


0:  Perceptual 
1:  Relative Colorimetric 
2:  Saturation 
3:  Absolute Colorimetric 
 
-Z
Turns on Black Point Compensation when performing ICC color correction.
-P
Extract the len byte long PICT image located off bytes into the file filename. Any other image and/or preview that may be contained in the file will be ignored. If there is no PICT at the offset specified, imagetox will exit with an error.
-p
this option causes imagetox to search for a ``preview'' image first before reading in the ``full-scale'' image. Previews consist of either a PICT inside filename's resource fork, or a PC-Style TIFF preview embedded in the data. If a pixel width and/or height is requested and there are multiple PICTs, the one closest to the requested size will be chosen and scaled. If -pdb is selected, the width and height will be ouput to the stream (4 bytes each) before the image, and the program will exit if no PICT preview is available.
-t
if an EPS image has a PC-Style TIFF preview, this option causes the TIFF to be read instead of the EPS.
-b
Sets the background color, when a Masked or Clipped image is output in a format that does not support masks (or Clipping paths) to the given color, which must be an X Window System color name (the #RRGGBB hex convention is also supported - see showrgb for available color names on your system), since X display output is one that doesn't support masks in any other way. The default color is white.
-N
Forbids any of the image-reading routines from using an included preview, but does not prevent rendering of vector-based formats. Both the -t and -p options take precedence over this option.
-l
Enables reading "lower res" parts of an image, if the format supports it. But, unlike -p or -N, doesn't make PICTs the preferred preview, nor does it prevent using a preview if that's all that's available.
-m
Forces pixels to be clipped to a selected clipping path even if the output format supports clipping paths. Normally, either the clipping path is written or the pixels are clipped. This option makes both happen (if the output format supports clipping paths).
-n
Causes all Masks and Clipping paths to be ignored. If the option is -nc, only clipping paths will be ignored (except that PhotoShop-style clip resources will still be passed to those output formats that support them, unless the -k option is used). The option -nm will cause mask channels to be ignored, but still apply an active clipping path.
-q
Disables interlacing when making native JPEGs (interlacing never happens for JPEG-encoded EPSFs).
-W
Turns on watermarking for the output image. This is automatically turned on if the FullPress installation is not licensed. If the option is set to -W1, any custom watermark is overlayed only once on the image. By default, a watermark is tiled, pixel-for-pixel across and down the image as many times as it will fit.
-G
set the image to use as a grey-scale watermark to greyfile. This does not imply the -W argument, and is ignored if FullPress is unlicensed.
-B
set the image to watermark Indexed and 1-bit images to B&Wfile. This does not imply the -W argument, and is ignored if FullPress is unlicensed.
-V
use the watermark images set in the fpovolume options for watermarking. This does not imply the -W argument, and is ignored if FullPress is unlicensed.
-C
select the Cyan plate from the input image to render in greyscale. If filename is not in CMYK colorspace, it will be converted (unless it is already 1-bit or greyscale, in which case this option has no effect).
-M
like -C, but selects the Magenta plate.
-Y
like -C, but selects the Yellow plate.
-K
like -C, but selects the Black plate.
-S
If the image filename contains a spot color channel named colorname, this option will select that channel and output it in greyscale, just like the -C option.
-H
Causes any file that must be rendered (PDFs and vector EPS, for example) to be rendered in CMYK, regardless of what output colorspace was requested. Normally, the rendering is done in the colorspace set by the -c option. This option guarantees that Overprints in the image are preserved. Note that the -[CMYK] options imply this.
-E
Sets the `page' number (starting with 1) to render from files that can contain multiple images (like PDF). It is an error to ask for a page number that does not exist in the source file.
-i
By default, enabled spot colors will be merged with the colorspace channels and output in the image. This option excludes spot channels.
-k
Causes all non-pixel data (NAA records, paths, ICC profiles, etc.) to be omitted from the output image. One side-effect of this option is that pixels outside any active clipping path will be set to the background color (or masked, if the output format supports it). This can be avoided by also supplying the -nc option.
-L
For those input image formats that support separate ConTone/LineWork parts (like Tiff/IT), this option sets a preference for reading the LineWork part only. If the input image doesn't support a separate LineWork part, the entire image is read.
-T
Just like -L above, but sets the preference for the Continuous-Tone part of the image.
-u
Performs an Unsharp Mask (sharpening) filter over the image. This option has one argument, which can be one of the following. The number 0 causes the sharpening parameters to be read from the default system table (a file named default in the usm directory of the installed FullPress administration directory). A filename can be given, and the table will be read from that file. The argument can alternatively be 1 to 4 comma-separated numbers giving the parameters for the filter.

The sharpening parameters are: the radius, in pixels, of the blurring Aperture, which must be greater than 0.5 (and has no default); a percentage strength of the sharpening values to apply (default is 100), where anything zero or less disables the Unsharp Mask filter; a lower threshhold, in pixel intensity (0-255), below which no sharpening will occur (default is 0); and an upper limit on the sharpening that will be applied to the image (default is 255, and any number out of the 1-255 range will be ignored). A limit of 255 means no limit, a limit of 10 means limit the maximum amount of change to a pixel to 10 (in component intensity value units which are 0 - 255). Note that the Unsharp Mask parameters differ from PhotoShop in the radius only - add one to a PhotoShop Unsharp Mask Radius to get the equivalent sharpening from imagetox. Photoshop also does not have user control over a limit setting.

The Unsharp Mask arg can also be preceeded by a `+' character, which, if imagetox enlarges an image, causes the sharpening to happen before the image is expanded. By default, all sharpening is done after any scale factor has been applied.

-v
Causes a PC/Tiff-style preview to be generated along with the EPS output format. This option is ignored if EPS output is not selected.
-Q
Controls feature support for reading TIFFs. By default, alpha (mask) channels, spot colors and clipping paths are ignored in TIFFs. These features can be enabled if the input image is on a FullPress FPO-enabled volume with them turned on. With -Q alone, support for all the features is enabled. Otherwise, -Q can be immediately followed by a hex bitmask of features to enable. The features are:
1:  Alpha Channels 
2:  Spot color channels 
4:  Clipping paths 
 
Coincidentally, the argument -Q3 is equivalent to the Q3 key in fpovolopts(4) .
-U
Prevents Image Replacement from being attempted on PDF files that contain OPI comments.
-y -z
These two options affect conversions between CMYK and RGB colorspaces, but only when ICC is not in use. Without ICC, there are default table-driven conversions for both CMYK-to-RGB and RGB-to-CMYK. You may replace these tables by using one of these options along with a specially-formatted TIFF file (available from Xinet's website) containing the table. The -y option gives the TIFF filename to replace the CMYK-to-RGB table, and the -z option replaces the RGB-to-CMYK table.
-!
This option disables the inversion of CMYK channels when reading JPEG input files. It is useful for reading DCT-Encoded images stripped from PDFs.
-3
If the output format is eps and the input image contains a mask channel, this option enables true masked image output. The resulting file will not be valid for a PostScript interpreter that does not support Language-Level 3 masked images. It also, currently, will not be readable by imagetox.

Iptc

This section describes the possible naa argument values to set IPTC/NAA fields in the output image. The output formats that currently support NAA records are eps, tif, and jpg.

Arguments to the -e option can be a number, comma, and string, giving the field's item number and its value directly, or can be a filename. The contents of the referenced file must consist of item numbers alone on a line followed by one or more lines of text for the item, optionally followed by a blank line and more items. The file method is the only way to get multiple-line comments into the NAA record.

Below is a table mapping of well-known IPTC/NAA field numbers to their names. This is not a complete list of valid numbers. Any field numbers over 255 will be quietly ignored.


NumberIPTC/NAA field name
  5Object
 10Urgency
 15Category
 20Supplemental Categories
 25Keywords
 40Special Instruction
 55Date
 80By-Line
 85By-Line Title
 90City
 95Province/State
101Country/Primary Location Name
103Original Transmission Reference
105Headline
110Credit
115Source
116Copyright Notice
120Caption/Abstract
122Writer/Editor

Info Output

If the fmt is inf, the image pixel data is ignored, and only the image parameters are written to standard output, one per line. The format of the information is

parameter_name: value

where string values will be surrounded by double-quotes. The output is "human readable" but, with a small amount of text processing, can easily be converted to shell variables.

The complete table of possible parameters is given below. Every input image will write at least format and vector parameters, but the rest will vary with image format and contents. Also, be aware that inf is an output format, so the parameters can be affected by other command-line options. It's safest to include no other options along with the -xinf option.


ParameterType          Description
formatstringOne of the many formats supported by FullPress
vectoryes/noSays whether FullPress supports reading pixels
  out of the image. EPSF images can be yes or
  no depending on their contents
colorspace-One of: 1BIT, Grey, Index-RGB, Index-CMYK, RGB,
  Lab, CMYK, CMYK-1bit or unknown (for PDF or EPSF)
boundingboxfloats(EPSF only) the 4 values from the header comment
creatorstring(EPSF only) copied from the header comment
pagesinteger(PDF only) the number of pages in a PDF document
mediawidthfloat(PDF only) width, in 1/72 inch, of the page a PDF
  document was formatted for (for the first page)
mediaheightfloat(PDF only) vertical dimension, like mediawidth
rotateinteger(PDF only) page /Rotate value (in degrees), if present
widthintegerPixel width of image
heightintegerPixel height of image
hresfloatHorizontal resolution (in DPI)
vresfloatVertical resolution (in DPI)
maskyes/noWhether the image contains an alpha (mask) channel
clippathintegerGives the length of an embedded EPS-style clipping
  path (will be 0 if no path is included in the image)
profileyes/noWhether the image has an ICC profile embedded
spotsintegerGives number of spot channels included in image
spotname#stringEach spot color name, starting with 0
spotcolor#floatsCMYK values for each spot color
naayes/noWhether the image includes an IPTC/NAA record
NAAcategoriesintegernumber of Categories in IPTC/NAA record
NAAcategory#stringeach Category string, starting with 0
NAAkeywordsintegernumber of Keywords in IPTC/NAA record
NAAkeyword#stringeach Keyword string, starting with 0
NAA*stringvarious other IPTC/NAA information

Caveats on UNIX Systems

This program is NOT a Motif program, so does not take proper X arguments, nor does it respond correctly to window-manager events. It is not intended as a general purpose image viewer. If the image is displayed via X, a mouse click anywhere in the images will cause the window to close and program to exit.

See Also

X(1) , mkfpo(1) , opidebug(5) , opi(8)