Luxar Viewer API Documentation - v2026.9.22
    Preparing search index...

    Class InputHandler

    Central coordinator for all user input events and nD navigation.

    InputHandler

    Index
    constructor
    eventListeners _initialized renderingControls? scaleBar? colormapLegend? recordingPanel? layersPanel? uiActions? overlayManager? selectedDimension dimensionSliders? animationManager? sceneDimsListener? debugConsole contextManager panelCoordinator controlRail? windowEvents dimensionSlidersFactory? sceneManager animationController performanceMonitor
    setRenderingControls setScaleBar setColormapLegend setRecordingPanel setDatasetBrowser setOverlayManager setLayersPanel setControlRail init clearDimensionUI initDimensionSliders showDimensionSliders getAnimationManager makeDimNavSetupCtx setupWindowEvents setupControlEvents setupUserInteractionEvents handleDataMonitorCycle registerAllKeyBindings getUiActions onKeyDown onKeyUp toggleHelp getRegisteredShortcutBindings registerContext unregisterContext registerBinding unregisterBinding pushContext popContext getShortcutLabel setEnabled toggleDimensionSliders togglePerformanceStats toggleFullscreen toggleRenderingControls toggleCinematicMode exportViewerState makeViewerStateExportCtx toggleControlMode setControlMode toggleInertialMode makeControlModeCtx shouldHandleSpaceKey isTypingInInput handleDimensionNavigation selectDimension handleEscapeKey recenterCamera dispose
    eventListeners: (() => void)[] = []

    Cleanup functions for all registered event listeners

    Private_initialized

    _initialized: boolean = false
    renderingControls?: RenderingControlsHandle

    Optional reference to advanced rendering controls

    scaleBar?: ToggleableHandle

    Optional reference to scale bar overlay

    colormapLegend?: ToggleableHandle

    Optional reference to colormap legend overlay

    recordingPanel?: RecordingPanelHandle

    Optional reference to recording panel

    layersPanel?: LayersPanelHandle

    Optional reference to layers panel

    uiActions?: { commands: KeyBindingsCommands; panels: KeyBindingsPanelGetters }

    The command + panel surface shared with the keyboard bindings. Built in registerAllKeyBindings; exposed via getUiActions.

    overlayManager?: ToggleableHandle

    Optional reference to overlay manager

    selectedDimension: number = 0

    Index of currently selected dimension for keyboard navigation

    dimensionSliders?: DimensionSlidersHandle

    UI component for interactive dimension sliders

    animationManager?: DimensionAnimationManager

    Animation manager for dimension playback

    sceneDimsListener?: () => Promise<void>

    sceneDimsManager listener. Stored so dispose / clearDimensionUI can remove it — without this, app dispose (without a subsequent dataset switch) leaves the listener attached to the singleton and retains a disposed InputHandler.

    debugConsole: DebugConsoleHandle

    Debug console for capturing browser console output

    contextManager: InputContextManager

    Input context manager for handling keyboard conflicts

    panelCoordinator: PanelCoordinator

    Panel-coordination concern: owns the priority-ordered "close all panels" flow used by Escape. Constructed in the InputHandler ctor once debugConsole and animationController are available.

    controlRail?: ControlRailHandle
    windowEvents: WindowEventHandler

    Window-event concern: owns resize / wheel / fullscreenchange. Keyboard listeners stay in InputHandler — they're a separate concern coordinating with InputContextManager.

    dimensionSlidersFactory?: DimensionSlidersFactory

    Optional factory injected by core/app.ts to construct DimensionSliders lazily once a scene is loaded. When omitted (e.g. tests, embedders without nD navigation), initDimensionSliders() becomes a no-op rather than reaching into the ui layer directly.

    sceneManager: SceneManager
    animationController: AnimationController
    performanceMonitor: PerformanceMonitorHandle

    • Associate rendering controls for post-processing and visual effects.

      Enables keyboard shortcuts (R, C) to toggle rendering controls panel and cinematic mode. Should be called after rendering controls are created. Optional - rendering controls integration is not required for basic functionality.

      Parameters

      • controls: RenderingControlsHandle

        Rendering controls UI component providing access to bloom, HDR, noise, and other post-processing effects

      Returns void

      const renderingControls = new RenderingControls(sceneManager);
      inputHandler.setRenderingControls(renderingControls);

      // Now 'R' key toggles rendering controls panel
      // Now 'C' key toggles cinematic mode

    • Forward a dataset-browser close handle (or undefined to clear it) to PanelCoordinator so the Escape path closes via the panel's own close() method — which fires onClose and clears the owner's LuxarApp.datasetBrowser reference. The O shortcut needs that reference cleared in order to reopen the panel.

      Parameters

      • browser: { close(): void } | undefined

      Returns void

    • Adopt the control rail (or undefined to clear it on dispose, the contract the app's teardown relies on). Two duties: the handler keeps the rail so a keydown the router reports as handled can notify it (handleRoutedKeyDown — dismisses the first-run hint, refreshes active-state), and forwards it to PanelCoordinator so the Escape flow closes the rail's flyout/popover in the right priority order.

      Parameters

      Returns void

    • Initialize all event listeners for user interaction.

      Sets up the complete input handling system including:

      • Window events (resize, wheel, keyboard, fullscreen)
      • Control events (orbit/fly control integration)
      • User interaction events (mousedown, touchstart)
      • Context-specific key bindings

      Called once during application initialization, after scene manager is created but before scene loading. Re-entry is guarded: a second call logs a warning and returns without re-binding listeners (so HMR / context-restore / test re-setup can't silently double event volume). Event listeners are automatically cleaned up when dispose() is called.

      Returns void

      const app = new LuxarApp();
      const inputHandler = new InputHandler(sceneManager, animController);

      // Initialize input system
      inputHandler.init();

      // Input handlers are now active
      // User can press H for help, P for performance, etc.

    • Clear dimension UI and reset dimension manager to initial state.

      Disposes of dimension sliders and resets the scene dimension manager. Used when loading a new scene to ensure clean state. The dimension manager is reset to allow it to be reinitialized with new scene metadata.

      This is called automatically before loading a new scene. You typically don't need to call this manually unless implementing custom scene switching logic.

      Returns void

      // Before loading new scene
      inputHandler.clearDimensionUI();
      await sceneManager.loadSceneData(newUrl);
      inputHandler.initDimensionSliders();

    • Initialize dimension navigation UI after scene loading completes.

      This method must be called after the scene is fully loaded and dimension metadata is available. It sets up:

      • Scene dimension manager integration with scene metadata
      • Interactive dimension sliders UI for non-displayed dimensions
      • Reactive update system for all nD objects (points, lines, splats)
      • Keyboard navigation targets ([/] keys and number keys 1-9)

      The initialization process ensures all nD objects share the same dimensional coordinate system and respond consistently to navigation. If no nD objects are found in the scene, initialization is skipped gracefully (3D-only scene).

      Returns void

      // After scene loads
      await sceneManager.loadSceneData(url);

      // Initialize dimension navigation
      inputHandler.initDimensionSliders();

      // Now users can:
      // - Press 1-9 to select a non-displayed dimension
      // - Press [ ] to navigate selected dimension
      // - Use sliders to navigate visually

      // Check if dimension sliders were created
      inputHandler.initDimensionSliders();

      const dims = sceneDimsManager.getDims();
      if (!dims) {
        console.log('No nD objects in scene (3D only)');
      } else {
        console.log(`Navigating ${dims.ndim}D dataset`);
      }

    • Show the dimension sliders panel (if it exists). Called from viewer_config application.

      Returns void

    • Private

      Set up window-level event listeners for global input handling.

      Registers listeners for:

      • Window resize: Updates canvas size and camera aspect ratio
      • Mouse wheel: Zoom and FOV control (Ctrl+wheel for FOV, Shift+wheel for roll)
      • Keyboard: All keyboard shortcuts and navigation
      • Fullscreen changes: Adjusts canvas styling for fullscreen mode

      All listeners are bound to class instance and stored for cleanup. Called once during init().

      Returns void

    • Private

      Set up event listeners for THREE.js orbit controls.

      Registers listeners on the controls object to trigger animation when user interacts with camera controls (orbit, pan, zoom). Ensures smooth rendering during camera manipulation.

      Returns void

    • Private

      Set up user interaction event listeners for canvas.

      Registers listeners for mousedown and touchstart on the canvas to trigger animation when user begins interaction. Provides visual feedback that system is responding to input.

      Returns void

    • Private

      Handle cycling the data loading monitor (hidden → mini → expanded → hidden).

      Extracted to a method to support binding registration.

      Returns void

    • Private

      Register all key bindings with the context manager.

      This method registers all keyboard shortcuts using the binding registration system. Bindings are organized by input context:

      • NAVIGATION: Default orbit mode shortcuts
      • FLY_CONTROLS: WASD movement keys for fly mode
      • Explicit fallback contexts: shared shortcuts remain reachable where intended

      Called during init() to set up the complete keyboard interface.

      Returns void

    • Handle key down events.

      Routes ALL keyboard events through the context manager's binding system. No special cases - everything uses the unified binding system.

      Parameters

      • event: KeyboardEvent

      Returns void

    • Handle key up events.

      Routes through context manager for keys that have keyupHandler registered. Keys without keyupHandler (most toggle actions) are ignored on keyup.

      Parameters

      • event: KeyboardEvent

      Returns void

    • Private

      Toggle help overlay visibility on/off.

      Shows or hides the keyboard shortcuts help overlay. Triggered by H key. The help overlay displays all available keyboard shortcuts organized by category (navigation, view controls, panels, etc.).

      Returns void

    • Remove a binding from a built-in or custom context.

      Parameters

      • context: InputContextId
      • key: string
      • Optionalmodifiers: { ctrl?: boolean; shift?: boolean; alt?: boolean; meta?: boolean }

      Returns void

    • Resolve the active binding label for a registered action.

      Parameters

      • actionId: string

      Returns string | undefined

    • Enable or disable all routed keyboard input.

      Parameters

      • enabled: boolean

      Returns void

    • Private

      Toggle dimension sliders panel visibility.

      Shows or hides the nD dimension navigation sliders. Triggered by N key. Only functional if dimension sliders have been initialized (nD dataset loaded). Has no effect for 3D-only datasets.

      Returns void

    • Private

      Toggle performance statistics (FPS, memory) display.

      Shows or hides the stats.js performance monitor in top-left corner. Triggered by P key. Displays:

      • FPS (frames per second)
      • Frame time in milliseconds
      • Memory usage (if available)

      Returns void

    • Private

      Toggle fullscreen mode on/off.

      Requests fullscreen for the document element (true fullscreen including browser chrome). Triggered by Space key (when not focused on UI element) and the View-options fullscreen chip.

      Fullscreen exit is also possible via browser's native ESC key handling.

      Returns void

    • Private

      Toggle advanced rendering controls panel visibility.

      Shows or hides the rendering controls UI providing access to:

      • Post-processing effects (bloom, HDR, vignette, chromatic aberration)
      • Camera settings (FOV presets)
      • Control mode selection (orbit, fly, ortho)
      • Point rendering parameters

      Triggered by R key. Only functional if rendering controls have been associated via setRenderingControls().

      Returns void

    • Private

      Toggle cinematic mode (film-like visual effects).

      Enables or disables a preset combination of effects:

      • Film grain noise
      • Vignette (darkened corners)
      • Chromatic aberration (color fringing)
      • Lens distortion

      Triggered by C key. Provides quick access to cinematic aesthetics without manually adjusting individual effects. Only functional if rendering controls have been associated.

      Returns void

    • Private

      Export the complete viewer state as JSON to the clipboard.

      Triggered by Ctrl+Shift+S. Captures all rendering settings, camera state, dimensions, theme, etc. and copies the JSON to the clipboard. The JSON can be loaded in Python with luxar.ViewerConfig.from_json().

      Returns void

    • Private

      Cycle through camera control modes: Orbit → Fly → Ortho → Orbit.

      Triggered by V key. Control modes provide different camera interaction styles:

      • Orbit: Quaternion-based rotation with no gimbal lock (drag to rotate around target)
      • Fly: First-person WASD movement (for exploring inside datasets)
      • Ortho: Orthographic pan + zoom (for 2D viewing)

      Updates input context when switching to fly mode to enable WASD keys. Syncs rendering controls display if active.

      Returns void

    • Private

      Switch directly to a specific camera control mode (orbit / fly / ortho). Triggered by the control rail's Navigation popover mode selector; reuses the same context/sync wiring as the V-key cycle.

      Parameters

      Returns void

    • Private

      Toggle inertial mode for fly controls (momentum-based movement).

      Triggered by I key. Only functional when in fly control mode.

      Inertial mode adds physics-based momentum:

      • ON: Movement continues after releasing keys (space-like float)
      • OFF: Movement stops immediately when keys released (FPS-like control)

      Syncs rendering controls display if active. Logs info message if called while not in fly mode.

      Returns void

    • Private

      Check if Space key should trigger fullscreen toggle.

      Returns true only if focus is on document body or canvas, preventing fullscreen toggle when user is interacting with UI elements (buttons, inputs, etc.) where Space might have other meanings (submit, type space).

      Returns boolean

      true if Space key should toggle fullscreen, false otherwise

    • Private

      Check if user is currently typing in a text input field. Thin wrapper around the pure isTypingInInput helper so callers in this file keep their compact this.isTypingInInput() shape.

      Returns boolean

    • Private

      Handles keyboard navigation through nD dimensions using [ and ] keys.

      This implements intelligent dimension navigation with adaptive step sizes:

      • The animation menu's per-dimension Step override wins when set (quantized to the authored grid for discrete dims)
      • Otherwise discrete dimensions step by their defined increment
      • Otherwise continuous dimensions step by 1% of their total range
      • Steps are clamped to dimension bounds
      • Only updates if the value actually changes

      The navigation respects the currently selected dimension (set by number keys) and provides smooth, predictable movement through nD space.

      Parameters

      • direction: -1 | 1

        Direction to navigate: -1 for backward, 1 for forward

      Returns void

    • Private

      Selects which dimension to control with keyboard navigation.

      Number keys (1-9) map to navigable dimensions, allowing users to switch between controlling different non-displayed dimensions with the [ and ] navigation keys.

      Parameters

      • index: number

        Zero-based position in the non-displayed dimension list

      Returns void

    • Escape-key dispatch. Delegates to PanelCoordinator which owns the recording-priority and fullscreen-defer rules.

      Returns void

    • Private

      Frame camera to fit the entire scene.

      Triggered by F key. Computes bounding box of all visible geometry and repositions camera at the optimal distance to see everything. Works for both perspective (distance) and orthographic (zoom) cameras.

      Returns void

    • Clean up all event listeners and dispose of managed resources.

      Removes all registered event listeners from window, document, and canvas to prevent memory leaks. Disposes of dimension sliders and debug console. Should be called when the input handler is no longer needed (e.g., when destroying the application).

      After calling dispose(), the input handler cannot be reused - create a new instance if needed.

      Returns void

      // During application teardown
      inputHandler.dispose();
      sceneManager.dispose();
      animationController.dispose();

    Settings
    Member Visibility

    On This Page
    Constructors
    Properties
    Methods
    setRenderingControlssetScaleBarsetColormapLegendsetRecordingPanelsetDatasetBrowsersetOverlayManagersetLayersPanelsetControlRailinitclearDimensionUIinitDimensionSlidersshowDimensionSlidersgetAnimationManagermakeDimNavSetupCtxsetupWindowEventssetupControlEventssetupUserInteractionEventshandleDataMonitorCycleregisterAllKeyBindingsgetUiActionsonKeyDownonKeyUptoggleHelpgetRegisteredShortcutBindingsregisterContextunregisterContextregisterBindingunregisterBindingpushContextpopContextgetShortcutLabelsetEnabledtoggleDimensionSliderstogglePerformanceStatstoggleFullscreentoggleRenderingControlstoggleCinematicModeexportViewerStatemakeViewerStateExportCtxtoggleControlModesetControlModetoggleInertialModemakeControlModeCtxshouldHandleSpaceKeyisTypingInInputhandleDimensionNavigationselectDimensionhandleEscapeKeyrecenterCameradispose