Command: wcloth
Command: wclothwcloth <window>, <xmlfile>
Define the backcloth characteristics for a graphic window. A backcloth is one or more image files over which entity graphics are displayed.
Several layers (levels) of image files are permitted to accommodate different levels of detail.
<window>
A window identifier. It must be a graphic window.
<xmlfile>
The name of an xml file defining the backcloth characteristics. If <xmlfile>
is an empty string value, then the backcloth characteristics of the window
are set to null, i.e. no backcloth.
-q
Quiet mode. The default behavior during cloth redraws is for change-of-scale
messages to be displayed on the monitor. In quiet mode these messages
are suppressed.
The outer tag of the xml must be <cloth>.
Within the <cloth> tag, the following tags are available (they provide general information for the whole cloth system):
<level>subtags</level>
There must be at least one <level> tag present, each defining
a set of images to be displayed when the viewing scale is within the thresholds
defined by its <min>
and<max> sub-tags.
<interpolate>boolean</interpolate>
Whether or not to interpolate images. When this value is true (the default
is false), the pixels of images displayed at resolutions other than 1:1
are interpolated to enhance the result.
<stencil>tile</stencil>
A bitmap to be used as a stencil through which the image files are drawn.
By using for example a "greying" bitmap, the backcloths will appear
in a lower intensity than entity graphics.
<title>string</title>
A title to be displayed in messages, and when the image is displayed in
outline only.
<thresholds>string</thresholds>
Whether the scale thresholds (defined by the ‘min’ and ‘max’ phrases) are
pixel factors or screen scales. Only the values pixel_factor or screen_scale
are permitted. When pixel factors are used, min and max refer to the ratio
of world pixels to screen pixels, i.e. window.pixel_factor
(adjusted by any change of units.) When screen scales are used, min and
max refer to the true scale, i.e. window.scale.
The default value is pixel_factor.
<units>string</units>
The unit of measurement for the cloth coordinate system. If omitted, the
units are dynamic and are assumed to be the current modeling units when
the cloth is drawn. This can create a problem if an application redefines
what the current modeling units are. Including this phrase ensures the correct
cloth scaling whatever the current modeling units.
Within the <cloth> tag, the following tags are available and their values are inherited by images defined within levels unless overridden within the <level> tag:
<angle>numeric</angle>
A rotation angle (counter-clockwise) for images. The default value is 0.
<background>color</background>
The background color for images, if they have changeable backgrounds, when
displayed on a color workstation. The default color for monochrome images
is that of the graphic window in which the cloth is displayed.
<foreground>color</foreground>
The foreground color for images, if it is monochrome, when displayed on
a color workstation. The default value black.
<justification>string</justification>
The justification of the images relative to their geo-location. The usual
suspects are permitted, i.e. TL, M, BR etc. The default
value is TL.
<view>string</view>
An indication of the view on which images are to be shown, typically plan,
although the following values are permitted: north, south,
east, west and under. The default is plan.
Within each <level> tag, the following tags are available:
<cache>boolean</cache>
If this has a true value, this implies that image file contents on
this level should be cached to help speed up retrieval and display times.
Caching should only be used when there are a few files in a level (e.g.
less than eight) likely to be in view at any one time. Caching many files
can severely impair performance. The default behavior is not to cache.
<image>subtags</image>
Details of an image to be included on this level. There can be as many of
these tags as necessary.
<interpolate>boolean</interpolate>
Whether or not to interpolate images on this level. When this value is true (the
default value is inherited from the outer tag), the pixels
of images displayed at resolutions other than 1:1 are interpolated to enhance
the result.
<max>numeric</max>
The maximum scale at which this level of images can be drawn. If the current
window ‘scale’ is greater or equal to this value then the previous level
of image files is displayed, or none if this is the first level in the hierarchy.
See the <thresholds> tag for the meaning
of scale. Omitting this will use the <min> of the previous
level. For the first level it can be used to indicate a scale beyond which
the cloth is no longer displayed.
<min>numeric</min>
The minimum scale at which this level of image files can be drawn. If the
current window ‘scale’ is less than this value then the next level of images
is displayed, or none if this is the last level in the hierarchy. See the
<thresholds> tag for the meaning of
‘scale’. Omitting this will use the <max> of the next level.
For the last level it can be used to indicate a scale beyond which the cloth
is no longer displayed.
<pixel_factor>numeric</pixel_factor>
The pixel factor for images within the level. This provides the number of
world units which each pixel of an image represents. Current modeling units
are assumed unless the <units> tag is
present. This may be overriden on a per-image basis within the <image>
or <tileset> sub-tags. If one numeric value is included this
applies to both x and y axes of an image. If two (commas-separated) values
are present they define the x and y factors respectively. Omitting this
will use the pixel_factor values of the first <image>
or <tileset> sub-tag.
<tileset>subtags</tileset>
Details of a set of contiguously tiled images. There can be as many of these
tags as necessary. Within a tile set, the tiles are arranged in an m x n
matrix, they all have the same scale, the same pixel dimensions (apart from
optionally the right most and bottom most of the matrix), and they touch
along their edges, producing a seamless tapestry.
<title>string</title>
A title or description associated with this level. Typically this is used
to describe the resolution of the images, and is displayed by various messages
at display time.
<transparent>boolean</transparent>
If included, this implies that the images on this level are transparent
and should be overlayed on top of previous levels of image file. The default
value is false.
Within a <level> tag, the following tags are available and their values are inherited by images within the level unless individually overridden within the <image> or <tileset> sub-tags. If they are omitted, they inherit any values set by the enclosing <cloth> tag.
<angle>numeric</angle> details
<background>color</background> details
<foreground>color</foreground> details
<justification>string</justification> details
<view>string</view> details
An <image> tag defines an image to be displayed within its parent level. Within each <image> tag, the following tags are available:
<file>string</file>
The name of the file containing the image.
<clip>numeric,numeric,numeric,numeric</clip>
Restrict display of the image to a partial rectangle. The 4 values are image
pixel values: start x, start y, finish x, finish y, 0,0 being the top-left
pixel of the image. Restriction can also be specified in world units using
the <mbr> tag.
<dims>numeric,numeric</dims>
The dimensions of the image in pixels (width,height). This can be omitted
in which case the file will be queried for its dimensions.
<geo>point</geo>
The world coordinates corresponding to the key position. If omitted, the
value (0,0,0) is assumed. Current modeling units are assumed unless the
<units> tag is present. This can be omitted
if the image file defines its own geopositioning, e.g. ECW.
<key>numeric,numeric</key>
The key position in the image used to locate the image in world space. The
two numeric values corresponding to x,y pixels in the image where 0,0 is
the top-left corner of the image. If omitted the
<justification> is used to
locate the image. Don't forget, image y ordinates run from top to bottom.
<mbr>point,point</mbr>
Restrict display of the image to a partial rectangle. The 2 values are corners
of a maximum bounding rectangle measured in world space (in the same units
as the <geo> value). Restriction
can also be specified in image pixels using the <clip> tag.
<title>string</title>
A title or description associated with this image. This may be displayed
by various messages at display time.
Within an <image> tag, the following tags are available. If they are omitted, an image will inherit any values set by the enclosing <cloth> or <level> tags.
<angle>numeric</angle> details
<background>color</background> details
<foreground>color</foreground> details
<justification>string</justification> details
<pixel_factor>string</pixel_factor> details
<view>string</view> details
If the image file defines its own geopositioning, e.g. ECW, the <pixel_factor> tag may be omitted. Remember, the <angle> tag may not be used in conjunction with the <clip> or <mbr> tags.
A <tileset> tag defines a matrix of contiguous tiled images to be displayed within its parent level. Within each <tileset> tag, the following tags are available:
<file>string</file>
The name template for resolving the file names of images in the matrix.
The parameters $x$ and $y$ should be used in the template for resolving
file names, e.g. a value tile_$x$_$y$.jpg would resolve into the
following file names for a 3 x 2 matrix:
tile_1_1.jpg tile_2_1.jpg tile_3_1.jpg
tile_1_2.jpg tile_2_2.jpg tile_3_2.jpg
It follows from this that the image file names must be named appropriately for this to work.
<default_file>string</default_file>
The name of an image file to be used if a tile cannot be found. A typical example
for this is when a tiled map contains many tiles with no detail, e.g. sea or desert.
This facility therefore reduces the number of image files on disc.
Note: the file corresponding to the first tile in the matrix (i.e. the top-left
tile) must exist.
<dims>numeric,numeric</dims>
The dimensions of the each image in pixels (width,height). This can be omitted
in which case the file will be queried for its dimensions. All images (except
those in the rightmost column and bottom row) must have the same dimensions.
<geo>point</geo>
The world coordinates corresponding to the key position of the top left
image in the matrix. If omitted, the value (0,0,0) is assumed. Current modeling
units are assumed unless the <units>
tag is present.
<key>numeric,numeric</key>
The key position in the top left image in the matrix, used to locate the
image in world space. The two numeric values corresponding to x,y pixels
in the image where 0,0 is the top-left corner of the image. If omitted the
<justification> is used to locate
the image. Don't forget, image y ordinates run from top to bottom.
<matrix>numeric,numeric</matrix>
The configuration (columns, rows) of the matrix of images, e.g. a value
3,4 would indicate a matrix of 3 columns and 4 rows, 12 images in total.
<residue>numeric,numeric</residue>
The dimensions (width,height) of the bottom right image of the matrix. This
can be omitted in which case the relevant image file will be queried for
its dimensions. This will provide the width of all images in the right column,
and the height of all images in the bottom row.
<title>string</title>
A title or description associated with this tile set. This may be displayed
by various messages at display time.
Within an <tileset> tag, the following tags are available. If they are omitted, images inherit any values set by the enclosing <cloth> or <level> tags.
<angle>numeric</angle> details
<background>color</background> details
<foreground>color</foreground> details
<justification>string</justification> details
<pixel_factor>string</pixel_factor> details
<view>string</view> details
A window's backcloth characteristics may also be set to the contents of a file by setting the window.cloth attribute to the name of the xml file.
Earlier versions of Fire had a non-xml cloth definition. This is still supported but its use is discouraged because it will eventually be dropped. It can be reviewed here.
This command will also add a cloth layer to the window's window.layers
array.
To illustrate image interpolation
(specified via the interpolate tag) compare the
2 images below. The left image has interpolation on, the right image has interpolation
off. Both are shown in a graphic window with a yellow background, with a file-to-screen
pixel resolution of 6.
Consider an xml definition:
<?xml version="1.0" encoding="ISO-8859-1"?>
<cloth>
<title>Wilmington Test Cloth</title>
<thresholds>pixel_factor</thresholds>
<units>m</units>
<justification>TL</justification>
<level>
<title>Based on 8 meter image</title>
<pixel_factor>8</pixel_factor> <max>50</max>
<image>
<dims>638,638</dims>
<file>c:/delaware/layout/lev8/1_1.jpg</file>
<geo>186900,196200</geo>
</image>
</level>
<level>
<title>Based on 2.5 meter image</title>
<pixel_factor>2.5</pixel_factor>
<tileset>
<matrix>3,3</matrix>
<dims>680,680</dims><residue>680,680</residue>
<file>c:/delaware/layout/lev2.5/$x$_$y$.jpg</file>
<geo>186900,196200</geo>
</tileset>
</level>
<level>
<title>Based on 1 meter image</title>
<pixel_factor>1</pixel_factor>
<tileset>
<matrix>8,8</matrix>
<dims>680,680</dims><residue>340,340</residue>
<file>c:/delaware/layout/lev1/$x$_$y$.jpg</file>
<geo>186900,196200</geo>
</tileset>
</level>
<level>
<title>Based on 0.25 meter image</title>
<pixel_factor>0.25</pixel_factor> <min>0.1</min>
<tileset>
<matrix>30,30</matrix>
<dims>680,680</dims><residue>680,680</residue>
<file>c:/delaware/layout/lev0.25/$x$_$y$.jpg</file>
<geo>186900,196200</geo>
</tileset>
</level>
</cloth>
The above code, stored in a file named clothinfo.xml, could be assigned to a window by the following:
wcloth win1, clothinfo.xmlor
win1.cloth = 'clothinfo.xml'
|
Commands: |
|
|
Structures: |
window (graphic), window.cloth_layers, window.layers |
