function [tilt, theta, singular] = h3d_scan_dir2tt(direction)
	% [tilt, theta, singular] = h3d_scan_dir2tt(direction)
	%
	% Converts a direction to tilt and theta.
	% tilt and theta are always valid, but singular warns
	% that there is some ambiguity for tilt.
	% In that case, tilt is set arbitrarily to 0.

	% Recall that the transformation (theta,tilt) -> direction
	% is given by
	%
	%  direction = rot_y(tilt) * rot_z(theta) * [1; 0; 0];
	%
	% You can recover tilt just by looking at the (x,z) coordinates of direction:

	singular = 0;

	if very_small(direction(3)) && very_small(direction(1))
		singular = 1;
		tilt = 0;
	else
	    tilt = -atan2( direction(3), direction(1) );
	end


	% now eliminate the tilt:

	  p2d = rot_y(-tilt) * direction;

	% we got a planar point

	  assert( very_small(p2d(3)) );

	% easy to get theta now

	  theta = atan2( p2d(2), p2d(1) );


function res = very_small(x)
	res = abs(x) < 1e-6;