File format for .AUR (AutoREALM Map) Files and .AUS (AutoREALM Symbol) Files

Version 1.2

 

An .AuR File consists of all the information needed by AutoREALM to store a map.  This includes the objects in the map, as well as other assorted information like the background colors, the set of overlays, the views, and the pushpins. 

 

An .AuS File contains all the symbols in a single symbol group.  The symbol library consists of an .AuS file for each group, with the file name the name of the group.  The files must be present in the AutoREALM program directory to be read by the program at startup.

General

The data in an AutoREALM file is stored as a binary stream of bytes.  Specific data formats used throughout this document are as follows:

         A Long is a 4 byte unsigned long integer stored in little-endian format.

         A Word is a 2 byte unsigned integer.

         A Byte is a single unsigned byte.

         A Float is a 4-byte IEEE floating-point number.

         A Double is a 8-byte IEEE floating-point number.

         A Color is stored as a 4-byte RBG quantity.  Each byte contains the luminance value of a Red, Blue, or Green gun from 0 (no color) to 255 (full color).  The bytes are as follows:

1st Byte

2nd Byte

3rd Byte

4th Byte

Red

Green

Blue

Special

The Special byte is 0, except to indicate a No-Color state.  For No-Color, the special byte is 0x1F, and the other bytes will all be 0xFF.

         A String is stored as a length prefixed array of single-byte ANSI characters.  The length prefix is a 4 byte long.  As an example, the five character string “ABCDE” would be stored as:

4 byte length (little-endian) = 5          “A”         “B”         “C”         “D”         “E”

0x05  0x00  0x00  0x00  0x41  0x42  0x43  0x44  0x45

A null string (i.e. containing no characters) is: 0x00 0x00 0x00 0x00.

         A Boolean is stored as a single byte: 0x00 means false, and 0x01 means true.

         A Point is a coordinate stored as an X Float followed by a Y Float.

Header

The AutoREALM file has a header that identifies the file, and gives the file format version.  This information is as follows:

 

“AutR” FileVersion

 

The Magic ID value of “AutR” (equal to 0x52747541 as an unsigned long) must be present.  Any other data in the first four bytes of the file represents another file type. 

 

The FileVersion is a four byte unsigned long identifying the format revision of the file.  The current version is 5 (0x00000005), and is stored in Little-Endian format as the bytes:

0x05 0x00 0x00 0x00

A check for a valid file version should be made, and if the version is higher, the file should be rejected.  Any new files should be created with a file version of 5.  Other versions earlier than 5 that might be encountered:

         Version 4 is identical to Version 5, except for the addition of the Bitmap object type. 

         Version 3 is identical to Version 4, except it does not contain the “LA” Landscape chunk.

         Versions previous to 3 should be rejected.

Chunks

The remainder of an AutoREALM file is grouped in a chunk for each type of data present in the file.  Each chunk begins with a four character tag, and is followed by a two character ID identifies that chunk type.

 

Although most AutoREALM files will have all chunk types listed here, all chunks are optional except the EndOfFile chunk.  An AutoREALM file consisting of just the file Header and an EndOfFile chunk is still a valid (although useless) file.  No more than one chunk of each type may be present in a file.

 

The chunk format:

 

“<CH>” ChunkID ChunkData

 

The ChunkID is a two ASCII character ID that specifies which chunk follows.  ChunkData is a stream of bytes, the length of which is determined by the chunk type.

Color Chunk (“CO”)

The Color Chunk contains color information that applies to the entire map.  Its format:

Field Data

Field Description

“<CH>”

4-byte Chunk header

“CO”

2-byte Color Chunk identifier

RGBColor

The color of the grid lines (even if not currently visible).

RGBColor

The color of the map background.

Comment Chunk (“CM”)

The comment chunk contains the map comments.  Map comments are used by the user to identify or label the map. 

Field Type

Field Description

“<CH>”

4-byte Chunk header

“CM”

2-byte Comment Chunk identifier

String

Map comments. The string may contain CR/LF (0x0D 0x0A) sequences between each line if it is more than one line long.

Overlay Chunk (“OV”)

The overlay chunk contains a list of the overlays in use in the file.  The overlays are sequentially numbered beginning at 0.  There will always be at least one overlay.

Field Type

Field Description

