Fictive path calculation issue

[LeonieCK]

Hello! I just wanted to raise an issue about the Fictive path output of Fictrac, in case it is useful to other Fictrac users. You have to take into account your configuration (with positive and negative signs of the x,y z axis), otherwise your fictive path output could be wrong. For this reason, I think it is better to calculate the fictive path by manually (see below), rather than use the output of column 15 and 16 in the dat file.

Fictrac outputs the fictive path, the fly’s XY position, rotated by its heading direction (Z), using Moore et al equation 6 and 7. The fictive path could in theory be plotted along any coordinate system (i.e. forward walking could be north,east, south or west). However, some confusion may arise because of the naming of intX and intY (column 15 and 16 in the output dat file) – if you plot intX on the x axis, and intY on the Y axis, forward walking is actually rightwards (positive values along the x axis). Also, the equation doesn’t take into account differences in the sign of the X and Z values (which can be negative or positive depending on the camera configuration).

To get around this, instead of using Fictrac column 15 and 16, we can calculate the fictive path ourselves, using the Moore equations. I I made a matlab function (see below); getFictivePath.m, where : • Positive values of X must be rightward sidestepping (mine is opposite, so I need to multiply the vector X by -1 first,before inputting to the function). • Positive values of Z must be rightward turning • Positive values of Y must be forward walking

Note: the output will plot forward walking going EAST, and right turning/sidestepping going SOUTH. If you want to plot forward walking going NORTH, you will need to multiply the output by a rotation matrix. To obtain the ground truth for your set up, it is good idea to check the fictive path by adjusting the x,y,z values manually to (e.g. to 0s and 1s) to check the path is moving in the expected directions for each axis, because the signs equation may need to be adjusted according to whether X and Z positive values correspond to left or right movement.

I hope this makes sense and is useful to anyone using Fictrac.

function Pxy= getFictivePath(X,Y,Z) numframes=length(X); % 1. Integrate turning (z rotation) to get animal's current heading (Moore eqn6) Zc=zeros(numframes,1); for k=3:numframes Zc(k)=Zc(k-1)-Z(k); %negative because fly turns opposite way to ball end

% Obtain the animal's fictive path (xy position, rotated by current heading (Moore Eqn 7)
Pxy=zeros(2,numframes)';
Theta=Zc;
for k=3:numframes
    Pxy(k,:)=Pxy(k-1,:)+([cos(Theta(k)),-sin(Theta(k)); sin(Theta(k)),cos(Theta(k))]*[Y(k);-X(k)])'; %moore equation

end

end

[LeonieCK]

The function can also include a rotation matrix, to set walking straight ahead as NORTH, and side-stepping/turning to the right as EAST.
% 3) Implement rotation matrix coordT=Pxy; %GET X AND Y TO ROTATE %ROTATION theta=90; %TO ROTATE COUNTERCLOCKWISE BY X DEGREES R=[cosd(theta) -sind(theta); sind(theta) cosd(theta)]; %CREATE THE MATRIX rotcoord=coordT*R'; %MULTIPLY VECTORS BY THE ROT MATRIX Pxy=rotcoord; %Output final position.

[rjdmoore]

Hi @LeonieCK , thanks for your contribution.

If there is a bug in the code, it should be fixed, but I don't fully understand the issue you describe. FicTrac should compute the fictive path (i.e. integrated X,Y position of the animal - cols 15,16 in the output) in the lab coordinate frame, which should be set up such that X is forward for the animal, Y is to animal right, and Z is animal down assuming the animal is on top of the ball. As you say, if you plot the fictive path, forward motion will be along the +ve X axis and side-stepping to the right will be along the +ve Y axis. On a regular cartesian axis this will give animal forward motion to axis right and righthand turns will be counterclockwise. To plot such that forward motion is 'upwards' on a cartesian axis, with righthand turns clockwise, you should just swap X and Y before plotting.

Is this the effect you describe or is there a further issue in the code? FicTrac should (correctly) handle any camera position with respect to the trackball - this just has to be configured during setup.

[LeonieCK]

Hi @rjdmoore , Thanks very much for your response

My configuration set up is such that the camera is horizontal to the fly on its right side. So during the config set up, I use option 3 and set the points as suggested (TR,TL,BL,BR). In the config image, my X points to the right, Y into the image, and Z down (with a circle mark for Y and Z, and a cross mark for X). In my output file in cols 6-8, this corresponds to positive X vals as rightward ball rotation ( left sidestepping), positive Y vals as backward ball rotation (forward walking) and positive Zvals as leftward ball turning (animal turning right). I think for Fictrac output of cols 15 and 16 to be correct, my Y and Z values are fine but my X values need to be flipped. Does that sound correct to you? Thanks very much for your help!

[rjdmoore]

I had further communication with @LeonieCK outside this thread and the issue is now resolved, but I will summarise here for the benefit of anyone with a similar query.

Unfortunately, the documentation on the various coordinate frames used by FicTrac can be easily misinterpreted. To help with this, I have created a new documentation page on coordinate frames doc/coordinate_frames.md.

The output data from FicTrac is correct and the system can be configured for a camera in any orientation, but it is important to check the generated configImg to make sure that the animal's axes have been configured correctly.

Naively plotting the fictive path generated by FicTrac (output data cols 15-16) on a regular cartesian axis can also lead to confusion. FicTrac fictive path is generated in the NED (north-east-down) coordinate frame, so that pure forward animal motion will map to a fictive path in the +X direction, and pure sidestepping to right will map to +Y. Whereas the cartesian axis is ENU (east-north-up), with +X to the right and +Y up. Thus simply plotting the fictive path directly will cause the path to be rotated by 90 degrees and flip clockwise rotations to counterclockwise.

To plot the fictive path correctly, you should simply switch X and Y during plotting, i.e. plot(Y,X) instead of plot(X,Y).

These concepts are explained in more detail in the new documentation page linked above.