Preventing Objects From Moving Off-Screen While Panning

🌵 Needle Engine
1

I want to restrict panning so that the object doesn’t move off the screen. Any tips on how to implement this?

2

Hi Ashok, you can solve this by clamping the object’s screen position during panning. One common approach is to project the object’s world position into normalized device coordinates (NDC), enforce boundaries in those coordinates, and then unproject back to world space. This way, you can make sure the object never goes off-screen.

For example, you could create a Needle Engine component like this:

import { Behaviour, serializable } from "@needle-tools/engine";
import { Object3D, Vector3 } from "three";

export class ClampPan extends Behaviour {
  // Reference the object to be panned – assign this in the editor.
  @serializable(Object3D)
  target?: Object3D;

  // Define a margin to keep the object a bit inside the edges.
  @serializable()
  margin: number = 0.1;

  update() {
    if (!this.target) return;
    const camera = this.context.mainCamera;
    if (!camera) return;

    // Retrieve the object's current world position
    const worldPos = new Vector3();
    this.target.getWorldPosition(worldPos);

    // Project the world position to normalized device coordinates (NDC), where x and y are in [-1, 1]
    const ndcPos = worldPos.clone().project(camera);

    // Compute clamped values within the defined margin
    let clamped = false;
    if (ndcPos.x < -1 + this.margin) { ndcPos.x = -1 + this.margin; clamped = true; }
    if (ndcPos.x >  1 - this.margin) { ndcPos.x =  1 - this.margin; clamped = true; }
    if (ndcPos.y < -1 + this.margin) { ndcPos.y = -1 + this.margin; clamped = true; }
    if (ndcPos.y >  1 - this.margin) { ndcPos.y =  1 - this.margin; clamped = true; }

    // If clamping occurred, convert back to world coordinates and update the object's position
    if (clamped) {
      ndcPos.unproject(camera);
      this.target.position.copy(ndcPos);
    }
  }
}

This component calculates the screen position of your target object and, if it’s about to move beyond the visible region (while panning), it clamps those coordinates to a safe range. You can adjust the margin based on how far inside you want the object to remain.

If you’re using OrbitControls or another panning control, you might consider clamping the camera’s target position in a similar way to restrict pan movements. Also, if your object has significant dimensions, you may need to factor in its bounding box to ensure it stays fully visible.

This approach aligns with typical three.js ideas, and since Needle Engine works on top of three.js, it fits right in. For further details on similar techniques, you can also check out the Needle Engine docs at Needle Engine Documentation.

Hope that helps! Let me know if you need any further tweaks.

4 replies left
thread_eUe8juCAAic1zXnufA1nPOpE
Reply to this post directly if you need further help (bottom right button)

3

Hi, below is a simple solution. Does that fix your issue?

import {
  Behaviour,
  getTempVector,
  Gizmos,
  OrbitControls,
  serializable,
} from '@needle-tools/engine';
import { Vector3 } from 'three';

export class LimitPan extends Behaviour {
  @serializable(Vector3)
  size: Vector3 = new Vector3(1, 1, 1);

  @serializable()
  duration: number = 0.1;

  @serializable(OrbitControls)
  orbit: OrbitControls | null = null;

  @serializable()
  debug: boolean = false;

  onBeforeRender(): void {
    const orbit =
      this.orbit || this.context.mainCamera.getComponent(OrbitControls);
    if (orbit) {
      const target = orbit.controls?.target;
      if (target) {
        const pos = this.gameObject.worldPosition;
        const halfSize = getTempVector(this.size).multiplyScalar(0.5);
        const min = getTempVector(pos).sub(halfSize);
        const max = getTempVector(pos).add(halfSize);
        const newTarget = getTempVector(target).clamp(min, max);
        if (this.duration <= 0) {
          target.copy(newTarget);
        } else {
          target.lerp(newTarget, this.context.time.deltaTime / this.duration);
        }
      }
    }
    if (this.debug) {
      Gizmos.DrawWireBox(this.gameObject.worldPosition, this.size, 0xff0000);
    }
  }
}
1 Like
4

Yes, Thanks a lot. It worked.

5

This topic was automatically closed 13 days after the last reply. New replies are no longer allowed.