home *** CD-ROM | disk | FTP | other *** search
/ Amiga Developer CD 2.1 / Amiga Developer CD v2.1.iso / Extras / IFF / IFF_Forms / MTRX.doc < prev    next >
Encoding:
Text File  |  1993-03-01  |  7.7 KB  |  163 lines
  1. Numerical data storage (MathVision - Seven Seas)
  2.  
  3. MTRX FORM, for matrix data storage                    19-July-1990
  4.  
  5. Submitted by: Doug Houck
  6.               Seven Seas Software
  7.               (address, etc)
  8.  
  9. INTRODUCTION:
  10.  
  11. Numerical data, as it comes from the real world, is an ill-mannered beast.
  12. Often much is assumed about the data, such as the number of dimensions, 
  13. formatting, compression, limits, and sizes.  As such, data is not portable.
  14. The MTRX FORM will both store the data, and completely describe its
  15. format, such that programs no longer need to guess the parameters of
  16. a data file.  There needs to be but one program to read ascii files and
  17. output MTRX IFF files.
  18.  
  19. A matrix, by our definition, is composed of three types of things.
  20. Firstly, the atomic data, such as an integer, or floating point number.
  21. Secondly, arrays, which are simply lists of things which are all the same.
  22. Thirdly, structures, which are lists of things which are different.
  23. Both arrays and structures may be composed of things besides atomic data - 
  24. they may contain other structures and arrays as well.  This concept
  25. of nesting structures may be repeated to any desired depth. 
  26.  
  27. For example, a list of data pairs could be encoded as an array of structures,
  28. where each structure contains two numbers.  A two-dimensional array is
  29. simply an array of arrays.  
  30.  
  31. Since space conservation is often desirable, there is provision for
  32. representing each number with fewer bits, and compressing the bits together.
  33.  
  34.  
  35. CHUNKS
  36.  
  37. The MTRX FORM is composed of the definition of the structure, followed
  38. by the BODY which contains the data which is defined.  Usually, there
  39. is only one set of data, but a smarter IFF read could use the definition
  40. as a PROPerty, with identically formatted data sets (BODYs) in a LIST.
  41.  
  42.   FORM MTRX
  43.     definition (ARRY | STRU | DTYP)
  44.     BODY
  45.  
  46. ARRY: The array chunk defines a counted list of similar items.
  47. The first (required) chunk in an ARRY is ELEM, which gives the number
  48. of elements in the array.  Optionally, there may be limits given, (LOWR
  49. and UPPR), which could be used in scaling during sampling of the data.
  50. Lastly is the definition of an element of the array, which may be a 
  51. nested definition like everything else. 
  52.  
  53.   ARRY ::= "ARRY" #{ ELEM [LOWR] [UPPR] [PACK] ARRY|STRU|DTYP }
  54.  
  55. STRU: The structure chunk defines a counted list of dissimilar things.
  56. The first (required) chunk in a STRU is FLDS, which gives the number 
  57. of fields in the structure.  Lastly are definitions of each field
  58. in the structure.  Again, each field may have a nested definition like
  59. everything else.
  60.  
  61.  STRU ::= "STRU" #{ FLDS ([PACK] ARRY|STRU|DTYP)* }
  62.  
  63. VALU: The value contains a datatype, and then a constant of that type.
  64. The datatype contains the size of the constant, so this chunk has variable
  65. size.  VALU is used in the ARRY chunk to give the scaling limits of the array.
  66.  
  67. BODY: This is the actual data we went to so much effort to describe.
  68. It is stored in "row-first" format, that is, items at the bottom of the
  69. nested description are stored next to each other.  In most cases, it
  70. should be sufficient to simply block-read the whole chunk from disk, 
  71. unless the reader needs to adjust byte-ordering or store in a more
  72. time-efficient format in memory.  Data is assumed to be byte-aligned.
  73.  
  74. PACK: The PACK chunk is necessary when the bit length of the data is
  75. not a multiple of 8, that is, not byte-aligned, and the user wishes
  76. to conserve space by packing data items together.  PACK is simply a
  77. number - the number of items to bit-pack before aligning on a byte.
  78. A PACK is in effect for the remainder of its nested scope, or until 
  79. overridden by a new specification.  A STRU or ARRY is assumed to have 
  80. a PACK of 1 by default - it is not affected by PACKs in definitions above.
  81. A PACK of 0 means to byte-align before processing the next definition.
  82. The PACK specifier should be normalized.  For example, when packing a large
  83. array of 3-bit numbers, PACK should be 8 since 3*8 = 24. In this case 8 is
  84. the smallest PACK number which aligns on a byte naturally.
  85.  
  86. DTYP: The DataType is the most interesting chunk, as it attempts to define
  87. every conceivable type of numeric data with 32 bits.  The 32 bits are broken
  88. down into three fields, 1) the size in bits, 2) the Class, and 3) SubClass.
  89. The Class makes the most major distinction, separating integers from floating
  90. point numbers from Binary Coded Decimal and etc.  Within each class is a
  91. SubClass, which gives the specific encoding used.  Finally, the Size tells
  92. what how much room the data occupies.  The basic division of datatypes is
  93. given in the tree structure below.
  94.  
  95. Class             SubClass     Size  Final Specific Type
  96. =====             ========     ====  ===================
  97.  |
  98. Binary Unsigned - 0 ------------ 8   UByte
  99.  |                              16   UWord
  100.  |                              32   ULong
  101.  |
  102. Binary Signed --- 0 ------------  8  Byte
  103.  |                               16  Word
  104.  |                               32  ULong
  105.  |
  106. Real ------------Ieee38 -------- 32  Ieee Single Precision
  107.  |                |
  108.  |               Ieee308 ------- 64  Double Precision
  109.  |                |              32  Truncated Double Precision
  110.  |                |
  111.  |               FFP ----------- 32  Motorola Fast Floating Point
  112.  |
  113. Text ----------- Text0 --------- ??  Null-terminated text
  114.  |                |
  115.  |               CText --------- ??  Number of characters in first byte
  116.  |                |
  117.  |               FText --------- ??  Fixed length, space padded
  118.  |
  119. BCD ------------ Nibble -------- ??
  120.                   |
  121.                  Character ----- ??
  122.  
  123.   A design goal was to create a classification system which other people
  124. can easily plug into.  Many data types are simply size variations on 
  125. existing data types.  For example, a 4-bit integer can be specified by
  126. giving the size as four bits in the Signed Binary class.  Be aware that
  127. not all MTRX readers may support your new type, but there will not be
  128. any type clashes or ambiguities by following these rules.  If you have
  129. a truly unique Class or SubClass, you will need to register it with
  130. Commodore to prevent clashes.
  131.  
  132.  A second design goal was to create a format which is easily decoded
  133. by software.  By aligning fields on bytes, you have the option of redefining
  134. the datatype as a structure, so as to avoid shifting when accessing the 
  135. fields.  Since the numbers are sequentially assigned, they are suitable
  136. as array indicies, and may be optimized in a C switch statement.
  137.  
  138. A third design goal was allowing for naive and sophisticated readers.
  139. In checking for a certain datatype, a naive reader can simply compare
  140. the whole datatype with a small set of known types, which assumes that
  141. each different Size defines a unique datatype.  Sophisticated readers
  142. will consider the Class, SubClass and Size separately, so as to support
  143. arbitrary size integers, and truncated Floating Point numbers, for example. 
  144.  
  145.  *
  146.  * MTRX ::= "FORM" #{ "MTRX" ARRY|STRU|DTYP BODY        } Matrix
  147.  * ARRY ::= "ARRY" #{ ELEM [LOWR] [UPPR] [PACK] ARRY|STRU|DTYP } Array
  148.  * STRU ::= "STRU" #{ FLDS ([PACK] ARRY|STRU|DTYP)*     } Structure
  149.  * ELEM ::= "ELEM" #{ elements                          } Array elements
  150.  * LOWR ::= "LOWR"  { VALU                              } Minimum limit 
  151.  * UPPR ::= "UPPR"  { VALU                              } Maximum limit
  152.  * VALU ::=        #{ dtyp value                        } Value (in union)
  153.  * dtyp ::=         { size, subclass, class             } Data Type (scalar)
  154.  * DTYP ::= "DTYP" #{ dtyp                              } 
  155.  * FLDS ::= "FLDS" #{ number of fields                  } Number of Fields
  156.  * PACK ::= "PACK" #{ units packed b4 byte alignment    } Packing
  157.  * BODY ::= "BODY" #{ inner-first binary dump           } Data
  158.  *
  159.  *   [] means optional
  160.  *   #  means the size of the unit following
  161.  *   *  means one or more of
  162.  *
  163.