Visualization Module (-V)#

Module -V is the module for visualizing tessellations, meshes, simulation results and custom data, either as publication-quality (raster) PNG or (vector) PDF images, or VTK files, for interactive visualization. Visualization can be done in real (physical) space, but also on pole figures or inverse pole figures, which is managed by option -space.

Virtually any detail of the visualization can be set. For example, all entities (tessellation polyhedra, faces, edges, vertices, seeds and crystals, 3D, 2D, 1D and 0D mesh elements and nodes, and points) can be assigned a particular color, size, transparency, etc. (options -data*), the visibility of the different entities can be adjusted (options -show*), or slice views can be generated (option -slicemesh). These different capabilities make it possible to carry out standard or advanced visualizations but also post-processing.

Note

The specification of colors, etc. via options -data* and visibility via options -show* is common to all spaces.

Standard, real space visualizations (default -space real) are achieved using the POV-Ray ray tracing renderer to produce high-quality (raster) PNG images. The parameters of the “scene” are assigned default values, but can also be fine-tuned, such as the light positions, camera position and angle, projection type, etc. (options -camera* and -light*).

Pole figure and inverse pole figure visualizations (option -space pf) are achieved using the Asymptote vector graphics renderer to produce high-quality (raster) PNG images (by default) or high-quality (vector) PDF images. Data can be represented as symbols or a density field, and can be superimposed. Orientation trajectories can be plotted (option -step).

In contrast to other modules, module -V can generate several outputs on the same run (using option -print several times); command arguments are therefore read in batches, stopping at each -print to generate an output.

Here is what a typical run of module -V looks like:

$ neper -V n10-id1.tess,n10-id1.msh -dataelsetcol id -print img

========================    N   e   p   e   r    =======================
Info   : A software package for polycrystal generation and meshing.
Info   : Version 5.0.1
Info   : Built with: gsl|libgmsh|muparser|opengjk|openmp|libscotch
         (full)
