DriveWorks Pro 24

How To: Set Up The Drag Entity

How To: Set Up The Drag Entity

The Drag Entity is used to allow a node to be moved and positioned on other geometry in the scene.

This guide demonstrates how it can be applied to a DriveWorks 3D document.

How drag works

The drag effect starts when the object comes into contact with other geometry in the scene.

If the object is positioned away from other geometry, the drag will only begin when the object hovers over other geometry.

Any transform position co-ordinates, applied to the object, will be overridden once the drag starts.

Drag uses the default camera or any other camera entities added to the scene.

Nodes can be dragged between cameras within the same scene.

The object will be dragged about its origin regardless of the selection point.

When the object is selected a ray is cast (based on the mouse location and node origin) into the scene.

The position of the node is then set to be the closest part of the drag surface that is hit by the ray.

1. Camera
2. Mouse Ray
3. Click Position
4. Model
5. Drag Ray
6. Model Origin
7. Drag Surface
8. Model's New Position

Create a DriveWorks 3D Document Using the Drag Entity

1. Create a new DriveWorks 3D document

With a Group and Project open in DriveWorks Administrator:

1. From Stage 4: Output Rules > Documents - 3D, click Add to begin a new DriveWorks 3D Document.
2. In the wizard enter a Document Name.
3. In the Add Scene Templates, select Ground Plane.

   This will be the surface the object will be dragged around.

4. Click Finish in the 3D Document Wizard.

2. Add an object to be dragged

1. Right click the Root node and select Add Node.
2. Enter a name for the node, for example Object
3. Click OK
4. Right click on this node and select Add Entity > Geometry > Primitive Model.

   The default primitive Model Type (Cube) will be used, along with the default Scale (1m x 1m x 1m) settings.

5. Right click on the same node and select Add Entity > Interaction > Drag Entity

2b. Optionally apply a color to the object

1. Right click on the Appearance category from the Feature Panel and select Add Appearance.
2. Enter the name Object Color.
3. Highlight the new Appearance in the Feature Panel and adjust the Red, Green and Blue values, to achieve the required color, in the Diffuse Color section in the Information Panel.
4. Drag the Object Color Appearance from the Feature Panel onto the Object in the 3D View.

3. See the drag working

The drag effect can now be viewed by:

• Play Mode
  1. In the 3D Document Editor, click Play Mode from the command bar.
  2. Rotate the view, click and hold the object model to drag around the ground plane.
• 3D Preview Control
  1. Go to Form Design and add a 3D Preview Control.
  2. For the property Preview Document Name select the 3D document that contains the drag example.
  3. Enter Test Mode, rotate the view, click and hold the object model to drag around the ground plane.

Enhancing By Adding Drag Surface

As the object is dragged about its origin, the ray cast from this point will hit the extents of the surface it is dragged on.

This allows the object go beyond the boundary of the surface.

To overcome this a Drag Surface can be added that is offset from the Ground Plane (added in the first step above) by the size of the object from its origin point.

1. Copy the ground plane node

1. Right click on the bottom level Ground Plane node (the node with the Primitive Model entity applied) and select Copy.

   

2. Right Click on it's parent Ground Plane node (the node without any entities applied) and select Paste.
3. Right click the pasted node (Ground Plane-1) and select Rename Node and enter the name Drag Surface.

2. Apply the offset dimensions to the drag surface

The default Scale values (X,Y,Z) applied to the cube primitive model, added to the Object node are 1m x 1m x 1m.

The default Scale values (X,Z) applied to the plane primitive model, and copied for the Drag Surface node are 5m x 5m.

Therefore the scale (X,Z) of the Primitive Model applied to the Drag Surface needs to be 5m - 1m = 4m.

1. Highlight the Drag Surface node from the Feature Panel.
2. In the Information Panel scroll to the Primitive Model section, in the Scale X parameter enter 4, (note this is in meters).
3. In the Scale Z parameter enter 4, (note this is in meters).

3. Apply the drag surface to the drag entity

