---
title: "OmniCal"
description: "Programmatic control of the OmniCal RigCheck workflow and related OmniCal features"
url: https://developer.disguise.one/api/session/omnical/
---

# OMNICAL API

Programmatic control of the OmniCal RigCheck workflow and related OmniCal features. These endpoints allow third-party systems and show controllers to trigger recalibrations, monitor progress, manage results, and handle fallback without requiring direct access to Designer. The API is split into [general OmniCal endpoints](#omnical-general-endpoints) and specific [RigCheck endpoints](#omnical-rigcheck-endpoints).

For full background on the RigCheck workflow, see [OmniCal RigCheck in the User Guide](https://help.disguise.one/workflows/calibration-projection/omnical-rigcheck). See below for a [RigCheck example workflow](#rigcheck-example-workflow).

📝

OmniCal QuickAlign adjustments are currently not supported via the API. If such [adjustments](https://help.disguise.one/workflows/calibration-projection/omnical-rigcheck#using-rigcheck) are needed, then these can usually be done by logging into a Designer session remotely.

## OmniCal General Endpoints

These endpoints allow to query OmniCal Plan information and control OmniCal camera discovery.

-   [GET cameradiscovery](#get-cameradiscovery)
-   [POST cameradiscovery](#post-cameradiscovery)
-   [GET currentplan](#get-currentplan)
-   [GET plans](#get-plans)

## OmniCal RigCheck Endpoints

These endpoints allow to trigger recalibrations, monitor progress, manage results, and handle fallback.

-   [POST executeplan](#post-executeplan)
-   [GET checkresult](#get-checkresult)
-   [POST acceptresult](#post-acceptresult)
-   [POST revertresult](#post-revertresult)
-   [GET currentresult](#get-currentresult)
-   [GET currentfallbackresult](#get-currentfallbackresult)
-   [GET results](#get-results)
-   [GET resultsforplan](#get-resultsforplan)
-   [POST deleteoldresults](#post-deleteoldresults)

## GET cameradiscovery

### Summary

Checks whether OmniCal camera discovery is currently enabled or disabled

### URL

GET    /api/session/omnical/cameradiscovery

### Response

```json
{
  "status": {
    "code": 0,
    "message": "",
    "details": [
      {
        "type_url": "",
        "value": ""
      }
    ]
  },
  "enabled": false,
  "discovery": "UNKNOWN"
}
```

## POST cameradiscovery

### Summary

Request OmniCal camera discovery to be enabled or disabled

### URL

POST    /api/session/omnical/cameradiscovery

### Request with a JSON body

```json
{
  "enabled": false
}
```

### Response

```json
{
  "status": {
    "code": 0,
    "message": "",
    "details": [
      {
        "type_url": "",
        "value": ""
      }
    ]
  },
  "enabled": false,
  "discovery": "UNKNOWN"
}
```

## GET currentplan

### Summary

Get name and UID of current OmniCal Plan set in Designer, if any

### URL

GET    /api/session/omnical/currentplan

### Response

```json
{
  "status": {
    "code": 0,
    "message": "",
    "details": [
      {
        "type_url": "",
        "value": ""
      }
    ]
  },
  "plan": {
    "name": "",
    "uid": ""
  }
}
```

## GET plans

### Summary

Get names and UIDs of all OmniCal Plans in the current Designer project, if any

### URL

GET    /api/session/omnical/plans

### Query Params

filter    RequestPlansFilter enum    

### Response

```json
{
  "status": {
    "code": 0,
    "message": "",
    "details": [
      {
        "type_url": "",
        "value": ""
      }
    ]
  },
  "plans": [
    {
      "name": "",
      "uid": ""
    }
  ]
}
```

## POST executeplan

### Summary

Runs a new RigCheck capture, calibration, and alignment based on the current OmniCal Plan settings and saves the data in a Result

### URL

POST    /api/session/omnical/rigcheck/executeplan

### Response

```json
{
  "status": {
    "code": 0,
    "message": "",
    "details": [
      {
        "type_url": "",
        "value": ""
      }
    ]
  }
}
```

## GET checkresult

### Summary

Checks the progress of the current OmniCal RigCheck and, if completed, returns success and quality information about the Result calibration and alignment

### URL

GET    /api/session/omnical/rigcheck/checkresult

### Response

```json
{
  "status": {
    "code": 0,
    "message": "",
    "details": [
      {
        "type_url": "",
        "value": ""
      }
    ]
  },
  "result": {
    "status": "UNKNOWN",
    "feedback": "",
    "omniCalScore": 0,
    "cameraRmsError": 0,
    "projectorRmsError": 0
  }
}
```

## POST acceptresult

### Summary

Accepts the current OmniCal RigCheck Result as the new Fallback Result, if possible

### URL

POST    /api/session/omnical/rigcheck/acceptresult

### Response

```json
{
  "status": {
    "code": 0,
    "message": "",
    "details": [
      {
        "type_url": "",
        "value": ""
      }
    ]
  }
}
```

## POST revertresult

### Summary

Reverts the current OmniCal RigCheck Result and switches to the current Fallback Result, if possible

### URL

POST    /api/session/omnical/rigcheck/revertresult

### Response

```json
{
  "status": {
    "code": 0,
    "message": "",
    "details": [
      {
        "type_url": "",
        "value": ""
      }
    ]
  }
}
```

## GET currentresult

### Summary

Returns the name and UID of the OmniCal RigCheck Result set as current in Designer, if any

### URL

GET    /api/session/omnical/rigcheck/currentresult

### Response

```json
{
  "status": {
    "code": 0,
    "message": "",
    "details": [
      {
        "type_url": "",
        "value": ""
      }
    ]
  },
  "result": {
    "name": "",
    "uid": ""
  }
}
```

## GET currentfallbackresult

### Summary

Returns the name and UID of the OmniCal RigCheck Result set as the fallback in Designer, if any

### URL

GET    /api/session/omnical/rigcheck/currentfallbackresult

### Response

```json
{
  "status": {
    "code": 0,
    "message": "",
    "details": [
      {
        "type_url": "",
        "value": ""
      }
    ]
  },
  "result": {
    "name": "",
    "uid": ""
  }
}
```

## GET results

### Summary

Returns the names and UIDs of all OmniCal RigCheck Results in the current Designer project, if any

### URL

GET    /api/session/omnical/rigcheck/results

### Query Params

filter    RequestPlansFilter enum    

### Response

```json
{
  "status": {
    "code": 0,
    "message": "",
    "details": [
      {
        "type_url": "",
        "value": ""
      }
    ]
  },
  "results": [
    {
      "name": "",
      "uid": ""
    }
  ]
}
```

## GET resultsforplan

### Summary

Returns the names and UIDs of OmniCal RigCheck Results that were executed from the specified Plan, if any

### URL

GET    /api/session/omnical/rigcheck/resultsforplan

### Query Params

uid    uint64    

name    string    

filter    RequestPlansFilter enum    

### Response

```json
{
  "status": {
    "code": 0,
    "message": "",
    "details": [
      {
        "type_url": "",
        "value": ""
      }
    ]
  },
  "results": [
    {
      "name": "",
      "uid": ""
    }
  ]
}
```

## POST deleteoldresults

### Summary

Deletes unused old OmniCal RigCheck Results to free up disk space

### URL

POST    /api/session/omnical/rigcheck/deleteoldresults

### Response

```json
{
  "status": {
    "code": 0,
    "message": "",
    "details": [
      {
        "type_url": "",
        "value": ""
      }
    ]
  }
}
```

## RigCheck Example Workflow

[OmniCal RigCheck](https://help.disguise.one/workflows/calibration-projection/omnical-rigcheck) is the tool for quickly re-calibrating without advanced knowledge of the rest of the OmniCal system. It is primarily used by operators at fixed installations to re-calibrate shows after minor external changes such as changes in projector position, or projector lens changes or replacements.

The requirement for this workflow is to have a previously set up OmniCal Plan that is well [calibrated](https://help.disguise.one/workflows/calibration-projection/omnical-calibration) and [aligned](https://help.disguise.one/workflows/calibration-projection/omnical-alignment).

The typical use case for remote OmniCal re-calibration using the [RigCheck API](#omnical-rigcheck-endpoints) is detailed below.

### Enable Discovery

Enable OmniCal camera discovery by calling [POST cameradiscovery](#post-cameradiscovery) with `enabled` set to `true`:

```cmd
curl -X POST "http://127.0.0.1/api/session/omnical/cameradiscovery" -H "accept: application/json" -H "Content-Type: application/json" -d "{ \"enabled\": true}"
```

This step is optional, since **executeplan** will automatically enable camera discovery, if it was not enabled, yet. Since it may take a few seconds for all cameras to come online, explicitly enabling discovery will reduce the initial delay when calling **executeplan**.

Note that camera discovery occupies CPU and network resources on the Director, and must therefore be [disabled](#disable-discovery) before running a show.

### Execute Plan

1.  Start a new RigCheck re-calibration by calling [POST executeplan](#post-executeplan) with an empty body:
    
    ```cmd
    curl -X POST "http://127.0.0.1/api/session/omnical/rigcheck/executeplan" -H "accept: application/json" -H "Content-Type: application/json" -d "{}"
    ```
    
    OmniCal will run a capture, calibration and alignment with the settings from the original Plan. This may take some time.
    
2.  Wait until the RigCheck is done. To check its progress it’s possible to periodically poll [GET checkresult](#get-checkresult):
    
    ```cmd
    curl -X GET "http://127.0.0.1/api/session/omnical/rigcheck/checkresult" -H "accept: application/json"
    ```
    
    While the RigCheck is still in progress the response body will look similar to this:
    
    ```json
    {
      "status": {
        "code": 0,
        "message": "Most recent OmniCal task is real RigCheck Result: 'plan 12mm_result_000'.\nExecute Plan Task state: complete=0, success=0, cancelled=0, fatalErrors=0, progress=0.57\n",
        "details": []
      },
      "result": {
        "status": "Amber",
        "feedback": "RigCheck still in progress.",
        "omniCalScore": 10000,
        "cameraRmsError": 10000,
        "projectorRmsError": 10000
      }
    }
    ```
    

### Evaluate RigCheck Result

1.  Get the RigCheck result by calling [GET checkresult](#get-checkresult):
    
    ```cmd
    curl -X GET "http://127.0.0.1/api/session/omnical/rigcheck/checkresult" -H "accept: application/json"
    ```
    
    The API caller can store the result information for later comparisons.
    
    If the RigCheck has completed, the response body will look similar to this:
    
    ```json
    {
      "status": {
        "code": 0,
        "message": "Most recent OmniCal task is simulated RigCheck Result: 'plan 12mm_result_000'.\nNo OmniCal Tasks in progress.",
        "details": []
      },
      "result": {
        "status": "Green",
        "feedback": "OmniCal successful. Capture and Calibration are good; please check alignment visually.\nOmniCal Score is excellent.\nAggregate Camera error is excellent.\nAggregate Projector error is excellent.\n",
        "omniCalScore": 0.2,
        "cameraRmsError": 0.200915024,
        "projectorRmsError": 0.184068009
      }
    }
    ```
    
    If the RigCheck failed to complete, the response will look similar to this:
    
    ```json
    {
      "status": {
        "code": 0,
        "message": "Most recent OmniCal task is real RigCheck Result: 'plan 12mm_result_000'.\nNo OmniCal Tasks in progress.",
        "details": []
      },
      "result": {
        "status": "Red",
        "feedback": "Incomplete capture.",
        "omniCalScore": 10000,
        "cameraRmsError": 10000,
        "projectorRmsError": 10000
      }
    }
    ```
    
2.  Visually Evaluate the Result:  
    If the calibration was successful, then follow it up with a **visual inspection of the physical stage**. This ensures that the alignment on the physical projection surfaces is still visually correct.  
    If the alignment is off, then this usually means that the OmniCal cameras or the projection surfaces have moved since the original Plan alignment.
    
    To fix misalignments, open Designer and [adjust the RigCheck alignment](https://help.disguise.one/workflows/calibration-projection/omnical-rigcheck#using-rigcheck) manually. This can be done by remotely logging into the Director machine.
    
3.  Compare against previous RigChecks:  
    If the API caller has stored result information from previous RigChecks, then it can compare the current Result against the best or most recent successful one. This should be done by comparing only the **omniCalScore**, since RMS error values may fluctuate even under near identical conditions. Lower [OmniCal Score](https://help.disguise.one/workflows/calibration-projection/omnical-calibration#omnical-score) values are better.
    
    Based on the outcome of such comparisons the API caller should decide whether to accept or revert the current Result, or whether to simply [run a new RigCheck](#execute-plan).
    

### Accept or Revert the RigCheck Result

1.  If the calibration was successful and the alignment looks good, then accept the RigCheck Result as the new fallback by calling [POST acceptresult](#post-acceptresult) with an empty body:
    
    ```cmd
    curl -X POST "http://127.0.0.1/api/session/omnical/rigcheck/acceptresult" -H "accept: application/json" -H "Content-Type: application/json" -d "{}"
    ```
    
2.  If the calibration was unsuccessful, or results are noticeably worse than a previous RigCheck, then revert to a previous successful calibration, the “fallback Result”, by calling [POST revertresult](#post-revertresult) with an empty body:
    
    ```cmd
    curl -X POST "http://127.0.0.1/api/session/omnical/rigcheck/revertresult" -H "accept: application/json" -H "Content-Type: application/json" -d "{}"
    ```
    
    Then fix any potential external issues such as interfering light, or people walking across the stage. Then repeat from [Execute Plan](#execute-plan).
    

### Disable Discovery

Disable OmniCal camera discovery after a successful RigCheck by calling [POST cameradiscovery](#post-cameradiscovery) with `enabled` set to `false`:

```cmd
curl -X POST "http://127.0.0.1/api/session/omnical/cameradiscovery" -H "accept: application/json" -H "Content-Type: application/json" -d "{ \"enabled\": false}"
```

### Clean up old RigCheck Results

Periodically [clean up old RigCheck data](https://help.disguise.one/workflows/calibration-projection/omnical-rigcheck#delete-old-and-unused-rigcheck-results), to prevent the media drive from filling up, by calling [POST deleteoldresults](#post-deleteoldresults) with an empty body:

```cmd
curl -X POST "http://127.0.0.1/api/session/omnical/rigcheck/deleteoldresults" -H "accept: application/json" -H "Content-Type: application/json" -d "{}"
```

A possible response looks like this:

```json
{
  "status": {
    "code": 0,
    "message": "OmniCal: Deleted 2/5 old unused RigCheck Results:\nplan 12mm_result_000, plan 12mm_result_001\nAnother 3 are either newer or in use.",
    "details": []
  }
}
```