The acedTrans() function translates a point or a displacement from one coordinate system into another. It takes a point argument, pt, that can be interpreted as either a three-dimensional point or a three-dimensional displacement vector. This is controlled by an argument called disp, which must be nonzero if pt is treated as a displacement vector; otherwise, pt is treated as a point. The translated point or vector is returned in a call-by-reference result argument, which, like pt, is of type ads_point.
The arguments that specify the two coordinate systems, from and to, are both result buffers. The from argument specifies the coordinate system in which pt is expressed, and the to argument specifies the coordinate system of the result. Both the from and to arguments can specify a coordinate system in any of the following ways:
The following are descriptions of the AutoCAD coordinate systems that can be specified by the from and to arguments.
World Coordinate System. The “reference” coordinate system. All other coordinate systems are defined relative to the WCS, which never changes. Values measured relative to the WCS are stable across changes to other coordinate systems.
User Coordinate System. The “working” coordinate system. All points passed to AutoCAD commands, including those returned from AutoLISP routines and external functions, are points in the current UCS (unless the user precedes them with a * at the Command prompt). If you want your application to send coordinates in the WCS, ECS, or DCS to AutoCAD commands, you must first convert them to the UCS by calling acedTrans().
Entity Coordinate System. Point values returned by acdbEntGet() are expressed in this coordinate system relative to the entity itself. Such points are useless until they are converted into the WCS, current UCS, or current DCS, according to the intended use of the entity. Conversely, points must be translated into an ECS before they are written to the database by means of acdbEntMod() or acdbEntMake().
Display Coordinate System. The coordinate system into which objects are transformed before they are displayed. The origin of the DCS is the point stored in the AutoCAD TARGET system variable, and its Z axis is the viewing direction. In other words, a viewport is always a plan view of its DCS. These coordinates can be used to determine where something appears to the AutoCAD user.
When the from and to integer codes are 2 and 3, in either order, 2 indicates the DCS for the current model space viewport, and 3 indicates the DCS for paper space (PSDCS). When the 2 code is used with an integer code other than 3 (or another means of specifying the coordinate system), it is assumed to indicate the DCS of the current space (paper space or model space), and the other argument is assumed to indicate a coordinate system in the current space.
Paper Space DCS. This coordinate system can be transformed only to or from the DCS of the currently active model space viewport. This is essentially a 2D transformation, where the X and Y coordinates are always scaled and are offset if the disp argument is 0. The Z coordinate is scaled but is never translated; it can be used to find the scale factor between the two coordinate systems. The PSDCS (integer code 2) can be transformed only into the current model space viewport: if the from argument equals 3, the to argument must equal 2, and vice versa.
The following example translates a point from the WCS into the current UCS.
ads_point pt, result; struct resbuf fromrb, torb; pt[X] = 1.0; pt[Y] = 2.0; pt[Z] = 3.0; fromrb.restype = RTSHORT; fromrb.resval.rint = 0; // WCS torb.restype = RTSHORT; torb.resval.rint = 1; // UCS // disp == 0 indicates that pt is a point: acedTrans(pt, &fromrb, &torb, FALSE, result);
If the current UCS is rotated 90 degrees counterclockwise around the world Z axis, the call to acedTrans() sets the result to the point (2.0,-1.0,3.0). However, if acedTrans() is called as shown in the following example, the result is (-2.0,1.0,3.0).
acedTrans(pt, &torb, &fromrb, FALSE, result);