“<CH>”

4-byte Chunk header

“OV”

2-byte Overlay Chunk identifier

Long

Number of Overlays (N) in the chunk

N

String

Names of the overlays from 0..N-1

     

Landscape Chunk (“LA”)

This indicates whether the preferred orientation of the map is portrait (tall) or landscape (wide), and is the default setting for printouts made with the map. (This chunk is not present in file versions previous to 4.)

Field Type

Field Description

“<CH>”

4-byte Chunk header

“LA”

2-byte Landscape Chunk identifier

Boolean

If TRUE, default orientation of map is Landscape.

 


Grid Chunk (“GR”)

The grid chunk indicates the snap settings and grid display properties of the map.

Field Type

Field Description

“<CH>”

4-byte Chunk header

“GR”

2-byte Grid Chunk identifier

Boolean

Grid Snap setting.

Boolean

Gravity Snap setting.

Boolean

Display Grid setting.

Long

Grid Spacing.  The value is in units of the initial graph coordinates: a value of 1205 is the default.

 

View Chunk (“VW”)

Each view in a map contains information about the desired grid properties, measurement units, the units used to describe that view, the coordinates of the view, and the active overlays.  There is always at least one view for a map, called the “(View when map was last saved)” from within AutoREALM, and this view is unnamed in the AutoREALM file (i.e. has a null string for the name).  Note: the map scaling factors (GraphScale and GraphUnitConvert) must contain the same numbers for each view.

Field Type

Field Description

“<CH>”

4-byte Chunk header

“VW”

2-byte View Chunk identifier

Long

Number of views in the chunk (N).

 

 

 

 

 

 

 

 

N

String

Name of the view (or “” if the default view).

Long

ClientWidth.  Width of the AutoREALM client window in pixels when the view was originally created (used for scaling the view between different machines).

Long

ClientHeight.  Height of the AutoREALM client window in pixels when the view was originally created.

Float

AreaLeft.  Coordinate of the left edge of the view.

Float

AreaTop. Coordinate of the top edge of the view.

Float

AreaRight. Coordinate of the right edge of the view.

Float

AreaBottom. Coordinate of the bottom edge of the view.

32 Bytes

VisibleOverlays.  One bit for each overlay that is visible in the current view, with the 0th overlay represented by bit 0 in the first byte, and the 255th overlay represented by bit 7 in the last byte.  All 32 bytes are present, even if there are less than 255 overlays.

32 Bytes

ActiveOverlays.  One bit for each overlay that is unfrozen in the current view, with the 0th overlay represented by bit 0 in the first byte, and the 255th overlay represented by bit 7 in the last byte.  All 32 bytes are present, even if there are less than 255 overlays.

Double

GraphScale.  The number of coordinate units (internal scaling) represented by one user-measurement unit (external scaling).

Double

GraphUnitConvert.  The length of the “A” grid segment in user units.

String

GraphUnitsName.  Name of the currently selected user measurement units for this view.

Long

GraphUnitIndex.  Index of the currently selected user measurement index (listed in order of the Right-Click context menu, with 0=Centimeters and 26=Parsecs).

Float

GridSize.  Size of the grid spacing in coordinate units.

Byte

GridType. 0x00=None, 0x01=Square, 0x02=Hex, 0x03=Triangle.  Versions of AutoREALM after 1.11 support the following additional types: 0x04=RotatedHex, 0x05=Diamond, 0x06=HalfDiamond, 0x07=Polar.

Long

Grid Secondary Units.  Number of standard grid lines before secondary grid lines are used (0=No secondary grid).

Word

GridFlags.  Currently only contains one bit:
0x01 = Grid On Top.  If set, the grid is displayed above all objects.  If clear, the grid is displayed below all objects.

Byte

PrimaryGridStyle.  Specifies line style of primary grid.  Available in AutoREALM 1.11 and later only—previous versions contain 0x00 in this field.  Values are 0x00=Default (Single), 0x01=Single, 0x02=Dot, 0x03=Dash 0x04=Dash Dot, 0x05=Dash Dot Dot, 0x06=Bold

Byte

SecondaryGridStyle.  Specifies line style of secondary grid.  Available in AutoREALM 1.11 and later only—previous versions contain 0x00 in this field.  0x00=Default (Bold), 0x01=Single, 0x02=Dot, 0x03=Dash 0x04=Dash Dot, 0x05=Dash Dot Dot, 0x06=Bold

