OOF2 Tutorial: Red-Blue


Our microstructure shall be based on the following image by 
M. T. Gastner, C. R. Shalizi, and M. E. J. Newman

Let us assign elastic constants and different coefficients of thermal
expansion to the red, blue and white regions, in such a way that the
blue regions expand while the red regions contract when we apply a 
temperature gradient from top to bottom.
At the end of the tutorial, we should get something like the following:

(The initial grid is 30x20. We shall tell oof2 to assign a material
color of green to the white regions. The white spots in this image are
elements with no material assigned to them), and without the mesh:

  1. Loading the image
  2. Viewing the image
  3. Constructing Pixel Groups
  4. Defining material properties
  5. Creating and refining a skeleton
  6. Creating a mesh
  7. Specifying fields and equations
  8. Specifying boundary conditions
  9. Engaging the solver
  10. Viewing the results
  11. Saving your work

Loading the image

The first step is to load the image into oof2. The image is available at
Download and save this image onto disk.

Now run oof2 and go to the Microstructure Task page in the main oof2 window:

Click "New from Image File", find and select the image, then load
and create the microstructure (by clicking "OK"):

(We let the physical size be the same as the dimension in pixels by not
entering values into "width" and "height".)
After this step, you will see some of the buttons have become active.
The Microstructure Info box on the left side of the Microstructure Task
page will also tell you the pixel dimensions and physical size of the image.

Viewing the image

Locate the "Windows" menu (part of the "File Settings Windows" triumvirate)
at the top of the main oof2 window. Select "Graphics" from the popup and
click "New". The following should show up:

(The keystroke combination Ctrl+G can also do this, as you might have noticed
just before you clicked "New".)

One can probe the microstructure/image for pixel information and other
bits of information by using the mouse and clicking on the image.
The kind of information you get, as well as some types of operations one can
perform on the image, may be changed by selecting items in the Toolbox
menu, located at the top of the left pane of the Graphics window.
For instance, select "Pixel Info" on the Toolbox list. You get something
like the following:

Here, the RGB values show (1.0, 0.0, 0.0) because a red region has
been clicked. It also says that "No material" is currently assigned.

You can change the size of the Graphics window by clicking and dragging
at the edges of the window. Similarly, the relative sizes of the panes
can be adjusted by clicking and dragging at the boundaries between
the panes. The image itself may be enlarged/shrunk by selecting
"Settings" at the top of the Graphics window and playing with "Zoom".

Constructing Pixel Groups

The goal of categorizing pixels into groups is to build a small set
of 'targets' to which material properties can be assigned.

In your Graphics window, select "Pixel Selection" for your Toolbox.
Under Toolbox, there are several "Method"'s available.
"Point" for example, lets you select individual pixels, while "Circle"
or "Rectangle" lets you select circular or rectangular regions in the image. 
Since our image contains large regions with a single color but with irregular
boundaries, it is recommended that we use the "Burn" or "Color" tool.

Let us illustrate the use of the "Burn" tool to select the blue regions.
Select "Burn" for our Method. Placing the mouse pointer over
the menu for "Burn" reveals a tooltip (Mine says "Select a contiguous set
of similar pixels, using a forest fire algorithm". Most menus and buttons
have tooltips).

Now click on any blue region (say California to the west).
The color changes to some shade of purple:

The box beside "Selection size" at the bottom of the left pane displays
the number of pixels selected.

Clicking on another region selects that region and deselects
the previous one (if the two regions are not contiguous). To select
multiple regions, (you guessed it) hold down the "Ctrl" key.

Now select all the blue regions this way (from California in the west,
through the Great Lakes/Midwestern states, to Maine in the east. It may be
helpful to zoom in or magnify the image):

If you make a mistake, don't worry. There are "Undo" and "Redo" buttons
on the left pane. To clear all the selections, use the "Clear" button.

With all (or most) of the blue regions selected, let us go back to the
Microstructure Task page in the main oof2 window.
In the Pixel Groups pane, click "New...". When presented with a dialog
box, check the box beside "name" and type in "bluegroup":

Click "OK". The result is:

There are currently 0 pixels in this group. Click "Add" to
add the pixels of the selected blue regions into this group:

The right pane now displays a non-zero number (mine is "40377 pixels").

Now let us use the "Color" tool to select the white regions.
Don't forget to clear any previous selections.
Select "Color" for the Method. The "Color" tooltip says "Select pixels
whose color is close to that of a reference pixel."
Click on a white region close to any red or blue region (say a point just off
the coast of Florida). You should get the following picture:

