Wrangling the WCS

Having a working coordinate system (WCS) that can easily be moved around makes life easier for the designer. Choosing a convenient coordinate system and entering values directly is much simpler than transforming all the desired coordinates into the absolute coordinate system (ACS). The benefits of having a WCS are not only for the designers using interactive NX, programmers can also use the WCS to make their lives easier too. Moving the WCS around is fairly easy, much more so if you have a reference to a CartesianCoordinateSystem object or a Point3D and an orientation matrix; fortunately, many NX objects expose these object types as properties for our use.

Who's in charge here?

Rule #1 for working with the WCS: the display part, not the work part, controls the WCS - always. We need to define what NX means by 'display part' and 'work part'. The distinction only arises in the context of an assembly; if you have a piece part open, then the display part and work part are one and the same - the current part you have open. When you work with an assembly file, you can make a component the work part (right click on a component and choose 'make work part'). Any new geometry you create will belong to the work part. This is helpful for creating or modifying a component in the context of the assembly; you can easily see how the changes you make affect other parts in the assembly. In this case, the assembly is the display part and the component is the work part. If NX's title bar reads [part2.prt in Assembly part1.prt], you know that part2 is the work part and part1 is the display part.




So, what does this mean for us? The WCS is accessible through a part object; any calls we make to modify the WCS must go through the display part. If the display part and the work part are the same, you can use either to change the WCS; however, using the display part reference will always work. Using only the display part reference will make our programming task a bit easier as we won't have to keep track of work part vs. display part.

Items of interest

The WCS object has several properties and methods available for use, the ones that we'll focus on here are:

• .CoordinateSystem
• .Origin
• .Rotate
• .SetCoordinateSystem
• .SetCoordinateSystemCartesianAtCsys
• .SetOriginAndMatrix

.CoordinateSystem

The .CoordinateSystem property is read only, it will return a CartesianCoordinateSystem object that represents the WCS' orientation in space (the X, Y, and Z vectors that define the direction of each axis). The CartesianCoordinateSystem object will return the X and Y vectors (as Vector3d objects) through its .GetDirections method. If you want to see all the values in the orientation matrix, you will have to dig a bit deeper to find the elements; the code would look something like this:





'write the orientation matrix to the listing window
lw.WriteLine(displayPart.WCS.CoordinateSystem.Orientation.Element.ToString)

'access individual elements of the orientation matrix, the X axis elements in this case
lw.WriteLine(displayPart.WCS.CoordinateSystem.Orientation.Element.Xx.ToString)
lw.WriteLine(displayPart.WCS.CoordinateSystem.Orientation.Element.Xy.ToString)
lw.WriteLine(displayPart.WCS.CoordinateSystem.Orientation.Element.Xz.ToString)

.Origin

The .Origin property represents a Point3d object, the property is read/write; feel free to pass in a new Point3d to change the WCS' position.

.Rotate

The .Rotate method gives you an easy way to rotate the WCS around one of its axes. If we want to rotate the WCS by 30 degrees about its Z axis, the code would look like this:



displayPart.WCS.Rotate(WCS.Axis.ZAxis, 30)

Get your bearings

The last three methods that we'll look at: .SetCoordinateSystem, .SetCoordinateSystemCartesianAtCsys, and .SetOriginAndMatrix each allow you to specify the orientation and/or origin (you'll remember that the .CoordinateSystem property is read only). These methods were added at different times during the API's life and each works slightly differently, use the one that best meets your needs.

.SetCoordinateSystem

This method first showed up in NX 4; it takes a CartesianCoordinateSystem as a parameter and it returns a CartesianCoordinateSystem which represents the previous position of the WCS. In addition to returning an object for you (as a programmer) to use, it also creates a coordinate system object in the NX graphics window. If the user doesn't need or want this object, you can delete it at the end of your journal or you can use one of the other methods which do not create an object in the graphics window.

.SetCoordinateSystemCartesianAtCsys

