Writer Directives

The directives processed by the GIF Writer are listed below. The suffixes shown are prefixed by the current <WriterKeyword> in a mapping file. By default, the <WriterKeyword> for the GIF writer is GIF. FME provides a synonym for the GIF writer when it is being used to generate PNG files, and in that case, the writer type and default <WriterKeyword> are PNG.

DATASET

The value for this keyword is the name of the GIF or PNG file to be created. If a file of this name exists, it is replaced by the new GIF.

Required/Optional

Required

Mapping File Syntax

A typical mapping file fragment specifying an output GIF dataset looks like:

GIF_DATASET /tmp/92i080.gif

A typical mapping file fragment specifying an output PNG dataset looks like:

PNG_DATASET /tmp/92i080.png

The PNG and GIF writers are internally identical, so the actual naming of the output file determines what the output will be. If a GIF writer or PNG writer is given a dataset ending in .png or .PNG it will generate a PNG file; otherwise, it will generate a GIF.

DEF

Required/Optional: Required

The GIF writer uses GIF_DEF lines to define colors. The names given to colors are used as the feature types of features destined for the GIF writer. The GIF writer will allocate a color index in the GIF's color table for this color, and this index will be used the pixel value for features whose feature type matches the color name.

Up to 255 different 24-bit colors may be defined. If the GIF writer cannot allocate a color exactly – perhaps due to the color table being partially filled with a background image’s colors – it assigns a color value as close as possible to the one requested.

Mapping File Syntax

The syntax of a GIF DEF line is:

<WriterKeyword>_DEF <colorName>	\
	GIF_RED <redValue> \
	GIF_BLUE <blueValue> \
	GIF_GREEN <greenValue>

The red, green, and blue values must be between 0 (low intensity) and 255 (highest intensity), and if they are not specified, then 0 is assumed. The color components be specified in any order.

The mapping file fragment below defines two GIF colors:

GIF_DEF white GIF_RED 255 GIF_GREEN 255 GIF_BLUE 255
GIF_DEF black GIF_RED 0   GIF_GREEN 0   GIF_BLUE 0

WIDTH

This directive defines the width of the output GIF file in pixels.

Note that when the SQUARE_PIXELS directive is set to YES, the width of the output image may not necessarily be equal to the width specified in this directive, as the number of pixels will be modified in order to make each pixel cover a square area in ground units. This adjustment occurs when the aspect ratio of the desired GIF does not match the aspect ratio of the input data’s bounding box.

Required/Optional

Required

Mapping File Syntax

The syntax of a GIF WIDTH line is:

<WriterKeyword>_WIDTH <widthInPixels>

HEIGHT

This directive controls the height of the output GIF image, in pixels.

As with the WIDTH directive, when the SQUARE_PIXELS directive is set to YES, the height of the output image may not necessarily be equal to the height specified in this directive.

Required/Optional

Required

Mapping File Syntax

The syntax of a GIF HEIGHT line is:

<WriterKeyword>_HEIGHT <heightInPixels>

The GIF writer scales the source feature data to fit it into the desired image size. However, it ensures that all pixels remain square in terms of the original ground units of the features. This results in a blank band of background being present across either the bottom or the right-hand side of the produced image if the aspect ratio of the image did not match the aspect ratio of the input source data. In the future, an option to clip off this blank band will be introduced in to the software.

GROUND_RANGE

This directive fixes the area that the GIF image will cover in ground units. If this is not specified, the GIF covers the minimum bounding rectangle of the feature data. If necessary, the ground coverage is adjusted, not the size of the image in pixels, to maintain squareness of pixels. For this reason, the aspect ratio of the GROUND_RANGE setting must be the same as the aspect ratio of the height and width to ensure that the image provides exactly the desired coverage.

Required/Optional

Optional

Mapping File Syntax

The syntax of a GIF GROUND_RANGE line is:

<WriterKeyword>_GROUND_RANGE <xmin> <xmax> <ymin> <ymax> \

SQUARE_PIXELS

This flag controls whether the pixels of the GIF produced will have the same height as width. If the value is YES, which is the default, the ground range is fit into the output GIF image (each pixel in the generated GIF will have the same height as width). If necessary, some of the output image is left in the background color providing the aspect ratio if the input data did not match that of the output image. If the value is NO, then the pixels are stretched to fill the entire output image (the pixel height and width are adjusted to completely fit the ground range of the data into the GIF).

Required/Optional

Optional

Values

YES (default) | NO

Mapping File Syntax

<WriterKeyword>_SQUARE_PIXELS (YES|NO)

BACKGROUND_COLOR

This setting establishes the color index of the image background and is required if a BACKGROUND_PATTERN is not specified. The color must have previously been defined in a GIF_DEF line. One of BACKGROUND_COLOR or BACKGROUND_IMAGE must be supplied.

Required/Optional

Optional

Mapping File Syntax

The syntax of a GIF BACKGROUND_COLOR line is:

<WriterKeyword>_BACKGROUND_COLOR <colorName>

The colorName must be defined in a GIF_DEF statement.

BACKGROUND_IMAGE

Contains the file name of a GIF file to be used as the background for the produced image. Lines, polygons, text, and points are drawn on top of this image. If the image is smaller than the size of the output GIF, it is tiled to fill the output image. One of BACKGROUND_COLOR or BACKGROUND_IMAGE must be supplied.

Required/Optional

Optional

Mapping File Syntax

<WriterKeyword>_BACKGROUND_IMAGE <backgroundGIF>

The backgroundGIF must be the name of a valid GIF file.

