Interface ZOSAPI::Tools::ISystemTool

Definition:

Base interface for all system tools. See IOpticalSystemTools for access to specific tools.

Inherited by:

• ZOSAPI.Tools.FileManager.IConvertProjectToFileTool
• ZOSAPI.Tools.General.IComputeRMSSpotSize
• ZOSAPI.Tools.General.ICreateArchive
• ZOSAPI.Tools.General.ICreateProject
• ZOSAPI.Tools.General.IExportCAD
• ZOSAPI.Tools.General.ILensCatalogs
• ZOSAPI.Tools.General.IQuickAdjust
• ZOSAPI.Tools.General.IQuickFocus
• ZOSAPI.Tools.General.IRayAimingWizard
• ZOSAPI.Tools.General.IRestoreArchive
• ZOSAPI.Tools.General.IRestoreProject
• ZOSAPI.Tools.General.IScale
• ZOSAPI.Tools.IConvertToNSCGroup
• ZOSAPI.Tools.ICriticalRaysetGenerator
• ZOSAPI.Tools.IDesignLockdown
• ZOSAPI.Tools.IExportToSpeosLensSystem
• ZOSAPI.Tools.IExportToSpeosWhitebox
• ZOSAPI.Tools.IFileManager
• ZOSAPI.Tools.IMFCalculator
• ZOSAPI.Tools.IMaterialsCatalog
• ZOSAPI.Tools.IShadedModelVisualizationExport
• ZOSAPI.Tools.Layouts.I3DViewerExport
• ZOSAPI.Tools.Layouts.ICrossSectionExport
• ZOSAPI.Tools.Layouts.INSC3DLayoutExport
• ZOSAPI.Tools.Layouts.INSCShadedModelExport
• ZOSAPI.Tools.Layouts.IShadedModelExport
• ZOSAPI.Tools.Optimization.IGlobalOptimization
• ZOSAPI.Tools.Optimization.IHammerOptimization
• ZOSAPI.Tools.Optimization.ILocalOptimization
• ZOSAPI.Tools.Optimization.INSCQuickFocus
• ZOSAPI.Tools.OptimizationTools.IConvertAsphereType
• ZOSAPI.Tools.OptimizationTools.IFindBestAsphere
• ZOSAPI.Tools.RayTrace.IBatchRayTrace
• ZOSAPI.Tools.RayTrace.ILightningTrace
• ZOSAPI.Tools.RayTrace.INSCRayTrace
• ZOSAPI.Tools.RayTrace.IZRDReader
• ZOSAPI.Tools.Sequences.ISequenceSelector
• ZOSAPI.Tools.Tolerancing.IQuickSensitivity
• ZOSAPI.Tools.Tolerancing.IToleranceDataViewer
• ZOSAPI.Tools.Tolerancing.IToleranceNest
• ZOSAPI.Tools.Tolerancing.ITolerancing

Members

• CanCancel
• Cancel
• Close
• ErrorMessage
• IsAsynchronous
• IsFiniteDuration
• IsRunning
• IsValid
• Progress
• Run
• RunAndWaitForCompletion
• RunAndWaitWithTimeout
• Status
• Succeeded
• WaitForCompletion
• WaitWithTimeout

Properties

Property Progress

Definition:

int ZOSAPI.Tools.ISystemTool.Progress

Gets the progress of the current tool, if supported.

The progress (0-100)

Return type: int

Property Status

Definition:

string ZOSAPI.Tools.ISystemTool.Status

Gets the status of the current tool, if supporoted.

The status message;

Return type: string

Property IsRunning

Definition:

bool ZOSAPI.Tools.ISystemTool.IsRunning

Gets a value indicating whether the tool is currently running asynchronously.

true if the tool is currently running; otherwise, false.

Return type: bool

Property CanCancel

Definition:

bool ZOSAPI.Tools.ISystemTool.CanCancel

Gets a value indicating whether the tool can be cancelled.

true if this tool is asynchronous and can be cancelled; otherwise, false.

Return type: bool

Property IsAsynchronous

Definition:

bool ZOSAPI.Tools.ISystemTool.IsAsynchronous

Gets a value indicating whether the tool runs asynchronously (i.e. on a thread).

true if this the tool is asynchronous; otherwise, false.

Return type: bool

Property IsFiniteDuration

Definition:

bool ZOSAPI.Tools.ISystemTool.IsFiniteDuration

Gets a value indicating whether this tool will complete on its own.

true if the tool is synchronous, or if it is asynchronous and will terminate on its own; otherwise, false.

Return type: bool

Property IsValid

Definition:

