cyl_obj: cylinder object

creates a cylindrical query object from arbitrary points in 3D and easily converts between cylindrical, spherical and cartesian coordinates

cyl = rcyl(P,Q,R) creates a rcyl object; P, Q and R are 3x1 arrays; P is the original point in the cylinder. PQ defines the central axis of the cylinder and R is a reference point outside line PQ to help determine angle.

cyl_pos = cyl.cart2cyl(cart_pos) converts cartesian coordinates to cylindrical coordinates

cart_pos = cyl.cyl2cart(cyl_pos) converts cylindrical coordinates to cartesian coordinates

cart_pos is an n by 3 matrix of cartisian coordinates, all the conversions are vectorized and computationally efficient

cyl_pos is an n by 3 matrix of cylindrical coordinates, the 3 columns are r, theta and h

similarly, you can call rcyl.cart2sph, rcyl.sph2cart, rcyl.cyl2sph, rcyl.sph2cyl to convert from or to spherical coordinates

how does the conversion work:

P,Q defines the central axis of the cylinder from arbitrary points in cartesian space. In rcyl.cart2cyl, to ontain r, any point is projected to line PQ and the length of the projected path is calculated. To obtain h, a query point is first projected to PQ and the distance from projected point to origin P is calculated. Q only defines the normal direction. So there will be negative values for h. To determine theta (angle), a random point M will be projected to PQ and get projected point M'; The reference point R is also projected to PQ to get R'; Then the angle between MM' and RR' is calculated. Note that this only returns an angle between 0~pi. To assign a sign to the angle, the function of the plane defined by Ax+By+Cz+1 = 0 (or Ax+ By+Cz=0, depending on whether [0,0,0] is on the plane) is calculated. and the sign of Ax+By+Cz+1( or Ax+By+Cz+0) will be assigned to the angle from arccos calculation. Angle will be in the range of -180 to 180. So it's in degrees. You can easily transfer between degree to radians. The spherical system is similar, which comes with (r, theta, phi). Here theta is in 0~180 and phi is from 0~360.

As the angle increments from -180 to 180, the ring along with the normal direction defined by PQ forms a right-handed helix. That's why it's called rcyl.

Most of the unexpected scenarios should have been accounted for already. For example, if a point on the central axis was queried in rcyl.cart2cyl, r will be zeros and theta will be NaNs (but you cannot call rcyl.cyl2cart with inputs with NaNs). Let me know if you find other cases that does not work. Refer to the sample_code for some examples if you are not familiar with the use of OOP/handle.