Visualization Module (-V)

Module -V is the module for visualizing tessellations, meshes, simulation results and custom data, either as publication-quality (raster) PNG or (vectorial) 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). This 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 rendered to produce high-quality (raster) PNG images (by default) or high-quality (vectorial) 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 4.0.0
Info   : Built with: gsl|muparser|opengjk|openmp|nlopt|libscotch (full)
Info   : Running on 8 threads.
Info   : <https://neper.info>
Info   : Copyright (C) 2003-2024, and GNU GPL'd, by Romain Quey.
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   : 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 (elset3d, col)...
Info   : Printing image...
Info   :     [o] Writing file `img.pov'...
Info   :   - Printing mesh...
Info   :     > Reducing data...
Info   :       . 3D...
Info   :       . 2D...
Info   :       . Number of 3D elt faces reduced by  90% (to 418).
Info   :       . Number of 3D elt edges reduced by  50% (to 627).
Info   :       . Number of 0D elts      reduced by 100% (to 0).
Info   :     [o] Wrote file `img.pov'.
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.546 secs.
========================================================================

Arguments

Prerequisites

-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.

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.

Note

It is used by option -space [i]pf.

Default value: value read in the inputs when defined, 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;

  • 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 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 in color 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 the 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 applied only in PF 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 radian (default is the fundamental region);

    • axis-angle[(<max>[,absolute])] for rotation axis / angle coloring, where <max> is the maximum angle (in radian) and absolute makes it so 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:

Note

-datacelledgerad applied only in PF space.

Default value: tessellation dependent.

-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.

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: <data_minimum>:<data_maximum>.

-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 -data<entity>rad 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 R-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, nodes, and full mesh). elt and elset refer to the elements and elsets of higher dimensions. The dimension can be also be specified explicitly, as in elt2d or elset2d. 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 in color 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,elt{2,3}dedge,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>: vectorial values (only for VTK output), which can be:

  • tensor:<data_value>: tensorial 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 (elsets of higher dimension colored, other elsets white, element edges black)

-data{elt,elset,node,elt{0-3}d,elset{0-3}d}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 radian (default is the fundamental region);

    • axis-angle[(<max>[,absolute])] for rotation axis / angle coloring, where <max> is the maximum angle (in radian) and absolute makes it so 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}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}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.

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: <data_minimum>:<data_maximum>.

-data{elt,elset,node,elt{0-3}d,elset{0-3}d}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,elset{0-3}d}rad <rad>

Specify the radii, which can be:

  • a real value;

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

Default value: mesh dependent.

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 in color 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 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 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.

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: <data_minimum>:<data_maximum>.

-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<entity>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 interprated 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.

Show Options

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

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

Show or hide a full tessellation or mesh, the mesh slices, the 1D elements of the mesh slices, the coordinate system, or the scale, 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.

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.

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 (nodes). Also note that the 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 to define individual values;

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

  • 0 or none: none.

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

-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 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 are equal to 3.462, -5.770 and 4.327, respectively in 3D, and 0, 0 and 8, respectively, in 2D.

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.

-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: orthographic for 2D and perspective for 3D.

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: x:-y.

-[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.

-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 disable 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.

Output Image Options

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

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

  • Usual , 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 (scalar 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.

Renderer Options

-povrayantialiasing <logical>

Specify whether antialiasing (which produces a smoother PNG image) should be used.

Default value: 1.

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: -.

Output Options

-outdir <dir1>,<dir2>,...

Specify the output directories (the first valid one is used), which can be:

  • a custom directory;

  • sim_dir: the standard location of the simulation directory, <dir.sim>/images/, where <format> is the image format (see option -imageformat). sim_dir is only valid if a simulation directory is loaded as input.

For example, to write to a simulation directory when loaded as input and to the local directory in other cases, sim_dir,. (which may be placed in the initialization file).

Default value: ..

Advanced Options

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

Include objects to the image under the form of POV-Ray files and optionally apply it a transformation. 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 thetax, thetay and thetaz about x, y and z.

    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: -.

Output Files

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

  • .pdf: PDF file, a scalar 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.

Examples

Below are some examples of use of neper -V.

  • Print out tessellation n10-id1.tess with cells colored from their identifiers and an image size of 900 x 450 pixels:

    $ neper -V n10-id1.tess -datacellcol id -imagesize 900:450 -print img

  • Print out tessellation n10-id1.tess with cells colored from crystal orientations and semi-transparency:

    $ neper -V n10-id1.tess -datacellcol ori -datacelltrs 0.5 -print img

  • Print out mesh n10-id1.msh with elements colored from scalar values written in file v and a scale ranging from 0 to 100:

    $ neper -V n10-id1.msh -dataeltcol "real:file(v)" -dataeltscale 0:100 -print img

  • Print out mesh n10-id1.msh with elements colored from nodal scalar values written in file v and a scale ranging from 0 to 100:

    $ neper -V n10-id1.msh -datanodecol "real:file(v)" -dataeltcol from_nodes -dataeltscale 0:100 -print img

  • Print out the 10 first cells of a 100-cell tessellation, colored from their identifiers and semi-transparency, and with edges shown in red and vertices shown as green spheres of radius 0.01:

    $ neper -V n100-id1.tess -showcell "id<=10" -datacellcol id -datacelltrs 0.5 -showedge cell_shown -showver cell_shown -dataverrad 0.01 -dataedgecol red -datavercol green -print img

  • Print out the interior element sets of mesh n100-id1.msh and show the 1D elements:

    $ neper -V n100-id1.tess,n100-id1.msh -dataelsetcol id -showelset 'body>0' -showelt1d elt3d_shown -print img

  • Print out 3 slices of mesh n100-id1.msh:

    $ neper -V n100-id1.msh -dataelsetcol id -slicemesh "x=0.5:y=0.5:z=0.5" -print img

  • Print out slices of mesh n100-id1.msh, at z coordinates ranging from 0.1 to 0.9 by step of 0.1, each slice being printed in a separate file:

    $ neper -V n100-id1.msh -dataelsetcol id -loop Z 0.1 0.1 0.9 -slicemesh "z=Z" -print imgZ -endloop

  • Print out a deformed mesh colored by orientations, defined from a simulation directory:

    $ neper -V mysim.sim -step 10 -datanodecoo coo -dataeltcol ori -print img

  • Print out a deformed mesh colored by orientations, defined from a simulation directory; generate an image at each deformation step:

    $ neper -V mysim.sim -loop STEP 0 1 10 -step STEP -datanodecoo coo -dataeltcol ori -print imgSTEP -endloop