ZOS-API.NET: 概要

OpticStudio のアプリケーション プログラミング インタフェース (API) によって、最新のソフトウェア技術を用いたアプリケーションへの接続や、カスタマイズが可能です。

著者 Sanjay Gangadhara

序論

ZOS-API.NET は、OpticStudio との通信やカスタマイズを可能とする強力な手段を提供します。ユーザは、COM (C++) もしくは .NET (C#) いずれかでビルドされるアプリケーションを作成できます。アプリケーションは API を通じて、開いている OpticStudio インスタンスと直接通信する、もしくはバックグラウンド処理として OpticStudio を実行できます。API には非常に多くの機能が存在し、OpticStudio の将来的なリリースに伴って開発されます。

この記事では、ZOS-API を始める方法を紹介し、独自のアプリケーションを作成するうえで有益な機能やヒントを提供します。

ZOS-API.NET 入門

ZOS-API.NET を通じて OpticStudio と通信する方法は 2 つあります。1 つはスタンドアロンのアプリケーションで、対話する OpticStudio のコピーを立ち上げます (スタンドアロン モード)。もう 1 つは OpticStudio がすでに実行されている状態で、アプリケーションを呼び出します (他のすべてのモード、継承モードと呼びます)。こちらのリンク から無料の Microsoft Visual Studio 2017 の Express Edition が利用できます。

Visual Studio で新しい C# プロジェクトを作成します。

  1. File...New...Project... を選択
  2. Template...Visual C#...Console Application を選択
  3. Name, Solution name を作成するソリューション / プロジェクトに適するように変更

下図のように設定します。

Visual Studio Setup 1

OK をクリックすると、ソリューション / プロジェクトが生成されます。下図のようになります。

  Visual Studio Setup 2

Solution Explore の References 上で右クリックして、メニューで Add Reference… を選択します。次に、Reference Manager で Browser をクリックし、OpticStudio がインストールされたディレクトリに移動します。ZOSAPI.dll をクリックし、<Ctrl-Click> でZOSAPI_Interfaces.dll を追加します。下図のようになります。

Visual Studio Setup 3

Add を選択し、OK を押します。

Visual Studio Setup 4

次に、References 上で右クリックして、メニューでAdd Reference… を選択します。

Visual Studio Setup 5

Reference Manager で Browse を選択し、ZOS-API/Libraries へ移動します。次に、 ZOSAPI_NetHelper.dll を選択し、Add を押し、OK を押します。Reference Manager に ZOSAPI_NetHelper.dll があることを確認します。

Visual Studio Setup 8

Solution Explore...ReferencesZOSAPI 上で右クリックし、メニューから Properties を選択します。Copy Local を False に変更します。ZOSAPI_Interfaces で同じ処理を行います。ZOSAPI_NetHelper の Properties は変更しません。

Visual Studio Setup 9

ボイラープレート コード

OpticStudio のプログラミング タブにある ZOS-API.NET アプリケーション ビルダー セクションには、ボイラープレート コードを自動的に生成する有用なビルトイン ツールがあります。

  ZOS-API.NET Application Builders

ボイラープレート コード テンプレートは、C#, C++, MATLAB, Python を使用するプログラミング アプリケーション向けに提供されています。C#, C++ には、すべての接続モード向けのテンプレートが使用できます。

 C# Standalone Application

MATLAB と Python には、スタンドアロン アプリケーションとインタラクティブ拡張機能向けのテンプレートが使用できます。

  Python Interactive Extension

ZOS-API.NET で作成されたアプリケーションをコンパイルするのに Visual Studio Express を使用する場合、for Windows Desktop か for Community エディションを使用する必要があります。Visual Studio の他のバージョンでは、API でコンパイルできません。

以下の示すコードの一部は、ZOS-API を用いて作成するすべてのアプリケーションで必要なる標準的なボイラープレート コードです。これらのサンプルには、完全なエラー処理は含まれていません。独自のエラー処理を加えることを強く推奨します。各戻り値を使用する前に、”null” と照合することを推奨します。同様に、コードを try / catch ブロックに分割することで不可解な動作の処理が容易になります。ここでの変数名は、”自己文書化” を意図していますが、必要に応じて自由に変更できます。

注釈: Main() はシステムを初期化してから別の関数を呼び出して API と実際に “接続” することで、アプリケーションが実際の作業を行います。オペレーティング システムとコンパイラの最適化で適用される “オペレーション順番の最適化” によって、特定のコード シーケンスが “まだ存在しない” 機能を “プリロード” する場合があります。したがって、”Main” が 2 次機能を呼び出し、その 2 次機能がアプリケーションのすべての “作業” を指示するのがベストプラクティスです。

注釈: 必ずしも必要ではありませんが、APIで作成されたアプリケーションを起動する前にライセンスのステータスを確認することをお勧めします。ライセンスが最新でない場合、もしくは OpticStudio への接続時に他のライセンス エラーが起きている場合は、アプリケーションが正しく動作する可能性が低くなります。

スタンドアロン モードのボイラープレート コード

using System; using ZOSAPI;

namespace CSharpStandaloneApplication

{

    class Program

    {

        static void Main(string[] args)

        {

            bool isInitialized = ZOSAPI_NetHelper.ZOSAPI_Initializer.Initialize();

            if (isInitialized)

            {

                LogInfo("Found OpticStudio at: " + ZOSAPI_NetHelper.ZOSAPI_Initializer.GetZemaxDirectory());

            }

            else

            {

                HandleError("Failed to locate OpticStudio!");

                return;

            }

           

            BeginStandaloneApplication();

        }

 

        static void BeginStandaloneApplication()

        {

            ZOSAPI_Connection TheConnection = new ZOSAPI_Connection();

            IZOSAPI_Application TheApplication = TheConnection.CreateNewApplication();

            if (TheApplication == null)

                {

                HandleError("An unknown connection error occurred!");

                     return;

                }

            if (!TheApplication.IsValidLicenseForAPI)

            {

                HandleError("Failed to connect to OpticStudio: " + TheApplication.LicenseStatus);

                return;

            }

            if (TheApplication.Mode != ZOSAPI_Mode.Server)

            {

                HandleError("User plugin was started in the wrong mode: expected Server, found " + TheApplication.Mode.ToString());

                return;

            }

 

            IOpticalSystem TheSystem = TheApplication.PrimarySystem;

           

 

                FinishStandaloneApplication(TheApplication);

        }

           static void FinishStandaloneApplication(IZOSAPI_Application TheApplication)

           {

                if (TheApplication != null)

                {

                     TheApplication.CloseApplication();

                }

           }

 

        static void LogInfo(string message)

        {

            Console.WriteLine(message);

        }

 

        static void HandleError(string errorMessage)

        {

            throw new Exception(errorMessage);

        }

 

    }

}

継承モードのボイラープレート コード

以下は、OpticStudio がすでに実行されておりアプリケーションを呼び出すためのボイラープレート コードです (“継承” モードと呼びます)。

using System;

using ZOSAPI;

namespace CSharpUserExtensionApplication

{

    class Program

    {

        static void Main(string[] args)

        {

            bool isInitialized = ZOSAPI_NetHelper.ZOSAPI_Initializer.Initialize();

            if (isInitialized)

            {

                LogInfo("Found OpticStudio at: " + ZOSAPI_NetHelper.ZOSAPI_Initializer.GetZemaxDirectory());

            }

            else

            {

                HandleError("Failed to locate OpticStudio!");

                return;

            }

           

            BeginUserExtension();

        }

        static void BeginUserExtension()

        {

            ZOSAPI_Connection TheConnection = new ZOSAPI_Connection();

            IZOSAPI_Application TheApplication = null;

            try

            {

                TheApplication = TheConnection.ConnectToApplication();

            }

            catch (Exception ex)

            {

                HandleError(ex.Message);

                return;

            }

            if (TheApplication == null)

            {

                HandleError("An unknown connection error occurred!");

                return;

            }

            if (TheApplication.Mode != ZOSAPI_Mode.Plugin)

            {

                HandleError("User plugin was started in the wrong mode: expected Plugin, found " + TheApplication.Mode.ToString());

                return;

            }

               

            if (!TheApplication.IsValidLicenseForAPI)

            {

                HandleError("Failed to connect to OpticStudio: " + TheApplication.LicenseStatus);

                return;

            }

            TheApplication.ProgressPercent = 0;

            TheApplication.ProgressMessage = "Running Extension...";

            IOpticalSystem TheSystem = TheApplication.PrimarySystem;

                if (!TheApplication.TerminateRequested)

            {

           

            }

               

          

            FinishUserExtension(TheApplication);

        }

          

           static void FinishUserExtension(IZOSAPI_Application TheApplication)

           {

                if (TheApplication != null)

                {

                TheApplication.ProgressMessage = "Complete";

                TheApplication.ProgressPercent = 100;

                }

           }

        static void LogInfo(string message)

        {

            Console.WriteLine(message);

        }

        static void HandleError(string errorMessage)

        {

            throw new Exception(errorMessage);

        }

    }

}

継承モードを使用して C++ もしくは C# で作成されたアプリケーションは、スタンドアロン モードを使用して作成されたアプリケーションと同様に、実行ファイル (.exe) にコンパイルされますが、継承モードのアプリケーションを OpticStudio で .exe ファイルを使用するためには、OpticStudio のプログラム フォルダにコピーもしくはビルトする必要があります。

  • ユーザー拡張機能モードで作成されたアプリケーションは、Zemax\ZOS-API\Extensions フォルダに置きます。
  • ユーザー オペランド モードで作成されたアプリケーションは、Zemax\ZOS-API\Operands フォルダに置きます。
  • ユーザー 解析モードで作成されたアプリケーションは、Zemax\ZOS-API\User Analysis フォルダに置きます。

Zemax\ZOS-API\Extensions, Zemax\ZOS-API\User Analysis フォルダに置かれたアプリケーションは、プログラミング... ZOS-API アプリケーション の対応するアイコンの下に表示されます。

  User Analyses and User Extensions

ZOS-API を通じて可能な機能

上記に示した本記事の 2 つのセクション (ZOS-API.NET 入門およびボイラープレート コード) の詳細については、ZOS-API.NET の完全なドキュメントから抜粋したものです。ドキュメントは、OpticStudio ヘルプファイルの “ZOS-API ヘルプ” で確認できます。このアイコンには、プログラミング ... ZOS-API アプリケーション にあります。

  ZOS-API.NET Help Introduction

API を用いてアプリケーションを開発する前に、ヘルプファイル ドキュメントを読むことを強く推奨します。API で用いられるインタフェースに関するドキュメントや、C++, C#, Python, MATLAB の有用なサンプルの多くが、シンタックス ヘルプ ドキュメントで確認できます。

以下では、ZOS-API.NET で現在使用可能な機能のまとめを示します。

システム エクスプローラ

  • すべてのアイテムの値が、すべてのプログラム モードで取得と編集ができます。

エディタ (レンズデータ、ノンシーケンシャル コンポーネント、マルチ コンフィグレーション、メリット ファンクション、公差解析データ)

  • すべてのアイテムの値が、すべてのプログラム モードで取得と編集ができます。
    • すべての場合において、セルは列のヘッダーではなく列の番号で参照されます。
  • 設定ダイアログにあるすべてのデータの値が、すべてのプログラム モードで取得と編集ができます。

解析

以下の解析について、API を通じて直接設定を定義し、解析結果をデータアレイに直接保持できます。

  • Detector Viewer
  • Field Curvature and Distortion
  • Longitudinal Aberration
  • Lateral Color
  • Chromatic Focal Shift
  • Wavefront Map
  • Interferogram
  • Foucault Analysis
  • FFT PSF
  • FFT PSF Cross-Section
  • FFT Line/Edge Spread
  • Huygens PSF
  • Huygens PSF Cross-Section
  • FFT MTF
  • FFT Through Focus MTF
  • FFT Surface MTF
  • FFT MTF vs. Field
  • FFT MTF Map
  • Huygens MTF
  • Huygens Through Focus MTF
  • Huygens Surface MTF
  • Huygens MTF vs. Field
  • Geometric MTF
  • Geometric Through Focus MTF
  • Geometric MTF vs. Field
  • Geometric MTF Map
  • RMS vs. Field
  • RMS vs. Wavelength
  • RMS vs. Focus
  • RMS Field Map
  • Diffraction Enclosed Energy
  • Geometric Enclosed Energy
  • Geometric Line/Edge Spread
  • Extended Source Enclosed Energy
  • Surface Sag
  • Surface Phase
  • Surface Curvature
  • Surface Sag Cross-Section
  • Surface Phase Cross-Section
  • Surface Curvature Cross-Section
  • Full-Field Aberration
  • Contrast Loss Map
  • Grin Profile

上記の解析について、結果の出力データは現在のデータベースのデータに基づきます (例えば、開いたファイルからデータを読み込む場合はセッション ファイルの一部として保存されたデータ)。もしくは、解析の設定が変更されたのち、結果が取得されます。結果には、計算した結果そのものと、ユーザ インタフェースの解析結果として表示されるテキスト / ヘッダー データが含まれます。

以下の解析については、API を通じて直接設定を定義し、GetTextFile メソッドを使って結果を保持できます。

  • Single Ray Trace
  • Ray Fan
  • Standard Spot Diagram
  • Footprint Diagram
  • Through Focus Spot Diagram
  • Full Field Spot Diagram
  • Matrix Spot Diagram
  • Configuration Matrix Spot Diagram
  • OPD Fan
  • Pupil Aberration Fan
  • Grid Distortion
  • Seidel Coefficients
  • Seidel Diagram
  • Zernike Fringe Coefficients
  • Zernike Standard Coefficients
  • Zernike Annular Coefficients
  • Zernike Coefficients vs. Field

他のすべての解析については、ModifySettings メソッドを使って設定を定義し、GetTextFile メソッドを使って結果を保持できます。

ツール

以下のルールがサポートされています。(ツールの場所はカッコ内に記載されています。)

  • Add Coatings to All Surfaces (Lens Data Editor)
  • Convert Global To Local Coordinates (Lens Data Editor)
  • Convert Local To Global Coordinates (Lens Data Editor)
  • Convert Semi Diameters to Circular (Lens Data Editor)
  • Convert Semi Diameters to Floating (Lens Data Editor)
  • Convert Semi Diameters to Maximum (Lens Data Editor)
  • Remove All Apertures (Lens Data Editor)
  • Replace Vignetting with Apertures (Lens Data Editor)
  • Reload Object (Non-Sequential Component Editor)
  • Reload All Objects (Non-Sequential Component Editor)
  • Delete Configuration (Multi-Configuration Editor)
  • Insert Configuration (Multi-Configuration Editor)
  • Next Configuration (Multi-Configuration Editor)
  • Previous Configuration (Multi-Configuration Editor)
  • Insert Configuration with Pickups (Multi-Configuration Editor)
  • Make Single Configuration (Multi-Configuration Editor)
  • Insert Merit Function (Merit Function Editor)
  • Load Merit Function (Merit Function Editor)
  • Save Merit Function (Merit Function Editor)
  • Delete All Operands (Merit Function Editor)
  • Default Merit Function Wizard (Merit Function Editor)
  • Create Archive (File Tab)
  • Load Archive (File Tab)
  • Export CAD (File Tab)
  • Non-Sequential Ray Trace (Analyze Tab – Non-Sequential UI mode)
  • LightningTrace (Analyze Tab – Non-Sequential UI mode)
  • Remove All Variables (Optimize Tab)
  • Set All Radii Variable (Optimize Tab)
  • Set All Thickness Variable (Optimize Tab)
  • Quick Adjust (Optimize Tab)
  • Quick Focus (Optimize Tab)
  • Local Optimization (Optimize Tab)
  • Hammer Optimization (Optimize Tab)
  • Global Optimization (Optimize Tab)
  • Ray Trace of custom rays (not directly in UI; previously supported with DDE)

すべての DDE データ アイテムが ZOS-API.NET でサポートされていますが、以下の例外があります。

  • CloseUDOData
  • ReleaseWindow
  • SetUDOData
  • ExportCheck
  • GetAddress
  • GetAspect
  • GetMetaFile
  • GetRefresh
  • GetSequence
  • GetSettingsData
  • GetUDOSystem
  • PushLens
  • PushLensPermission
  • SetSettingsData
  • WindowMaximize
  • WindowMinimize
  • WindowRestore

プロジェクト環境設定

プロジェクト環境設定ダイアログにある以下のデータは、取得と編集が可能です。

  • DateTimeType
  • EncodingType
  • LanguageType
  • ShowLineAsType

最後の注意点として、Undo / Redo 機能は現在の ZOS-API ではサポートされていません。

KA-01517

この記事は役に立ちましたか?
0人中0人がこの記事が役に立ったと言っています

コメント

0件のコメント

サインインしてコメントを残してください。