Home > atmlab > geoplots > gmt > gmt_plot.m

gmt_plot

PURPOSE ^

GMT_PLOT plotting interface for GMT (Generic Mapping Tools)

SYNOPSIS ^

function filename = gmt_plot(in,field)

DESCRIPTION ^

 GMT_PLOT plotting interface for GMT (Generic Mapping Tools)

 The function is basically a wrapper that calls gmt shell commands using easy
 to use matlab arguments. Try test_gmt.m for some examples on how to use the function.
 Preferably, the data should be CENTERED if the data is gridded (fastest performance).

 OUT   filename  The filename of the figure.

 IN    in        A structure with input data and options. See below for
                 a detailed description of the structure.

 OPT   field     The string name of the structure element that contains
                 the data to be plotted. If no field is given, 'data'
                 is assumed.

 Easy example: If you just want to plot some data..
                 in.somefield = data2plot
                 in.lon  = longitudes
                 in.lat  = latitudes

                 file = gmt_plot(in,'somefield');

 see STRUCTURE CONTENTS below for the rest of the available arguments

 VIEWING THE PLOT:
 The easiest thing to do is to define a viewer in your startup file.

 Add something like the following to your startup file')
 gmtlab( 'OUTDIR', '/name/a/favorite' ) %% The default directory to put plots
 gmtlab( 'PSVIEWER','gv');             %% set viewer for .ps files
 gmtlab( 'PDFVIEWER','xpdf -z width'); %% set viewer for .pdf files
 gmtlab( 'OPEN_COMMAND','gnome-open'); %% set a general open command
 gmtlab( 'VERBOSITY',1); %% This outputs stdout on the screen.

 Structure contents:

 MANDATORY INPUT

 1) in.(field) % the data (default is field='data' i.e. in.data)
 2) in.lat     % the corresponding latitudes
 3) in.lon     % the corresponding longitudes

 If your data is ungridded the dimensions of the manditory input
 (lat,lon.data) must be the same.
 i.e isequal(size(in.lat),size(in.lon),size(in.data))

 If your data is gridded the data MUST have the dimensions:
 [length(in.lat),length(in.lon)] == size(in.(field));
  << transpose: in.(field) = in.(field)'; if this is not the case >>

 NOTE: 1) If your data is UNGRIDDED I recommend setting
          in.nearneighbor.resolution = Deg (something suitable).
       2) gmt_plot automatically detects if the data is gridded or not


 HOW TO READ VARIABLE DESCRIPTION OF OPTIONAL VARIABLES:
 KEY:  in.variable   in: = expect input type, ex: = Explanation/Example, de: = Default value/behavior
 NOTE: If "def" is missing for a variable it means the variable is not used by default

                  types: %s=character or string
                         %f=numeric/logical
                         {}=cell
