Using ZOS-API with C# and C++: what to install

Also available in 日本語, 简体中文

This article will show what components of MS Visual Studio need to be installed to use ZOS-API with C# or C++ and create a Standalone Application, a User Extension, a User Analysis or a User Operand.

Authored By Kaleb Niall

Disclaimer

Ansys Zemax does not officially support or endorse any of the following software or products. The views and opinions expressed in this article are those solely of the author, who is a Zemax employee, and these are only provided as guidance for other users of the ZOS-API to help get started.

Installing Visual Studio

To use C++ and C# with with ZOSAPI, it is highly recommended to use an Integrated Development Environment (IDE) when writing your C++ or C# code. Microsoft offers a community edition of their Visual Studio (https://visualstudio.microsoft.com/vs/) IDE which is what this author uses. Visual Studio provides code completion, syntax error checking, a built-in console, and a debugging tool with break points. This last feature is one of the best features of the IDE since you can inspect the properties of any object in the ZOSAPI environment.

When installing, make sure to install the three core Windows workloads and any other supplementary workloads desired.

When the download process is finished, launch OpticStudio and try some examples!

C++ Example

Let’s try a simple example to compile and run some code in C++. Open OpticStudio and navigate to the “Programming” tab. Open a new Standalone Application from the C++ dropdown.

This will open Visual Studio with the “Boilerplate” C++ code which will establish a connection with OpticStudio when run. This code can be accessed by expanding the “CppStandaloneApplication” line in the Solution Explorer and then clicking on “CppStandaloneApplication.cpp”

Now we will be able to add in custom code on line 55 where is says “// Add your custom code here…”. Try pasting in the code below. This code, which is taken from the API Syntax Help Example 1, will set up a simple sequential system and then use the quick focus tool to bring the image plane into focus. It will then save the system as “e01_new_file_and_quickfocus.zmx” in Documents\Zemax\Samples\API\CPP.

// creates a new API directory

CreateDirectory(_bstr_t(TheApplication->SamplesDir + "\\API"), NULL);

CreateDirectory(_bstr_t(TheApplication->SamplesDir + "\\API\\CPP"), NULL);

// Set up primary optical system

_bstr_t sampleDir = TheApplication->SamplesDir;

_bstr_t testFile = sampleDir + (_bstr_t)"\\API\\CPP\\e01_new_file_and_quickfocus.zmx";

// Make new file

TheSystem->New(false);

TheSystem->SaveAs(testFile);

ISDMaterialCatalogDataPtr(TheSystem->SystemData->MaterialCatalogs)->AddCatalog("SCHOTT");

// Aperture

ISystemDataPtr TheSystemData = TheSystem->SystemData;

TheSystemData->Aperture->ApertureValue = 40;

// Fields

IFieldPtr Field_1 = TheSystemData->Fields->GetField(1);

IFieldPtr NewField_2 = TheSystemData->Fields->AddField(0, 5.0, 1.0);

// Wavelength preset

bool slPreset = TheSystemData->Wavelengths->SelectWavelengthPreset(WavelengthPreset_d_0p587);

// Lens data

ILensDataEditorPtr TheLDE = TheSystem->LDE;

TheLDE->InsertNewSurfaceAt(2);

TheLDE->InsertNewSurfaceAt(2);

ILDERowPtr Surface_1 = TheLDE->GetSurfaceAt(1);

ILDERowPtr Surface_2 = TheLDE->GetSurfaceAt(2);

ILDERowPtr Surface_3 = TheLDE->GetSurfaceAt(3);

// Changes surface cells in LDE

Surface_1->Thickness = 50.0;

Surface_1->Comment = "Stop is free to move";

Surface_2->Radius = 100.0;

Surface_2->Thickness = 10.0;

Surface_2->Comment = "front of lens";

Surface_2->Material = "N-BK7";

Surface_3->Comment = "rear of lens";

// Solver

ISolveDataPtr Solver = Surface_3->RadiusCell->CreateSolveType(SolveType_FNumber);