Info   : Running on 8 threads.
Info   : <https://neper.info>
Info   : Copyright (C) 2003-2026, and GNU GPL'd, by Romain Quey, CNRS.
Info   : No initialization file found (`/home/rquey/.neperrc').
Info   : ---------------------------------------------------------------
Info   : MODULE  -V loaded with arguments:
Info   : [ini file] (none)
Info   : [com line] n10-id1.tess,n10-id1.msh -dataelsetcol id -print img
Info   : ---------------------------------------------------------------
Info   :   - Reading arguments...
Info   : Loading tessellation...
Info   :     [i] Parsing file `n10-id1.tess'...
Info   :     [i] Parsed file `n10-id1.tess'.
Info   : Loading mesh...
Info   :     [i] Parsing file `n10-id1.msh'...
Info   :     [i] Parsed file `n10-id1.msh'.
Info   : Reconstructing mesh...
Info   : Reading data (elset, col)...
Info   : Printing image...
Info   :   - Printing mesh...
Info   :     > Reducing data...
Info   :       . 3D...
Info   :       . 2D...
Info   :       . Number of 3D elt faces reduced by  90% (to 290).
Info   :       . Number of 3D elt edges reduced by  50% (to 435).
Info   :       . Number of 0D elts      reduced by 100% (to 0).
Info   :   - Generating png file (1200x900 pixels)...
Info   :     [o] Writing file `img.png'...
Info   :     [o] Wrote file `img.png'.
Info   : Printing scale...
Info   : Elapsed time: 1.111 secs.
========================================================================

Input Data#

<file_name1>,<file_name2>,...#

Specify the input file(s) or directory. The argument can be:

For ori, the descriptor can be specified (see Rotations and Orientations, default rodrigues).

Note

As a custom input is loaded, new options such as -data<input>col, -show<input>, etc. are defined, as described in the following. It is possible to load several custom inputs.

Default value: -.

-crysym <crysym>#

Specify the crystal symmetry (see Crystal Symmetries).

Note

It is used by option -space [i]pf, ori and rodrigues. The orientation space is available for the cubic and hexagonal symmetries only.

Default value: value read in the inputs when defined (other than triclinic), and cubic otherwise.

When a simulation directory is loaded as input, it is possible to specify the simulation step to consider.

-step <step>#

Specify the simulation step(s), which can be:

  • 0: the initial state;

  • final: the final step;

  • any step number;

  • all: all steps;

  • a list of steps combined with ,; a range of values can also be specified using -. An example is 0-10,20 (for steps 0 to 10, and 20).

Note

Several steps can be specified in the case of -space [i]pf, to plot orientation trajectories.

Default value: 0.

The data internal to the simulation directory have the same status as internal data (such as, for instance, the nominal element orientations stored in the mesh file) and can therefore be loaded (with options -data*) more simply than with standard external files. For example, coloring elements from orientations can be done using -step 2 -dataeltcol ori.

Space Options#

The following option enables the definition of the space in which data (simulation, tessellation, mesh, point, etc.) are represented. The space is most generally real (physical) space, real, but can be defined as pole figure space, pf, or tree space, tree. Tree space shows a tree-like structure of a simulation directory.

-space <space>#

Specify the space in which data are represented, which can be:

  • real: real (physical) space;

  • pf: pole figure space;

  • ipf: inverse pole figure space;

  • ori: orientation space (an alias for rodrigues(fr20), see below);

  • rodrigues[(fr<N>)]: Rodrigues orientation space, and the (optional) fr<N> mesh of the fundamental region (default fr20);

  • tree: tree space.

Default value: real.

Tessellation Data Loading and Rendering Options#

The following option enables the definition of the cell data itself (pole figure space only):

-datacell <type>:<value>#

Specify the cell data type and value, which can be:

Default value: ori.

-datacellweight <weight>#

Specify the cell weights, which can be:

Note

-datacellweight applies only in [i]pf space (see option -space).

Default value: size.

The following options enable the definition of the properties (color and size) of the tessellation cells or entities (polyhedra, faces, edges and vertices), seeds and crystals. Crystals are plotted at the centers of their respective cells, shaped according to the crystal symmetry (see Crystal Symmetries) and have the same volumes as their respective cells. This can be done either directly, by providing one or several values (e.g. the RGB channel values for color) or indirectly, e.g. using scalar values that are converted into colors using a given color scheme. In this case (and for real-type data), a scale image is also generated, and its properties (minimum, maximum and tick values) can be specified.

For each entity, all attributes can be set, although they may not apply in certain spaces (see option -space). Specifically, -data{cell,poly,face}rad do not apply in real space.

-data{cell,poly,face,edge,ver,seed,crystal,vox,voidvox,{crystal,cell,vox}edge}col <color>#

Specify the colors, which can be done in two main different ways.

Colors can be specified directly:

Colors can be set from data using an argument of the general form <data_type>:<data_value>, which can be shortened to <data_value> in the frequent case where the data type can be unambiguously determined from the data value. The possibilities are:

  • int:<data_value>: integer values represented using a color palette, which can be:

  • real:<data_value>: real values represented using a smooth color scale, which can be:

  • ori:<data_value>: crystal orientations (when applicable), which can be:

  • disori:<data_value> (only for vox): crystal disorientations (the rotation with respect to the nominal cell orientation, when applicable), which can be:

See also option -data...colscheme.

Note

-datacelledgecol applies only in pole figure space.

Default value: id for cells and crystals, white for faces, black for edges and vertices, gray for seeds, voxels and void voxels, black for voxel edges.

-data{cell,poly,face,edge,ver,seed,crystal,vox}colscheme <col_scheme>#

Specify the color scheme used to get colors from the data loaded with option -data...col. The type of color scheme depends on the type of data.

  • For integer values, the color scheme is palette, as described in Color Map for Integer Values;

  • For real values, the available color schemes are described in Color Maps for Real Values;

  • For crystal orientations (cubic symmetry is assumed), the color scheme can be:

    • ipf[(<dir>)]: IPF coloring using direction <dir>, which can be x, y or z (default z);

    • rodrigues[(<max>)]: Rodrigues vector coloring, where <max> is the half-length along a direction (default is the fundamental region);

    • axis: rotation axis coloring;

    • angle[(<max>)]: rotation angle coloring, where <max> is the maximum angle (in radians, default is the fundamental region);

    • axis-angle[(<max>[,absolute])] for rotation axis / angle coloring, where <max> is the maximum angle (in radians) and absolute specifies that the absolute values of the axis components are used.

Default value: palette for integer values, viridis for real values, and rodrigues for crystal orientations.

-data{cell,poly,face,edge,ver,seed,crystal}trs <transparency>#

Specify the transparencies (values from 0 to 1), which can be:

-data{cell,poly,face,edge,ver,seed,crystal,{crystal,cell,vox}edge}rad <rad>#

Specify the radii, which can be:

In an expression, default is the default radius (for ver, edge, seed and the cells of the highest dimension), e.g. (domtype==1)?default*1.5:default for thicker domain edges.

Note

-datacelledgerad applies only in pole figure space.

Default value: tessellation dependent; the radii of the vertices and edges scale with the domain size and the number of cells, and are the same as those of the 0D and 1D elements of a mesh of the tessellation.

-data{cell,poly,face,edge,ver,seed,crystal,vox}scale <scale>#

Specify the scale relative to the -data...col real data, which can be:

  • <min>:<max>: minimal and maximal values;

  • <min>:<inter1>:...:<max>: minimal, intermediate and maximal values.

Each value can be a real value, min or max (data minimum or maximum), or a percentile of the data, <p>% (e.g. 5%). Percentiles truncate the distribution so that a few outliers do not compress the color range; values out of the scale take the color of the closest scale end, and the data minimum and maximum are then printed below the scale (see -show{tess,tesr,mesh,meshslice,meshsliceelt1d,csys,scale,scalemin,scalemax}). Use min:max for the full data range.

When only minimal and maximal values are specified, the scale ticks are set automatically. When intermediate values are specified, the scale ticks are the specified values.

The scale ticks have the same format as the minimal value.

Default value: 2%:98%.

-data{cell,poly,face,edge,ver,seed,crystal,vox}scaletitle <title>#

Specify the title of the scale relative to the -data...col real data.

Default value: -.

-datacellsymbol <symbol>#

Specify the symbol representing the cells (only for -space pf), which can be:

  • a symbol to apply to all cells (see below);

  • file(<file_name>): individual values to load from a Data File.

A symbol can be (all arguments are optional, and the radius is taken from option -datacellrad if defined):

  • circle[(rad=<rad>)]: a circle/disc of specified radius;

  • square[(rad=<rad>,theta=<angle>)]: a square of specified properties;

  • triangle[(rad=<rad>,theta=<angle>)]: a triangle of specified properties;

  • diamond[(rad=<rad>,theta=<angle>)]: a diamond (45° rotated square) of specified properties;

  • star[(rad=<rad>,theta=<angle>)]: a five-branch star of specified properties.

Default value: circle.

Mesh Data Loading and Rendering Options#

-dataelsetweight <weight>#

Specify the elset weights, which can be:

Note

-dataelsetweight applies only in [i]pf space (see option -space).

Default value: size.

The following options enable the definition of the properties (color, size, etc.) of the mesh entities (3D, 2D, 1D and 0D elements and elsets, cohesive elements and elsets, nodes, and full mesh). elt and elset refer to the elements and elsets of the highest dimension. The dimension can also be specified explicitly, as in elt2d or elset2d. eltco and elsetco represent the cohesive elements and elsets (see option -showeltco). node represents all nodes, and mesh the full mesh. This can be done either directly, by providing one or several values (e.g. the RGB channel values for color) or indirectly, e.g. using scalar values that are converted into colors using a given color scheme. In this case (and for real-type data), a scale image is also generated, and its properties (minimum, maximum and tick values) can be specified.

-data{elt,elset,node,elt{0-3}d,elset{0-3}d,eltco,elsetco,elt{2,3}dedge,eltcoedge,mesh}col <color>#

Specify the colors, which can be done in two main different ways.

Colors can be specified directly:

Colors can be set from data using an argument of the general form <data_type>:<data_value>, which can be shortened to <data_value> in the frequent case where the data type can be unambiguously determined from the data value. The possibilities are:

  • int:<data_value>: integer values represented using a color palette, which can be:

  • real:<data_value>: real values represented using a smooth color scale, which can be:

  • vector:<data_value>: vector values (only for VTK output), which can be:

  • tensor:<data_value>: tensor values (only for VTK output), which can be:

    • a simulation result (see Simulation Results);

    • file(<file_name>): individual values to load from a Data File. The file can contain either 9 components or only 6 components, in which case Voigt notation is assumed.

  • ori:<data_value>: crystal orientations (when applicable), which can be:

The color schemes used to determine the colors from the data can be fine-tuned using options -dataeltcolscheme or -dataelsetcolscheme.

Default value: -dataelsetcol id and -dataelsetcocol id (elsets of the highest dimension and cohesive elsets colored, other elsets white, element edges black).

-data{elt,elset,node,elt{0-3}d,elset{0-3}d,eltco,elsetco}colscheme <col_scheme>#

Specify the color scheme used to get colors from the data loaded with option -data...col. The type of color scheme depends on the type of data.

  • For integer values, the color scheme is palette, as described in Color Map for Integer Values;

  • For real values, the available color schemes are described in Color Maps for Real Values;

  • For crystal orientations (cubic symmetry is assumed), the color scheme can be:

    • ipf[(<dir>)]: IPF coloring using direction <dir>, which can be x, y or z (default z);

    • rodrigues[(<max>)]: Rodrigues vector coloring, where <max> is the half-length along a direction (default is the fundamental region);

    • axis: rotation axis coloring;

    • angle[(<max>)]: rotation angle coloring, where <max> is the maximum angle (in radians, default is the fundamental region);

    • axis-angle[(<max>[,absolute])] for rotation axis / angle coloring, where <max> is the maximum angle (in radians) and absolute specifies that the absolute values of the axis components are used.

Default value: palette for integer values, viridis for real values, and rodrigues for crystal orientations.

-data{elt2d,elset2d,eltco,elsetco}trs <transparency>#

Specify the transparencies (values from 0 to 1), which can be:

  • a real value;

  • an expression based on the variables described in Mesh Keys, such as x or area;

  • file(<file_name>): individual values to load from a Data File.

-data{elt,elset,node,elt{0-3}d,elset{0-3}d,eltco,elsetco}scale <scale>#

Specify the scale relative to the -data...col real data, which can be:

  • <min>:<max>: minimal and maximal values;

  • <min>:<inter1>:...:<max>: minimal, intermediate and maximal values.

Each value can be a real value, min or max (data minimum or maximum), or a percentile of the data, <p>% (e.g. 5%). Percentiles truncate the distribution so that a few outliers do not compress the color range; values out of the scale take the color of the closest scale end, and the data minimum and maximum are then printed below the scale (see -show{tess,tesr,mesh,meshslice,meshsliceelt1d,csys,scale,scalemin,scalemax}). Use min:max for the full data range.

When only minimal and maximal values are specified, the scale ticks are set automatically. When intermediate values are specified, the scale ticks are the specified values.

The scale ticks have the same format as the minimal value.

Default value: 2%:98%.

-data{elt,elset,node,elt{0-3}d,elset{0-3}d,eltco,elsetco}scaletitle <title>#

Specify the title of the scale relative to the -data...col real data.

Default value: -.

-data{elt{0,1}d,node,elt{2,3}dedge,eltcoedge,elset{0-3}d}rad <rad>#

Specify the radii, which can be:

  • a real value;

  • an expression based on the variables described in Mesh Keys (not for *edge*), which allows one to define individual values;

  • file(<file_name>): individual values to load from a Data File (not for *edge*).

In an expression, default is the default radius (not for eltcoedge), e.g. (domtype==1)?default*1.5:default for thicker 1D elements on the domain edges, or default*2 for *edge*.

Default value: mesh dependent; the radii scale with the domain size and the number of cells (elsets of the highest dimension), so that the 0D and 1D elements have the same radii as the vertices and edges of the tessellation, except for the nodes, whose radius is \(0.1/N^{1/4}\), where \(N\) is the number of nodes.

The following options enable the loading of node positions.

-datanodecoo <coo>#

Specify the coordinates of the nodes, which can be done in two main different ways.

Coordinates can be specified directly as follows:

  • file(<file_name>): individual coordinates to load from a Position File.

Coordinates can be set from data using an argument of the general form <data_type>:<data_value>:

  • disp:file(<file_name>): individual displacements to load from a Data File (formatted as a Position File);

  • coo: load coordinates from the simulation directory and step specified in input.

Default value: -.

-datanodecoofact <fact>#

Specify the value of the scaling factor to apply to the displacements of the nodes.

Default value: 1.

Custom Input Data Loading and Rendering Options#

The following options enable the definition of the properties (color, shape, size, etc.) of custom inputs. This can be done either directly, by providing one or several values (e.g. the RGB channel values for color) or indirectly, e.g. using scalar values that are converted into colors using a given color scheme. In this case (and for real-type data), a scale image is also generated, and its properties (minimum, maximum and tick values) can be specified.

-data<input>col <color>#

Specify the colors of the input points, which can be done in two main different ways.

Colors can be specified directly:

Colors can be set from data using an argument of the general form <data_type>:<data_value>, which can be shortened to <data_value> in the frequent case where the data type can be unambiguously determined from the data value. The possibilities are:

  • int:<data_value>: integer values represented using a color palette, which can be:

    • an integer value;

    • an expression based on the variables defined in Point Keys, such as id or cell, which allows one to define individual values;

    • file(<file_name>): individual values to load from a Data File.

  • real:<data_value>: real values represented using a smooth color scale, which can be:

    • a real value;

    • an expression based on the variables described in Point Keys, such as x or y, which allows one to define individual values;

    • file(<file_name>): individual values to load from a Data File.

See also option -data<input>colscheme.

Default value: id.

-data<input>colscheme <col_scheme>#

Specify the color scheme used to get colors from the data loaded with option -data<input>col. The type of color scheme depends on the type of data.

Default value: palette for integer values and viridis for real values.

-data<input>trs <transparency>#

Specify the transparency of the input points (a value from 0 to 1), which can be:

  • a real value;

  • file(<file_name>): individual values to load from a Data File.

Default value: 0.

-data<input>scale <scale>#

Specify the scale relative to the -data<input>col real data, which can be:

  • <min>:<max>: minimal and maximal values;

  • <min>:<inter1>:...:<max>: minimal, intermediate and maximal values.

Each value can be a real value, min or max (data minimum or maximum), or a percentile of the data, <p>% (e.g. 5%). Percentiles truncate the distribution so that a few outliers do not compress the color range; values out of the scale take the color of the closest scale end, and the data minimum and maximum are then printed below the scale (see -show{tess,tesr,mesh,meshslice,meshsliceelt1d,csys,scale,scalemin,scalemax}). Use min:max for the full data range.

When only minimal and maximal values are specified, the scale ticks are set automatically. When intermediate values are specified, the scale ticks are the specified values.

The scale ticks have the same format as the minimal value.

Default value: 2%:98%.

-data<input>scaletitle <title>#

Specify the title of the scale relative to the -data<input>col real data.

Default value: -.

-data<input>coo <coo>#

Specify the coordinates of the input points, which can be done in two main different ways.

Coordinates can be specified directly as follows:

  • file(<file_name>): individual coordinates to load from a Position File.

Coordinates can be set from data using an argument of the general form <data_type>:<data_value>:

  • disp:file(<file_name>): individual displacements to load from a Data File (formatted as a Position File);

  • coo: load coordinates from the simulation directory and step specified in input.

Default value: -.

-data<input>coofact <fact>#

Specify the value of the scaling factor to apply to the displacements of the input points.

Default value: 1.

-data<input>rad <rad>#

Specify the radii of the input points, which can be:

  • a real value;

  • file(<file_name>): individual values to load from a Data File (not for *edge*).

Default value: 0.02.

-data<input>symbol <symbol>#

Specify the symbol representing the input points, which can be:

  • a symbol to apply to all input points (see below);

  • file(<file_name>): individual values to load from a Data File.

A symbol can be (all arguments are optional, and the radius is taken from option -data<input>rad if defined):

  • sphere[(rad=<rad>)]: a sphere of radius <rad>;

  • cube[(rad=<rad>,ori=<ori>)]: a cube of radius (half edge length) <rad> and orientation <ori> (default identity);

  • cylinder[(rad=<rad>,length=<length>,axis=(<axis_x>,<axis_y>,<axis_z>))]: a cylinder of specified properties;

  • arrow[(rad=<rad>,length=<length>,axis=(<axis_x>,<axis_y>,<axis_z>))]: an arrow of specified properties;

  • disc[(rad=<rad>,axis=(<axis_x>,<axis_y>,<axis_z>))]: a disc of specified properties;

  • ellipsoid[(rad1=<rad>,rad2=<rad>,rad3=<rad>,axis1=(<axis_x>,<axis_y>,<axis_z>),axis2=(<axis_x>,<axis_y>,<axis_z>),axis3=(<axis_x>,<axis_y>,<axis_z>))]: an ellipsoid of specified properties;

  • torus[(rad1=<rad>,rad2=<rad>,axis=(<axis_x>,<axis_y>,<axis_z>))]: a torus of specified properties.

Default value: sphere.

-data<input>edgerad <rad>#

Specify the radius of the input point edges (represented as symbols), which can be any real value (\(\geq0\)).

Default value: 0.

-data<input>edgecol <color>#

Specify the color of the input point edges (represented as symbols), which can be a color as described in Colors and Color Maps.

Default value: black.

Coordinate System Rendering Options#

-datacsyscoo <coo_x>:<coo_y>:<coo_z>#

Specify the coordinates of the origin of the coordinate system.

Default value: 0:0:0.

-datacsyslength <length>#

Specify the length of the coordinate system axes.

Default value: 0.2.

-datacsysrad <rad>#

Specify the radius of the coordinate system axes.

Default value: 0.01.

-datacsyslabel <label_x>:<label_y>:<label_z>#

Specify the labels of the coordinate system axes.

Note

A LaTeX (mathematical) syntax can be used, but is interpreted as such only by the Asymptote renderer.

Default value: $X_1$:$X_2$:$X_3$.

-datacsyscol <color>#

Specify the color of the coordinate system, which can be a color as described in Colors and Color Maps.

Default value: 32:32:32.

-datacsysfontsize <size>#

Set the font size of the labels of the coordinate system axes.

Default value: 1.

Domain Rendering Options#

The following options apply to the domain (see -showdomain).

-datadomainrad <rad>#

Specify the radius of the domain edges, which can be a real value or an expression of the following variables, e.g. default*2 or elt1drad*1.5:

  • default: the default radius of the domain edges;

  • edgerad: the default radius of the tessellation edges (half of default);

  • elt1drad: the default radius of the 1D elements (the same as edgerad);

  • elt2dedgerad and elt3dedgerad: the default radii of the edges of the 2D and 3D elements.

The mesh variables are computed from the tessellation when no mesh is loaded.

Default value: twice the default radius of the tessellation edges (edgerad*2).

-datadomaincol <color>#

Specify the color of the domain edges, which can be a color as described in Colors and Color Maps.

Default value: black.

Show Options#

The following options apply to the full tessellations, mesh, etc.

-show{tess,tesr,mesh,meshslice,meshsliceelt1d,csys,scale,scalemin,scalemax} <logical>#

Show or hide a full tessellation or mesh, the mesh slices, the 1D elements of the mesh slices, the coordinate system, the scale, or (on the scale itself) the scale (data) minimum and maximum, respectively.

Note

The 1D elements of the mesh slices are printed as specified by options -dataelt1d*.

Default value: 1 for the more informative data (mesh slice \(>\) mesh \(>\) tessellation) and 0 for others; 1 for the scale, and 1 for the scale (data) minimum and maximum if they are out-of-scale, and 0 otherwise.

-showdomain <logical>#

Show or hide the domain, as a wireframe, i.e. the edges of the tessellation that are on domain edges (curved domain edges are curved). The domain is shown whether or not the tessellation is, e.g. to outline a mesh, and its rendering is set by options -datadomainrad and -datadomaincol.

Default value: 0.

The following option applies to a tessellation or a raster tessellation.

-show{cell,poly,face,edge,ver,seed,crystal,faceinter,vox} <logical>#

Specify the entities to show. The argument can be:

For faces, etc., cell_shown and poly_shown can also be used. The -show* options are processed by decreasing entity dimension, so that such variables account for the other -show* options, whatever their order (the same applies to the mesh, e.g., -showelt1d elt3d_shown).

Default value: all for cells and edges, none for others.

The following options apply to the entities of the mesh. The options apply to 3D elements (elt3d) and element sets (elset3d), 2D elements (elt2d) and element sets (elset2d), 1D elements (elt1d) and element sets (elset1d), 0D elements (elt0d) and element sets (elset0d), and nodes (node). Also note that elt and elset can be used to denote the highest-dimension elements and elsets.

-show{elt,elset,elt{0-3}d,elset{0-3}d,node} <logical>#

Specify the entities to show. The argument can be:

  • 1 or all: all;

  • an expression based on the Mesh Keys, which allows one to define individual values. For -shownode, the expression can also include nset==<nset_label>, which is true for the nodes of a node set of the Mesh File (.msh) (for example, -shownode nset==z1). The label can be enclosed in double quotes, which is needed if it contains other characters than letters, digits and underscores;

  • file(<file_name>): individual values to load from a Data File;

  • 0 or none: none.

Default value: 1 if the highest mesh dimension is 3 and 0 otherwise.

-show{eltco,elsetco} <logical>#

Specify the cohesive elements to show (see Meshing Module (-M)’s option -interface). The argument can be:

  • 1 or all: all;

  • an expression based on the Mesh Keys, which allows one to define individual values;

  • file(<file_name>): individual values to load from a Data File;

  • 0 or none: none.

Cohesive elements of zero thickness lie at the interfaces between the element sets and so are hidden by the 3D elements, but can be shown with -showelt3d 0. Their faces and edges of zero size are not printed. Cohesive elements of non-zero thickness can be obtained using Meshing Module (-M)’s option -transform explode.

Default value: 1.

-show<input> <logical>#

Show or hide the points of a custom input. The argument can be:

  • 1 or all: all;

  • an expression based on the Point Keys, which allows one to define individual values;

  • file(<file_name>): individual values to load from a Data File;

  • 0 or none: none.

Default value: 1.

Slice Options#

-slicemesh <plane1>,<plane2>,...#

Plot one (or several) slice(s) of the mesh. A slicing plane is defined by its equation, such as x=0 or 0.12*x+0.34*y+0.56*z=0.78.

Default value: -.

Camera Options#

-cameracoo <coo_x>:<coo_y>:<coo_z>#

Specify the coordinates of the camera. The coordinates can be defined as expressions based on the following variables:

  • x, y and z: the center of the tessellation or mesh (if both a tessellation and a mesh have been loaded, the mesh is considered);

  • length: the average length of the domain (1 for a unit cube);

  • vx, vy and vz: the coordinates of the shift vector, which in real space are equal to 3.462, -5.770 and 4.327, respectively, in 3D, and 0, 0 and 8, respectively, in 2D. In orientation space, the coordinates are equal to 4, 4 and 3, respectively.

Default value: x+length*vx:y+length*vy:z+length*vz.

-cameralookat <coo_x>:<coo_y>:<coo_z>#

Specify the coordinates of the camera look-at point. The coordinates can be defined as expressions based on the following variables:

  • x, y and z: the center of the tessellation or mesh (if both a tessellation and a mesh have been loaded, the mesh is considered).

Default value: x:y:z.

-cameraangle <angle>#

Specify the opening angle of the camera along the horizontal direction (in degrees).

The opening angle along the vertical direction is determined from the opening along the horizontal direction and the image size ratio.

Default value: 25 in -space real, and 20 for cubic crystal symmetry and 32 otherwise in -space ori.

-camerasky <dir_x>:<dir_y>:<dir_z>#

Specify the sky vector of the camera (vertical direction of the image).

Default value: 0:1:0 in 2D and 0:0:1 in 3D.

-cameraprojection <projection>#

Specify the type of projection of the camera, which can be perspective or orthographic.

Default value: For -space real: orthographic for 2D and perspective for 3D; for -space ori: orthographic.

Light Options#

These options set the lights (only for the POV-Ray renderer).

-lightambient <ambient>#

Specify the amount of ambient light. Ambient light is light that is scattered everywhere in the scene, and it ranges from 0 to 1.

Default value: 0.6 in 3D and 1 in 2D.

-lightsource <light1>:<light2>:...#

Specify the light sources. The argument can be:

  • point(coo=<coo>[,color=<color>][,shadow={0,1}]): a point light source, where:

    • <coo> can be either camera (for the camera coordinates) or <coo_x>:<coo_y>:<coo_z> for actual coordinates.

    • <color> can be any color as described in Colors and Color Maps.

    • <shadow> can be 0 for no shadows or 1 for shadows.

  • none: none.

Default value: "point(coo=camera,shadow=0)" in 3D and none in 2D.

-lightdiffuse <diffuse>#

Specify the amount of diffuse reflection, i.e. how much of the light coming directly from any light sources is reflected by diffuse reflection. It ranges from 0 to 1.

Default value: 0.6.

-lightreflection <reflection>#

Specify the amount of specular reflection, ranging from 0 to 1.

Default value: 0.0.

Note

To disable all light effects, use -lightambient 1 -lightsource none.

Scene Options#

-scenebackground <color>#

Specify the color of the background, which can be any color as described in Colors and Color Maps.

Default value: white.

Pole Figure and Inverse Pole Figure Options#

Most options apply to pole figures or inverse pole figures and can equivalently be called as -pf... or -ipf.... For inverse pole figures, cubic crystal symmetry is assumed.

-[i]pfdir <dir1>:<dir2>#

Specify the 2 reference coordinate system directions aligned with the horizontal and vertical directions of the pole figure, respectively, which can be x, y, z, -x, -y or -z.

Note

The resulting normal direction must be pointing upwards. To set the actual direction labels, see option -datacsyslabel.

Default value: y:-x.

-[i]pfpole <h>:<k>:<l> or <h>:<k>:<i>:<l>#

Specify the pole (for orientation input). It is a crystal (family) direction for pole figures and a reference direction for inverse pole figures. A crystal family direction can be specified using Miller indices (3 values, for cubic) or Miller-Bravais indices (4 values, for hexagonal).

Default value: 1:1:1 for -space pf and cubic crystal symmetry, 0:0:0:1 for -space pf and hexagonal crystal symmetry, and 0:0:1 for -space ipf.

-[i]pfprojection <projection>#

Specify the projection, which can be stereographic or equal-area.

Default value: stereographic.

-[i]pfsym <symmetry>#

Specify the symmetry, which can be monoclinic, orthotropic or uniaxial.

Default value: monoclinic.

-pfshape <shape>#

Specify the shape, which can be full (full circle) or quarter (quarter-circle, for orthotropic symmetry).

Default value: full.

-[i]pfmode <mode1>,<mode2>,...#

Specify the representation mode, which can be:

  • symbol: data represented as symbols;

  • density: data represented as a distribution density field.

Note

Modes are processed successively, so that the last one(s) are printed on top of the first one(s). In the case of multiple inputs, density is applied only to the first input.

Default value: symbol.

-[i]pfkernel <kernel>#

Specify the kernel used to smooth pole directions when computing a pole density field, which can be:

  • normal(theta=<theta>): a (2-variate) normal distribution of (1-D) standard deviation <theta> (in degrees).

Default value: normal(theta=3).

-[i]pfgridsize <size> (secondary option)#

Specify the size of the density grid (in pixels).

Default value: 200.

-[i]pfclustering <logical>#

Specify whether data clustering (which speeds up density generation) should be used.

Note

Clustering is available only for standard pole figures (-space pf -pfshape full).

Clustering applies to all representation modes (see -[i]pfmode) and slightly alters the point positions. It should be disabled for absolute accuracy.

Default value: 1.

-[i]pffont <font> (secondary option)#

Specify the character font, which can be TimesRoman or ComputerModern.

Default value: TimesRoman.

-[i]pfprojectionlabel <label>#

Specify the projection label.

Default value: stereo. proj. for -[i]pfprojection stereographic and equal-area proj. for -[i]pfprojection equal-area.

-[i]pfpolelabel <label>#

Specify the pole label.

Default value: {<h><k>[<i>]<l>} for PFs and {X,Y,Z} direction for IPFs.

Orientation Space Options#

-oricol <color>#

Specify the color of orientation space (see Colors and Color Maps).

Default value: white.

-oritrs <transparency>#

Specify the transparency of orientation space (value from 0 to 1).

Default value: 0.5.

-oriedgecol <color>#

Specify the color of the edges of orientation space (see Colors and Color Maps).

Default value: black.

-oriedgerad <rad>#

Specify the radius of the edges of orientation space.

Default value: 0.002 for cubic crystal symmetry and 0.0035 for hexagonal crystal symmetry.

-oriedgetrs <transparency>#

Specify the transparency of the edges of orientation space (value from 0 to 1).

Default value: 0.

-orimode <mode1>,<mode2>,...#

Specify the representation mode, which can be:

  • symbol: data represented as symbols;

  • density: data represented as a distribution density field.

Note

Modes are processed successively, so that the last one(s) are printed on top of the first one(s). In the case of multiple inputs, density is applied only to the first input.

Default value: symbol.

-orifield <field>#

Specify the field to represent, which must be a simulation result.

Note

Requires -orimode density.

Default value: -.

-orilayout <layout>#

Specify the orientation space layout, in the case where a field is visualized (-orimode density), which can be:

  • surface for the surface of orientation space;

  • slices for orthogonal slices (\(x=0\), \(y=0\) and \(z=0\)).

Note

The scale automatically appears to the right of the image. Use -showscale 0 to exclude it.

Default value: surface for -orimode symbol, and surface,slices for -orimode [symbol,]density.

-orisym <symmetry>#

Specify the sample symmetry, which can be monoclinic (no symmetry) or orthotropic. In the case of orthotropic, each orientation is represented together with its 3 images by the rotations of 180 degrees about the sample axes (the width of the density smoothing is not affected).

Note

Not available with -orifield.

Default value: monoclinic.

Output Image Options#

-imageformat <format1>,<format2>,...#

Specify the format(s) of the output image(s), which can be:

  • Real-space images:

    • png: the PNG format;

    • pov: the POV-Ray format;

    • pov:objects: the POV-Ray format, but containing only the objects (the resulting file can be loaded with -includepov, not compatible with png);

    • vtk: the VTK format.

  • Pole figure images:

    • pdf: the PDF format (vector format, recommended);

    • png: the PNG format;

    • asy: the Asymptote format.

Default value: png.

-imagesize <size_x>:<size_y>#

Specify the size of the PNG image (in pixels).

Default value: 1200:900.

Scripting Options#

-loop <variable> <initial_value> <increment_value> <final_value> <commands> -endloop#

Create a loop of commands, as in -loop Z 0.1 0.1 0.9 -slicemesh "z=Z" -print zZ -endloop.

Default value: -.

Advanced Options#

-includepov <file_name1>[:<transformation1>:<transformation2>:...],<file_name2>,...#

Include objects in the image in the form of POV-Ray files and optionally apply transformations to them. A transformation can be:

  • translate(<dist_x>,<dist_y>,<dist_z>): translate by distances <dist_x>, <dist_y> and <dist_z> along x, y and z, respectively;

  • scale(<fact_x>,<fact_y>,<fact_z>): scale by <fact_x>, <fact_y> and <fact_z> along x, y and z, respectively;

  • rotate(<theta_x>,<theta_y>,<theta_z>): rotate by angles <theta_x>, <theta_y> and <theta_z> about x, y and z.

    Important

    The rotation is read in POV-Ray style, i.e., according to the POV-Ray documentation:

    Note that the order of the rotations does matter.  Rotations occur about the x-axis
    first, then the y-axis, then the z-axis.  If you are not sure if this is what you
    want, then you should only rotate on one axis at a time using multiple rotation
    statements to get a correct rotation.  Rotation is always performed relative to the
    axis. Thus, if an object is some distance from the axis of rotation, it will not only
    rotate but it will orbit about the axis as though it was swinging around on an
    invisible string.  POV-Ray uses a left-handed rotation system. Using the famous
    "Computer Graphics Aerobics" exercise, you hold up your left hand and point your thumb
    in the positive direction of the axis of rotation.  Your fingers will curl in the
    positive direction of rotation.  Similarly, if you point your thumb in the negative
    direction of the axis, your fingers will curl in the negative direction of
    rotation.
    

Default value: -.

-povray <binary>#

Specify the POV-Ray command or the path to the POV-Ray binary (for generating standard PNG images).

Default value: povray.

-asymptote <binary>#

Specify the Asymptote command or the path to the Asymptote binary (for generating pole figures).

Default value: asy.

Output Files#

  • .png: PNG file, a bitmapped image (the alpha channel is off);

  • .pdf: PDF file, a vector image;

  • .pov: POV-Ray file, a POV-Ray script file;

  • .asy: Asymptote file, an Asymptote script file;

  • .vtk: a VTK file, for interactive visualization.

A PNG image can be obtained from a POV-Ray file by invoking POV-Ray as follows (see the POV-Ray documentation for details and further commands):

$ povray <file.pov> +W<image_width>+H<image_height> -D +A0.2

Images can be obtained from an Asymptote file by invoking Asymptote as follows (see the Asymptote documentation for details and further commands):

$ asy -f <format> <file.asy>

where <format> can be png, pdf, eps, jpg, tiff, etc.