3D Animation using lines. What is handle and mode in this code?

I have been trying to understand how to use some Matlab code that came with a book. It's meant to produce a 3D line-drawing of an object. Here is how it goes:

We start with labelling the points on the object and storing that information in XYZ:

function XYZ=spacecraftPoints
%define points on the spacecraft in local NED coordinates 
XYZ = [...
    1 1 0;...% point 1
    1 -1 0;...% point 2
    -1 -1 0;...% point 3
    -1 1 0;...% point 4
    1 1 0;...% point 1
    1 1 -2;...% point 5
    1 -1 -2;... % point 6
    1 -1 0;... % point 2
    1 -1 -2;... % point 6
    -1 -1 -2;... % point 7
    -1 -1 0;... % point 3
    -1 -1 -2;... % point 7
    -1 1 -2;... % point 8
    -1 1 0;...% point 4
    -1 1 -2;... % point 8
    1 1 -2;...% point 5
    1 1 0;...% point 1
    1.5 1.5 0;... % point 9
    1.5 -1.5 0;... % point 10
    1 -1 0;...% point 2
    1.5 -1.5 0;... % point 10
    -1.5 -1.5 0;... % point 11
    -1 -1 0;... % point 3
    -1.5 -1.5 0;... % point 11
    -1.5 1.5 0;... % point 12
    -1 1 0;...% point 4
    -1.5 1.5 0;... % point 12
    1.5 1.5 0;... % point 9
    ]';

We define the Euler angles as phi, theta and psi and north-east-down positions as pn,pe and pd. Then we write the following code for the rotation and translation of the object:

Rotation:

function XYZ=rotate(XYZ,phi,theta,psi)

%define rotation matrix

R_roll = [...
    1, 0, 0;...
    0, cos(phi), -sin(phi);...
    0, sin(phi), cos(phi)
    ];
R_pitch = [...
    cos(theta), 0, sin(theta);...
    0, 1, 0;...
    -sin(theta), 0, cos(theta)
    ];
R_yaw = [...
    cos(psi), -sin(psi), 0;...
    sin(psi), cos(psi), 0;...
    0, 0, 1
    ];
R = R_roll*R_pitch*R_yaw;
% rotate vertices
XYZ = R*XYZ;

Translation

    function XYZ = translate(XYZ,pn,pe,pd)
    XYZ = XYZ + repmat([pn;pe;pd],1,size(XYZ,2));

Then comes the bit where we are meant to produce the 3D drawing. This is where I am getting confused. The code for drawing goes like this:

function handle = drawSpacecraftBody(pn,pe,pd,phi,theta,psi, handle, mode)

%define points on spacecraft in local NED coordinates

NED = spacecraftPoints;

%rotate spacecraft by phi, theta, psi

NED = rotate(NED,phi,theta,psi);

%translate spacecraft to [pn; pe; pd]

NED = translate(NED,pn,pe,pd);

% transform vertices from NED to XYZ

R = [...
    0, 1, 0;...
    1, 0, 0;...
    0, 0, 1;...
    ];
XYZ = R*NED;

%plot spacecraft
if isempty(handle),
    handle = plot3(XYZ(1,:),XYZ(2,:),XYZ(3,:), 'EraseMode', mode);
else
    set(handle,'XData',XYZ(1,:),'YData',XYZ(2,:),'ZData',XYZ(3,:));
    drawnow
end

I can't seem to run this code because I am not sure what should I replace the "handle" and "mode" with in the input arguments of the drawSpacecraftBody.

Any suggestions?

Answer 1

[Sambit Senapati]

'mode' variable in the above code is used to specify the value of 'EraseMode' property for the 3D plot. Generally 'EraseMode' is set to 'none' to accumulate data in each frame of the picture. But Starting in R2014b, the 'EraseMode' property has been removed from all graphics objects. Go through this link, where other methods to animate is specified.

Now in your code do the following change:

function handle = drawSpacecraftBody(pn,pe,pd,phi,theta,psi, handle)
%define points on spacecraft in local NED coordinates
NED = spacecraftPoints;
%rotate spacecraft by phi, theta, psi
NED = rotate(NED,phi,theta,psi);
%translate spacecraft to [pn; pe; pd]
NED = translate(NED,pn,pe,pd);
% transform vertices from NED to XYZ
R = [...
    0, 1, 0;...
    1, 0, 0;...
    0, 0, 1;...
    ];
XYZ = R*NED;
%plot spacecraft
if isempty(handle),
    handle = plot3(XYZ(1,:),XYZ(2,:),XYZ(3,:));
else
    set(handle,'XData',XYZ(1,:),'YData',XYZ(2,:),'ZData',XYZ(3,:));
    drawnow
end

Now pass the 'handle' variable as an empty array as follows:

>> drawSpacecraftBody(1,1,1,pi/4,pi/4,pi/4, [])

Here I have set pn=pe=pd=1 and phi=theta=psi=pi/4.

[Mahmud Khan]

Hello Sambit,

Thank you so much for your detailed answer. If I understood you correctly, from now on, I shouldn't use EraseMode in my code as long as I am using a version of Matlab 2014b or the ones that came later. I made the modifications you suggested and got the result I was looking for:

I have a question about how you called the function. Did you pass it an empty handle with "[]"? Also, why do we put a space between the "," and handle or mode in functions? for example:

function handle = drawSpacecraftBody(pn,pe,pd,phi,theta,psi, handle)

Every input from pn to psi are typed back to back while we include a space after the final "," and before "handle". Is that necessary? Why so?

[Stephen23]

"Did you pass it an empty handle with "[]"?"

No, [] is an empty numeric array. That code only checks to see if handle is empty, it does not matter what class the empty handle has.

https://www.mathworks.com/help/matlab/math/empty-matrices-scalars-and-vectors.html

"Also, why do we put a space between the "," and handle or mode in functions? Is that necessary?"

No, it is optional. It has no meaning in this context.

[Mahmud Khan]

@Stephen Cobeldick

Thanks for the clarification :)