Creating Handles

Introduction

Handles allow users to edit the value of the selected object's attributes in the 3D view. They are created by adding a @Handle annotation to an attribute.

Handles can be enabled or disabled for the current scene in the Preferences dialog, under the heading Scene. By default handles are enabled.

Examples


The above handles were created using the following attribute annotations:
@Handle(shape=Cube, axis=y)
attr height = 30

@Handle(shape=Cube, axis=x)
attr width = 30

@Handle(shape=Cube, axis=z)
attr depth = 30

Lot -->
	s(width, 0, depth)
	extrude(height)
	Cube

The option shape=Cube specifies a shape in the model to attach the handle to, while axis= specifies a scope-specific direction for the handle.

Thin gray extension lines connect the handle to the shape that it is measuring.

Handles can be applied to a wide range of objects.

The above handle was created using the annotation:

@Handle(shape=TreeCenter, axis=y, reference=center, slip=screen)
attr height = 30

The advanced options reference= and slip= specify the handle's position and movement as the camera moves. In this case the height handle rotates smoothly around the tree with the camera.

Handles that do not move with the camera can also be created, for example:

@Handle(shape=TreeCenter, axis=y, reference=origin, slip=inside, occlusion=false)
attr height = 30

Adding many handles, or adding handles to complex models may lead to low framerates on low-end hardware.

General Options

The default options in the below table are marked with an asterisk. If any option is omitted, the default value is taken. The only option that must be specified is shape=.

OptionDescription
shape=

shape_name^argument_count

where shape_name is given by the name of the rule that created the shape, and argument_count is the number of arguments that the rule takes.

If ^argument_count is omitted, ^0 is assumed. An asterix allows referencing anonymous leaf shapes, e.g.: shape=Box*^3.


type=

linear*|move|angular|toggle|selector|color

Selects the type of handle to create. Handles with a linear type are used for editing float values that represent distances. The move type is used for editing float values that represent positions, in contrast to the linear type the handles are always shown at a constant length. The angular type is for float attributes that represent angles, the toggle type for boolean attributes, selector type for attributes with the @Enum annotation, and color for editing color string attributes.

Linear

Move

Angular

Toggle

Selector

Color

Additional options specific to each type are given below.


align=

topLeft|left|bottomLeft|bottom|bottomRight|right|topRight|top|default*

Selects a screen direction as the offset direction preference for a reference handle. default selects the nearest location outside of the model's silhouette.


linear example of align=left


linear example of align=right


toggle example of align=topLeft


toggle example of align=right

slip=

scope*|screen|inside

This option specifies the way in which reference handles may be moved outside the model's silhouette. slip=scope moves the handle in directions given by the scope axes, slip=screen moves the handle parallel to the camera, and slip=inside disables the offsetting behvior.

Different slip= are appropriate for different shapes. For example the length of cylindrical objects is best specified using slip=screen, while the dimensions of a cuboid should use slip=scope.

In the below image we see that slip=scope causes the handle to align itself to the edges of the scope as the camera moves. In contrast slip=screen maintains a constant offset direction, independent of camera location.


Left, middle: slip=scope, right: slip=screen

It is recommended that cuboid objects use slip=scope, while cylindrical or spherical objects will use slip=screen. While it is possible to use either of these options in any case, following these recommendations presents a consistent and intuitive interface to users.


repeat=

chain*|none

Chained handles will be clustered into a single continuous chain. Linear handles of several different attributes with the same orientation may be grouped onto one chain if there is sufficient space.


Left: repeat=chain, right: repeat=none

If repeat=none, CityEngine determines an appropriate location for a single handle, preferring locations with short extension lines, and long linear handles.


minDisplaySize=

pixels

If the size of a handle is below pixels, it is not shown. Users can override this behaviour by pressing the command key (OS X) or control (PC / Linux).

The size of a handle with linear type is the screen-length. The size of an angular handle is the distance between the zero degrees, and the handle. The size of toggle, selector, or color handles is the screen length of the shape's scope's shortest edge.


extensionLines=

scope*|silhouette|fade|off

Specifies the style of the extension lines associated with a handle.


Clockwise from bottom right: extensionLines=scope, extensionLines=fade,
extensionLines=off
and extensionLines=silhouette.

The below image shows typical use cases for the different extension line types. Scope (left) is used to highlight embedded features, silhouette (middle) with obvious features to avoid cluttering the geometry, and fade (right) for irregular shapes.


