KnotPlot File Formats

KnotPlot uses at least 22 different file formats, either as input or as output. This page does not describe them all, just a few of the most important ones.


KnotPlot knot and link format, version 1.0

This is probably the single most important file format used by KnotPlot. It is the format that the load and save commands use (although both commands can also work with a simple ascii format). A simple program, kpfsnoop.cpp is provided for examining the contents of KnotPlot files. Another program, unknot.cpp is included as a complete example of writing a link file. Note that the load command can also read input data in the form of ascii text, similar to that output by the coords command.

This format consists of an ascii header, followed by one or more fields or sections.

Header

This can consist of arbitrary text but must begin with the string

KnotPlot 1.0

indicating that the file is a KnotPlot file, version 1.0. The header ends with a control-L character (new-page character, ascii value 12) followed by exactly one character (of arbitrary value, but usually set to a new-line character). The reason for the control-L new-line combination is that this allows for easy viewing of the header using the UNIX command more without having to have to see any of the binary data that follows the header (this doesn't always work).

Fields

After the header, the file must contain at least one field. All fields are optional, except for the endf field, which must be the last field present. Each field consists of a four character string which is the field name, followed by a data segment (possibly null). There are three types of fields, depending on the kind and amount of data following. The fields can be distinguished by the case of the first two characters in the field name:

Both lower case
This indicates a field that has a null data segment. Examples are the endf and comp fields. Such fields are usually used to signal an event or milestone of some sort, and they need no other data.
Both upper case
Following the field name, these fields have a four byte long which indicates the number of remaining bytes in the data segment. Therefore if this number is K, the total length of the field (including the field name) is K + 8 bytes. This makes it easy for software that doesn't understand how to deal with the field to simply skip the remaining part of the data segment by skipping the K bytes following the four byte long. Examples are the LOCF and LOCS fields.
First character upper, second lower case
The data segment in these fields consists of exactly the four bytes following the field name. An example is the Attr field.

endf field

This field signals the end of the data file. It must be the last field present.

comp field

Signals the beginning of a new component. All coordinate data following (in LOC* fields, for example) are added to this new component. Note that one component may have multiple coordinate fields, for example a LOCF field followed by a LOCS field, or a dozen LOCC fields. The normal situation is to just have a single coordinate field, however.

LOCF field

A coordinate field (LOCation field) stored using 4 byte floating point numbers for coordinates, so 12 bytes per vertex. The floating point numbers are stored in network (big-endian) order.

LOCS field

Coordinate field stored using unsigned shorts (2 bytes) per coordinate, six bytes per vertex. At the beginning of the field, there is scale and offset information. If chosen appropriately, these numbers allow one to get maximal resolution out of the unsigned shorts. However, there is no restriction on the values for the scale and offset.

LOCD field

A coordinate field stored using 8 byte doubles for coordinates, 24 bytes per vertex. Like all multi-byte data in this file format, these doubles are stored in network order.

Attr field

A optional field that specifies attributes (flags) of the current component. The 32-bits of the field, if set to 1, are interpreted by KnotPlot in the following way:

bit 1
Current component is closed, set this bit to 0 if you want to indicate the current component is open. Note there is possibility for confusion here: if the Attr field is present, KnotPlot will consider the current component open or closed according to whether bit 1 of the attribute is 0 or 1, respectively. However, if the Attr field is missing (the usual case), then KnotPlot considers the component to be closed.

NAME field

Optional name of the thing contained in the file.

USER field

Field for holding arbitrary information that a user might need.

IDEN field

For knotted graphs, stores information on how things are glued together.

VIEW field

COMM field

Field that can contain a KnotPlot command. This field is for experts only.

META field

Stores arbitrary meta-information in name/value pairs.

FRAC field

CELT field

THOL field

Information describing how a tangle holder is constructed

Twst field

Mcyl field

Specifies the string width (cylinder width) of the current component.

Date field

Date file was created (or any other date).

COLR field

A RGB-triple specifying the colour of the current component.

Iter field

WORM field

DNAL field


PPM format

The simplest possible (but not simpler) file format for RGB colour images, described elsewhere.


PGM format