This method first showed up in NX 7.5; it also takes a CartesianCoordinateSystem as a parameter and returns a CartesianCoordinateSystem object which represents the previous WCS position/orientation. The main difference from the previously discussed method is this one does NOT create a coordinate system object in the graphics window.

.SetOriginAndMatrix

This method debuted along with journaling itself in NX 3. This method takes two parameters: a Point3d structure and a Matrix3x3 structure. This method does not return any value, nor does it create any object in the graphics window. Many other NX objects, such as an Arc, expose an origin and orientation matrix as properties; this makes it easy to read these values from another object and assign them directly to the WCS.

Example Code

The journal code below was written and tested on NX 8.5. It should run on NX 7.5 and above, but I make no guarantees.



Option Strict Off
Imports System
Imports NXOpen

Module Module1

Sub Main()

Dim theSession As Session = Session.GetSession()
Dim workPart As Part = theSession.Parts.Work
Dim displayPart As Part = theSession.Parts.Display

Dim lw As ListingWindow = theSession.ListingWindow
lw.Open()

If IsNothing(displayPart) Then
'active part required
Return
End If

'save current WCS position and orientation
Dim oldOrigin As Point3d = displayPart.WCS.Origin
Dim oldOrientation As CartesianCoordinateSystem = displayPart.WCS.CoordinateSystem

'move WCS origin 10 units in +X (absolute) direction
Dim newOrigin As New Point3d(oldOrigin.X + 10, oldOrigin.Y, oldOrigin.Z)

'move WCS, the .SetOriginAndMatrix method does not save the old WCS
displayPart.WCS.SetOriginAndMatrix(newOrigin, oldOrientation.Orientation.Element)

MsgBox("Notice the WCS has moved in the +X (absolute) direction")

'rotate WCS
displayPart.WCS.Rotate(WCS.Axis.ZAxis, 32)
displayPart.WCS.Rotate(WCS.Axis.YAxis, 16)
displayPart.WCS.Rotate(WCS.Axis.XAxis, 8)

MsgBox("Notice the WCS has been rotated")

'move to absolute coordinate system
Dim absXform As Xform = displayPart.Xforms.CreateXform(SmartObject.UpdateOption.WithinModeling, 1)
Dim absCsys As CartesianCoordinateSystem = displayPart.CoordinateSystems.CreateCoordinateSystem(absXform, SmartObject.UpdateOption.WithinModeling)

'The .SetCoordinateSystem method returns a CartesianCoordinateSystem object and creates an NX coordinate system object in the graphics window.
'Assign it to a variable if you want to refer to it later (re-use it, delete it, etc).
Dim csys2 As CartesianCoordinateSystem = displayPart.WCS.SetCoordinateSystem(absCsys)

'lw.WriteLine(csys2.Orientation.Element.ToString)
MsgBox("The WCS is back at absolute and the previous position has been saved as an NX coordinate system object (the saved csys object might not be visible until after you press OK)")

Dim pt1 As Point3d = csys2.Origin
Dim startPt As Point = displayPart.Points.CreatePoint(pt1)
Dim vec1 As New Vector3d(csys2.Orientation.Element.Xx, csys2.Orientation.Element.Xy, csys2.Orientation.Element.Xz)

Dim dir2 As Direction = displayPart.Directions.CreateDirection(displayPart.Points.CreatePoint(pt1), vec1)
Dim dist2 As Scalar = displayPart.Scalars.CreateScalar(2, Scalar.DimensionalityType.Length, SmartObject.UpdateOption.WithinModeling)
Dim offset2 As Offset = displayPart.Offsets.CreateOffset(dir2, dist2, SmartObject.UpdateOption.WithinModeling)
Dim endPoint As Point = displayPart.Points.CreatePoint(offset2, startPt, SmartObject.UpdateOption.WithinModeling)

