TranslateCoordinates Method (ActiveX)

Translates a point from one coordinate system to another.

Supported platforms: Windows only

Signature

VBA:

RetVal = object.TranslateCoordinates(Point, FromCoordSystem, ToCoordSystem, Displacement, [OCSNormal])

object

Type: Utility

The object this method applies to.

Point

Access: Input-only

Type: Variant (three-element array of doubles)

The 3D WCS coordinates specifying the original coordinates to be translated. This parameter can be treated as a point or a displacement vector depending on the value of Displacement.

FromCoordSystem

Access: Input-only

Type: AcCoordinateSystem enum

The coordinate system from which the point originates.

• acWorld
• acUCS
• acOCS
• acDisplayDCS
• acPaperSpaceDCS

ToCoordSystem

Access: Input-only

Type: AcCoordinateSystem enum

The coordinate system to which the point will be converted.

• acWorld
• acUCS
• acOCS
• acDisplayDCS
• acPaperSpaceDCS

Displacement

Access: Input-only

Type: Long

A displacement vector flag.

• True: Point is treated as a displacement vector.
• False: Point is treated as a point.

OCSNormal

Access: Input-only; optional

Type: Variant (three-element array of doubles)

The normal for the OCS.

Return Value (RetVal)

Type: Variant (three-element array of doubles)

The translated 3D coordinate.

Remarks

You cannot directly translate a coordinate from one OCS to another OCS. To do this, first translate the coordinate from one OCS to an intermediary coordinate system such as the WCS. Then translate that coordinate into the second OCS.

To translate a point on a Polyline or LWPolyline object from OCS to WCS:

1. Get the X and Y coordinates of the OCS point from the Coordinate or Coordinates property.
2. Get the Z coordinate of the OCS point from the Elevation property.
3. Get the Normal for the polyline from the Normal property.
4. Call TranslateCoordinates using the X, Y, Z coordinates and the Normal.

Examples

VBA:

Sub Example_TranslateCoordinates()
    ' This example creates a UCS with an origin at 2, 2, 2.
    ' Next, a point is entered by the user. The WCS and UCS
    ' coordinates of that point are output in a Msgbox.
    
    AppActivate ThisDrawing.Application.Caption
    
    ' Create a UCS named "New_UCS" in current drawing
    Dim ucsObj As AcadUCS
    Dim origin(0 To 2) As Double
    Dim xAxisPnt(0 To 2) As Double
    Dim yAxisPnt(0 To 2) As Double
    
    ' Define the UCS
    origin(0) = 2#: origin(1) = 2#: origin(2) = 2#
    xAxisPnt(0) = 5#: xAxisPnt(1) = 2#: xAxisPnt(2) = 2#
    yAxisPnt(0) = 2#: yAxisPnt(1) = 6#: yAxisPnt(2) = 2#
    
    ' Add the UCS to the UserCoordinatesSystems collection
    Set ucsObj = ThisDrawing.UserCoordinateSystems.Add(origin, xAxisPnt, yAxisPnt, "New_UCS")
    ThisDrawing.ActiveUCS = ucsObj
    
    ' Get the active viewport and make sure the UCS icon is on
    Dim viewportObj As AcadViewport
    Set viewportObj = ThisDrawing.ActiveViewport
    viewportObj.UCSIconOn = True
    viewportObj.UCSIconAtOrigin = True
    ThisDrawing.ActiveViewport = viewportObj
   
    ' Have the user enter a point
    Dim pointWCS As Variant
    pointWCS = ThisDrawing.Utility.GetPoint(, "Enter a point to translate:")
    
    ' Translate the point into UCS coordinates
    Dim pointUCS As Variant
    pointUCS = ThisDrawing.Utility.TranslateCoordinates(pointWCS, acWorld, acUCS, False)
    
    ' Display the coordinates of the point
    MsgBox "The point has the following coordinates:" & vbCrLf & _
           "WCS: " & pointWCS(0) & ", " & pointWCS(1) & ", " & pointWCS(2) & vbCrLf & _
           "UCS: " & pointUCS(0) & ", " & pointUCS(1) & ", " & pointUCS(2), , "TranslateCoordinates Example"

End Sub

Visual LISP:

(vl-load-com)
(defun c:Example_TranslateCoordinates()
    ;; This example creates a UCS with an origin at 2, 2, 2.
    ;; Next, a point is entered by the user. The WCS and UCS
    ;; coordinates of that point are output in a Msgbox.
    (setq acadObj (vlax-get-acad-object))
    (setq doc (vla-get-ActiveDocument acadObj))

    ;; Create a UCS named "New_UCS" in current drawing
    ;; Define the UCS
    (setq origin (vlax-3d-point 2 2 2)
          xAxisPnt (vlax-3d-point 5 2 2)
          yAxisPnt (vlax-3d-point 2 6 2))
    
    ;; Add the UCS to the UserCoordinatesSystems collection
    (setq ucsObj (vla-Add (vla-get-UserCoordinateSystems doc) origin xAxisPnt yAxisPnt "New_UCS"))
    (vla-put-ActiveUCS doc ucsObj)
    
    ;; Get the active viewport and make sure the UCS icon is on
    (setq viewportObj (vla-get-ActiveViewport doc))
    (vla-put-UCSIconOn viewportObj :vlax-true)
    (vla-put-UCSIconAtOrigin viewportObj :vlax-true)
    (vla-put-ActiveViewport doc viewportObj)
   
    ;; Have the user enter a point
    (setq pointWCS (vlax-variant-value (vla-GetPoint (vla-get-Utility doc) nil "\nEnter a point to translate:")))
    
    ;; Translate the point into UCS coordinates
    (setq pointUCS (vlax-variant-value (vla-TranslateCoordinates (vla-get-Utility doc) pointWCS acWorld acUCS :vlax-false)))
    
    ;; Display the coordinates of the point
    (alert (strcat "The point has the following coordinates:"
                   "\nWCS: " (rtos (vlax-safearray-get-element pointWCS 0) 2) ", "
                             (rtos (vlax-safearray-get-element pointWCS 1) 2) ", "
                             (rtos (vlax-safearray-get-element pointWCS 2) 2)
                   "\nUCS: " (rtos (vlax-safearray-get-element pointUCS 0) 2) ", "
                             (rtos (vlax-safearray-get-element pointUCS 1) 2) ", "
                             (rtos (vlax-safearray-get-element pointUCS 2) 2)))
)