skeleton

1. Get started by creating a Microstructure.

Locate the file small.ppm within the share/oof2/examples directory in your OOF2 installation.

Open the Microstructure page and click New from Image File to create a new microstructure.

In the file selection dialog box, navigate to small.ppm.

Click OK to load the Image and create the Microstructure.

2. The micrograph features eight distinct colors, each corresponding exactly to a microstructural
feature. Since the correspondence between colors and features is trivial, we can group pixels
automatically.

Open the Image page and click the Group button.

Go back to the Microstructure page and you will see that 8 pixel groups have been created for the
microstructure.

3. Now, open the Skeleton page, where we will spend most of the time in this tutorial.

The page is comprised of three parts.

The top part contains a Skeleton Selector and administrative features. The Skeleton Selector is the
two pull-down menus labelled Microstructure and Skeleton. The first lets you choose a
Microstructure and the second lets you choose a Skeleton belonging to that Microstructure.

The Skeleton Status pane on the left is a display for Skeleton summary data such as number of
nodes and elements.

The Skeleton Modification pane on the right contains a bunch of skeleton modification tools that we
will use to adapt a Skeleton to the material boundaries in its Microstructure.

4. Click New... to create an initial skeleton.

As in other cases, to give a skeleton a user-defined name, check the little square box and type in a
name of your liking.

The number of elements in the initial skeleton can be set with the parameters, x_elements and
y_elements.

You can choose the element shape with the skeleton_geometry parameter.

For this tutorial, just use the default values for the initial skeleton: x_elements=4, y_elements=4,
and skeleton_geometry=QuadSkeleton.

Click OK to create the Skeleton.

5. Open a Graphics window if you haven't already. It should be showing the skeleton on top of the
micrograph.

For a Skeleton to be a good representation of a Microstructure, the Elements in the Skeleton must
not cross boundaries between different pixel types. Two pixels are defined to have the same type if
they have the same Material assigned to them and if they belong to the same pixel groups. Since we
haven't assigned Materials yet, and since we've assigned groups according to pixel color, in this
tutorial pixel color is synonymous with pixel type.

Except for one yellow element at the top-right corner of the skeleton, all the elements are
heterogeneous, meaning that these elements contain pixels of two or more pixel types.

We want every element to be as homogeneous as possible.

6. Let us subdivide these heterogeneous elements as the first step towards making them
homogeneous.

In the Skeleton Modification pane in the Skeleton page, set the method pull-down menu to Refine.

Four parameters need to be set.

