NAME

       gmt_shell_functions.sh - Practical functions to be used in GMT bourne shell scripts

SYNOPSIS

       gmt_init_tmpdir

       gmt_remove_tmpdir

       gmt_clean_up [ prefix ]

       gmt_message message

       gmt_abort message

       gmt_build_movie [ -d directory ] [ -n ] [ -r framerate ] [ -v ] namestem

       gmt_build_gif [ -d directory ] [ -l loop ] [ -r delay ] namestem

       gmt_build_kmz -p prefix [ -r ] files

       gmt_get_nrecords file(s)

       gmt_get_ndatarecords file(s)

       gmt_get_nfields string

       gmt_get_field string

       gmt_get_region file(s) [ options ]

       gmt_get_gridregion file [ options ]

       gmt_get_map_width -R -J

       gmt_get_map_height -R -J

       gmt_movie_script [ -c canvas OR -e dpi -h height -w width ] [ -f format ]
              [ -g fill ] [ -n frames ] [ -m margin ] [ -r rate ] namestem

       gmt_launch_jobs [ -c n_cores ] [ -l nlines_per_cluster ] [ -n ] [ -v ] [ -w ] commandfile

       gmt_set_psfile scriptfile

       gmt_set_pdffile scriptfile

       gmt_set_framename prefix framenumber

       gmt_set_framenext framenumber

DESCRIPTION

       gmt_shell_functions.sh provides a set of functions to Bourne (Again) shell scripts in support of GMT. The
       calling shell script should include the following line, before the functions can be used:

       . gmt_shell_functions.sh

       Once included in a shell script, gmt_shell_functions.sh allows GMT users to do some scripting more easily
       than otherwise. The functions made available are:

       gmt_init_tmpdir
              Creates  a  temporary  directory  in  /tmp  or  (when  defined)  in the directory specified by the
              environment variable TMPDIR. The name of  the  temporary  directory  is  returned  as  environment
              variable GMT_TMPDIR. This function also causes GMT to run in 'isolation mode', i.e., all temporary
              files will be created in GMT_TMPDIR and the gmt.conf file will not be adjusted.

       gmt_remove_tmpdir
              Removes the temporary directory and unsets the GMT_TMPDIR environment variable.

       gmt_cleanup
              Remove  all files and directories in which the current process number is part of the file name. If
              the optional prefix is given then we also delete all files and directories that  begins  with  the
              given prefix.

       gmt_message
              Send a message to standard error.

       gmt_abort
              Send a message to standard error and exit the shell.

       gmt_get_nrecords
              Returns the total number of lines in file(s)

       gmt_get_ndatarecords
              Returns the total number of data records in file(s), i.e., not counting headers.

       gmt_get_nfields
              Returns the number of fields or words in string

       gmt_get_field
              Returns  the given field in a string. Must pass string between double quotes to preserve it as one
              item.

       gmt_get_region
              Returns the region in the form w/e/s/n based on the data in table file(s). Optionally add  -Idx/dy
              to round off the answer.

       gmt_get_gridregion
              Returns  the region in the form w/e/s/n based on the header of a grid file. Optionally add -Idx/dy
              to round off the answer.

       gmt_get_map_width
              Expects the user to give the desired -R -J settings and returns  the  map  width  in  the  current
              measurement unit.

       gmt_get_map_height
              Expects  the  user  to  give  the desired -R -J settings and returns the map height in the current
              measurement unit.

       gmt_movie_script
              Creates an animation bash script template based on the arguments that set size, number of  frames,
              video format etc.  Without arguments the function will display its usage.

       gmt_launch_jobs
              Takes  a  file  with a long list of commands and splits them into many chunks that can be executed
              concurrently.  Without  arguments  the  function  will  display  its  usage.   Note:  It  is  your
              responsibility  to make sure no race conditions occur (i.e., multiple commands writing to the same
              file).

       gmt_set_psfile
              Create the output PostScript file name based on the base name of a given file (usually the  script
              name $0).

       gmt_set_framename
              Returns  a  lexically  ordered  filename  stem  (i.e., no extension) given the file prefix and the
              current frame number, using a width of 6 for the integer  including  leading  zeros.  Useful  when
              creating animations and lexically sorted filenames are required.

       gmt_set_framenext
              Accepts the current frame integer counter and returns the next integer counter.

       gmt_build_movie
              Accepts  a namestem which gives the prefix of a series of image files with names dir/namestem_*.*.
              Optional argument sets the directory [same as namestem ], and frame rate [24].  Without  arguments
              the function will display its usage.

       gmt_build_gif
              Accepts  a namestem which gives the prefix of a series of image files with names dir/namestem_*.*.
              Optional argument sets the directory [same as namestem], loop count and frame rate [24].   Without
              arguments the function will display its usage.

       gmt_build_kmz
              Accepts  -p  prefix  [  -r ] and any number of KML files and and the images they may refer to, and
              builds a single KMZ file with the name prefix.kmz.  Without arguments the  function  will  display
              its usage.

NOTES

       1.  These  functions  only  work  in the Bourne shell (sh) and their derivatives (like ash, bash, ksh and
       zsh). These functions do not work in the C shell (csh) or their derivatives (like tcsh),  and  cannot  be
       used in DOS batch scripts either.

       2.  gmt_shell_functions.sh  were  first  introduced  in  GMT  version 4.2.2 and have since been regularly
       expanded with other practical scripting short-cuts. If you want to suggest other functions, please do  so
       by adding a New Issue request on https://github.com/GenericMappingTools/gmt.

SEE ALSO

       gmt, gmt.conf, gmtinfo, grdinfo

COPYRIGHT

       2024, The GMT Team

6.5                                               Jan 07, 2024                         GMT_SHELL_FUNCTIONS.SH(1)