📷 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=vertical&zoomOutDistance=1

That freezes the vertical tilt at the product's default camera angle and stops the camera zooming out past double its starting distance — while horizontal spin and zooming in keep 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=vertical&zoomOutDistance=1',
  // ...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. Angle limits map 1:1 onto three.js OrbitControls properties — angles are in radians.

How the zoom allowances work

When a product loads, the configurator automatically frames it — the camera is positioned so the whole product fits comfortably in view. zoomInDistance and zoomOutDistance say how far shoppers may travel from that framed starting view, one per direction:

• zoomInDistance — zoom in allowance. 0 = can't zoom in at all; each step up allows more: 1 lets the camera get twice as close (the product appears 2× larger), 10 lets it get 11× closer.
• zoomOutDistance — zoom out allowance, same scale. 1 = up to double the starting distance, 10 = up to 11×.
• zoomInDistance=0&zoomOutDistance=0 locks the zoom at the framed view entirely.

The two are independent — set just one and the other direction keeps the product's normal behaviour. And because they're relative to the framed view, the same values work for a footstool and a corner sofa: you never need to know the product's real-world size.

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

Example — allow a bit of zoom either way, and stop shoppers tilting below eye level:

?zoomInDistance=1&zoomOutDistance=1&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, zoomOutDistance: 1 }),
}, '*');

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.
• The zoom allowances' baseline is the framed starting distance, so if the model being viewed changes size (for example a modular build growing as pieces are added), the configurator reframes and your allowances automatically rescale with it.
• Negative zoomInDistance / zoomOutDistance values are ignored (0 is valid — it means no zoom in that direction).
• 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.