Dim rotX As Scalar = displayPart.Scalars.CreateScalar(30, Scalar.DimensionalityType.Angle, SmartObject.UpdateOption.WithinModeling)
Dim rotY As Scalar = displayPart.Scalars.CreateScalar(0, Scalar.DimensionalityType.Angle, SmartObject.UpdateOption.WithinModeling)
Dim rotZ As Scalar = displayPart.Scalars.CreateScalar(0, Scalar.DimensionalityType.Angle, SmartObject.UpdateOption.WithinModeling)

Dim myXform As Xform = displayPart.Xforms.CreateXform(csys2, startPt, endPoint, rotX, rotY, rotZ, 0, SmartObject.UpdateOption.WithinModeling, 1)
Dim newCsys As CartesianCoordinateSystem = displayPart.CoordinateSystems.CreateCoordinateSystem(myXform, SmartObject.UpdateOption.WithinModeling)

'The .SetCoordinateSystemCartesianAtCsys method returns a CartesianCoordinateSystem object, but does NOT create an NX coordinate system object in the graphics window.
Dim csys3 As CartesianCoordinateSystem = displayPart.WCS.SetCoordinateSystemCartesianAtCsys(newCsys)

'lw.WriteLine(csys3.Orientation.Element.ToString)

MsgBox("Finally, the WCS has been offset 2 units along the previously saved Csys' X direction and it has been rotated about the previous Csys' X axis")

End Sub

End Module

Smart Objects

Near the end of the code above, we used some 'smart objects' (Scalars, Offsets, and Xforms) to help us define the final coordinate system. Some more information on these objects can be found in the Point3d and Point objects: Part Two tutorial, if you are interested.

And now, for our special guest... The User!

Manipulating the WCS through code is well and good, but occasionally you will want the user to specify an orientation. The SpecifyCsys function is perfect for this. It will open a dialog box that allows the user to specify a coordinate system with one of NX's built in methods (dynamic, by object, origin + X point + Y point, etc etc). It is an older User Function (UF), so calling it is slightly different than the usual .NET functions/methods. The function takes 5 parameters as shown below:

Public Function SpecifyCsys ( _
title As String, _
ByRef option As Integer, _
csys_matrix As Double(), _
origin As Double(), _
ByRef csys_tag As Tag _
) As Integer

• title {input only} - a prompt to the user
• option {input/output} - an integer value that represents one of the methods of specifying a coordinate system (csys of object, csys of view, origin X point Y point, etc etc). The initial value passed into the function will determine the default value presented to the user, the value after the function completes will indicate the method the user actually chose to use.
• csys_matrix {output} - a 9 element array of doubles that represents the orientation matrix of the coordinate system.
• origin {output} - a three element array of doubles that represents the origin of the coordinate system.
• csys_tag {input/output} - the tag of an existing coordinate system, this will be the default starting point presented to the user. A null value (Nothing in VB.net) can be passed into the function, in which case the current WCS will be used.

The return value of the function (an integer) represents the result of the dialog box.

• 1 = user pressed Back
• 2 = user pressed Cancel
• 3 = user pressed OK
• 7 = error: no active part
• 8 = disallowed state, unable to bring up dialog

Example Code: Specify Csys

The code below was written and tested with NX 8.5, no guarantees for other versions.





Option Strict Off
Imports System
Imports System.Windows.Forms
Imports NXOpen
Imports NXOpen.UF

Module Module2

Public Enum csysOption As Integer
Inferred = 0
Origin_Xpt_Ypt = 1
Xaxis_Yaxis = 2
Zaxis_Xpoint = 3
Csys_object = 4
Dynamic = 5
OffsetCsys = 6
Absolute = 7
CurrentView = 8
ThreePlanes = 9
Xaxis_Yaxis_Origin = 10
Point_PerpendicularCurve = 11
Plane_Vector = 12
Plane_Xaxis_Pt = 13
Zaxis_Xaxis_Origin = 14
Zaxis_Yaxis_Origin = 15
End Enum

Sub Main()

