legend - create a multi-line text legend metafile based on input dataset

legend - Create a multi-line text legend metafile based on input dataset

SYNOPSIS

legend  [ parameter=value ...]  [ inputfile outputfile ]
legend  [ parameter=value ...]  [ inputfile ... directory ]

Parameters are: line_n, text_height, text_type, line_offset, sample_offset, full_width, center_text, outline, solid_bg, compute_latlon, display .

DESCRIPTION

This function is used to create a multi-line text legend metafile relative to a given input dataset. The size of the image over which a given legend will be drawn is determined from the corresponding input dataset.

A legend can consist of up to 8 text lines, and optionally can have a solid color background and/or an outlining rectangle. Text and outline are defined with one color, the solid background with a second color.

The size of the background and outline rectangle are automatically computed, based on the text height and type, which are user-specified. Optionally, legends can be defined so they are as wide as the image. Lines of text can be centered relative to the background, or can be left justified. Legend placement is controlled by user-specified offsets from the edges of the image.

A legend may include attributes of the corresponding input dataset. The string %attribute-name is replaced by attribute-value. For example, %satellite might be replaced by noaa-11. Dates, times, latitudes, and longitudes are expanded using standard output formats (See formats). If there is no value for a particular attribute, no substitution occurs. If a % character is required in a legend, it must be preceded by the escape character \.

A special parameter is provided for fixing the center_lat and center_lon attributes so they reflect the true center of the input image. Ordinarily, these attributes help define the map projection and do not necessarily coincide with the center of the data. Subsetting an image registered to a map projection can cause such a discrepancy.

legend can be run only when the X server is running. The X server is needed to get text width and line spacing information.

PARAMETERS

line_n: The user is prompted for text lines line_1, line_2, and so on until a blank line is entered. If a blank line is needed in a legend, an escape character \, following by a carriage return will give the desired results. There is no default for the first line_n parameter.

text_height: This parameter defines the height of the text to be used in the legend. The default value is 18. The valid range is [12, 30].

text_type: This parameter defines the type (font) of text to be used in the legend. Valid responses are plain, bold, and italic. The default is plain.

line_offset: This parameter controls vertical legend placement. If line_offset is non-negative, it specifies the number of pixels between the top of the image and the top of the legend. If line_offset is negative, it specifies the number of pixels between the bottom of the legend and the bottom of the image. Valid responses are any integer. The default is 0.

sample_offset: This parameter controls horizontal legend placement. If sample_offset is non-negative, it specifies the number of pixels between the left edge of the image and the left edge of the legend. If sample_offset is negative, it specifies the number of pixels between the right edge of the legend and the right edge of the image. Valid responses are any integer. The default is 0.

full_width: This parameter determines whether or not legend width will be forced to be the same as image width. Valid responses are [yes, no]. The default is no.

center_text: This parameter determines whether or not each text line will be centered horizontally within the legend. Valid responses are [yes, no]. The default is no.

outline: This parameter determines whether or not an outline will be drawn around the legend. Valid responses are [yes, no]. The default is no.

solid_bg: This parameter determines whether or not a solid background will be drawn behind the legend. Valid responses are [yes, no]. The default is yes.

compute_latlon: OPTIONAL. This parameter determines whether center_lat and center_lon attributes are to be computed or used as is. Valid responses are [yes, no]. The default is no, i.e., used as is.

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

% legend
in/out files   : char(255) ? n11.93195.1103 n11.93195.1103.legend
line_1         : char(255) ? This is an example of adding a Legend
line_2         : char(255) ? [] to a dataset.
line_3         : char(255) ? []
text_height    : int       ? [18] 12
text_type      : char(  6) ? [plain] italic
line_offset    : int       ? [0] -10
sample_offset  : int       ? [0] -15
full_width     : char(  3) ? [no]
center_text    : char(  3) ? [no] yes
outline        : char(  3) ? [no] yes
solid_bg       : char(  3) ? [yes]
%