r.in.mat(1)

1r.in.mat(1)                   Grass User's Manual                  r.in.mat(1)
2
3
4

NAME

6       r.in.mat  - Imports a binary MAT-File(v4) to a GRASS raster.
7

KEYWORDS

9       raster
10

SYNOPSIS

12       r.in.mat
13       r.in.mat help
14       r.in.mat  [-v]  input=string   [output=string]   [--overwrite]  [--ver‐
15       bose]  [--quiet]
16
17   Flags:
18       -v
19           Verbose mode
20
21       --overwrite
22           Allow output files to overwrite existing files
23
24       --verbose
25           Verbose module output
26
27       --quiet
28           Quiet module output
29
30   Parameters:
31       input=string
32           Name of an existing MAT-File(v4)
33
34       output=string
35           Name for the output raster map (override)
36

DESCRIPTION

38       r.in.mat will import a GRASS raster map from a Version 4 MAT-File which
39       was  created  with  Matlab or Octave.  Attributes such as map title and
40       bounds will also be imported if they exist.
41       Specifically, the following array variables will be read:
42
43                      map_data
44
45                      map_name
46
47                      map_title
48
49                      map_northern_edge
50
51                      map_southern_edge
52
53                      map_eastern_edge
54
55                      map_western_edge
56       Any other variables in the MAT-file will be simply skipped over.
57       The 'map_name' variable is optional, if it exists, and  is  valid,  the
58       new  map will be thus named. If it doesn't exist or a name is specified
59       with the output= option, the raster map's name will be set to "MatFile"
60       or  the  name  specified  respectively.  (maximum 64 characters; normal
61       GRASS naming rules apply)
62       The 'map_title' variable is optional, the map's  title  is  set  if  it
63       exists.
64       The  'map_northern_edge'  and  like  variables are mandatory unless the
65       user is importing to a "XY" non-georeferenced  location  (e.g.  imagery
66       data). Latitude and longitude values should be in decimal form.
67

NOTES

69       r.in.mat  imports a Version 4 MAT-File. These files can be successfully
70       created with more modern versions of Matlab and Octave (see  "EXAMPLES"
71       below).
72       Everything  should  be  Endian  safe, so the file to be imported can be
73       simply copied between different  system  architectures  without  binary
74       translation (caveat: see "TODO" below).
75       As there is no IEEE value for NaN in integer arrays, GRASS's null value
76       may be used to represent it within these maps. Usually Matlab will save
77       any integer based matrix with NaN values as a double-precision floating
78       point array, so this usually isn't an issue. To save  space,  once  the
79       map is loaded into GRASS you can convert it back to an integer map with
80       the following command:
81       r.mapcalc int_map="int(MATFile_map)"
82        NaN values in either floating point or double-precision floating point
83       matrices should translate into null values as expected.
84       r.in.mat  must  load  the  entire map array into memory before writing,
85       therefore it might have problems with huge arrays.  (a 3000x4000  DCELL
86       map uses about 100mb RAM)
87       GRASS  defines  its map bounds at the outer-edge of the bounding cells,
88       not at the coordinates of their centroids. Thus, the  following  Matlab
89       commands may be used to determine and check the map's resolution infor‐
90       mation will be correct:
91           [rows cols] = size(map_data)
92           x_range = map_eastern_edge - map_western_edge
93           y_range = map_northern_edge - map_southern_edge
94           ns_res = y_range/rows
95           ew_res = x_range/cols
96
97       Remember Matlab arrays are referenced as (row,column), i.e. (y,x).
98       In addition, r.in.mat and r.out.mat make for a  nice  binary  container
99       format  for  transferring  georeferenced maps around, even if you don't
100       use Matlab or Octave.
101

EXAMPLES

103       In Matlab, save with:
104       save filename.mat map_* -v4
105        In Octave, save with:
106       save -mat4-binary filename.mat map_*
107
108

TODO

110       Robust support for  mixed-Endian  importation.   (This  is  a  work  in
111       progress, please help by reporting any failures to the GRASS bug track‐
112       ing system)
113       Add support for importing map history, category information, color map,
114       etc.  if they exist.
115       Option to import a version 5 MAT-File, with map and support information
116       stored in a single structured array.
117

BUGS

119       If you encounter any problems, please  contact  the  GRASS  Development
120       Team.
121

AUTHOR

128       Hamish Bowman
129
130       Department of Marine Science
131       University of Otago
132       New Zealand
133
134       Last changed: $Date: 2006-04-21 11:06:24 +0200 (Fri, 21 Apr 2006) $
135
136       Full index
137
138       © 2003-2008 GRASS Development Team
139
140
141
142GRASS 6.3.0                                                        r.in.mat(1)