Editing Software Plugins and Codes (section)

=ParaView=
==Getting ParaView With Numerics88 Extensions==

A custom-compiled version of ParaView is available with extensions to open AIM files, and FAIM output files directly.  This version is already installed on many lab computers.  If you need a copy, go see Eric.

==How-Tos==

===Display Slices of an AIM file===

Open the AIM file.  Make sure that <b>Data on Cells</b> is not selected.  Click the Apply button in the Object Inspector, as shown.

[[Image:ParaView_Object_Insp1.png]]

Go to the Display tab of the Object Inspector, find the Style section, and set the Representation box to Slice.

[[Image:ParaView_Slice_Representation.png]]

Now you probably want to set the viewing direction along a particular axis.  There are buttons on the toolbar for this purpose.  Finally, for viewing slices, it is convenient to use parallel projection.  Select View Settings from the Edit menu, and make sure that Use Parallel Projection is selected.

[[Image:ParaView_View_Settings.png]]

Now you can scroll through the slices with the Slice slider bar, which is located on the Display tab of the Object Inspector.  You may want to click the Toggle Color Legend Visibility button on the toolbar in order to get a legend for the color scale.

[[Image:ParaView_Slice169.png]]

===Display an AIM file using the Threshold filter===

Open the AIM file.  Make sure that <b>Data on Cells</b> is selected, otherwise, the data will be interpolated in the threshold filter and this can result in artefacts (for example, it can make it appear that disconnected regions are connected, or vice versa).  Click the Apply button.

Making sure that the AIM file is selected in the Pipeline Browser (it should be if you just opened it), choose a Threshold filter.  You can do this from the icon on the toolbar, or Filters menu.  Select suitable threshold values with the sliders.  Click Apply.  If your data file is large, you might not see anything yet, since ParaView may have chosen Outline as the best viewing mode.  You can change this to Surface.  This can either be done from the toolbar, where there is a drop-down list, or you can go to the Display tab of the Object Inspector.

[[Image:ParaView_Threshold1.png]]

Tips:
* You can use multiple Threshold filters on the same data.  This can be useful if your data consists of two different materials.  In this case you can go to Display and set a different Solid Color for each Threshold filter.

===Display an AIM file using the Contour filter===

Contouring can provide smoother-looking surfaces than Thresholding.  However, it is more computationally intensive.

Open the AIM file.  Make sure that <b>Data on Cells</b> is not selected, but that <b>Pad</b> is.  The reason for padding the image, which adds a layer of zero-valued points all around the image volume, is that this will result in outer surfaces being shown.  Click Apply.  Select a Contour filter, either from the toolbar or the Filter menu, and click Apply.  Done!

[[Image:ParaView_Contour_View.png]]


===Show exaggerated displacements of an FE model===

# Open the FE .out file.  Make sure it is selected in the Pipeline Browser.
# Go to the Filters menu and choose Common -> Warp By Vector
# Make sure that the drop down box Vectors in Properties for the Warp By Vector filter has NODAL_DISPLACEMENTS selected.  (It should already.)
# Enter the desired Scale Factor and click Apply.

[[Image:ParaViewWarp.png]]

===Show displacements only in the x,y directions===

The example shows how to use the calculator to manipulate vector fields associated with data objects.  Here we are eliminating the z component of the displacement.  This may be useful when we want to investigate fine details of the x,y displacement without flattening the model due to excessive exaggerated z displacement.

# Starting with an open FE model, select a Calculator filter.
# Enter this expression, which subtracts the z-component from the vector field NODAL_DISPLACEMENTS:
 NODAL_DISPLACEMENTS -  kHat * (kHat.NODAL_DISPLACEMENTS)
# Click Apply.
# Now apply a Warp By Vector filter as described previously.

[[Image:ParaViewWarpNoZ.png]]

===Show the difference in displacements between two similar models===

====Method 1: Using a Programmable Filter====

