3D Copilot Manual

Introduction
Polestar Functions
Drag and Quickview Specifications
Quickview Functions
Recording Copilot Motion
Examples

1. Introduction

A copilot consists of handles and feedback in the graphics area that make it simple and staightforward to specify geometrical intent. The copilot enables intuitive direct manipulations on objects and reduces the need to interact via UI controls in a separate window.

A copilot consists of the following 3 components

Polestar: A polestar contains selectable handles that can be placed and oriented anywhere in the graphics window. It can consist of line, circular, ring, disc area and sphere components.
The images below illustrate a polestar, containing the major types of components, and a circular polestar.

When a user selects a polestar component, a predefinable pick token and a pick point are issued to the input buffer. These inputs are received by the currently active dialog.

The pick token typically activates a dialog variable. That dialog variable then receives the pick point which then initiates the dragger. The geometrical properties of the selected polestar can be inquired and exploited in the code attachments of the activated variable, e.g. in :before-input. On completion of the drag, the :after-input code of the entered variable is excecuted.

A pick on a polestar component contains much more information than is available by using simple UI controls such a buttons, checkboxes, ranges and input fields.

A set of functions are provided to create, inquire and destroy a polestar.
Dragger: A dragger generates feedback that moves along a constrained path as the mouse cursor moves freely. Typical constrained paths are along a linear direction, a circular curve or within a plane.
The state of the drag motion is displayed by appropriate drag feedback. The images below illustrate linear, planar and circular drag feedback:

The blue point marks the initial drag position while the yellow point represents the current drag value. The current drag position is displayed numerically in a cursor text window that moves in sync with the mouse cursor.

It is possible to attach the polestar and a quickview to the constrained drag motion.

The dragger can be specified by adding drag options to a dialog variable. Such a variable is called a drag variable.

The dragger feedback is activated as soon as the drag variable is entered and a pick point is received. Thus, for example, a pick on a polestar component can activate a drag variable which then immediately generates drag feedback in the graphics window.
Quickview: A quickview is a feedback object that is updated instantaneously during the drag motion. It displays the result of the drag operation in a quick but possibly approximate way.
The image below illustrates a predefined quickview called :extrude-profile.

Several other predefined quickviews are supported. Furthermore, arbitrary quickview feedback can be created by means of LISP application code.

A quickview can be obtained by adding quickview options to a drag variable.

The quickview is automatically generated as soon as the drag feedback is created. Further functions are provided to create, inquire and delete quickview feedback.

The polestar or the dragger can be omitted from the copilot, but one of the two must be present.

2. Polestar Functions

The following functions can be used to create, inquire, activate, deactivate and delete a polestar.

sd-create-polestar
sd-delete-polestar
sd-classic-polestar-components
sd-inq-polestar-pick
sd-activate-polestar
sd-deactivate-polestar
sd-inq-profile-center
sd-get-visible-profile-pnt
sd-get-picked-polestar

SD-CREATE-POLESTAR [function]

(sd-create-polestar :pick-token      pick-token
                    :origin          origin
                    :dir             dir
                    :forward-picking boolean
                    :no-vport-pick   boolean
                    :components      components)

Description:

Creates a polestar using the specified polestar component specifications.

Polestars are automatically managed in the following ways:

The polestar is automatically deleted when the dialog terminates. Alternatively, it can be deleted at some earlier time by means of the function sd-delete-polestar.
The polestar is automatically deactivated during
- a drag motion that was initiated from that polestar, and during
- the interruption of the dialog by an interrupt dialog.
In the first situation the polestar colors are not changed. In the second situation, the colors of the polestar are changed to grey.
This deactivation ensures that polestar pick tokens do not terminate the drag and are not sent to wrong dialogs.

Warning: In order to obtain the above built-in polestar management, the polestar must be created in sync with the dialog, e.g. in forms like :before-input and :after-input or in functions called from these forms. Polestars used within a dialog should not be created outside the scope of the dialog, e.g. in a subaction called by the dialog. In particular, polestars should not be created in a :feedback-update-function, since this option is executed while the drag subaction is active. Furthermore, polestars should not be generated in UI-related forms, such as :after-input-ui.

Parameters:

Pick-Token {STRING [no-effect]}

Default pick token for the polestar components.
This argument can be omitted if each polestar component contains a :pick-token specification.

Origin {3D VECTOR [no-effect]}

Default origin of the polestar components.
This argument can be omitted if a polestar component contains an :origin specification (see below).

Dir {3D VECTOR [no-effect]}

Default direction of the polestar components.
This argument can be omitted if each polestar component, that requires a :dir, has a :dir specification.

Forward-Picking {BOOLEAN [NIL]}

Forward picking controls the direction that is generated when a polestar is picked. When this option is set to T, the polestar pick data will contain a direction towards the pick point rather than the direction in the polestar.

This argument is optional.

This option is useful when picking on one of the linear arrows of a classic polestar, resulting in directions that point out from the polestar center. (see Co_View dialog).

The default NIL generates the same polestar pick direction that was supplied when the polestar was created.

