Difference between revisions of "ParaView/UsersGuide/Macros"

From KitwarePublic
Jump to: navigation, search
(Created page with "== Macros (aka Custom Filters) == It often happens that once you figure out how to do some specific data processing task, you will want to repeat that task often. It is very usef...")
 
m (improve text)
Line 1: Line 1:
 
== Macros (aka Custom Filters) ==
 
== Macros (aka Custom Filters) ==
It often happens that once you figure out how to do some specific data processing task, you will want to repeat that task often. It is very useful to be able to reuse particular filters with exact filter settings (for example complicated calculator or programmable filter expressions) or even entire pipeline sections consisting of a number of filters on different datasets.
+
It often happens that once you figure out how to do some specific data processing task, you want to repeat it often.
 +
You may for example want to reuse particular filters with specific settings (for example complicated calculator or programmable filter expressions) or even entire pipeline sections consisting on new data sets without having to manually enter the parameters each time.
  
 +
You can do this via the clever use of state files or more conveniently python scripts and python macros [[ParaView/Python_Scripting | 1 ]]. Saving, editing and reusing state files gives you the ability to recreate entire ParaView sessions. This does not give you fine enough control for small, repeatedly reused tasks. Python Tracing does give you fine grained control, but this assumes that your have python enabled in your copy of ParaView (which is usually but not always the case) and that you remember to turn on Trace recording before you did whatever it was that you want to play back. Both techniques largely require that you think like a programmer when you initially create and setup the scripts.
 +
Another alternative is to use ParaView's Custom Filters which let you create reusable meta-filters strictly within the GUI.
  
