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:

1^st Byte	2^nd Byte	3^rd Byte	4^th 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 0^th overlay represented by bit 0 in the first byte, and the 255^th 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 0^th overlay represented by bit 0 in the first byte, and the 255^th 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:

The header contains the Magic ID value of “AutS” (equal to 0x 53747541 as an unsigned long), and a file version of 1 (0x00000001).

Multiple symbols exist in each symbol file. Each symbol in the file consists of a String that is the symbol name, followed by the symbol’s data (the objects representing the symbol), followed by a Boolean called “Favorites” that indicates whether or not the symbol should be placed into the toolbar.
Any objects can be present in the symbol’s data (any “OB” chunk data). And a single comment chunk (“CO”) can be part of the symbol’s data as comments on that symbol. The only other allowable chunk is an EOF chunk, which must be the last chunk following the symbol’s objects, and indicates termination of that symbol’s data.

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

General

Header

Chunks

Color Chunk (“CO”)

Field Data

Field Description

“<CH>”

“CO”

RGBColor

Comment Chunk (“CM”)

Field Type

Field Description

“<CH>”

“CM”

String

Overlay Chunk (“OV”)

Field Type

Field Description

“<CH>”

“OV”

Long

N

String

Landscape Chunk (“LA”)

Field Type

Field Description

“<CH>”

“LA”

Boolean

Grid Chunk (“GR”)

Field Type

Field Description

“<CH>”

“GR”

Boolean

Boolean

Boolean

Long

View Chunk (“VW”)

Field Type

Field Description

“<CH>”

“VW”

Long

N

String

Long

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

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

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

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.