disguise developers

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 and specific RigCheck endpoints.

For full background on the RigCheck workflow, see OmniCal RigCheck in the User Guide. See below for a RigCheck example workflow.

OmniCal QuickAlign adjustments are currently not supported via the API. If such adjustments 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.

OmniCal RigCheck Endpoints

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

GET cameradiscovery

Summary

Checks whether OmniCal camera discovery is currently enabled or disabled

URL

GET    /api/session/omnical/cameradiscovery

Response

{
  "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

{
  "enabled": false
}

Response

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

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

RigCheck Example Workflow

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 and aligned.

The typical use case for remote OmniCal re-calibration using the RigCheck API is detailed below.

Enable Discovery

Enable OmniCal camera discovery by calling POST cameradiscovery with enabled set to true:

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 before running a show.

Execute Plan

  1. Start a new RigCheck re-calibration by calling POST executeplan with an empty body:

    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:

    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:

    {
  "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:

    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:

    {
  "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:

    {
  "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 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 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.

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 with an empty body:

    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 with an empty body:

    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.

Disable Discovery

Disable OmniCal camera discovery after a successful RigCheck by calling POST cameradiscovery with enabled set to false:

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, to prevent the media drive from filling up, by calling POST deleteoldresults with an empty body:

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:

{
  "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": []
  }
}