Mapping Toolbox

readmtx

Read a matrix stored in a file

Syntax

• mtx = readmtx(fname,nrows,ncols,precision)
  readmtx(fname,nrows,ncols,precision,readrows,readcols)
  readmtx(fname,nrows,ncols,precision,readrows,readcols,mformat)  
  readmtx(fname,nrows,ncols,precision,readrows,readcols,mformat, 
  nheadbytes)
  readmtx(fname,nrows,ncols,precision,readrows,readcols,mformat, 
  nheadbytes,nRowHeadBytes)
  readmtx(fname,nrows,ncols,precision,readrows,readcols,mformat, 
  nheadbytes,nRowHeadBytes,nRowTrailBytes)
  readmtx(fname,nrows,ncols,precision,readrows,readcols,mformat, 
  nheadbytes,nRowHeadBytes,nRowTrailBytes,nFileTrailBytes)
  readmtx(fname,nrows,ncols,precision,readrows,readcols,mformat, 
  nheadbytes,nRowHeadBytes,nRowTrailBytes,nFileTrailBytes, 
  recordlen)
  

Background

Map data is often provided as binary or ASCII files with a fixed format. Writing your own functions to read the data into MATLAB can be difficult and time-consuming, particularly for binary files. This function allows you to read the data by simply specifying the format of the file.

Description

mtx = readmtx(fname,nrows,ncols,precision) reads a matrix stored in a file. The file contains only a matrix of numbers with the dimensions nrows by ncols stored with the specified precision. Recognized precision strings are described below.

mtx = readmtx(fname,nrows,ncols,precision,readrows,readcols) reads a subset of the matrix. readrows and readcols specify which rows and columns are to be read. They can be vectors containing the row or column numbers, or two-element vectors of the form [start end], which are expanded using the colon operator to start:end. To read just two rows or columns, without expansion by the colon operator, provide the indices as a column matrix.

mtx = readmtx(fname,nrows,ncols,precision,readrows,readcols,mformat)specifies the machine format used to write the file. mformat can be any string recognized by fopen. This option is used to automatically swap bytes for file written on platforms with a different byte ordering.

mtx = readmtx(fname,nrows,ncols,precision,readrows,readcols,mformat,nheadbytes) skips the file header, whose length is specified in bytes.

mtx = readmtx(fname,nrows,ncols,precision,readrows,readcols,mformat,nheadbytes,nRowHeadBytes) also skips a header which precedes every row of the matrix. The length of the header is specified in bytes.

mtx = readmtx(fname,nrows,ncols,precision,readrows,readcols,mformat,nheadbytes,nRowHeadBytes,nRowTrailBytes) also skips a trailer which follows every row of the matrix. The length of the trailer is specified in bytes.

mtx = readmtx(fname,nrows,ncols,precision,readrows,readcols,mformat,nheadbytes,nRowHeadBytes,nRowTrailBytes,nFileTrailBytes) accounts for the length of data following the matrix. The sizes of the components of the matrix are used to compute an expected file size, which is compared to the actual file size.

mtx = readmtx(fname,nrows,ncols,precision,readrows,readcols,mformat,nheadbytes,nRowHeadBytes,nRowTrailBytes,nFileTrailBytes,recordlen) overrides the record length calculated from the precision and number of columns, and instead uses the record length given in bytes. This is used for formatted data with extra spaces or line breaks in the matrix.

Examples

Write and read a binary matrix file:

• fid = fopen('binmat','w');
  fwrite(fid,1:100,'int16');
  fclose(fid);
  
  mtx = readmtx('binmat',10,10,'int16')
  mtx =
       1     2     3     4     5     6     7     8     9    10
      11    12    13    14    15    16    17    18    19    20
      21    22    23    24    25    26    27    28    29    30
      31    32    33    34    35    36    37    38    39    40
      41    42    43    44    45    46    47    48    49    50
      51    52    53    54    55    56    57    58    59    60
      61    62    63    64    65    66    67    68    69    70
      71    72    73    74    75    76    77    78    79    80
      81    82    83    84    85    86    87    88    89    90
      91    92    93    94    95    96    97    98    99   100
  
  mtx = readmtx('binmat',10,10,'int16',[2 5],3:2:9)
  mtx =
      13    15    17    19
      23    25    27    29
      33    35    37    39
      43    45    47    49
  

Limitations

Every row of the matrix must have the same number of elements.

Remarks

This function reads files that have a general format consisting of a header, a matrix and a trailer. Each row of the matrix may have a certain number of bytes of extraneous information preceding or following the matrix data.

Both binary and formatted data files can be read. If the file is binary, the precision argument is a format string recognized by fread. Repetition modifiers such as '40*char' are not supported. If the file is formatted, precision is a fscanf and sscanf-style format string of the form '%nX', where n is the number of characters within which the formatted data is found, and X is the conversion character such as 'g' or 'd'. Fortran-style double precision output such as '0.0D00' may be read using a precision string such as '%nD', where n is the number of characters per element. This is an extension to the C-style format strings accepted by sscanf. Users unfamiliar with C should note that '%d' is preferred over '%i' for formatted integers. MATLAB follows C in interpreting '%i' integers with leading zeros as octal. Formatted files with line endings need to provide the number of trailing bytes per row, which may be 1 for platforms with carriage returns or line-feed (Macintosh, UNIX), or 2 for platforms with carriage returns and line-feeds (DOS).

See Also

readfields	Reads fields or records from a fixed format file
textread	Read formatted text files
spcread	Read columns of data from an ascii text file
dlmread	Read ASCII delimited file

readfields

rec2geod