1GRDFILTER(1) GMT GRDFILTER(1)
2
6 grdfilter - Filter a grid in the space (or time) domain
7
9 grdfilter ingrid -Ddistance_flag
10 -Fxwidth[/width2][modifiers]
11 -Goutgrid [ -Iincrement ] [ -Ni|p|r ] [ -Rregion ] [ -T ] [
12 -V[level] ] [ -fflags ]
13 Note: No space is allowed between the option flag and the associated
15 arguments.
16
18 grdfilter will filter a grid file in the time domain using one of the
19 selected convolution or non-convolution isotropic or rectangular fil‐
20 ters and compute distances using Cartesian or Spherical geometries.
21 The output grid file can optionally be generated as a sub-region of the
22 input (via -R) and/or with new increment (via -I) or registration (via
23 -T). In this way, one may have "extra space" in the input data so that
24 the edges will not be used and the output can be within one half-width
25 of the input edges. If the filter is low-pass, then the output may be
26 less frequently sampled than the input.
27
29 ingrid The grid file of points to be filtered. (See GRID FILE FORMATS
30 below).
31 -Ddistance_flag
33 Distance flag tells how grid (x,y) relates to filter width as
34 follows:
35 flag = p: grid (px,py) with width an odd number of pixels;
37 Cartesian distances.
38 flag = 0: grid (x,y) same units as width, Cartesian distances.
40 flag = 1: grid (x,y) in degrees, width in kilometers, Cartesian
42 distances.
43 flag = 2: grid (x,y) in degrees, width in km, dx scaled by
45 cos(middle y), Cartesian distances.
46 The above options are fastest because they allow weight matrix
48 to be computed only once. The next three options are slower
49 because they recompute weights for each latitude.
50 flag = 3: grid (x,y) in degrees, width in km, dx scaled by
52 cosine(y), Cartesian distance calculation.
53 flag = 4: grid (x,y) in degrees, width in km, Spherical distance
55 calculation.
56 flag = 5: grid (x,y) in Mercator -Jm1 img units, width in km,
58 Spherical distance calculation.
59 -Fxwidth[/width2][modifiers]
61 Sets the filter type. Choose among convolution and non-convolu‐
62 tion filters. Use any filter code x (listed below) followed by
63 the full diameter width. This gives an isotropic filter; append
64 /width2 for a rectangular filter (requires -Dp or -D0). By
65 default we perform low-pass filtering; append +h to select
66 high-pass filtering. Some filters allow for optional arguments
67 and modifiers.
68 Convolution filters (and their codes) are:
70 (b) Boxcar: All weights are equal.
72 (c) Cosine Arch: Weights follow a cosine arch curve.
74 (g) Gaussian: Weights are given by the Gaussian function, where
76 width is 6 times the conventional Gaussian sigma.
77 (f) Custom: Weights are given by the precomputed values in the
79 filter weight grid file weight, which must have odd dimensions;
80 also requires -D0 and output spacing must match input spacing or
81 be integer multiples.
82 (o) Operator: Weights are given by the precomputed values in the
84 filter weight grid file weight, which must have odd dimensions;
85 also requires -D0 and output spacing must match input spacing or
86 be integer multiples. Weights are assumed to sum to zero so no
87 accumulation of weight sums and normalization will be done.
88 Non-convolution filters (and their codes) are:
90 (m) Median: Returns median value. To select another quantile
92 append +qquantile in the 0-1 range [Default is 0.5, i.e.,
93 median].
94 (p) Maximum likelihood probability (a mode estimator): Return
96 modal value. If more than one mode is found we return their
97 average value. Append +l or +u if you rather want to return the
98 lowermost or uppermost of the modal values.
99 (h) Histogram mode (another mode estimator): Return the modal
101 value as the center of the dominant peak in a histogram. Append
102 /binwidth to specify the binning interval. Use modifier +c to
103 center the bins on multiples of binwidth [Default has bin edges
104 that are multiples of binwidth]. If more than one mode is found
105 we return their average value. Append +l or +u if you rather
106 want to return the lowermost or uppermost of the modal values.
107 (l) Lower: Return the minimum of all values.
109 (L) Lower: Return minimum of all positive values only.
111 (u) Upper: Return maximum of all values.
113 (U) Upper: Return maximum or all negative values only.
115 In the case of L|U it is possible that no data passes the ini‐
117 tial sign test; in that case the filter will return NaN.
118 -Goutgrid
120 outgrid is the output grid file of the filter. (See GRID FILE
121 FORMATS below).
122
124 -Ixinc[unit][+e|n][/yinc[unit][+e|n]]
125 x_inc [and optionally y_inc] is the grid spacing. Optionally,
126 append a suffix modifier. Geographical (degrees) coordinates:
127 Append m to indicate arc minutes or s to indicate arc seconds.
128 If one of the units e, f, k, M, n or u is appended instead, the
129 increment is assumed to be given in meter, foot, km, Mile, nau‐
130 tical mile or US survey foot, respectively, and will be con‐
131 verted to the equivalent degrees longitude at the middle lati‐
132 tude of the region (the conversion depends on PROJ_ELLIPSOID).
133 If y_inc is given but set to 0 it will be reset equal to x_inc;
134 otherwise it will be converted to degrees latitude. All coordi‐
135 nates: If +e is appended then the corresponding max x (east) or
136 y (north) may be slightly adjusted to fit exactly the given
137 increment [by default the increment may be adjusted slightly to
138 fit the given domain]. Finally, instead of giving an increment
139 you may specify the number of nodes desired by appending +n to
140 the supplied integer argument; the increment is then recalcu‐
141 lated from the number of nodes and the domain. The resulting
142 increment value depends on whether you have selected a grid‐
143 line-registered or pixel-registered grid; see App-file-formats
144 for details. Note: if -Rgrdfile is used then the grid spacing
145 has already been initialized; use -I to override the values.
146 -Ni|p|r
148 Determine how NaN-values in the input grid affects the filtered
149 output: Append i to ignore all NaNs in the calculation of fil‐
150 tered value [Default], r is same as i except if the input node
151 was NaN then the output node will be set to NaN (only applies if
152 both grids are co-registered), and p which will force the fil‐
153 tered value to be NaN if any grid-nodes with NaN-values are
154 found inside the filter circle.
155 -R west, east, south, and north defines the Region of the output
157 points. [Default: Same as input.]
158 -T Toggle the node registration for the output grid so as to become
160 the opposite of the input grid [Default gives the same registra‐
161 tion as the input grid].
162 -V[level] (more ...)
164 Select verbosity level [c].
165 -f[i|o]colinfo (more ...)
167 Specify data types of input and/or output columns.
168 -^ or just -
170 Print a short message about the syntax of the command, then
171 exits (NOTE: on Windows just use -).
172 -+ or just +
174 Print an extensive usage (help) message, including the explana‐
175 tion of any module-specific option (but not the GMT common
176 options), then exits.
177 -? or no arguments
179 Print a complete usage (help) message, including the explanation
180 of all options, then exits.
181
183 By default GMT writes out grid as single precision floats in a
184 COARDS-complaint netCDF file format. However, GMT is able to produce
185 grid files in many other commonly used grid file formats and also
186 facilitates so called "packing" of grids, writing out floating point
187 data as 1- or 2-byte integers. (more ...)
188
190 When the output grid type is netCDF, the coordinates will be labeled
191 "longitude", "latitude", or "time" based on the attributes of the input
192 data or grid (if any) or on the -f or -R options. For example, both
193 -f0x -f1t and -R90w/90e/0t/3t will result in a longitude/time grid.
194 When the x, y, or z coordinate is time, it will be stored in the grid
195 as relative time since epoch as specified by TIME_UNIT and TIME_EPOCH
196 in the gmt.conf file or on the command line. In addition, the unit
197 attribute of the time variable will indicate both this unit and epoch.
198
200 Suppose that north_pacific_etopo5.nc is a file of 5 minute bathymetry
201 from 140E to 260E and 0N to 50N, and you want to find the medians of
202 values within a 300km radius (600km full width) of the output points,
203 which you choose to be from 150E to 250E and 10N to 40N, and you want
204 the output values every 0.5 degree. Using spherical distance calcula‐
205 tions, you need:
206 gmt grdfilter north_pacific_etopo5.nc -Gfiltered_pacific.nc -Fm600 \
208 -D4 -R150/250/10/40 -I0.5 -V
209 If we instead wanted a high-pass result then one can perform the corre‐
211 sponding low-pass filter using a coarse grid interval as grdfilter will
212 resample the result to the same resolution as the input grid so we can
213 compute the residuals, e.g.,
214 gmt grdfilter north_pacific_etopo5.nc -Gresidual_pacific.nc -Fm600+h \
216 -D4 -R150/250/10/40 -I0.5 -V
217 Here, the residual_pacific.nc grid will have the same 5 minute resolu‐
219 tion as the original.
220 To filter the dataset in ripples.nc using a custom anisotropic Gaussian
222 filter exp (-0.5*r^2) whose distances r from the center is given by
223 (2x^2 + y^2 -2xy)/6, with major axis at an angle of 63 degrees with the
224 horizontal, try
225 gmt grdmath -R-10/10/-10/10 -I1 X 2 POW 2 MUL Y 2 POW ADD X Y MUL 2 MUL \
227 SUB 6 DIV NEG 2 DIV EXP DUP SUM DIV = gfilter.nc
228 gmt grdfilter ripples.nc -Ffgfilter.nc -D0 -Gsmooth.nc -V
229
231 1. To use the -D5 option the input Mercator grid must be created by
232 img2mercgrd using the -C option so the origin of the y-values is the
233 Equator (i.e., x = y = 0 correspond to lon = lat = 0).
234 2. If the new x_inc, y_inc set with -I are NOT integer multiples of the
236 increments in the input data, filtering will be considerably slower.
237 [Default increments: Same as input.]
238
240 gmt, grdfft img2grd
241
243 2019, P. Wessel, W. H. F. Smith, R. Scharroo, J. Luis, and F. Wobbe
2445.4.5 Feb 24, 2019 GRDFILTER(1)