manpagez: man pages & more
man grdfilter(1)
Home | html | info | man
grdfilter(1)                          GMT                         grdfilter(1)




NAME

       grdfilter - Filter a grid in the space (or time) domain


SYNOPSIS

       grdfilter ingrid  -Ddistance_flag
        -Fxwidth[/width2][modifiers]
        -Goutgrid  [   -Iincrement  ]  [   -Ni|p|r  ]  [  -Rregion ] [  -T ] [
       -V[level] ] [ -fflags ]

       Note: No space is allowed between the option flag  and  the  associated
       arguments.


DESCRIPTION

       grdfilter  will  filter a grid file in the time domain using one of the
       selected convolution or non-convolution isotropic or  rectangular  fil-
       ters  and  compute  distances  using Cartesian or Spherical geometries.
       The output grid file can optionally be generated as a sub-region of the
       input  (via -R) and/or with new increment (via -I) or registration (via
       -T). In this way, one may have aextra spacea in the input data so  that
       the  edges will not be used and the output can be within one half-width
       of the input edges. If the filter is low-pass, then the output  may  be
       less frequently sampled than the input.


REQUIRED ARGUMENTS

       ingrid The  grid  file of points to be filtered. (See GRID FILE FORMATS
              below).

       -Ddistance_flag
              Distance flag tells how grid (x,y) relates to  filter  width  as
              follows:

              flag  =  p:  grid  (px,py)  with  width an odd number of pixels;
              Cartesian distances.

              flag = 0: grid (x,y) same units as width, Cartesian distances.

              flag = 1: grid (x,y) in degrees, width in kilometers,  Cartesian
              distances.

              flag  =  2:  grid  (x,y)  in  degrees, width in km, dx scaled by
              cos(middle y), Cartesian distances.

              The above options are fastest because they allow  weight  matrix
              to  be  computed  only  once.  The next three options are slower
              because they recompute weights for each latitude.

              flag = 3: grid (x,y) in degrees,  width  in  km,  dx  scaled  by
              cosine(y), Cartesian distance calculation.

              flag = 4: grid (x,y) in degrees, width in km, Spherical distance
              calculation.

              flag = 5: grid (x,y) in Mercator -Jm1 img units,  width  in  km,
              Spherical distance calculation.

       -Fxwidth[/width2][modifiers]
              Sets  the filter type. Choose among convolution and non-convolu-
              tion filters. Use any filter code x (listed below)  followed  by
              the  full diameter width. This gives an isotropic filter; append
              /width2 for a rectangular filter  (requires  -Dp  or  -D0).   By
              default  we  perform  low-pass  filtering;  append  +h to select
              high-pass filtering.  Some filters allow for optional  arguments
              and modifiers.

              Convolution filters (and their codes) are:

              (b) Boxcar: All weights are equal.

              (c) Cosine Arch: Weights follow a cosine arch curve.

              (g)  Gaussian: Weights are given by the Gaussian function, where
              width is 6 times the conventional Gaussian sigma.

              (f) Custom: Weights are given by the precomputed values  in  the
              filter  weight grid file weight, which must have odd dimensions;
              also requires -D0 and output spacing must match input spacing or
              be integer multiples.

              (o) Operator: Weights are given by the precomputed values in the
              filter weight grid file weight, which must have odd  dimensions;
              also requires -D0 and output spacing must match input spacing or
              be integer multiples. Weights are assumed to sum to zero  so  no
              accumulation of weight sums and normalization will be done.

              Non-convolution filters (and their codes) are:

              (m)  Median:  Returns  median  value. To select another quantile
              append +qquantile in  the  0-1  range  [Default  is  0.5,  i.e.,
              median].

              (p)  Maximum  likelihood  probability (a mode estimator): Return
              modal value. If more than one mode  is  found  we  return  their
              average  value. Append +l or +u if you rather want to return the
              lowermost or uppermost of the modal values.

              (h) Histogram mode (another mode estimator):  Return  the  modal
              value  as the center of the dominant peak in a histogram. Append
              /binwidth to specify the binning interval.  Use modifier  +c  to
              center  the bins on multiples of binwidth [Default has bin edges
              that are multiples of binwidth].  If more than one mode is found
              we  return  their  average  value. Append +l or +u if you rather
              want to return the lowermost or uppermost of the modal values.

              (l) Lower: Return the minimum of all values.

              (L) Lower: Return minimum of all positive values only.

              (u) Upper: Return maximum of all values.

              (U) Upper: Return maximum or all negative values only.

              In the case of L|U it is possible that no data passes  the  ini-
              tial sign test; in that case the filter will return NaN.

       -Goutgrid
              outgrid  is  the  output grid file of the filter. (See GRID FILE
              FORMATS below).


