opt_plugin.texi

@c
@c This file is generated automatically by running "gmsh -doc".
@c Do not edit by hand!
@c

@ftable @code
@item Plugin(Annotate)
Plugin(Annotate) adds the text string `Text',
in font `Font' and size `FontSize', in the view
`iView'. If `ThreeD' is equal to 1, the plugin inserts
the string in model coordinates at the position
(`X',`Y',`Z'). If `ThreeD' is equal to 0, the plugin
inserts the string in screen coordinates at
the position (`X',`Y'). The string is aligned
according to `Align'. If `iView' < 0, the plugin
is run on the current view.

Plugin(Annotate) is executed in-place.

String options:
@table @code
@item Text
Default value: @code{"My Text"}
@item Font
Default value: @code{"Helvetica"}
@item Align
Default value: @code{"Left"}
@end table
Numeric options:
@table @code
@item X
Default value: @code{50}
@item Y
Default value: @code{30}
@item Z
Default value: @code{0}
@item ThereD
Default value: @code{0}
@item FontSize
Default value: @code{14}
@item iView
Default value: @code{-1}
@end table

@item Plugin(Curl)
Plugin(Curl) computes the curl of the field
in the view `iView'. If `iView' < 0, the plugin
is run on the current view.

Plugin(Curl) creates one new view.

Numeric options:
@table @code
@item iView
Default value: @code{-1}
@end table

@item Plugin(CutGrid)
Plugin(CutGrid) cuts the view `iView' with a
rectangular grid defined by the 3 points
(`X0',`Y0',`Z0') (origin), (`X1',`Y1',`Z1') (axis of
U) and (`X2',`Y2',`Z2') (axis of V). The number of
points along U and V is set with the options
`nPointsU' and `nPointsV'. If `ConnectPoints' is
zero, the plugin creates points; otherwise, the
plugin generates quadrangles, lines or points
 depending on the values of `nPointsU' and
`nPointsV'. If `iView' < 0, the plugin is run on
the current view.

Plugin(CutGrid) creates one new view.

Numeric options:
@table @code
@item X0
Default value: @code{0}
@item Y0
Default value: @code{0}
@item Z0
Default value: @code{0}
@item X1
Default value: @code{1}
@item Y1
Default value: @code{0}
@item Z1
Default value: @code{0}
@item X2
Default value: @code{0}
@item Y2
Default value: @code{1}
@item Z2
Default value: @code{0}
@item nPointsU
Default value: @code{20}
@item nPointsV
Default value: @code{20}
@item ConnectPoints
Default value: @code{1}
@item iView
Default value: @code{-1}
@end table

@item Plugin(CutMap)
Plugin(CutMap) extracts the isosurface of value
`A' from the view `iView' and draws the
`dTimeStep'-th value of the view `dView' on the
isosurface. If `iView' < 0, the plugin is run
on the current view. If `dTimeStep' < 0, the
plugin uses, for each time step in `iView', the
corresponding time step in `dView'. If `dView'
< 0, the plugin uses `iView' as the value source.
If `ExtractVolume' is nonzero, the plugin
extracts the isovolume with values greater (if
`ExtractVolume' > 0) or smaller (if `ExtractVolume'
< 0) than the isosurface `A'.

Plugin(CutMap) creates as many views as there
are time steps in `iView'.

Numeric options:
@table @code
@item A
Default value: @code{0}
@item dTimeStep
Default value: @code{-1}
@item dView
Default value: @code{-1}
@item ExtractVolume
Default value: @code{0}
@item RecurLevel
Default value: @code{4}
@item TargetError
Default value: @code{0}
@item iView
Default value: @code{-1}
@end table