Create a pixel group ("whitegroup") and add the selected pixels to the
pixel group, as we did with the blue pixels. Make sure the correct group name
is selected in the Pixel Groups pane.

Now go through the same steps in selecting the red regions (spanning fom
Virginia in the east, across the heartland, to Nevada in the west)
and constructing a pixel group ("redgroup") for it:

Due to the color scheme, the selected red regions might not be obvious,
but "Selection size" does indeed register the number of pixels selected.

At the end of this process, you might get the following result:

(optional) Before we continue...

Athough the actual image is rectangular, the surrounding white region 
in the image blends with the white background of the Graphics window.
If you feel uncomfortable with this, you could set the background to
a different color, say black, by going back to the Graphics window,
then clicking on "Settings" - "Color" - "Background...":

oof2 also furnishes methods for "massaging" the image. In the main oof2 window,
select the Image Task page. A host of Image Modification tools are available,
such as converting an image to Gray scale, Edge detection, Normalization
and Contrast, etc.

Finally, there are additional Pixel Selection Modification tools available.
This can be accessed in the main oof2 window's Pixel Selection Task page.
One of these methods is "Despeckle" (and its opposite "Elkcepsed"), 
which the tooltip describes as "Recursively select all pixels with a
minimum number of selected neighbors. This fills in small holes in the

At this point, we hope you learned how to use oof2 to load an image
and create a microstructure, view the image and probe some of its properties,
and select pixels and build pixel groups.
The next steps would involve the following:

Defining material properties

This is where we assign elastic constants and coefficients of thermal
expansion to the desired regions in the microstructure. We shall
arbitrarily specify the following properties:
Region Color Young/Poisson Thermal Conductivity Thermal Expansion
red RGB(1,0,0) 0.6666,0.3333 1.0 -1.0
blue RGB(0,0,1) 0.6666,0.3333 1.0 1.0
white RGB(0,1,0) 0.6666,0.3333 1.0 0.0
The elastic moduli and thermal conductivities are the same for all three regions. The Color property enables us to assign a different color to the pixels in the microstructure (Yes, we are assigning RGB(0,1,0)=green to the white regions, but you can choose not to go along.) This task is handled in the main oof2 window's Materials Task page: The main idea is to collect, under one material name, the various relevant properties. The material is then assigned to a pixel group. Let us start by creating material names. Click "New..." in the Material pane, out comes a small dialog box, check the box beside "name", and type in "redmaterial". Likewise, create "bluematerial" and "whitematerial". These steps add "redmaterial", "bluematerial" and "whitematerial" to the list box in the Material pane: Now let us define the properties to be added to the materials. The properties we are interested in will be based on the following prototype properties: These appear in the treeview of the Property pane (click on the tiny triangles to expand/contract the tree stems): For example, to create a new Mechanical-Elasticity-Isotropic property, first select the leaf "Isotropic", then click the "Copy..." button in the Property pane. Give the property the name "YoungPoisson" (we plan to give this same property to all materials): Now select "YoungPoisson", and click "Parametrize..." (double clicking on "YoungPoisson" also brings up the same window). The choices in the list box are "Cij", "Lame", "E and nu", and "Bulk and Shear". Select the item "E and nu": Change the values into something like young=0.6666 and poisson=0.3333, if they aren't already. Click "OK". Go through the same process when creating the following properties:
name copy from prototype values
redcolor Color RGBColor=(1,0,0)
bluecolor Color RGBColor=(0,0,1)
greencolor Color RGBColor=(0,1,0)
k Thermal - Conductivity - Isotropic kappa=1.0
redalpha Couplings - Thermal Expansion - Isotropic alpha=-1.0,T0=0.0
bluealpha Couplings - Thermal Expansion - Isotropic alpha=1.0,T0=0.0
whitealpha Couplings - Thermal Expansion - Isotropic alpha=0.0,T0=0.0
Now we are ready to attach properties to a material name. To add properties to a material, say "redmaterial", make sure "redmaterial" is selected in the Material pane. Select the property on the Property pane, say "redalpha", and click the button "Add Property to Material". The result: Add the rest of the properties for "redmaterial" ("redcolor","k", "YoungPoisson"). Likewise, add properties to "bluematerial" and "whitematerial". To summarize:
material name properties
redmaterial redcolor,YoungPoisson,k,redalpha
bluematerial bluecolor,YoungPoisson,k,bluealpha
whitematerial greencolor,YoungPoisson,k,whitealpha
When this is done, assign materials to Pixel Groups by clicking "Assign Material to Pixels...". For example, with "redmaterial" currently selected in the Material pane, select pixels=redgroup: Click "OK". Do the same for "bluematerial" (bluegroup) and "whitematerial" (whitegroup). Congratulations! You have now infused some material science and physics into the regions of our microstructure. (BTW, you could also assign an Orientation property to a region. This is relevant when a property is Anisotropic. In that case, you could create an orientation called "left" for the blue regions, "right" for the red regions...)