<nowiki>You can use of course edit and use state files <REFERENCE BATCH MODE CHAPTER?> to recreate entire ParaView sessions but this does not give you fine enough control for small, highly reusable tasks. Another alternative is to use Python Tracing <REFERENCE PYTHON TRACING>, which does give you fine grained control, but assumes that your have python enabled in your copy of ParaView (which is usually but not always the case) and that you remembered to turn on Trace recording before you did whatever it was that you wanted to be able to play back. ParaView’s Custom Filters suffer from neither of these problems.</nowiki>
+
A Custom Filter is a black box filter that encapsulates one or more filters in a sub-pipeline and exposes only those parameters from that sub-pipeline that the Custom Filter creator chose to make available. For example, if you capture a ten element pipeline in your Custom Filter where each filter happened to have eight parameters, you could choose to expose anywhere from zero to eighty parameters in your Custom Filter's '''Properties''' tab.  
 
+
 
+
A Custom Filter is a black box filter that encapsulates one or more filters in a sub-pipeline and exposes only those parameters from that sub-pipeline that the Custom Filter creator chose to make available. For example, if you have a ten element pipeline in your Custom Filter and each filter in the pipeline has eight controls, you can choose to expose anywhere from zero to eighty controls in your Custom Filter's Properties tab.  
+
  
  
Line 14: Line 14:
  
  
Once you have set up some pipeline that performs the data processing that you want to reuse, the process of creating a Custom Filter consists of three steps. First select one or more filters from the Pipeline Browser using the mouse. Next from the Tools menu select Create Custom Filter. From that dialog choose the module who's input is representative of where you want data to enter into your Custom Filter. This is usually the topmost filter. If you are creating a multi-input filter, use the + button to add more and configure it as well. Clicking Next brings you to a similar dialog that you use similarly to configure one or more outputs of your Custom Filter. Click Next again to get to the last dialog. This dialog is where you specify the parameters of the internal filters that you want to expose to the eventual user of your custom filter. You also are able here to give each parameter a label if you like. The three dialogs are shown below.
+
Once you have set up some pipeline that performs the data processing that you want to reuse, the process of creating a Custom Filter consists of three steps. First select one or more filters from the '''Pipeline Browser''' using the mouse. Next from the '''Tools''' menu select '''Create Custom Filter'''. From that dialog choose the filter in your chosen sub-pipeline who's input is representative of where you want data to enter into your Custom Filter. This is usually the topmost filter. If you are creating a multi-input filter, click the '''+''' button to add additional inputs and configure them in the same way. Clicking '''Next''' brings you to a similar dialog in which you choose the outputs of your Custom Filter. Click '''Next''' again to get to the last dialog. On this one you specify which parameters of the internal filters that you want to expose to the eventual user of the custom filter. You can optionally give each parameter a descriptive label here as well. The three dialogs are shown below.
  
  
Line 36: Line 36:
  
  
Once you create a Custom Filter it is added to the Alphabetical sub menu of the Filters menu. It is saved in ParaView's settings, so the next time you start ParaView on the same machine you will have access to your new filter. Custom Filters are treated no differently than other filters in ParaView and are saveable and restorable in state files and python scripts. If you find that you no longer need some Custom Filter, you can use the Tools->Manage Custom Filters dialog box to remove it from your Filters menu.  
+
Once you create a Custom Filter it is added to the '''Alphabetical''' sub menu of the '''Filters''' menu. It is automatically saved in ParaView's settings, so the next time you start ParaView on the same machine you can use it just like any of the other filters that came with your copy of ParaView. Custom Filters are treated no differently than other filters in ParaView and are saveable and restorable in state files and python scripts. If you find that you no longer need some Custom Filter and want to get rid of it, use the '''Manage Custom Filters''' dialog box under the '''Tools''' menu to remove it.  
  
  
If on the other hand you find that a Custom Filter is very useful, you may instead want to give it to a colleague. On that same dialog are controls for exporting and importing Custom Filters. When you save a Custom Filter you are prompted for a location and filename to save the filter in, and the filter will be written to that file in an XML text file that you can simply email to share.
+
If on the other hand you find that a Custom Filter is very useful, you may instead want to give it to a colleague. On that same dialog are controls for exporting and importing Custom Filters. When you save a Custom Filter you are prompted for a location and filename to save the filter in. The file format is a simple XML text file that you can simply email or otherwise deliver.

Revision as of 13:56, 28 January 2011

Macros (aka Custom Filters)

It often happens that once you figure out how to do some specific data processing task, you want to repeat it often. You may for example want to reuse particular filters with specific settings (for example complicated calculator or programmable filter expressions) or even entire pipeline sections consisting on new data sets without having to manually enter the parameters each time.

You can do this via the clever use of state files or more conveniently python scripts and python macros 1 . Saving, editing and reusing state files gives you the ability to recreate entire ParaView sessions. This does not give you fine enough control for small, repeatedly reused tasks. Python Tracing does give you fine grained control, but this assumes that your have python enabled in your copy of ParaView (which is usually but not always the case) and that you remember to turn on Trace recording before you did whatever it was that you want to play back. Both techniques largely require that you think like a programmer when you initially create and setup the scripts. Another alternative is to use ParaView's Custom Filters which let you create reusable meta-filters strictly within the GUI.

A Custom Filter is a black box filter that encapsulates one or more filters in a sub-pipeline and exposes only those parameters from that sub-pipeline that the Custom Filter creator chose to make available. For example, if you capture a ten element pipeline in your Custom Filter where each filter happened to have eight parameters, you could choose to expose anywhere from zero to eighty parameters in your Custom Filter's Properties tab.


ParaView UsersGuide CustomFilterConcept.png
Figure 13: Custom Filter concept


Once you have set up some pipeline that performs the data processing that you want to reuse, the process of creating a Custom Filter consists of three steps. First select one or more filters from the Pipeline Browser using the mouse. Next from the Tools menu select Create Custom Filter. From that dialog choose the filter in your chosen sub-pipeline who's input is representative of where you want data to enter into your Custom Filter. This is usually the topmost filter. If you are creating a multi-input filter, click the + button to add additional inputs and configure them in the same way. Clicking Next brings you to a similar dialog in which you choose the outputs of your Custom Filter. Click Next again to get to the last dialog. On this one you specify which parameters of the internal filters that you want to expose to the eventual user of the custom filter. You can optionally give each parameter a descriptive label here as well. The three dialogs are shown below.


Step 1: configure one or more inputs to your new filter.
ParaView UsersGuide CustomFilterInputs.png
Step 2: configure one or more outputs of your new filter.
ParaView UsersGuide CustomFilterOutputs.png
Step 3: identify and name the controls you want to expose of your new filter.
ParaView UsersGuide CustomFilterParameters.png
Figure 9: Creating a Custom Filter


Once you create a Custom Filter it is added to the Alphabetical sub menu of the Filters menu. It is automatically saved in ParaView's settings, so the next time you start ParaView on the same machine you can use it just like any of the other filters that came with your copy of ParaView. Custom Filters are treated no differently than other filters in ParaView and are saveable and restorable in state files and python scripts. If you find that you no longer need some Custom Filter and want to get rid of it, use the Manage Custom Filters dialog box under the Tools menu to remove it.


If on the other hand you find that a Custom Filter is very useful, you may instead want to give it to a colleague. On that same dialog are controls for exporting and importing Custom Filters. When you save a Custom Filter you are prompted for a location and filename to save the filter in. The file format is a simple XML text file that you can simply email or otherwise deliver.