Polygon Objects are one way of creating flexible user-defined volumes or shells within OpticStudio. This article covers how to create Polygon Objects, define face groups, and call the object from the NSC Editor.
Authored By Dan Hill, Updated by Misato Hayashida
Introduction
Defining Polygon Objects is one of many ways of creating user-definable objects in OpticStudio. Polygon Objects are objects that are composed of a collection of triangles in 3D space, whose vertices are defined in an ASCII text file. The file format may be created and edited in any text editor, such as Notepad, and consists of a series of rows of data. Each row begins with a single letter or symbol, followed by the data for that symbol. For a complete description of the supported symbols and their syntax, refer to the “Defining Polygon Objects” section in the Non-Sequential Components Chapter of the OpticStudio Help System.
Defining the vertices
To fully demonstrate how to construct a Polygon Object, define individual faces or face groups, where to save the file, and how to load it in OpticStudio, let’s create an equilateral triangle prism using the POB capabilities. An equilateral triangle prism has a total of five faces, but only a total of 6 vertices need to be defined. We can then connect each of these vertices using the rectangle symbol supported by the Polygon Object in OpticStudio.
We can start with a blank Notepad Editor. Lines which begin with the exclamation mark (!) indicate a comment line. It is always useful to include comments so that you can remember what you have done when you view the definition of this object later on.
Let’s first define the 6 vertices of the prism. The syntax we must use is described by the vertex symbol: V. Lines which define a vertex must start with the letter V, followed by the vertex number and the x, y, z coordinates of the vertex:
V number x y z
The number designates the x,y,z positions to a vertex number, which may then be used later on in our definition of the Polygon Object. This makes it convenient so that we do not have to define the x,y,z coordinates each time this vertex is used. Instead, we just reference the number.
The x,y,z coordinates are relative to the local (0,0,0) of the Polygon Object. Be aware that the (0,0,0) coordinate of the Polygon Object is positioned globally within the NSC Editor.
So, let’s assume that we want the vertex of the prism to be at the center of the bottom edge of the front face, and that all sides of the prism have the dimension of 2. Note that the units are defined under the System Explorer...Units. Therefore, if my system units are in millimeters, then each side of the prism is 2 millimeters. If I switch the system units to inches, then the each side will be 2 inches.
Again, a total of 6 vertices are defined by their respective x, y, and z positions. Here is a graphic which represents the collection of points that we have just defined above:
Note that we have not yet connected any of the vertices. The blacklines in the graphic above are shown just for visual purposes – they help distinguish the prism shape and give depth to the picture.
The arrows indicate the local coordinate axes, with the origin at the bottom edge of our Polygon Object. The local axis for each object may be drawn by checking the “Draw Local Axis” box under the Draw tab of the Object Properties dialog:
Connecting the vertices
Now that the vertices are defined, we can construct the prism using a series of rectangle and triangle calls. The triangle syntax requires three vertex numbers which make up the triangle, in addition to two other parameters:
T vertex1 vertex2 vertex3 isreflective face
The rectangle syntax requires four vertex numbers:
R vertex1 vertex2 vertex3 vertex4 isreflective face
The vertex numbers must be integer vertices previous defined in the file, and the order of the vertices is not arbitrary – they must be listed in a continuously clockwise or counter-clockwise order. A “bow-tie” order is not supported, as indicated by the diagram below:
As an example, the following line would create the front face of our prism, connecting vertices 1, 2, and 3:
T 1 2 3 0 0
The isreflective argument is an integer value which can be -1, 1, or 0. Each face of the Polygon Object can either be reflective, refractive, or absorbing. If the reflective flag was set to 1 in the example above, then the surface would be considered as a reflective surface, and syntax would look like:
T 1 2 3 1 0
For the isreflective flag, 0 stands for refractive, 1 stands for reflective, and -1 stands for absorbing. Separate from what is defined in the POB file, each face of each object can be made reflective or absorbing from the Object Properties dialog:
Note that this selection overrides whatever has been set in the POB file. For example, if one of the faces in the POB file was set to reflective, it can be changed to absorbing in the Object Properties dialog without having to edit the POB file. If Object Default is selected, then the property assigned in the POB file is assumed.
The face argument determines which face group the surface is related to. This is discussed in more detail later in this article.
So, to continue the definition of each face of the cube, we need a total of two triangle commands and four rectangle commands, each of which will be refractive:
Saving and loading POB files
Polygon Objects need to be saved in the Zemax/Objects/Polygon Objects/ directory in order to be recognized by OpticStudio. The extension should be .POB, for Polygon Object. Save the current example as Equilateral triangle prism.POB.
The object type must be changed to Polygon Object to call your *.POB files. To pull up our newly created object, choose Equilateral triangle prism.POB from the available Data File pull down menu:
Open the Shaded Model to confirm the prism that we just constructed.
Assigning surfaces of the Polygon Object to different face groups
Currently, our defined Polygon Object has one face group. In other words, any coating and/or scattering properties that we apply to it will be placed on all six faces (or surfaces) of the prism. Under the Coat/Scatter tab of the Object Properties dialog, only Face 0 is present, which represents all faces of the prism.
Using the Object Viewer (select View Current Object in the NSC Editor toolbar), all of the faces are highlighted as Face 0 is chosen.
We may assign each face to a different face group in the .POB file. Then, we may apply different coating and scattering properties to the various faces of our object.
The name and number of each face is first defined using the C symbol within the definition of our POB object. The face name symbol C requires the following syntax:
C facenumber “any name here”
The facenumber is just an integer used for reference in the rectangle or triangle commands. Face groups can also be given any name which may be helpful in distinguishing which surface(s) the face group corresponds to.
In the current example, let’s edit our Polygon Object to distinguish the front, back and side faces of the prism (select Edit Object Data File in the NSC Editor toolbar). Before the vertex definitions, let’s define 3 unique face groups: one for the front face, one for the back face, and one for the four side faces of the prism. To do so, 3 face commands are required:
Remember that each triangle/rectangle definition had a face flag, which corresponds to the face group number previously defined in the POB file. So, we need to modify this flag for each triangle/rectangle definition to distinguish which face(s) relate to which face group or face number.
The triangle describing the front face will be given a face number of 1, since that is the face group describing the “Front Face.” All of the rectangles defining the side faces of the prism will be left with the face number of 0. And lastly, a face group number of 2 will be applied to the back face triangle:
Once the appropriate flags have been set, save the file and reload the object in OpticStudio (Non-Sequential Component Editor...Reload All Objects).
Now, there are three distinct face groups:
Thus, any coating and/or scattering property that is chosen for face group 0, Side Faces, will be applied to all of the side faces of the prism (each of the side faces of the POB file pointed to a face number of 0). Similarly, if a different face number is chosen (1, Front Face for example), then a separate set of coating/scattering properties may be applied to the front face of the prism.
The Object Viewer also helps distinguish the surfaces of the object which correspond to the selected face group number. Note that those surfaces which correspond to the selected face group are highlighted in orange:
What to look out for
There are a few items to be aware of with Polygon Objects.
- Make sure that the combination of rectangles/triangles defined in the POB file form an enclosed volume if it is being used as a volume (POB objects can also be made shells via the “Is Volume” flag in the NSC Editor).
- When defining rectangles, do not use a “bow-tie” pattern when connecting vertices. This will result in erroneous ray tracing.
- There is no fixed upper limit as to the number of triangles a Polygon Object may contain. This is determined by the amount of real or virtual RAM the computer has available. Each triangle takes about 100 bytes of memory. However, OpticStudio often maintains multiple copies of the lens data simultaneously, and so a good rule of thumb is that OpticStudio will need 500 bytes of RAM for each triangle.
Included with OpticStudio is a sample macro which may be used to create various Polygon Objects, without requiring you to define every single vertex and other details. The macro is named Polygon.ZPL and requires a few input values from the user: radius of the containing circle (note that this does not require the Polygon Object be circular), the number of edges along the “circle,” the length of the “tube”, and the number of sections along the length. For more details on how the macro generates the POB file, please refer to the syntax of this file located in the Zemax/Macros directory.
KA-01376