Navigation (Zoom, Pan, Fit)
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
Navigation within the Nextcloud CAD Viewer is a core functional module that enables users to interact with DWG and DXF drawings through WebGL-accelerated controls. The system provides three primary interaction modes: Zooming for magnification adjustment, Panning for lateral movement across the drawing area, and Fitting for automatic viewport optimization. These features are designed to work across desktop environments via mouse and keyboard, as well as mobile devices through touch gestures.
The navigation system is powered by the @mlightcad/cad-viewer library, which is integrated into the Nextcloud environment using a Vue 3 frontend. This implementation ensures that high-resolution CAD data can be navigated smoothly without the need for server-side rendering, as all viewport transformations occur directly in the client's browser.
Sources: README.md:9-11, appinfo/info.xml:9-12, wiki/User-Guide.md:73-77
Architecture and Components
The navigation features are implemented through a combination of the MlCadViewer component and utility managers that handle viewer settings. The cadLoader.ts utility serves as the bridge between the Nextcloud environment and the underlying CAD engine.
Interaction Flow
The following diagram illustrates how user input is processed to update the viewport within the CAD Viewer.
The navigation logic is handled by the MlCadViewer component, which is mounted to a container in the App.vue template.
Sources: src/App.vue:15, src/utils/cadLoader.ts:45-50, wiki/User-Guide.md:73-82
Key Classes and Data Structures
| Element | Description | Source |
|---|---|---|
ViewerInstance | Interface representing the active viewer session, including the mount container. | src/utils/cadLoader.ts:22-28 |
CADViewerOptions | Configuration object for initializing navigation settings like useMainThreadDraw. | src/utils/cadLoader.ts:8-16 |
AcApSettingManager | Manager used to configure UI behaviors and viewer settings programmatically. | src/utils/cadLoader.ts:71-73 |
MlCadViewer | The primary Vue component that encapsulates navigation controls and the WebGL canvas. | src/utils/cadLoader.ts:5-6 |
Zoom Operations
Zooming allows users to change the magnification level of the drawing. The CAD Viewer supports multiple zoom triggers to accommodate different hardware setups.
Zoom Control Mechanisms
- Toolbar Buttons: The interface includes + and - buttons for incremental magnification changes.
- Mouse Wheel: Scrolling up zooms in, while scrolling down zooms out.
- Keyboard Shortcuts: Users can use
+or=to zoom in, and-to zoom out. A reset to 100% is available via the0key. - Touch Gestures: On mobile devices, a "pinch out" gesture increases magnification, and a "pinch in" decreases it.
Sources: wiki/User-Guide.md:120-136, wiki/User-Guide.md:315-325
Pan Operations
Panning enables users to move the "camera" laterally across the CAD drawing without changing the zoom level.
Panning Methods
- Pan Tool: Activating the Pan button in the toolbar allows for left-click and drag movement.
- Middle Mouse Button: Holding the middle mouse button (scroll wheel click) allows for immediate panning regardless of the active tool.
- Spacebar Modifier: Holding the Spacebar while performing a left-click drag provides a temporary panning mode.
- Touch Interaction: One-finger dragging on touch-enabled devices pans the drawing area.
Sources: wiki/User-Guide.md:144-162, wiki/User-Guide.md:280-285
Fit to View
The Fit to View (or simply Fit) command is a utility function that automatically calculates the extents of all visible drawing elements and adjusts both the zoom level and the pan position so the entire drawing is visible within the viewport.
- Trigger: Click the Fit button in the toolbar or press the F key.
- Logic: The engine calculates the bounding box of the CAD data and scales it to the current canvas dimensions.
Sources: wiki/User-Guide.md:164-166, wiki/User-Guide.md:318
Technical Implementation Details
The navigation system is initialized through the loadCADViewer function. This function sets up the underlying WebGL context and attaches the necessary event listeners for navigation.
// Example of how the viewer is initialized with specific navigation-related props
// File: src/utils/cadLoader.ts (lines 35-42)
const viewerProps: Record<string, unknown> = {
locale,
theme,
background,
useMainThreadDraw, // Affects rendering performance during navigation
}
if (url !== undefined) viewerProps.url = url
Sources: src/utils/cadLoader.ts:35-42, src/App.vue:59-62
Performance Considerations for Navigation
Navigation performance is highly dependent on the client's GPU capabilities due to the WebGL-based rendering. Users experiencing "laggy" navigation are advised to enable hardware acceleration in their browser settings.
| Issue | Technical Solution | Source |
|---|---|---|
| Slow Zoom/Pan | Enable hardware acceleration in Browser (Settings -> System). | wiki/Troubleshooting.md:195-200 |
| Viewport Freeze | Close other browser tabs to free up GPU memory for WebGL. | wiki/Troubleshooting.md:223-225 |
| Mobile Navigation | Use landscape orientation for a wider panning viewport. | wiki/Troubleshooting.md:278-281 |
Summary
The Navigation system in Nextcloud CAD Viewer provides a robust set of controls for exploring complex DWG and DXF files. By utilizing the MLightCAD engine, the viewer supports professional-grade navigation features including multi-modal zooming, versatile panning options, and a "Fit to View" capability. This system ensures that users can effectively inspect CAD drawings within the Nextcloud interface across various devices and input methods.