dimfilter man page on DragonFly

Man page or keyword search:  
man Server   44335 pages
apropos Keyword Search (all sections)
Output format
DragonFly logo
[printable version]

DIMFILTER(1)		     Generic Mapping Tools		  DIMFILTER(1)

NAME
       dimfilter - Directional filtering of 2-D gridded files in the space (or
       time) domain

SYNOPSIS
       dimfilter  input_file.grd  -Ddistance_flag  -F<filtertype><width>[mode]
       -Goutput_file.grd	-N<filtertype><n_sectors>	-Qcols	     [
       -Ixinc[unit][=|+][/yinc[unit][=|+]] ] [ -Rwest/east/south/north[r] ]  [
       -T ] [ -V ]

DESCRIPTION
       dimfilter  will	filter	a  .grd	 file in the space (or time) domain by
       dividing the given filter circle into n_sectors, applying  one  of  the
       selected primary convolution or non-convolution filters to each sector,
       and choosing the final outcome according to the selected secondary fil‐
       ter.   It  computes  distances using Cartesian or Spherical geometries.
       The output .grd file can optionally be generated as a sub-Region of the
       input  and/or with a new -I ncrement.  In this way, one may have "extra
       space" 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.  -Q  is  for the error analysis mode and only requires the total
       number of columns in  the  input	 file,	which  contains	 the  filtered
       depths.	 Finally,  one	should	know that dimfilter will not produce a
       smooth output as other spatial filters do because it returns a  minimum
       median  out  of	N medians of N sectors.	 The output can be edgy unless
       the input data is noise-free.  Thus,  an	 additional  filtering	(e.g.,
       Gaussian) to the DiM-filtered data is generally recommended.

       input_file.grd
	      The file of points to be filtered.

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

	      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 dis‐
	      tance calculation.

       -F     Sets the primary filter type.  Choose among convolution and non-
	      convolution  filters.   Append  the  filter code followed by the
	      full diameter width. Available convolution filters 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.
	      Non-convolution filters are:
	      (m) Median: Returns median value.
	      (p) Maximum likelihood probability (a  mode  estimator):	Return
	      modal  value.   If  more	than one mode is found we return their
	      average value.  Append - or + to the filter width if you	rather
	      want to return the smallest or largest of the modal values.

       -N     Sets  the	 secondary  filter type and the number of bow-tie sec‐
	      tors. n_sectors must be integer and larger than 0.  When	n_sec‐
	      tors is set to 1, the secondary filter is not effective.	Avail‐
	      able secondary filters are:
	      (l) Lower: Return the minimum of all filtered values.
	      (u) Upper: Return the maximum of all filtered values.
	      (a) Average: Return the mean of all filtered values.
	      (m) Median: Return the median of all filtered values.
	      (p) Mode: Return the mode of all filtered values.

       -G     output_file.grd is the output of the filter.

OPTIONS
       -I     x_inc [and optionally y_inc] is the output Increment.  Append  m
	      to  indicate  minutes,  or  c  to indicate seconds.  If  the new
	      x_inc, y_inc are NOT integer multiples of the old ones  (in  the
	      input  data),  filtering will be considerably slower.  [Default:
	      Same as input.]

       -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].

       -Q     cols is the total number of columns in the input file.  For this
	      mode, it expects to read depths consisted	 of  several  columns.
	      Each  column  represents	a  filtered  grid with a filter width,
	      which can be obtained by	'grd2xyz  -Z'.	The  outcome  will  be
	      median,  MAD,  and mean. So, the column with the medians is used
	      to generate the regional component and the column with the  MADs
	      to conduct the error analysis.

       -V     Selects verbose mode, which will send progress reports to stderr
	      [Default runs "silently"].

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  facili‐
       tates  so called "packing" of grids, writing out floating point data as
       2- or 4-byte integers. To specify the precision, scale and offset,  the
       user should add the suffix =id[/scale/offset[/nan]], where id is a two-
       letter identifier of the grid type and precision, and scale and	offset
       are  optional scale factor and offset to be applied to all grid values,
       and nan is the value used  to  indicate	missing	 data.	 When  reading
       grids,  the  format  is generally automatically recognized. If not, the
       same suffix can be added to input grid file names.  See	grdreformat(1)
       and  Section  4.17 of the GMT Technical Reference and Cookbook for more
       information.

       When reading a netCDF file that contains multiple grids, GMT will read,
       by default, the first 2-dimensional grid that can find in that file. To
       coax GMT into reading another multi-dimensional variable	 in  the  grid
       file,  append  ?varname	to the file name, where varname is the name of
       the variable. Note that you may need to escape the special meaning of ?
       in  your	 shell	program	 by  putting a backslash in front of it, or by
       placing the filename and suffix between quotes or double	 quotes.   The
       ?varname suffix can also be used for output grids to specify a variable
       name different from the default: "z".  See grdreformat(1)  and  Section
       4.18  of the GMT Technical Reference and Cookbook for more information,
       particularly on how to read splices of 3-, 4-, or 5-dimensional grids.

