Interacting with Ellipses
Carmenta Engine can draw ellipses using EllipseOperator. This article explains what needs to be done to enable interaction with ellipses created in this way.
First, a summary of the classes involved:
EllipseOperator is an operator that takes a point and creates an ellipse polygon.
The tools CreateTool, CreateTouchTool, CreateTool3D and CreateTouchTool3D are used in your MapControl to create new ellipses.
The tools StandardTool, StandardTouchTool, StandardTool3D, StandardTouchTool3D are used in your MapControl to edit the ellipses.
EllipseCreateToolParameters contains settings that affect how an ellipse is created, and is attached to the CreateTool.
InteractionVisualizer generates "interaction handles" for the ellipses. It is through these handles that the user can modify the ellipses.
The map configuration sample ellipse_operator.px gives you an example of how this is done.
Configuration
In order to create ellipses that the user can interact with, your layer needs to contain an EllipseOperator with a MemoryDataSet as its input. Interacting with ellipses requires the EllipseOperator to have some of its properties set up as IndirectAttributeVariable<System.Double>. This enables the tools to set and read the attributes on the point feature that will be used by the EllipseOperator to generate the ellipse.
We have created a Carmenta Studio template to make it easier to set this up. Start Carmenta Studio and under the Classes tab in the upper left part of the application you can find the Templates folder. In this folder there is a template called CreateEllipseTemplate. Drag this template into the configuration area to add it to a px-file. A MemoryDataSet is created because that is the only dataset that works with the CreateTool and StandardTool.
The attributes you need to set up depend on what kind of ellipse you are creating. There are three types of ellipses available:
An ellipse is defined by a radius, direction and ratio.
A circle is defined by a radius and direction, and can also have an inner radius.
A sector is defined by a radius and two angles, and can also have an inner radius. What the angles mean depend on the EllipseOperator.SectorDefinition value.
You do not have to set up all of the properties if you have a constant value that you want to use. For Carmenta Engine to properly recognize what type a feature will create, some of the properties have to be set. For the Sector, which ones that need to be set up is dependent on the value of EllipseOperator.SectorDefinition.
This table shows what properties are used by which type. To enable editing of a property, it must be set up as an IndirectAttributeVariable<System.Double>.
X: Required to be set up and that the feature has the attribute key set.
O: Is used by the visualization and only needs to be set up if you want to be able to edit it.
Type | radius | innerRadius | direction | ratio | sectorStart | sectorFinish | sectorMiddle | sectorWidth |
|---|---|---|---|---|---|---|---|---|
Ellipse | O | O | X | |||||
Sector | O | O | O | X | X | X | X | |
Circle | O | O | O |
When using the CreateTool with Ellipses, you must make sure that the attributes used by the EllipseOperator corresponds to the ones used by the CreateTool. You can either use the default attributes (the CreateEllipseTemplate will set them for you), or customize them with EllipseCreateToolParameters. The default attributes are as follows:
Property | Default attribute |
|---|---|
radius | ellipseRadius |
innerRadius | ellipseInnerRadius |
direction | ellipseDirection |
ratio | ellipseRatio |
sectorStart | ellipseSectorStart |
sectorFinish | ellipseSectorFinish |
sectorMiddle | ellipseSectorMiddle |
sectorWidth | ellipseSectorWidth |
While the EllipseOperator can combine any of its properties, such as ratio and sector angles, the interaction support from Carmenta Engine only supports visualizing and editing these definitions of Ellipse, Circle and Sector. Do not set conflicting attributes from these types.
Creating
To create ellipses you need to use a CreateTool and set it on your MapControl. The dataset provided to the tool is the MemoryDataSet used as the input for the EllipseOperator.
After you have created an instance of CreateTool, the first thing to do is to set the CreateTool.CreateMode to Ellipse. The options for creating ellipses can be found in the EllipseCreateToolParameters class. If you create an instance of the parameters you can set it on the CreateTool.Parameters property. If you do not set any parameters, a default parameters class will be used and the settings will match the template we used earlier in Carmenta Studio. To be able to make changes to the options, you need to create an instance of the properties class and set it on the tool.
EllipseCreateToolParameters.EllipseCreateMode decides what kind of ellipse to create.
EllipseCreateToolParameters.HasInnerRadius decides if the tool sets an inner radius or not. Only applicable for Circles and Sectors.
EllipseCreateToolParameters.EllipseInteractionMode alters the way you create the ellipse. You can decide if you want to create ellipses and circles by clicking in the center, or by first placing a point on the circumference and then another point creating the diameter for the ellipse or circle. The point geometry feature will still be saved with its center point in both cases.
See CreateTool, CreateTouchTool, CreateTool3D and CreateTouchTool3D for information on how the user operates the tools.
Initial values
If you want to lock some of the values that the EllipseOperator uses, you can do so by setting them in the CreateTool.Attributes. The values will then be locked and can't be changed when using the CreateTool. If you have set all the attributes for a specific step in the creation process, that step will be skipped. If you for example want to create a sector where you already know the value for the radius, inner radius, and width, the tool will only require you to place the center point and then click in the direction you want the middle angle to be.
Visualizing
The created ellipse polygon can be visualized with a PolygonVisualizer and LineVisualizer. To create the symbol handles that will enable the StandardTool to interact with the ellipse, you need to add an InteractionVisualizer in the VisualizationOperator.SelectionVisualizers. Use the InteractionVisualizer.NodeVisualizer and InteractionVisualizer.GroundNodeVisualizer to visualize the handles. Each handle is tagged with an attribute value that you can use to customize the visualization. See InteractionVisualizer for more information on this.
The InteractionVisualizer.EllipseInteractionMode property works in the same way as the EllipseCreateToolParameters.EllipseInteractionMode to create the handles needed for the StandardTool to move the diameter points.
Editing
Editing ellipses is done by setting a StandardTool on your MapControl. It can then interact with the handles visualized with the InteractionVisualizer.
StandardTool.MaximumEllipseRatio can be used to limit the ratio of an ellipse. This can for example be used to make sure that the ratio axis will not be longer than the radius axis.
See StandardTool, StandardTouchTool, StandardTool3D and StandardTouchTool3D for information on how the user operates the tools.