Last modified December 21, 1997.
Numerical carpets are described in an article in Icon Analyst 45 (IA45). That is the primary reference for the concepts and methods related to the programs described here. Since that article was written, several features have been added. These are:
And, of course, there are all the particulars concerning the use of the
programs concerned with creating numerical carpets. This document describes
the carpet-specification program, carport.icn, and, to a lesser
extent, the carpet-generation program, carplay.icn, which is
invoked by carport.
These programs, especially carport, have many features.
It is, however, possible to use them creatively without exploring all their
features.
This document is a work in progress. It will be extended and improved over time.
The carpet programs require Version 9.3 of Icon with graphics facilities
and Version 9.3.1 of the Icon program library. The procedures portion of
the library must be installed and available via the IPATH environment
variable.
Installing the carpet-specification program, carport, is
simple. It can be done with the simple script given in build
or its equivalent. No installation of the carpet-generation program, carplay,
is needed; it is compiled and executed by carport. On some
platforms, however, it may be necessary to modify the part of carport.icn
that does this.
Note: To date, the carpet programs have been tested only on UNIX platforms. There probably will be problems under Windows.
Launch carport. It should look something like this:
Press the return key with the interface window active. This
starts the generation of the default carpet. The mouse pointer should turn
into a watch symbol, indicating computation is in progress. After a bit,
a new, small window should open, showing the carpet as it is generated.
When it is complete, a mirrored version should appear in another window.
To dismiss the carpet-generation program, press q with the
smaller carpet window active. Note: To get back to the
carpet-specification program, you must dismiss carpet window.
Now that you've generated your first, albeit mundane, carpet, start exploring.
For example, enter @T (the letter T with the meta
key depressed). You'll get a dialog for default the top-row expression,
which is just 1 for a lone 1 in the upper-left corner of the
carpet. Edit this to, for example, make it |1, which produces 1s all along
the top row and, by default, along the left column. Dismiss the dialog and
press the return key again. You'll get a different carpet. Next you might
try changing the modulus. Enter @M and change the default value
from 5 to, say, 3. Dismiss the dialog, and press the return key again. And
so on; there are endless possibilities to explore.
The carpet-specification program, carport, maintains several
kinds of data :
The database initialially contains a single default specification. There is always a current carpet specification, initially the default one. The database can be changed by adding and deleting specifications, as well as by loading an existing database from a file. There is no limit to the number of specifications that can be contained in a database except the amount of memory available.
Tables of definitions associate names with strings. This allows, among other things, the use of names for long expressions and to provide useful mnemonics.
List of links contain the names of Icon library modules that may be needed for carpet generation.
A carpet specification consists of five parts:
Each specification has its own table of definitions and list of links.
The parameters are:
All parameters are interpreted as Icon expressions and can range from simple literals to complicated expressions. Except for the color list, which must evaluate to a suitable string, all expressions must produce numbers.
The height defaults to the width, and the left-side initializer defaults to the top-row initializer.
The default carpet specification is shown in this dialog:
The parameters are represented by defined names as follows:
Modulus modulus Width carpet width Height carpet height Top top-row initializer Left left column initializer Neighbors neighborhood computation Colors color list
These names may be used in expressions. For example, the carpet height
can be set to (Width / 2) so that the height is half the width,
whatever the width is.
The interface provides menus and text lists:
All menu items have keyboard shortcuts as indicated below.
The notation @L means typing the letter L with
the meta key depressed . The notation ^@L means typing the
letter L with the meta and control keys depressed. The control
key modifier is used only in the Database, Specification,
and Links menus.
The File menu has these items:
generate @G create carpet display @D display options options @O generation options quit @Q quit applicationThe Database menu provides items for manipulating the database as a whole:
load ^@L load database from file merge ^@J merge (join) database from file save ^@S save database save as ^@T save database to specified file clear ^@Z clear (zap) database revert ^@R revert to last saved databaseThe Edit menu provides items for editing the current specification:
modulus @M edit modulus expression width @W edit width expression height @H edit height expression top @T edit top-row initializer expression left @L edit left-column initializer expression neighbors @N edit neighborhood expression color @C edit color-list expression name @I edit name (identification) comments @K edit commentsThe Specification menu provides items relating to individual specifications:
new ^@N create new specification copy ^@D copy (duplicate) current specification display ^@Y display current specification write ^@W write current specification to a fileThe Definitions menu provides items related to definitions:
add @A add definition load @F load definitions from file merge @J merge definitions from file save @S save definitions to file clear @Z clear (zap) the table of definitionsThe Links menu provides items related to links to library modules:
add ^@A add link clear ^@C clear the list of links
In addition to the keyboard shortcuts lists in the menus above, typing
return on the carpet-specification interface is equivalent
to @G and starts the carpet-generation process. If you are
dismissing a dialog that completes the current specification, typing return
twice dismisses the dialog and starts carpet generation.
There may be undocumented keyboard shortcuts as well. See carport.icn.
The specifications list shows the names of all carpet specifications in the current database. Clicking on one brings up a dialog that allows you to make that specification the current one, display the details of the specification, or delete the specification from the database.
The definitions list shows the defined names for the definitions in the current carpet specification. Clicking on one brings up a dialog that allows you to edit or delete the definition. (Definitions are added via the Definitions menu (
@A).)The links list shows the names of the procedure modules that will be linked by the carpet-generation program. Clicking on one brings up a dialog that allows you to edit or delete the name. (Links are added via the Links menu (
^@A).)
The colors in the color list are assigned in order to the integers 0, 1, 2, ... during carpet generation.
The list of colors is given by a string that may have one of the following four forms:
The string is converted into a color list during carpet generation.
Any Icon palette can be used to create a a color list. For example, "g2"
produces a list of two colors, black and white in that order, and "g8"
produces a list of eight equally spaced shades of gray from black
to white. Note that many palettes contain more colors than the modulus,
so in such cases only the first part of such a color list is used.
A hue encoding is a list of characters, each of which represents a hue in the Icon color-naming system. The characters representing hues are:
"R" red "V" violet "G" green "W" white "B" blue "G" gray "C" cyan "b" brown "Y" yellow "k" black "M" magenta "p" pink "P" purple "O" orange
Note that uppercase letters are used when the hue begins with that letter and lowercase letters are used when more than one hue begins with the same letter.
As an example, "RWBRWB" is a hue encoding for
a list of six colors: red, white, blue, red, white, blue. Since color lists
are expressions, repl("RWB",2) produces this color
list also.
A color-specification list consists of a sequence of Icon color specifications,
each followed by a colon. The specifications can be given in any of the
forms that Icon allows. For example, "red:green:blue:" produces
a color list consisting of red, green, and blue, while repl("red:white:blue:",2)
produces the same color list and given in the example for hues in the previous
section. Of course, color-specification lists can be used to represent any
of the colors available in Icon, not just the pure hues of its color-naming
system.
The last color in a color-specification list must have a terminating colon.
A color-list file consists of a sequence of Icon color specifications, one per line.
A definition consists of a name and an associated string. When the name is used, the string is substituted. The rules for names, strings, and how they are substituted are those for Icon preprocessor defined constants.
A definition is added by selecting add (@A)
from the Definitions menu, which provides a dialog with a place for
the name and its associated string.
The dialog imposes maximum length of 15 characters for the name and the maximum length of 80 characters for the string.
The maximum on the length of the string can be circumvented by using
defined names in strings. For example, if Z is defined to be
(|0 \ 20) and O is defined to be (|1 \ 20),
the S could be defined to be (Z | O | O | Z | Z | O |
O | O | Z).
Adding a definition whose name is already in use replaces the former definition.
The definitions text list contains the names for all current definitions. Clicking on one brings up a dialog showing the definition:
The definition can be edited, followed by dismissing the dialog with
Okay, or it can be deleted by dismissing with Delete.
Caution: There is no undo facility at present.
Defined names can be used in any parameter expression or definition. The rules of Icon syntax apply.
The dialogs for the top, left, and neighbors expressions have a
Define button. Pressing this button brings up a dialog that allows
you to assign a name to the expression.
[image to come]
There are four items in the Definitions menu in addition to add:
clear(@C) deletes all definitions
load(@L) loads definitions from a file, replacing all current definitions
merge(@J) loads definitions from a file and merges them with the current definitions. If the name occurs in both, the definition from the file replaces the current one.
save(@S) saves the current definitions in a specified file. The standard suffix for definitions files is .def.
Note: As mentioned in Section 4, parameters are represented by definitions. Defining a name that is the same as a parameter results in a preprocessor error (duplicate definition) when the carpet-generation program is compiled. It is, of course, possible to define names that are identifiers in the carpet-generation program, but this is likely to produce bad results. It is safe to use names that begin with an uppercase letter and do not conflict with names, like carpet parameters, that the carpet-specification program uses.
At any time after a carpet image window appears, the generation process
can be aborted by typing q with that window active. This is
particularly useful when it's immediately evident that the carpet is not
working out well.
Once carpet generation is complete, typing s with the carpet
image window active saves the carpet in a GIF file whose basename is the
name of the carpet. For example, if the carpet name is medusa,
the file name is medusa.gif. If a file by that name already
exists, it is silently overwritten. Note: After saving
an image file, it is necessary to type q to dismiss the carpet-generation
program and get back to the carpet-specification program.
Several options are provided to control the carpet-generation display.
They are specified by selecting the display item (@D)
from the File menu:
If mirror is specified (it is by default), a mirrored image
of the carpet is shown in a separate window. If this option is selected,
the mirrored image can be save in a GIF file by typing m in
the carpet image window (not the mirrored image window). The file name is
obtained by appending _m to the caret name, as in medusa_m.gif.
If hidden is specified, the carpet-generation program does
not produce any windows and does not need to be dismissed. This option is
designed for use with the following two.
If save carpet is specified, the carpet image is saved automatically,
named as described above. If save mirror is specified, a mirrored
image of the carpet is saved automatically, named as described above.
If dialogs is specified, dialogs are provided for saving
images and dismissing the carpet-generation program instead of the low-level
keyboard events described above. The disadvantage of this option is that
it delays the launch of the carpet-generation program because of the additional
code that has to be linked.
Specifying background is equivalent to specifying save
carpet and hidden; background overrides
other specifications.
Three options are available for controlling the way the carpet is generated.
They are specified by selecting the options item (@O)
from the File menu:
If wrap is specified, the edges of the carpet are wrapped
around, top-to-bottom and left-to-right, to form a torus, topologically.
When this is done, the neighborhood computation along the top and left edges
wraps around instead of failing, since there are no out-of-bounds references.
This option may or may not produce different results from the default and
they may or may not be more attractive.
If randomize is specified, the seed for random generation
is picked randomly and any random carpet elements may vary from generation
to generation.
If two pass is specified, the carpet generation is done
in two passes. The first pass performs the neighborhood computation to assign
values to cells, but it does not take the residue with respect to the modulus.
The second pass takes the residue and assigns colors. The default one-pass
and the optional two-pass algorithms may produce different results if computations
are specified that produce different results with and without modular arithmetic.
For example, (i % m) + (j % m) = (i + j) % m but, in general,
ixor(i % m, j %m) ~= ixor(i, j) % m. The two-pass algorithm
takes longer than the one-pass algorithm, and the carpet image window is
blank until the second pass starts.
Note: Generation options are not part of carpet specifications.
The file examples.cdb is a database that contains example
carpet specifications. The file examples.htm is a Web page
showing these specifications and the corresponding carpets.
The directory colors contains example color-list files.
Creating interesting and attractive numerical carpets is a skill that combines a bit of mathematics, some Icon programming knowledge, a sense for graphic design, and not a little bit of luck.
Different persons are likely to approach carpet creation in different ways: analytically, randomly, OTW-wise, ... . It's easy to get frustrated when nothing really new comes from experiments and variations. Certain themes dominate numerical carpets: the classical "fractal" theme epitomized by the default parameters, Sierpinski triangles, textures, and chaotic carpets with little or no apparent structure. Persistence pays off; keep trying.
genrfnc.icn).
pdco.icn and intpdco.icn)
As noted in the Analyst article on numerical carpets, the carpet-generation program does no error checking for the validity of expressions or values. This is left to the carpet-specification program. Consequently, errors do not show up until an attempt is made to generate a carpet. There are several possible kinds of errors:
There all are manifested by Icon error messages. Realize that the carpet-specification program writes an include file which is prepended to the carpet-specification program; if the generation specifications contain errors, these become errors in the carpet-generation program.
Preprocessor errors can result from illegal definition syntax and duplicate definitions. Syntax errors result from illegal expression syntax, such as mismatched parentheses in an initialization expression.
Linking errors occur if a specified link does not exist.
As in all Icon programs, there are many possible sources of run-time errors. For example, misspelling a procedure name or failing to prove a link name for the module that contains the procedure is likely to result in an invalid value -- a null value where a procedure is expected. Of course, expressions themselves may result in run-time errors. Note that run-time errors may not occur until some time after carpet generation starts.
It's also possible to get the carpet-generation process into an endless loop.
The source of many errors is evident from the error messages they produce.
Often examining the carpet-generation program, carplay.icn,
will suggest the cause. Since it is the include file, carpincl.icn,
that introduces errors, examining this file often reveals the problem. Note
that it is possible to edit the include file and compile and run the carpet-generation
program, independent of the carpet-specification program. This also is an
easy way to experiment with minor changes to a carpet specification -- and
to get insight into the way numerical carpets are specified.
^@S).
At present, there are no known bugs in the carpet programs. That does no mean there aren't any bugs; there almost certainly are. The programs have only been tested by the author, and many features have been tested only lightly. Please report any bugs you find.
Databases are represented by tables internally and stored in files using
xencode() from the Icon program library. By convention, carpet
database files have the suffix .cdb. Note: In order
to decode a database file, it is necessary for the decoding program to contain
the record declaration carpet(), which is contained in carputil.icn.
Carpet specifications are represented internally by records of type carpet.
When a carpet is created, the current specification is written as an include
file for the carpet-creation program, carplay. The current
specification can be written in this format to a file without creating a
carpet (^@W). By convention, specification files have the suffix
.cpt. When a specification is written to a file, it is appending
to the specified file, so it is possible to write a sequence of carpet specifications
to a file. Such files can be used by other applications to perform such
tasks as creating carpet images in the background and creating new databases.
Color lists are identified internally by names; the actual lists are
not kept internally. Color-list files are simply lists of color specifications.
By convention, color-list files have the suffix .clr.
Definitions are represented by tables internally and stored in files
using xencode().By convention, carpet database files have the
suffix .def.
All file formats (including xencodings) are ASCII text.