No-Vport-Pick {BOOLEAN [NIL]}

If this option is set, a click on the polestar or one of its components does not generate a pick in the viewport. Just the :pick-token is sent to the input buffer.

Components {LIST of PLISTS}

This argument specifies the individual components of the polestar. Each component is specified by a property list. Options that have default values are optional.

     ((:type :line 
         :pick-token     string    ; default=default pick-token
         :origin         3d-vector ; default=default origin
         :dir            3d-vector ; default=default dir
         :forward-arrow  boolean   ; default=t
         :backward-arrow boolean   ; default=t
         :mid-disc       boolean   ; default=nil
         :forward-only   boolean   ; default=nil
         :label          string    ; default=nil
      )      
      (:type :arc
         :pick-token     string    ; default=default pick-token
         :origin         3d-vector ; default=default origin
         :dir            3d-vector ; default=default dir
         :mid-help-pos   3d-vector
                         ;The vector :mid-help-pos H is projected onto the
                         ;axis giving point C, the center of the arc.
                         ;The direction H-C is used as the direction
                         ;towards the middle of the arc (where the disc
                         ;is drawn). The actual position of this disc
                         ;depends on the viewport scale.
         :forward-arrow  boolean   ; default=t
         :backward-arrow boolean   ; default=t
         :mid-disc       boolean   ; default=nil
      )      
      (:type :disc
         :pick-token     string    ; default=default pick-token
         :origin         3d-vector ; default=default origin
         :dir            3d-vector ; default=default dir
      )
      (:type :ring 
         :pick-token string        ; default=default pick-token
         :origin     3d-vector     ; default=default origin
         :dir        3d-vector     ; default=default dir
      )
      (:type :model-ring  ;This component is intended to be generated
                          ;only via the function sd-classic-polestar-components 
         :pick-token string        ; default=default pick-token
         :center     3d-vector
         :dir        3d-vector     
         :mid-dir    3d-vector     ; direction from the ring/arc center
                                   ; towards the pick point.
                                   ; When a model ring is not a full circle
                                   ; (this depends on the view scale at 
                                   ; creation time) the mid point of the arc
                                   ; is generally placed at the picked point.
                                   ; However, because the radius can vary
                                   ; supplying the mid point is more general.
         :radius     number      
      )
      (:type :sphere 
         :pick-token string        ; default=default pick-token
         :origin     3d-vector     ; default=default origin
      )
     )

Each component can overwrite the default :pick-token, :origin and :dir values - whenever applicable.

However, there is a restriction for the :origin specifications: all component origins must be equal. If a default origin is specified, then the individual component origins are ignored and replaced by the default origin. If no default origin is specified, then all component origins must be equal. If not, the first specified component origin is used for all the other components.

When a user clicks on a polestar component, usually two inputs are sent to the input buffer:

the :pick-token associated with the picked component, followed by
the pick point.

If the option :no-vport-pick is set, no pick point is generated.

The :pick-token can be used to activate a dialog variable. That dialog variable then receives the pick point. The receiving variable must be designed to receive a pick point and should be either

a drag variable (i.e. a variable that contains drag options) that eats the pick, or
a variable with an appropriate value type, e.g. :point-3d-pick.

Note: If the :pick-token string starts with a left parenthesis (, the string will be evaluated before the evaluation result (has to be a string or a keyword) is sent to the input buffer. That way you can execute some LISP expression which determines the pick-token at runtime.

The details of the picked polestar component can be inquired within the dialog by means of the function sd-inq-polestar-pick

Return Value:

A polestar structure if the polestar creation was successful or nil if it was unsuccessful.

Example:

(sd-create-polestar
  :components
    (list (list :type       :line
                :dir        1,0,0
                :origin     0,0,0
                :pick-token ":DISTANCE" )
          (list :type       :line
                :dir        0,1,0
                :origin     0,0,0
                :pick-token ":DISTANCE")))

where a dialog variable called DISTANCE is assumed to exist.

3D Copilot Manual

1. Introduction

2. Polestar Functions

SD-CREATE-POLESTAR [function]

SD-DELETE-POLESTAR [function]

SD-CLASSIC-POLESTAR-COMPONENTS [function]

SD-INQ-POLESTAR-PICK [function]

SD-ACTIVATE-POLESTAR [function]

SD-DEACTIVATE-POLESTAR [function]

SD-INQ-PROFILE-CENTER [function]

SD-GET-VISIBLE-PROFILE-PNT [function]

SD-GET-PICKED-POLESTAR [function]

3. Drag and Quickview Specifications

3.1. Overview

3.2. Drag Options

3.3. Quickview Options

4. Quickview Functions

SD-INQ-QUICKVIEW [function]

SD-MODIFY-QUICKVIEW [local function]

SD-DELETE-QUICKVIEW [local function]

SD-CREATE-QUICKVIEW [local function]

SD-GET-QUICKVIEW [local function]

5. Recording Copilot Motion

6. Examples

6.1. View Copilot

6.2. Extrude Copilot

6.3. Parcels Copilot

6.4. Cable Copilot