bool ZOSAPI.Tools.ISystemTool.IsValid

Gets a value indicating whether the input settings are valid.

true if the settings are valid; otherwise, false.

Return type: bool

Property Succeeded

Definition:

bool ZOSAPI.Tools.ISystemTool.Succeeded

Gets a value indicating whether the tool execution succeeded.

true if the last execution of the tool succeeded; otherwise, false.

Return type: bool

Property ErrorMessage

Definition:

string ZOSAPI.Tools.ISystemTool.ErrorMessage

If Succeeded is false, get the error messages; otherwise, null.

The error message.

Return type: string

Public functions

Function Run

bool ZOSAPI.Tools.ISystemTool.Run()

Start the tool. Note that for synchronous tools (see IsAsynchronous), this call will block until completion. If it is asynchronous it will start running but return immediately.

Usage (see Example 20 for a full sample)

C#

            // Starting exporting
            // Run with a 3 minites timeout
            Console.Write("Starting exporting...");
            ToolExportCAD.Run();
            RunStatus runstatus = ToolExportCAD.WaitWithTimeout(3 * 60);

            // Report the status
            switch (runstatus)
            {
                case RunStatus.Completed:
                    Console.WriteLine("Completed!");
                    break;
                case RunStatus.FailedToStart:
                    Console.WriteLine("Failed To Start!");
                    break;
                case RunStatus.InvalidTimeout:
                    Console.WriteLine("Invalid Timeout!");
                    break;
                case RunStatus.TimedOut:
                    Console.WriteLine("Timed Out!");
                    break;
            }
            Console.WriteLine("Progress: " + ToolExportCAD.Progress.ToString("000") + "%");

            // If the exporting is not completed and can be cancelled, cancel the work
            if (runstatus != RunStatus.Completed & ToolExportCAD.CanCancel)
            {
                ToolExportCAD.Cancel();
            }

            // Close the tool
            ToolExportCAD.Close();

C++

    // Starting exporting
    // Run with a 3 minites timeout
    // Run() and WaitWithTimeout() is inherited from interface ISystemTool.
    // In C++ we need to cast before using these methods.
    cout << "Starting exporting..." << endl;
    ISystemToolPtr baseTool = ToolExportCAD;
    baseTool->Run();
    RunStatus runstatus = baseTool->WaitWithTimeout(3 * 60);

    // Report the status
    switch (runstatus)
    {
    case RunStatus_Completed:
        cout << "Completed!" << endl;
        break;
    case RunStatus_FailedToStart:
        cout << "Failed To Start!" << endl;
        break;
    case RunStatus_InvalidTimeout:
        cout << "Invalid Timeout!" << endl;
        break;
    case RunStatus_TimedOut:
        cout << "Timed Out!" << endl;
        break;
    }
    cout << "Progress: " << baseTool->Progress << endl;

    // If the exporting is not completed and can be cancelled, cancel the work
    if (runstatus != RunStatus_Completed & baseTool->CanCancel)
    {
        baseTool->Cancel();
    }

    // Close the tool
    baseTool->Close();

Matlab

    % Starting exporting
    % Run with a 3 minites timeout
    fprintf('Starting exporting...\n');
    ToolExportCAD.Run();
    [runstatus] = ToolExportCAD.WaitWithTimeout(3 * 60);
    
    % Report the status
    switch (runstatus)
        case ZOSAPI.Tools.RunStatus.Completed
            fprintf('Completed!\n');
        case ZOSAPI.Tools.RunStatus.FailedToStart
            fprintf('Failed To Start!\n');
        case ZOSAPI.Tools.RunStatus.InvalidTimeout
            cfprintf('Invalid Timeout!\n');
        case ZOSAPI.Tools.RunStatus.TimedOut
            fprintf('Timed Out!\n');
    end
    
    fprintf('Progress: %i\n', ToolExportCAD.Progress);
    
    % If the exporting is not completed and can be cancelled, cancel the work
    if (runstatus ~= ZOSAPI.Tools.RunStatus.Completed && ToolExportCAD.CanCancel)
        ToolExportCAD.Cancel();
    end

    % Close the tool
    ToolExportCAD.Close();

