Modifying an operator
This page addresses making a modification to an existing operator.
It is easier to talk about something "real", so this page will reflect an approximation of an upcoming change by Dave Pugmire: adding a new mechanism for selecting the normal for the Slice operator. The normal will be specified by giving theta and phi values.
Every plugin has an XML file that describes it. So, since Slice is an existing operator, there is an existing file, Slice.xml, that describes it.
The program to modify these XML files is xmledit. For an operator (i.e. Slice), the most notable feature provided by xmledit is the ability to specify the attributes to the Slice. These SliceAttributes are used to define the plane of the slice.
For this change, we will need to do three things:
- Under the Enums tab, there is an enumerated type for how to define an axis (AxisType). This enumerated type needs a new entry for Theta/Phi specifications. Call it ThetaPhi.
- Under the Fields tab, we need to add a new data member to the slice attributes for specifying the angle of theta.
- Click on "New" (lower left)
- Name is "theta"
- Label is "theta"
- Type is double
- Enabler is "axisType".
- (Enabler) Values is ThetaPhi.
- Initialization values / code (at the bottom) is "0.". This means that theta will have a default value of 0.
- Repeat for "phi"
Once you've done all of that, go to File->Save and then exit.
Once you have an XML file, VisIt can codegen much of the plugin. Of course, since this is an existing plugin, you don't want to clobber important, pre-existing pieces. With a new plugin, you would run xml2plugin, which in turn calls many xml2 programs. We will want to re-run some of these programs, but not others.
- xml2atts: You changed the attributes in the XML file, so you need to regenerate the C++ code for these attributes.
- xml2java: This creates Java bindings to the attributes, so you will have to re-run this.
- xml2python: This creates Python bindings to the attributes, so you will have to re-run this.
Also, all of the xml2 tools will not overwrite existing files by default. In this case, you'll want to add "-clobber" to get the new output.
- xml2avt: There is an existing avtSliceFilter which you only want to slightly modify. So leave it as is.
- xml2info: This creates the code that lets VisIt load it as a shared library, understand what is in the file, etc. You haven't changed anything along those lines, so don't rerun.
- xml2makefile: You've got the same set of files, so don't re-run this.
- xml2window: There is an existing Qt window which you only want to slightly modify. Again, leave it as is.
- xml2projectfile: See xml2makefile (this creates the Windows equivalent)
You will have to modify two modules: QvisSliceWindow and avtSliceFilter.
QvisSliceWindow will have many examples that can be cut-n-pasted to add theta and phi. You can make these changes in entirety without modifying the AVT code. The AVT code will be oblivious to your changes, but it's nice to be able to tackle one half of the problem independently of the other half.
avtSliceFilter has a routine that sets the normal of the plane. You should only need to do that.
Once you make those changes and compile, you should be good to go.