1GMT_SHELL_FUNCTIONS.SH(1) GMT GMT_SHELL_FUNCTIONS.SH(1)
2
6 gmt_shell_functions.sh - Practical functions to be used in GMT bourne
7 shell scripts
8
10 gmt_init_tmpdir
11 gmt_remove_tmpdir
13 gmt_clean_up [prefix]
15 gmt_message message
17 gmt_abort message
19 gmt_build_movie [-d directory] [-n] [-r framerate] [-v] namestem
21 gmt_build_gif [-d directory] [-l loop] [-r delay] namestem
23 gmt_build_kmz -p prefix [ -r ] files
25 gmt_get_nrecords file(s)
27 gmt_get_ndatarecords file(s)
29 gmt_get_nfields string
31 gmt_get_field string
33 gmt_get_region file(s) [options]
35 gmt_get_gridregion file [options]
37 gmt_get_map_width -R -J
39 gmt_get_map_height -R -J
41 gmt_movie_script [-c canvas OR -e dpi -h height -w width] [-f format]
43 [-g fill] [-n frames] [-m margin] [-r rate] namestem
44 gmt_launch_jobs [-c n_cores] [-l nlines_per_cluster] [-n] [-v] [-w]
46 commandfile
47 gmt_set_psfile scriptfile
49 gmt_set_pdffile scriptfile
51 gmt_set_framename prefix framenumber
53 gmt_set_framenext framenumber
55
57 gmt_shell_functions.sh provides a set of functions to Bourne (again)
58 shell scripts in support of GMT. The calling shell script should
59 include the following line, before the functions can be used:
60 . gmt_shell_functions.sh
62 Once included in a shell script, gmt_shell_functions.sh allows GMT
64 users to do some scripting more easily than otherwise. The functions
65 made available are:
66 gmt_init_tmpdir
68 Creates a temporary directory in /tmp or (when defined) in the
69 directory specified by the environment variable TMPDIR. The name
70 of the temporary directory is returned as environment variable
71 GMT_TMPDIR. This function also causes GMT to run in 'isolation
72 mode', i.e., all temporary files will be created in GMT_TMPDIR
73 and the gmt.conf file will not be adjusted.
74 gmt_remove_tmpdir
76 Removes the temporary directory and unsets the GMT_TMPDIR envi‐
77 ronment variable.
78 gmt_cleanup
80 Remove all files and directories in which the current process
81 number is part of the file name. If the optional prefix is given
82 then we also delete all files and directories that begins with
83 the given prefix.
84 gmt_message
86 Send a message to standard error.
87 gmt_abort
89 Send a message to standard error and exit the shell.
90 gmt_get_nrecords
92 Returns the total number of lines in file(s)
93 gmt_get_ndatarecords
95 Returns the total number of data records in file(s), i.e., not
96 counting headers.
97 gmt_get_nfields
99 Returns the number of fields or words in string
100 gmt_get_field
102 Returns the given field in a string. Must pass string between
103 double quotes to preserve it as one item.
104 gmt_get_region
106 Returns the region in the form w/e/s/n based on the data in ta‐
107 ble file(s). Optionally add -Idx/dy to round off the answer.
108 gmt_get_gridregion
110 Returns the region in the form w/e/s/n based on the header of a
111 grid file. Optionally add -Idx/dy to round off the answer.
112 gmt_get_map_width
114 Expects the user to give the desired -R -J settings and returns
115 the map width in the current measurement unit.
116 gmt_get_map_height
118 Expects the user to give the desired -R -J settings and returns
119 the map height in the current measurement unit.
120 gmt_movie_script
122 Creates an animation bash script template based on the arguments
123 that set size, number of frames, video format etc. Without
124 arguments the function will display its usage.
125 gmt_launch_jobs
127 Takes a file with a long list of commands and splits them into
128 many chunks that can be executed concurrently. Without arguments
129 the function will display its usage. Note: It is your responsi‐
130 bility to make sure no race conditions occur (i.e., multiple
131 commands writing to the same file).
132 gmt_set_psfile
134 Create the output PostScript file name based on the base name of
135 a given file (usually the script name $0).
136 gmt_set_framename
138 Returns a lexically ordered filename stem (i.e., no extension)
139 given the file prefix and the current frame number, using a
140 width of 6 for the integer including leading zeros. Useful when
141 creating animations and lexically sorted filenames are required.
142 gmt_set_framenext
144 Accepts the current frame integer counter and returns the next
145 integer counter.
146 gmt_build_movie
148 Accepts a namestem which gives the prefix of a series of image
149 files with names dir/namestem_*.*. Optional argument sets the
150 directory [same as namestem], and frame rate [24]. Without
151 arguments the function will display its usage.
152 gmt_build_gif
154 Accepts a namestem which gives the prefix of a series of image
155 files with names dir/namestem_*.*. Optional argument sets the
156 directory [same as namestem], loop count and frame rate [24].
157 Without arguments the function will display its usage.
158 gmt_build_kmz
160 Accepts -p prefix [ -r ] and any number of KML files and and the
161 images they may refer to, and builds a single KMZ file with the
162 name prefix.kmz. Without arguments the function will display
163 its usage.
164
166 1. These functions only work in the Bourne shell (sh) and their deriva‐
167 tives (like ash, bash, ksh and zsh). These functions do not work in the
168 C shell (csh) or their derivatives (like tcsh), and cannot be used in
169 DOS batch scripts either.
170 2. gmt_shell_functions.sh were first introduced in GMT version 4.2.2
172 and have since been regularly expanded with other practical scripting
173 short-cuts. If you want to suggest other functions, please do so by
174 adding a New Issue request on gmt.soest.hawaii.edu.
175
177 gmt , gmt.conf , gmtinfo , grdinfo
178
180 2019, P. Wessel, W. H. F. Smith, R. Scharroo, J. Luis, and F. Wobbe
1815.4.5 Feb 24, 2019 GMT_SHELL_FUNCTIONS.SH(1)