Dim theSession As Session = Session.GetSession()
Dim theUfSession As UFSession = UFSession.GetUFSession
Dim theUISession As UI = UI.GetUI()

Dim workPart As Part = theSession.Parts.Work
Dim displayPart As Part = theSession.Parts.Display

Dim lw As ListingWindow = theSession.ListingWindow
lw.Open()

If IsNothing(displayPart) Then
'active part required
Return
End If

'9 element orientation matrix of specified csys
'arrays are zero based
Dim myCsys(8) As Double

'3 element array: origin point of specified csys
Dim myOrigin(2) As Double

'tag variable used as input/output for the .SpecifyCsys method
'passing a null tag into the function uses the current WCS as the starting csys
Dim newCsysTag As Tag = Tag.Null

'variable to hold the user specified coordinate system
Dim newCsys As CartesianCoordinateSystem

Dim response As Integer

'If you want to know the option the user used to specify the csys, pass in a variable.
'The initial value of the variable will control the default option shown to the user.
'After the function returns, this variable will hold the actual option used.
Dim specifyOption As csysOption = csysOption.Dynamic

'optional message to user
MessageBox.Show("Orient manipulator to the desired location/orientation", "Specify Coordinate System", MessageBoxButtons.OK, MessageBoxIcon.Information)
theUISession.LockAccess()

response = theUfSession.Ui.SpecifyCsys("Specify Desired Orientation", specifyOption, myCsys, myOrigin, newCsysTag)

'if you don't care what option was used to specify the csys, simply pass in an integer that specified the default method to show to the user
'response = theUfSession.Ui.SpecifyCsys("Specify Desired Orientation", csysOption.Dynamic, myCsys, myOrigin, newCsysTag)

theUISession.UnlockAccess()

If response = Selection.Response.Ok Then
'get CartesianCoordinateSystem object from tag
newCsys = Utilities.NXObjectManager.Get(newCsysTag)
'orient WCS to specified coordinate system
displayPart.WCS.SetCoordinateSystemCartesianAtCsys(newCsys)

'try to parse enumeration value to integer (should always work in our case)
Dim num As Integer
If Not Integer.TryParse(specifyOption, num) Then
num = -1
End If

If num > -1 Then
MessageBox.Show("The user used option: " & specifyOption.ToString & " (option: " & num.ToString & ")", "Option used", MessageBoxButtons.OK, MessageBoxIcon.Information)
Else
MessageBox.Show("The user used option: " & specifyOption.ToString, "Option used", MessageBoxButtons.OK, MessageBoxIcon.Information)
End If

Else
'user pressed back or cancel or the system was in a state that could not allow the dialog to be shown
'1 = back
'2 = cancel
'3 = OK
'7 = no active part
'8 = disallowed state, unable to bring up dialog
End If

End Sub

End Module

Enumeration Elaboration

An enumeration is a way to group related constants and give them meaningful names. Since the dawn of programming, integer values have been used to represent program options. You might run across code like:

if optA = 2 then
.
.
end if



You would have to know what the '2' meant in context of the program logic. These types of values became known as 'magic constants', since the programmer working on the code needed some arcane, specialized knowledge of the program. Sure, while I'm programming the original code, I may know that option 4 = csys of object, but I'm not going to remember that next week, let alone 6 months from now when I pick up the code again to add a new feature. The value seems to work like magic, but I don't know why. Using an integer value to represent an option isn't a bad idea, but it does tend to obfuscate the resulting code, especially when the same integer value may represent something completely different in another part of the program. We create an enumeration at the module level to group the options and give them names that we will recognize later. Now that we have an enumeration, the IDE will help fill in the value I want. We now also have the advantage of using the .ToString method on the enumeration value; this will return the name we gave to the constant. The final message box in the journal may tell me "The user used option: Origin_Xpt_Ypt", this is much more useful to me than "The user used option: 1".




For more information on enumerations, see the following links:


Dot Net Pearls: VB.net Enum


MSDN Enum statement


MSDN How to: Declare enumerations