--------------------------------------------------------------------------

 GENERAL:

 in.annot_font_size_primary
                   in:     %s or %f (if %f, unit is assumed from in.measure_unit)
                   ex:     The size of the font, e.g., '2c'=2cm for e.g., the axis.
                           Setting this will also change the size of the
                           fonts of the annotations for the legend. If you
                           want a different size for the legend
                           annotations, set in.legend.font_size.
                   def:    '14p'
 in.basemap_axis   in:     %s
                   ex:     'WSne', annotates West and South of the map,
                           but not North or East
                   def:    'WSne'
                   ------------
 in.display        in:     %f
                   ex:     If false, file created but not displayed
                   def:    true
                   ------------
 in.filename       in:     %s
                   ex:     'yourfilename', or 'yourfilename.jpg'
                   def:    Generated from title. The filetype is determined by the file
                           ending given by your filename, e.g., any of bla.{pdf,jpg,eps,tif,png,ps}
                     ------------
 in.figuretype     in:     %s
                   ex:     'eps','pdf','BMP','jpg','PNG','PPM' (not recommended), or 'tif'.
                           If the figure type is included in the filename,
                           e.g., file.png, or file.jpg, then that file type is
                           used, however defining in.figuretype will
                           override this.
                   def:    'pdf'
                     ------------
 in.gmtset         in:     {%s,%s,...}
                   ex:     Cell with one or more gmtset commands.
                           E.g. in.gmtset={'gmtset D_FORMAT %3.1e','gmtset ...'}
                     ------------
 in.header         in:     %s
                   ex:     Title of plot
                   def     ''
                     ------------
 in.header_font    in: %s or %f
                   ex: There are 35 fonts to choose from. Either provide a
                       number 1-35 or a string (case sensitive) of the
                       font to use. E.g., 'Helvetica' (0), 'Times-Roman' (4),
                       'Courier' (8), etc. See "gmtdefault" man page for the
                       whole list
                   def: 'Helvetica' ('0')
                     ------------
 in.header_fontsize in:    %s or %f (if %f, unit is assumed from in.measure_unit)
                   ex:     Title size
                   def:    '36p' (points)
                     ------------
 in.header_offset  in:     %s or %f (if %f, unit is assumed from in.measure_unit)
                   ex:     Moves the title in y-dir on the page
                   def:    '0.5c' (cm)
                     ------------
 in.keep_files     in:     %f
                   ex:     If you don't want to delete intermediate files
                   def:    false
                     ------------
 in.measure_unit   in:     %s
                   ex:     You can explicitly specify the unit used for
                       distances and lengths by appending c (cm), i (inch), m
                       (meter), or p (points). When no unit is indicated the
                       value will be assumed to be in the unit set by
                       MEASURE_UNIT. The default unit to use for all commands
                       if none is given.
                   def:    'c'
                     ------------
 in.nodata         in:     %f
                   ex:     If you only want a map (compatible with all options)
                   def:    false
                     ------------
 in.outdir         in:     %s
                   ex:     'name/a/directory'
                   def:    gmtlab('OUTDIR')  ('.' if not set)
                       ------------
 in.plotPlacement  in:     %s
                   ex:     String of global plotPlacements (see "man grdimage" for info)
                   def:    '-Ya5 -Xa5'
                       ------------
 in.ticks          in:     %s
                   ex:     '60g30/30g15'. The first value for both axis
                           denotes the tick interval to annotate, the second
                           value is the interval to draw the gridlines. xaxis and
                           yaxis are separated by '/'. i.e (x-axis: 'annot'g'grid'/ y-axis: 'annot'g'grid')
                           Note: To remove gridlines set the second value to 0.
                   def:    Determined by input lat/lon range.
                     ------------
 in.unit           in:     %s
                   ex:     String displayed on the y-axis of a legend
                   def:    ''
                     ------------
 in.xunit          in:     %s
                   ex:     String displayed on the x-axis of a legend
                   def:    ''
                     ------------

 NOTE:               For special characters in the string refer to the
                     section on character escape sequences (4.16 in GMT
                     cookbook v4.5.7).
                     e.g. for unit (or title) \Delta r^{-2} should be
                     written '@~D@~r@+-2' (see GMT_manpages under plotting
                     text (p207 GMT 5.0)

--------------------------------------------------------------------------

 PROJECTION, GRID, COASTLINES:

 in.region         in:     %s
                   ex:     '-180/180/-90/90'=global range, defined from
                           sprintf('%f/%f/%f/%f',lon1,lon2,lat1,lat2)
                   def:    determined by input lat/lon range
                     ------------
 in.nearneighbor   in:     %s
                   ex:     'nearneighbor OPT > filename.ps', explicitly sets
                           the nearneighbor GMT command directly. If
                           in.nearneighbor is a structure, it'll use the
                           structure arguments to generate the command.
                     ----------------------

 in.nearneighbor.    | STRUCTURE with one or more of the following fields:

  search           in:     %s
                   ex:     '30m' Search for data within 30 [arcmin]
                   def:    Loosely based on the density of the data points
                     ------------
  resolution       in:     %f [degree]
                   ex:     1˚ (== 60minuntes) looks for values withing 1˚
                   def:    Loosely based on the density of the data points, or avialable memory

                     ----------------------

 in.projection     in:     %s
                   ex:     See available projections in GMT manual.
                   def:    'Q' (cylindric equidistant)
                     ------------
 in.center         in:     %f
                   ex:     Center map at given longitude
                   def:    0˚
                     ------------
 in.map_width      in:     %s or %f (if %f, unit is assumed from in.measure_unit)
                   ex:     Set width of map, e.g., '20c'=20cm
                   def:    20 (cm)
                     ------------
 in.proj           in:     %s
                   ex:     Describes the projection, center, and map_width
                   def:    'Q0/20' (see above)
                     ------------
 in.pscoast        in:     %s
                   ex:     'pscoast OPT > filename.ps', explicitly sets the
                           pscoast GMT command.
                     ----------------------
 in.coast          in:     %f
                   ex:     If you don't want coastlines, set to false. If
                           in.coast is a structure, it'll use the structure
                           arguments to generate the pscoast command.
                   def:    To generate coastlines
                     ----------------------

 in.coast.           | STRUCTURE with one or more of the following fields:

  features         in:     %f
                   ex:     Don't plot features < in.features [km²]
                   def:    determined by lon/lat range
                     ------------
  resolution       in:     %s
                   ex:     (f)ull, (h)igh, (i)ntermediate, (l)ow, and (c)rude
                   def:    determined by lon/lat range
                     ------------
  rivers           in:     %s
                   ex:     Display rivers. pscoast -Ioption (1-10, a,r,i,c)
                   def:    '1' (=major rivers)
                     ------------
  width            in:     %f [points]
                   ex:     Width of coastlines
                   def:    .3
                     ----------------------
  color            in:     %s
                   ex:     Color of coast and rivers in rgb e.g. '255/255/255'
                           gives white coastlines
                   def:    COLOR_BACKGROUND
                     ----------------------

 (for grid, see in.ticks)

--------------------------------------------------------------------------

 COLORS & DATA REPRESENTATION:

 in.datarange      in:     [%f, %f]
                   ex:     Min and max range of data values to display
                     ------------
 in.grdimage       in:     %s
                   ex:     'grdimage OPT > filename.ps', explicitly sets
                           the grdimage GMT command directly.
                     ------------
 in.makecpt        in:     %s
                   ex:     'makecpt OPT > filename.ps', explicitly sets the
                           makecpt GMT command directly.
                     ------------
 in.cptfile        in:     %s
                   ex:     Path to any .cpt file generated previously
                     ------------
 in.ctable         in:     %s
                   ex:     See GMT color palettes
                   def:    'rainbow'

                     NOTE: 'mypolar' is a nice colortable for difference
                     plots, and there are two additional optional
                     arguments for this color table:
                                   ------------
                     in.reference:  in:    %d
                                    ex:    Where to center the white color
                                    def:   mean(data(:))

                           Note:    Recommend set in.reference = 0 for
                                    difference plots, but any reference
                                    will work.
                                   ------------

                     in.nwhite:     in:    %d
                                    ex:    The number of white contours around
                                           a reference value
                                    def:   determined by number of levels

 in.color_background   in:  %s
                       ex:  Set the background color (values less than range)
                       def: '0/0/0' ('black')
                     ------------
 in.color_foreground   in:  %s
                       ex:  Set the foreground color (values greater than range)
                       def: '255/255/255' ('white')
                     ------------
 in.color_nan          in:     %s
                       ex:     Set the color of NaNs
                       def:    '125/125/125' ('grey')
                     ------------
 in.nlevels            in:     %d
                       ex:     Refers to the number of contour levels (converted to
                           stepsize using datarange)
                       def:    20
                     ------------
 in.force_nlevels      in:     (logical)
                       ex:     If set to true, keep nlevels even if it
                               exceeds  the number of unique values.  If
                               set to false, nlevels is reduced to the
                               number of unique values if it exceeds it.
                       def:    false
                      ------------
 in.stepsize           in:     %f
                       ex:     The stepsize between data values. This overrides
                               nlevels (-T/min/max/stepsize in makecpt)
                       def:    determined by nlevels
                     ------------

 in.tickval            in:     %f
                       ex:     Vector of values to be used for ticks and data interval
                       def:    Determined by datarange and stepsize
                     ------------

 NOTE: For your own CUSTOM COLORTABLE use in.colorrange.colors
 (see below). Assign a color to a relative value, e.g between 0-1, where
 0 is for the minimum of the datarange and 1 is for the color of the
 maximum datarange. For example,
 in.colorrange.colors = {{0,'250/0/0''},{.3,'0/0/0'},{0.5,'0/255/0'},{1,'0/0/255'}},
 makes a colortable that goes from red to black to green to blue.
 Naturally you can also use the 'contour values' directly as long as you
 assign all levels a color.

                     ----------------------
 in.colorrange.      | STRUCTURE with one or more of the following fields:

  colors           in:     {{%d,%s},{%d,%s},etc.} %d is the data value, %s is the color
                   ex:     {20,'255/0/0'} (red in RGB)
                     ------------
  color_model      in:     %s
                   ex:     'RGB', 'HSV'
                   def:    'RGB'
                     ----------------------

------------------------------------------------------------------------------------
 LEGENDS:

 in.extra_legend     structure containing:
       name        in:     %s
                   ex:     An associated string name. E.g., 'NaN','masked', etc...
                   def:    mandatory
                     ------------
       type        in:     %s
                   ex:     'bg','fg', or 'nan', means use the color for the background,
                            foreground, or nan, given in in.color_background, in.color_foreground,
                            in.color_nan. So far these are the only 3 options.
                   def:    mandatory
                     ------------
       position    in:     %s
                   ex:     '9.7i/2.3i/0.8c/0.8c' ('x-displacement/y-displacement/height/width') (i = inch , c = cm)
                           Append 'h' for horisontal legend.
                   def:    Placement otherwise determined by the placement of the main legend
                     ------------
      fontsize     in:     %s or %f (if %f, unit is assumed from in.measure_unit)
                   ex:     '10c'
                     ----------------------
 in.pscale         in:     %s
                   ex:     'psscale OPT > filename.ps', explicitly sets the
                            psscale GMT command for the legend directly.
                     ------------
 in.pscale_extra   in:     %s
                   ex:     'psscale OPT > filename.ps', explicitly sets the
                           psscale GMT command for the extra legend directly.
                     ------------
 in.savelegend     in:     %f
                   ex:     Controls separate PDF for the legend.  If value
                           is 0, only 1 file will be generated containing
                           map+legend.  If value is 1, one file will be
                           generated for map+legend and one file for
                           legend only.  If value is 2, one file will be
                           generated containing ONLY the map, and one
                           containing ONLY the legend.  The legend will be
                           stored in [in.filename '_legend.' extension] in
                           the output directory.
                   def:    false
                     ------------
 in.legend         in:     %f
                   ex:     Set to false if you don't want a legend. if in.legend
                           is a structure, it's equivalent to in.legend = true
                   def:    true
                     ----------------------

 in.legend.          | STRUCTURE with one or more of the following fields:

  font_size
                   in:     %s or %f (if %f, unit is assumed from in.measure_unit)
                   ex:     Size of annotations in legend, e.g., '1c'=1cm
                   def:    '14p'
                     ------------
  box_spacing      in:     %f
                   ex:     Space between legend boxes
                   def:    0 (side by side)
                     ------------
  position         in:     %s
                   ex:     '9.7i/2.3i/10c/0.8c' (i = inch , c = cm)
                           ('x-displacement/y-displacement/height/width'). Append 'h'
                           for horisontal legend.
                   def:    Determined by map dimensions
                     ------------
  equalboxwidth    in:     %f
                   ex:     If the legend color boxes have to be the same size, 1
                   def:    false (-L option)
                     ------------
  length           in:     %s or %f (if %f, unit is assumed from in.measure_unit)
                   ex:     Toggle the length of the legend bar (e.g., '3.9i'=3.9 inch). Use negative value to reverse the
                           legend. See also width,xpos,ypos,orientation for legend
                   def:    '3.9i'
                     ------------
  orientation      in:     %s
                   ex:     If you want a horizontal/vertical legend input 'h'/'v'.
                   def:    Determined by map dimensions
                     ------------
  shift_tick_annotations
                   in:     %s
                   ex:     Move tick annotations to the right by x units, e.g. '.5i' (.5 inches)
                     ------------
  sidebar          in:     %f
                   ex:     Input scalar 0, 1, 2, or 3. Indicates none,
                           below range only, above range, or both
                   def:    Determined from data
                     ------------
  tick_annotations
                   in:     {%s,%s,...}
                   ex:     {'','','middle','',''}. Number of annotations must be = nlevels, and all
                           cell elements must be strings (or empty strings)
                     ------------
  tick_annotation_format
                   in:     %s
                   ex:     '%3.1e'
                     ------------
  tick_centering   in:     %f
                   ex:     Have tick annotation at the center of the boxes
                   def:    false (edges)
                     ------------
  tick_length      in:     %s or %f (if %f, unit is assumed from in.measure_unit)
                   ex:     The length of the ticks, e.g., '.5c'=.5cm
                     ------------
  tick_spacing     in:     %f
                   ex:     If you want to manually decide how the ticks in the
                           legend should be spread. x=> every xth data value,
                           1=>same number of ticks as datarange
                   def:    One tick per data level

                   NOTE: This option is desirable if you have many
                           data levels.
                     ------------
  width            in:     %s or %f (if %f, unit is assumed from in.measure_unit)
                   ex:     Toggle the width of the legend bar. See also length,xpos,ypos, orientation for legend
                   def:    '.2i'
                     ------------
  xpos             in:     %s or %f (if %f, unit is assumed from in.measure_unit)
                   ex:     Toggle the x-position of the center of the
                           legend bar. See also length,width,ypos, orientation for legend
                   def:    '9.8i' for verticle
                     ------------
  ypos             in:     %s or %f (if %f, unit is assumed from in.measure_unit)
                   ex:     Toggle the y-position of the center of the legend bar.
                           See also length,width,xpos, orientation for legend
                   def:    '2.3i' for verticle
------------------------------------------------------------------------------------
 PLOT LOCATION MARKERS:

  for multiple locations define all fields according to :
  in.locations(1).name = 'x',
  in.locations(2).name = 'y', etc...

                     ----------------------

 in.locations.       | Structure with one or more of the following fields:

  lat              in:     %f
                   ex:     Latitude of marker
                   def:    mandatory user input
                     ------------
  lon              in:     %f
                   ex:     Longitude of marker
                   def:    manditory user input
                     ------------
  name             in:     %s
                   ex:     Name of marker
                     ------------
  shape            in:     %s
                   ex:     Shape of marker
                   def:    'c' c=filled circle
                     ------------
  size             in:     %f
                   ex:     Size of shape.
                   def:    .08
                     ------------
  color            in:     %s
                   ex:     Color of marker
                   def:    'white'
                     ------------
  textsize         in:     %f
                   ex:     Size of name
                   def:    15
                     ------------
  textcolor        in:     %s
                   ex:     Color of name
                   def:    in.location.color
                     ------------
  textalign        in:     %s
                   ex:     Two letters for the position of marker relative
                           to the text. 1st letter for horizontal
                           position: L, C, R. 2nd letter for vertical
                           position: T, M, B
                   def:    'LT'
--------------------------------------------------------------------------

 PLOT CONTOURS:

 in.grdcontour     in:     %s
                   ex:     'grdcontour OPT > filename.ps', explicitly sets
                           the grdcontour GMT command directly.
                     ------------

 in.contourline.     | Structure with one or more of the following fields:

 spacing           in:     %f
                   ex:     Data interval between contours
                     ------------
 range             in:     [%f %f]
                   def:    in.datarange
                     ------------
 linethick         in:     %f
                     ------------
 more              in:     %s
                   ex:     Additional commands for GMT's grdcontour.
                           E.g. '-T1c/0.001c:LH'
                     ----------------------

 If several contour plots should overlap define all fields according to:
  in.grdcontour(1).spacing = x,
  in.grdcontour(2).spacing = y, etc...
--------------------------------------------------------------------------

 DRAW SHAPES ON MAP:
 in.psbox = [%f %f %f %f]
 in.psbox.           | Structure with one or more of the following fields:

                     ----------------------
  box              in:     [%f %f %f %f]
                   ex:     E.g. for box regions: [lon11 lat11 lon12 lat12;lon21 lat21 lon22 lat22]=
                           [Bottom left corner1, Top right corner1;
                           Bottom left corner2, Top right corner2]|
                     ------------
  boxes            in:     [%f %f ...]
                   ex:     The index of the last row of the regions. e.g 3 7, if
                           you have 2 regions defined by 3 resp 4 boxes. This is
                           useful for defining psboxcolor. Each index is defines
                           the last corner of a region, where a region is
                           essentially made up of many smaller boxes regions.
                     ------------
 boxcolor          in:     {[%f %f %f]}
                   ex:     RGB color or every region
                   def:    {[0 0 0]} for every region
                     ------------
 boxthick          in:     {%f}
                   ex:     Thickness of lines
                   def:    20 for every region boundary
                     ------------

 in.pspoly (%double)
                   in:     {[%f %f;%f %f;...] [%f %f;...]}
                   ex:     Draws a polygon. Use one cell row per polygon:
                           {[p1lon1 p1lat1; p1lon2 p1lat2| ...];...}
                     ------------
 in.pspolycolor    ex:     See in.psboxcolor
                     ------------
 in.pspolythick    ex:     See in.psboxthick
                     ------------

--------------------------------------------------------------------------
 DRAW TEXT ON A MAP

 in.pstext         in:     %s
                   ex:     'pstext OPT > filename.ps', explicitly sets
                           the pstext GMT command directly. If in.pstext is a
                           structure, it'll use the structure arguments to
                           generate the command.
                     ----------------------

 in.pstext.          | STRUCTURE with one or more of the following fields:

  for multiple text entries define all fields according to :
  in.pstext(1).text = 'example',
  in.pstext(2).text = 'example2', etc...

  lat              in:     %f
                   ex:     Centre word at this latitude
                   def:    manditory user input

  lon              in:     %f
                   ex:     Centre word at this longitude
                   def:    manditory user input

  text             in:     %s
                   ex:     String to appear at lat/lon
                   def:    manditory user input

  thick            in:     %f
                   ex:     Text size in points
                   def:    20

  angle            in:     %f
                   ex:     degrees counter-clockwise from horizontal
                   def:    0˚

  fontnum          in:     %f
                   ex:     Sets the font type
                   def:    1

  justify          in:     %f
                   ex:     Sets the alignment
                   def:    6

  color            in:     %s
                   ex:     RGB text color
                   def:    '0/0/0'
--------------------------------------------------------------------------

 QUICK TEST

 in.lat  = -89.5:89.5;
 in.lon  = -179.5:179.5
 in.data = rand(length(in.lat),length(in.lon))
 file = gmt_plot(in);


 Created by Salomon Eliasson (s.eliasson@ltu.se) and Oliver Lemke
 $Id: gmt_plot.m 8901 2014-06-19 08:12:54Z seliasson $

CROSS-REFERENCE INFORMATION ^

This function calls: This function is called by:

SUBFUNCTIONS ^

DOWNLOAD ^

gmt_plot.m

SOURCE CODE ^

0001 function filename = gmt_plot(in,field)
0002 % GMT_PLOT plotting interface for GMT (Generic Mapping Tools)
0003 %
0004 % The function is basically a wrapper that calls gmt shell commands using easy
0005 % to use matlab arguments. Try test_gmt.m for some examples on how to use the function.
0006 % Preferably, the data should be CENTERED if the data is gridded (fastest performance).
0007 %
0008 % OUT   filename  The filename of the figure.
0009 %
0010 % IN    in        A structure with input data and options. See below for
0011 %                 a detailed description of the structure.
0012 %
0013 % OPT   field     The string name of the structure element that contains
0014 %                 the data to be plotted. If no field is given, 'data'
0015 %                 is assumed.
0016 %
0017 % Easy example: If you just want to plot some data..
0018 %                 in.somefield = data2plot
0019 %                 in.lon  = longitudes
0020 %                 in.lat  = latitudes
0021 %
0022 %                 file = gmt_plot(in,'somefield');
0023 %
0024 % see STRUCTURE CONTENTS below for the rest of the available arguments
0025 %
0026 % VIEWING THE PLOT:
0027 % The easiest thing to do is to define a viewer in your startup file.
0028 %
0029 % Add something like the following to your startup file')
0030 % gmtlab( 'OUTDIR', '/name/a/favorite' ) %% The default directory to put plots
0031 % gmtlab( 'PSVIEWER','gv');             %% set viewer for .ps files
0032 % gmtlab( 'PDFVIEWER','xpdf -z width'); %% set viewer for .pdf files
0033 % gmtlab( 'OPEN_COMMAND','gnome-open'); %% set a general open command
0034 % gmtlab( 'VERBOSITY',1); %% This outputs stdout on the screen.
0035 %
0036 % Structure contents:
0037 %
0038 % MANDATORY INPUT
0039 %
0040 % 1) in.(field) % the data (default is field='data' i.e. in.data)
0041 % 2) in.lat     % the corresponding latitudes
0042 % 3) in.lon     % the corresponding longitudes
0043 %
0044 % If your data is ungridded the dimensions of the manditory input
0045 % (lat,lon.data) must be the same.
0046 % i.e isequal(size(in.lat),size(in.lon),size(in.data))
0047 %
0048 % If your data is gridded the data MUST have the dimensions:
0049 % [length(in.lat),length(in.lon)] == size(in.(field));
0050 %  << transpose: in.(field) = in.(field)'; if this is not the case >>
0051 %
0052 % NOTE: 1) If your data is UNGRIDDED I recommend setting
0053 %          in.nearneighbor.resolution = Deg (something suitable).
0054 %       2) gmt_plot automatically detects if the data is gridded or not
0055 %
0056 %
0057 % HOW TO READ VARIABLE DESCRIPTION OF OPTIONAL VARIABLES:
0058 % KEY:  in.variable   in: = expect input type, ex: = Explanation/Example, de: = Default value/behavior
0059 % NOTE: If "def" is missing for a variable it means the variable is not used by default
0060 %
0061 %                  types: %s=character or string
0062 %                         %f=numeric/logical
0063 %                         {}=cell
0064 %--------------------------------------------------------------------------
0065 %
0066 % GENERAL:
0067 %
0068 % in.annot_font_size_primary
0069 %                   in:     %s or %f (if %f, unit is assumed from in.measure_unit)
0070 %                   ex:     The size of the font, e.g., '2c'=2cm for e.g., the axis.
0071 %                           Setting this will also change the size of the
0072 %                           fonts of the annotations for the legend. If you
0073 %                           want a different size for the legend
0074 %                           annotations, set in.legend.font_size.
0075 %                   def:    '14p'
0076 % in.basemap_axis   in:     %s
0077 %                   ex:     'WSne', annotates West and South of the map,
0078 %                           but not North or East
0079 %                   def:    'WSne'
0080 %                   ------------
0081 % in.display        in:     %f
0082 %                   ex:     If false, file created but not displayed
0083 %                   def:    true
0084 %                   ------------
0085 % in.filename       in:     %s
0086 %                   ex:     'yourfilename', or 'yourfilename.jpg'
0087 %                   def:    Generated from title. The filetype is determined by the file
0088 %                           ending given by your filename, e.g., any of bla.{pdf,jpg,eps,tif,png,ps}
0089 %                     ------------
0090 % in.figuretype     in:     %s
0091 %                   ex:     'eps','pdf','BMP','jpg','PNG','PPM' (not recommended), or 'tif'.
0092 %                           If the figure type is included in the filename,
0093 %                           e.g., file.png, or file.jpg, then that file type is
0094 %                           used, however defining in.figuretype will
0095 %                           override this.
0096 %                   def:    'pdf'
0097 %                     ------------
0098 % in.gmtset         in:     {%s,%s,...}
0099 %                   ex:     Cell with one or more gmtset commands.
0100 %                           E.g. in.gmtset={'gmtset D_FORMAT %3.1e','gmtset ...'}
0101 %                     ------------
0102 % in.header         in:     %s
0103 %                   ex:     Title of plot
0104 %                   def     ''
0105 %                     ------------
0106 % in.header_font    in: %s or %f
0107 %                   ex: There are 35 fonts to choose from. Either provide a
0108 %                       number 1-35 or a string (case sensitive) of the
0109 %                       font to use. E.g., 'Helvetica' (0), 'Times-Roman' (4),
0110 %                       'Courier' (8), etc. See "gmtdefault" man page for the
0111 %                       whole list
0112 %                   def: 'Helvetica' ('0')
0113 %                     ------------
0114 % in.header_fontsize in:    %s or %f (if %f, unit is assumed from in.measure_unit)
0115 %                   ex:     Title size
0116 %                   def:    '36p' (points)
0117 %                     ------------
0118 % in.header_offset  in:     %s or %f (if %f, unit is assumed from in.measure_unit)
0119 %                   ex:     Moves the title in y-dir on the page
0120 %                   def:    '0.5c' (cm)
0121 %                     ------------
0122 % in.keep_files     in:     %f
0123 %                   ex:     If you don't want to delete intermediate files
0124 %                   def:    false
0125 %                     ------------
0126 % in.measure_unit   in:     %s
0127 %                   ex:     You can explicitly specify the unit used for
0128 %                       distances and lengths by appending c (cm), i (inch), m
0129 %                       (meter), or p (points). When no unit is indicated the
0130 %                       value will be assumed to be in the unit set by
0131 %                       MEASURE_UNIT. The default unit to use for all commands
0132 %                       if none is given.
0133 %                   def:    'c'
0134 %                     ------------
0135 % in.nodata         in:     %f
0136 %                   ex:     If you only want a map (compatible with all options)
0137 %                   def:    false
0138 %                     ------------
0139 % in.outdir         in:     %s
0140 %                   ex:     'name/a/directory'
0141 %                   def:    gmtlab('OUTDIR')  ('.' if not set)
0142 %                       ------------
0143 % in.plotPlacement  in:     %s
0144 %                   ex:     String of global plotPlacements (see "man grdimage" for info)
0145 %                   def:    '-Ya5 -Xa5'
0146 %                       ------------
0147 % in.ticks          in:     %s
0148 %                   ex:     '60g30/30g15'. The first value for both axis
0149 %                           denotes the tick interval to annotate, the second
0150 %                           value is the interval to draw the gridlines. xaxis and
0151 %                           yaxis are separated by '/'. i.e (x-axis: 'annot'g'grid'/ y-axis: 'annot'g'grid')
0152 %                           Note: To remove gridlines set the second value to 0.
0153 %                   def:    Determined by input lat/lon range.
0154 %                     ------------
0155 % in.unit           in:     %s
0156 %                   ex:     String displayed on the y-axis of a legend
0157 %                   def:    ''
0158 %                     ------------
0159 % in.xunit          in:     %s
0160 %                   ex:     String displayed on the x-axis of a legend
0161 %                   def:    ''
0162 %                     ------------
0163 %
0164 % NOTE:               For special characters in the string refer to the
0165 %                     section on character escape sequences (4.16 in GMT
0166 %                     cookbook v4.5.7).
0167 %                     e.g. for unit (or title) \Delta r^{-2} should be
0168 %                     written '@~D@~r@+-2' (see GMT_manpages under plotting
0169 %                     text (p207 GMT 5.0)
0170 %
0171 %--------------------------------------------------------------------------
0172 %
0173 % PROJECTION, GRID, COASTLINES:
0174 %
0175 % in.region         in:     %s
0176 %                   ex:     '-180/180/-90/90'=global range, defined from
0177 %                           sprintf('%f/%f/%f/%f',lon1,lon2,lat1,lat2)
0178 %                   def:    determined by input lat/lon range
0179 %                     ------------
0180 % in.nearneighbor   in:     %s
0181 %                   ex:     'nearneighbor OPT > filename.ps', explicitly sets
0182 %                           the nearneighbor GMT command directly. If
0183 %                           in.nearneighbor is a structure, it'll use the
0184 %                           structure arguments to generate the command.
0185 %                     ----------------------
0186 %
0187 % in.nearneighbor.    | STRUCTURE with one or more of the following fields:
0188 %
0189 %  search           in:     %s
0190 %                   ex:     '30m' Search for data within 30 [arcmin]
0191 %                   def:    Loosely based on the density of the data points
0192 %                     ------------
0193 %  resolution       in:     %f [degree]
0194 %                   ex:     1˚ (== 60minuntes) looks for values withing 1˚
0195 %                   def:    Loosely based on the density of the data points, or avialable memory
0196 %
0197 %                     ----------------------
0198 %
0199 % in.projection     in:     %s
0200 %                   ex:     See available projections in GMT manual.
0201 %                   def:    'Q' (cylindric equidistant)
0202 %                     ------------
0203 % in.center         in:     %f
0204 %                   ex:     Center map at given longitude
0205 %                   def:    0˚
0206 %                     ------------
0207 % in.map_width      in:     %s or %f (if %f, unit is assumed from in.measure_unit)
0208 %                   ex:     Set width of map, e.g., '20c'=20cm
0209 %                   def:    20 (cm)
0210 %                     ------------
0211 % in.proj           in:     %s
0212 %                   ex:     Describes the projection, center, and map_width
0213 %                   def:    'Q0/20' (see above)
0214 %                     ------------
0215 % in.pscoast        in:     %s
0216 %                   ex:     'pscoast OPT > filename.ps', explicitly sets the
0217 %                           pscoast GMT command.
0218 %                     ----------------------
0219 % in.coast          in:     %f
0220 %                   ex:     If you don't want coastlines, set to false. If
0221 %                           in.coast is a structure, it'll use the structure
0222 %                           arguments to generate the pscoast command.
0223 %                   def:    To generate coastlines
0224 %                     ----------------------
0225 %
0226 % in.coast.           | STRUCTURE with one or more of the following fields:
0227 %
0228 %  features         in:     %f
0229 %                   ex:     Don't plot features < in.features [km²]
0230 %                   def:    determined by lon/lat range
0231 %                     ------------
0232 %  resolution       in:     %s
0233 %                   ex:     (f)ull, (h)igh, (i)ntermediate, (l)ow, and (c)rude
0234 %                   def:    determined by lon/lat range
0235 %                     ------------
0236 %  rivers           in:     %s
0237 %                   ex:     Display rivers. pscoast -Ioption (1-10, a,r,i,c)
0238 %                   def:    '1' (=major rivers)
0239 %                     ------------
0240 %  width            in:     %f [points]
0241 %                   ex:     Width of coastlines
0242 %                   def:    .3
0243 %                     ----------------------
0244 %  color            in:     %s
0245 %                   ex:     Color of coast and rivers in rgb e.g. '255/255/255'
0246 %                           gives white coastlines
0247 %                   def:    COLOR_BACKGROUND
0248 %                     ----------------------
0249 %
0250 % (for grid, see in.ticks)
0251 %
0252 %--------------------------------------------------------------------------
0253 %
0254 % COLORS & DATA REPRESENTATION:
0255 %
0256 % in.datarange      in:     [%f, %f]
0257 %                   ex:     Min and max range of data values to display
0258 %                     ------------
0259 % in.grdimage       in:     %s
0260 %                   ex:     'grdimage OPT > filename.ps', explicitly sets
0261 %                           the grdimage GMT command directly.
0262 %                     ------------
0263 % in.makecpt        in:     %s
0264 %                   ex:     'makecpt OPT > filename.ps', explicitly sets the
0265 %                           makecpt GMT command directly.
0266 %                     ------------
0267 % in.cptfile        in:     %s
0268 %                   ex:     Path to any .cpt file generated previously
0269 %                     ------------
0270 % in.ctable         in:     %s
0271 %                   ex:     See GMT color palettes
0272 %                   def:    'rainbow'
0273 %
0274 %                     NOTE: 'mypolar' is a nice colortable for difference
0275 %                     plots, and there are two additional optional
0276 %                     arguments for this color table:
0277 %                                   ------------
0278 %                     in.reference:  in:    %d
0279 %                                    ex:    Where to center the white color
0280 %                                    def:   mean(data(:))
0281 %
0282 %                           Note:    Recommend set in.reference = 0 for
0283 %                                    difference plots, but any reference
0284 %                                    will work.
0285 %                                   ------------
0286 %
0287 %                     in.nwhite:     in:    %d
0288 %                                    ex:    The number of white contours around
0289 %                                           a reference value
0290 %                                    def:   determined by number of levels
0291 %
0292 % in.color_background   in:  %s
0293 %                       ex:  Set the background color (values less than range)
0294 %                       def: '0/0/0' ('black')
0295 %                     ------------
0296 % in.color_foreground   in:  %s
0297 %                       ex:  Set the foreground color (values greater than range)
0298 %                       def: '255/255/255' ('white')
0299 %                     ------------
0300 % in.color_nan          in:     %s
0301 %                       ex:     Set the color of NaNs
0302 %                       def:    '125/125/125' ('grey')
0303 %                     ------------
0304 % in.nlevels            in:     %d
0305 %                       ex:     Refers to the number of contour levels (converted to
0306 %                           stepsize using datarange)
0307 %                       def:    20
0308 %                     ------------
0309 % in.force_nlevels      in:     (logical)
0310 %                       ex:     If set to true, keep nlevels even if it
0311 %                               exceeds  the number of unique values.  If
0312 %                               set to false, nlevels is reduced to the
0313 %                               number of unique values if it exceeds it.
0314 %                       def:    false
0315 %                      ------------
0316 % in.stepsize           in:     %f
0317 %                       ex:     The stepsize between data values. This overrides
0318 %                               nlevels (-T/min/max/stepsize in makecpt)
0319 %                       def:    determined by nlevels
0320 %                     ------------
0321 %
0322 % in.tickval            in:     %f
0323 %                       ex:     Vector of values to be used for ticks and data interval
0324 %                       def:    Determined by datarange and stepsize
0325 %                     ------------
0326 %
0327 % NOTE: For your own CUSTOM COLORTABLE use in.colorrange.colors
0328 % (see below). Assign a color to a relative value, e.g between 0-1, where
0329 % 0 is for the minimum of the datarange and 1 is for the color of the
0330 % maximum datarange. For example,
0331 % in.colorrange.colors = {{0,'250/0/0''},{.3,'0/0/0'},{0.5,'0/255/0'},{1,'0/0/255'}},
0332 % makes a colortable that goes from red to black to green to blue.
0333 % Naturally you can also use the 'contour values' directly as long as you
0334 % assign all levels a color.
0335 %
0336 %                     ----------------------
0337 % in.colorrange.      | STRUCTURE with one or more of the following fields:
0338 %
0339 %  colors           in:     {{%d,%s},{%d,%s},etc.} %d is the data value, %s is the color
0340 %                   ex:     {20,'255/0/0'} (red in RGB)
0341 %                     ------------
0342 %  color_model      in:     %s
0343 %                   ex:     'RGB', 'HSV'
0344 %                   def:    'RGB'
0345 %                     ----------------------
0346 %
0347 %------------------------------------------------------------------------------------
0348 % LEGENDS:
0349 %
0350 % in.extra_legend     structure containing:
0351 %       name        in:     %s
0352 %                   ex:     An associated string name. E.g., 'NaN','masked', etc...
0353 %                   def:    mandatory
0354 %                     ------------
0355 %       type        in:     %s
0356 %                   ex:     'bg','fg', or 'nan', means use the color for the background,
0357 %                            foreground, or nan, given in in.color_background, in.color_foreground,
0358 %                            in.color_nan. So far these are the only 3 options.
0359 %                   def:    mandatory
0360 %                     ------------
0361 %       position    in:     %s
0362 %                   ex:     '9.7i/2.3i/0.8c/0.8c' ('x-displacement/y-displacement/height/width') (i = inch , c = cm)
0363 %                           Append 'h' for horisontal legend.
0364 %                   def:    Placement otherwise determined by the placement of the main legend
0365 %                     ------------
0366 %      fontsize     in:     %s or %f (if %f, unit is assumed from in.measure_unit)
0367 %                   ex:     '10c'
0368 %                     ----------------------
0369 % in.pscale         in:     %s
0370 %                   ex:     'psscale OPT > filename.ps', explicitly sets the
0371 %                            psscale GMT command for the legend directly.
0372 %                     ------------
0373 % in.pscale_extra   in:     %s
0374 %                   ex:     'psscale OPT > filename.ps', explicitly sets the
0375 %                           psscale GMT command for the extra legend directly.
0376 %                     ------------
0377 % in.savelegend     in:     %f
0378 %                   ex:     Controls separate PDF for the legend.  If value
0379 %                           is 0, only 1 file will be generated containing
0380 %                           map+legend.  If value is 1, one file will be
0381 %                           generated for map+legend and one file for
0382 %                           legend only.  If value is 2, one file will be
0383 %                           generated containing ONLY the map, and one
0384 %                           containing ONLY the legend.  The legend will be
0385 %                           stored in [in.filename '_legend.' extension] in
0386 %                           the output directory.
0387 %                   def:    false
0388 %                     ------------
0389 % in.legend         in:     %f
0390 %                   ex:     Set to false if you don't want a legend. if in.legend
0391 %                           is a structure, it's equivalent to in.legend = true
0392 %                   def:    true
0393 %                     ----------------------
0394 %
0395 % in.legend.          | STRUCTURE with one or more of the following fields:
0396 %
0397 %  font_size
0398 %                   in:     %s or %f (if %f, unit is assumed from in.measure_unit)
0399 %                   ex:     Size of annotations in legend, e.g., '1c'=1cm
0400 %                   def:    '14p'
0401 %                     ------------
0402 %  box_spacing      in:     %f
0403 %                   ex:     Space between legend boxes
0404 %                   def:    0 (side by side)
0405 %                     ------------
0406 %  position         in:     %s
0407 %                   ex:     '9.7i/2.3i/10c/0.8c' (i = inch , c = cm)
0408 %                           ('x-displacement/y-displacement/height/width'). Append 'h'
0409 %                           for horisontal legend.
0410 %                   def:    Determined by map dimensions
0411 %                     ------------
0412 %  equalboxwidth    in:     %f
0413 %                   ex:     If the legend color boxes have to be the same size, 1
0414 %                   def:    false (-L option)
0415 %                     ------------
0416 %  length           in:     %s or %f (if %f, unit is assumed from in.measure_unit)
0417 %                   ex:     Toggle the length of the legend bar (e.g., '3.9i'=3.9 inch). Use negative value to reverse the
0418 %                           legend. See also width,xpos,ypos,orientation for legend
0419 %                   def:    '3.9i'
0420 %                     ------------
0421 %  orientation      in:     %s
0422 %                   ex:     If you want a horizontal/vertical legend input 'h'/'v'.
0423 %                   def:    Determined by map dimensions
0424 %                     ------------
0425 %  shift_tick_annotations
0426 %                   in:     %s
0427 %                   ex:     Move tick annotations to the right by x units, e.g. '.5i' (.5 inches)
0428 %                     ------------
0429 %  sidebar          in:     %f
0430 %                   ex:     Input scalar 0, 1, 2, or 3. Indicates none,
0431 %                           below range only, above range, or both
0432 %                   def:    Determined from data
0433 %                     ------------
0434 %  tick_annotations
0435 %                   in:     {%s,%s,...}
0436 %                   ex:     {'','','middle','',''}. Number of annotations must be = nlevels, and all
0437 %                           cell elements must be strings (or empty strings)
0438 %                     ------------
0439 %  tick_annotation_format
0440 %                   in:     %s
0441 %                   ex:     '%3.1e'
0442 %                     ------------
0443 %  tick_centering   in:     %f
0444 %                   ex:     Have tick annotation at the center of the boxes
0445 %                   def:    false (edges)
0446 %                     ------------
0447 %  tick_length      in:     %s or %f (if %f, unit is assumed from in.measure_unit)
0448 %                   ex:     The length of the ticks, e.g., '.5c'=.5cm
0449 %                     ------------
0450 %  tick_spacing     in:     %f
0451 %                   ex:     If you want to manually decide how the ticks in the
0452 %                           legend should be spread. x=> every xth data value,
0453 %                           1=>same number of ticks as datarange
0454 %                   def:    One tick per data level
0455 %
0456 %                   NOTE: This option is desirable if you have many
0457 %                           data levels.
0458 %                     ------------
0459 %  width            in:     %s or %f (if %f, unit is assumed from in.measure_unit)
0460 %                   ex:     Toggle the width of the legend bar. See also length,xpos,ypos, orientation for legend
0461 %                   def:    '.2i'
0462 %                     ------------
0463 %  xpos             in:     %s or %f (if %f, unit is assumed from in.measure_unit)
0464 %                   ex:     Toggle the x-position of the center of the
0465 %                           legend bar. See also length,width,ypos, orientation for legend
0466 %                   def:    '9.8i' for verticle
0467 %                     ------------
0468 %  ypos             in:     %s or %f (if %f, unit is assumed from in.measure_unit)
0469 %                   ex:     Toggle the y-position of the center of the legend bar.
0470 %                           See also length,width,xpos, orientation for legend
0471 %                   def:    '2.3i' for verticle
0472 %------------------------------------------------------------------------------------
0473 % PLOT LOCATION MARKERS:
0474 %
0475 %  for multiple locations define all fields according to :
0476 %  in.locations(1).name = 'x',
0477 %  in.locations(2).name = 'y', etc...
0478 %
0479 %                     ----------------------
0480 %
0481 % in.locations.       | Structure with one or more of the following fields:
0482 %
0483 %  lat              in:     %f
0484 %                   ex:     Latitude of marker
0485 %                   def:    mandatory user input
0486 %                     ------------
0487 %  lon              in:     %f
0488 %                   ex:     Longitude of marker
0489 %                   def:    manditory user input
0490 %                     ------------
0491 %  name             in:     %s
0492 %                   ex:     Name of marker
0493 %                     ------------
0494 %  shape            in:     %s
0495 %                   ex:     Shape of marker
0496 %                   def:    'c' c=filled circle
0497 %                     ------------
0498 %  size             in:     %f
0499 %                   ex:     Size of shape.
0500 %                   def:    .08
0501 %                     ------------
0502 %  color            in:     %s
0503 %                   ex:     Color of marker
0504 %                   def:    'white'
0505 %                     ------------
0506 %  textsize         in:     %f
0507 %                   ex:     Size of name
0508 %                   def:    15
0509 %                     ------------
0510 %  textcolor        in:     %s
0511 %                   ex:     Color of name
0512 %                   def:    in.location.color
0513 %                     ------------
0514 %  textalign        in:     %s
0515 %                   ex:     Two letters for the position of marker relative
0516 %                           to the text. 1st letter for horizontal
0517 %                           position: L, C, R. 2nd letter for vertical
0518 %                           position: T, M, B
0519 %                   def:    'LT'
0520 %--------------------------------------------------------------------------
0521 %
0522 % PLOT CONTOURS:
0523 %
0524 % in.grdcontour     in:     %s
0525 %                   ex:     'grdcontour OPT > filename.ps', explicitly sets
0526 %                           the grdcontour GMT command directly.
0527 %                     ------------
0528 %
0529 % in.contourline.     | Structure with one or more of the following fields:
0530 %
0531 % spacing           in:     %f
0532 %                   ex:     Data interval between contours
0533 %                     ------------
0534 % range             in:     [%f %f]
0535 %                   def:    in.datarange
0536 %                     ------------
0537 % linethick         in:     %f
0538 %                     ------------
0539 % more              in:     %s
0540 %                   ex:     Additional commands for GMT's grdcontour.
0541 %                           E.g. '-T1c/0.001c:LH'
0542 %                     ----------------------
0543 %
0544 % If several contour plots should overlap define all fields according to:
0545 %  in.grdcontour(1).spacing = x,
0546 %  in.grdcontour(2).spacing = y, etc...
0547 %--------------------------------------------------------------------------
0548 %
0549 % DRAW SHAPES ON MAP:
0550 % in.psbox = [%f %f %f %f]
0551 % in.psbox.           | Structure with one or more of the following fields:
0552 %
0553 %                     ----------------------
0554 %  box              in:     [%f %f %f %f]
0555 %                   ex:     E.g. for box regions: [lon11 lat11 lon12 lat12;lon21 lat21 lon22 lat22]=
0556 %                           [Bottom left corner1, Top right corner1;
0557 %                           Bottom left corner2, Top right corner2]|
0558 %                     ------------
0559 %  boxes            in:     [%f %f ...]
0560 %                   ex:     The index of the last row of the regions. e.g 3 7, if
0561 %                           you have 2 regions defined by 3 resp 4 boxes. This is
0562 %                           useful for defining psboxcolor. Each index is defines
0563 %                           the last corner of a region, where a region is
0564 %                           essentially made up of many smaller boxes regions.
0565 %                     ------------
0566 % boxcolor          in:     {[%f %f %f]}
0567 %                   ex:     RGB color or every region
0568 %                   def:    {[0 0 0]} for every region
0569 %                     ------------
0570 % boxthick          in:     {%f}
0571 %                   ex:     Thickness of lines
0572 %                   def:    20 for every region boundary
0573 %                     ------------
0574 %
0575 % in.pspoly (%double)
0576 %                   in:     {[%f %f;%f %f;...] [%f %f;...]}
0577 %                   ex:     Draws a polygon. Use one cell row per polygon:
0578 %                           {[p1lon1 p1lat1; p1lon2 p1lat2| ...];...}
0579 %                     ------------
0580 % in.pspolycolor    ex:     See in.psboxcolor
0581 %                     ------------
0582 % in.pspolythick    ex:     See in.psboxthick
0583 %                     ------------
0584 %
0585 %--------------------------------------------------------------------------
0586 % DRAW TEXT ON A MAP
0587 %
0588 % in.pstext         in:     %s
0589 %                   ex:     'pstext OPT > filename.ps', explicitly sets
0590 %                           the pstext GMT command directly. If in.pstext is a
0591 %                           structure, it'll use the structure arguments to
0592 %                           generate the command.
0593 %                     ----------------------
0594 %
0595 % in.pstext.          | STRUCTURE with one or more of the following fields:
0596 %
0597 %  for multiple text entries define all fields according to :
0598 %  in.pstext(1).text = 'example',
0599 %  in.pstext(2).text = 'example2', etc...
0600 %
0601 %  lat              in:     %f
0602 %                   ex:     Centre word at this latitude
0603 %                   def:    manditory user input
0604 %
0605 %  lon              in:     %f
0606 %                   ex:     Centre word at this longitude
0607 %                   def:    manditory user input
0608 %
0609 %  text             in:     %s
0610 %                   ex:     String to appear at lat/lon
0611 %                   def:    manditory user input
0612 %
0613 %  thick            in:     %f
0614 %                   ex:     Text size in points
0615 %                   def:    20
0616 %
0617 %  angle            in:     %f
0618 %                   ex:     degrees counter-clockwise from horizontal
0619 %                   def:    0˚
0620 %
0621 %  fontnum          in:     %f
0622 %                   ex:     Sets the font type
0623 %                   def:    1
0624 %
0625 %  justify          in:     %f
0626 %                   ex:     Sets the alignment
0627 %                   def:    6
0628 %
0629 %  color            in:     %s
0630 %                   ex:     RGB text color
0631 %                   def:    '0/0/0'
0632 %--------------------------------------------------------------------------
0633 %
0634 % QUICK TEST
0635 %
0636 % in.lat  = -89.5:89.5;
0637 % in.lon  = -179.5:179.5
0638 % in.data = rand(length(in.lat),length(in.lon))
0639 % file = gmt_plot(in);
0640 %
0641 %
0642 % Created by Salomon Eliasson (s.eliasson@ltu.se) and Oliver Lemke
0643 % $Id: gmt_plot.m 8901 2014-06-19 08:12:54Z seliasson $
0644 
0645 if ~exist('field','var') && isfield(in,'data')
0646     field = 'data';
0647 end
0648 
0649 assert(logical(exist('field','var')) || (isfield(in,'nodata')&&in.nodata) ,...
0650     ['atmlab:' mfilename ':badInput'],...
0651     'I need a "field".\nIf you want to plot the map with no data, input in.nodata=true')
0652 
0653 check_input(in)
0654 
0655 if isfield(in,'nodata')&&in.nodata
0656     out = set_GMT_plot(in);
0657 else out = set_GMT_plot(in,field);
0658 end
0659 
0660 % make TEMPDIR and set atmlab('VERBOSITY') to gmtlab('VERBOSITY')
0661 % cleanup after I'm done
0662 out.tmpdir = create_tmpfolder();
0663 p = pwd(); V = atmlab('VERBOSITY');
0664 cleanupObject = onCleanup(@() gmtcleanup(out.tmpdir,p,out.keep_files,V));
0665 
0666 atmlab('VERBOSITY',gmtlab('VERBOSITY'));
0667 
0668 cd(out.tmpdir);
0669 
0670 if out.gridded
0671     out.grdfile = [out.filename '.grd'];
0672     gmt_nc_save_gridded(out.lon,out.lat,out.(field),out.grdfile);
0673     logtext(1,'Writing grdfile: %s sucessfull\n',out.grdfile)
0674 else
0675     if ~out.nodata
0676         out.ungriddedfile = [out.filename '.nc'];
0677         gmt_nc_save_ungridded(out.ungriddedfile,double(out.(field)),out.lat,out.lon);
0678     end
0679 end
0680 
0681 % main function
0682 commands = create_gmt_earth(out);
0683 
0684 % finalize
0685 
0686 filename=sort_figures(out,commands);
0687 
0688 end
0689 %%%%%%%%%%%%%%%%%%%%
0690 % SUBFUNCTIONS
0691 %     ||||
0692 %     vvvv
0693 function in = set_GMT_plot(in,field)
0694 %% SETUP %%
0695 
0696 
0697 % Test is GMT is installed and in the path
0698 [a,b] = system('which gmtset');
0699 if a == 1
0700     error(['gmtlab:' mfilename ':shell'],[ [ b '\n\n'],...
0701         'Either GMT is not installed\n',...
0702         'or\n',...
0703         'You need to add its installation directory to your PATH\n',...
0704         'e.g. in Matlab you can add the PATH via \n',...
0705         'setenv(''PATH'',[getenv(''PATH'') '':<GMTINSTALLDIR>/bin''])'])
0706 end
0707 
0708 % SET DEFAULTS
0709 % general
0710 default.annot_font_size_primary = '14p';     % size of axis labels (include legend if not set differently by in.legend.font_size)
0711 default.basemap_axis    = 'nSeW';           % Annotates West and South of the map.
0712 default.display         = true;             % Display figure to screen
0713 default.center          = 0;                % The center longitude of the map. The region has to be -180:180 (cyclic)
0714 default.color_background= '0/0/0';
0715 default.color_foreground= '255/255/255';
0716 default.color_nan       = '150/150/150';
0717 default.header          = '';               % no title by default
0718 default.header_font     = 'Helvetica';      % one of 35 available fonts
0719 default.header_fontsize = '36p';
0720 in = optargs_struct(in,default);
0721 % how far the title is removed from the top of the map (depends on 'N' or 'n')
0722 default.header_offset   = [num2str(-0.4+0.6*ismember('N',in.basemap_axis)) 'c'];
0723 default.keep_files      = false;            % keep intermediate files (debugging)
0724 default.map_width       = 20;
0725 default.measure_unit    = 'cm';             % Choose between cm, inch, m, and point.
0726 default.nlevels         = 20;               % Use 20 color levels by default
0727 default.force_nlevels   = false;            % do not force, e.g. reduce if uniques are less
0728 default.nodata          = false;            % true if you only want the map
0729 default.outdir          = gmtlab('OUTDIR'); % where to put the figure
0730 default.plotPlacement   = '-Xa5 -Ya5';      % String of global plotPlacements
0731 default.projection      = 'Q';              % Cylindrical Equidistant Projection.
0732 default.savelegend      = false;            % make an additional pdf-file only containing the legend
0733 default.unit            = '';               % unit displayed with legend
0734 default.xunit           = '';               % xlabel for the legend
0735 
0736 in = optargs_struct(in,default);
0737 
0738 in.outdir = sanitise(in.outdir);
0739 
0740 if strcmp(in.outdir(1),'~')
0741     % netcdffunctions don't like ~ for home
0742     in.outdir = [getenv('HOME') '/' in.outdir(2:end)];
0743 end
0744 
0745 if system(sprintf('test -d %s -a -w %s',in.outdir,in.outdir))
0746     error(['gmtlab:' mfilename ':BadInput'],...
0747         'Either %s doesn''t exist, or atmlab does not have write access to %s',in.outdir,in.outdir)
0748 end
0749 
0750 % backward compatibility
0751 if isfield(in,'header_size')
0752     warning('atmlab:temporary','in.header_size has been renamed to in.header_fontsize. in.header_size will be removed in future releases')
0753     in.header_fontsize = in.header_size; in=rmfield(in,'header_size');
0754 end
0755 
0756 if ~isempty(in.header)
0757     default.filename = ['gmtfile_' in.header '.pdf'];
0758 else default.filename = 'default.pdf';
0759 end
0760 
0761 in = optargs_struct(in,default);
0762 
0763 % find default figuretype
0764 b = regexp(in.filename,'\.');
0765 if ~isempty(b)
0766     ft = in.filename(b(end)+1:end);
0767     if ismember(lower(ft),lower({'eps','pdf','BMP','JPEG','jpg','PNG','PPM','tif'}))
0768         default.figuretype = ft;
0769     else
0770         logtext(atmlab('OUT'),'figuretype: %s is not an available type. Will produce .pdf\n',ft);
0771         default.figuretype = 'pdf';
0772     end
0773     if ~isfield(in,'figuretype')
0774         in.filename=in.filename(1:b(end)-1);
0775     end
0776 else
0777     default.figuretype = 'pdf';
0778 end
0779 
0780 in = optargs_struct(in,default);
0781 
0782 in.filename = sanitise(in.filename);
0783 in.header = regexprep(in.header,'([()])','\\$1');
0784 in.header = regexprep(in.header,':',' ');
0785 
0786 %coast
0787 if ~isfield(in,'coast') || isstruct(in.coast) || in.coast
0788     if ~isfield(in,'coast'), in.coast=struct([]);end
0789     default.rivers      = '1';  % '1' displays major rivers only. 'a' displays all.
0790     default.width       = .3;   % width of the coast
0791     
0792     in.coast            = optargs_struct(in.coast,default); clear default
0793 end
0794 
0795 if in.nodata
0796     % If I only want an empty map, get the essentials and leave here.
0797     in = nodata(in);
0798     return
0799 end
0800 
0801 if ~ismember(field,fieldnames(in))
0802     error(['gmtlab:' mfilename ':BadInput'],...
0803         'no field by the name of "%s" in struct',field)
0804 else
0805     in.fieldname  = field;
0806 end
0807 
0808 % is the data plotable?
0809 in = isdata(in,field);
0810 
0811 % Check to see if the data is gridded or not
0812 in = isgridded(in,field);
0813 
0814 % Also get rid of NaNs in the geodata (This only applies to ungridded data)
0815 in = rmNaNsGeo_and_standardize_geodata(in,field);
0816 
0817 % REGION
0818 in = assign_region(in,field);
0819 
0820 in = specialregion(in,field); %in case the region covers the dateline and is not continuous
0821 
0822 
0823 % DATARANGE
0824 if ~in.nodata
0825     default.datarange     = getdatarange(in,field); %
0826     if any(isnan(in.(field)(:)))
0827         default.extra_legend = struct('name','NaN','type','nan'); % include NaNs in the legend
0828     end
0829 end
0830 in = optargs_struct(in,default);
0831 in.datarange = double(in.datarange);
0832 
0833 % COLORS & DATA REPRESENTATION
0834 default.ctable      = 'rainbow';          % color palette
0835 [default.stepsize,default.tick_annotation_format]    = getstepsize(in,field);    % color level datastep interval
0836 in = optargs_struct(in,default); clear default
0837 
0838 % LEGEND
0839 in = setupLegend(in);
0840 
0841 end
0842 
0843 
0844 %% SUBFUNCTIONS FOR SETUP
0845 %      ||||||
0846 %      VVVVVV
0847 
0848 function check_input(in)
0849 %% CheckInput
0850 % Checks the input type of all options. If the field is in the list of
0851 % available options, it will be tested against a anomynous function (e.g.
0852 % in.region should pass @(x)(ischar(x)) ). The field names and their
0853 % corresponding test functions are listed in gmt_inputs.
0854 
0855 errID = ['gmtlab:' mfilename ':BadInput'];
0856 assert(isstruct(in),errID,'"in" must be a structure')
0857 
0858 [GSE,GSSE] = gmt_inputs;
0859 
0860 Fields = fieldnames(in)';
0861 
0862 for F = Fields
0863     % See if the in.(field) is a listed option
0864     test = GSE(ismember(GSE(:,2),F{1}),:);
0865     
0866     if ~isempty(test)
0867         % corresponding test function
0868         fun = test{1};
0869         strfun = func2str(fun);
0870         
0871         assert(fun(in.(test{2})),errID,...
0872             'Input type is incorrect. in.%s should pass test: %s',test{2},strfun);
0873         
0874         % If in.(field) is itself a structure, do it again (more or less)
0875         if isstruct(in.(test{2})) && ismember(test{2},fieldnames(GSSE))
0876             Fields2 = fieldnames(in.(test{2}))';
0877             for F2 = Fields2
0878                 test2 = GSSE.(test{2})(ismember(GSSE.(test{2})(:,2),F2{1}),:);
0879                 if ~isempty(test2)
0880                     fun = test2{1};
0881                     strfun = char(fun);
0882                     assert(fun(in.(test{2})(1).(test2{2})),errID,...
0883                         'Input type is incorrect. in.%s.%s should pass the test: @%s',...
0884                         test{2},test2{2},strfun);
0885                 else
0886                     warning(errID,'in.%s.%s is not a valid field in in.%s ',...
0887                         test{2},F2{1},test{2})
0888                 end
0889             end
0890         end
0891     end
0892 end
0893 
0894 end
0895 
0896 function in = assign_region(in,field)
0897 
0898 errId = ['gmtlab:' mfilename ':badInput']; % common error ID
0899 
0900 if ~isfield(in,'region')
0901     if in.gridded
0902         % check if the data is probably global
0903         
0904         dn = diff(in.lon);
0905         dt = diff(in.lat);
0906         if isempty(dt), dt = mean(dn);end %incase there's only one latitude
0907         
0908         % make the region str, keeping in min the 'resolution' of the grid
0909         annot_format = {getAnnotFormat(mean(diff(in.lon))),...
0910             getAnnotFormat(mean(diff(in.lat)))};
0911         
0912         % check to see if lon-dlon is out side the boundary. If so, fix the
0913         % region to the edges. Same goes for lat...
0914         cond1 = abs(-180-in.lon(1)) <= dn(1);
0915         cond2 = 180-in.lon(end) <= dn(end);
0916         cond3 = abs(-90-in.lat(1)) <= dt(1);
0917         cond4 = 90-in.lat(end) <= dt(end);
0918         
0919         af = annot_format{1};
0920         if cond1 && cond2 && cond3 && cond4
0921             in.region = '-180/180/-90/90';
0922         elseif cond1 && cond2
0923             fstr = sprintf('-180/180/%s/%s',af,af);
0924             in.region = sprintf(fstr,in.lat(1)-dt(1)/2,in.lat(end)+dt(end)/2);
0925         elseif cond3 && cond4
0926             fstr = sprintf('%s/%s/-90/90',af,af);
0927             in.region = sprintf(fstr,in.lon(1)-dn(1)/2,in.lon(end)+dn(end)/2);
0928         else
0929             fstr = sprintf('%s/%s/%s/%s',af,af,af,af);
0930             in.region = sprintf(fstr,...
0931                 in.lon(1)-dn(1)/2,in.lon(end)+dn(end)/2,...
0932                 in.lat(1)-dt(1)/2,in.lat(end)+dt(end)/2);
0933         end
0934     else
0935         in.region = sprintf('%g/%g/%g/%g',...
0936             min(in.lon(:)),max(in.lon(:)),...
0937             min(in.lat(:)),max(in.lat(:)));
0938     end
0939 else
0940     in.userDefinedRegion = true;
0941     % remove frivolous data for memory and speed performance in that case
0942     x = sscanf(in.region,'%f/%f/%f/%f');
0943     lt = in.lat >= x(3) & in.lat <=x(4); %logical vector
0944     ln = in.lon >= x(1) & in.lon <=x(2); %logical vector
0945     if in.gridded
0946         in.(field) = in.(field)(lt,ln);
0947         in.lat = in.lat(lt);
0948         in.lon = in.lon(ln);
0949     else
0950         in.(field) = in.(field)(lt&ln);
0951         in.lat = in.lat(lt&ln);
0952         in.lon = in.lon(lt&ln);
0953     end
0954     assert(~isempty(in.lat) && ~isempty(in.lon),...
0955         errId,'lat or lon are empty')
0956 end
0957 
0958 end
0959 
0960 function datarange = getdatarange(in,field)
0961 %% getdatarange
0962 
0963 tmp = in.(field)(:);
0964 d = double([min(tmp(~isinf(tmp))) max(tmp(~isinf(tmp)))]);
0965 
0966 % Do some tricks to get the most useful datarange. (rounded, but preserve precision)
0967 x = log10(d(2)-d(1));
0968 
0969 datarange = [10^(round(x)-1) * round(d(1) * (1/10^(round(x)-1))),...
0970     10^(round(x)-1) * round(d(2) * (1/10^(round(x)-1)))];
0971 
0972 
0973 end
0974 
0975 function [stepsize,annot_format] = getstepsize(in,field)
0976 %% getstepsize
0977 
0978 if in.nodata
0979     stepsize = 0;
0980     annot_format='';
0981     return
0982 end
0983 
0984 % default number of levels
0985 if length(unique(in.(field)))<in.nlevels && ~in.force_nlevels
0986     logtext(atmlab('OUT'),'unique values < %d\n',in.nlevels)
0987     in.nlevels = length(unique(in.(field)));
0988     logtext(atmlab('OUT'),'setting in.nlevels =  length(unique(in.(field)) (%d)\n',...
0989         length(unique(in.(field))))
0990 end
0991 
0992 if isfield(in,'stepsize')
0993     % warning('gmtlab:input','in.stepsize overrides in.nlevels')
0994     stepsize = in.stepsize;
0995 elseif ~isfield(in,'stepsize')
0996     stepsize = (in.datarange(2)-in.datarange(1))/in.nlevels;
0997 end
0998 annot_format = getAnnotFormat(stepsize);
0999 
1000 end
1001 
1002 function in = nodata(in)
1003 %% NODATA
1004 % if you want to only plot coastlines
1005 
1006 in.sidebar = false;
1007 in.legend  = false;
1008 in.gridded = false;
1009 in.nlevels = 1;
1010 if isfield(in,'region')
1011 elseif ~isfield(in,'region') && all(isfield(in,{'lat','lon'}))
1012     in.region = sprintf('%g/%g/%g/%g/%g',...
1013         min(in.lon(:)),max(in.lon(:)),...
1014         min(in.lat(:)),max(in.lat(:)));
1015 else
1016     in.region='-180/180/-90/90';
1017 end
1018 
1019 end
1020 
1021 function in = isdata(in,field)
1022 %% is there any useable data?
1023 
1024 Id  = ['gmtlab:' mfilename ':badInput'];
1025 Eps = 1e-10;
1026 
1027 % silently squeeze the data
1028 in.(field)=squeeze(in.(field));
1029 assert(isfield(in,field), Id,'The field: "%s" is not in the structure',field)
1030 assert(any(~isnan(in.(field)(:))),'gmtlab:gmt_plot:noData',...
1031     '%s%s','Data does not contain any valid',...
1032     ' values for contour levels to be based on...')
1033 assert(~(~ismatrix(in.(field))),Id,'in.%s must not be more than 2 dimensional',field)
1034 assert((max(in.(field)(:))-min(in.(field)(:))>Eps),Id,...
1035     'min(data) must not be equal to max(data)')
1036 
1037 % check for lat and lons
1038 if ~isfield(in,'lat')
1039     l = {'Latitude','latitude'};
1040     assert(any(isfield(in,l)),Id,'No latitudes present')
1041     in.lat = in.(l{isfield(in,l)});
1042 elseif any(isfield(in,{'Latitude','latitude'}))
1043     disp('Several latitude vectors present. Using in.lat')
1044 end
1045 if ~isfield(in,'lon')
1046     l = {'Longitude','longitude','long'};
1047     assert(any(isfield(in,l)),Id,'No longitudes present')
1048     in.lon = in.(l{isfield(in,l)});
1049 elseif any(isfield(in,{'Longitude','longitude','long'}))
1050     disp('Several longitude vectors present. Using in.lon')
1051 end
1052 
1053 end
1054 
1055 function in = isgridded(in,field)
1056 %% ISGRIDDED: Test if the data is gridded
1057 %  If it is not gridded, flatten the data
1058 
1059 if isempty(in.(field))
1060     error(['gmtlab:' mfilename ':BadInput'],....
1061         'The data variable: in.%s is empty',field)
1062 end
1063 
1064 if ndims(in.(field))==3
1065     in.(field) = squeeze(in.(field));
1066 end
1067 
1068 [a,b]=size(in.(field));
1069 pos1 = a==length(in.lat)&b==length(in.lon); %(lat,lon)
1070 pos2 = b==length(in.lat)&a==length(in.lon); %(lon,lat)
1071 
1072 % if (pos1 && pos2) && (pos1 || pos2), then we dont know if it gridded, but
1073 % assume it's not.
1074 if ~isfield(in,'gridded')
1075     ig = ~ (isequal(size(in.(field)(:)),size(in.lat(:)),size(in.lon(:))));
1076     if ~ig
1077         in.(field) = in.(field)(:);
1078         in.lat     = in.lat(:);
1079         in.lon     = in.lon(:);
1080         in.gridded = false;
1081     else
1082         if pos2 && (pos2 ~= pos1)
1083             % want it in (lat,lon)
1084             in.(field)=in.(field)';
1085         end
1086         in.gridded = true;
1087     end
1088 end
1089 
1090 end
1091 
1092 function in = rmNaNsGeo_and_standardize_geodata(in,field)
1093 %% rmNaNsGeo
1094 % Also get rid of NaNs in the geodata
1095 % This only applies to ungridded data
1096 
1097 errId = ['gmtlab:' mfilename ':badInput']; % common error ID
1098 
1099 if ~in.gridded
1100 
1101 index = in.lat >= -90 & in.lat <= 90 & in.lon >= -180 & in.lon <= 360;
1102 if any(~index)
1103     logtext(1,'Data with dodgy geodata will be ignored (%.2f%%)\n',100*sum(~index)/numel(index))
1104     in.lat = in.lat(index);
1105     in.lon = in.lon(index);
1106     in.(field) = in.(field)(index);
1107 end
1108 
1109 else
1110     % make sure that the lons,lats and data are ordered in ascending and data(lat,lon)
1111     assert(length(in.lat)*length(in.lon)==numel(in.(field)),...
1112         errId,'numel(data) must length(lat)*length(lon)')
1113     [~,in.lat,in.lon,in.(field)] = standardize_geodata(in.lat,in.lon,in.(field));
1114     
1115 end
1116 
1117 end
1118 
1119 function in = setupLegend(in)
1120 % SETUP LEGEND
1121 
1122 errId = ['gmtlab:' mfilename ':badInput']; % common error ID
1123 if isfield(in,'legend') && (~isstruct(in.legend) && ~in.legend)
1124     % If in.legend = false, do nothing
1125     return
1126 end
1127 if ~isfield(in,'legend') || ~isstruct(in.legend)
1128     in.legend=struct([]);
1129 end
1130 
1131 % apply defaults to legend
1132 if ~isfield(in.legend,'position')
1133     % ORIENTATION
1134     
1135     x = sscanf(in.region,'%f/%f/%f/%f');
1136     f = 2*( x(4)-x(3))/ ( x(2)-x(1) ); %something between 0->1 equivalent to 180/360->120/360 lats/lons
1137     myHcondition = f < 0.5; tmp = ['v','h']; %vertical,horisontal
1138 
1139     if in.savelegend
1140         default.orientation = 'h'; % because usually you want this.
1141     else
1142         default.orientation = tmp(myHcondition+1);
1143     end
1144     defThick=.2; %thickness of legend bar
1145     
1146     % I use map_width to find the defaults.
1147     [mw,mwu] = separate_integer_and_unit(in.map_width);
1148     in.legend           = optargs_struct(in.legend,default); %need orientation now
1149     switch in.legend.orientation
1150         case 'v'
1151             vec = [10.11+(.5*defThick+0.44*ismember('E',in.basemap_axis)) ... % could use annot_font_size_primary for better precision
1152                 2.44*f ...
1153                 5.22*f ...
1154                 defThick]/10;
1155             
1156         case 'h'
1157             
1158             vec = [5 ...
1159                 -0.1-(0.5*defThick+0.4*ismember('S',in.basemap_axis))...
1160                 10.55 ...
1161                 defThick]/10;
1162             
1163         otherwise
1164             error(errId,'orientation should be "v" or "h", not "%s"',in.legend.orientation)
1165     end
1166     default.xpos   = sprintf('%.2f%s',vec(1)*mw,mwu);
1167     default.ypos   = sprintf('%.2f%s',vec(2)*mw,mwu);
1168     default.length = sprintf('%.2f%s',vec(3)*mw,mwu);
1169     default.width  = sprintf('%.2f%s',vec(4)*mw,mwu);
1170 else
1171     default = regexp(in.legend.position,'(?<xpos>.+)/(?<ypos>.+)/(?<length>.+)/(?<width>.+)(?<orientation>\w{1})','names');
1172 end
1173 default.tick_annotion_format = in.tick_annotation_format;
1174 default.sidebar     = getsidebar(in); % coloroured triangles using in.datarange
1175 in.legend           = optargs_struct(in.legend,default);
1176 
1177 end
1178 
1179 function sidebar = getsidebar(in)
1180 %% color level datastep interval
1181 % sidebar can have the values 0,1,2,3 (none, bellow only, above only, both).
1182 
1183 sidebar =  ( min(in.(in.fieldname)(:))<in.datarange(1) ) + ...
1184     2* ( max(in.(in.fieldname)(:))>in.datarange(2) );
1185 
1186 end
1187 
1188 function in = specialregion(in,field)
1189 
1190 if in.gridded
1191     % DO some special treatment of data crossing the dateline that is not continuous
1192     % after changing to -180:180 regime OR if in.region is in 0:360 mode
1193     
1194     if any(diff(in.lon)==0)
1195         % in case a longitude appears twice. e.g., if the grid was originally
1196         % lon = 0:360
1197         cond = diff(in.lon)~=0;
1198         in.lon = in.lon(cond);
1199         in.(field) = in.(field)(:,cond);
1200     end
1201     if max(diff(in.lon))>5*min(diff(in.lon)) || ...
1202             structfun(@str2double,regexp(in.region,'.+/(?<lnmax>.+)/.+/.+','names')) > 180 % this is a 360 test
1203         
1204         in.lon = in.lon+(in.lon < 0)*360;
1205         [in.lon,lnindex] = sort(in.lon);
1206         in.(field) = in.(field)(:,lnindex);
1207         % if diff equal 0 somewhere then at best the data is repeated e.g.
1208         % at 0˚ and 360˚
1209         if any(diff(in.lon)==0)
1210             if isequal(in.(field)(:,find(diff(in.lon)==0)),in.(field)(:,find(diff(in.lon)==0)+1)) %#ok<FNDSB>
1211                 % then remove duplicate line
1212                 in.lon      = in.lon(diff(in.lon)~=0);
1213                 in.(field)  = in.(field)(:,diff(in.lon)~=0);
1214             else
1215                 error(['atmlab:' mfilename],'Same longitudes are repreated but the data are not the same there')
1216             end
1217         end
1218         % Do the region part again
1219         if ~isfield(in,'userDefinedRegion') || ~in.userDefinedRegion
1220             in = rmfield(in,'region');
1221             in = assign_region(in,field);
1222         end
1223     end
1224     
1225     
1226     assert(max(diff(in.lon))<5*min(diff(in.lon)),['atmlab:' mfilename, ':Error'],...
1227         'The longitudes are not continuous. FIXME: put workaround in place')
1228     
1229     if length(in.lat) == size(in.(field),1)+1 || length(in.lon) == size(in.(field),2)+1
1230         logtext(1,'Data does not appear to be centered. Internally ')
1231         in = centerGeoData(in,field);
1232     end
1233 end
1234 
1235 end
1236 
1237 % ----------------
1238 % Other subfunctions
1239 %
1240 
1241 function filename = sort_figures(in,command)
1242 %% SORT FIGURES
1243 
1244 
1245 %'eps','pdf','BMP','jpg','PNG','PPM','TIFF', ot 'tif'
1246 switch lower(in.figuretype)
1247     case 'pdf'
1248         T = '-Tf';
1249     case 'bmp'
1250         T = '-Tb -Qg -Qt';
1251     case 'eps'
1252         T = '-Te';
1253     case 'jpg'
1254         T = '-Tj -Qg -Qt';
1255     case 'png'
1256         T = '-Tg -Qg -Qt'; %-Q is for no antialiaing 'g'raphics and 't'ext
1257     case 'tif'
1258         T = '-Tt -Qg -Qt';
1259     case 'ppm' % is not recommended
1260         T = '-Tm -Qg -Qt';
1261     otherwise
1262         error(['gmtlab:' mfilename ':FigureType'],...
1263             '%s: not supported',in.figuretype)
1264 end
1265 command{end+1} = sprintf('ps2raster %s.ps -A -P %s',in.filename,T);
1266 command{end+1} = sprintf('mv %s.%s %s',in.filename,in.figuretype,in.outdir);
1267 
1268 if in.savelegend
1269     % MAKE a separate file for the legend
1270     findPsScale = ~cellfun('isempty',regexp(command,'psscale'));
1271     if ~any(findPsScale)
1272         v = atmlab('VERBOSITY');
1273         atmlab('VERBOSITY',1);
1274         logtext(atmlab('ERR'),'psscale, which is used to make the legend was never called. Maybe legend=0 or there was no input data?\n')
1275         atmlab('VERBOSITY',v);
1276         filename = '';
1277         
1278         return
1279     end
1280     in.filename_legend = makelegendpdf(in.filename, command(findPsScale));
1281     if in.savelegend==2 % store legend ONLY in external file
1282         command = command(~findPsScale);
1283     end
1284     command{end+1} = sprintf('mv %s.%s %s',in.filename_legend,in.figuretype,in.outdir);
1285 end
1286 
1287 % Assemble open command
1288 openwith = NaN;
1289 if strcmp(in.figuretype,'pdf')
1290     openwith = gmtlab('PDFVIEWER');
1291 elseif strcmp(in.figuretype,'eps')
1292     openwith = gmtlab('PSVIEWER');
1293 end
1294 if isnan(openwith)
1295     openwith = gmtlab('OPEN_COMMAND');
1296 end
1297 if in.display && ~any(isnan(openwith))
1298     command{end+1} = sprintf('%s %s/%s.%s >/dev/null &',...
1299         openwith,in.outdir,in.filename,in.figuretype);
1300 end
1301 
1302 out = exec_system_cmd(command,gmtlab('verbosity')); % execute all gathered commands
1303 
1304 filename = sprintf('%s/%s.%s',in.outdir,in.filename,in.figuretype);
1305 
1306 % If no viewer is defined, check for xpdf, then evince, then okular
1307 if in.display && any(isnan(openwith)) && strcmp(in.figuretype,'pdf')
1308     disp('No pdfviewer defined.')
1309     disp('Set gmtlab(''PDFVIEWER'',''<e.g. xpdf>'') in your startup file')
1310     if ~system('which xpdf')
1311         openwith = 'xpdf';
1312     elseif ~system('which evince')
1313         openwith = 'evince'; % for gnome users
1314     elseif ~system('which okular')
1315         openwith  = 'okular'; % for kde users
1316     end
1317     if ~any(isnan(openwith))
1318         logtext(1,'Opening file with %s for now\n',openwith)
1319         system(sprintf('%s %s &',openwith,filename));
1320     end
1321 end
1322 
1323 hunt_down_errors(command,out) % look for system call errors in the gmt calls
1324 
1325 logtext(atmlab('OUT'), 'GMT plot stored at:  %s\n',filename)
1326 
1327 end
1328 
1329 function file = makelegendpdf(basename, command)
1330 %% Make a separate pdf for the legend
1331 % Only allowed to have 1 or 2 psscale commands in the commad list. the first one
1332 % is the regular legend. The second is for the nan legend (if it exists)
1333 
1334 file = [basename '_legend'];
1335 
1336 %make sure it's not here
1337 exec_system_cmd(sprintf('rm -f %s.ps',file),gmtlab('verbosity'));
1338 
1339 % Make the page large enough to fit most legends
1340 cmd = {'gmtset PAPER_MEDIA a0'};
1341 command = [cmd, command{1}];
1342 
1343 %Remove trailing .ps entry
1344 crop=regexp(command,'>>');
1345 
1346 % Additional adjustments
1347 for i = 2:length(command)
1348     command{i} = sprintf('%s -P >> %s.ps', command{i}(1:crop{i}-1), file );
1349     if i == 2
1350         command{i} = regexprep(command{i},'-O','');
1351     end
1352     if i == length(command)
1353         command{i} = regexprep(command{i},'-K','');
1354     end
1355 end
1356 
1357 % This forces it to be a pdf
1358 command{end+1} = sprintf('ps2raster %s.ps -A -P -Tf',file);
1359 exec_system_cmd(command,gmtlab('verbosity'));
1360 
1361 end
1362 
1363 function hunt_down_errors(command,errors)
1364 %% Hunt down any errors encounted using GMT
1365 
1366 % messages containing any of these are exempted
1367 error_exeptions = {'warning','not set'};
1368 definite_errors = {'illegal','error'};
1369 
1370 % this gives cell{1:nerrors}{1:nerr_exp}
1371 found_err_exp = cellfun(@(x)(regexp(x,error_exeptions,'ignorecase','once')),errors,'uniformoutput',0);
1372 found_def_err = cellfun(@(x)(regexp(x,definite_errors,'ignorecase','once')),errors,'uniformoutput',0);
1373 
1374 windex = cellfun(@(x)(any(cell2mat(x))),found_err_exp);
1375 eindex = cellfun(@(x)(any(cell2mat(x))),found_def_err);
1376 
1377 Warnings             = errors(windex);
1378 associated_w_warning = command(windex);
1379 Errors               = errors(eindex);
1380 associated_w_errors  = command(eindex);
1381 
1382 % display GMT calls containing warning
1383 if ~isempty(Warnings)
1384     V = atmlab('VERBOSITY'); atmlab('VERBOSITY',1);
1385     logtext(atmlab('OUT'),'GMT completed with the following warning messages:\n')
1386     tmp = cellfun(@(x,y)(sprintf('%s\n%s\n',x,y(1:end-1))),associated_w_warning,Warnings,'UniformOutput',0);
1387     logtext(atmlab('OUT'),'%s\n',[tmp{:}])
1388     atmlab('VERBOSITY',V);
1389 end
1390 
1391 % error on GMT errors
1392 if ~isempty(Errors)
1393     tmp = cellfun(@(x,y)(sprintf('%s\n%s\n',x,y(1:end-1))),associated_w_errors,Errors,'UniformOutput',0);
1394     error(['gmtlab:' mfilename ':GMT'],...
1395         'GMT encountered the following errors:\n%s',[tmp{:}])
1396 end
1397 
1398 end
1399 
1400 function gmtcleanup(tmpdir,curdir,keepfiles,V)
1401 %% cleanUp
1402 
1403 if keepfiles
1404     logtext(1,'in.keep_files = true;\nTemporary files are stored at %s.\n',pwd)
1405     logtext(2,'Remember to delete the directory when you are done\n')
1406 else
1407     % cd back to the original directory
1408     cd(curdir);
1409     rmdir(tmpdir,'s')
1410     logtext(1,'%s is now removed\n',tmpdir)
1411     atmlab('VERBOSITY',V);
1412 end
1413 
1414 end

Generated on Mon 15-Sep-2014 13:31:28 by m2html © 2005