Python

    # Starting exporting
    # Run with a 3 minites timeout
    print('Starting exporting...')
    
    ToolExportCAD.Run()
    runstatus = ToolExportCAD.WaitWithTimeout(float(3 * 60))

    # Report the status
    if runstatus == ZOSAPI.Tools.RunStatus.Completed:
        print('Completed!')
    elif runstatus == ZOSAPI.Tools.RunStatus.FailedToStart:
        print('Failed To Start!')
    elif runstatus == ZOSAPI.Tools.RunStatus.InvalidTimeout:
        print('Invalid Timeout')
    else:
        print('Timed Out!')

    print('Progress: ', ToolExportCAD.Progress)

    # If the exporting is not completed and can be cancelled, cancel the work
    if (runstatus != ZOSAPI.Tools.RunStatus.Completed and ToolExportCAD.CanCancel):
        ToolExportCAD.Cancel()

    # Close the tool
    ToolExportCAD.Close()

Returns:

true if the tool successfully started (and, for synchronous tools, completed); otherwise, false.

Note that if the tool is already running this will return false

.

Return type: bool

Function RunAndWaitForCompletion

bool ZOSAPI.Tools.ISystemTool.RunAndWaitForCompletion()

Sames as calling Run followed by WaitForCompletion.

Usage (see Example 15 for a full sample)

C#

            //change BFL & run quick focus                         
            Surface_Last.Thickness = 40.0;
            IQuickFocus QFocus = tools.OpenQuickFocus();
            QFocus.Criterion = QuickFocusCriterion.SpotSizeRadial;
            QFocus.UseCentroid = true;
            QFocus.RunAndWaitForCompletion();
            QFocus.Close();
            SampleFile = System.IO.Path.Combine(TheApplication.SamplesDir, @"API\CS\e15_Seq_Optimization\OptimizedFile2.zos");
            TheSystem.SaveAs(SampleFile);

C++

    // change BFL & run quick focus
    Surface_Last->Thickness = 40.0;
    IQuickFocusPtr QFocus = tools->OpenQuickFocus();
    QFocus->Criterion = QuickFocusCriterion::QuickFocusCriterion_SpotSizeRadial;
    QFocus->UseCentroid = true;
    ISystemToolPtr baseTool = QFocus;
    baseTool->RunAndWaitForCompletion();
    baseTool->Close();
    SampleFile = _bstr_t(TheApplication->SamplesDir) + "\\API\\CPP\\e15_Seq_Optimization\\OptimizedFile2.zos";
    TheSystem->SaveAs(SampleFile);

Matlab

    %change BFL & run quick focus                         
    Surface_Last.Thickness = 40.0;
    QFocus = tools.OpenQuickFocus();
    QFocus.Criterion = ZOSAPI.Tools.General.QuickFocusCriterion.SpotSizeRadial;
    QFocus.UseCentroid = true;
    QFocus.RunAndWaitForCompletion();
    QFocus.Close();
    SampleFile = System.String.Concat(TheApplication.SamplesDir, '\API\Matlab\e15_Seq_Optimization\OptimizedFile2.zos');
    TheSystem.SaveAs(SampleFile);

Python

    # change BFL & run quick focus
    Surface_Last.Thickness = 40.0
    QFocus = tools.OpenQuickFocus()
    QFocus.Criterion = ZOSAPI.Tools.General.QuickAdjustCriterion.SpotSizeRadial
    QFocus.UseCentroid = True
    QFocus.RunAndWaitForCompletion()
    QFocus.Close()
    SampleFile = TheApplication.SamplesDir + '\\API\\Python\\e15_Seq_Optimization\\OptimizedFile2.zos'
    TheSystem.SaveAs(SampleFile)

Returns:

true if the call to Run succeeded, IsAsynchronous is true, and IsFiniteDuration is false; otherwise, false

Return type: bool

Function WaitForCompletion

bool ZOSAPI.Tools.ISystemTool.WaitForCompletion()

Waits for the asynchronous tool to complete.

Returns:

true if the tool is running, it is asynchronous, and it has a finite run duration; otherwise, false.

Return type: bool

Function Cancel

bool ZOSAPI.Tools.ISystemTool.Cancel()

Cancels the currently running asynchronous tool.

Usage (see Example 03 for a full sample)

C#

            // Hammer for 10 seconds
            Console.WriteLine("Running Hammer for 10 seconds");
            IHammerOptimization HammerOpt = TheSystem.Tools.OpenHammerOptimization();
            HammerOpt.RunAndWaitWithTimeout(10); // 10s of Hammer
            HammerOpt.Cancel();
            HammerOpt.WaitForCompletion();
            HammerOpt.Close();

C++

    // Hammer for 10 seconds
    IHammerOptimizationPtr HammerOpt = TheSystem->Tools->OpenHammerOptimization();
    baseTool = HammerOpt;
    baseTool->RunAndWaitWithTimeout(10);    
    baseTool->Cancel();
    baseTool->WaitForCompletion();
    baseTool->Close();

