View source for ParaView/Users Guide/Widgets

== 3D Widgets ==
In addition to being controlled manually through entry boxes, sliders, etc., parameters of some of the filters and sources in ParaView can be changed interactively by manipulating 3D widgets in a 3D view. Often the 3D widgets are used to set the parameters approximately, and then the manual controls are used for fine-tuning these values. In the manual controls for each 3D widget, there is a check box for toggling whether the 3D widget is drawn in the scene; the label for the check box depends on the type of 3D widget being used. The following 3D widgets are supported in ParaView.

=== Line Widget ===
[[Image:]]The line widget is used to set the orientation and the position of a line. It is used in both the '''Stream Tracer''' and '''Elevation''' filters. The position of the line can be changed by clicking on any point on the line except the endpoints and dragging. To position the widget accurately, the user may need to change the camera position as well. Holding the Shift key while interacting will restrict the motion of the line widget to one of the X, Y, or Z planes. (The plane chosen is the one most closely aligned with the direction of the initial mouse movement.) To move one of the endpoints, simply use one of the point widgets on each end of the line. These are marked by spheres which become red when clicked. You can also reposition the endpoints by pressing the “P” key; the endpoint nearest to the mouse cursor will be placed at the position on the data set surface beneath the mouse position. Left-clicking while the cursor is over the line and dragging will reposition the entire line. Doing the same with the right mouse button causes the line to resize. Upward mouse motion increases the length of the line; downward motion decreases it.

<center>[[Image:]]</center>

<center>'''Figure 10. Line widget user interface'''</center>

The '''Show Line''' check box toggles the visibility of the line in the 3D view.

The controls shown above can be used to precisely set the endpoint coordinates and resolution of the line. The '''X Axis''', '''Y Axis''', and '''Z Axis''' buttons cause the line to be along the selected axis and pass through the center of the bounds of the data set.

Depending on the source or filter using this widget, the '''Resolution''' spin box may not be displayed. The value of the '''Resolution''' spin box determines the number of segments composing the line.

=== Plane Widget ===
[[Image:]]The plane widget is used in clipping and cutting. The plane can be moved parallel to its normal by left-clicking on any point on the plane except the line center and dragging. Right-clicking on the plane (except on the normal line center) and dragging scales the plane widget. Upward mouse motion increases the size of the plane; downward motion decreases it. The plane normal can be changed by manipulating one of the point widgets (displayed as cones that become red when clicked) at each end of the normal vector.

Shown below, the standard user interface for this widget provides entry boxes for setting the center position ('''Origin''') and normal direction of the plane as well as toggling the plane widget’s visibility (using the '''Show Plane''' check box). Buttons are provided for positioning the plane at the center of the bounding box of the data set ('''Center on Bounds''') and for aligning the plane’s normal with the normal of the camera ('''Camera Normal'''), the X axis, the Y axis, or the Z axis ('''X Normal''', '''Y Normal''', and '''Z Normal''', respectively). If the bounds of the data set being operated on change, then you can use the '''Reset Bounds''' button to cause the bounding box for the plane widget to match the new bounds of the data set and reposition the origin of the plane at the center of the new bounds. (Using only the '''Center on Bounds''' button in this case would move the origin to the center of the new bounds, but the bounds of the widget would not be updated.)

<center>[[Image:]]</center>

<center>'''Figure 11. Plane widget user interface'''</center>

=== Point Widget ===
[[Image:]]The point widget is used to set the position of a point or the center of a point cloud. It is used by both the '''Stream Tracer''', '''Probe Location''' and '''Probe Location over Time''' filters. The position of the point can be changed by left-clicking anywhere on it and dragging. Right-clicking and dragging anywhere on the widget changes the size of the point widget in the scene. To position the widget accurately, the user may need to change the camera position as well. Holding the Shift key while interacting will restrict the motion of the point to one of the x, y or z planes. (The plane chosen is the one that is most closely aligned with the direction of the initial mouse movement.)

As shown below, entry boxes allow the user to exactly specify the coordinates of the point, and a button is provided to position the point at the center of the bounds of the current data set. If the point widget is being used to position a point cloud instead of a single point, entry boxes are also provided to specify the radius of the point cloud and the number of points the cloud contains.

<center>[[Image:]]</center>

<center>'''Figure 12. Point widget user interface'''</center>