.. highlight:: rst

.. _mtimg:

#####
mtimg
#####

**Create beachball images from a focal mechanism or a moment tensor.**


Description
===========

*mtimg* generates custom images from moment-tensor solutions and focal
mechanisms in different image formats. If unspecified, the file format is
determined by the ending of the output file. *mtimg* is called, e.g., by the
default script for report generation
:file:`@DATADIR@/mtv/tools/mtv-plot-extended-log.py` configured in :ref:`scmtv`
by :confval:`mtv.extendedLog.script` for :ref:`report generation
<sec-mtv-report>`.

Example:

* Generate a PNG image for focal mechanism with strike/dip/rake = 110/30/45 deg

  .. code-block:: sh

     mtimg 110 30 45 -d 200x200 -o mt.png


* Write JPEG image with 95% quality for moment tensor with
  RR/TT/PP/RT/RP/TP = 1/2/3/-1/0/-1 to stdout and then into file.

  .. code-block:: sh

     mtimg --quality 95 -f jpg 1 2 3 -1 0 -1 > /tmp/mt.jpg



Module Configuration
====================

| :file:`etc/defaults/global.cfg`
| :file:`etc/defaults/mtimg.cfg`
| :file:`etc/global.cfg`
| :file:`etc/mtimg.cfg`
| :file:`~/.seiscomp/global.cfg`
| :file:`~/.seiscomp/mtimg.cfg`

mtimg inherits :ref:`global options<global-configuration>`.

.. note::

   Modules/plugins may require a license file. The default path to license
   files is :file:`@DATADIR@/licenses/` which can be overridden by global
   configuration of the parameter :confval:`gempa.licensePath`. Example: ::

      gempa.licensePath = @CONFIGDIR@/licenses




Command-Line Options
====================

:program:`mtimg [options] [source parameters]`

Verbosity
---------

.. option:: --verbosity arg

   Verbosity level [0..4]. 0:quiet, 1:error, 2:warning, 3:info,
   4:debug.

.. option:: -v, --v

   Increase verbosity level \(may be repeated, eg. \-vv\).

.. option:: -q, --quiet

   Quiet mode: no logging output.

.. option:: --component arg

   Limit the logging to a certain component. This option can
   be given more than once.

.. option:: -s, --syslog

   Use syslog logging backend. The output usually goes to
   \/var\/lib\/messages.

.. option:: -l, --lockfile arg

   Path to lock file.

.. option:: --console arg

   Send log output to stdout.

.. option:: --debug

   Execute in debug mode.
   Equivalent to \-\-verbosity\=4 \-\-console\=1 .

.. option:: --log-file arg

   Use alternative log file.


Generic
-------

.. option:: -h, --help

   Show help message.

.. option:: -V, --version

   Show version information.

.. option:: --config-file arg

   Use alternative configuration file. When this option is
   used the loading of all stages is disabled. Only the
   given configuration file is parsed and used. To use
   another name for the configuration create a symbolic
   link of the application or copy it. Example:
   scautopick \-> scautopick2.

.. option:: --plugins arg

   Load given plugins.


Options
-------

.. option:: -d, --dimension arg

   Default: ``100x100``

   Output image dimensions in pixel \(width x height\).

.. option:: -o, --output arg

   Name of output image file. If unspecified or '\-',
   the image is written to stdout.

.. option:: -f, --format arg

   Image format, if unset, the format is derived by the
   output file name extension. Please refer to the
   command\-line help to get a list of formats supported
   by your platform.

.. option:: --quality arg

   Default: ``-1``

   The image quality factor which must be in the
   range 0 to 100 or \-1. Specify 0 to obtain small
   compressed files, 100 for large
   uncompressed files, and \-1 to use the default settings.

.. option:: --color-p arg

   Color of pressure area.

.. option:: --color-t arg

   Color of tension area.

.. option:: --color-b arg

   Color of borders.

.. option:: --shading

   Enable shading.

.. option:: --margin arg

   Width of margin.