OPTIONAL ARGUMENTS

       -Ixinc[unit][+e|n][/yinc[unit][+e|n]]
              x_inc [and optionally y_inc] is the  grid  spacing.  Optionally,
              append  a  suffix  modifier. Geographical (degrees) coordinates:
              Append m to indicate arc minutes or s to indicate  arc  seconds.
              If  one of the units e, f, k, M, n or u is appended instead, the
              increment is assumed to be given in meter, foot, km, Mile,  nau-
              tical  mile  or  US  survey foot, respectively, and will be con-
              verted to the equivalent degrees longitude at the  middle  lati-
              tude  of  the region (the conversion depends on PROJ_ELLIPSOID).
              If y_inc is given but set to 0 it will be reset equal to  x_inc;
              otherwise  it will be converted to degrees latitude. All coordi-
              nates: If +e is appended then the corresponding max x (east)  or
              y  (north)  may  be  slightly  adjusted to fit exactly the given
              increment [by default the increment may be adjusted slightly  to
              fit  the  given domain]. Finally, instead of giving an increment
              you may specify the number of nodes desired by appending  +n  to
              the  supplied  integer  argument; the increment is then recalcu-
              lated from the number of nodes and  the  domain.  The  resulting
              increment  value  depends  on  whether you have selected a grid-
              line-registered or pixel-registered grid;  see  App-file-formats
              for  details.  Note:  if -Rgrdfile is used then the grid spacing
              has already been initialized; use -I to override the values.

       -Ni|p|r
              Determine how NaN-values in the input grid affects the  filtered
              output:  Append  i to ignore all NaNs in the calculation of fil-
              tered value [Default], r is same as i except if the  input  node
              was NaN then the output node will be set to NaN (only applies if
              both grids are co-registered), and p which will force  the  fil-
              tered  value  to  be  NaN  if any grid-nodes with NaN-values are
              found inside the filter circle.

       -R     west, east, south, and north defines the Region  of  the  output
              points. [Default: Same as input.]

       -T     Toggle the node registration for the output grid so as to become
              the opposite of the input grid [Default gives the same registra-
              tion as the input grid].

       -V[level] (more a|)
              Select verbosity level [c].

       -f[i|o]colinfo (more a|)
              Specify data types of input and/or output columns.

       -^ or just -
              Print  a  short  message  about  the syntax of the command, then
              exits (NOTE: on Windows just use -).

       -+ or just +
              Print an extensive usage (help) message, including the  explana-
              tion  of  any  module-specific  option  (but  not the GMT common
              options), then exits.

       -? or no arguments
              Print a complete usage (help) message, including the explanation
              of all options, then exits.


GRID FILE FORMATS

       By  default  GMT  writes  out  grid  as  single  precision  floats in a
       COARDS-complaint netCDF file format. However, GMT is  able  to  produce
       grid  files  in  many  other  commonly  used grid file formats and also
       facilitates so called apackinga of grids, writing  out  floating  point
       data as 1- or 2-byte integers. (more a|)


GEOGRAPHICAL AND TIME COORDINATES

       When  the  output  grid type is netCDF, the coordinates will be labeled
       alongitudea, alatitudea, or atimea based on the attributes of the input
       data  or  grid  (if  any) or on the -f or -R options. For example, both
       -f0x -f1t and -R90w/90e/0t/3t will result  in  a  longitude/time  grid.
       When  the  x, y, or z coordinate is time, it will be stored in the grid
       as relative time since epoch as specified by TIME_UNIT  and  TIME_EPOCH
       in  the  gmt.conf  file  or  on the command line. In addition, the unit
       attribute of the time variable will indicate both this unit and  epoch.


EXAMPLES

       Suppose  that  north_pacific_etopo5.nc is a file of 5 minute bathymetry
       from 140E to 260E and 0N to 50N, and you want to find  the  medians  of
       values  within  a 300km radius (600km full width) of the output points,
       which you choose to be from 150E to 250E and 10N to 40N, and  you  want
       the  output  values every 0.5 degree. Using spherical distance calcula-
       tions, you need:

              gmt grdfilter north_pacific_etopo5.nc -Gfiltered_pacific.nc -Fm600 \
                            -D4 -R150/250/10/40 -I0.5 -V

       If we instead wanted a high-pass result then one can perform the corre-
       sponding low-pass filter using a coarse grid interval as grdfilter will
       resample the result to the same resolution as the input grid so we  can
       compute the residuals, e.g.,

              gmt grdfilter north_pacific_etopo5.nc -Gresidual_pacific.nc -Fm600+h \
                            -D4 -R150/250/10/40 -I0.5 -V

       Here,  the residual_pacific.nc grid will have the same 5 minute resolu-
       tion as the original.

       To filter the dataset in ripples.nc using a custom anisotropic Gaussian
       filter  exp  (-0.5*r^2)  whose  distances r from the center is given by
       (2x^2 + y^2 -2xy)/6, with major axis at an angle of 63 degrees with the
       horizontal, try

              gmt grdmath -R-10/10/-10/10 -I1 X 2 POW 2 MUL Y 2 POW ADD X Y MUL 2 MUL \
                          SUB 6 DIV NEG 2 DIV EXP DUP SUM DIV = gfilter.nc
              gmt grdfilter ripples.nc -Ffgfilter.nc -D0 -Gsmooth.nc -V


LIMITATIONS

       1. To  use  the  -D5  option the input Mercator grid must be created by
          img2mercgrd using the -C option so the origin of the y-values is the
          Equator (i.e., x = y = 0 correspond to lon = lat = 0).

       2. If the new x_inc, y_inc set with -I are NOT integer multiples of the
          increments in the input data, filtering will be considerably slower.
          [Default increments: Same as input.]


SEE ALSO

       gmt(1), grdfft(1), img2grd(1)


COPYRIGHT

       2017, P. Wessel, W. H. F. Smith, R. Scharroo, J. Luis, and F. Wobbe



5.4.2                            Jun 24, 2017                     grdfilter(1)

gmt5 5.4.2 - Generated Wed Jun 28 18:26:31 CDT 2017
© manpagez.com 2000-2021
Individual documents may contain additional copyright information.