Commit 13966a13 authored by Jay Jay Billings's avatar Jay Jay Billings
Browse files

Merge remote-tracking branch 'origin/next' into jay/UIRefactor

Signed-off-by: default avatarJay Jay Billings <>
parents a6cac0aa f7e31c74
File deleted
<?xml version="1.0" encoding="UTF-8"?>
#TeXlipse project settings
#Thu Feb 04 13:36:18 EST 2016
%%This is a very basic article template.
%%There is just one section and two subsections.
\section{Editing Meshes}
This document is designed to outline the basic user controls of the Mesh Editor plugin in ICE.
\subsection{Getting Started}
Once ICE is installed on your system, there are no addional dependencies or
preparation required to use the Mesh Editor.
\subsubsection{Opening a Mesh Editor}
To open a Mesh Editor in ICE, you have four options:
The UI elements which can be used to open a Mesh Editor are
highlighted. Instruction for how to use each one, from top to bottom, left to
right, are given below.
1) Click the File menu, then New, then Create Item Wizard.
2) Click the New Item Button and select Create Item Wizard.
3) Click the Mesh Editor button.
4) In the ICE Perspective, click the Create an Item button, select Mesh Editor,
and click OK.
\section{Working With the Mesh Editor}
The mesh editor will initially open to an empty grid, as shown below. There is
currently no way to import pre-existing meshes from another source directly
into the Mesh Editor.
Meshes are constructed on the background grid. Gridlines are spaced one unit
apart from each other. The origin is the initial center of the screen, with the
x axis in red and the y axis in green coming out from it in the positive x and y
directions, respectively.
\subsubsection{Camera Controls}
The camera is controlled with keyboard and mouse commands. The W, A, S, and D
keys are used to move the camera around the editor's area, while scrolling the
mouse wheel is used to zoom the camera in and out.
If the controls are not working, ensure that the Mesh Editor has focus by
clicking inside of it.
\begin{tabular}{| l | l |}
\multicolumn{2}{|c|}{\textbf{Camera Controls}} \\
\textbf{Action} & \textbf{Key(s)} \\ \hline
Scroll Up & W \\ \hline
Scroll Down & S \\ \hline
Scroll Left & A \\ \hline
Scroll Right & D \\ \hline
Zoom In & Scroll mouse wheel up \\ \hline
Zoom out & Scroll mouse wheel down \\
\subsection{Adding Elements}
2D meshes are constructed in the editor by specifying one quadtrilatiral at a
time. To add a new polygon, the Mesh Editor must be in Add Elements Mode. This
is the editor's default setting, and it can later be reset by clicking the Mode
button in the top left corner.
\subsubsection{Placing Vertices}
In Add Elements Mode, clicking anywhere on the grid will place a new vertex at
that location. These new, temporary vertices and the edges between them will be
colored in green, to show that the polygon in still under construction.
Alternatively, you may select a vertex not already in the new polygon. This
allows you to reuse vertices and/or edges already present in the mesh to form
part of your new polygon.
\caption{One of the edges from the trapezoid is being combined with a new edge
in the creation of the current polygon.}
Once the fourth vertex has been specified, the polygon will change to purple to
show that it has been completed. At any time before this, you can press the Esc
button to cancel the new polygon, removing it from the editor and allowing you
to start the process over.
\subsection{Editing Elements}
To edit an already present element of the mesh, you must switch to Edit Elements
Mode. The Mode button in the upper left corner alows you to switch between
modes, as shown below.
A vertex can be selected by either clicking it in the Mesh Editor, or by
selecting it from the tree in the ICE Perspective's Mesh Elements View. Holding
down shift while clicking will allow multiple vertices to be selected at once,
while holding down control during a click will toggle a vertex's state either
into or out of the selection. Selected elements are displayed in blue.
The current selection can be cleared by pressing the Esc button.
Click on a selected vertex and drag it to change its location. The clicked
vertex will stay beneath your mouse cursor, while all other selected vertices
will be moved as well, keeping their relative position to the dragged vertex.
White circles are displayed to show each vertex's new location. Pressing Escape
during the drag will deselect the vertices and cancel the movement.
\caption{Two vertices are selected. When the bottom vertex is moved left, the
top vertex is moved left by an equal amount.}
\begin{tabular}{| l | l |}
\multicolumn{2}{|c|}{\textbf{Edit Mode Controls}} \\
\textbf{Action} & \textbf{Key(s)} \\ \hline
Select vertex & Left click \\ \hline
Add to selection & Shift + left click \\ \hline
Toggle (Add/Remove) Selection & Ctrl + left click \\ \hline
Move selected vertices & Left click on vertex and drag mouse \\ \hline
Clear selection/Cancel move & Escape \\
Alternatively, you can edit a vertex more precisely by setting its exact
coordinates. First, select it in the Mesh Elements view, then open the
Properties View. The vertex's x and y coordinates will be displayed in editable
text boxes.
Selecting a polygon in the same way, then opening the tab for one of its edges
in the Properties View, will display the edge's boundary conditions for that
polygon. These are editable, just like the vertices are.
\subsection{Deleting Elements}
Polygons in the mesh can be deleted. All four vertices for the polygon must be
selected, then press the Delete button on the toolbar. Vertices and edges which
are still part of other, undeleted, polygons will remain, but all others will be
removed from the editor.
\subsection{Additional Controls}
The Toggle Axis button on the toolbar allows will add/remove the axes from the
\title{Visualizing Output}
Currently, ICE features two plugins for visualizing and plotting simulation
output data:
\textbf{VisIt Tools} - An interactive 3D visualization tool for rendering
meshes, scalar plots, contour plots, and more.
\textbf{CSV Plotting Tools} - A customizable, 2D data plotting utility for data
from .csv files.
\section{Installation and Configuration}
The CSV Plotting Tools require no additional software or preparation before use.
The VisIt Tools need both an instance of VisIt and a connection between ICE and
the VisIt session.
\subsection{VisIt Installation}
Before preparing ICE,
\href{}{VisIt}, developed
by Lawrence Livermore National Laboratory, must be downloaded. This must be
version 2.8.2 or higher, and does not need to be on the same machine that ICE is
installed on, as ICE is capable of launching a VisIt session on a remote machine. Make
note of the folder where you installed VisIt for use in the next step.
\subsection{Configuring the VisIt Connection}
Once VisIt is installed, ICE must connect to a VisIt session in order to provide
data visualization. There are two different parts of ICE which connect with
VisIt, both providing slightly different functionalities. These are the Plot
Editor, which is slightly more user friendly, and the Visualization Perspective,
which allows for arbitrary Python commands to be sent to the VisIt client.
\subsubsection{Connecting for the Plot Editor}
This process will set up a default connection to VisIt in the ICE Preferences
page, and so only needs to be performed once. After creating the connection, ICE
will launch and connect with VisIt each time it is started.
To set the connection, select Window $\rightarrow$ Preferences in ICE's
toolbar. (If you are using Mac OSx, this will instead be located at Eclipse
$\rightarrow$ Preferences.) Then select Visualization $\rightarrow$ VisIt in the
tree of the Preferences page.
Press the new row button, the button with a "+" symbol in the upper right,
highlighted in the image above. You can then click on each of the cells of the
new row to edit them. The default values automatically supplied by ICE should
be fine for most users. However, two fields may need to be changed:
\textbf{Host:} The default value of "localhost" is for connections to local
installations of VisIt on your computer. If you want to launch a remote VisIt
connection, you must change this to the hostname of the machine to connect to.
\textbf{Path:} You need to put the full path to the VisIt folder here. The path
should end with the folder containing the VisIt executable. For example, if
VisIt.exe is in a folder called VisIt 2.9.1, the the path should end in
\textbackslash{}VisIt 2.9.1\textbackslash , not \textbackslash{}VisIt
2.9.1\textbackslash VisIt.exe.
Once finished, press Apply, then OK. ICE will then open VisIt and connect to it.
\subsubsection{Connecting for the Visualization Perspective}
First, open the Visualization perspective. On the main menu bar at the top of
the window, click Window $\rightarrow$ Perspective $\rightarrow$ Open
Perspective $\rightarrow$ Other\ldots, select Visualization in the dialog that pops up and click OK.
Alternatively, you can also access the same pop-up dialog by clicking the Open Perspective button in
the main toolbar in the upper right-hand corner of the ICE workbench.
Now click the Launch VisIt button in the menu bar.
This will open a dialog offering you three options for connecting to VisIt.
\textbf{1) Launch VisIt locally -} If you installed VisIt on your local machine,
use the Browse button to direct ICE to your local installation directory. Using this
method of connecting will launch a new VisIt session. Optionally, you can also
set a port number (default 9600) and--if you want to share your VisIt session
with another user--a password.
\textbf{2) Launch VisIt remotely -} If you installed VisIt on a remote machine,
specify the hostname and full path to the VisIt installation directory. Using this
method of connecting will launch a new VisIt session. Optionally, you can
specify a port number (default 9600) and--if you want to share your VisIt
session with another user--a password. If you need or want to use an external
gateway or proxy to access the remote VisIt installation, you may specify its
URL and port number as well.
\textbf{3) Connect to VisIt -} If you would like to connect to a session of VisIt
already running somewhere else, specify the hostname, port number, and password set on
the VisIt session; you will need to obtain this information from the person who
initially launched the VisIt session. If you need or want to use an external
gateway or proxy to access the remote VisIt installation, you may specify its
URL and port number as well.
If you've forgotten where VisIt is installed on Windows, find a shortcut to
VisIt either on your desktop or in the start menu. Right-click the shortcut and
open its Properties. The path to the VisIt executable's directoy will be shown
next to Target.
Regardless of which method you choose to connect to VisIt, enter a Connection
name at the bottom of the pop-up dialog.
If you are connecting to an existing session, specify a Window ID between 1 and
16. Which Window ID you use depends on how you would like to connect to VisIt.
If multiple users connect using the same Window ID, they will all see and be
able to interact with the same VisIt view. However, if you would like multiple
users to each have their own unique session each with its own controls, assign a
unique Window ID to each user. The VisIt installation can support up to 16
unique window IDs at a time.
Once you are done, click the Finish button at the bottom, and ICE should begin
connecting to VisIt.
\subsection{Opening a VisIt File}
\subsubsection{Opening a Plot Editor}
To open a plot editor, first the file must be placed in the Project Explorer.
This view lists files imported into ICE. To access the Project Explorer, use the
the main menu bar at the top of the window and navigate to Window $\rightarrow$
Show View $\rightarrow$ Project Explorer.
By default, the Project Explorer should automatically import the
ICEFiles/default and ICEFiles/itemDB folders. If it does not, or it you want to
import a different folder into ICE, right click in the Project Explorer and
select Import... from the context menu. Then select General $\rightarrow$ File
System from the tree and press the Next button. You can then select directories
and/or files to import into the Project Explorer and which folder they should be
imported under, as seen below.
Once a file is in the Project Explorer, you can simply double click on it to
open it in VisIt.
\subsubsection{Opening in the Visualization Perspective}
To open a file in the Visualization Perspective, it must first be imported into
the Visualization File Viewer, located in the upper left of the screen. To do
this, click the Open a File button, with a green plus sign icon. This will open
a dialog to let you select a local file to import.
Currently, ICE can only open files in VisIt on the same machine as that VisIt
session is running. If you are connected to a remote VisIt installation, you
will instead need to click the arrow beside the Open a File button and select
``Add a remote file'' from the drop down menu. This will open a dialog box to
browse the file system of the remote machine VisIt is hosted on, which can be
used to select a file as normal.
Once your file is in the Visualization File Viewer, you will need to create a
plot from it. To do this, select the file and then click the Add a Plot to the
List button located in the VisIt Plot Viewer on the left of the screen. A window
will open, prompting you to select which plots from the file you would like
to view. After you have made your selection and hit OK, these plots will be
placed in the VisIt Plot Viewer.
Finally, you may double click a plot in the VisIt Plot Viewer to open that plot
in VisIt.
\subsection{Using VisIt}
Both methods of accessing VisIt allow the user to rotate the model by clicking
and dragging inside the display area or zoom it by scrolling the mouse wheel.
Other commands require slightly different actions between the two.
\subsubsection{Selecting the Plot}
In the Plot Editor, pressing the Select Series\ldots button will open a dialog
which lists the various plots in the opened file. Simply select one and click OK
to open it.
In the Visualization Perspective, the opened plots will be listed in the VisIt
Plot Viewer. Double click on one to open it.
\subsubsection{Setting the Plot Representation}
VisIt is capable of displaying plots in several different representations, such
as pseudocolor, contour, or volume.
To switch between these in the Plot Editor, right click inside the display area
and select one of the listed options under the Representation category in the
context menu.
The Visualization Perspective features a drop down menu at the top of the VisIt
Plot Viewer which allows for switching between the available representations.
\subsubsection{Animation and Time Data}
The Plot Editor features a time slider widget at the bottom of the screen.
The controls, in order of left to right, are:
1) Return to the previous time step.
2) Automatically play the plot as an animation by displaying the time steps
3) Advance to the next time step.
4) Opens an options menu that allows the user to set the playback speed, toggle
whether the animation should loop when it reaches the end, and set the plot to
the first or last time step.
5) A display for the current time step. It can be edited to set the plot to an
arbitrary time step.
6) A slider that shows the current time step's position on the timeline. The
slider can be dragged around the timeline, setting the plot's time step
In the Visualization Perspective, the Visit Plot Viewer has a similiar set of
The buttons, in order of left to right, are:
1) Return to the previous time step.
2) Automatically play the plot as an animation backwards, going through the time
steps in reverse order.
3) Pause the animation.
4) Automatically play the plot as an animation by displaying the time steps
5) Advance to the next time step.
\subsubsection{Sending VisIt Python Commands}
This functionality is only available in the Visualization Perspective.
The Execute Python Script button in the upper right of the VisIt Plot Viewer
will open a new window with a Python shell. Commands entered into this shell
will be sent to the instance of VisIt.
Python code can be written into the shell directly, but the Load from File
button will import an existing .py script into the console. Once done, hit the
Execute button to send the python command(s) to VisIt.
Writing Python scripts for VisIt is beyond the scope of this tutorial. However,
you are welcome to refer to the
\href{}{VisIt Python
Interface Manual} provided by the VisIt development team at Lawrence Livermore
National Laboratory.
\section{CSV Plot Viewer}
ICE offers functionality for the viewing of CSV files.
\subsection{Opening a CSV File}
CSV files are opened in Plot Editors through the Project Explorer. Open the
Project Explorer with Window $\rightarrow$ Show View $\rightarrow$ Project
Explorer and import the file by right clicking and selecting import. Once the
file is in the Project Explorer, double click to open it.
ICE expects CSV files to be in an [m x n] format, with no row holding empty
values. The first row in the file will be used to name a series, with the series
data being specified by the column of values beneath it.
\subsection{Using the CSV Plot Viewer}
\subsubsection{Controlling the Graphics}
The row of buttons at the top of the viewer provide basic graph editing
The first button allows the user to edit a variety of basic graph attributes,
such as font, axis titles and scales, line colors, etc.
The next two buttons allow for the addition and removal of annotations for
specific data points.
The central grouping of buttons allow the user to zoom and pan the camera in a
variety of ways.
The two yellow arrow buttons will undo/redo changes made to the graph.
The final button will export a screenshot of the graph.
\subsubsection{Setting the Independent Series}
By default, the first column in the file will serve as the independent series
setting the graph's x axis. By right clicking the Plot Viewer and selecting Set
Independent Series\ldots you can replace it with any other series in the file.
\subsubsection{Setting the Dependent Series}
When first opened, only the series defined by the second column in the file will
be displayed. There are several ways to change this.
The Select Series\ldots button in the upper lefthand corer will display a list
of all the series in the file. Selecting one and pressing OK will graph that
series and removing all others.
Right clicking and choosing Select series\ldots from the context menu will open
a dialog in which any of the series will be selected. All selected series will
be graphed at once, with deselected series removed.
Finally, the Remove all series option in the context menu will completely clear
the graph.
\section{MOOSE Embedded Visualization}