Integer Field File Format (OIF)

The OIF format is loosely based on the OVF formats, but stores non-negative integer values rather than floating point in its data block. Moreover, the integers are typically relatively small values indexing into a list of labels, rather than representing raw data quantities directly. One client of OIF files is the Oxs_FileAtlas class, where the OIF integers map out the locations of distinct regions in the atlas. A sample OIF file is included below.

The OIF file structure consists of an identification record followed by header and data blocks. All non-data lines begin with a `#' character. Comments may be embedded inside the header block, with the `##' pair denoting the start of a comment. Comments run to the end of the line. The data block consists of non-negative integer values in either plain text or little endian binary form.

The file type identification record must be the first line of an OIF file, with the form

# OOMMF OIF 1.0

Segment count and begin records, as in the OVF formats, may follow the identification line, but are optional in OIF files and are ignored. The next required record is the header block start record

# Begin: Header

The header block continues until the header block end record

# End: Header

All records inside the header block are structured as label+value pairs. The label tag consists of all characters after the initial `#' up to the first colon (`:') character. Case is ignored, and all space and tab characters are eliminated. The value consists of all characters after the first colon, continuing up to a `##' comment designator or the end of the line.

Records inside the header block include

• meshtype: Must have the value rectangular. Required
• xnodes, ynodes, znodes: Three separate lines, specifying the number of nodes along each axis (integer). Required.
• xbase, ybase, zbase: Three separate lines, specifying one corner of the volume covered by the file (floating point). Optional.
• labels: A single record containing a (Tcl) list of alphanumeric labels associated with values in the data block. This is an optional record that clients may ignore, but if used the first label typically corresponds to the value 1, the second label to 2, and so on, with the value 0 being reserved for client use. (For example, the Oxs_FileAtlas class in the Oxs application assigns `0' to the implicit “universe” region.) If supplied, the maximum value in the data block should not be greater than the number of elements in this list.
• xstepsize, ystepsize, zstepsize: Three separate lines, specifying the distance between adjacent grid points. Optional. The x/y/zbase and x/y/zstepsize may be ignored by the client, but if used the volume represented runs across
  $$(\mathrm{xbase},\mathrm{xbase}+\mathrm{xnodes}\cdot\mathrm{xsteps... ... \times (\mathrm{zbase},\mathrm{zbase}+\mathrm{znodes}\cdot\mathrm{zstepsize})$$
  with the first node in the data block located at
  $$(\mathrm{xbase}+\mathrm{xstepsize}/2, \mathrm{ybase}+\mathrm{ystepsize}/2, \mathrm{zbase}+\mathrm{zstepsize}/2)$$
  and the last at
  $$(\mathrm{xbase}+(\mathrm{xnodes}-1/2)\cdot\mathrm{xstepsize},\\ ... ...m{ystepsize},\\ \mathrm{zbase}+(\mathrm{znodes}-1/2)\cdot\mathrm{zstepsize}).$$

The order of records inside the header block does not matter.

The data block follows the header block, and starts with a record of the form

# Begin: data text

for plain text data or

# Begin: data binary n

for binary data, where n is 1, 2, or 4, indicating the width in bytes of each item in the data block. (To portably detect the start of a binary data block, the end of line marker should follow either the Unix and macOS convention of a simple newline, or else the Windows carriage return + newline pair.)

In text data blocks, the $\mathrm{xnodes}\cdot\mathrm{ynodes}\cdot\mathrm{znodes}$ data items are whitespace separated. Binary data blocks are more compact, with items distinguished by item width. Multi-byte binary values are stored with the least significant byte first (little endian). To guard again byte ordering mishaps, and to provide a partial check that the file hasn't been sent through a non 8-bit clean channel, the first item in a binary data block is a check value: 255 (hex 0xFF), 65 306 (hex 0xFF1A), or 83 827 228 (hex 0x04FF1A1C), for 1 byte, 2 byte, and 4 byte binary respectively. (These will read sequentially in the the file as 0xFF, 0x1A 0xFF, and 0x1C 0x1A 0xFF 0x04.) Including the check value, each binary data block contains a total of $1 + \mathrm{xnodes}\cdot\mathrm{ynodes}\cdot\mathrm{znodes}$ items.

In all cases the ordering runs with the $x$ index incremented first, then the $y$ index, and the $z$ index last. This is the same ordering as used by the OVF formats. (Note that as compared to images used by the Oxs_ImageAtlas class, where the $y$ index typically runs from the top to the bottom of the image, the $y$ index in OIF files would be interpreted as running from the “bottom” to the “top”.) Text and data blocks both end with a trailing end of line marker (newline or carriage return + newline) followed by either

# End: data text

or

# End: data binary n

for text and binary blocks, respectively.

# OOMMF OIF 1.0
# Begin: Header
## Two '#' characters denote a comment
# meshtype: rectangular
# xbase: 2.5e-9
# ybase: 2.5e-9
# zbase: 2.5e-9
# xstepsize: 5e-9
# ystepsize: 5e-9
# zstepsize: 4e-9
# labels: Fe Ni Co spacer
#
## The x/y/zbase, x/y/zstepsize, and labels records are optional. Each
## may be treated as a hint and ignored by a client application. In
## particular, the Oxs class Oxs_FileAtlas Specify block may override
## these file values, and regardless always implicitly inserts a
## "universe" region as the first label value which corresponds to the
## data value 0. Thus, in this example, 1 corresponds to Fe, 2 to Ni,
## 3 to Co, and 4 to spacer.
#
## The x/y/znodes records are required. The product
##    xnodes * ynodes * znodes
## equals the number of entries in the data block.
#
# xnodes: 4
# ynodes: 3
# znodes: 2
# End: Header
# Begin: data text
4  4  4  4  4  4  4  4  4  4  4  4
2  2  2  2  2  2  2  2  2  2  2  2
4  4  4  4  4  4  4  4  4  4  4  4
0  0  0  3  3  3  3  3  3  0  0  0
# End: data text

Figure 20.1: OIF 1.0 sample file, with comments. (description)

OOMMF Documentation Team
September 27, 2024