Overview

The RoseXform2D class wraps a double[9] array of 2D transformation matrix data with inline member functions for simple access and update. The RoseXform class class discusses how to use these class wrappers instead of the raw arrays.

It is defined in the rose_xform.h header file.

Array Member

public:
	double m[9];

The class has a public array member with the coordinates. You can access the data directly whenever you want. The member functions are strictly for clearer code and better compiler checking.

RoseXform2D xf;

// completely equivalent
printf (My ydir is %g, %g\n, xf.m[2], xf.m[4]);
printf (My ydir is %g, %g\n, xf.ydir().i(), xf.ydir().j());

Constructor

RoseXform2D();
RoseXform2D(const double src[9]);
RoseXform2D(
	double xi,double xj,
	double yi,double yj,
	double x=0,double y=0
	);

The RoseXform2D() default constructor initializes the transform to the identity matrix, while the other initialize the components from either an array or separate parameters.

// rotate 90 degrees clockwise 
double foo[9] = { 0,-1,	  1, 0,	  0, 0 };

// default ctor initializes as identity matrix
RoseXform2D i_am_identity;

// initialized with explicit arguments
RoseXform2D xf1 ( 0,-1,	  1, 0,	  0, 0 );

// initialized by copying contents of foo
RoseXform2D xf2 (foo);
RoseXform2D xf3 = foo;	// same

// initialized by copying another RoseXform2D
RoseXform2D xf4 = xf3;

origin()

const RosePoint2D& origin() const;
RosePoint2D& origin();

void origin (const RosePoint2D& val);
void origin (const double val[2]);
void origin (double x,double y);
void origin (ListOfDouble * lst);

The origin() function works with the x, y coordinates for the origin of a transform. The access functions return a reference to a RosePoint2D, and you can call the update function with a RosePoint2D, a two-element array, or two separate numbers. The update functions are equivalent to calling rose_xform2d_put_origin() on the transform array.

RoseXform2D xf;

// get the coordinate values by name
printf (origin is at %g, %g\n,
       xf.origin().x(), 
       xf.origin().y());

// get the coordinate values by array index
printf (coord %g\n, xf.origin().m[0]);
printf (coord %g\n, xf.origin().m[1]);


double pt1[2] = { 100, 0 };
RosePoint2D pt2 (100, 0);

xf.origin (pt1);	// set origin from array
xf.origin (pt2);	// set origin from RosePoint2D

// set origin directly from arguments
xf.origin (100, 0);

put_alldirs()

void put_alldirs(const RoseXform2D& src);

The put_alldirs() function copies the xdir() and ydir() directions from a transform. It is equivalent to calling rose_xform2d_put_alldirs() on the transform array.

RoseXform2D xf;
RoseXform2D other;

// copy direction portion
xf.put_alldirs (other);	     

// same, but assign each direction
xf.xdir (other.xdir());	     
xf.ydir (other.ydir());	     

// same, but work on arrays directly
rose_xform2d_put_alldirs(xf.m,other.m);	     

put_cto()

void put_cto(
	const RoseDirection2D& xax,
	const RoseDirection2D& yax,
	const RosePoint2D& loc,
	double scale = 1
	);

The put_cto() function initializes from a cartesian transform operator, which is a generalized transform that can do rotation, translation, uniform scaling, and mirroring (by giving a left handed set of direction vectors). This function is equivalent to calling rose_xform2d_put_cto() on the transform array.

The function expects direction vectors for the X-axis, Y-axis, a location vector, and an optional scale factor. Any of the vectors can be null or zero vectors. As with put_dirs(), This function follows the STEP and IFC Part 42 EXPRESS logic for building the axes when they are missing.

put_dirs()

void put_dirs(
	const RoseDirection2D& xaxis
	);

The put_dirs() function takes an X axis direction, computes a Y axis direction, makes sure the results are normalized, and sets xdir() and ydir(). You can completely initialize a 2D transfrorm by calling this function followed by origin().

This function is equivalent to calling rose_xform2d_put_dirs() on the transform array.

RoseXform2D xf;
RoseDirection2D minux_xaxis (-1, 0);

// Set rotation to 180deg counterclockwise about the origin.
// The Y direction will be (0, -1)   Finish by setting the
// translation portion to (10, 20)

