xinject - renders metafiles, injecting them into image variables

xinject - Renders metafiles, injecting them into image variables

SYNOPSIS

xinject  [ parameter=value ... ]  [ inputfile ... outputfile ]

Parameters are: bg_var_name, colors_per, meta_colors, line_widths, line_types, marker_types, marker_sizes, image_colors, display .

DESCRIPTION

xinject renders up to eight metafiles, injecting them into a user-specified image background variable. The first inputfile is assumed to contain the background variable. The other inputfiles are assumed to be metafiles. After the metafiles have been injected into the background variable, it is written to the newly created outputfile.

For each input metafile, pixels are injected into the background with up to three different values, according to the colors_per parameter. (Most metafiles usually involve a single color, so colors_per can be 1; however, some metafiles, such as those created by the legend function, require colors_per to be greater than 1.)

The values can change for each input metafile. For example, if there are two input metafiles, Coast and Grid, then Coast lines can be injected into the background with one value, and Grid lines can be injected into the background with a different value.

These values, called meta_colors, must be specified as if the background variable is unscaled. For example, if data for the background variable is stored as 8-bit byte quantities, the meta_colors must be specified in the range [0,255], regardless if the variable is scaled or not.

Different line widths, line types, marker types, and marker sizes can be used for each input metafile. This only works when these values are not hard-coded into the metafile data, which is normally the case, but not the rule.

The background variable can be any datatype except string. However, color wedges can only be injected into byte-valued backgrounds. Also for byte-valued background variables, meta_colors outside the range [0, 255] are drawn by inverting the background; e.g., so lines would appear light over a dark background, or dark over a light background.

xinject can be run only when the X server is running. xinject declares an 8-bit XPixmap and an XImage the same size as the background variable, renders the metafile graphics into the XPixmap, and reads the results back into the XImage. The metafile-to-X rendering engine is the same as the one used by xvu.

If the background variable is byte-valued, it is written into the XPixmap before any rendering occurs. Then, the N-th metafile is rendered with its actual meta_colors. After reading the XPixmap back into the XImage, xinject immediately writes the XImage data to the output dataset.

If the background variable is not-byte valued, the XPixmap is initialized with value 255, and the N-th metafile is rendered with fake meta_colors N*colors_per through N*colors_per - colors_per -1, where N starts at 0. After reading the XPixmap back into the XImage, xinject uses these fake colors to tell how true meta_colors are to be injected into the background.

PARAMETERS

bg_var_name: This is the name of the variable to be used as the background. The variable must exist in the first input file. Background variables can be any datatype except string. There is no default.

colors_per: This is the number of meta_colors per input metafile. The valid range is [1, 3]. The default is 1.

meta_colors: This is a list of real pixel values to inject. The number of colors per input metafile is determined by colors_per. All the meta_colors for the first metafile are listed first, followed by all meta_colors for the second metafile, etc. There is no default.

line_widths: This is a list of line widths to use, one for each input metafile. The valid range is [1, 5]. The default value for each input metafile is 1.

line_types: This is a list of line types to use, one for each input metafile. Valid line types are [solid, dashed, dotted and dashdot]. The default value for each input metafile is solid.

marker_types: This is a list of marker types to use, one for each input metafile. Valid maker types are ['.', '+', '*', 'o', and 'x']. The default value for each input metafile is '+'.

marker_sizes: This is a list of marker sizes to use, one for each input metafile. The valid range is [1, 100]. The default value for each input metafile is 15.

image_colors: This is the number of image colors in the background variable. This parameter is only of interest when the background variable is byte-valued and one of the input metafiles contains an image color wedge. This allows the wedge to be drawn with colors in the range [0, image_colors -1]. The valid range is [2, 256]. The default is 216.

display: OPTIONAL. This is the name of the display on which the X server is running. Valid responses are typically of the form hostname:0. The default is :0.

EXAMPLES

This is an example that will take a wedge and legend metafile and inject them into an image background variable. This is a nice feature to utilize for repetitive image production of a given area. Make sure the image is registered. imscale must be run on the registered dataset before xinject can be performed.

When running coast, refer to the coast man page for details on specific file names used to run coast for states, boundaries, etc.

Be sure to inject the overlays in the order that you would like the overlays to appear. If you inject a wedge then the coast, the coast will overlay on top of the wedge. This will not look very appealing.

lapaz% xinject
in/out files   : char(255) ? TEXASIM Coast Wedge legend TEXAS.inject
bg_var_name    : char( 31) ? avhrr_ch3
colors_per     : int       ? [1] 2
meta_colors    : real(  4) ? 215 0 215 0 215 0
line_widths    : int (  2) ? [1 1 1]
line_types     : char( 15) ? [solid solid solid]
marker_types   : char(  3) ? [+ + +]
marker_sizes   : int (  2) ? [15 15 15]
image_colors   : int       ? [216]
lapaz%

NOTES

Text characteristics were not included among the parameters. The reasoning was that these characteristics are generally hard-coded into metafiles used with xinject, such as metafiles generated by the legend or wedge functions.

The actual text fonts used are determined by the rendering engine, based on metafile text height and type primitives. Currently, the renderer uses Courier as the base font for all text.