The first part of this appendix describes the types and formats of data supported by the Map Visualizer. Data input to the Map Visualizer must be provided as a single file containing raw data, usually in a tab-separated ASCII text form.
The second part discusses the configuration file, which describes how the Map Visualizer reads in, and displays, the data file.
Both the data and configuration files can be generated automatically by the Tool Manager (see Chapter 3).
In its simplest form, the data file consists of a list of lines, each containing a set of fields separated by one tab. (Other separators are also allowed, but only one can separate each field. See “Input options”.) All lines must contain the same fields. The interpretation of the fields is specified by the configuration file, described in “The Configuration File”. Using the U.S. population data (examples/population.usa.data file), provided as part of the Map Visualizer package, the first few lines of this input file appear as shown below:
AL 0 0 0 1000 9000 127901 309527 590756 771623 964201 996992 1262505 1513401 1828697 2138093 2348174 2646248 2832961 3061743 3266740 3444354 3894025 4040587 51705 AR 0 0 0 0 1000 14000 30000 98000 210000 435000 484000 803000 1128000 1312000 1574000 1752000 1854000 1949000 1910000 1786000 1923000 2286000 2351000 53187 AZ 0 0 0 0 0 0 0 0 0 0 10000 40000 88000 123000 204000 334000 436000 499000 750000 1302000 1775000 2717000 3665000 114000 CA 0 0 0 0 0 0 0 0 93000 380000 560000 865000 1213000 1485000 2378000 3427000 5677000 6907000 10586000 15717000 19971000 23668000 29760021 158706 |
In this example, the first column is a two-character string identifying the graphical object—the state. (This string locates a record in a .gfx file containing information about the shape of the graphical object.) The tab separator is followed by a grouping of 23 numeric values, which represent the state's population from 1770 through 1990, in 10-year increments. The next tab separator is followed by a single numeric value, which specifies the state's area in square miles.
The data file cannot contain blank lines or comments. Missing or extra data on a line causes an error.
Any field in the data can also be a “?”, indicating that the data is null (unknown). See Appendix J, “Nulls in MineSet.”
The Map Visualizer supports integer, floating point number, and string data types, as well as arrays of these types. The following data types are supported:
float represents a single-precision floating point number. The decimal point is optional. Numbers in exponential “e” notation are also accepted.
double represents a double-precision floating point number. The decimal point is optional when representing a floating point number. Numbers in exponential “e” notation are also accepted. The superior precision of double can be useful for accurately representing large numbers, since float can represent only seven or eight significant digits accurately. This superior accuracy, however, consumes twice the memory space of float.
dataString represents a string that is unlikely to appear multiple times. If it appears multiple times, multiple copies are made.
string represents a string of characters that can appear multiple times in the data file. Unlike a dataString, only a single copy of a given string is stored in memory, no matter how many times it appears in the data. This saves memory for strings appearing many times.
Comparing strings is also much quicker than comparing dataStrings. Processing is somewhat slower when looking for duplicate strings as they are read in. An example of string use is for a division name that appears once for each department in the division. If you are unsure whether to use a string or a dataString, use a string.
fixed string represents a string of fixed length. Like a dataString, if a fixed string appears multiple times, multiple copies are made. In general, fixed strings are used internally for representations of data from data bases, and are generally better to use than strings or dataStrings.
date represents a date and time. In the data file, date must appear in the format MM/DD/YY HH:MM:SS.
With the Map Visualizer, you can use one- or two-dimensional arrays of fixed size. In a fixed-sized array, all entries of the given type have the same number of values. Arrays contain the data values across one or two independent variables, that is, those dimensions controlled by the sliders.
A variant of the “enumerated array” is the “null enumerated array.” This is a variant of the enumerated array with an additional entry at the beginning for null, which is represented by “?”. See “Enumerated Arrays” in Appendix B for a discussion of enumerated arrays.
The configuration file format is flexible. Words in it must be separated by spaces, and it is case-sensitive. Except for the include statement and text within quoted strings, spacing and line breaks are irrelevant.
The configuration file's structure and grammar are explained in the following sections.
The configuration file consists of a series of sections, each of which has the following syntax:
sectionKeyword
{
statements...
}
|
where sectionKeyword names the section. A semicolon (;) can follow the closing brace (}) but is not required. The order of the sections is significant, since sections can refer to variables defined in previous sections.
As each section is encountered, a special configuration file (referred to as a defaults file) is also read in. The defaults file has the same name as the section. Defaults files contain options statements. These files are searched in the following order, as specified by the X-resource Mapviz*configPath in the file /usr/lib/X11/app-defaults/Mapviz.
Files with the same name can appear in more than one of the above-named directories; in this case, the order given is the one in which the directories are read. If the same option is found in multiple files, the last option read is used. Note that the appropriate section in the configuration file is read after all the defaults files; thus, options in the configuration file override those in the defaults files.
A statement has the following syntax:
statementKeyword info ; |
where statementKeyword defines the statement, and info varies according to the keyword. A statement can be another section (using the brace format defined under “Sections”).
A variable name can appear in two formats:
In the first format, it is a letter followed by a number of letters, digits, or underscores. It cannot be a keyword, and should not be placed in quotation marks.
In the alternate form, the variable name should be surrounded by back quotes (`). In this form, the variable name can match a keyword, and can contain even non-alphanumeric characters. The primary purpose of this second form is for configuration files generated automatically by the Tool Manager.
There is no scoping of variable names; a given variable name can be declared only once in the configuration file.
Many sections have options statements, which have the syntax:
options key info, key info... ; |
where key defines the specific option, and info depends on the key. In some cases, the key can be more than one word. To maximize the number of allowable variable names, most option keys are meaningful only within the appropriate option statement; keys do not conflict with variable names. You can declare several options on the same line, separating them by commas or placing them in several options statements. If two conflicting values for the same option appear, the last value is taken.
The configuration file may contain lines of the form
include "filename" |
These lines can appear anywhere in the configuration file, but each must be on its own line. The filename must be in quotes; anything after the closing quote is ignored. The number of nested includes is unlimited. If a relative pathname (one not beginning with a slash) is specified, the file is first sought in the directory containing the current configuration file. If include statements are present, this might not be the same as the initially loaded configuration file. If it is not found in the directory containing the current configuration file, the include file is sought in the current directory. If the file is not found, an error message appears.
A statement similar to an include is sinclude, which has the syntax:
sinclude "filename" |
This is identical to the include statement, except that no error is given if the file does not exist; instead, the sinclude statement is ignored.
Strings and characters in the configuration file follow C conventions. Strings are in double quotation marks (“), and characters are in single quotation marks ('). All standard backslash conventions are followed (for example, \n represents a new line).
Comments begin with a pound (#) symbol at the beginning of a line; anything after this symbol to the end of the line is ignored.
The currently recognized keywords are listed below. Variables can not have these names unless they are surrounded by back quotes (`). Tokens appearing only in option statements are not keywords, and can be used for variable names.
Table C-1. Keywords for the Map Visualizer
|
|
|
|
|---|---|---|---|
buckets | expressions | level | outlines |
color | file | map | scale |
colors | float | message | separator |
datapoints | from | modulus | slider |
dataString | height | monitor | string |
date | input | null | summary |
divide | int | objects | title |
double | key | off | to |
enum | label | on | view |
execute | legend | options |
|
Expressions are accepted in several places in the input. Expressions follow standard C-language syntax The operations and their expressions are listed in Table C-2:
Table C-2. Operators Used With Expressions
Operator | Description |
|---|---|
+ | |
- | Subtraction |
* | Multiplication |
/ | Division |
% | Modulus |
== | |
!= | Not equals |
> | Greater than |
< | Less than |
>= | Greater than or equal to |
<= | Less than or equal to |
&& | |
|| | |
! | |
& | |
| | Bitwise OR |
^ | Bitwise XOR |
A?B:C | If (A), then B else C |
Also, the following functions are available:
Type handling is similar to that in C. Expressions using int and float promote both sides to float. Expressions using int and double, or float and double promote both sides to double. The result of a relational expression (for example, ==, <) is always an int. Type casting is also supported.
Unlike in C, strings can be compared using relational expressions; the strings are compared lexicographically.
The following sections explain the use and syntax of the Map Visualizer configuration file's input, expression, and view geography sections.
The first section of a data file is normally the input section. It defines the name and format of the data file. A typical input section might look like this:
input
{
file
"/usr/lib/MineSet/mapviz/examples/population.usa.data";
enum int Year from 1770 to 1990 by 10;
string states;
float population[enum Year] separator ' ';
float sqMiles;
}
|
This example specifies that the input data file is called population.usa.data, and that there are three tab-separated (the default) fields as follows:
one of type string
one a fixed-length vector of type float, with each value separated by a space
one a scalar value of type float
When the input section is entered, the defaults file, /usr/lib/MineSet/mapviz/input.mapviz.options, is read in.
The file statement names the data file to be read. This statement is required. Its syntax is
file "filename"; |
The file name must be in double quotation marks. If it is a relative pathname (no leading slash), it is first sought in the directory containing the current configuration file. If include statements are present, this might not be the same as the initially loaded configuration file. If it is not found in the current configuration file's directory, the file is sought in the current directory.
Enum statements declare enumeration variables that index into array fields. The enum statement has three forms.
-
enum type name from value1 to value2 by increment;
This declares an enum with values starting at value1 and incremented by increment until they reach or exceed value2. For example, the statement:
enum int age from 20 to 70 by 10;
declares age as an array dimension with the values 20, 30, 40, 50, 60, and 70.
Type must be a number type (int, float, or double) or date (see “Dates”).
The second enum statement form is
enum type name from value1 to value2 across numberOfValues;
This declares an enum with values ranging from value1 to value2. The numberOfValues is an integer specifying the number of values. For example, the statement
enum int age from 20 to 70 across 6;
declares age as an enum with the values 20, 30, 40, 50, 60, and 70.
Type must be a number type (int, float, or double) or date (see “Dates”).
The third enum statement explicitly lists the enumeration values. Its form is
enum type name { value1, value2, ..., valueN };Type can be any type or date (see “Dates”).
The enum statement includes special support for a date type that handles date and time values starting Jan 1, 1753. The date type is valid only within enum statements. A date enum statement can have the following syntaxes:
enum date “format” name from “value1” to “value2” across numberOfValues;
enum date “format” name { value1, value2, ..., valueN };
enum date “format” name from “value1” to “value2” by “increment”;
|
The format string specifies the format of the values; it is useful for controlling how dates are displayed in the animation control panel. The syntax of the format string is similar to the scanf function in C. Various units of time are represented by special characters preceded by the percent symbol (%). For example:
enum date cq “Calendar Q%Q, %Y” from “Calendar Q1, 1980” to “Calendar Q3, 1985” by “1 quarter”; |
The “Calendar Q” in the format string matches the “Calendar Q” in value1 and value2. The %Q in the format string indicates that the next number in value1 and value2 is the calendar quarter. The comma and space in the format string match the commas and spaces in the values. Finally, the %Y in the format string specifies that the year values are next.
Table C-3 lists the characters that can follow the percent symbol and the units of time they represent.
Table C-3. Characters That Can Follow the Percent Symbol in the Format String
Character | Time Unit | Precision |
|---|---|---|
Y | 4 | |
Q | 1 | |
M | 2 | |
N | month name | >= 3 |
D | 2 | |
h | 2 | |
m | 2 | |
s | 2 |
With the exception of N, each character matches an integer of the specified precision. N matches 3 or more characters giving the English name of the month.
The from-to-by form of the enum statement includes an increment value. For dates, the increment is a quoted string containing an integer, an optional space, and one of the special characters in Table C-3 or one of the symbols year, quarter, month, day, hour, minute, and second. The plural forms of these symbols are also accepted. Note that these symbols are not keywords, since they have special meaning only in the increment string. The following are examples of valid increments:
“1 year” “7 days” “4h” |
The data statements declare the columns in the data file. The columns must be declared in the order they appear in the data file. The format of most data statements is
type name; |
where type is int, float, double string, dataString, date, and fixedString(n), where n is an integer representing the width of the string; name is the variable name. Unlike in C, only one variable can be declared per statement.
Fixed arrays can also be declared using simple numeric data declarations; however, if you also are going to declare a slider, you must use the enum declaration form. The declaration syntax is
type name [ number ] ; |
For example:
float revenue [50]; |
You can also override the separator by declaring it as
type name [ number ] separator 'char'; |
For example:
float revenue [50] separator ':'; |
If no separator is specified, the default separator (usually a tab) is used.
Fixed arrays can also be two-dimensional, such as
enum string products {“bread”,“milk”,”cheese”,”cereal”, ”apples”,”lettuce”,”juice”,”toothpaste”,”soap”,”eggs”};
enum year from 1985 to 1994 by 1;
float prices[enum products][enum year];
|
or
float prices[10][20]; |
which might be used for an array of prices for a set of 10 products over a 20-year period.
Using the prices array, for example, if you specified in the Tool Manager that data was to be retrieved from the database in "wide" mode (with a bin for null values), the enumerated products are declared as:
float prices[null enum products][enum year]; |
and the first column contains the prices for unknown products (products not in the enumerated list of ten known products) declared in the enum string products statement.
The input section of a data file has several options. All options statements begin with the word “options” and have one or more comma-separated options.
The separator option defines the separator between columns in the data file. The default separator is a tab. The syntax is
options separator 'char';
For example:
options separator ':';
Note: Arrays can override the separator. The monitor option allows a dynamic update of the data displayed. When the specified file is changed (for example, through the UNIX touch command), the data file (not the configuration file) is reread. Note that although the data file could be used to trigger the updates, it is better to use a different file so that the data file is not read while it is being updated. The syntax of the monitor option is:
options monitor "filename"; options monitor "filename" timeout;
where filename is the file to watch, and the optional timeout specifies the number of seconds to wait after the file changes. If the user interacts with the application in any way during this timeout (via the mouse or keyboard), the timeout restarts. Updating the file can take a few seconds. By specifying a timeout, the chances of an update occurring while the user is interacting with the tool are minimized. This might delay the update. If no timeout is specified, the update occurs immediately.
The file being monitored must exist at the start of the program. When this file is being updated, it must not be removed and re-created; instead, only its modify time should be updated (for example, through the touch command). If the file is deleted, subsequent updates are not shown.
Suppose a program extractor extracts data from a database into a data file. If you want the program to update the data file every 10 minutes, the script you write might look like this:
extractor > dataFile; # create first data file touch trigger; # create the trigger file while (sleep 600) # sleep 10 minutes do extractor > dataFile; # create new data file touch trigger; # force a reread done & # this loop goes in the # background mapviz configFile; # run mapviz kill $! # when mapviz exits, kill # the update loopThe monitor option can be used only if the file alteration monitor /usr/etc/fam is installed (this can be found in the subsystem desktop_eoe.sw.fam).
The input section of configuration file might look like this:
input { file "dataFile: #data declarations here options monitor "trigger" 15; }The backslash option controls whether backslashes in the input data are treated specially or like other characters. The syntax is:
options backslash off; options backslash on;The default is off. If backslash processing is on, separators in the input data preceded by backslashes are treated as regular characters rather than separators. Also, within strings standard C-style backslash processing is done.
The expressions section pf a data file lets you define additional columns that are expressions of existing columns. For example, one column can be defined as the sum of two other columns. The following is a sample expression section. This section assumes two existing fixed-length columns of type double: “male” and “female”; these represent spending by males and females on various goods across time (one independent dimension). Two columns are added: “total” represents the total dollars spent, and “pctFemale” represents the percentage of dollars spent by females.
expressions
{
double total[enum month] = male+female;
double pctFemale[enum month] = divide(female*100,total,50.0);
}
|
| Note: The pctFemale calculation uses “total,” defined in the previous section. Also, note the use of the divide function rather than the / operator. This results in 50% for the case where there are no dollars spent at all; using the / operator generates a divide by zero error in such a case. (The divide function is described in the “Expressions” section.) |
The format of the expressions section is
expressions
{
expressionDeclaration;
...
}
|
where expressionDeclaration has the following syntax:
type name = expression ; |
The format of expression has already been described.
Since the expressions section has no options, no defaults file is read in for it.
The view section of a data file describes how the graphic objects are displayed, including the mapping of heights, colors, labels, and so forth. A sample view section is
view map
{
map objects "usa.states.hierarchy";
slider Year;
height population;
height legend label "Height: U.S. Population (1770-1990)";
color density, scale 0 250 500 750 1000;
color colors "white" "#ffc0c0" "#ff8080" "#ff4040" "red";
color legend label "Color: Pop. Density" "0/sq-mile"
"250/sq-mile" "500/sq-mile" "750/sq-mile"
"1000/sq-mile";
message "population %,.0f %,.1f per sq mile",
population, density;
execute "xconfirm -t 'Population %,.0f'
-t 'averaging %,.1f per sq mile'
-t 'across %,.0f sq-miles' > /dev/null",
population, density, sqMiles;
}
|
The first words of the view section (before the opening brace) describe the type of view. The only view type supported is view map; thus, these words must introduce the view section.
When entering the view section, the viewMap.mapviz.options defaults file is read in. Note that there is no simple view defaults file, so the full name viewMap.mapviz.options must be used.
The title statement inserts a title string at the bottom of the main window. The syntax is
title string; |
where string is a string enclosed by double- quotation makes.
The map statement specifies how the graphical objects are to be drawn in the main window. The map statement has three possible syntaxes: one required, the other two optional. The required syntax is
map objects hierarchy_filename; |
where “objects” is a keyword, and hierarchy_filename is a filename enclosed in double quotation marks. This statement names the .hierarchy file describing the 3D graphical objects that exhibit heights and colors.
The following map statements are optional:
map outlines hierarchy_filename;
Declares graphical objects that are drawn as flat lines on which the map objects objects are placed. See the samples provided in examples/population.usa.cities.mapviz.
map level column_name;
Specifies an alternative level of the geographical hierarchy for initial display. For example, in the examples/population.usa.mapviz file, the unstated default is
map level states;
and the main window initially displays individual states. If, instead, the configuration file specified
map level eastWest;
the main window initially displays the United States as two halves: East and West.
The slider statement identifies a key to be used as a slider dimension. Its syntax is
slider [enum] enumName; |
where enumName is the name of an enum variable declared in the input section. Note that the enum keyword is optional.
There can be 0, 1, or 2 slider statements. The first slider statement applies to the horizontal slider. The second slider statement applies to the vertical slider. If there is no slider statement, the resulting display does not include animation.
No slider statement is required if “height” and “color” map to non-array variables. One slider statement can be included if “height” and “color” map to one-dimensional arrays. Two slider statements can be included if “height” and “color” map to:
two-dimensional arrays, or
one-dimensional arrays, where dimensions are enum variable names that one of the sliders controls.
The height statement describes how the columns of data are mapped to the height of objects. It consists of a series of clauses separated by commas. The first clause normally contains the name of a column to be mapped to height (“population,” in the example in the section “The View Section”). The column must be of a number type (int, float, or double), of which float is the most memory-efficient. If the column is a fixed-length array, the view section also must contain at least one, and no more than two, slider statements.
If no height column is specified, all bars are flat, and the remaining height clauses have no effect.
The scale clause lets you scale the height values. Normally, the height variable is mapped directly to the height of the graphical objects, so that the tallest object (with the largest numeric value) rises towards the top of the view window. With the optional scale clause, all values are multiplied by the scale. The scale clause syntax is
scale float |
The legend clause defines the meaning of the height mappings. Any string can be placed in the height legend. The legend clause has the following syntaxes:
| legend off | This turns off the height legend (this is the default). | ||
| legend on | This turns on the height legend. The legend can be changed by using the legend label form, in which case legend on is unnecessary. The legend's default syntax is
where varname is the name of the variable that is mapped to height. | ||
| legend label string |
|
The color statement describes how values are mapped to colors. The format is similar to that of the height statement, consisting of several clauses that can be separated by commas or entered as multiple statements.
Color naming follows the conventions of the X Window System, except that the names must be in quotation marks. Examples of valid colors are “green,” “Hot Pink,” and “#77ff42.” The last one is in the form “#rrggbb”, in which the red, green, and blue components of the color are specified as hexadecimal values. Pure saturation is represented by ff, a lack of color by 00. For example, “#000000” is black, “#ffffff” is white, “#ff0000” is red, and “#00ffff” is cyan.)
The color variable lets you specify a single column to be mapped to a color (as with height). The column must be a number type.
The colors clause specifies the colors to be used. The colors clause's syntax is
colors "colorname" "colorname"... |
The format for colorname is described above. Note that there are no commas between the colors. This is because commas are used to separate clauses in the color statement. A sample colors clause is
colors "red" "gray" "blue" |
Colors in the list are subsequently referred to by their index, starting at zero. In the above example, red is color 0, gray is color 1, and blue is color 2.
If there is no colors statement, colors are chosen randomly; however, if there is a colors statement, at least as many colors must be specified as are to be mapped.
The scale clause allows assignment of values to a continuous range of colors. For example, when displaying a percentage, red can be assigned to 0%, gray to 50%, and blue to 100%. Intermediate values are interpolated; for example 25% is pinkish, and 55% is a slightly bluish gray.
The syntax for the scale clause is
scale float float ... |
The first value is mapped to color 0, the second to color 1, and so forth. The colors statement must contain at least as many colors as are to be mapped to the largest index.
Values in this statement must be in increasing order. Any value less than the first color is assigned the value of the first color. Any value greater than the last value is assigned the last color. Intermediate values are interpolated.
For example, assume the pctFemale column indicates what percentage of the group is female, and you want to map a group that is 100% female to red, 100% male to blue, and 50% each to gray. The colors statement for this is:
colors pctFemale, colors "blue" "gray" "red", scale 0 50 100; |
The buckets clause is similar to the scale clause without interpolation. All values are rounded down to the highest value in the clause, and that exact color is used. Values less than the first value use the first color.
The syntax for the buckets clause is
buckets float float ... |
The syntax and assignment of colors is the same as for the scale clause.
If, in the pctFemale example, you used the buckets clause instead of the scale clause, the statement would be:
colors pctFemale, colors "blue" "gray" "red", buckets 0 50 100; |
All values greater or equal to 100 are colored red. Values greater than or equal to 50, but less than 100, are gray. All other values are blue.
The normalize clause controls a form of color normalization, analogous to height normalization. By default, color normalization is off. The syntax is
normalize off; normalize on; |
When color normalization is on, the color scale (or buckets) list of values must range between 0 and 100. These color values then represent relative percentages of the range from the minimum to the maximum for a given viewed scene. For example,
color totalSales;legend off color scale 0 100, colors “white” “red”, normalize on; |
generates colors in the range of “white” to “red,” where “white” corresponds to the minimum “totalSales” and “red” corresponds to the maximum “totalSales” for the particular set of graphical objects being viewed. See /usr/lib/MineSet/mapviz/examples/variations.articles.france.mapviz for a more elaborate example.
The legend clause creates a legend of the colors. By default, the color legend is off. The legend clause syntax can be any of the following:
legend off legend on legend "string" "string" ... legend label "string" legend "string" "string" ... label "string" |
The legend off clause turns the legend off. The legend on clause turns the legend on. It can be omitted if other legend statements are included. Specifying only legend on generates the default legend.
The default legend includes a single label to the left (with the name of the column that is mapped to color), and a list of colored labels on the right (with values obtained from the scale clause, the buckets clause, or from the keys). To override the strings in the colored labels, specify the strings as:
legend "string" "string |
To override the label on the left, specify it following the word label. To eliminate this label, specify an empty string; that is
legend "" |
The message statement specifies the message displayed when an object is selected. The syntax is similar to the C printf statement. A sample message statement is
message "%s: $%f, %.0f%% of target, %.0f%% of last year",
product, sales, pctTarget, pctLastYear;
|
This could produce the following message:
furniture: $2425.37, 23% of target, 87% of last year |
The formats must match the type of data being used:
Strings must use %s.
Ints must use integer formats (such as %d).
Floats and doubles must use floating point formats (such as %f).
For details of the printf format, see the printf (1) reference (man) page (type man printf at the shell prompt).
A special format type has been added to printf. If the percent sign is followed by a comma (for example, “%,f”), commas are inserted in the number for clarity. Currently, only the United States convention of d,ddd,ddd.dddd is supported, with the decimal point represented by a period, and commas separating every three places to the left of the decimal point. For example, if the above format were:
message "%s: $%,f, %,.0f%% of target, %,.0f%% of last year",
product, sales, pctTarget, pctLastYear;
|
it would produce the message:
furniture: $2,425.37, 23% of target, 87% of last year |
The $, *, h, l, ll, L, and n printf format options are not supported.
All values, including the format string, are expressions. Thus, if you had a pctFemale column, but wanted a more gender-neutral message, you can use:
message pctFemale>50?"%f%% females":"%f%% males",
pctFemale>50?pctFemale:100-pctFemale;
|
If pctFemale is 70, the message “70% females” is displayed; if pctFemale is 30, the message “70% males” is displayed. In this case, you can also achieve the same result with a single format string:
message "%f%% %s", pctFemale>50?pctFemale:100-pctFemale,
pctFemale>50?"females":"males";
|
If no message is specified, a default message containing the names and values of all the columns is used.
The execute statement lets you execute a shell command by double-clicking an object. The syntax is similar to that of the message command.
Here is a sample execute statement that uses xconfirm to show a window with information about the item. Note that the command line (string) is shown as three lines. In an actual file, this should be on a single line. Multi-line strings are not supported.
execute "xconfirm -t '%s' -t 'population %,.0f' -t '%,.0f per
sq mile' -t '%,.0f sq-miles' > /dev/null", states,
population, density, sqMiles;
|
This might produce a dialog with the message:
CA 64 per sq mile 266,807 sq-miles |
If there is no execute statement, double-clicking an object has the same effect as single-clicking it.
The hierarchy file defines the object hierarchy, allowing objects to be displayed at different levels of aggregation. It enables the drill up and drill down capabilities of the Map Visualizer (see “File Requirements” in Chapter 6). The hierarchy file is specified in the .mapviz configuration file with the map object hierarchy_filename statement (see “The View Section” and “Map Statement”).
Here are the first few lines of the usa.states.hierarchy file:
states regions eastWest USA
usa.states.gfx usa.states.gfx
usa.states.gfx usa.states.gfx
AL E_S_CENTRAL USA_E USA_ALL
AR W_S_CENTRAL USA_W USA_ALL
AZ MOUNTAIN USA_W USA_ALL
CA PACIFIC USA_W USA_ALL
CO MOUNTAIN USA_W USA_ALL
CT NEW_ENGLAND USA_E USA_ALL
DE MID_ATLANTIC USA_E USA_ALL
|
This defines how states combine into regions, sectors, and into a single object encompassing all states.
The first record is a list of column names of the hierarchy; each name must be separated by a single tab (`\t') character. One of the column names must match a type string column in the data file, as declared in the configuration file's input section in “The Input Section”. In this example, the first column name, states, is also the name of a data column in the example population.usa.mapviz. The number of column names in this record must be the same as the number of columns of hierarchy data, beginning at the third record of the .hierarchy file. If there is only one column name (for example, gfx_files/canada.provinces.hierarchy), then there are only two records in the .hierarchy file.
The second record is a list of .gfx file pathnames, where each pathname is separated by a single tab (`\t') character. Each column name in the first record must have a matching .gfx file pathname.
If there is a single column name (and .gfx file pathname), then only these two records must be in the file. If there are multiple column names and pathnames, then starting at the third record in the .hierarchy file is an N-column table of keywords of graphical objects, where N is the number of column names in the first record. Looking at the sample file, the first column contains “states” keywords, the second column “regions” keywords, the third the “eastWest” keywords, and the fourth the “USA” keyword. The matching .gfx files contain the positions and shapes of each of the column's graphical objects.
The third and remaining records in the hierarchy file are the hierarchy data. These records define how objects at one level correspond to objects at other levels.
The .gfx files define the geometry of each object used by the Map Visualizer when displaying the objects. Each .gfx file contains multiple records, one for each object being displayed. Each record contains:
the gfx keyword name
the gfx full name
the vertex pair count
the shape hint
the vertex pairs
The following steps guide you through the procedure for building .gfx files.
Using a digitizing scanner, convert a geographical image into an RGB image file format. Note that the image itself is not used by the Map Visualizer; it is just used as a template for defining the graphical objects in Step 6.
Launch the i3dm application in /usr/demos/bin/. (If this application is not currently installed, it can be installed from the IRIX™ 5.3 or 6.2 distribution, in the subsystem demos.sw.tools.) This creates windows on your screen: a Menu window on the left, an Input window across the bottom, and four windows (labeled TOP, Pers, Front, and Right) on the right. All i3dm windows must remain displayed (not iconified) for i3dm to work.
Move the cursor to the Front window.
Press the right mouse button to display options. Continue holding the right mouse button, and scroll to the Image Background option, then to the Load Image option. The Input window (at the bottom of your screen) prompts you for a name to apply to this image.
Enter the name of the RGB image file. The image appears in the Front window.
Delineate the shape of each object in the image by pointing and clicking at significant points on the boundary of each object. Do this in a clockwise sequence for each object. Each identified point is called a “vertex” and is represented by numeric x- and y-axis values. These values are assigned by the i3dm application and exist in a relative frame of reference for that RGB image file. The following procedure is used to delineate each object's shape:
Use the middle mouse button to drag the image in the Front window so that the object you are going to delineate is completely exposed. If this is not possible, see step 8.
Go to the Menu window, and click the right mouse button on the Create pulldown menu.
Choose the Line option.
Start the point-and-click process of selecting vertices with the left mouse button in the Front window. Note that the greater the number of vertices you identify, the more accurate the resulting graphical image is.
Note the red line crosshairs as you move the cursor over the image. As you click the left mouse button to declare each vertex, a small red box appears at that point. The box of the previous vertex changes to a small “x,” and a yellow line connects the new vertex to the previous vertices. As you move clockwise around the object, stop selecting vertices immediately before you are about to close the shape (that is, before clicking on the first vertex you selected when starting to delineate the object).
Go to the Menu window, and click the right mouse button on the Attrib pulldown menu.
Scroll to the Name option. The Input window (at the bottom of your screen) prompts you for a name.
Enter a unique identifier for the object you have just delineated. Do not use spaces. The becomes the object's gfx keyword name. For example, in population.usa.mapviz the gfx column is specified as the first column in the data file. This first column contains strings such as “CA” and “NY.” These are the keyword names for the states. These keyword names are the gfx keyword names in the associated gfx file.
Go to the Menu window, and click the right mouse button on Done.
Repeat Step 6 for every other object in the same image. If the object adjoins a previously identified object, you must reuse common vertices by selecting them with the middle mouse button instead of the left mouse button. Using the middle mouse button while the crosshairs are positioned close to a previously selected vertex ensures that the newly selected vertex is identical to the previously selected one.
Caution: If a graphical object is too large to fit into the Front window, you must identify the vertices in sections. After all the objects are declared and the vertex information written to an ASCII file, you must edit this output file to join the sections of each subdivided object. When all objects are identified, save the recorded vertices in a file. To do this:
Go to the Menu window and press the right mouse button on the File pulldown menu.
Scroll down to the File i3dm format option and choose it. The Input window (at the bottom of your screen) prompts you for a filename.
Enter a filename, specifying the .i3dm suffix.
Exit the i3dm application. To do this
Go to the Menu window, and choose the File pulldown menu.
Scroll to the Exit option, and choose it.
Convert the i3dm format file into a gfx file format by using the convert.i3dm utility, using the following syntax:
/usr/lib/MineSet/mapviz/convert.i3dm inputFilename outputFilename.gfx
For each object, the utility prompts you to
confirm the object's keyword name (which defaults to the Attrib name you supplied in Step 6, substep 6, above, when identifying the vertices)
declare the object's full name (which is the name the user sees in the Map Visualizer's Selection window when using the mouse to select a geographical object)
declare if the object has a concave shape that requires special handling
Note: Declaring an object to be concave results in an accurate graphical display, but at the cost of slower performance. One strategy is to declare no objects as concave, examine the display to determine which objects are inaccurately drawn, then manually edit the gfx files for those objects, changing the string “convex” to “concave.” Another strategy is to declare all objects as “concave” (assuming there are few objects), then determine if the resulting performance is acceptable.