Creating and refining a skeleton

The first step in meshing is to create what in oof2 parlance is called
a skeleton.

Visit the oof2 main window and select the Skeleton Task page:

To create an initial skeleton (or grid), click the "New..." button,
and enter the values shown:

After you click "OK", the skeleton should show up in the Graphics window:

This grid may be too coarse: several elements enclose regions with
different colors, and the boundaries are poorly resolved. To improve
the situation a bit (aside from creating a finer initial skeleton), it is
recommended that you use the Skeleton Modification tools on the Skeleton
Task page. These tools ATTEMPT to refine or subdivide only those elements
that need refining according to a set of criteria. Several methods are 
available ("Refine","Relax","Anneal","Snap Nodes",etc.), and it is a good
idea to play around with these (perhaps later after this tutorial).

In this tutorial, let us use "Refine". Choose
"Refine" in the Skeleton Modification method. Leave the parameters as
they are. (Make the mouse pointer hover above the labels to access
tooltips/descriptions.) Now click "OK", bring up the Graphics window,
and wait...

This looks better. (For example, the white region corresponding to
Lake Michigan, between the blue states of Wisconsin and Michigan,
has a few elements containing only white. The coastlines are also
much better traced by the element edges.)
The degree in which elements of a skeleton fit a microstructure is
quantified by a "Homogeneity Index". Its value is displayed on the
Skeleton Status pane in the Skeleton Task page.

If you are unhappy with the result, you can refine further (and it
is strongly recommended that you avail of the other Skeleton Modification
tools), but the computations on the resulting mesh would take more CPU time.

We can also modify a selected portion of the skeleton. For example,
in the Graphics window, choose "Skeleton Selection" for the Toolbox.
Under "Skeleton Selection", select "Segment" and pick the Method "Rectangle".
Use the mouse to select a portion of the tip of Texas:

Now go back to the Skeleton Task page. For "targets", instead of
"Heterogeneous Elements", select "Selected Segments". Then hit "OK":

The result on the Graphics window is:

We get a finer mesh at the tip.
Click "Undo" on the Skeleton Task page before proceeding to the next section. 

Creating a mesh

Much of the information contained in the mesh is inherited from the skeleton.
What the mesh creation adds are material properties (to the elements) and
(possibly) extra nodes not lying in an element corner.

In this tutorial, let us create a simple mesh with all nodes corresponding
to skeleton nodes. Open the FE Mesh Task page and click the "New..." button.

Leave the mapping and interpolation orders to the value 1, and click "OK":

When you go to the Graphics window, you might not notice anything new.
The mesh layer is on top of the skeleton layer (and both layers are on top
of the image/microstructure), but the skeleton and mesh diagrams look the

To verify that you have indeed created a mesh, visit the Layers pane
located at the bottom of the Graphics window. By unchecking the Skeleton
and Image layers, you are left with the following:

Specifying fields and equations

