Overview
Camera Calibration is the process by which Iris learns how your specific PTZ (pan-tilt-zoom) camera physically moves. During calibration, Iris measures your camera's speed characteristics, zoom behavior, focal properties, and the full range of its movement — all automatically, without any manual input from you.
This "learning" process is what makes Iris's smart movement features accurate. Auto-tracking, position presets, and precision movement controls all depend on calibration data to work correctly. Without it, features like auto-tracking are unavailable.
Calibration is typically a one-time setup per camera. Once complete, Iris saves your camera's profile to a central registry. If you reconnect the same camera later, it will load the saved profile automatically — no recalibration needed.
If you do not see a pop up asking you to calibrate your camera, your camera is already successfully calibrated and saved within Iris and you do not need to recalibrate.
What You Need
Camera type: Your camera must support full pan, tilt, and zoom movement (PTZ).
Brand & model selected: You must have chosen the correct brand and model for your camera in Iris. Cameras registered as a generic "Other" model cannot be calibrated.
Camera online & powered on: The camera must be connected, online, and turned on before calibration can start.
Clear field of view: There must be visible objects in the camera's view — the camera cannot be pointed at a blank wall or into an empty, featureless room.
Good lighting: The room must be adequately lit.
No plan requirement confirmed for calibration itself. (Auto-tracking, which requires calibration, is gated by your plan.)
How to Use Camera Calibration
When Does It Start?
Calibration can be triggered in two ways:
Automatically: When you add a new camera to a room and Iris finds no saved calibration profile for it, calibration is offered automatically.
Manually: You can start (or restart) calibration at any time from the camera's Advanced Settings panel.
Start
Open Advanced Settings for the camera you want to calibrate (click the settings/gear icon on the camera card or source panel).
In the settings header, locate the "Start Calibration" button (it may also appear as "Calibration Required" with a warning triangle if the camera is using a generic driver).
A confirmation dialog titled "Camera Calibration Required" will appear. It reads:
"This is a one-time process that will take a few minutes. To ensure a successful calibration, please review our list of best practices."
Review the best-practices checklist shown in the dialog:
Verify Brand & Model — confirm you selected the right camera make/model.
Avoid Empty Rooms & Walls — there must be visible objects in the camera's view.
Prevent Camera Obstructions — keep people from walking in front of the camera during calibration.
Ensure Adequate Lighting — the room must be well lit.
Click "Start Calibration" to begin, or "Calibrate Later" to dismiss without starting.
Note: If your camera's brand and model are set to "Other," clicking the calibration button will instead warn you: "You must first select your camera's brand and model before starting calibration." Go to the Brand & Model tab in settings first.
While It's Active
What you'll see:
A notification banner appears: "The camera [name] is being calibrated. This process will take a few minutes..."
The calibration button in Advanced Settings changes to show a spinner and the label "Calibrating..." (or "Calibrating (XX%)" with a live progress percentage).
The camera badge on the source card updates to reflect the calibrating state.
What you can't do while calibration is running:
Movement controls are disabled — all pan, tilt, zoom quick-shot buttons are grayed out.
Position presets are locked — you cannot add, select, or refresh position presets.
Auto-tracking is unavailable during calibration.
Behind the scenes: Iris temporarily adjusts a few camera settings (like setting focus to automatic and turning off zoom compensation and image flip) before running its measurement routines. These settings are automatically restored to their original values once calibration finishes.
The camera will also automatically return to its starting position after calibration completes.
Stop / Finish
If Calibration Succeeds
A success notification appears: "The camera [name] is now calibrated! You can now use all the magic movement tools."
The camera badge updates to show a calibrated state. All movement controls are re-enabled, and auto-tracking becomes available.
The calibration results are saved to a central registry automatically — future sessions will load the profile without requiring recalibration.
If Calibration Fails
An error notification appears: "An error occurred during calibration. Please make sure the camera [name] is not pointed towards a wall and there is enough light in the room."
A prompt will also appear titled "Retry Calibration?" with three options:
Option | What It Does |
Retry Calibration | Restarts only the step(s) that failed — already-completed steps are skipped. |
Use Generic Driver | Fills in the missing data from a reference profile for your camera model. Less precise than a full calibration, but functional. |
Skip Calibration | Dismisses the dialog. You can recalibrate later from Advanced Settings. |
If You Stop Calibration Manually
You can close the session; the camera reverts to its previous calibration status (fully calibrated, generic, or uncalibrated — whichever it was before you started).
Limits and Restrictions
Only one calibration at a time, per camera. If calibration is already running on a camera, you cannot start a second one until the first completes or is stopped.
PTZ cameras only. Calibration requires the camera to support pan, tilt, and zoom movement. Cameras without this capability (e.g., fixed cameras, webcams) do not show the calibration option.
Brand & model must be set (not "Other"). Cameras registered as "Other" cannot be calibrated.
Duration: Calibration takes several minutes (the UI informs you "a few minutes"). The exact time depends on your camera model and response speed; there is no hard user-facing timeout.
No storage or quota limit applies to calibration itself.
The camera must be powered on and online. The button is only active when the device is in the online + powered-on state.
Embedded/local-only agents are excluded. The calibration button is not shown for cameras attached via an embedded agent.
What Happens If…
You try to start calibration while it's already running? Nothing happens. The system prevents a second calibration from starting on the same camera simultaneously. You'll need to wait for the current calibration to finish (or fail) first.
You close the browser or navigate away during calibration? Calibration runs on the camera's connected hardware, not in your browser tab. Closing the browser does not stop it. When you return to the room, the calibration status will reflect what happened while you were away — completed, failed, or still running.
Your internet drops mid-calibration? The physical calibration process continues on the hardware side. However, you may miss the live progress updates and completion notifications. When you reconnect, the current status will be reflected on the camera badge.
You stop calibration mid-way and restart it? When you retry (rather than starting fresh), Iris skips any steps that were already successfully completed and resumes from the failed or incomplete step.
Calibration partially fails? You are shown the "Retry Calibration?" dialog with three choices: retry, use a generic driver, or skip for now.
You try to use position presets during calibration? Iris shows an inline notice: "You cannot add a position preset while the camera is calibrating." or "You cannot select a position preset while the camera is calibrating." These actions are blocked until calibration finishes.
Your camera doesn't support full PTZ? The calibration option will not appear. Only cameras with absolute pan, tilt, and zoom movement capabilities are supported.
Your camera model is set to "Other"? Clicking the calibration entry point from Advanced Settings will redirect you to the Brand & Model tab with the warning: "You must first select your camera's brand and model before starting calibration."
Troubleshooting
Symptom | Likely Cause | Fix |
"Start Calibration" button is grayed out | Calibration is already running on this camera | Wait for the current calibration to finish or fail before starting again. |
"Start Calibration" button doesn't appear | Camera doesn't support PTZ, is offline, or is powered off | Ensure the camera is online and powered on. Check that it supports pan, tilt, and zoom. |
Calibration button missing; redirected to Brand & Model tab | Camera is registered as "Other" | Open Advanced Settings → Brand & Model tab and select the correct make and model. |
Calibration fails immediately or quickly | Camera is pointed at a blank wall or empty room, or lighting is poor | Point the camera toward a well-lit area with visible objects and retry. |
Calibration completes but shows "Generic driver enabled" | One or more calibration steps could not be completed for this specific camera | Use the generic driver for now, or retry calibration. From Advanced Settings, use "Start Calibration" / "Calibration Required" button to try again. |
Auto-tracking still unavailable after successful calibration | Your plan may not include auto-tracking | Check your subscription plan. Calibration is a prerequisite for auto-tracking, but your plan must also include the feature. |
Camera moved to an unexpected position after calibration | Normal behavior | Calibration moves the camera through its range. Your camera is automatically returned to its original position when calibration ends. |
Movement controls remain disabled | Calibration is still in progress | Wait for calibration to complete. Controls re-enable automatically once finished. |
FAQ
Q: Do I need to calibrate every time I reconnect my camera? No. Calibration results are saved to Iris's registry. The next time you connect the same camera, Iris loads the saved profile automatically. You only need to recalibrate if you want to update the profile or if calibration previously failed.
Q: How long does calibration take? Calibration takes several minutes. The exact time depends on your specific camera model and how quickly it responds to movement commands. You'll see a live progress percentage on the calibration button as it runs.
Q: Can I use the camera while it's calibrating? No. Movement controls, position presets, and auto-tracking are all disabled while calibration is running. You can still view the video feed. Everything re-enables automatically when calibration finishes.
Q: What is a "generic driver"? If Iris cannot complete all calibration steps specific to your camera, it can fill in the missing data using a reference profile for the same camera model — this is the generic driver. It's less precise than a full custom calibration but still allows you to use smart features. You can retry full calibration at any time from Advanced Settings.
Q: Will calibration change my camera settings permanently? No. Iris temporarily adjusts certain camera settings (focus mode, zoom compensation, image flip) to run calibration, then automatically restores everything to the way it was when calibration finishes — including returning the camera to its original position.
Q: Why does calibration require me to set a brand and model? Iris uses your camera's model data to apply the right reference parameters during calibration. Without knowing the camera make/model, it cannot run an accurate calibration process.
Q: What if calibration fails? Do I have to start from the beginning? No. When you choose "Retry Calibration" after a failure, Iris picks up from the step that failed — it skips any steps that had already completed successfully.
Q: Is calibration required to use auto-tracking? Yes. Auto-tracking is only available on cameras that are fully calibrated (or using a generic driver). If your camera is not yet calibrated, the auto-tracking panel will show an option to start calibration.
Q: Can multiple cameras be calibrated at the same time? Each camera can only run one calibration session at a time, but different cameras can be calibrated independently and simultaneously (each in their own session).
Q: What triggers automatic calibration when I add a camera? When a new camera is added to a room, Iris checks its registry for an existing calibration profile. If none is found, calibration is automatically initiated. For cameras listed as "Other" make/model, the automatic check is skipped entirely — you'll need to set the brand/model first.