1. Right click on the Drag Surface node, in the Feature Panel, and select Copy Address.
2. Highlight the Object node (that has the Drag Entity applied) from the Feature Panel.
3. In the Information Panel scroll to the Drag section, right click in the Drag Surface parameter and select Paste.

The Object can now be dragged so its origin meets the limits of the Drag Surface, which sit inside the limits of the Ground Plane.

4. Raise the object so the base sits on the ground plane

There are two elements that can be addressed by raising the object:

• Initial loading of the scene.

  The transform position co-ordinates of the object can be set so it sits on top of the ground plane when the scene initially loads.

• Ensure the base position is maintained when the drag starts.

  As the Drag Entity overrides any transform position co-ordinates the Drag Surface can be positioned so the base stays in contact with the ground plane.

Initial loading of the scene.

1. Highlight the Object node from the Feature Panel.
2. In the Information panel, select the Transform Position Y parameter and enter 500 (note these units are in mm).

   The Y Scale of the object is 1m, therefore its origin is 500mm from the edge.

Maintain position on Drag Start

To maintain the position of the object the Drag Surface must also be raised to the same Y value.

1. Highlight the Drag Surface node from the Feature Panel.
2. In the Information panel, select the Transform Position Y parameter and enter 500 (note these units are in mm).

4b. Optionally apply transparency to the drag surface

As the Drag Surface should not be seen a transparent appearance can be applied.

1. Right click on the Appearance category from the Feature Panel and select Add Appearance.
2. Enter the name Transparent.
3. Highlight the new Appearance in the Feature Panel and apply a value of 0 for the Alpha parameter in the Diffuse Color section in the Information Panel.
4. Drag the Transparent Appearance from the Feature Panel onto the Drag Surface in the 3D View.

Enhancing By Adding Macro's

The On Start Macro Name parameter, of the Drag Entity can be used to run a macro as soon as the Drag occurs.

Similarly the On End Macro Name parameter can be used to run a macro as soon as the Drag finishes.

This example will run a macro that controls a Glow entity applied to the Drag Surface.

1. Create a constant and the macro's to turn glow on and off

1. In Define Constants create a constant named ShowDragArea.
2. Enter False for the value.
3. In Specification Macros create a macro named ShowDragAreaOn.
4. Add the Drive Constant Value task.
5. Connect the Start node to the Drive Constant Value task.
6. In the Drive Constant Value task, set the Constant Value to True.
7. Set the Constant Name to DWConstantShowDragArea.
8. Highlight the ShowDragAreaOn macro from the macro list, click the Copy button from the command bar.
9. Click the Paste button from the command bar.
10. Rename the pasted macro to ShowDragAreaOff.
11. In the Drive Constant Value task, set the Constant Value to False.

2. Apply the macro's to the drag entity

1. In the 3D Document highlight the Object node from the Feature Panel.
2. In the Information Panel scroll to the parameters for the Drag Entity.
3. In the On Start panel enter ShowDragAreaOn for the Macro Name parameter.
4. In the On End panel enter ShowDragAreaOff for the Macro Name parameter.

3. Add the glow entity to the ground plane

Although a Drag Surface node was added, this limited the object from extended beyond the Ground Plane.

Therefore the ground plane will be highlighted as the Drag Area.

1. Select the Ground Plane node (check the box) from the Feature Panel.
2. Right click the Ground Plane node from the Feature Panel.
3. Select Add Entity > Effects > Glow.
4. Locate and select the Glow Enabled parameter from the Parameter Panel (type Glow Enabled in the filter box).
5. Click the Build button (or double click on the Glow Enabled parameter) to launch the Rule Builder.
6. Clear the current value and select the ShowDragArea constant.
7. Click OK to apply the rule.

4. Enable outline glow in the environment

1. In the Feature Panel highlight the Environment node.
2. In the Information Panel scroll to the parameters for Outline Glow.
3. Check the box for Outline Glow Enabled.
4. In the Glow Color panel set the Red value to be 0 and the Blue value to 0 (this will apply a bright green color for the Glow)
5. Select the Drag Surface node (check the box) from the Feature Panel.

5. See glow working

As macros will not run using Play Mode or Test Mode (in Form Design) a Specification should be started to see the Glow effect working.