The properties we have defined relate to temperature and coordinate
displacement, so we should tell oof2 that these are the physical quantities
we are interested in.
These fields are specified in the Fields Task page. Check the boxes
for "Temperature" and "Displacement" (check all of "defined","active",

On the next Task page, the Equations page, check the boxes for "Heat Eqn"
and "Force Balance".

Note that if you want plane stress (plane heat flux) instead of in-plane
for the elasticity problem (thermal problem), you should check
"Plane Stress" ("Plane Heat Flux") in the Equations page and uncheck
"in-plane" for "Displacement" ("Temperature") in the Fields page.

Specifying boundary conditions

The boundary conditions we want to set up are summarized in the following
boundary condition
top T=0.3,uy=0
bottom T=0.6,uy=0
left ux=0
right ux=0
So we are imposing a temperature (T) gradient from top to bottom (it is warmer down south), and constraining the boundaries to remain fixed by setting components of the displacement field (ux,uy) to zero. These boundary conditions are entered into oof2 via the Boundary Conditions Task page: For example, let us enter the boundary condition T=0.3 at the top. Click "New...". Under "Dirichlet" condition, make the following choices: Click "OK". Enter the rest of the boundary conditions as shown: Our Boundary Conditions Task page should end up looking like: At last, we are ready to commence the solution.

Engaging the solver

In the Solver Task page, click "Solve" at the bottom of the page:

The Graphics window should show the following (with all the layers checked):

The window shows the finite element mesh being warped because of the thermal
The next section will illustrate some ways of getting a better picture.

Viewing the results

First, let us make a contour plot of the temperature profile.
Click the "Layer" menu at the top of the Graphics window. In the popup,
select "New...". Out comes the Graphics Layer Editor:

In the Displayed Object pane, under "category", select "Mesh".
Now click the "New..." button in the Display Methods pane. Out comes
the window:

Instead of "Element Edges", select "Filled Contour":

If you are happy with the options, click "OK".
The Graphics window now shows the following:

Notice that a new layer has been added to the Layers list at the bottom
of the Graphics window.

Next, let us see the new positions of the red and blue regions afer the thermal
expansion. We could go through the same steps as with the filled-color
contour map for temperature. Instead, go to the Layers list and double click
on the item that says
"Mesh(mesh)  FilledContourDisplay('Field:Component',component='',field=Temperature)".
This brings up the Graphics Layer Editor. Under Display Methods, click
"Edit...". Instead of "Filled Contour", select "Material Color".
For "where", select "actual":

After you click "OK", look at your Graphics window:

This picture is what was promised at the beginning of the tutorial (albeit
with a slightly coarser mesh). You may select and modify the layers you want
to show to get an even better picture.

The small white spots in the image are regions devoid of a material definition.
These regions are not part of any pixel group. It is possible to go back
and do a more thorough selection of pixels into pixel groups.

Finally, although less visually appealing, one can get more mathematically-
exact results through the Analysis Task page:

The Output pane (upper left) currently specifies "Temperature" for "field",
while the Sampling pane (lower right) specifies sampling of field values
on a 10x10 grid. Leave these as they are, and hit the "Go" button.
This would produce raw numbers that are written to the Messages window
by default:

You may choose instead for the destination to be a file by using the
"New..." button in the Destination pane on the Analysis Task page.

Saving your work

oof2 can not only write and save numerical results and images, but it can also
save (onto a log-file) the sequence of operations and commands you have made
interactively with the GUI.

To save the image shown in the Graphics window, start from the menu "File"
in the Graphics window, then "Save Image...". The image is saved in PDF format.

To save the sequence of operations you have made while working with oof2,
select "File" in the main oof2 window, then "Save", then "Python Log..."
For "playback" of this sequence of operations, you may run oof2 in the
command line as follows:

shellprompt> oof2 --script yourpythonlogfile

or if oof2 is already up and running, select "File", then "Load", then
"Script...", then locate and select your log-file.

You can also save and reload properties, skeleton and mesh construction
information in a manner very similar to that with log-files
(use --data instead of --script).

The End

For your reference, you may obtain an oof2 log-file recreating the steps
described in this tutorial from the URL:
The image used is at:
You may have to change "filename" in the first line of the log-file to point to
the correct location of the image. You may run oof2 and load the log-file by
entering the command: oof2 --script tutorial.log.

Here is also a link to a log-file that does a better job of building and "fitting" a
skeleton onto the microstructure:
The skeleton can also be loaded using the file:
(This file can be loaded into oof2 via the command: oof2 --data tutorialskeleton.skel.
The skeleton file includes the microstructure data, so the image file need
not be present.)
The skeleton looks like:

A combination of Refine, Snap Nodes, Rationalize, Split Quads, Anneal,
Pin Nodes, Swap Edges, Merge Triangles, and Smooth was used to construct the
skeleton. These techniques are described in the hands-on tutorial "Skeleton"
that is accessible in the "Help" menu of the main oof2 window.

There are many features of oof2 that we have not touched upon, but
you do not need to learn everything about oof2 in one sitting. However,
it is hoped that this tutorial supplement would get you started in
applying oof2 to realistic microstructures.

OOF team
Last modified: Mon Aug 21 15:45:48 EDT 2006