NAME

       r.out.mat  - Exports a GRASS raster to a binary MAT-File.

KEYWORDS

       raster, export, output

SYNOPSIS

       r.out.mat
       r.out.mat --help
       r.out.mat input=name output=name  [--overwrite]  [--help]  [--verbose]  [--quiet]  [--ui]

   Flags:
       --overwrite
           Allow output files to overwrite existing files

       --help
           Print usage summary

       --verbose
           Verbose module output

       --quiet
           Quiet module output

       --ui
           Force launching GUI dialog

   Parameters:
       input=name [required]
           Name of input raster map

       output=name [required]
           Name for output binary MAT file

DESCRIPTION

       r.out.mat  will  export  a  GRASS  raster map to a MAT-File which can be loaded into Matlab or Octave for
       plotting or further analysis.  Attributes such as map  title  and  bounds  will  also  be  exported  into
       additional array variables.
       Specifically, the following array variables are created:

           •
                map_data

           •
                map_name

           •
                map_title (if it exists)

           •
                map_northern_edge

           •
                map_southern_edge

           •
                map_eastern_edge

           •
                map_western_edge
       In  addition,  r.out.mat  makes  for  a  nice binary container format for transferring georeferenced maps
       around, even if you don’t use Matlab or Octave.

NOTES

       r.out.mat exports a Version 4 MAT-File. These files should successfully load into more modern versions of
       Matlab and Octave without any problems.
       Everything  should  be  Endian  safe, so the resultant file can be simply copied between different system
       architectures without binary translation.
       As there is no IEEE value for NaN for integer maps, GRASS’s null value is used  to  represent  it  within
       these maps. You’ll have to do something like this to clean them once the map is loaded into Matlab:
           map_data(find(map_data < -1e9)) = NaN;
       Null  values  in  maps  containing  either  floating point or double-precision floating point data should
       translate into NaN values as expected.
       r.out.mat must load the entire map into memory before writing, therefore it might have problems with huge
       maps.  (a 3000x4000 DCELL map uses about 100mb RAM)
       GRASS  defines  its  map  bounds at the outer-edge of the bounding cells, not at the coordinates of their
       centroids. Thus, the following Matlab commands may be used to determine the map’s resolution information:
           [rows cols] = size(map_data)
           x_range = map_eastern_edge - map_western_edge
           y_range = map_northern_edge - map_southern_edge
           ns_res = y_range/rows
           ew_res = x_range/cols

EXAMPLE

       In Matlab, plot with either:
       imagesc(map_data), axis equal, axis tight, colorbar
       or
       contourf(map_data, 24), axis ij, axis equal, axis tight, colorbar

TODO

       Add support for exporting map history, category information, color map, etc.
       Option to export as a version 5 MAT-File, with map and support information stored in a single  structured
       array.

SEE ALSO

        r.in.mat
       r.out.ascii, r.out.bin
       r.null
       The Octave project

AUTHOR

       Hamish Bowman
        Department of Marine Science
       University of Otago
       New Zealand

SOURCE CODE

       Available at: r.out.mat source code (history)

       Main index | Raster index | Topics index | Keywords index | Graphical index | Full index

       © 2003-2019 GRASS Development Team, GRASS GIS 7.8.2 Reference Manual