[image:42 align:right]
    Mesh of 3D micro-CT data using `ImageFunction`
Phase field simulations often require the phase to be initialized or compared to existing micro-structure data, such as CT or SEM scans as shown in the figure. The phase-field module in MOOSE includes a flexible, [Function](http://mooseframework.org/wiki/MooseSystems/Functions/)-based method for accessing this type of data for use in initial conditions or other calculations.

# Setup
To utilize the image reading portion of the phase-field module VTK must be enabled when building libMesh. If the MOOSE environment package was installed (see [Getting Started](http://mooseframework.org/getting-started/)) this may be easily accomplished by using the following commands:

```
module load advanced_modules
module load vtk-clang
cd ~/projects/moose/scripts
./update_and_rebuild_libmesh.sh --with-vtk-include=$VTKINCLUDE_DIR --with-vtk-lib=$VTKLIB_DIR
```

If you are using a custom build of VTK then the above include and lib directories simply must be altered to use the correct location for your build.

It is also possible to set the `VTK_DIR` environmental variables in your `.bash_profile` with the aforementioned directories, then utilize the `--enable-vtk` flag when running the build script rather including the directories explicitly.

# Getting Started: Single Image 
[image:37 align:right] 
    **Figure 1:** Example image input (example.png).
Consider the simple image show on the right in Figure 1, reading this image is accomplished by including a `ImageFunction` in your input file.

```puppet
[Functions]
  [./my_image]
    type = ImageFunction
    file = example.png
  [../]
[]
```

[image:38 align:right]
    **Figure 2**: Mesh showing initial condition extracted from image in Figure 1.
This function may then be used just like any other function within MOOSE, for example, it may be utilized as an initial condition for a variable.
The following input file syntax would use the function above as an initial condition for the `u` variable and create an initial mesh as shown in Figure 2.

```puppet
[ICs]
  [./u_ic]
    type = FunctionIC
    function = my_image
    variable = u
  [../]
[]
```

The example image shown is 20 by 20 pixels as is the mesh (20 by 20 elements) to which the initial condition is applied. This IS NOT a requirement, in fact the main reason for building the `ImageFunction` object was to enable an arbitrary mesh geometry to be able to sample the image and adapt accordingly.

[image:39 align:right]
     **Figure 3:** Mesh showing initial condition with initial adaptivity extracted from image in Figure 1.

Beginning with a 2 by 2 element mesh and adding the following Adaptivity block, which includes initial adaptivitiy, to the input file results in the mesh shown Figure 3.

```puppet
[Adaptivity]
  max_h_level = 5
  initial_steps = 5
  initial_marker = marker
  [./Indicators]
    [./indicator]
      type = GradientJumpIndicator
      variable = u
    [../]
  [../]
  [./Markers]
    [./marker]
      type = ErrorFractionMarker
      indicator = indicator
      refine = 0.9
    [../]
  [../]
[]
```

# Image Stacks
Image stacks or 3D images (see Supported File Types section for more details) are also supported. For example, consider as set of images named example_00.png, example_01.png, ..., and example_19.png. To read these images the syntax below is used in the `ImageFunction` block.  Again, using this data as an initial condition and using initial adaptivity, as shown above, results in the mesh shown in Figure 4. It is also possible to limit the reader to a set of images using the `file_range` parameter, which may be set to a single value to read a single image or a range (e.g., `file_range = '00 10'`) to read a subset of the images.


[image:40 align:right]
     **Figure 4:** 3D Mesh showing initial condition with initial adaptivity extracted from a stack of images similar to the image in Figure 1. The mesh is cropped in the vertical direction to show the internal structure.

```puppet
[Functions]
  [./my_image]
    type = ImageFunction
    file_base = example_
    file_type = png
  [../]
[]
```

# Image Processing
The [VTK](http://www.vtk.org/) library includes a range of image filters and processing tools, some basic processing tools are included. However, a derivative class could easily be developed to expand upon these capabilities.

Currently, the three types of processing are applied in the order shown below.

## Component
By default, the RGB pixel data is converted into a single greyscale value representing the magnitude. This is accomplished using the [vtkImageMagnitude](http://www.vtk.org/doc/nightly/html/classvtkImageMagnitude.html) class.

It is possible to select a single component rather than using the magnitude by setting the `component` parameter in the input file to a valid component number, which will be 0, 1 or 2 for RGB images.

## Thresholding
Basic thresholding is accomplished using the [vtkImageThreshold](http://www.vtk.org/doc/nightly/html/classvtkImageThreshold.html) class. Thresholding requires three parameters be set in the input file:

- `threshold`: The threshold value to consider.
- `upper_value`: Image data above the threshold are replaced with this value.
- `lower_value`: Image data below the threshold are replaced with this value.

## Shift and Scale
It is possible to shift and scale the image data, this is accomplished using the [vtkImageShiftScale](http://www.vtk.org/doc/nightly/html/classvtkImageShiftScale.html) object. The `shift` input parameter adds the given value to the image data and `scale` input parameter multiplies the image data by the supplied value.

The order of application of the shift and scale are dictated by the VTK object, the documentation states: "Pixels are shifted (a constant value added) and then scaled (multiplied by a scalar)." 

## Image Flipping
Flipping an image along the major axis directions x, y, or z is performed using [vtkImageFlip](http://www.vtk.org/doc/nightly/html/classvtkImageFlip.html) object. Three flags exists---`flip_x`, `flip_y`, and `flip_z`---which may be set in any combination.

# Image Dimensions
By default, the image actual physical dimensions are set to the dimensions of the mesh. However, it is possible to set the dimensions of the image independently from using the `origin` and `dimensions` input parameters.

This allows for flexibility to how the `ImageFunction` is utilized. For example, a mesh could be defined to domain that is smaller than the actual image. Thus, if the `ImageFunction` dimensions are set to the larger domain, the mesh would only sample some portion of the image. Effectively, this feature can work on a cropped image, without needing to create a separate cropped image.

# Supported File Types
Currently, two types of files are supported \*.tif and \*.png. However, \*.tif files often to no read correctly with VTK, depending on the format of the file. So, if you experience problems reading \*.tif files it may require changing the format to \*.png. This can easily be done with any number of tools with [ImageMagick](http://www.imagemagick.org/) being one of the most powerful.

# Examples and Tests
A range of tests that implement each of the aforementioned features are included in the phase-field module tests directory: `moose/modules/phase_field/tests/image_function`.