Space Navigation Camera

Control camera movement and positioning for navigating virtual spaces and creating immersive user experiences. These camera functions are optimized for first-person navigation, virtual tours, and spatial exploration.

🎯 Essential Camera Control

getCameraPosition

getCameraPosition(callback: Function)

Gets the current camera position - the most fundamental camera information for navigation and positioning.

api.getCameraPosition(function(position){
  console.log('Camera at:', position); // Result: [x, y, z]
  updateNavigationUI(position);
});

---

setCameraPosition

setCameraPosition(position: [x: number, y: number, z: number], [duration: number], [callback: Function])

Sets the camera position with smooth animation. Essential for guided tours and navigation.

// Quick navigation to specific location
api.setCameraPosition([5, 2, 5], 1.5, function(camera){
  console.log('Moved to new viewpoint');
});

// Smooth guided tour transition
api.setCameraPosition([10, 5, 0], 3.0, function(){
  showLocationInfo('Gallery Entrance');
});

---

getCameraRotation

getCameraRotation(callback: Function)

Gets the camera rotation (in radians) - essential for understanding viewing direction.

api.getCameraRotation(function(rotation){
  console.log('Looking direction:', rotation); // Result: [x, y, z]
  updateCompass(rotation);
});

---

setCameraRotation

setCameraRotation(rotation: [x: number, y: number, z: number], [duration: number], [callback: Function])

Sets the camera rotation with smooth animation. Perfect for directing user attention.

// Point camera toward specific object
api.setCameraRotation([0, Math.PI/2, 0], 2.0, function(){
  console.log('Now looking east');
  highlightPointOfInterest();
});

🎬 Advanced Camera Control

getCameraOrientation

getCameraOrientation(callback: Function)

Gets both camera position and rotation in one call - efficient for saving/restoring camera states.

api.getCameraOrientation(function(camera){
  console.log('Position:', camera.position); // [x, y, z]
  console.log('Rotation:', camera.rotation); // [x, y, z]

  // Save camera state for later restoration
  saveCameraBookmark(camera);
});

---

setCameraOrientation

setCameraOrientation(position: [x: number, y: number, z: number], rotation: [x: number, y: number, z: number], [duration: number], [callback: Function])

Sets both camera position and rotation simultaneously - perfect for scene transitions and bookmarks.

// Restore saved camera bookmark
api.setCameraOrientation([0, 10, 0], [0, Math.PI, 0], 2.5, function(){
  console.log('Camera bookmark restored');
  showBookmarkName('Main Entrance');
});

🎯 Camera Targeting

getCameraTarget

getCameraTarget(callback: Function)

Gets the point the camera is looking at - useful for focus-based interactions.

api.getCameraTarget(function(target){
  console.log('Looking at:', target); // [x, y, z]
  highlightTargetObject(target);
});

---

setCameraTarget

setCameraTarget(target: [x: number, y: number, z: number], [duration: number], [callback: Function])

Points the camera at a specific location - essential for guided attention and object focus.

// Focus on specific object
api.setCameraTarget([5, 2, -3], 1.5, function(){
  console.log('Now focusing on artwork');
  showObjectDetails('Mona Lisa Replica');
});

🔍 Camera Types & Zoom

switchCameraType

switchCameraType(type: 'walk' | 'birdseye' | 'vr' | 'cardboard' | 'anaglyph' | 'topdown' | 'virtual-joysticks' | 'device-orientation', [callback: Function])

Changes the camera control mode for different interaction styles.

// Switch to overview mode
api.switchCameraType('birdseye', function(){
  console.log('Switched to overview mode');
  showNavigationControls();
});

// Switch to VR mode
api.switchCameraType('vr', function(){
  console.log('VR mode activated');
});

---

getCameraZoom

getCameraZoom(callback: Function)

Gets the current zoom level (birdseye camera radius).

api.getCameraZoom(function(radius){
  console.log('Zoom level:', radius);
  updateZoomSlider(radius);
});

---

setCameraZoom

setCameraZoom(radius: number, [duration=0], [callback: Function])

Sets the zoom level for birdseye camera mode.

// Zoom in for detail view
api.setCameraZoom(15, 2, function(){
  console.log('Zoomed in for detail view');
});

// Zoom out for overview
api.setCameraZoom(50, 2, function(){
  console.log('Zoomed out for overview');
});

👁️ Field of View

getFov

getFov(callback: Function)

Gets the current field of view in degrees - affects how much of the scene is visible.

api.getFov(function(fov){
  console.log('Current FOV:', fov, 'degrees');
  updateFovSlider(fov);
});

---

setFov

setFov(angle: number, [callback: Function])

Sets the field of view (1-179 degrees) - wider angles show more, narrower angles zoom in.

// Wide angle for architectural overview
api.setFov(90, function(){
  console.log('Wide angle view enabled');
});

// Narrow angle for focused detail
api.setFov(45, function(){
  console.log('Focused detail view');
});

📋 Best Practices

Navigation Patterns:

• Use setCameraPosition() for location changes
• Use setCameraTarget() to direct attention
• Combine both with setCameraOrientation() for complete scene transitions

User Experience:

• Provide smooth transitions with appropriate duration values
• Save/restore camera states for bookmarks and undo functionality
• Match camera type to interaction context (walk for exploration, birdseye for overview)

Performance:

• Cache camera positions for frequently visited locations
• Use shorter durations for responsive interactions
• Consider user motion sensitivity when setting transition speeds