This chapter describes the data and configuration files that are required for the Map Visualizer. You can also generate these files automatically by using the Tool Manager. The subjects discussed are:
Read the Map Visualizer chapter of the MineSet Enterprise User's Guide for Windows before reading this chapter.
Data input to the Map Visualizer must be provided as a single file containing raw data, usually in ASCII text form. 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 “Configuration File Overview”. Using the U.S. population data in the examples directory (the population.usa.data file), provided as part of the Map Visualizer package, the first few lines of this input file appear as follows:
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 Chapter 13, “Nulls in MineSet.”
The Map Visualizer supports integer, floating point number, and string data types, as well as arrays of these types. See Chapter 5, “Data and Configuration File Basics,” for details about data types.
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 “?”.
The configuration file format is flexible. You must separate words in it by spaces, and it is case-sensitive. Except for the include statement and text within quoted strings, spacing and line breaks are irrelevant.
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 configuration file's structure and grammar are explained in the following 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:
Windows searches for all the files in the directory in which MineSet is installed, under \config\mapviz.
UNIX searches for the files as specified by the X-resource Mapviz*configPath in the Mapviz file, in the directory X11/app-defaults, for example in /usr/lib/MineSet.
The mapviz directory. This directory contains system defaults.
The ~/.MineSet directory (the tilde, ~, indicates your home directory). You can set up personal defaults in this directory.
The current directory, which lets you set up defaults for each directory.
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.
The first section of a data file is normally the input section. It defines the name and format of the data file. A typical IRIX 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:
Type string.
Fixed-length vector of type float, with each value separated by a space.
Scalar value of type float.
When the input section is entered, the defaults file, input.mapviz.options, is read in.
For Windows users this file is in the directory in which MineSet is installed, in \config\mapviz\input.mapviz.options.
For UNIX users the file is in /usr/lib/MineSet/mapviz/input.mapviz.options.
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 following statement declares age as an array dimension with the values 20, 30, 40, 50, 60, and 70:
enum int age from 20 to 70 by 10;
Type must be a number type (int, float, or double) or date (see “Dates”).
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 following statement declares age as an enum with the values 20, 30, 40, 50, 60, and 70:
enum int age from 20 to 70 across 6;
Type must be a number type (int, float, or double) or date (see “Dates”).
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 January 1, 1753. The date type is valid only within enum statements. A date enum statement can have the following types of syntax:
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 8-1 lists the characters that can follow the percent symbol and the units of time they represent.
Table 8-1. 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 8-1 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, because 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. You must declare the columns must in the order they appear in the data file. The format of most data statements is:
type name; |
type is int, float, double string, dataString, date, or fixedString(n); n is an integer representing the width of the string; name is the variable name. Unlike in C, you can declare only one variable per statement.
You can also declare fixed arrays by 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 the following which might be used for an array of prices for a set of 10 products over a 20-year period.
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]; |
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]; |
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 you change the specified file (for example, through the UNIX touch command), the data file (not the configuration file) is reread. 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;
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. If you specify a timeout, the chances of an update occurring while the user is interacting with the tool are minimized. This might delay the update. If you do not specify a timeout, the update occurs immediately.
On Windows, the timeout value has no effect. In other words, the monitor update always occurs immediately.
The file being monitored must exist at the start of the program. When this file is being updated, you must not remove and re-create it; instead, you should only update only its modify time (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 on UNIX systems 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 as separators. Also, within strings, standard C-style backslash processing is done.
The expressions section of a data file lets you define additional columns that are expressions of existing columns. For example, you can define one column as the sum of two other columns.
The following is a sample expressions 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 over 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, the use of the divide function rather than the / operator. This results in 50% for the case in which no dollars are spent; using the / operator generates an error because it results in division by zero. (The divide function is described in Chapter 5, “Data and Configuration File Basics,” in “MineSet Expression Language”.) |
The format of the expressions section is:
expressions
{
expressionDeclaration;
...
}
|
expressionDeclaration has the following syntax:
type name = expression; |
Because 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. The following is a sample view section:
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; therefore, these words must introduce the view section.
When entering the view section, the viewMap.mapviz.options defaults file is read in.
The title statement inserts a title string at the bottom of the main window. The syntax is:
title string; |
string is a string enclosed by double quotation marks.
The map statement specifies how the graphical objects will be drawn in the main window. The map statement has three possible types of syntax: one required, the other two optional. The required syntax is:
map objects hierarchy_filename; |
objects is a keyword, and hierarchy_filename is a filename enclosed in double quotation marks. This statement names the .hierarchy file that describes the 3D graphical objects that exhibit heights and colors.
The following map statements are optional:
map outlines hierarchy_filename;
This declares graphical objects that are drawn as flat lines on which the map objects are placed. See the samples provided in the examples directory, population.usa.cities.mapviz.
map level column_name;
This specifies an alternative level of the geographical hierarchy for initial display. For example, in the examples directory, the population.usa.mapviz file, the unstated default is:
map level states;
The main window initially displays individual states. If, instead, the configuration file specifies the following, the main window initially displays the United States as two halves: East and West:
map level eastWest;
The slider statement identifies a key to be used as a slider dimension. Its syntax is:
slider [enum] enumName; |
enumName is the name of an enum variable declared in the input section. 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 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 either of the following:
Two-dimensional arrays.
One-dimensional arrays, where the 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 (such as population in the example in “Configuration File 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 toward 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 types of syntax:
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:
height:varname
varname is the name of the variable that is mapped to height.
legend label string
string is the name of the variable that is mapped to height. You can change the legend by using the legend label form. If legend label is used, legend on is unnecessary.
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.
Windows users should use only the “#ff0000” form, as only some of the named colors are supported (for example, white, black, gray, red, yellow, green, and so on.)
UNIX users can find the color list file at /usr/lib/X11/rgb.txt.
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"... |
This is the format for colorname. 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, you must specify at least as many colors as will 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 will 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 than 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, the following 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:
color totalSales;legend off color scale 0 100, colors “white” “red”, normalize on; |
See the file variations.articles.france.mapviz for a more elaborate example.
Windows users can find the file in the directory in which MineSet is installed, under Examples\mapviz\examples, and UNIX users can find the file in /usr/lib/MineSet/mapviz/examples/variations.articles.france.mapviz.
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. You can omit it 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 as follows:
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 on UNIX systems, see the printf (1) 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 U.S. 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, the preceding format could be:
message "%s: $%,f, %,.0f%% of target, %,.0f%% of last year",
product, sales, pctTarget, pctLastYear;
|
In this case, it would produce the following 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. Therefore, if you had a pctFemale column, but wanted a more gender-neutral message, you could 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 statement.
The following is a sample UNIX execute statement that uses xconfirm to show a window with information about the item. The command line entry 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 following 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.
This sample execute statement will work on Windows as well as UNIX, because a simple xconfirm utility is provided with the installation on Windows.
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. The hierarchy file is specified in the .mapviz configuration file with the map object hierarchy_filename statement (see “Configuration File View Section” and “Map Statement”).
These 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 “Configuration File 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 contains “regions” keywords, the third contains the “eastWest” keywords, and the fourth contains the “USA” keyword. The matching .gfx files contain the positions and shapes of each 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 following:
gfx keyword name
gfx full name
vertex pair count
shape hint
vertex pairs
The following steps explain how to build .gfx files on UNIX systems. On Windows, an application for generating your own .gfx files, including instructions for using the utility to create maps, is downloadable from the MineSet Web page: http://mineset.sgi.com.
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 5.
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.
Right-click the Front window to display options. Hold down the right mouse button, scroll to the Image Background option, and then scroll 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 clicking 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 follow these steps to delineate each object's shape:
Use the middle mouse button to drag the image in the Front window so that the object you will delineate is completely exposed. If this is not possible, see step 7.
Go to the Menu window, and right-click the Create pulldown menu.
Choose the Line option.
Start clicking vertices in the Front window. The more vertices you select, the more accurate the resulting graphical image will be.
Note the red line crosshairs as you move the cursor over the image. As you click 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 the first vertex you selected when starting to delineate the object).
Go to the Menu window, and right-click 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 5 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 with 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 will be identical to the previously selected one.
Caution: If a graphical object is too large to fit into the Front window, you must select the vertices in sections. After all the objects are declared and the vertex information is 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 as follows:
Go to the Menu window and right-click 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 as follows:
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 do the following:
Confirm the object's keyword name (which defaults to the Attrib name you supplied in step 5, substep 8, when selecting 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, and 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), and then determine if the resulting performance is acceptable.