StandardTool3D Class
An advanced tool for interacting with 3D views.
NuGet/Assembly: Carmenta.Engine.5.16.2.nupkg (in the CECore assembly)
Syntax
public class StandardTool3D : ToolRemarks
StandardTool3D is a tool for interacting with 3D views. By using only the mouse, the user can easily move around the 3D view, zoom in or out on specific positions in the view, or rotate around interesting positions, controlling the camera position, bearing and pitch. It also supports moving complete objects or parts of objects, and even adding and removing nodes of existing features.
If attached to a 2D view, the StandardTool3D does nothing; use a StandardTool instead.
The editing operations only work if the feature is in a layer that is selectable (Layer.selectable), the layer's parent layers are selectable and the feature is stored in a dataset that is writable (i.e. it has to be a MemoryDataSet).
In general, the tool will change the original nodes of geometries you edit. If you want to edit individual nodes of the geometries with the tool, the operator chain should not add, delete or move nodes in the geometry between being read from the MemoryDataSet and being visualized by a VisualizationOperator. The features should not reside inside a GlobeTileLayer since this may introduce new nodes on the visualized geometry where the tiles are joined. To improve performance, editable features should instead reside in a OrdinaryLayer using Dynamic.
The StandardTool3D does not let you create new features; use CreateTool3D for that.
Supported Interactions
Some interactions use the selected ground point: the piece of ground that the cursor points at when you press the mouse button. These interactions cannot start if the cursor points at the sky.
The tool has several functions and the way you switch between these depend on what interaction and navigation mode is set. In the default mode, mouse buttons and the keyboard are used to switch between modes. Most of the functions can also be enabled or disabled using bool properties. It is also possible to switch to some of the modes manually by using the InteractionMode and NavigationMode properties.
Navigation
Interaction | Behavior |
|---|---|
Left-button and dragging | Moves the terrain relative to the camera, using the selected ground point as a handle. The camera altitude (unless modified by a ViewConstraints) and direction are unchanged |
Middle-button and dragging | Moves the camera up/down or sideways, but keeps it directed towards the selected ground point at a constant distance |
Right-button and dragging | Zooms in an amount based on how much the mouse is moved. Keeps the ground location in the same place on the screen. If there is no ground under the cursor, zooms towards the center |
Use scroll wheel | Zooming (continuous). Keeps the ground location in the same place on the screen. If there is no ground under the cursor, zooms towards the center |
Left-button double click | Zooms in a set amount. Keeps the clicked location in the same place on the screen |
Pressing Ctrl and left-button and dragging | Rotates the camera around its current position |
General Editing
Interaction | Behavior |
|---|---|
Let cursor hover over selectable feature | Replaces the default Cursor by the SelectFeature cursor (hover visualizers are applied) |
Left-button click on selectable feature | Selects the feature (selection visualizers are applied). |
Pressing Shift and left-button and dragging | Creates a rectangle and selects the features in it |
Left-button on a selectable feature and dragging | Moves the feature without modifying the Z coordinate |
Left-button click once on linepolygon node and dragging | Moves the node without modifying the Z coordinate. This operation requires a selection visualizer for the nodes. |
Pressing Alt and left-button click on a node in the selected linepolygon | The node is removed. This operation requires selection visualizers. One for the nodes and a LineVisualizer for the linepolygon |
Pressing Alt and left-button click on an edge of the selected linepolygon | A new node is added. This operation requires selection visualizers. One for the nodes and a LineVisualizer for the linepolygon |
Press Shift and left-button on selectable feature and dragging | The feature is moved vertically. |
Press Shift and left-button on selectable node and dragging | The node is moved vertically. |
Ellipse Editing
Ellipse interaction symbols are generated by the InteractionVisualizer. You can find information on setting up the interaction in Interacting with Ellipses.
Interaction | Behavior |
|---|---|
Left-button on center symbol and dragging | Moves the center |
Left-button on circle radius symbol and dragging | Changes the radius and direction |
Left-button on circle inner radius symbol and dragging | Changes the inner radius and direction |
Interaction | Behavior |
|---|---|
Left-button on center symbol and dragging | Moves the center |
Left-button on ellipse primary radius symbol and dragging | Changes the radius and the direction. The ratio is also changed so that the ellipse is only changed in one direction |
Left-button on ellipse secondary radius symbol and dragging | Changes the ratio |
Interaction | Behavior |
|---|---|
Left-button on center symbol and dragging | Moves the center |
Left-button on middle symbol and dragging | Changes the radius and the start and end angle of the sector so that the middle of the sector is where the cursor is |
Left-button on left symbol and dragging | Depending on the EllipseOperator.SectorDefinition, changes the radius and/or start angle and/or width of the sector |
Left-button on right symbol and dragging | Depending on the EllipseOperator.SectorDefinition, changes the inner radius and/or finish angle and/or width of the sector |
StandardTool3D is not supported on Android.
Inheritance Hierarchy
System.Object (not available in C#)
EngineObject
Tool
StandardTool3D
InspectTool3D
Platforms
Windows, Linux, Android
StandardTool3D Members
The StandardTool3D type has the following members.
Constructors
| Name | Description |
|---|---|
| StandardTool3D | Initializes a new instance of the StandardTool3D class. |
Properties
| Name | Description |
|---|---|
| EditEnabled | Gets or sets a flag indicating if the user can edit features with the mouse. |
| HotTrackingEnabled | Gets or sets a value controlling if the mouse cursor is changed when moving over a selectable feature. |
| InteractionMode | Gets or sets the tool interaction mode. Use this to override the default tool interaction. |
| IsDisposed | Gets a value that tells whether the current StandardTool3D has been disposed. Inherited from EngineObject |
| KineticScrollingEnabled | Gets or sets a flag indicating if kinetic scrolling is enabled. |
| MaximumEllipseRatio | Gets or sets a value indicating the maximum allowed EllipseOperator.Ratio when editing ellipses. The most useful case is when you want the axis that is along the EllipseOperator.Direction to always be longer than the axis that is defined by the EllipseOperator.Direction. You can then set the value of this property to 1.0. A value of 0.0 means that there is no maximum ratio. |
| MouseDoubleClickZoomEnabled | Gets or sets a flag indicating if the user may zoom the view by double-clicking the left mouse button. |
| MouseHysteresis | Gets or sets the maximum distance the mouse can be moved until a pan or move operation is started instead of a selection. |
| MouseInspectSpeed | Gets or sets a value indicating how fast the camera circles around a locked position. |
| MousePanEnabled | Gets or sets a flag indicating if the user may pan the view by dragging the mouse while holding the left mouse button. |
| MousePanSpeed | Gets or sets a value indicating how fast the camera pans around when the Control key is pressed. |
| MouseWheelZoomEnabled | Gets or sets a flag indicating if the user may zoom the view with the mouse wheel. |
| MouseWheelZoomSpeed | Gets or sets a value controlling the amount the view is zoomed in response to mouse wheel events. |
| MouseZoomEnabled | Gets or sets a flag indicating if the user may zoom the view by dragging the mouse while holding the right mouse button. |
| MouseZoomSpeed | Gets or sets a value controlling the amount the view is zoomed in response to mouse move events. |
| MultiSelectEnabled | Gets or sets a flag indicating if selecting multiple features using the mouse and control key is enabled. |
| NativeHandle | Gets the native Carmenta Engine kernel object the current StandardTool3D represents. Inherited from EngineObject |
| NavigationMode | Gets or sets the navigation mode. Use this to override the default tool navigation. |
| PointerRadius | Gets or sets the pointer radius for hit-testing. |
| SelectEnabled | Gets or sets a flag indicating if selecting features with the mouse is enabled. |
| ShowMarker | Gets or sets a flag indicating if the tool draws a marker in the 3D view, showing the zoom or inspect point. |
Methods
| Name | Description |
|---|---|
| Clone | Creates a copy of an object. Inherited from EngineObject |
| Dispose | Releases the reference to the native Carmenta Engine kernel instance the EngineObject represents. Inherited from EngineObject |
| Equals | Determines whether this instance is equal to another. Inherited from EngineObject |
| ITool.IsActive | Indicates if the tool is active with a user interaction. Inherited from ITool |
| ITool.OnConnect | Called when a tool is connected to the map control. Inherited from ITool |
| ITool.OnDisconnect | Called when the tool is disconnected from the map control. Inherited from ITool |
| ITool.OnKeyDown | Called when a key is pressed. Inherited from ITool |
| ITool.OnKeyUp | Called when a key is released. Inherited from ITool |
| ITool.OnMouseDoubleClick | Called when a mouse button is double clicked. Inherited from ITool |
| ITool.OnMouseDown | Called when a mouse button is pressed. Inherited from ITool |
| ITool.OnMouseMove | Called when the mouse is moved. Inherited from ITool |
| ITool.OnMouseUp | Called when a mouse button is released. Inherited from ITool |
| ITool.OnMouseWheel | Called when the mouse wheel is moved. Inherited from ITool |
Events
| Name | Description |
|---|---|
| Interacted | Occurs when a user completes (or aborts) an interaction. |
| Interacting | Occurs when a user interacts with features in a selectable layer. |
| Selecting | Occurs when user has clicked one ore more features and the tool is about to add them to the selection of the view. |