1.. index:: ! gmtgravmag3d
2.. include:: ../module_supplements_purpose.rst_
3
4************
5gmtgravmag3d
6************
7
8|gmtgravmag3d_purpose|
9
10Synopsis
11--------
12
13.. include:: ../../common_SYN_OPTs.rst_
14
15**gmt gravmag3d** *xyz_file* |-T|\ **v**\ *vert_file* OR |-T|\ **r\|s**\ *raw_file* OR |-M|\ **+s**\ *body,params*
16[ |-C|\ *density* ]
17[ |-E|\ *thickness* ]
18[ |-F|\ *xy_file* ]
19[ |-G|\ *outgrid* ]
20[ |-H|\ *f_dec*/*f_dip*/*m_int*/*m_dec*/*m_dip* ]
21[ |-L|\ *z_observation* ]
22[ |-S|\ *radius* ]
23[ |-Z|\ *level* ]
24[ |SYN_OPT-V| ]
25[ **-fg**]
26[ |SYN_OPT--| ]
27
28|No-spaces|
29
30Description
31-----------
32
33**gravmag3d** will compute the gravity or magnetic anomaly of a body described by a set of triangles.
34The output can either be along a given set of xy locations or on a grid. This method is not particularly
35fast but allows computing the anomaly of arbitrarily complex shapes.
36
37Required Arguments (not all)
38----------------------------
39
40.. _-C:
41
42**-C**\ *density*
43    Sets body density in SI. This option is mutually exclusive with **-H**.
44
45.. _-H:
46
47**-H**\ *f_dec*/*f_dip*/*m_int*/*m_dec*/*m_dip*
48    Sets parameters for computing a magnetic anomaly. Use *f_dec*/*f_dip* to set the geomagnetic
49    declination/inclination in degrees. *m_int*/*m_dec*/*m_dip* are the body magnetic intensity
50    declination and inclination.
51
52.. _-F:
53
54**-F**\ *xy_file*
55    Provide locations where the anomaly will be computed. Note this
56    option is mutually exclusive with **-G**.
57
58.. _-G:
59
60.. |Add_outgrid| replace:: Give the name of the output grid file.
61.. include:: /explain_grd_inout.rst_
62    :start-after: outgrid-syntax-begins
63    :end-before: outgrid-syntax-ends
64
65.. _-M:
66
67**-M+s**\ *body,params* (An alternative to **-Tr**\ /**-Ts**). Create geometric bodies and compute their grav/mag effect.
68    Select among one or more of the following bodies, where *x0* & *y0* represent the horizontal coordinates
69    of the body center [default to 0,0 positive up], *npts* is the number of points that a circle is discretized
70    and *n_slices* apply when bodies are made by a pile of slices. For example Spheres and Ellipsoids are made of
71    *2 x n_slices* and Bells have *n_slices* [Default 5]. It is even possible to select more than one body. For example
72    **-M+s**\ *prism,1/1/1/-5/-10/1*\ **+s**\ *sphere,1/-5* computes the effect of a prism and a sphere. Unfortunately there is
73    no current way of selecting distinct densities or magnetic parameters for each body.
74
75      - *bell,height/sx/sy/z0[/x0/y0/n_sig/npts/n_slices]* Gaussian of height *height* with characteristic STDs *sx* and *sy*. The base width (at depth *z0*) is controlled by the number of sigmas (*n_sig*) [Default = 2]
76
77      - *cylinder,rad/height/z0[/x0/y0/npts/n_slices]* Cylinder of radius *rad* and height *height* and base at depth *z0*
78
79      - *cone,semi_x/semi_y/height/z0[/x0/y0/npts]* Cone of semi axes *semi_x/semi_y* height *height* and base at depth *z0*
80
81      - *ellipsoid,semi_x/semi_y/semi_z/z_center[/x0/y0/npts/n_slices]* Ellipsoid of semi axes *semi_x/semi_y/semi_z* and center depth *z_center*
82
83      - *prism,side_x/side_y/side_z/z0[/x0/y0]* Prism of sides *x/y/z* and base at depth *z0*
84
85      - *pyramid,side_x/side_y/height/z0[/x0/y0]* Pyramid of sides *x/y* height *height* and base at depth *z0*
86
87      - *sphere,rad/z_center[/x0/y0/npts/n_slices]* Sphere of radius *rad* and center at depth *z_center*
88
89.. |Add_-R| replace:: |Add_-R_links|
90.. include:: ../../explain_-R.rst_
91    :start-after: **Syntax**
92    :end-before: **Description**
93
94.. _-T:
95
96**-Tv**\ *vert_file* (must have when passing a *xyz_file*) OR **-Tr\|s**\ *raw_file*
97    Gives names of a xyz and vertex (**-Tv**\ *vert_file*) files defining a close surface.
98    The file formats correspond to the output of the :doc:`triangulate </triangulate>` program.
99    The *xyz* file can have 3, 4, 5, 6 or 8 columns. In first case (3 columns) the magnetization (or density) are
100    assumed constant (controlled by **-C** or **-H**). Following cases are: 4 columns -> 4rth col magnetization intensity;
101    5 columns: mag, mag dip; 6 columns: mag, mag dec, mag dip; 8 columns: field dec, field dip, mag, mag dec, mag dip.
102    When n columns > 3 the third argument of the **-H** option is ignored. A *raw* format (selected by the **-Tr** option)
103    is a file with N rows (one per triangle) and 9 columns corresponding to the x,y,x coordinates of each of the three
104    vertex of each triangle. Alternatively, the **-Ts** option indicates that the surface file is in the ASCII STL
105    (Stereo Lithographic) format. These two type of files are used to provide a closed surface.
106
107Optional Arguments
108------------------
109
110.. |Add_-V| replace:: |Add_-V_links|
111.. include:: /explain_-V.rst_
112    :start-after: **Syntax**
113    :end-before: **Description**
114
115.. _-E:
116
117**-E**\ [*thickness*]
118    give layer thickness in m [Default = 0 m]. Use this option only when
119    the triangles describe a non-closed surface and you want the anomaly
120    of a constant thickness layer.
121
122.. _-L:
123
124**-L**\ [*z_observation*]
125    sets level of observation [Default = 0]. That is the height (z) at
126    which anomalies are computed.
127
128.. _-S:
129
130**-S**\ *radius*
131    search radius in km. Triangle centroids that are further away than
132    *radius* from current output point will not be taken into account.
133    Use this option to speed up computation at expenses of a less
134    accurate result.
135
136.. _-Z:
137
138**-Z**\ [*level*]
139    level of reference plane [Default = 0]. Use this option when the
140    triangles describe a non-closed surface and the volume is defined
141    from each triangle and this reference level. An example will be the
142    hater depth to compute a Bouguer anomaly.
143
144**-fg**
145   Geographic grids (dimensions of longitude, latitude) will be converted to
146   meters via a "Flat Earth" approximation using the current ellipsoid parameters.
147
148.. include:: ../../explain_help.rst_
149
150Grid Distance Units
151-------------------
152
153If the grid does not have meter as the horizontal unit, append **+u**\ *unit* to the input file name to convert from the
154specified unit to meter.  If your grid is geographic, convert distances to meters by supplying **-fg** instead.
155
156Examples
157--------
158
159To compute the magnetic anomaly of a cube of unit sides located at 5 meters depth and centered at -10,1 in a domain
160*-R-15/15/-15/15* with a magnetization of 10 Am with a declination of 10 degrees, inclination of 60 in a magnetic field
161with -10 deg of declination and 40 deg of inclination, do::
162
163    gmt gmtgravmag3d -R-15/15/-15/15 -I1 -H10/60/10/-10/40 -M+sprism,1/1/1/-5/-10/1 -Gcube_mag_anom.grd
164
165See Also
166--------
167
168:doc:`gmt </gmt>`, :doc:`grdgravmag3d`,
169:doc:`talwani2d </supplements/potential/talwani2d>`,
170:doc:`talwani3d </supplements/potential/talwani3d>`
171
172Reference
173---------
174
175Okabe, M., Analytical expressions for gravity anomalies due to
176polyhedral bodies and translation into magnetic anomalies, *Geophysics*,
17744, (1979), p 730-741.
178