LilGui Settings Panel
Relevant source files
The following files were used as context for generating this wiki page:
The LilGui Settings Panel is a specialized user interface component within HoloPrint designed to provide real-time control over 3D hologram previews. It acts as a wrapper for the lil-gui library, encapsulating its functionality within a custom HTML element to allow for modularity and style isolation within the application's preview system.
This panel specifically enables users to tweak visual parameters such as lighting, shadows, and resolution directly while viewing the structure preview. It is integrated into the PreviewRenderer to ensure that adjustments to settings immediately flag the rendering engine for a redraw.
Sources: src/components/LilGui.js, src/PreviewRenderer.js:107-118
Component Architecture
The LilGui component is implemented as a custom Web Component extending HTMLElement. It utilizes a Shadow DOM to isolate the GUI's layout and styles from the rest of the application, ensuring that the lil-gui default styles do not bleed into the main HoloPrint interface.
Style Encapsulation
The component manages its own styles through a static private property #lilGuiStylesheet. Upon the first connection of a LilGui element, it scans the document head for the lil-gui stylesheet, moves it into the component's internal storage, and clones it into the Shadow Root. This process ensures that the GUI remains styled even when nested inside isolated DOM environments.
Sources: src/components/LilGui.js:4-31
Lifecycle Management
The component follows standard Web Component lifecycle methods:
- connectedCallback: Initializes the
GUIinstance and attaches it to the shadow root. It also applies internal CSS to set the panel width and font family ("Space Grotesk"). - disconnectedCallback: Calls
this.gui.destroy()to clean up memory and event listeners when the preview is removed.
Sources: src/components/LilGui.js:18-50
The diagram above shows the relationship between the standard HTML element interface, the custom LilGui wrapper, and the internal GUI library. Sources: src/components/LilGui.js
Preview Integration
The settings panel is instantiated within the PreviewRenderer class when the showOptions flag is enabled. The renderer creates a <lil-gui> element and appends it to the preview container.
Data Flow and Re-rendering
When a user modifies a value within the GUI, an onChange callback is triggered. This callback sets the #shouldRenderNextFrame flag to true, which the PreviewRenderer's animation loop checks during its next cycle to perform a render update.
Sources: src/PreviewRenderer.js:113-118, src/PreviewRenderer.js:237-241
The diagram shows how user interaction with the GUI triggers a rendering update in the 3D scene. Sources: src/PreviewRenderer.js:113-118, src/PreviewRenderer.js:237-246
Configuration Options
The panel provides controls for several technical parameters of the 3D preview. These controls are mapped to the options object within the PreviewRenderer.
| Control Label (Translation Key) | Type | Purpose |
|---|---|---|
preview.options.maxPointLights | Range | Limits the number of active point lights (e.g., from torches/lanterns) in the scene. |
preview.options.shadowsEnabled | Toggle | Enables or disables directional light shadows. |
preview.options.shadowQuality | Range | Adjusts the resolution of the directional light shadow map. |
preview.options.lightAngle | Range | Changes the horizontal angle (rotation) of the main directional light. |
preview.options.lightHeight | Range | Adjusts the vertical elevation of the main directional light. |
preview.options.showSkybox | Toggle | Toggles the visibility of the panorama background. |
preview.options.highRes | Toggle | Scales the canvas resolution based on device pixel ratio. |
Sources: src/PreviewRenderer.js:24-35, src/PreviewRenderer.js:160-184, src/translations/en_US.json:52-62
Implementation Details
The GUI uses translation keys to support multiple languages. Labels are applied using the data-translate attribute on the internal GUI controller elements, which allows the main translation system to update them dynamically.
Control Setup Example
// From PreviewRenderer.js
if (this.#pointLights.length > 0) {
this.#guiLocName(
this.#optionsGui.add(this.options, "maxPointLights", 0, this.#pointLights.length, 1)
.onChange(() => this.#createPointLightsInScene()),
"preview.options.maxPointLights"
);
}
Sources: src/PreviewRenderer.js:160-164
Special Actions
Beyond simple parameters, the panel includes buttons for specific actions:
- Screenshot: Triggers
downloadScreenshot()which renders the current frame to a Blob and initiates a file download. - Export as GLB: Triggers
exportGlb(), which usesGLTFExporterto convert the structure's instanced meshes into a 3D model file.
Sources: src/PreviewRenderer.js:181-182, src/PreviewRenderer.js:215-235
Conclusion
The LilGui Settings Panel serves as the primary bridge between the user and the technical configuration of the hologram preview. By wrapping lil-gui in a custom Web Component, HoloPrint achieves clean style isolation while providing an extensible interface for managing complex 3D rendering properties like point light limits and shadow mapping quality.