INTERLACE

Controls whether or not the created GIF will be interlaced. If the value is YES, the GIF will be interlaced. If the value is NO, then the GIF will not be interlaced.

Interlacing is used most often in web applications, as an interlaced GIF gives the illusion of being displayed quicker than a non-interlaced GIF.

Required/Optional

Optional

Values: YES | NO

Default Value: YES

Mapping File Syntax

<WriterKeyword>_INTERLACE (YES|NO)

TRANSPARENT_COLOR

This flag sets the transparent color index of the image. Applications that interpret this will show the background through any pixels with this color when the image is displayed.

Required/Optional

Optional

Mapping File Syntax

The syntax of a GIF TRANSPARENT_COLOR line is:

<WriterKeyword>_TRANSPARENT_COLOR <colorName>

The colorName must have been previously defined in a GIF_DEF statement.

TRIM_UNUSED

This flag indicates whether rows or columns of pixels in the image which are not in the ground range of the feature data should be trimmed out of the image. This setting is ignored when square pixels are not forced. If it is specified as NO, then any unused rows or columns of pixels will remain blank in the output image.

This setting is only used when SQUARE_PIXELS is set to YES.

Required/Optional

Optional

Values: YES | NO

Default Value: NO

Mapping File Syntax

<WriterKeyword>_TRIM_UNUSED (YES|NO)

PAD_PERCENTAGE

This percentage value between 0 and 100 controls how much of a border the generated GIF will have. The size of the border is measured as a percentage of the image size. This is typically used to allow annotation at the edge of the scene that would otherwise be clipped to spill into a border around the image. The border is added after any unused pixels are trimmed when the TRIM_UNUSED flag has been set.

Required/Optional

Optional

Mapping File Syntax

The syntax of the PAD_PERCENTAGE line is:

<WriterKeyword>_PAD_PERCENTAGE <numberFrom0To100>

IMAGE_MAP_FILE

This sets the filename which will hold the HTML code for the generated client-side image map that can be used in conjunction with the produced GIF to produce a clickable image. A full path name should be specified. If this parameter is not specified, then no image map will be produced.

Required/Optional

Optional

Mapping File Syntax

The syntax of a GIF IMAGE_MAP_FILE line is:

<WriterKeyword>_IMAGE_MAP_FILE <pathname>

After the translation has completed, the file will contain the HTML code for an image map corresponding to the created image. The image map will contain entries for point, line, and polygon features which had a gif_href attribute. Polygons will appear only if they had an area greater than the minimum area threshold, and lines will appear only if they had a length greater than the minimum line length threshold. Points and lines are buffered by a specified number of pixels to form polygons within the image map, but not within the actual image.

Minimum area and line length thresholds, and point and line buffering, are described later. An example image map would look like this:

A web page that included this HTML would also include the generated GIF with a line like this:

The points, lines, and polygons are arranged in the image map such that all lines lie on top of all polygons, and all points lie on top of all lines. This prevents points being obscured by lines or polygons, and prevents lines from being obscured by polygons.

IMAGE_MAP_NAME

The name which will be used for the produced image map. This is only used when an image map is created. The default is IMAGEMAP. This name will be used in a web page.

Required/Optional

Optional

Mapping File Syntax

The syntax of a GIF IMAGE_MAP_NAME line is:

<WriterKeyword>_IMAGE_MAP_NAME <mapName>

IMAGE_MAP_MIN_AREA

Required/Optional: Optional

This value controls the minimum area a polygon must have before it will have an entry in the image map. Features with areas less than this will not have any entries in the image map. The default is 0.

Mapping File Syntax

The syntax of a GIF IMAGE_MAP_MIN_AREA line is:

<WriterKeyword>_IMAGE_MAP_MIN_AREA <minArea>

IMAGE_MAP_MIN_LINE_LENGTH

This value controls the minimum length a line must have, in ground units, before it will have an entry in the image map. Features which are shorter than this will not have any entries in the image map. The default is 0.

Required/Optional

Optional

Mapping File Syntax

The syntax of a GIF IMAGE_MAP_MIN_LINE_LENGTH line is:

<WriterKeyword>_IMAGE_MAP_MIN_LINE_LENGTH <minLineLength>

IMAGE_MAP_BUFFER_SIZE

Lines and points are entered into the image map by computing a buffer around the line, and inserting the resulting polygon. This value controls the amount of buffering applied to the line and points, measured in pixels. The default is 2.

Required/Optional

Optional

Mapping File Syntax

The syntax of a GIF IMAGE_MAP_BUFFER_SIZE line is:

<WriterKeyword>_IMAGE_MAP_BUFFER_SIZE <bufferSize>IMAGE_MAP_POLY_GENERALIZE_TOLERANCE

Polygons are generalized before being entered into the image map in order to reduce the size of the image map.

This value specifies the tolerance (in pixels) for this generalization operation. Note that a tolerance of 0 means only collinear points will be removed, and the image map should match the input polygon exactly. The default value is 2.

Required/Optional

Optional

Mapping File Syntax

<WriterKeyword>_ IMAGE_MAP_POLY_GENERALIZE_TOLERANCE <tolerance>

ESTIMATE_TEXT_BOUNDS

If this option is set to 'yes', the GIF writer will take the bounds of text into account when it scales the input features.

Required/Optional

Optional

Values

YES (default) | NO

Mapping File Syntax

<WriterKeyword>_ESTIMATE_TEXT_BOUNDS (YES|NO)

Workbench Parameter

Estimate text bounds