New in ParaView: Specifying custom default values

Update: File names for user and site settings have been corrected.


In past versions, the ability to customize ParaView by changing default values for properties of sources, filters, views, and representations was somewhat limited:

  • Relatively few property defaults were modifiable
  • Customized property defaults could only be saved for the user login under which ParaView was run
  • Customized property defaults were not preserved across different installed versions of ParaView
  • Property defaults specified in the ParaView application were not available in other programs such as pvpython and pvbatch.

The upcoming release of ParaView remedies these shortcomings by adding a new way to specify arbitrary property defaults in ParaView. All the previously available property defaults (as well as other application settings) are still accessible through the Edit -> Settings menu item. However, even more defaults can be set by modifying a JSON configuration file.

Specifying custom defaults with JSON

Let's look at a concrete example of how to specify a property default that is not exposed in ParaView's settings dialog. Suppose you are not happy with the default tessellation of the Sphere Source in ParaView and would like to increase it to produce a smoother sphere. You can do this every time you create a Sphere Source, but that gets tiresome after a while. Instead, you can change the default tesselation values when the sphere source is created with a little JSON:

{
  "sources" : {
    "SphereSource" : {
      "ThetaResolution" : 32,
      "PhiResolution" : 32
    }
  }
}

This is a simple JSON file where the top level specifies the group of the object whose default you want to change — in this case, the "sources" group. The second level ("SphereSource") specifies the name of the object. Finally, the third level ("ThetaResolution", "PhiResolution") names the setting whose default value you want to change. When ParaView creates a Sphere Source object, it consults these JSON settings for any default values that should be used in place of those embedded in the ParaView application.

On Windows 7, this file must be located under %APPDATA%\ParaView\ParaView-UserSettings.json where the APPDATA environment variable is usually something like C:\Users\USERNAME\AppData\Roaming. On Unix-like systems, it is located under ~/.config/ParaView/ParaView-UserSettings.json. This file will already exist if you have made any settings changes through the settings user interface in the ParaView application. It is absolutely okay and encouraged to modify this file in your favorite text editor to change settings not exposed in the GUI. Of course, making a backup copy of this file before you edit it is always a good idea.

You can also specify defaults for properties that are arrays of values. For example, to specify the default surface color of objects displayed with the Surface representation, you can write

{
  "representations" : {
    "GeometryRepresentation" : {
      "DiffuseColor" : [0, 0.65, 1.0]
    }
  }
}

With this JSON, all newly created objects in ParaView that have a Geometry Representation (i.e., polygonal geometry) will have a light blue color when the Coloring option is set to Solid Color and the Representation is set to Surface or Surface With Edges.

As another example, suppose you want the default background for 3D views to be a gradient from black to dark gray. You can specify this with

{
  "views" : {
    "RenderView" : {
      "Background" : [0.0, 0.0, 0.0],
      "Background2" : [0.3, 0.3, 0.3],
      "UseGradientBackground" : true
    }
  }
}

You can also change setting defaults for filters. For example, to change the Shrink Factor in the Shrink filter, you can write

{
  "filters" : {
    "ShrinkFilter" : {
      "ShrinkFactor" : 0.75
    }
  }
}

Putting these four examples together, our ParaView-UserSettings.json file will look like

{
  "sources" : {
    "SphereSource" : {
      "ThetaResolution" : 32,
      "PhiResolution" : 32
    }
  },
  "representations" : {
    "GeometryRepresentation" : {
      "DiffuseColor" : [0, 0.65, 1.0]
    }
  },
  "views" : {
    "RenderView" : {
      "Background" : [0.0, 0.0, 0.0],
      "Background2" : [0.3, 0.3, 0.3],
      "UseGradientBackground" : true
    },
  "filters" : {
    "ShrinkFilter" : {
      "ShrinkFactor" : 0.75
    }
  }
}

The names of groups and objects come from the XML proxy definition files in the ParaView source code in the directory ParaView/ParaViewCore/ServerManager/SMApplication/Resources. The group name is defined by the "name" attribute in a "ProxyGroup" element. The object name comes from the "name" attribute in the "Proxy" element (or elements of vtkSMProxy subclasses). We are considering how to make setting defaults simpler in a future version of ParaView.

Site-wide custom defaults

Site administrators can install site-wide custom defaults using another JSON file if that is desired. The JSON file must be named ParaView-SiteSettings.json and can be placed in the same directory as the ParaView executable, in a lib directory next to the the ParaView executable, or one directory level above the ParaView executable. ParaView will search these directories in that order, reading in the first ParaView-SiteSettings.json file it finds.

If the same default is specified in the ParaView-SiteSettings.json and ParaView-UserSettings.json file in a user's directory, the default specified in the ParaView-UserSettings.json file is used.

Keeping settings when installing new versions of ParaView

Unlike previous versions of ParaView, the ParaView-UserSettings.json and ParaView-SiteSettings.json files are not tied to any ParaView version, so installations of newer versions of ParaView will pick up these settings when you run them.

Using custom defaults in pvpython and pvbatch

Perhaps the most exciting aspect of the new defaults file is that settings are now available in other applications in the ParaView ecosystem, including pvpython and pvbatch. These applications read the same files in the same locations described in this post. This makes it possible to set up a visualization in the ParaView GUI application with some custom settings, then generate a full animation in pvpython or pvbatch with those same settings.

5 Responses to New in ParaView: Specifying custom default values

  1. says:

    Magician

    I’m interested in the technique.
    How can we get more information about the properties of JSON?
    For example, I’d like to set the conditions of default lights.

  2. David Thompson says:

    Cool! If you’re going to manually edit the JSON, I strongly recommend installing jsonlint.

  3. Cory Quammen says:

    Light properties are part of a RenderView, so the JSON to change those properties would be

    {
    “views” : {
    “RenderView” : {
    “BackLightWarmth” : 0.2,
    “BackLightAzimuth” : 100
    “KeyLightElevation” : 45
    }
    }
    }

    To figure this out, I looked at the ParaView source code file under

    ParaView/ParaViewCore/ServerManager/SMApplication/Resources/views_and_representations.xml

    I searched this file for “Light” and found that the light properties were nested under the “RenderView” proxy XML element. Then I looked for the property names listed above and found the “name” attribute in the properties to figure out what to put in for the property name in the JSON file.

    Ideally, you would be able to just click a button or something in the UI to say “make this default”, but we are still thinking about the best way to do that without cluttering the interface.

  4. Cory Quammen says:

    Rats, I was hoping the indentation of the JSON would come through.

    Thanks for the tip about jsonlint, David! I found jsonlint.com while searching for it, which enables you to do JSON validation in the browser.

  5. Cory Quammen says:

    Oops, I should have followed David’s advice before posting JSON. Here is the corrected version with the missing comma in place:

    {
    “views” : {
    “RenderView” : {
    “BackLightWarmth” : 0.2,
    “BackLightAzimuth” : 100,
    “KeyLightElevation” : 45
    }
    }
    }

Questions or comments are always welcome!