ParaView/Equation Rendering

From KitwarePublic
Jump to navigationJump to search

Equation Rendering

Example rendering using MathText

New in the 3.98 series, support for equation rendering is being introduced to various text objects in ParaView. Equations are specified using MathText markup, which is a subset of LaTeX. See the complete specification for the MathText language at [1].

ParaView will check text for a pair of "$" symbols surrounding a MathText expression. If such a pattern is found, the entire text field will be rendered as an equation. If it is not found, the text is rendered normally. To render a string containing two or more "$" symbols that is not intended to be an equation, use "\$" to tell the parser to treat the symbols literally.

As a result of using Python to render the equations, MathText strings may take noticeably longer to render than other text.

Compiling with MathText support

To compile ParaView with support for MathText, simply turn on PARAVIEW_ENABLE_PYTHON during configuration with cmake. While matplotlib is not required at compile time, the Python libraries must be available. ParaView will attempt to locate the matplotlib module at runtime, and will disable MathText rendering if it is not found.

Current Support

The following objects support MathText rendering:

  • Color bar categorical annotations (version 3.98)
  • Objects using vtkTextActor, e.g. the 2D Text annotation source (version 3.98.1)
  • Chart labels

Not yet supported:

  • Object using vtkTextActor3D

Caveats

  • Multiple lines are not supported by the MathText implementation -- keep equations to one line or less, or split them into multiple text sources.
  • The scaled bracket tokens \left(, left{, right], etc. seem to cause issues with matplotlib on different platforms -- they work fine with some matplotlib builds but not others. Avoid using them if portability is required.

Implementation

The MathText rendering is performed by the matplotlib python module using the Python C API. ParaView uses the interface provided by VTK. The following classes in VTK provide this functionality:

  • vtkTextRenderer: Abstract public interface for text rendering.
  • vtkMathTextFreeTypeTextRenderer: Concrete implementation of vtkTextRenderer that uses vtkMathTextUtilities and vtkFreeTypeTools for rendering MathText and "regular" text.
  • vtkMathTextUtilities: Abstract interface for MathText rendering.
  • vtkMatplotlibMathTextUtilities: Concrete implementation of vtkMathTextUtilities using matplotlib's mathtext module.