Matlab

    % Hammer for 10 seconds
    HammerOpt = TheSystem.Tools.OpenHammerOptimization();
    HammerOpt.RunAndWaitWithTimeout(10);    
    HammerOpt.Cancel();
    HammerOpt.WaitForCompletion();
    HammerOpt.Close();

Python

    # Hammer for 10 seconds
    # need to 'import time' at the top of the file to use the pause function
    print('Running Hammer Optimization')
    HammerOpt = TheSystem.Tools.OpenHammerOptimization()
    HammerOpt.RunAndWaitWithTimeout(10)    
    HammerOpt.Cancel()
    HammerOpt.WaitForCompletion()
    HammerOpt.Close()

Returns:

true if the tool is asynchronous and is currently running; otherwise, false

Return type: bool

Function Close

bool ZOSAPI.Tools.ISystemTool.Close()

Closes this tool and frees up and associated resources.

Usage (see Example 15 for a full sample)

C#

            //change BFL & run quick focus                         
            Surface_Last.Thickness = 40.0;
            IQuickFocus QFocus = tools.OpenQuickFocus();
            QFocus.Criterion = QuickFocusCriterion.SpotSizeRadial;
            QFocus.UseCentroid = true;
            QFocus.RunAndWaitForCompletion();
            QFocus.Close();
            SampleFile = System.IO.Path.Combine(TheApplication.SamplesDir, @"API\CS\e15_Seq_Optimization\OptimizedFile2.zos");
            TheSystem.SaveAs(SampleFile);

C++

    // change BFL & run quick focus
    Surface_Last->Thickness = 40.0;
    IQuickFocusPtr QFocus = tools->OpenQuickFocus();
    QFocus->Criterion = QuickFocusCriterion::QuickFocusCriterion_SpotSizeRadial;
    QFocus->UseCentroid = true;
    ISystemToolPtr baseTool = QFocus;
    baseTool->RunAndWaitForCompletion();
    baseTool->Close();
    SampleFile = _bstr_t(TheApplication->SamplesDir) + "\\API\\CPP\\e15_Seq_Optimization\\OptimizedFile2.zos";
    TheSystem->SaveAs(SampleFile);

Matlab

    %change BFL & run quick focus                         
    Surface_Last.Thickness = 40.0;
    QFocus = tools.OpenQuickFocus();
    QFocus.Criterion = ZOSAPI.Tools.General.QuickFocusCriterion.SpotSizeRadial;
    QFocus.UseCentroid = true;
    QFocus.RunAndWaitForCompletion();
    QFocus.Close();
    SampleFile = System.String.Concat(TheApplication.SamplesDir, '\API\Matlab\e15_Seq_Optimization\OptimizedFile2.zos');
    TheSystem.SaveAs(SampleFile);

Python

    # change BFL & run quick focus
    Surface_Last.Thickness = 40.0
    QFocus = tools.OpenQuickFocus()
    QFocus.Criterion = ZOSAPI.Tools.General.QuickAdjustCriterion.SpotSizeRadial
    QFocus.UseCentroid = True
    QFocus.RunAndWaitForCompletion()
    QFocus.Close()
    SampleFile = TheApplication.SamplesDir + '\\API\\Python\\e15_Seq_Optimization\\OptimizedFile2.zos'
    TheSystem.SaveAs(SampleFile)

Returns:

true if the tool is not currently running; otherwise, false.

Return type: bool

Function WaitWithTimeout

RunStatus ZOSAPI.Tools.ISystemTool.WaitWithTimeout(double timeOutSeconds)

Waits for the currently running tool to complete, with a specified time out value. Note that if the timeout is exceeded this method will return, however the tool will continue to run. Also note that this method will not start the tool running if it is not already.

Parameters:

• timeOutSeconds: The time out value (seconds). Note that this value must be greater than zero, else a RunStatus.InvalidTimeout value will be returned.

Returns:

A RunStatus value indicating the tool state.///

Parameters:

• double timeOutSeconds

Return type: RunStatus

Function RunAndWaitWithTimeout

RunStatus ZOSAPI.Tools.ISystemTool.RunAndWaitWithTimeout(double timeOutSeconds)

Starts the tool running, and waits for it to complete with the specified timeout value. Note that if the timeout is exceeded this method will return, however the tool will continue to run.

Parameters:

• timeOutSeconds: The time out value (seconds). Note that this value must be greater than zero, else a RunStatus.InvalidTimeout value will be returned.

Returns:

A RunStatus value indicating the tool state.///

Parameters:

• double timeOutSeconds

Return type: RunStatus