9.1.4 General Ellipses

The General Ellipse is a geometric primitive that can be thought of as a generalized elliptical helix. It is directly supported in the SP-ICE-3 Card's firmware, from version 3.3.3 onwards, via the SP-ICE-3 ClientLib API method AppendGeneralEllipse.
Note in particular that, in contrast to the Ellipse primitive, the General Ellipse supports arbitrary spatial placement in any orientation.

A General Ellipse is specified by the following parameters:

An arbitrary starting position S.
A continous sweep parameter ω, which may be negative, and defines the number of turns (not the angle in radians) around the center axis of the General Ellipse.
Thus, for instance, the value 1 means exactly one whole turn around the axis.
A (3 × 3) transformation matrix M,
or equivalently 3 column vectors u, v, w.

We first consider parameters for the Standard form of the General Ellipse, before applying further transformations to cover more complex forms.

Standard form of the General Ellipse

A standard general ellipse is one where M is an identity matrix, and S is at the origin.

The path described is simply a standard helix centered at (-1, 0, 0) with unit radius and height 1.

The projection of this helix on the Z = 0 plane is called the base ellipse of the general ellipse.

The standard general ellipse with ω = 1 looks like this:

The mathematical definition of its trajectory is given by the image of the function:

f(t) = (cos(2πωt) - 1, sin(2πωt), t)^T
where
- 0 ≤ t ≤ 1
Note in particular:
- We subtract 1 from the cosine of the x coordinate, so that the curve starts at the origin of the coordinate system.
- The curve is contained in the box [-2,0] × [-1,1] × [0,1].

Complex forms of General Ellipse

The complex forms are derived from the standard form, as described above, by applying a linear transformation M to f , and translating by S.

The trajectory can be described by

(M • f(t)) + S
where
- f is the trajectory function for the standard general ellipse (see above)
- 0 <= t <= 1
S is the starting location of the helix.
In practice, it is implicitly determined by the end position of the preceding scanner movement command.

Alternative Interpretations of the Transformation Matrix

If we regard M as three column vectors u, v, and w, some alternative geometrical interpretations of the transformation are possible:

u is the vector from the center C of the general ellipse to the starting point S.
Conversely, -u points from S towards C .
v and u together define the plane of the base ellipse.
Another interpetation is that this vector determines the start "velocity" of the planar ellipse at S, i.e. it is parallel to the trajectory of the base plane ellipse at the beginning, and its length determines the width of the ellipse in that direction.
w is the axis along which the helix develops.
For a flat ellipse with no helix development, set this vector to 0.

It is not necessary for any of the three vectors to be perpendicular to each other, or even to be non-zero.
Consequently, it is also possible to parameterize the general ellipse to produce flat ellipses, "wobbling" or "spiraling" lines, and even sine curves.

General Ellipse Parameters for Selected Special Cases

In this section, some special cases of general ellipses are examined and explained, to help you choose the correct parameters for your application.
Any of these cases can be further customized by applying a suitable additional transformation to the GeneralEllipse's matrix M.

Standard General Ellipse

The standard general ellipse, as described above, uses these parameters:

M = I₃
or equivalently:
u = (1, 0, 0)^T
v = (0, 1, 0)^T
w = (0, 0, 1)^T

Planar Axis-Aligned Ellipse

To define a simple ellipse in the X,Y plane with dimensions x and y, and the scanner starting at S, use the following parameters :

u = (x/2, 0, 0)^T
v = (0, y/2, 0)^T
w = (0, 0, 0)^T

If we additionally set w = (0, 0, z)^T, a helix with axial length z will be marked along the axis normal to the center of the base ellipse.
In fact, w can be any arbitrary vector, so we can generate a slanted helix in the direction of w if we wish.

Circle about a Normal Vector in 3D Space

Arguably the simplest form of GeneralEllipse is a circle.
Given:

A position C for the center of the circle.
A unit normal vector n pointing away from the desired circle.
An arbitrary starting position S for the scanner.

We can to define a full circle by setting

ω = 1 , u = CS , v = CS × n , w = 0 (where × denotes the cross product)

Circular Arc about a Normal Vector in 3D Space

With otherwise the same parameters as in the previous example, we simply set

0 < ω < 1

i.e. some fraction of a whole circle.

Flat Ellipse in 3D Space

From a scanner position S we wish to mark a flat ellipse about center C, with its second axis defined by vector b.

We set these parameters:

ω = 1 , u = CS , v = b , w = 0

Elliptical Helix in 3D Space

Using the flat ellipse of the previous example as a base, we can produce a helix for a distance d along the axis normal to the center C of the ellipse.

We define

n = u × v (where × denotes the cross product)

and then set

w = d * (n / |n| )

The sign of d determines the direction in which the helix is produced from the plane of the ellipse.
The magnitude of d determines the axial length of the helix.
Furthermore, by setting ω ≠ 1, we can determine how often the helix winds around the center axis.

Sine Curve in 3D Space

