ZOS-API.NET: 概要

Also available in English

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 を作成するソリューション / プロジェクトに適するように変更

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

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

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

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

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

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

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

ボイラープレート コード

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

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

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

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 アプリケーション の対応するアイコンの下に表示されます。

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

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

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