GEOGRAPHICAL AND TIME COORDINATES
       When the output grid type is netCDF, the coordinates  will  be  labeled
       "longitude", "latitude", or "time" 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	-R 90w/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 .gmtdefaults 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_dbdb5.grd 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.  To prevent the medians from being
       biased by the sloping plane, you want to divide the filter circle  into
       6 sectors and to choose the lowest value among 6 medians. Using spheri‐
       cal distance calculations, you need:

       dimfilter north_pacific_dbdb5.grd -G filtered_pacific.grd -Fm600	 -D  4
       -N l6 -R150/250/10/40 -I 0.5 -V

       Suppose that cape_verde.grd is a file of 0.5 minute bathymetry from 32W
       to 15W and 8N to 25N, and you want to  remove  small-length-scale  fea‐
       tures  in  order	 to  define a swell in an area extending from 27.5W to
       20.5W and 12.5N to 19.5N, and you want the output value every 2 minute.
       Using cartesian distance calculations, you need:

       dimfilter    cape_verde.grd    -G    t.grd    -Fm220    -Nl8    -D    2
       -R-27.5/-20.5/12.5/19.5 -I 2m -V
       grdfilter t.grd -G cape_swell.grd -Fg50 -D 2 -V

       Suppose that you found a range of filter widths for a given  area,  and
       you  filtered  the  given  bathymetric  data  using the range of filter
       widths (e.g., f100.grd f110.grd f120.grd f130.grd),  and	 you  want  to
       define  a regional trend using the range of filter widths, and you want
       to obtain median absolute deviation (MAD) estimates at each data point,
       you need:

       grd2xyz f100.grd -Z > f100.d
       grd2xyz f110.grd -Z > f110.d
       grd2xyz f120.grd -Z > f120.d
       grd2xyz f130.grd -Z > f130.d
       paste f100.d f110.d f120.d f130.d > depths.d
       dimfilter depths.d -Q4 > output.z

LIMITATIONS
       When  working  with  geographic (lat, lon) grids, all three convolution
       filters (boxcar, cosine arch, and gaussian) will properly normalize the
       filter  weights	for  the  variation in gridbox size with latitude, and
       correctly determine which nodes are needed for the convolution when the
       filter  "circle" crosses a periodic (0-360) boundary or contains a geo‐
       graphic pole.  However, the spatial filters, such as  median  and  mode
       filters,	 do  not use weights and thus should only be used on Cartesian
       grids (or at very low latitudes) only.  If you want to apply such  spa‐
       tial  filters  you should project your data to an equal-area projection
       and run dimfilter on the resulting Cartesian grid.

SCRIPT TEMPLATE
       The dim.template.sh is a skeleton shell script that can be used to  set
       up a complete DiM analysis, including the MAD analysis.

REFERENCE
       Kim,  S.-S.,  and  Wessel,  P. (2008), Directional Median Filtering for
       Regional-Residual Separation of Bathymetry, Geochem. Geophys. Geosyst.,
       9(Q03005), doi:10.1029/2007GC001850.

SEE ALSO
       GMT(1), grdfilter(1)

GMT 4.5.14			  1 Nov 2015			  DIMFILTER(1)
[top]

List of man pages available for DragonFly

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net