xf.put_dirs(minux_xaxis);      
xf.origin(10, 20);

// Same thing with an axis vector that is not normalized.   The 
// final result will have X, Y directions scaled to unit
// vectors, so you will get the same matrix as above.

RoseXform2D xf2;
RoseDirection2D denorm_minux_xaxis (-50, 0);

xf2.put_dirs(denorm_minux_xaxis);      
xf2.origin(10, 20);	 


if (rose_xform2d_is_equal(xf, xf2))
   printf(See! Same result!\n);

put_identity()

void put_identity();

The put_identity() function sets the contents of the transform to the identity matrix. It is equivalent to calling rose_xform2d_put_identity() on the transform array.

RoseXform2D xf;	 // default ctor initializes to identity matrix

// set to identity matrix again
xf.put_identity();

// same thing, but work on the array directly
rose_xform2d_put_identity(xf.m);

// more verbose way to set the identity matrix
xf.xdir (1, 0)
xf.ydir (0, 1);
xf.origin (0, 0);

put_rotation()

void put_rotation(
	double angle,
	RoseUnit angle_unit = roseunit_rad
	);

The put_rotation() function replaces the rotation part of the matrix with a transform that rotates by a certain angle in the XY plane. The direction of rotation is counterclockwise when looking down at the plane. By default, the angle is expected in radians, but you can use degrees by giving an extra unit parameter. This is equivalent to calling rose_xform2d_put_rotation() on the transform array.

RoseXform2D rot;
RoseDirection2D src(1,0);
RoseDirection dst;

// rotate 90deg counterclockwise around the Z axis
rot.put_rotation(90, roseunit_deg);

// apply to a src vec that points along X
rose_xform2d_apply_dir (dst, rot, src);

// dst vec now points along Y (0, 1)

put_rotation_about_pt()

void put_rotation_about_pt(
	const RosePoint2D& pt,
	double angle,
	RoseUnit angle_unit = roseunit_rad
	);

The put_rotation_about_pt() function initializes the matrix with a complete transform that rotates by a certain angle around a given point in the XY plane. The direction of rotation is counterclockwise when looking down at the plane. By default, the angle is expected in radians, but you can use degrees by giving an extra unit parameter. This is equivalent to calling rose_xform2d_put_rotation_about_pt() on the transform array.

xdir()

const RoseDirection2D& xdir() const;
RoseDirection2D& xdir();

void xdir (const RoseDirection2D& val);
void xdir (const double val[2]);
void xdir (double i,double j);
void xdir (ListOfDouble * lst);

The xdir() function works with the i, j components for the X-axis direction portion of a transform. The access functions return a reference to a RoseDirection2D, and you can call the update function with a RoseDirection2D, a two-element array, or two separate numbers. The update functions are equivalent to calling rose_xform2d_put_xdir() on the transform array.

The ydir() function works with the other axis direction.

RoseXform2D xf;

// get the coordinate values by name
printf (xdir is %g, %g\n,
       xf.xdir().i(), 
       xf.xdir().j());

// get the direction values by array index
printf (dir %g\n, xf.xdir().m[0]);
printf (dir %g\n, xf.xdir().m[1]);


double pt1[2] = { 0, 1 };
RoseDirection2D pt2 (1/ROSE_SQRT_2, 1/ROSE_SQRT_2);

xf.xdir (pt1);	// set x axis direction from array
xf.xdir (pt2);	// set x axis direction from RoseDirection2D

// set all axis directions and origin directly from arguments
xf.xdir (0, -1)
xf.ydir (1, 0);
xf.origin (10, 20);

ydir()

const RoseDirection2D& ydir() const;
RoseDirection2D& ydir();

void ydir (const RoseDirection2D& val);
void ydir (const double val[2]);
void ydir (double i,double j);
void ydir (ListOfDouble * lst);

The ydir() function works with the i, j components for the Y-axis direction portion of a transform. The access functions return a reference to a RoseDirection2D, and you can call the update function with a RoseDirection2D, a two-element array, or two separate numbers. The update functions are equivalent to calling rose_xform2d_put_ydir() on the transform array.

See xdir() for code examples.