User Defined Object

There are several different ways to create user defined objects. For simple polygon based objects, such as prisms and other shapes with all flat faces, see "Polygon Object" . Objects may also be defined in an external CAD program and then imported into OpticStudio, see "CAD Part: STEP/IGES/SAT" and "CAD Part: STL" . There are also methods for user definitions for gradient index media ("Defining GRIN media for non-sequential ray tracing" ), surface scattering properties ("Scattering" ), bulk scattering properties ("Bulk scattering" ), and diffraction ("Defining DLLs for ray splitting at diffractive surfaces" ).

The method of creating a user defined object described in this section involves the use of an external, user supplied program called a Dynamic Link Library or DLL. The advantages to defining an object using a DLL, rather than the other methods listed above, are:

  • DLL defined objects generally ray trace much faster, and with much higher numerical precision, than objects imported from CAD programs.
  • Any number of complex curved shapes may be combined in a single object, unlike the polygon object which only has flat faces.
  • Objects may have a mixture of reflective and refractive curved faces, with user definable face names.
  • The DLL description is inherently parametric, which means the object is dynamically regenerated when any defining property is modified. This allows interactive design, modification, and even optimization.
  • User defined coating data, including detailed control over the complex amplitude reflection and transmission coefficients is supported. Coating data may be ray position, cosine, or object coordinate dependent.

The entire definition for the object is contained within the DLL. The DLL computes the following data:

  • The computation of basic data about the object, such as whether it is a solid volume or a hollow shell, and the names of all the used parameters.
  • The determination of a list of triangles which approximate the shape of the object. These triangles are used to render the object as well as provide a "close first guess" for ray tracing purposes.
  • The exact computation of the ray-surface intercept. Most of this code is actually inside OpticStudio; the DLL only needs to find the exact ray-surface intercept point given a very close guess. OpticStudio handles all the logic for non-sequential tracing, nesting, refraction, reflection, diffraction, optical path, scattering, etc.
  • The user defined coating data used by the object, if any. The DLL or OpticStudio can compute coating data.
  • The starting "safe" data to use for the various free parameters when the object is first created.

The DLL must include two functions:

  • UserObjectDefinition
  • UserParamNames

The UserObjectDefinition function is called to create a list of triangles which approximate the shape of the object. OpticStudio traces rays non-sequentially to the triangles to determine close intercepts, if any. Once a potential close intercept is found, the UserObjectDefinition function is called again to determine the exact intercept. This is implemented using an iterative routine provided in any of the sample object DLL source files. A single object may contain multiple complex curved faces, each with its own defining function and iteration routines.

The best way to learn the use of Object DLLs is to study an existing DLL and modify it as needed. The sample DLLs provided with OpticStudio include extensive documentation and comments on the data formats and DLL functions; see any of the sample object code files for examples.

All Object DLLs must be placed in the <data>\DLL\Objects folder.

Face Numbers: All faces have user definable Face numbers.

If you require a User Defined Object DLL, but do not wish to write the DLL yourself, contact OpticStudio Technical Support.

Sample Object DLLs

The following sample object DLLs and source code are included with OpticStudio.

SAMPLE OBJECT DLLS

CoatingSample A rectangular surface, with user definable dimensions in x, y. This sample shows how to implement user defined coating data. The transmission of this rectangle is 1.0 outside of a circle of radius "a", and a user defined value inside of the circle.

EllipticalVolume An elliptical solid volume, with user definable dimensions in x, y, and z. This DLL demonstrates the creation of a list of triangles to approximate the object shape, naming object faces, and exact ray-surface iteration to arbitrary surface description functions.

HalfCylinder A half cylinder, with user definable radius and length. This DLL demonstrates the creation of a list of triangles to approximate the object shape, naming object faces, and exact ray-surface iteration to arbitrary surface description functions.

DiffractionGrating A rectangular volume with a simple linear grating on the front face, with user definable dimensions in x, y and length. This DLL shows how to define a diffractive object. Any ray traced to the front face will call the associated diffraction DLL defined under Object Properties > Diffraction (see for example "diff_samp_1.DLL").

Next: