Camera Movement

/**
 * Rotate camera by specified angles relative to current position
 * @param azimuthAngle - Horizontal rotation in radians
 * @param polarAngle - Vertical rotation in radians  
 * @param enableTransition - Whether to animate the transition
 * @returns Promise that resolves when rotation completes
 */
rotate(azimuthAngle: number, polarAngle: number, enableTransition?: boolean): Promise<void>;

/**
 * Rotate camera to specific azimuth angle
 * @param azimuthAngle - Target horizontal angle in radians
 * @param enableTransition - Whether to animate the transition
 * @returns Promise that resolves when rotation completes
 */
rotateAzimuthTo(azimuthAngle: number, enableTransition?: boolean): Promise<void>;

/**
 * Rotate camera to specific polar angle
 * @param polarAngle - Target vertical angle in radians
 * @param enableTransition - Whether to animate the transition
 * @returns Promise that resolves when rotation completes
 */
rotatePolarTo(polarAngle: number, enableTransition?: boolean): Promise<void>;

/**
 * Rotate camera to specific azimuth and polar angles
 * @param azimuthAngle - Target horizontal angle in radians
 * @param polarAngle - Target vertical angle in radians
 * @param enableTransition - Whether to animate the transition
 * @returns Promise that resolves when rotation completes
 */
rotateTo(azimuthAngle: number, polarAngle: number, enableTransition?: boolean): Promise<void>;

// Rotate by 45 degrees horizontally with smooth transition
await cameraControls.rotate(Math.PI / 4, 0, true);

// Rotate to specific angle instantly
await cameraControls.rotateTo(Math.PI / 2, Math.PI / 3, false);

// Rotate to look straight down with transition
await cameraControls.rotatePolarTo(Math.PI, true);

/**
 * Move camera closer or farther by specified distance
 * @param distance - Distance to move (positive = closer, negative = farther)
 * @param enableTransition - Whether to animate the transition
 * @returns Promise that resolves when movement completes
 */
dolly(distance: number, enableTransition?: boolean): Promise<void>;

/**
 * Set camera distance to specific value
 * @param distance - Target distance from target point
 * @param enableTransition - Whether to animate the transition
 * @returns Promise that resolves when movement completes
 */
dollyTo(distance: number, enableTransition?: boolean): Promise<void>;

/**
 * Dolly in by fixed amount (always moves closer)
 * @param distance - Distance to move closer
 * @param enableTransition - Whether to animate the transition
 * @returns Promise that resolves when movement completes
 */
dollyInFixed(distance: number, enableTransition?: boolean): Promise<void>;

/**
 * Zoom camera by specified amount (changes FOV, not position)
 * @param zoomStep - Zoom multiplier (>1 = zoom in, <1 = zoom out)
 * @param enableTransition - Whether to animate the transition
 * @returns Promise that resolves when zoom completes
 */
zoom(zoomStep: number, enableTransition?: boolean): Promise<void>;

/**
 * Set camera zoom to specific level
 * @param zoom - Target zoom level
 * @param enableTransition - Whether to animate the transition
 * @returns Promise that resolves when zoom completes
 */
zoomTo(zoom: number, enableTransition?: boolean): Promise<void>;

// Move camera 5 units closer with smooth transition
await cameraControls.dolly(-5, true);

// Set specific distance from target
await cameraControls.dollyTo(10, true);

// Zoom in by 2x instantly
await cameraControls.zoom(2, false);

// Set specific zoom level with transition
await cameraControls.zoomTo(1.5, true);

/**
 * Pan camera in screen space coordinates
 * @param x - Horizontal screen space movement
 * @param y - Vertical screen space movement
 * @param enableTransition - Whether to animate the transition
 * @returns Promise that resolves when movement completes
 */
pan(x: number, y: number, enableTransition?: boolean): Promise<void>;

/**
 * Move camera left/right and up/down (truck and pedestal)
 * @param x - Horizontal movement (left/right)
 * @param y - Vertical movement (up/down)
 * @param enableTransition - Whether to animate the transition
 * @returns Promise that resolves when movement completes
 */
truck(x: number, y: number, enableTransition?: boolean): Promise<void>;

/**
 * Move camera forward or backward along view direction
 * @param distance - Distance to move (positive = forward, negative = backward)
 * @param enableTransition - Whether to animate the transition
 * @returns Promise that resolves when movement completes
 */
forward(distance: number, enableTransition?: boolean): Promise<void>;

/**
 * Move camera up or down in world space
 * @param height - Height to move (positive = up, negative = down)
 * @param enableTransition - Whether to animate the transition
 * @returns Promise that resolves when movement completes
 */
elevate(height: number, enableTransition?: boolean): Promise<void>;

// Pan camera in screen space
await cameraControls.pan(100, -50, true);

// Move camera left and up
await cameraControls.truck(-2, 1, true);

// Move forward 3 units instantly
await cameraControls.forward(3, false);

// Elevate camera 5 units with transition
await cameraControls.elevate(5, true);

/**
 * Move camera to specific world position
 * @param x - World X coordinate
 * @param y - World Y coordinate
 * @param z - World Z coordinate
 * @param enableTransition - Whether to animate the transition
 * @returns Promise that resolves when movement completes
 */
moveTo(x: number, y: number, z: number, enableTransition?: boolean): Promise<void>;

/**
 * Set camera position to specific coordinates
 * @param positionX - World X coordinate
 * @param positionY - World Y coordinate
 * @param positionZ - World Z coordinate
 * @param enableTransition - Whether to animate the transition
 * @returns Promise that resolves when movement completes
 */
setPosition(positionX: number, positionY: number, positionZ: number, enableTransition?: boolean): Promise<void>;

/**
 * Set camera target (look-at point) to specific coordinates
 * @param targetX - World X coordinate
 * @param targetY - World Y coordinate
 * @param targetZ - World Z coordinate
 * @param enableTransition - Whether to animate the transition
 * @returns Promise that resolves when movement completes
 */
setTarget(targetX: number, targetY: number, targetZ: number, enableTransition?: boolean): Promise<void>;

/**
 * Set focal offset for off-center camera controls
 * @param x - X offset from target
 * @param y - Y offset from target
 * @param z - Z offset from target
 * @param enableTransition - Whether to animate the transition
 * @returns Promise that resolves when movement completes
 */
setFocalOffset(x: number, y: number, z: number, enableTransition?: boolean): Promise<void>;

// Move camera to specific world position
await cameraControls.moveTo(10, 5, 15, true);

// Set camera position instantly
await cameraControls.setPosition(0, 10, 20, false);

// Set target point with smooth transition
await cameraControls.setTarget(5, 0, -5, true);

// Apply focal offset for off-center framing
await cameraControls.setFocalOffset(2, 1, 0, true);

/**
 * Orient camera to look in specific direction
 * @param x - Direction X component
 * @param y - Direction Y component  
 * @param z - Direction Z component
 * @param enableTransition - Whether to animate the transition
 * @returns Promise that resolves when orientation completes
 */
lookInDirectionOf(x: number, y: number, z: number, enableTransition?: boolean): Promise<void>;

// Look toward positive X axis with transition
await cameraControls.lookInDirectionOf(1, 0, 0, true);

/**
 * Normalize rotation angles to prevent accumulation issues
 * Useful after many rotations to prevent floating-point drift
 * @returns This CameraControls instance for chaining
 */
normalizeRotations(): CameraControls;

/**
 * Update camera up vector based on current state
 * Must be called when camera up vector is changed
 */
updateCameraUp(): void;

/**
 * Apply stored up vector to camera
 * Used for non-standard coordinate systems
 */
applyCameraUp(): void;

// Normalize after many rotations
cameraControls.normalizeRotations();

// Chain with other operations
cameraControls.normalizeRotations().saveState();

// For Z-up coordinate systems (common in CAD/3D modeling)
camera.up.set(0, 0, 1); // Set Z-up before creating controls
cameraControls.updateCameraUp();

// After changing camera up vector during runtime
camera.up.set(0, 1, 0); // Back to Y-up
cameraControls.applyCameraUp();

// Custom up vector for tilted scenes
camera.up.set(0.5, 0.866, 0); // 30-degree tilt
cameraControls.updateCameraUp();

// Rotation constraints (in radians)
minPolarAngle: number; // default: 0
maxPolarAngle: number; // default: Math.PI  
minAzimuthAngle: number; // default: -Infinity
maxAzimuthAngle: number; // default: Infinity

// Distance constraints (PerspectiveCamera only)
minDistance: number; // default: Number.EPSILON
maxDistance: number; // default: Infinity

// Zoom constraints
minZoom: number; // default: 0.01
maxZoom: number; // default: Infinity

// Speed settings
azimuthRotateSpeed: number; // default: 1.0
polarRotateSpeed: number; // default: 1.0
dollySpeed: number; // default: 1.0
truckSpeed: number; // default: 2.0

// Behavior settings
dollyToCursor: boolean; // default: false
dollyDragInverted: boolean; // default: false
infinityDolly: boolean; // default: false

// Current values (read-only)
distance: number; // Current distance from target
azimuthAngle: number; // Current horizontal angle in radians
polarAngle: number; // Current vertical angle in radians

// Check current camera state
console.log(`Distance: ${cameraControls.distance}`);
console.log(`Azimuth: ${cameraControls.azimuthAngle * THREE.MathUtils.RAD2DEG}°`);
console.log(`Polar: ${cameraControls.polarAngle * THREE.MathUtils.RAD2DEG}°`);

// Set rotation limits (prevent full 360° rotation)
cameraControls.minAzimuthAngle = -Math.PI;
cameraControls.maxAzimuthAngle = Math.PI;

// Set distance limits
cameraControls.minDistance = 1;
cameraControls.maxDistance = 100;

// Enable dolly to cursor for zoom-to-point functionality
cameraControls.dollyToCursor = true;