Creating Unassociative Arcs
In this tutorial, we'll look at creating unassociative arc objects. So, with all the whiz-bang technology in NX, why look at unassociative arcs? The answer is three-fold:
- the creation methods are simple and straightforward
- the methods will introduce other NX data structures
- the geometry itself is perfectly valid and useful for modeling operations, title block geometry, logo art, etc
In short, the goal of this tutorial is to show you how to create useful geometry and introduce you to a few concepts that you will run into again when working with other NX object types.
The API offers three basic ways to create unassociative arcs:
- through three specified points
- with a given center point, orientation matrix, radius, start angle, and end angle
- with a given center point, an X vector, a Y vector (together, the vectors will define the arc's orientation matrix), radius, start angle, and end angle
We'll take a look at each in turn.
Arc through three points
The method to specify an arc through three points has the following signature:
Public Function CreateArc ( _
startPoint As Point3d, _
pointOn As Point3d, _
endPoint As Point3d, _
alternateSolution As Boolean, _
) As Arc
To define this arc, we'll need to pass in three points (via Point3d objects) and two boolean values. The points represent the start point, end point, and a point that would lie on the arc if it were drawn as a full circle. The "alternateSolution" boolean (true or false value) will specify if you want the standard solution or the alternate (complement arc) solution. So, if we specified a start point of (0,0), an end point of (1,1), and a "pointOn" of (0.7071, 0.7071), the resulting arc would range from 0° to 90°. The alternate solution (complement arc) would range from 90° to 360°. So, you can see that if we specify the "alternate solution", the "pointOn" will not actually lie on the resulting arc (though if the arc were a full circle, the "pointOn" would lie on the circle). The last parameter, "startAndEndGotFlipped" is passed in "ByRef"; ByRef is shorthand for "By Reference" which means that we are granting the function read/write permission on the given variable. "ByVal" (By Value) is the default way to pass in a parameter. ByVal means that the Sub or Function can only read the value of the parameter, it cannot change its value. If ByVal or ByRef is not included in the Sub/Function call, the default value of ByVal is inferred. The function itself will return an arc object and it will write to the boolean value that we pass in to give us a bit more information (and yes, the pun was intended) about the arc object.
So, what does the "startAndEndGotFlipped" represent? When NX creates the arc, it will "parameterize" the arc geometry. To do so, NX will draw the arc counter-clockwise about the arc's Z axis. If NX returns True for "startAndEndGotFlipped", it means that what you specified as the start point, NX considers to be the end point (and vice versa). This may be important if you are performing other operations later in your journal. The NX API has functions for returning the parameterization of a given object, I'd recommend using those functions rather than relying on your inputs (for an example, see the article on arc start and end points).
Now, an example:
Option Strict Off
Imports System
Imports System.Collections.Generic
Imports NXOpen
Module create_arc_3_pts
Sub Main()
Dim theSession As Session = Session.GetSession()
Dim workPart As Part = theSession.Parts.Work
Dim lw As ListingWindow = theSession.ListingWindow
lw.Open()
Dim markId1 As Session.UndoMarkId
markId1 = theSession.SetUndoMark(Session.MarkVisibility.Visible, "NXJournaling.com")
Dim my3pArcs As New List(Of Arc)
'create arc through 3 points
For i As Integer = 1 To 10
Dim stPt As New Point3d(i, 0, 0)
Dim endPt As New Point3d(-i, 0, 0)
Dim ptOn As New Point3d(0, 1, 0)
Dim altSolution As Boolean = False
'create boolean variable to pass ByRef to function
Dim endsFlipped As Boolean
my3pArcs.Add(workPart.Curves.CreateArc(stPt, ptOn, endPt, altSolution, endsFlipped))
lw.WriteLine("arc " & i.ToString & " ends flipped: " & endsFlipped.ToString)
Next
lw.Close()
End Sub
End Module
Things to try
After running the code to see the stock output, try changing the "altSolution" input to True to see the effect on the output. Also, see what happens to the "endsFlipped" variable after changing the start and end point definitions to:
Dim stPt As New Point3d(-i, 0, 0)
Dim endPt As New Point3d(i, 0, 0)
Arc given orientation matrix
The method signature for creating an arc with a given orientation matrix is as follows:
Public Function CreateArc ( _
center As Point3d, _
matrix As NXMatrix, _
radius As Double, _
startAngle As Double, _
endAngle As Double _
) As Arc
The "center" and "radius" inputs are fairly self-explanatory, but the other inputs require some more explanation. The "angle" inputs will be interpreted as radians by the function, so be sure to convert from degrees as necessary. If you remember back to algebra class, angles are specified by starting at 0° on the X axis and measuring counter-clockwise about the Z axis. NX follows the same convention. The "matrix" specifies the X, Y, and Z axes and the angles are measured relative to this resulting coordinate system. The matrix itself contains 9 values (3 rows x 3 columns); the first row defines the X vector, the second row defines the Y vector, and the third row defines the Z vector. The first value in each row represents the X value of each vector, second value represents Y, and the third Z. Overall, the matrix looks like this:
X vector [[Xx Xy Xz]
Y vector [Yx Yy Yz]
Z vector [Zx Zy Zz]]
This method of creating an arc is easy to use when you have an orientation matrix that you want to use. The good news is: many objects in NX will return an orientation matrix, saved Csys/Datum Csys objects being the most obvious. The code below will use the orientation matrix of the WCS, but you could use the orientation of a different object, or create your own matrix if you are feeling adventurous. You'll notice that the code uses the same orientation matrix each time, but varies the angle input values.
Option Strict Off
Imports System
Imports System.Collections.Generic
Imports NXOpen
Module create_arc_matrix
Sub Main()
Dim theSession As Session = Session.GetSession()
Dim workPart As Part = theSession.Parts.Work
Dim lw As ListingWindow = theSession.ListingWindow
lw.Open()
Dim markId1 As Session.UndoMarkId
markId1 = theSession.SetUndoMark(Session.MarkVisibility.Visible, "NXJournaling.com")
Dim ctrPt As New Point3d(0, 0, 0)
Dim arcMatrix As NXMatrix = workPart.WCS.CoordinateSystem.Orientation
lw.WriteLine("orientation matrix:")
lw.WriteLine(arcMatrix.Element.ToString)
Dim arcRadius As Double = 1
'must specify angles in radians
'radians = degrees * Math.PI / 180
Dim arcStartAngle As Double = 0
Dim arcEndAngle As Double = Math.PI / 4
Dim angleIncrement As Double = Math.PI / 10
For i As Integer = 1 To 10
arcRadius = i / 2
workPart.Curves.CreateArc(ctrPt, arcMatrix, arcRadius, arcStartAngle, arcEndAngle)
arcStartAngle += angleIncrement
arcEndAngle += angleIncrement
Next
lw.Close()
End Sub
End Module
Things to try
Before re-running the code, try moving the WCS to a new, arbitrary location (translate and rotate it). Notice how the arcs are created parallel to the X-Y plane but not necessarily on it. The WCS only provides the orientation, not the actual plane we will be drawing on.
Arc given X and Y vectors
This is very similar to the method above; the method signature is:
Public Function CreateArc ( _
center As Point3d, _
xDirection As Vector3d, _
yDirection As Vector3d, _
radius As Double, _
startAngle As Double, _
endAngle As Double _
) As Arc
The center, radius, startAngle, and endAngle have been covered and will not be repeated here. Instead of an orientation matrix, this method only takes an X and Y direction vector. You may recall that the cross-product of two vectors results in a third vector that is perpendicular to both inputs. In this way, the Z axis can be calculated given the X and Y axes. This method may come in handy if you don't have an orientation matrix, but have a couple of vectors that you want to define your arc's plane.
Example code:
Option Strict Off
Imports System
Imports System.Collections.Generic
Imports NXOpen
Module create_arc_vector
Sub Main()
Dim theSession As Session = Session.GetSession()
Dim workPart As Part = theSession.Parts.Work
Dim markId1 As Session.UndoMarkId
markId1 = theSession.SetUndoMark(Session.MarkVisibility.Visible, "NXJournaling.com")
Dim h As Double = 1
Dim hAngle As Double = 0
'must specify angles in radians
'radians = degrees * Math.PI / 180
Dim angleIncrement As Double = Math.PI / 8
Dim ctrPt As New Point3d(0, 0, 0)
Dim xVec As New Vector3d(h * Math.Cos(hAngle), h * Math.Sin(hAngle), 0)
Dim yVec As New Vector3d(h * Math.Cos(hAngle + Math.PI / 2), h * Math.Sin(hAngle + Math.PI / 2), 0)
Dim radius As Double = 1
Dim arcStartAngle As Double = 0
Dim arcEndAngle As Double = Math.PI
For i As Integer = 1 To 10
radius = i / 2
workPart.Curves.CreateArc(ctrPt, xVec, yVec, radius, arcStartAngle, arcEndAngle)
'increment angle and recalculate vectors
hAngle += angleIncrement
xVec.X = h * Math.Cos(hAngle)
xVec.Y = h * Math.Sin(hAngle)
yVec.X = h * Math.Cos(hAngle + Math.PI / 2)
yVec.Y = h * Math.Sin(hAngle + Math.PI / 2)
Next
End Sub
End Module
The output of this journal is very similar to the previous one. Note, however, that in this journal the start and end angles are held constant while we change the defining vectors (hence, the arc's defining coordinate system); while in the previous journal the coordinate system is held constant while we change the start and end angles. The results are similar, but the method of getting the results is fundamentally different.