The parameter targets determines which elements should be refined. Select Heterogeneous
Elements and set its threshold to be 1.0, meaning any heterogeneous elements will be refined. (All
elements with a homogeneity less than 1.0 will be refined. The homogeneity is the largest fraction
of an element's area belonging to a single pixel type.)

The second parameter criterion determines whether to accept or reject the resulting refinement.
Select Unconditional.

The parameter degree controls the degree of subdivision. It specifies into how many segments each
edge of an element will be divided.

Each refinement degree has a parameter rule_set that contains two options. The conservative
rule_set preserves the topology of the target element. That is, if you refine a quadrilateral, you'll get
only quadrilaterals, whenever possible. The liberal rule_set may mix triangles and quadrilaterals, if
the mix yields a better result.

Choose Trisection and conservative for its rule_set.

Finally, the parameter alpha determines how elements are refined when there are two or more
possibilities. When alpha is near zero, oof2 chooses the arrangement that produces elements with
the best shapes. When alpha is near one, it tries to make the elements as homogeneous as possible.
Set alpha to 0.5.

Click OK to refine the Skeleton.

7. The refined skeleton should be displayed in the graphics window.

Every element (except one in the top-right corner) has been divided into 9 elements. As a result, a
larger fraction of the Microstructure's area is covered by homogeneous elements.

At the bottom of the Skeleton Status pane in the Skeleton page, there is a Homogeneity Index. This
number indicates the homogeneity of the entire skeleton.

As the skeleton becomes more homogeneous and adapts to material boundaries, the Homogeneity
Index gets closer to 1.

Click Undo and Redo, while checking out Homogeneity Index.

The number has been increased from 0.7305 to 0.8726.

8. We're still one more Refine away from being satisfied.

This time, leave targets set to Heterogeneous Elements and set threshold to 0.9, so that only
elements less than 90% homogeneous will be refined.

Click OK to start refining.

9. The Skeleton looks okay -- no material boundary is very far from an element boundary -- but the
element boundaries don't really coincide with the material boundaries. More work is necessary.

At this point, more refinements may not yield a favorable result.

You don't want to refine a skeleton to the point where it inevitably inherits the jagged pixel
boundaries of the micrograph.

Thus, we need a different approach to resolve issues with the elements near the material boundaries.

10.While refinement is more of a chop-and-hope-for-the-best approach to the heterogeneity issue,

the node motion tools deal with the issue directly.

OOF2 provides three different methods of moving nodes in adapting to material boundaries -- Snap
Nodes, Anneal, and Move Nodes.

Snap Nodes first looks for boundary points -- intersections between material boundaries and
element edges -- and moves nodes to the corresponding points, if the result is favorable.

Anneal, on the other hand, moves nodes to randomly chosen points and accepts only the ones that
are beneficial.

The Move Nodes toolbox in the Graphics window allows you to move nodes manually.
11. Select the Snap Nodes method in the Skeleton Modification pane in the Skeleton page.

This tool will move nodes of target elements to the material boundary points along the edges of the
elements.

Select Heterogeneous Elements for the targets parameter and set the threshold to be 0.9, meaning it
will attempt to move nodes of elements with homogeneity less than 0.9.

12. For the criterion parameter, select Average Energy and set its parameter alpha to be 1.

The quality of a Skeleton element is quantified by a functional, E, which is called an "energy"

because of its role in the Skeleton annealing process. E ranges from 0 for good elements to 1 for
bad elements. There are two contributions to E: a shape energy, which is minimized for squares and
equilateral triangles; and a homogeneity energy, which is minimized for completely homogeneous
elements. The parameter alpha governs the relative weight of these two terms. alpha=0 gives all
the weight to the shape energy, while alpha=1 ignores shape and emphasizes homogeneity.

By setting alpha=1, we've told the Snap Nodes tool that it's ok if moving a node creates badly
shaped elements, as long as doing so makes them more homogeneous. (We'll fix the bad shapes
next.)

Click OK to make changes. The Homogeneity Index increases from 0.957 to 0.989.

13. Because Snap Nodes considered only homogeneity, some elements have been badly distorted
while adapting themselves to the material boundaries.

Select the Skeleton Modification method to Rationalize.

This modification tool automatically removes badly shaped elements, provided the changes meet a
certain criterion.

Set targets to All Elements.

Set criterion to Average Energy and set alpha to 0.8. With this setting, the Rationalize tool will only
make changes that lower the average energy E of the affected elements. alpha determines how E is
computed.

For the method parameter, select Specified.

Three rationalization techniques are listed. Move the mouse pointer over each technique to get
more information about it. Make sure all three are selected and click OK, while keeping the default
values for their parameters.

The summary for the modification is displayed in the OOF Messages window. Also, in the graphics
window, you will notice that many of the badly shaped elements are gone.
14. Open the Skeleton Selection page in the main OOF2 window. This page provides tools for
selecting Skeleton components -- elements, segments, and nodes -- and for manipulating groups of
them.

Set Selection Mode to Elements.

From the Element Selection Operations pane in the right side of the page, select Select By
Homogeneity for the parameter Action and set its threshold to be 0.9, to select all elements less than
90% homogeneous.

We will apply the next modification only to the selected elements.

Now, click OK to make a selection.

15. Return to the Skeleton page and select Split Quads for the modification method. This tool
splits target quadrilaterals into two triangles. A split is accepted only if it meets a specified
criterion.

Select Selected Elements for the parameter targets.

Set criterion to be Average Energy with alpha=0.9.

A quadrilateral element can be split along either of its two diagonals. The split_how parameter
determines how OOF2 decides which diagonal to choose. Geographic examines the element's
neighbors to see if it's likely that there's a material boundary crossing the target element on a
diagonal. TrialAndError splits a quadrilateral along the both diagonals and chooses the better of the
two. Set split_how to Geographic.

Click OK to modify the skeleton.

16. A handful of quadrilaterals have been split, but some badly shaped triangles were generated.

Select Rationalize and apply it to the Skeleton with the same settings as before.

17. Go back to the Skeleton Selection page and again select elements by homogeneity with the
threshold set to 0.9.

Notice the reduced number of selected elements.

18. Return to the Skeleton page and select Anneal for the modification method. Anneal moves
nodes randomly and accepts or rejects the new positions according to the given criterion. On each
iteration, Anneal attempts to move each node once, but it chooses the nodes in a random order.

Select Selected Elements for its targets, meaning it will attempt to move nodes of the selected
elements only.
For criterion, select Average Energy with alpha of 0.9.

Set T to be 0.0 and also set delta to be 1.0. Move the mouse over these parameters to get more
information.

For iteration, select Conditional Iteration, which stops annealing when certain conditions are met.
Set condition to Acceptance Rate, and set the acceptanceRate parameter to 7. This will terminate
the annealing procedure if it starts accepting fewer than 7% of the attempted moves.

Set extra to 3, to require that the condition be satisfied for three consecutive iterations before
actually terminating the procedure.

Leave maximum set to 100, setting an absolute limit on the number of iterations.

Click OK.

Watch the Message and Graphics windows to monitor the progress.

19. If you recall, we set alpha to 0.9 during the anneal. This put a strong emphasis on homogeneity,
thus many elements may have been distorted severely.

Select Rationalize for the modification method and click OK.

20. Open the Skeleton Selection page and select elements by homogeneity with threshold = 0.9.

You will notice that the number of elements selected is significantly reduced.

21. Return to Skeleton page and do the Anneal one more time with the same settings as before.

22. Again, we need to Rationalize the skeleton before we move on to the next step.

Use the same settings as before.

23. Open the Skeleton Selection page and select elements by homogeneity with the threshold being
0.9.

There should be very few elements selected. (Because of randomness in some modification
methods, your results may vary.)

Set the threshold to be 0.8 and click OK.

There should be very few elements selected, meaning that most of the elements have been adapted
to the material boundaries successfully.
24. Move back to the Skeleton page and check the Homogeneity Index.

It should be almost 1, which implies the skeleton is nearly homogeneous.

We'll now turn our attention to elements' quality, more precisely, their shape.

The tools for improving the skeleton's quality include Swap Edges, Merge Triangles, and Smooth.

These tools, however, can potentially affect material boundaries that have been established already.
Thus, we need to be extra careful not to disturb the existing boundaries. The best way to avoid this
potentially sorry situation is to pin down all the nodes along the boundaries.

The next slide will teach you how to do this.

25. Go to the Pin Nodes page.

In the pull-down menu labelled Method, Select Pin Internal Boundary Nodes. Click OK.

All the nodes along the boundaries should be selected and displayed as yellow dots.

These nodes are not going to move at all, until they are unpinned.

26. Go back to the Skeleton page in the OOF2 main window and select Swap Edges for the
modification method. This takes any two neighboring elements and reorients their shared edge.

A swapped edge is accepted only when it meets a certain criterion.

Select All Elements for targets.

Select Average Energy for criterion.

Set alpha to 0.5, putting equal emphasis on shape and homogeneity.

Click OK to swap edges.

Try Undo-Redo to see the changes wrought by the edge swap.

Also, it is a good idea to Rationalize the skeleton to remove potential bad elements created by the
swap.

27. In addition to Swap Edges, you can merge two neighboring triangles into a quadrilateral.

Select Merge Triangles for the modification method.

Select All Elements for targets and select Limited Unconditional for criterion.

Set alpha to 0.5, homogeneity to 0.9, and shape_energy to 0.4.

By doing this, you're accepting any changes, unless they produce elements for which the
homogeneity drops below the specified value or the shape energy goes above the specified value.

Click OK to merge triangles.

Again, use Undo-Redo to see the changes better.

28. We're going to give the skeleton finishing touches by applying Smooth. Smooth works much
like Anneal, except that instead of picking node positions randomly, it moves each node to the
average position of its neighbors.

Select Smooth for the modification method.

Select All Nodes for targets.

Select Limited Unconditional for criterion and set its parameters alpha to 0.5, homogeneity to 0.9,
and shape_energy to 0.4.

Select Fixed Iterations for iteration. Set the number of iterations to 5.

Click OK.

Updates are reported in the same way as in Anneal.

29. The Save/Skeleton command in the File menu in the main OOF2 window, and the Save button
on the Skeleton page both allow you to save Skeletons to a file.

The format parameter in the file selector dialog box was discussed in the Microstructure tutorial.

When you save a Skeleton, its Microstructure is saved with it in the data file. Loading the data file
with the Load/Data or Load/Script commands from the File menu restores both the Microstructure
and the Skeleton.

30. You must like what you see in the graphics window. Anyway, we have covered most of the
issues related to Skeleton modifications.

Related topics not covered in this tutorial include Active Areas, and the Move Node toolbox.