%====================================================================================
% USER MANUAL -- TGF software
%====================================================================================
%
% Version 2019-10-29
%
% Citation for this work:
% M. Yang, C. Hirt, R. Pail (2019) TGF: A New MATLAB-based Software for Terrain
% Gravity Field Calculation. Comput. Geosci., under review.
%-----------------------------------------------------------------------------------
% This is the user manual for TGF software which is developed for the calculations
% of full-scale topographic and RTM gravitational field in the Matlab environment.
%
% Please consult the Quick-start file for further information, including test data
% sets and simple examples for using the TGF software with its GUI or in batch mode.
%
% The full-scale topographic gravitational field calculated via the TGF software
% is generated by the topographic masses boundied by the mean sea level and the
% Earth surface, while the high-frequency RTM gravity field is caused by the
% attraction of residual masses between the Earth's surafce and a reference
% surface.
%
% In the TGF software, the topographic masses around the calculation point are
% divided into four zones for RTM gravity field calculation and five zones for
% full-scale topographic gravity field. The mass elements of nearest zones around
% calculation points are approximated by polyhedron and prism for precise
% computation, while tesseroid and point-mass for efficient computation for the
% far-zone masses. Please refer to following papers for detailed information about
% combination of various mass elements, and numerical evaluation of gravity field
% generated by polyhedron, tesseroid, and point mass:
% D. Tsoulis (2012) Analytical computation of the full gravity tensor of a
% homogeneous arbitrarily shaped polyhedral source using line integral.
% Geophysics 77(2), F1-F11.
% D. Nagy, G. Papp, J. Benedek (2000) The gravitational potential and its
% derivatives for prism. Journal of Geodesy 74, 552-560.
% D. Nagy, G. Papp, J. Benedek (2002) Corrections to "The gravitational potential
% and its derivatives for prism". Journal of Geodesy 76, 475-475.
% T. Grombein, K. Seitz, B. Heck (2013) Optimized formulas for the gravitational
% field of a tesseroid. Journal of Geodesy 87(7), 645-660.
% X.L. Deng, T. Grombein, W.B. Shen, B. Heck, K. Seitz (2016) Corrections to
% “A comparison of the tesseroid, prism and point-mass approaches for mass
% reductions in gravity field modelling” (Heck and Seitz, 2007) and “Optimized
% formulas for the gravitational field of a tesseroid” (Grombein et al., 2013).
% Journal of Geodesy 90, 585-587.
% M. Yang, C. Hirt, R. Tenzer, R. Pail (2018) Experiences with the use of
% mass-density maps in residual gravity forward modelling. Stud. Geophys. Geod., 62.
% M. Yang, C. Hirt, M. Rexer, R. Pail, D. Yamazaki (2019) The tree canopy effect
% in gravity forward modelling. Geophys. J. Int., 219 (1),
% https://doi.org/10.1093/gji/ggz264 .
% M. Yang, C. Hirt, R. Pail (2019) TGF: A New MATLAB-based Software for Terrain
% Gravity Field Calculation. Comput. Geosci., under review.
%% ----------------- Structures of the TGF software --------------------------------
% The TGF software works in two modes: in interactive mode with GUI interface and
% in batch mode without the GUI interface. In interative mode, the TGF interface is
% divided into four functional components: Computation Point, Forward Masses,
% Gravitational Field and Output:
% The 'Computation Point' component specifies and located the file contains
% computation point information.
% The ’Forward Mass’ module defines the input file to define the topographic masses,
% via the geometric upper and lower boundaries and density values.
% Parameters required for gravitational field calculation are defined in the module
% ‘Gravitational Field’.
% The outputs are defined in the 'Output' panel.
%% ---------------------- Input parameters -----------------------------------------
% ComPoints --- in binary format, list of number of points and triplet of the
& spherical/ellipsoidal coordinates (lat[-90, 90],
% lon [-180, 180], height [in meters])
% DetailedDEM --- Detailed DEM, in binary format
% --- [minlat maxlat reslat minlon maxlon reslon elevation]
% DetailedREF --- RTM reference surface with same resolution as DetailedDEM.bin
% MassDensity --- Map of mass density values, same resolution as DetailedDEM.bin
% --- (from nearest neigb.)
% --- Only used when not a constant value is selected
% --- Unit g/cm^3
% TessDEM --- DEM for tessroid zone
% TessREF --- REF for tessroid zone
% TessDensity --- mass density model for tessroid zone
% CoarseDEM --- lower resolution DEM for far-zone
% CoarseREF --- lower resolution REF for far-zone
% CoarseDensity --- lower resolution mass density model for far-zone
% GlobalDEM --- Global DEM for full-scale topographic gravity field calculations
% GlobalREF --- Global reference DEM for full-scale topographic gravity field
% calculations (mean sea level) In full-scale topographic gravity field calculations,
% & constant density assumption is made in TGF software for GlobalDEM covred area.
% idensity --- flag for mass density with values of 0, 1
% --- 0, constant value is used
% --- 1, density map is used
% ikind --- flag for the type of modelling with values of 1, 2
% --- 1, Topographic gravitational field
% --- 2, RTM gravitational field
% itype --- Specification of field functionals with values of 0, 1, 2, 4, 10, 103, 104
% --- 0, height anomaly / geoid height (N) in cm
% --- 1, Dovs (arc-sec) and gravity disturbances (mGal)
% --- 4, Dovs (arc-sec) and gravity anomaly (mGal)
% --- 2, all gradients (6 elements) in E
% --- 10, all functionals (geoid, Dovs, gravity disturbances, gradient tensor)
% --- 103, geoid height, Dovs and gravity disturbances
% --- 104, geoid height, Dovs and gravity anomaly
% rzones --- integral radius specifying the computation zones rzones = [r1 r2 r3 r4]
% --- r1, radius for polyhedron (detailed DEM)
% --- r2, radius for prism (detailed DEM)
% --- r3, radius for tesseroid (Tesseroid DEM)
% --- r4, radius for point-mass (coarse DEM)
% flag_earth --- flag of earth approximation with values of 0, 1
% --- 0, spherical approximation
% --- 1, ellipsoidal approximation
% e --- mass density in g/cm^3 when constant density assumption is used
%% ------------------------ Output parameters --------------------------------------
% height anomaly in unit of centi-meter, Dov in unit of arc-sec, dg in unit of
% mGal, gradients in unit of E
%% ------------------------ Run TGF in batch mode ----------------------------------
% TC_GUI (vstpar,ComPoints, DetailedDEM, DetailedREF, MassDensity, TessDEM, TessREF, ...
% TessDensity, CoarseDEM, CoarseREF, CoarseDensity,GlobalDEM,GlobalREF, outname, ...
% ikind, itype,idensity, flag_earth,rzones, e);
%% ---------------------- Notes on data formats ------------------------------------
% The input files (DEM grids) must be in binary format. You can generate your own
% DEM input data in binary format using the Matlab-script Write_DEM.m. Please
% consult this file for the file structure.
%% ---------------------- Assistance needed ? --------------------------------------
% Write an e-mail to Meng Yang via meng.yang@tum.de or meng.yang@vip.126.com.
%% -------------------------------- DISCLAIMER ------------------------------------
% The TGF is research-only software. Neither TU Munich nor any of its staff accept
% any liability in connection with the use of the software, data and models provided
% here. Neither TU Munich nor any of its staff make any warranty of correctness,
% fitness, completeness, usefulness and accuracy of the the software, data and
% models for any intented or unintended purpose.
%-----------------------------------------------------------------------------------