Solver->_S_FNumber->FNumber = 10;

Surface_3->RadiusCell->SetSolveData(Solver);

// QuickFocus

IQuickFocusPtr quickFocus = TheSystem->Tools->OpenQuickFocus();

quickFocus->Criterion = QuickFocusCriterion_SpotSizeRadial;

quickFocus->UseCentroid = true;

ISystemToolPtr baseTool = quickFocus;

baseTool->RunAndWaitForCompletion();

baseTool->Close();

// Save and close

TheSystem->Save();

Once this code is copied into Visual Studio, it can be compiled and run by pressing Build… Build Solution  and then Debug… Start Without Debugging. Check out the new file that is saved in the CPP folder after the code is run. Feel free to change some of the values or lines in the code to start customizing the system. Be sure to hit Build… Rebuild Solution after making edits to the code. 

C# Example

The C# procedures will be very similar to C++. This time, open a new Standalone Application from the C# dropdown in the programming tab.

Visual Studio will open automatically, and the “boilerplate” code can be accessed by clicking on the “Program.cs” line in the Solution Explorer. Just like in the C++ example, custom code can be pasted after the line “// Add your custom code here…” The code below is the C# version of the code in the previous example.

// creates a new API directory

string strPath = System.IO.Path.Combine(TheApplication.SamplesDir, @"API\\CS");

System.IO.Directory.CreateDirectory(strPath);

// Set up primary optical system

string sampleDir = TheApplication.SamplesDir;

string testFile = sampleDir + "\\API\\CS\\e01_new_file_and_quickfocus.zmx";

// Make new file

TheSystem.New(false);

TheSystem.SaveAs(testFile);

TheSystem.SystemData.MaterialCatalogs.AddCatalog("SCHOTT");

// Aperture

ISystemData TheSystemData = TheSystem.SystemData;

TheSystemData.Aperture.ApertureValue = 40;

// Fields

IField Field_1 = TheSystemData.Fields.GetField(1);

IField NewField_2 = TheSystemData.Fields.AddField(0, 5.0, 1.0);

// Wavelength preset

bool slPreset = TheSystemData.Wavelengths.SelectWavelengthPreset(WavelengthPreset.d_0p587);

// Lens data

ILensDataEditor TheLDE = TheSystem.LDE;

TheLDE.InsertNewSurfaceAt(2);

TheLDE.InsertNewSurfaceAt(2);

ILDERow Surface_1 = TheLDE.GetSurfaceAt(1);

ILDERow Surface_2 = TheLDE.GetSurfaceAt(2);

ILDERow Surface_3 = TheLDE.GetSurfaceAt(3);

// Changes surface cells in LDE

Surface_1.Thickness = 50.0;

Surface_1.Comment = "Stop is free to move";

Surface_2.Radius = 100.0;

Surface_2.Thickness = 10.0;

Surface_2.Comment = "front of lens";

Surface_2.Material = "N-BK7";

Surface_3.Comment = "rear of lens";

// Solver

ISolveData Solver = Surface_3.RadiusCell.CreateSolveType(SolveType.FNumber);

Solver._S_FNumber.FNumber = 10;

Surface_3.RadiusCell.SetSolveData(Solver);

// QuickFocus

IQuickFocus quickFocus = TheSystem.Tools.OpenQuickFocus();

quickFocus.Criterion = QuickFocusCriterion.SpotSizeRadial;

quickFocus.UseCentroid = true;

quickFocus.RunAndWaitForCompletion();

quickFocus.Close();

// Save and close

TheSystem.Save();

The code is compiled and ran in the same way by pressing Build… Build Solution and then Debug… Start Without Debugging.

More Examples

There are some extra examples that can be found in the ZOS-API Syntax Help  (Programming… ZOS-API Help…)

Note that these are complete examples, and already include the “boilerplate” code. They can be pasted into a blank C#/C++ editor and will be able to connect to OpticStudio.