PushPin Chunk (“PP”)

The PushPin chunk describes the locations and enabled state of each push pin.  The push pins in the file are in the same order as they appear in the pushpin toolbar: Red, Yellow, Green, Blue.

Field Type

Field Description

“<CH>”

4-byte Chunk header

“PP”

2-byte PushPin Chunk identifier

Long

Number of push pins in the chunk (N).  Currently fixed at 4.

 

 

 

N

Boolean

PushPin Checked.  True if pushpin has been placed.

Boolean

PushPin Coordinate Present.  If True there is a pushpin coordinate following this; if false, the next pushpin follows immediately, and the X and Y coordinates are not present.

(Point)

PushPin (X,Y) Coordinate (only if PushPin Coordinate Present is True).

 

Object Chunk (“OB”)

The Object chunk contains all of the map objects.  Objects can be grouped, and so can contain sub-chains of objects. 

Field Type

Field Description

“<CH>”

4-byte Chunk header

“OB”

2-byte PushPin Chunk identifier

Byte

Object 1 Identifier

<Data>

Object 1 Data

Byte

Object 2 Identifier

<Data>

Object 2 Data

Etc.

0x00

End of Objects

 

Object Header

Each object in the Object chunk has an object ID, which defines the data contained in that object.  Each object begins with the same header information:

Field Name

Type

Description

ID

Byte

Identifier of the object.

Color

Color

Color of the object.

Overlay

Byte

Number of the overlay containing the object.

BoundLeft

Float

Left edge of a bounding rectangle that contains the object.

BoundTop

Float

Top edge of a bounding rectangle that contains the object.

BoundRight

Float

Right edge of a bounding rectangle that contains the object.

BoundBottom

Float

Bottom edge of a bounding rectangle that contains the object.

 

Object Types

The following is a table of all the supported object types, and the data present for each type.

Object Id

Object Type

Object Contents

L (0x4c)

Line

Header

Object Header information.

Start

Point

(X,Y) Coordinate of line beginning

End

Point

(X,Y) Coordinate of line ending

Style

Long

Index of Line Style

l (0x6c)

Fractal Line

Header

Object Header information.

Start

Point

(X,Y) Coordinate of line beginning

End

Point

(X,Y) Coordinate of line ending

Style

Long

Index of Line Style

Seed

Long

Seed of the fractal (determines shape)

Roughness

Long

Number from 0 (smooth) to 1000 (rough) that determines the severity of the fractal.

C (0x43)

Curve

Header

Object Header information.

P1

Point

Beginning point of Bezier curve.

P2

Point

Control point 1

P3

Point

Control point 2

P4

Point

Ending point of Bezier curve.

Style

Long

Index of Line Style

c (0x63)

Fractal Curve

Header

Object Header information.

P1

Point

Beginning point of Bezier curve.

P2

Point

Control point 1

P3

Point

Control point 2

P4

Point

Ending point of Bezier curve.

Style

Long

Index of Line Style

Seed

Long

Seed of the fractal (determines shape)

Roughness

Long

Number from 0 (smooth) to 1000 (rough) that determines the severity of the fractal.

K (0x4b)

PolyCurve

Header

Object Header information.

FillColor

Color

Color of object interior

Style

Long

Index of Line Style

Count

Long

Number of points in the polycurve.  The first four points in the polycurve define the first curve.  Subsequent curves reuse the last point of the previous curve and add three more points.  Count must be (n*3)+1, where n is the number of complete curves.

Point 1

Point

First point

Point N

Point

Last point

k (0x6b)

Fractal PolyCurve

Header

Object Header information.

FillColor

Color

Color of object interior

Style

Long

Index of Line Style

Count

Long

Number of points in the polycurve.  The first four points in the polycurve define the first curve.  Subsequent curves reuse the last point of the previous curve and add three more points.  Count must be (n*3)+1, where n is the number of complete curves.

Point 1

Point

First point

Point N

Point

Last point

Seed

Long

Seed of the fractal (determines shape)

Roughness

Long

Number from 0 (smooth) to 1000 (rough) that determines the severity of the fractal.

S (0x53)

Symbol

Header

Object Header information.

Location

Point

Upper left corner of the symbol.

Width

Float

Width of the symbol.

Height

Float

Height of the symbol.

Diagonal

Float

Diagonal distance of the symbol.

Size

Long

Size of symbol when originally placed.

Angle

Long

Angle of rotation of the symbol.

Text

String

Characters of the symbol (in the AutoREALM font).

Outline

Color

Symbol outline boundary color.

T (0x54)

Text

Header

Object Header information.

Location

Point

Upper left corner of the text.

Width

Float

Width of the text.

Height

Float

Height of the text.

Diagonal

Float

Diagonal distance of the text.

Size

Long

Size of text when originally placed.

Angle

Long

Angle of rotation of the text.

Text

String

Text to be displayed.

Outline

Color

Text outline boundary color.

FontName

String

Name of the font.

FontStyle

Long

Style of the font.  Bits are: 1=Bold, 2=Italic, 4=Underline

Alignment

Long

0=Left Align, 1=Centered, 2=Right Align

t (0x74)

Curved Text

Header

Object Header information.

P1

Point

Beginning point of Bezier curve.

P2

Point

Control point 1

P3

Point

Control point 2

P4

Point

Ending point of Bezier curve.

Unused

Long

Unused data.

Height

Float

Height of the text.

Size

Long

Size of text when originally placed.

Text

String

Text to be displayed.

FontName

String

Name of the font.

FontStyle

Long

Style of the font.  Bits are: 1=Bold, 2=Italic, 4=Underline

Outline

Color

Text outline boundary color.

P (0x50)

PolyLine

Header

Object Header information.

FillColor

Color

Color of object interior

Style

Long

Index of Line Style

Count

Long

Number of points in the polyline.

Point 1

Point

First point

Point N

Point

Last point

p (0x70)

Fractal PolyLine

Header

Object Header information.

FillColor

Color

Color of object interior

Style

Long

Index of Line Style

Count

Long

Number of points in the polyline.

Point 1

Point

First point

Point N

Point

Last point

Seed

Long

Seed of the fractal (determines shape)

Roughness

Long

Number from 0 (smooth) to 1000 (rough) that determines the severity of the fractal.

G (0x47)

Group

Header

Object Header information.

Chain of Objects

All objects in a group form a new chain.  Groups may be recursively nested indefinitely.

0x00

End of Chain.  This byte indicates the end of the group.

B (0x42)

Bitmap

(not present in file versions previous to 5)

Header

Object Header information.

Left

Float

Left edge of the bitmap.  This should either equal BoundLeft for a normal image or BoundRight for a horizontally flipped image.

Top

Float

Top edge of the bitmap.  This should either equal BoundTop for a normal image or BoundBottom for a vertically flipped image.

Right

Float

Right edge of the bitmap.  This should either equal BoundRight for a normal image or BoundLeft for a horizontally flipped image.

Bottom

Float

Bottom edge of the bitmap.  This should either equal BoundBottom for a normal image or BoundTop for a vertically flipped image.

Size

Long

Number of bytes in the bitmap image.

Image

Bytes

Size bytes stored as a Device Independent Bitmap.

0x00

End of Chain

ID

0x00

This ID signifies the end of a chain (either a group, or the entire object chunk).

 

Selected Chunk (“SE”)

The Selected State chunk contains one boolean value for each primary object in the map.  Non-primary objects (i.e. objects that are part of groups) inherit the selection state of their parent.  This chunk is not typically present in maps saved to disk, as its intended use is during Undo streaming operations.

Field Type

Field Description

“<CH>”

4-byte Chunk header

“SE”

2-byte Selected Chunk identifier

Count x (Boolean)

A boolean (TRUE if selected) for each top-level object in the map.  Note that if this chunk is present, it must follow the object chunk as the number of bytes in the chunk is determined by the number of top-level objects in the object chunk.

 

EndOfFile Chunk (“EO”)

The EndOfFile chunk is the last chunk in the file.  Any data beyond the EndOfFile chunk should be ignored.

Field Type

Field Description

“<CH>”

4-byte Chunk header

“EO”

2-byte EndOfFile Chunk identifier

 

 

AutoREALM Symbols

The AutoREALM Symbol file is almost the same as a normal map file with the following differences: