📷 Camera Locks & Limits

Every product's 3D configurator ships with camera behaviour that was set up alongside the product: whether shoppers can zoom, pan, and rotate, and within what limits. Sometimes your page wants something different — a hero embed that shouldn't hijack scroll-wheel zoom, a "spin only" showroom view, or a completely static presentation.

Camera locks & limits let you override that behaviour at embed time, per page, without touching the product's camera data. Anything you don't override keeps working exactly as the product was set up.

There are two ways to apply an override:

• URL parameters on the configurator URL — set once, applies from load.
• A postMessage from your page — change or clear the override at any time.

Quick start

Add locks to the configurator URL:

https://configurator.orbital.vision/{apiKey}/{productId}?cameraLocks=zoom,vertical&maxDistance=4

That disables zooming, freezes the vertical tilt at the product's default camera angle, and stops the camera moving further than 4 units away — while horizontal spin keeps working as normal.

Using the ov25-ui package? productLink accepts a query string, and it's merged into the iframe URL for you:

injectConfigurator({
  apiKey: () => 'your-api-key',
  productLink: () => '92?cameraLocks=zoom,vertical&maxDistance=4',
  // ...the rest of your config
});

Testing tip: the iframe also inherits query parameters from the page it's embedded on, so you can try locks out by appending ?cameraLocks=zoom to your own product page's URL — no code changes needed.

Locks

Locks are the simple switches. Pass them as a comma-separated list in cameraLocks:

?cameraLocks=zoom,pan,vertical

Each token also works as an individual parameter if you prefer: ?lockZoom=1&lockVertical=1 is equivalent to ?cameraLocks=zoom,vertical.

A note on axes: the 3D camera orbits with two degrees of freedom — horizontal (spinning around the product) and vertical (tilting up and down). There is no "roll", so those two locks plus zoom and pan cover everything the shopper can do.

Limits

For finer control than an outright lock, set the underlying camera constraints directly. These take numbers and map 1:1 onto three.js OrbitControls properties — angles are in radians.

Degrees → radians: multiply by π/180. Handy values: 30° ≈ 0.524, 45° ≈ 0.785, 60° ≈ 1.047, 90° ≈ 1.571.

Example — keep the camera between 1.5 and 4 units away and stop shoppers tilting below eye level:

?minDistance=1.5&maxDistance=4&maxPolarAngle=1.571

Changing it at runtime

To apply, change, or remove an override after load, post a SET_CAMERA_CONTROLS_OVERRIDE message to the configurator iframe. The payload is a JSON string containing any mix of the lock flags and limit values above:

const iframe = document.getElementById('ov25-configurator-iframe'); // however you hold a reference
 
iframe.contentWindow.postMessage({
  type: 'SET_CAMERA_CONTROLS_OVERRIDE',
  payload: JSON.stringify({ lockRotate: true, maxDistance: 4 }),
}, '*');

Three things to know:

• Each message replaces the previous override entirely — it doesn't merge with it. Send the full set of locks/limits you want each time.

• Clear back to the product's own camera behaviour by sending null:

  iframe.contentWindow.postMessage({
    type: 'SET_CAMERA_CONTROLS_OVERRIDE',
    payload: JSON.stringify(null),
  }, '*');

• The iframe confirms with a message of the same type and payload {"success": true}. A malformed payload gets an ERROR message back, and unknown or wrongly-typed keys are silently dropped.

Recipes

Behaviour notes

• The override sticks for the life of the page: it survives option changes, model swaps, and camera switches. A full page reload clears a postMessage override (URL parameters re-apply themselves, of course).
• horizontal / vertical freeze the camera at the angle it's at when the override lands — via URL that's the product's default camera angle.
• Anything you don't override still comes from the product's camera setup, including its own zoom limits if it has them.
• Applies to the standard product configurator (single- and multi-product). The bed, dining, and Snap2 modular configurators have their own embeds and don't support this yet.
• AR is unaffected — these locks only govern the in-page 3D viewer.