translate=

{translate_x,translate_y,translate_z}

Gives a scope-relative translation of the handle. For example translate={3,0,0} translates the handle by 3 * scope.sx in the direction of the scope's x axis.


occlusion=

true*|false

Enables or disables occlusion queries for the handle. When enabled handles are only shown when their reference positions are visible. However, for complex models this may cause the handle to flicker. Using occlusion=false will resolve this issue, and never hide the handle because of occlusion.


color=

hexCodeString

Normally the color of handles is given by the viewport hightlight color. color= allows users to override this behavior with the preferred color, hexCodeString for the handles as an RGB hex code string within quotes, for example color="#ff0000".


The vertical linear handle uses the parameter color="#ffff00", the horizontal linear handle color="#33ff33", the selector handle color="#ff0000" and the toggle handle color="#33ffff".

Linear Type Options

Linear handles are assumed to be associated with a scope edge. The length of the linear handle is given by the scope edge specified by axis.

OptionDescription
reference=

edges*|center|origin|radial

Specifies the location of the reference handles. In the below images, the shape origin is at the right of the cube.

Note that the location of radial handles depends on the camera position.

reference=edges

reference=center

reference=origin

reference=radial

These reference handles are moved to their offset position using direction given in the slip= option.

Typical use cases are reference=edges for boxes or cuboid geometry (as shown in the first example on this page), reference=center for the length of cylindrical or spherical objects (such as the tree's height in the second example), reference=radial for the width of cylindrical objects (such as the dead tree model above), and finally reference=origin when a feature is one dimensional, or when the exact position of a handle must be specified.


axis=

y*|x|z|x-|y-|z-

Selects the shape's scope axis to position the handle along. A negative axis reverses the direction of the handle.


skin=

doubleArrow*|diameterArrow|sphere|hemisphere

Linear handles have several options for the rendering of terminators. These options do no change the behavior of the handle, with the exception of skin=diameterArrow, which scales symetrically about its center when dragged.


skin=doubleArrow


skin=diameterArrow


skin=sphere


skin=hemisphere

Move Type Options

Move handles are similar to linear handles, and are also associated with a scope edge. However, the length of the move handle is always constant, in contrast to linear handles where it is given by the scope edge. When dragging one end of the handle, the other end also moves by the same amount. This makes them suitable for attributes representing positions or offsets.

axis and skin are similar to linear handles. For reference, only center and origin is supported. Also, the slip value is restricted to inside.

Angular Type Options

Angular handles allow the user to manipulate angles. Typically a combination of axis= and translate= are used to position the handle in the appropriate location. By default, angular handles do not offset themselves, that is slip=inside. This behavor can be altered by specifying another slip=.

OptionDescription
reference=

edges|center*|origin

Specifies the location of the reference handles. In the below images, the shape origin is in the bottom right of the screen.


reference=edges


reference=center


reference=origin

axis=

y*|x|z|x-|y-|z-

Selects the shape's scope axis to position the angular handle's origin along. A negative axis reverses the direction of rotation.


The red, green and blue lines are the x, y and z axes. For example axis=x rotates around the x axis towards the z axis. The angular handles each have an attribute value of 30 degrees.

skin=

doubleArrow*|ring

Rotational handles have two skin options: doubleArrow or ring.


skin=doubleArrow


skin=ring

Toggle, Selector and Color Type Options

Toggle, selector and color types share layout options.

OptionDescription
reference=

edges|center*|origin|radial

Specifies the location of the reference handles. In the below images, the shape origin is in the bottom right of the screen.

Note that the location of radial handles depends on the camera position.

reference=edges

reference=center

reference=origin

reference=radial

axis=
if slip=scope

x|y*|z|xy|xz|yz

Specifies the directions in which the handle may move when slip=scope. For example handles with the option axis=xy may move along the x or y axes.


Left: the reference position for the toggle handle at the origin, and the three axes. Middle: axis=x, the handle can move alone the x axis. Right: axis=xy, the handle can move along the x or the y axis to find the best location.


axis=
if slip=screen

x|y*|z

In the case of slip=screen the handle moves in the same manner as a linear handle with the same axis parameter.


axis=
if slip=inside

axis= does not affect the placement of the handle if slip=inside.

 

Copyright ©2008-2017 Esri R&D Center Zurich. All rights reserved.