This example will demonstrate several things:
* Using a filter with multiple inputs.
* Using a programmable filter.
* Using numpy arrays within a ParaView Programmable Filter.  (See [http://paraview.org/Wiki/Python_Programmable_Filter#Center_Data_using_numpy].)

Here are the steps:

# Open both data files.  In this example, one will be a FAIM output file, while the other will be in the form of a VTK Unstructured Grid file.
# Select both files at once in the Pipeline Browser.  This is done in OS-X by clicking on one, then holding down the Command key and clicking on the other.
# Now select a Programmable Filter from the menu.
# Enter this script:
<source lang=python>
from paraview.vtk import dataset_adapter as DA

# Get inputs/outputs as VTK objects
input0 = self.GetInputDataObject(0,0)
input1 = self.GetInputDataObject(0,1)
output = self.GetOutputDataObject(0)

# We can get the array data from the "inputs" object, which is an alternative interface (more Pythonesque) to the same data.
# This gives us numpy arrays.
x0 = inputs[0].PointData.GetArray("NODAL_DISPLACEMENTS")
# Change the following to GetArray("NODAL_DISPLACEMENTS") if your second input is also a FAIM data file.
x1 = inputs[1].PointData.GetArray("displacement")

# Numpy arrays can be operated on element-by-element with simple expressions.  (Both x0 and x1 are Nx3 arrays.)
# You could also do a loop over the elements, but it would be slower and more verbose.
xdiff = x1 - x0

# Convert from a numpy array to a VTK array.
# Call it "dispdiff", but you could name it anything.
xdiff_vtk = DA.numpyTovtkDataArray(xdiff, 'dispdiff')

# The output is a copy of the first input, except we attach our new vector data to the points.
output.ShallowCopy(input0)
output.GetPointData().AddArray(xdiff_vtk)
</source>
# Click OK
# Change the Display of the programmable filter to "dispdiff", and click "Toggle Color Legend Visibility" button.

[[Image:ParaviewDifferenceInDisp.png]]

====Method 2: Using a Python Calculator Filter====

This is a little simpler than using a Programmable Filter.  Instead of a Programmable Filer, choose a Python Calculator.  In the expression field enter this line:
<source lang=python>
inputs[0].PointData.GetArray("NODAL_DISPLACEMENTS") - inputs[1].PointData.GetArray("displacement")
</source>
Set the Array Name if you want, then hit Apply.

[[Image:ParaviewDifferenceInDisp2.png]]

===Show differences between two images prior and after registration===

====Image differences====
* Load two images
* Select a subregion with the same size in both images
* Select two subregions (Ctrl-Click) and feed them to a Python Calculator.  In the expression field enter this line:
<source lang=python>
inputs[0].CellData.GetArray("AIMData") - inputs[1].CellData.GetArray("AIMData")
</source>
This assumes that the AIM image attaches pixel values to CellData.
* Set 'Array Association = CellData'
* Uncheck 'Copy Arrays'
* Set the Array Name if you want, then hit Apply. 
* To visualize, choose Display->Style->Representation = Slice. Play with XY vs XZ vs YZ views and select a slice of interest. Modify the colormap and mapping of the grayscale values to have a better comparison. 
* Add a second '3D View' in a separate panel and repeat the above for the second image pair. 
* Add the image comparison as a 'custom filter' by selecting the python calculator you just created and choosing Tools->Custom Filter, give a name like 'Compare Images' and click Finish. Select any two images you want to compare and Choose Filter->Alphabetical->Compare Images - done :o)

Here is the end result:

[[Image:ParaviewBeforeVsAfterRegistration.jpg]]

====Checkerboard====
* Load two images, unselect 'DataOnCells' so that pixal values are attached to PointData
* Select a subregion with the same size in both images (Somehow we need 'subregion', otherwise it is not happy later)
* Select two subregions (Ctrl-Click) and feed them to a Programmable Filter, the code is:
<source lang=python>
from paraview.vtk import imaging as im

# Get inputs/outputs as VTK objects
input0 = self.GetInputDataObject(0,0)
input1 = self.GetInputDataObject(0,1)
output = self.GetOutputDataObject(0)

# Create a checkerboard object
checker = im.vtkImageCheckerboard()

# Set checkerboard inputs
checker.SetInput1(input0)
checker.SetInput2(input1)

# Set the number of tiles in each dimension
checker.SetNumberOfDivisions(4,4,2)

# Copy to the output object
checker.Update()
output.DeepCopy(checker.GetOutput())
</source>
* Click apply and use slice for visualization.
* Create a custom filter as described above. Note I don't know how you would expose the SetNumberOfDivisions(), that would be handy.
Here is the end result:

[[Image:ParaviewBeforeVsAfterRegistrationCheckerBoard.jpg]]

==Wish List==

This is a list of things that we would like to be able to do.  They may be things that ParaView can inherently do already, but we haven't figured out how, or they may be things that will require the writing of a new plug in.
* Save a subvolume of an AIM
: Would like to be able to read an AIM, select a reduced volume, and write that out as another AIM.
* Create an FE model interactively.
: This would involve lots of smaller steps.  For example, selecting sets of points for Boundary Conditions.
* Registration within ParaView
: There are some existing plugins.  They might be useful, or posibly they could be further customized for our purposes. http://paraview.org/Wiki/User_Created_Plugins
* World Peace button on the toolbar


[[Image:Redirect.jpg|15px]] [[#top|''Return to Contents'']] or [[Main_Page|''Return to Main Page'']]

==Writing Plugins for Paraview==

Have a look at the paraview_plugins project in the Numerics88 source code.  The plugins there are working examples.

===Links===

Here are some useful links.

http://paraview.org/Wiki/Plugin_HowTo

http://paraview.org/Wiki/ParaView:FAQ#How_do_I_add_my_own_vtk_filter.2Freader_to_ParaView.3F

http://public.kitware.com/pipermail/paraview/2003-September/000290.html

http://paraview.org/Wiki/ExtendingParaView

===Tips===

====Link to Paraview's internal VTK====

Your plugins, and any libraries that they use, must link to Paraview's internal version of VTK, and not some other VTK libraries.  This is true even if both the internal and external versions of VTK were built from the same VTK sources!  As a concrete example, paraview_plugins links to vtkski.  The plugins will die with mysterious segmentation faults unless you build vtkski to link against the Paraview internal version of VTK.  So for example, on my Linux system, cmake will automatically find vtk at <tt>/usr/lib/vtk-5.2</tt> .  However, I have to change the cmake variable <tt>VTK_DIR</tt> manually to <tt>/home/eric/source/ParaView3/build/VTK</tt> .

====Implement RequestInformation for vtkImageData data types====

This seems to be necessary for vtkImageData, although strangely not for vtkUnstructuredData.

Here is an example, where the extent, spacing, origin and data type are set in RequestInformation.  This seems to be sufficient.

<source lang=c>
int vtkAIMReaderPlugin::RequestInformation (
  vtkInformation       * vtkNotUsed( request ),
  vtkInformationVector** vtkNotUsed( inputVector ),
  vtkInformationVector * outputVector)
{
  // Make sure FileName is set
  if (!this->FileName)
  {
    vtkErrorMacro("A Filename must be specified");
    return 0;
  }
  vtkSmartPointer<vtkAIMReader> reader = vtkSmartPointer<vtkAIMReader>::New();
  reader->SetFileName (FileName);
  reader->UpdateInformation();
  vtkImageData* data = reader->GetOutput();
  vtkInformation* outInfo = outputVector->GetInformationObject(0);

  outInfo->Set (vtkStreamingDemandDrivenPipeline::WHOLE_EXTENT(),
                data->GetWholeExtent(), 6);
  outInfo->Set (vtkDataObject::SPACING(), data->GetSpacing(), 3);
  outInfo->Set (vtkDataObject::ORIGIN(), data->GetOrigin(), 3);
  vtkDataObject::SetPointDataActiveScalarInfo(outInfo, VTK_FLOAT, 1);
  return 1;
}
</source>

====You may need to convert to VTK_FLOAT====

Paraview does not seem to handle byte (char) data well.  In particular, there is sign/unsigned ambiguity with char types in paraview.  If your source produces byte data, I recommend converting it in your plugin to float.

====Scalar values must be named====

If you don't assign a name to scalar values, paraview can't do anything with them.

Here is an example.

<source lang=c>
int vtkAIMReaderPlugin::RequestData (vtkInformation*,
                                     vtkInformationVector**,
                                     vtkInformationVector* outputVector)
{
  vtkSmartPointer<vtkImageData> temp = vtkSmartPointer<vtkImageData>::New();

  // ACTUAL WORKING CODE TO FILL temp REMOVED FOR CLARITY
  // see vtkAIMReaderPlugin.cxx for details.
  //   .
  //   .
  //   .

  vtkImageData* out = vtkImageData::GetData (outputVector);
  out->ShallowCopy(temp);

  // Must have a name for the scalar data otherwise paraview can do nothing
  // with it.
  out->GetPointData()->GetScalars()->SetName("AIMData");

  return 1;
}
</source>

====Copy your data to the output, instead of connecting the output to a VTK filter====

I don't understand why this is sometimes required, but using ShallowCopy seems be necessary in certain cases.  Note there should in theory be no performance impact to using ShallowCopy (no new copy of the data will be made in memory).

Here is an example.

<source lang="c">
int vtkAIMReaderPlugin::RequestData (vtkInformation*,
                                     vtkInformationVector**,
                                     vtkInformationVector* outputVector)
{
  // Make sure FileName is set
  if (!this->FileName)
    {
    vtkErrorMacro("A Filename must be specified");
    return 0;
    }

  vtkSmartPointer<vtkAIMReader> reader = vtkSmartPointer<vtkAIMReader>::New();
  reader->SetFileName (FileName);
  reader->UpdateInformation();   // Not sure if this is redundant
  reader->Update();
  vtkImageData* data = reader->GetOutput();

  vtkImageData* out = vtkImageData::GetData (outputVector);
  if (!out)
  {
    return 0;
  }
  // Not sure why we need a temporary object for the caster, but without it,
  // an error occurs in paraview.
  vtkSmartPointer<vtkImageData> temp = vtkSmartPointer<vtkImageData>::New();
  // Convert to float, regardless of original type
  vtkSmartPointer<vtkImageCast> caster = vtkSmartPointer<vtkImageCast>::New();
  caster->SetInput (data);
  caster->SetOutput (temp);
  caster->SetOutputScalarType (VTK_FLOAT);
  caster->Update();

  out->ShallowCopy(temp);

  // Must have a name for the scalar data otherwise paraview can do nothing
  // with it.
  out->GetPointData()->GetScalars()->SetName("AIMData");

  return 1;
}
</source>

This is the error that you will get if you fail to use ShallowCopy and just set the output of caster in the above example to 'out':

 ERROR: In /home/eric/source/paraview-3.6.1/Servers/Common/vtkPVDataInformation.cxx, line 586
 vtkPVDataInformation (0x2c391a0): Could not cast object to a known data set: vtkAlgorithmOutput


[[Image:Redirect.jpg|15px]] [[#top|''Return to Contents'']] or [[Main_Page|''Return to Main Page'']]