Given:

A starting location S for the scanners.
A target location T for the scanners.
A vector a, perpendicular to ST representing the amplitude.

We can generate a sine curve between S and T by setting

u = 0 , v = a , w = ST

The number of cycles in the curve between S and T may be defined by setting the sweep parameter ω appropriately.

We can also make the sine curve start with some arbitrary phase φ by setting:

u = sin(φ) . a
v = cos(φ) . a
w = ST

Calculating General Ellipse Matrix Parameters from Legacy Ellipse Parameters

Given the legacy representation of parameters for an Ellipse:

the starting position of the scanners on the ellipse, S,
the position of the center of the ellipse, C,
the ratio of the axes of the ellipse, r,
the angle of rotation of the major axis, φ,

it is possible to compute the corresponding general ellipse representation.
To this end we define:

a = S - C
c = cos(φ)
s = sin(φ)

The equivalent matrix for the general ellipse is then:

SP-ICE-3 General Ellipse Equiv Params M Matrix

Explanation

We can compute the equivalent matrix parameters for a general ellipse using linear algebra.

The u and w vectors of the general ellipse's matrix M can be computed quite simply:

u = (X_S - X_C, Y_S - Y_C , 0 )^T
w = (0 , 0 , Z_C - Z_S )^T

However, for v the computations are somewhat more complex.

Considering the XY-plane, and noting that legacy ellipses never expand in the Z direction, we need essentially to find the direction in which the scanner starts moving, as projected on to the plane of the base ellipse.

To compute this direction, we could try to work out how to tranform the ellipse into a circle (not necessarily a unit circle), since, for the circle, we know that the direction of initial movement will be perpendicular to the vector to the starting location.

However, it is easier to start with a circle and transform it into our ellipse, and then use the inverse transformation when calculating v.
First we stretch the Y-axis of the circle by r, and then we rotate it by φ, thus:

Hence T⁻¹ represents the inverse transformation from the circle to our ellipse, and it can be used as follows:

We apply T, which turns our ellipse into a circle.
We rotate by 90° (to obtain the perpendicular to a) using the matrix R:
We transform the circle back to our ellipse coordinates by applying T⁻¹.

Our equation for v is thus:

v = TRT⁻¹a

By simplfiying and substituting, we obtain the formulae for the x and y coordinates of v shown in M, above.

Example: Marking a Standard General Ellipse.

Note
Boilerplate code is omitted from this example for brevity: please refer to 12.3 Example Code in this Manual.

Marking a standard general ellipse.

Copy

using ( ClientAPI client = new ClientAPI() )
{
    try
    {
        client.Connect( CardIP );
        client.System.ResetToDefaults();

        // define the starting point S
        double Sx = 0;
        double Sy = 0;
        double Sz = 0;

        // 
        // For this example, we choose to make the general ellipse fairly small compared to the available marking field.
        // 
        // Note how we use the (pre-)configured size of the marking field:
        double sizeX = client.Scanner.GetConfig().FieldSize.X / 10;
        double sizeY = client.Scanner.GetConfig().FieldSize.Y / 10;
        double sizeZ = client.Scanner.GetConfig().FieldSize.Z / 10;


        // Define the general ellipse's transformation matrix.
        // Note how we use Point3D to represent the transpose of a column vector.
        // For the standard ellipse, the centre point C lies in the negative half-plane relative to the starting point S. 
        Point3D u = new Point3D( -0.5 * sizeX,           0,            0 );
        Point3D v = new Point3D(            0, 0.5 * sizeY,            0 );
        Point3D w = new Point3D(            0,           0,  0.5 * sizeZ );

        // define the number of turns for the general ellipse's helix
        double turns = 1.0;

        double jumpSpeed = 1.0;
        double markSpeed = 0.1;

        CommandList list = new CommandList();

        // Append process parameter values to the List:
        list.AppendJumpSpeed( jumpSpeed );
        list.AppendMarkSpeed( markSpeed );

        // Append vectors to the List:
        // 
        // move to the start of the arc at S
        list.AppendJumpAbs( Sx, Sy, Sz );
        // 
        // mark the general ellipse
        list.AppendGeneralEllipse( u, v, w, turns );

        int listID = 0;
        client.List.Set( listID, list );

        client.Laser.ArmLaser( true );

        client.List.Execute( listID );

        // obviously, the timeout has to be appropriate for the marking speed, etc.
        int timeoutMs = 1000;

        int? doneID;
        if ( !client.List.WaitForListDone( out doneID, timeoutMs ) )
        {
            throw new ListException( "Timed out waiting for ListDone." );
        }
        if ( doneID != listID )
        {
            throw new ListException( "Got ListDone for wrong listID!" );
        }
    }
    catch ( Exception ex )
    {
        // 
        // TODO:
        // Define suitable error handling for your application.
        // 

        Console.WriteLine( "Uhhh, Houston? We've had a problem...{0}", ex.ToString() );

    }
}