Coordinate Transformation

The first of the additional arguments returned by acedNEntSelP() is a 4x4 transformation matrix of type ads_matrix. This matrix is known as the Model to World Transformation Matrix. It enables the application to transform points in the entity's definition data (and extended data, if that is present) from the entity's model coordinate system (MCS) into the World Coordinate System (WCS). The MCS applies only to nested entities. The origin of the MCS is the insert point of the block, and its orientation is that of the UCS that was in effect when the block was created.

If the selected entity is not a nested entity, the transformation matrix is set to the identity matrix. The transformation is expressed by the following matrix multiplication:

The individual coordinates of a transformed point are obtained from the equations where M _mn is the Model to World Transformation Matrix coordinates, (X,Y,Z) is the entity definition data point expressed in MCS coordinates, and (X',Y',Z') is the resulting entity definition data point expressed in WCS coordinates. See Transformation Matrices.

Note: To transform a vector rather than a point, do not add the translation vector [M ₀₃ M ₁₃ M ₂₃ ] (from the fourth column of the transformation matrix).

The following sample code defines a function, mcs2wcs(), that performs the transformations described by the preceding equations. It takes the transformation matrix returned by acedNEntSelP() and a single point (presumably from the definition data of a nested entity), and returns the translated point. If the third argument to mcs2wcs(), is_pt, is set to 0 (FALSE), the last column of the transformation matrix—the translation vector or displacement—is not added to the result. This enables the function to translate a vector as well as a point.

void mcs2wcs(xform, entpt, is_pt, worldpt) 
ads_matrix xform; 
ads_point entpt, worldpt; 
int is_pt; 
{ 
    int i, j; 
    worldpt[X] = worldpt[Y] = worldpt[Z] = 0.0; 
    for (i=X; i<=Z; i++) 
        for (j=X; j<=Z; j++) 
            worldpt[i] += xform[i][j] * entpt[j]; 
    if (is_pt) // If it's a point, add in the displacement 
        for (i=X; i<=Z; i++) 
            worldpt[i] += xform[i][T]; 
} 

The following code fragment shows how mcs2wcs() might be used in conjunction with acedNEntSelP() to translate point values into the current WCS.

ads_name usrent, containent; 
ads_point usrpt, defpt, wcspt; 
ads_matrix matrix; 
struct resbuf *containers, *data, *rb, *prevrb; 
status = acedNEntSelP(NULL, usrent, usrpt, FALSE, matrix, 
    &containers); 
if ((status != RTNORM) || (containers == NULL)) 
    return BAD; 
data = acdbEntGet(usrent); 
// Extract a point (defpt) from the data obtained by calling
// acdbEntGet() for the selected kind of entity.
. 
. 
. 
mcs2wcs(matrix, defpt, TRUE, wcspt); 

The acedNEntSelP() function also allows the program to specify the pick point. A pickflag argument determines whether or not acedNEntSelP() is called interactively.

In the following example, the acedNEntSelP() call specifies its own point for picking the entity and does not prompt the user. The pickflag argument is TRUE to indicate that the call supplies its own point value (also, the prompt is NULL).

ads_point ownpoint; 
ownpoint[X] = 2.7; ownpoint[Y] = 1.5; ownpoint[Z] = 0.0; 
status = acedNEntSelP(NULL, usrent, ownpt, TRUE, matrix, 
    &containers); 

The acedNEntSel() function is provided for compatibility with existing ObjectARX applications. New applications should be written using acedNEntSelP().

The Model to World Transformation Matrix returned by the call to acedNEntSel() has the same purpose as that returned by acedNEntSelP(), but it is a 4x3 matrix—passed as an array of four points—that uses the convention that a point is a row rather than a column. The transformation is described by the following matrix multiplication:

The equations for deriving the new coordinates are as follows:

Although the matrix format is different, the formulas are equivalent to those for the ads_matrix type, and the only change required to adapt mcs2wcs() for use with acedNEntSel() is to declare the matrix argument as an array of four points.

void mcs2wcs(xform, entpt, is_pt, worldpt); 
ads_point xform[4]; // 4x3 version  
ads_point entpt, worldpt; 
int is_pt; 

The identity form of the 4x3 matrix is as follows:

In addition to using a different matrix convention, acedNEntSel() doesn't let the program specify the pick point.