@item Plugin(CutParametric)
Plugin(CutParametric) cuts the view `iView' with
the parametric function (`X'(u), `Y'(u), `Z'(u)),
using `nPointsU' values of the parameter u in
[`MinU', `MaxU']. If `ConnectPoints' is set, the
plugin creates line elements; otherwise, the
plugin generates points. If `iView' < 0, the plugin
is run on the current view.

Plugin(CutParametric) creates one new view.

String options:
@table @code
@item X
Default value: @code{"0 + 1 * Cos(u)"}
@item Y
Default value: @code{"0 + 1 * Sin(u)"}
@item Z
Default value: @code{"0"}
@end table
Numeric options:
@table @code
@item MinU
Default value: @code{0}
@item MaxU
Default value: @code{6.2832}
@item nPointsU
Default value: @code{360}
@item ConnectPoints
Default value: @code{0}
@item iView
Default value: @code{-1}
@end table

@item Plugin(CutPlane)
Plugin(CutPlane) cuts the view `iView' with
the plane `A'*X + `B'*Y + `C'*Z + `D' = 0. If
`ExtractVolume' is nonzero, the plugin extracts
the elements on one side of the plane (depending
on the sign of `ExtractVolume'). If `iView' < 0,
the plugin is run on the current view.

Plugin(CutPlane) creates one new view.

Numeric options:
@table @code
@item A
Default value: @code{1}
@item B
Default value: @code{0}
@item C
Default value: @code{0}
@item D
Default value: @code{-0.01}
@item ExtractVolume
Default value: @code{0}
@item RecurLevel
Default value: @code{4}
@item TargetError
Default value: @code{0}
@item iView
Default value: @code{-1}
@end table

@item Plugin(CutSphere)
Plugin(CutSphere) cuts the view `iView' with the
sphere (X-`Xc')^2 + (Y-`Yc')^2 + (Z-`Zc')^2 = `R'^2.
If `ExtractVolume' is nonzero, the plugin extracts
the elements inside (if `ExtractVolume' < 0) or
outside (if `ExtractVolume' > 0) the sphere. If
`iView' < 0, the plugin is run on the current view.

Plugin(CutSphere) creates one new view.

Numeric options:
@table @code
@item Xc
Default value: @code{0}
@item Yc
Default value: @code{0}
@item Zc
Default value: @code{0}
@item R
Default value: @code{0.25}
@item ExtractVolume
Default value: @code{0}
@item RecurLevel
Default value: @code{4}
@item iView
Default value: @code{-1}
@end table

@item Plugin(Divergence)
Plugin(Divergence) computes the divergence of the
field in the view `iView'. If `iView' < 0, the plugin
is run on the current view.

Plugin(Divergence) creates one new view.

Numeric options:
@table @code
@item iView
Default value: @code{-1}
@end table

@item Plugin(Eigenvalues)
Plugin(Eigenvalues) computes the three real
eigenvalues of each tensor in the view `iView'.
If `iView' < 0, the plugin is run on the current view.

Plugin(Eigenvalues) creates three new scalar views.

Numeric options:
@table @code
@item iView
Default value: @code{-1}
@end table

@item Plugin(Eigenvectors)
Plugin(Eigenvectors) computes the three (right)
eigenvectors of each tensor in the view `iView'
and sorts them according to the value of the
associated eigenvalues. If `ScaleByEigenvalues'
is set, each eigenvector is scaled by its
associated eigenvalue. The plugin gives an error
if the eigenvectors are complex. If `iView' < 0,
the plugin is run on the current view.

Plugin(Eigenvectors) creates three new
vector views.

Numeric options:
@table @code
@item ScaleByEigenvalues
Default value: @code{1}
@item iView
Default value: @code{-1}
@end table

@item Plugin(Evaluate)
Plugin(Evaluate) sets the `Component'-th
component of the `TimeStep'-th time step in the
view `iView' to the expression `Expression'.
`Expression' can contain:

- the usual mathematical functions (Log, Sqrt,
Sin, Cos, Fabs, ...) and operators (+, -, *, /, ^);

- the symbols x, y and z, to retrieve the
coordinates of the current node;

- the symbols Time and TimeStep, to retrieve the
current time and time step values;

- the symbol v, to retrieve the `Component'-th
component of the field in `iView' at the
`TimeStep'-th time step;

- the symbols v0, v1, v2, ..., v8, to retrieve each
component of the field in `iView' at the
`TimeStep'-th time step;

- the symbol w, to retrieve the `Component'-th
component of the field in `ExternalView' at the
`ExternalTimeStep'-th time step. If `ExternalView'
and `iView' are based on different spatial grids,
or if their data types are different, `ExternalView'
is interpolated onto `iView';

- the symbols w0, w1, w2, ..., w8, to retrieve each
component of the field in `ExternalView' at the
`ExternalTimeStep'-th time step.

If `TimeStep' < 0, the plugin automatically loops
over all the time steps in `iView' and evaluates
`Expression' for each one. If `ExternalTimeStep'
< 0, the plugin uses `TimeStep' instead. If
`Component' < 0, the plugin automatically loops
over all the components in the view and
evaluates `Expression' for each one. If `iView'
< 0, the plugin is run on the current view. If
`ExternalView' < 0, the plugin uses `iView'
instead.

Plugin(Evaluate) is executed in-place.

String options:
@table @code
@item Expression
Default value: @code{"v0*Sin(x)"}
@end table
Numeric options:
@table @code
@item Component
Default value: @code{-1}
@item TimeStep
Default value: @code{-1}
@item ExternalView
Default value: @code{-1}
@item ExternalTimeStep
Default value: @code{-1}
@item iView
Default value: @code{-1}
@end table

@item Plugin(Extract)
Plugin(Extract) extracts a combination of
components from the `TimeStep'th time step
in the view `iView'. If only `Expression0' is
given (and `Expression1', ..., `Expression8' are
all empty), the plugin creates a scalar view.
If `Expression0', `Expression1' and/or
`Expression2' are given (and `Expression3',
..., `Expression8' are all empty) the plugin
creates a vector view. Otherwise the plugin
creates a tensor view. In addition to the usual
mathematical functions (Exp, Log, Sqrt, Sin, Cos,
Fabs, etc.) and operators (+, -, *, /, ^), all
expressions can contain the symbols v0, v1, v2,
 ..., vn, which represent the n components of the
field, and the symbols x, y and z, which represent
the three spatial coordinates. If `TimeStep' < 0,
the plugin extracts data from all the time steps
in the view. If `iView' < 0, the plugin is run on
the current view.

Plugin(Extract) creates one new view.

String options:
@table @code
@item Expression0
Default value: @code{"Sqrt(v0^2+v1^2+v2^2)"}
@item Expression1
Default value: @code{""}
@item Expression2
Default value: @code{""}
@item Expression3
Default value: @code{""}
@item Expression4
Default value: @code{""}
@item Expression5
Default value: @code{""}
@item Expression6
Default value: @code{""}
@item Expression7
Default value: @code{""}
@item Expression8
Default value: @code{""}
@end table
Numeric options:
@table @code
@item TimeStep
Default value: @code{-1}
@item iView
Default value: @code{-1}
@end table

@item Plugin(ExtractElements)
Plugin(ExtractElements) extracts the elements
from the view `iView' whose `TimeStep'-th values
(averaged by element) are comprised between
`MinVal' and `MaxVal'. If `iView' < 0, the plugin
is run on the current view.

Plugin(ExtractElements) creates one new view.

Numeric options:
@table @code
@item MinVal
Default value: @code{0}
@item MaxVal
Default value: @code{1}
@item TimeStep
Default value: @code{0}
@item iView
Default value: @code{-1}
@end table

@item Plugin(FieldView)
Plugin(FieldView) evaluates a field on the choosen view.

Numeric options:
@table @code
@item Component
Default value: @code{-1}
@item iView
Default value: @code{-1}
@item iField
Default value: @code{-1}
@end table

@item Plugin(FiniteElement)
Plugin(FiniteElement) solves simple PDEs
using the finite element method. This is only
intended as a demonstration tool: it is NOT
intended for general use.
Plugin(FiniteElement) creates a new view.

String options:
@table @code
@item Equation
Default value: @code{"Projection"}
@item Parameter
Default value: @code{"Sin(x*y)"}
@item Gamma1BC
Default value: @code{""}
@item Gamma2BC
Default value: @code{""}
@end table
Numeric options:
@table @code
@item Omega
Default value: @code{1}
@item Gamma1
Default value: @code{0}
@item Gamma1Value
Default value: @code{0}
@item Gamma2
Default value: @code{0}
@item Gamma2Value
Default value: @code{0}
@end table

@item Plugin(GSHHS)
Plugin(GSHHS) read different kind of contour lines data and write a .geo file on the surface of a sphere (the Earth).
The principal application is to load GSHHS data
 (see http://www.soest.hawaii.edu/wessel/gshhs/gshhs.html).
Valid values for "Format" are ):
 -"gshhs" : open GSHHS file
 -"loops2" : import 2D contour lines in simple text format :
   NB_POINTS_IN_FIRST_LOOP FIRST_LOOP_IS_CLOSED
   COORD1 COORD2
   COORD1 COORD2
   ...    ...
   NB_POINTS_IN_SECOND_LOOP SECOND_LOOP_IS_CLOSED
   ...
   (LOOP_IS_CLOSED specify if this coast line describe a closed curve (0=no, 1=yes).
In the case of "loops2" format, you can specify the the coordinate system used in the input file with the"Coordinate" option, valid values are
 -"lonlat" for longitude-latidute radian,
 -"lonlat_degrees" for longitude-latitude degrees,
 -"UTM" for universal transverse mercartor ("UTMZone" option should be specified)
 -"cartesian" for full 3D coordinates
"radius" specify the earth radius.
If the "iField" option is set, consecutive points closer than the value of the field iField (in meters) will not be added.
If "MinStraitsFactor" >0 and if a field iField is provided, coastlines closer than MinStraitsFactor*field(IField) are merged and inner corners which form an angle < pi/3 are removed.
The output is always in stereographic coordinates, if the "WritePolarSphere" option is not 0, a sphere is added to the geo file.
WARNING : this plugin is still experimental and need polishing and error-handling. In particular, it will probably crash if an inexistant field id is given or if the input/output cannot be open.
String options:
@table @code
@item InFileName
Default value: @code{"gshhs_c.b"}
@item OutFileName
Default value: @code{"earth.geo"}
@item Format
Default value: @code{"gshhs"}
@item Coordinate
Default value: @code{"cartesian"}
@end table
Numeric options:
@table @code
@item iField
Default value: @code{-1}
@item UTMZone
Default value: @code{0}
@item UTMEquatorialRadius
Default value: @code{6.37814e+06}
@item UTMPolarRadius
Default value: @code{6.35675e+06}
@item radius
Default value: @code{6.37101e+06}
@item WritePolarSphere
Default value: @code{1}
@item MinStraitsFactor
Default value: @code{1}
@end table

@item Plugin(Gradient)
Plugin(Gradient) computes the gradient of the
field in the view `iView'. If `iView' < 0, the
plugin is run on the current view.

Plugin(Gradient) creates one new view.

Numeric options:
@table @code
@item iView
Default value: @code{-1}
@end table

@item Plugin(HarmonicToTime)
Plugin(HarmonicToTime) takes the values in the
time steps `RealPart' and `ImaginaryPart' of
the view `iView', and creates a new view
containing (`iView'[`RealPart'] * cos(p) -
`iView'[`ImaginaryPart'] * sin(p)), with
p = 2*Pi*k/`nSteps', k = 0, ..., `nSteps'-1.
If `iView' < 0, the plugin is run on the
current view.

Plugin(HarmonicToTime) creates one new view.

Numeric options:
@table @code
@item RealPart
Default value: @code{0}
@item ImaginaryPart
Default value: @code{1}
@item nSteps
Default value: @code{20}
@item iView
Default value: @code{-1}
@end table

@item Plugin(Integrate)
Plugin(Integrate) integrates scalar fields over
all the elements in the view `iView', as well
as the circulation/flux of vector fields over
line/surface elements. If `iView' < 0, the
plugin is run on the current view.

Plugin(Integrate) creates one new view.

Numeric options:
@table @code
@item iView
Default value: @code{-1}
@end table

@item Plugin(Lambda2)
Plugin(Lambda2) computes the eigenvalues
Lambda(1,2,3) of the tensor (S_ik S_kj +
Om_ik Om_kj), where S_ij = 0.5 (ui,j + uj,i)
and Om_ij = 0.5 (ui,j - uj,i) are respectively
the symmetric and antisymmetric parts of the
velocity gradient tensor. Vortices are well
represented by regions where Lambda(2) is
negative. If `iView' contains tensor elements,
the plugin directly uses the tensors as the
values of the velocity gradient tensor; if
`iView' contains vector elements, the plugin
uses them as the velocities from which to derive
the velocity gradient tensor. If `iView' < 0,
the plugin is run on the current view.

Plugin(Lambda2) creates one new view.

Numeric options:
@table @code
@item Eigenvalue
Default value: @code{2}
@item iView
Default value: @code{-1}
@end table

@item Plugin(LongitudeLatitude)
Plugin(LongituteLatitude) Project the view `iView'
in Longitude-Latitude. If `iView' < 0, the plugin
is run on the current view.

Plugin(LongituteLatitude) is executed in place.

Numeric options:
@table @code
@item iView
Default value: @code{-1}
@end table

@item Plugin(MakeSimplex)
Plugin(MakeSimplex) decomposes all non-
simplectic elements (quadrangles, prisms,
hexahedra, pyramids) in the view `iView' into
simplices (triangles, tetrahedra). If `iView' < 0,
the plugin is run on the current view.

Plugin(MakeSimplex) is executed
in-place.

Numeric options:
@table @code
@item iView
Default value: @code{-1}
@end table

@item Plugin(ModulusPhase)
Plugin(ModulusPhase) interprets the time steps
`realPart' and `imaginaryPart' in the view `iView'
as the real and imaginary parts of a complex field
and replaces them with their corresponding
modulus and phase. If `iView' < 0, the plugin is
run on the current view.

Plugin(ModulusPhase) is executed in-place.

Numeric options:
@table @code
@item RealPart
Default value: @code{0}
@item ImaginaryPart
Default value: @code{1}
@item iView
Default value: @code{-1}
@end table

@item Plugin(Probe)
Plugin(Probe) gets the value of the view `iView' at
the point (`X',`Y',`Z'). If `iView' < 0, the plugin is
run on the current view.

Plugin(Probe) creates one new view.

Numeric options:
@table @code
@item X
Default value: @code{0}
@item Y
Default value: @code{0}
@item Z
Default value: @code{0}
@item iView
Default value: @code{-1}
@end table

@item Plugin(Remove)
Plugin(Remove) removes the marked items
from the view `iView'. If `iView' < 0, the plugin
is run on the current view.

Plugin(Remove) is executed in-place.

Numeric options:
@table @code
@item Text2D
Default value: @code{1}
@item Text3D
Default value: @code{1}
@item Points
Default value: @code{0}
@item Lines
Default value: @code{0}
@item Triangles
Default value: @code{0}
@item Quadrangles
Default value: @code{0}
@item Tetrahedra
Default value: @code{0}
@item Hexahedra
Default value: @code{0}
@item Prisms
Default value: @code{0}
@item Pyramids
Default value: @code{0}
@item Scalar
Default value: @code{1}
@item Vector
Default value: @code{1}
@item Tensor
Default value: @code{1}
@item iView
Default value: @code{-1}
@end table

@item Plugin(Skin)
Plugin(Skin) extracts the skin (the boundary) of
the view `iView'. If `iView' < 0, the plugin is run
on the current view.

Plugin(Skin) creates one new view.

Numeric options:
@table @code
@item iView
Default value: @code{-1}
@end table

@item Plugin(Smooth)
Plugin(Smooth) averages the values at the nodes
of the scalar view `iView'. If `iView' < 0, the
plugin is run on the current view.

Plugin(Smooth) is executed in-place.

Numeric options:
@table @code
@item iView
Default value: @code{-1}
@end table

@item Plugin(SphericalRaise)
Plugin(SphericalRaise) transforms the
coordinates of the elements in the view
`iView' using the values associated with the
`TimeStep'-th time step. Instead of elevating
the nodes along the X, Y and Z axes as in
View[`iView'].RaiseX, View[`iView'].RaiseY
and View[`iView'].RaiseZ, the raise is applied
 along the radius of a sphere centered at
(`Xc', `Yc', `Zc'). To produce a standard
radiation pattern, set `Offset' to minus the
radius of the sphere the original data lives on.
If `iView' < 0, the plugin is run on the current
view.

Plugin(SphericalRaise) is executed in-place.

Numeric options:
@table @code
@item Xc
Default value: @code{0}
@item Yc
Default value: @code{0}
@item Zc
Default value: @code{0}
@item Raise
Default value: @code{1}
@item Offset
Default value: @code{0}
@item TimeStep
Default value: @code{0}
@item iView
Default value: @code{-1}
@end table

@item Plugin(StreamLines)
Plugin(StreamLines) computes stream lines
from the `TimeStep'-th time step of a vector
view `iView' and optionally interpolates the
scalar view `dView' on the resulting stream
lines. The plugin takes as input a grid defined
by the 3 points (`X0',`Y0',`Z0') (origin),
(`X1',`Y1',`Z1') (axis of U) and (`X2',`Y2',`Z2')
(axis of V). The number of points that are to
be transported along U and V is set with the
options `nPointsU' and `nPointsV'. The equation
DX(t)/dt=V(x,y,z) is then solved with the initial
condition X(t=0) chosen as the grid and with V(x,y,z)
interpolated on the vector view. The time stepping
scheme is a RK44 with step size `DT' and `MaxIter'
maximum number of iterations. If `iView' < 0, the
plugin is run on the current view. If `TimeStep' < 0,
the plugin tries to compute streamlines of the unsteady
flow.

Plugin(StreamLines) creates one new view. This
view contains multi-step vector points if `dView'
< 0, or single-step scalar lines if `dView' >= 0.

Numeric options:
@table @code
@item X0
Default value: @code{0}
@item Y0
Default value: @code{0}
@item Z0
Default value: @code{0}
@item X1
Default value: @code{1}
@item Y1
Default value: @code{0}
@item Z1
Default value: @code{0}
@item X2
Default value: @code{0}
@item Y2
Default value: @code{1}
@item Z2
Default value: @code{0}
@item nPointsU
Default value: @code{10}
@item nPointsV
Default value: @code{1}
@item MaxIter
Default value: @code{100}
@item DT
Default value: @code{0.1}
@item TimeStep
Default value: @code{0}
@item dView
Default value: @code{-1}
@item iView
Default value: @code{-1}
@end table

@item Plugin(Transform)
Plugin(Transform) transforms the homogeneous
node coordinates (x,y,z,1) of the elements in
the view `iView' by the matrix
[`A11' `A12' `A13' `Tx']
[`A21' `A22' `A23' `Ty']
[`A31' `A32' `A33' `Tz'].
If `SwapOrientation' is set, the orientation of the
elements is reversed. If `iView' < 0, the plugin
is run on the current view.

Plugin(Transform) is executed in-place.

Numeric options:
@table @code
@item A11
Default value: @code{1}
@item A12
Default value: @code{0}
@item A13
Default value: @code{0}
@item A21
Default value: @code{0}
@item A22
Default value: @code{1}
@item A23
Default value: @code{0}
@item A31
Default value: @code{0}
@item A32
Default value: @code{0}
@item A33
Default value: @code{1}
@item Tx
Default value: @code{0}
@item Ty
Default value: @code{0}
@item Tz
Default value: @code{0}
@item SwapOrientation
Default value: @code{0}
@item iView
Default value: @code{-1}
@end table

@item Plugin(Triangulate)
Plugin(Triangulate) triangulates the points in the
view `iView', assuming that all the points belong
to a surface that can be projected one-to-one
onto a plane. If `iView' < 0, the plugin is run on
the current view.

Plugin(Triangulate) creates one new view.

Numeric options:
@table @code
@item iView
Default value: @code{-1}
@end table

@item Plugin(Warp)
Plugin(Warp) transforms the elements in the
view `iView' by adding to their node coordinates
the vector field stored in the `TimeStep'-th time
step of the view `dView', scaled by `Factor'. If
`dView' < 0, the vector field is taken as the field
of surface normals multiplied by the `TimeStep'
value in `iView'. (The smoothing of the surface
normals is controlled by the `SmoothingAngle'
parameter.) If `iView' < 0, the plugin is run on
the current view.

Plugin(Warp) is executed in-place.

Numeric options:
@table @code
@item Factor
Default value: @code{1}
@item TimeStep
Default value: @code{0}
@item SmoothingAngle
Default value: @code{180}
@item dView
Default value: @code{-1}
@item iView
Default value: @code{-1}
@end table

@end ftable