IAN’s and APACK’s ASCII image file format

IAN’s and APACK’s ASCII image file format

IAN and APACK define and support a case insensitive ASCII image file format. An well defined ASCII image file is comprised of sections of user specified data. In general the ASCII image file format definition supports free layout of sections. Sections can appear in any order and not all sections are required. Sections can be separated by additional whitespace (or blank lines) if desired. Any deviations from these conventions are noted below.

A minimal ASCII image file includes three sections: the rows section, the columns section, and the cells section. These sections are each described below.

ASCII image files can be embellished with additional information such as a legend, a title, measurement units, and comments. Comments start with the two character sequence ‘//’. All text following the two character sequence ‘//’ to the end of line is ignored.

Columns section

The number of columns in the image file is specified in the columns section of the ASCII image. This section is a required element of any ASCII image file. The columns section starts with the string “[columns]” on its own line. The number of columns is then specified on the following line. The specification of the columns section in the ASCII image file must precede the cells section.

Rows section

The number of rows in the image file is specified in the rows section of the ASCII image. This section is a required element of any ASCII image file. The rows section starts with the string “[rows]” on its own line. The number of rows is then specified on the following line. The specification of the rows section in the ASCII image file must precede the cells section.

Cells section

The actual cell data in the image file is specified in the cells section of the ASCII image. This section is a required element of any ASCII image file. It must not precede the rows section or the columns section. The cells section starts with the string “[cells]” on its own line. Then starting on the next line each cell value is specified separated by spaces and/or carriage returns. There should be exactly as many cell values listed as there are rows and columns specified. APACK reads cell values one complete row at a time from top to bottom. So the first cell value entry is mapped to row 1 and column 1 and pertains to the upper left corner of an image. The second cell value entry is mapped to row 1 and column 2.

Title section

The title of the image file is specified in the title section of the ASCII image. Including this section in the definition of an ASCII image file is optional. The title section starts with the string “[title]” on its own line. Then starting on the next line the title string is specified. The case of the title string is maintained.

Legend section

The legend of the image file is specified in the legend section of the ASCII image. Including this section in the definition of an ASCII image file is optional. The legend section starts with the string “[legend]” on its own line. Then the following lines contain a cell value followed by a legend string. Legend items can specified in any order desired and there is no need to specify all of them. Simply specify those that are of interest. The cell value specified pertains to the cell value associated with the legend string. The cell values must be <= 16 million. The case of the legend strings are maintained.

Cell spacing section

The cell spacing of the image file is specified in the cell spacing section of the ASCII image. Including this section in the definition of an ASCII image file is optional. The cell spacing section starts with the string “[cell spacing]” on its own line. Then starting on the next line a number followed by a unit name is specified. The number specified represents the number of units between cells and must be greater than zero. The unit name specified represents the unit and must be a distance unit. In APACK the unit must be one of “m”, “km”, “ft”, “yd”, or “mi”. IAN has a much larger set of distance units. Simply specify the name or abbreviation of your distance unit. If it is not found in IAN’s unit database it is not difficult to add to IAN.

An example test image follows:

// Example ASCII text image file

[title]

Example text image for IAN and APACK

[rows]

[columns]

[cells]

1 1 2 2 // row 1

1 5 5 2 // row 2

4 5 5 3

4 4 3 3 // last row

[legend]

1 water

2 marsh

3 scrub

4 conifer

5 deciduous

0 background

[cell spacing]

28.5 m

// End example ASCII text image file