Overview

This section describes how to use the stepctl library to do common operations. As described in the Getting Started section, viewing applications use an instance of the GeomView control to read STEP files and display STEP 3D geometry contained within. This section describes some of the things you can do with the functions available on this class.

Reading Files

To read a STEP file into memory and display all of the geometry in the view window, call the LoadSTEPFile() function with the full pathname of the file. The control will read the file, compute display information from the brep faces, and then show the geometry. Computing the display information may take some time so the function will return after the file has been read. The window will incrementally display geometry as it is ready. If you want to clear the window and loaded file call the Reset() function.

After a STEP file has been loaded, you can access the header information from the file. Call the GetHeaderSchema() function to get the STEP protocol that the file was written with. The GetHeaderOriginatingSystem() and GetHeaderPreprocessorVersion() functions identify the system that was used to create the file, and the GetHeaderAuthor(), GetHeaderDescription(), and GetHeaderOrganization() functions give some information about the person who created it.

Controlling the View Window

By default, the view window will display all of the geometry in a STEP file and scale the view so that everything is visible. You can zoom the display in or out by assigning a value to the Zoom Property. This is a floating point number that controls the scale of the display. Setting this to a value of 1 or calling the ZoomAll() function will show everything.

When you left-click and drag the mouse in the window, the view usually rotates. You can control this behavior using the MouseMode Property. This property can take one of several different values to rotate the display, pan it up or down, or cause left-clicking to select geometric objects.

Dim cv As GeomView

'' rotate the display
cv.MouseMode = GeomView.MouseModeValue.Rotate

'' pan the display
cv.MouseMode = GeomView.MouseModeValue.Pan

'' select edges
cv.MouseMode = GeomView.MouseModeValue.PickEdge

'' select geometric faces
cv.MouseMode = GeomView.MouseModeValue.PickFace

'' select entire shape representations
cv.MouseMode = GeomView.MouseModeValue.PickShape

The viewing window normally shows geometry using a perspective transformation. This means that lines converge in the distance. You can use the Perspective Property to control this behavior, and by setting the value to false, you can show the geometry in an orthographic drawing style.

Normally the application user will control the view orientation using the mouse, but the orientation can be controlled programmatically as well with the SetView() function. You can set the view to predefined orientations or save view parameters using the GetView() function and restore them later.

Dim cv As GeomView
Dim sz As Double = ctlView.Zoom

'' An Isometric view
Dim rt2 As Double = System.Math.Sqrt(2)
Dim rt3 As Double = System.Math.Sqrt(3)
Dim rt6 As Double = System.Math.Sqrt(6)

cv.SetView(0, 0, 0, -rt3/rt6, -1/rt6, rt2/rt6, rt3/rt6, -1/rt6, rt2/rt6, sz)


'' A front view, along the X axis
cv.SetView(0, 0, 0, 0, 0, 1, 1, 0, 0, sz)

'' A top view, down the Z axis
cv.SetView(0, 0, 0, 1, 0, 0, 0, 1, 0, sz)

Picking Geometric Objects

When the MouseMode Property is set to one of the "pick" values, left-clicking on a geometric object will generate an event that gives information about the selected item. The PickShape, PickFace, and PickEdge events all return a STEP instance ID, as well as the XYZ coordinates of the click in the viewspace.

The instance ID returned by the event is an integer handle that corresponds to the entity ID number in a STEP exchange file. You can investigate the particular instance by opening the file with the STEP File Browser and searching for that instance number. All GeomView functions that operate on STEP instance data, such as the ones that change visual attributes, operate on this ID. A value of zero is a null ID.

When an object is selected, it is normally drawn in a blue highlight color, and the view window keeps track of it as the currently selected object. The ClearSelection() function will clear this state and restore the object to its normal appearance. You can also control some display attributes using the TransparentSelected() and HideSelected() functions.

Controlling Visual Attributes

The GeomView class has functions to control the visibility, transparency, and color of STEP instances in the viewing window. You can test whether an instance is a displayable part of the viewing window (also called a scenegraph node), using the IsSceneGraph() function. If this returns true, you can you can control an instance using the functions below.

When a STEP file is first read, all geometric objects within it are shown in the viewing window. Use the VisibleInstance() function to hide or show an object. The scenegraph is organized in a hierarchy following the STEP assembly or shape relationships, so turning off a higher level shape will hide all of the children of that shape, regardless of their visibility settings. The IsVisible() function will return the visibility setting of an individual object but will not indicate whether all of its scenegraph parents are also visible. Two functions change the visibility of entire trees of objects: The VisibleAll() function restores all objects back to the visible state, while the VisibleAllChildren() function shows or hides an instance as well as any assembly or shape children in the scenegraph.

A STEP file may contain presentation tolerances or other annotations to the geometry. These are normally shown along with all other geometry, but you can use the VisibleAllAnnotations() to explicity show or hide them and the IsVisibleAllAnnotations() function to check whether they are being shown. The VisibleAnnotations() function can also control the display of annotations for a particular instance, such as those created with the MakeProductPoint() function.

Shapes and faces are normally drawn in a solid style. Use the TransparentInstance() function to draw an object in a transparent manner. As with visibility, the scenegraph children of an object will also be drawn in a transparent manner. You can explicitly make one of the children solid again by calling the function on it with a value of false. Return an instance to inheriting the transparency state of its parent with the TransparentDefault() function, or return them all to the default with TransparentAllDefault(). The IsTransparent() function will return the transparency setting of an individual object but will not indicate whether it is inheriting transparency from its scenegraph parent.

The color of objects can also be controlled. Each object has a display color that is shown, as well as a default color that contains any STEP file color presentation information. You can change the displayed color of an object with the ColorInstance() function or copy default into the displayed color with ColorDefault(). You can also clear the display color with ColorClear(), in which case the object will inherit the color of its scenegraph parent. You can also clear the default color information from the STEP file with ColorClearDefault(), but there is no way to restore it again without re-reading the file.

Assembly and Shape Trees

STEP files usually contain separate trees of both product and shape structure, with references back and forth between them. The product structure describes the bill-of-materials layout of an assembly, while the shape structure describes the geometric transforms and spatial location of the geometry for each assembly component. The following basic functions can query this product and shape structure. The product functions return the IDs of STEP PRODUCT_DEFINITION instances while the shape functions return the IDs of STEP SHAPE_REPRESENTATION instances.

The GetProductRoots() function returns a list of top-level product definitions. This is the starting point for traversing the STEP bill-of-materials assembly structure. There is also a GetShapeRoots() function that returns top-level shapes that are not associated with any product, but most files do not have any.

From a given product definition, you can navigate to assembly children using the GetProductRels() function. This returns a set of relationship instances that you can follow to the child product definition with the GetRelChildProduct() function. Each product definition has associated shape instance, which you can get with the GetProductShapes() function. There is normally just one, but some STEP files may have several alternate shapes.

Shapes also have relationships to other shapes, which you can get to with the GetShapeRels() and GetRelChildShape() functions. Assemblies link shape and product relationships. The GetProductRelFromShapeRel() function finds the corresponding product relationship, if any, for a shape relationship.

Once you have a product definition instance, you can get some basic attribute information about it with the GetProductName(), GetProductIdentifier(), GetProductBaseID(), and GetProductFormationID() functions. Given any instance, you can find some basic information about it using the GetInstanceType(), GetInstanceNameAtt(), GetInstanceDescAtt(), and GetInstanceIdAtt() functions.