How the Render Quality System Works in the Text-to-CAD Viewer

The render quality system dynamically balances visual fidelity and GPU performance by calculating a pixel ratio cap that switches between high-quality idle mode and lower-quality interaction mode based on the presence of screen-space line materials in the scene.

The render quality system in the earthtojake/text-to-cad repository controls how the viewer allocates GPU resources when rendering CAD models. Located within the cadjs package, this system automatically detects scene composition—specifically whether edge-rendered lines are present—and adjusts the rendering resolution to ensure the UI remains responsive during user interactions.

Core Architecture of the Render Quality System

The resolveInteractionPixelRatioCap Function

At the heart of the system is the resolveInteractionPixelRatioCap function defined in [packages/cadjs/src/lib/viewer/renderQuality.js](https://github.com/earthtojake/text-to-cad/blob/main/packages/cadjs/src/lib/viewer/renderQuality.js). This function determines the maximum pixel ratio the renderer may use, directly impacting image sharpness versus GPU load.

The function evaluates scene content through the following logic:

1. If preservePixelRatio is true, the function immediately returns the idlePixelRatioCap, bypassing automatic detection.
2. Otherwise, it calculates the count of screen-space line materials from either screenSpaceLineMaterialCount or the size of screenSpaceLineMaterials.
3. If any line materials exist (count > 0), the function returns the idle cap to maintain crisp edge rendering.
4. If no line materials exist, it returns the interactionPixelRatioCap, reducing quality to preserve frame rate during mesh-only scene navigation.

export function resolveInteractionPixelRatioCap({
  idlePixelRatioCap = 2,
  interactionPixelRatioCap = 1,
  preservePixelRatio = false,
  screenSpaceLineMaterialCount = null,
  screenSpaceLineMaterials = null
} = {}) {
  if (preservePixelRatio) {
    return idlePixelRatioCap;
  }
  const materialCount = screenSpaceLineMaterialCount != null && Number.isFinite(Number(screenSpaceLineMaterialCount))
    ? Number(screenSpaceLineMaterialCount)
    : Number(screenSpaceLineMaterials?.size || 0);
  return materialCount > 0
    ? idlePixelRatioCap          // keep high quality when screen‑space lines exist
    : interactionPixelRatioCap; // lower quality for mesh‑only scenes
}

Scene Content Detection Logic

The system distinguishes between mesh-only scenes and edge-rendered CAD scenes by inspecting screenSpaceLineMaterials. When screen-space lines are present—used for rendering technical edges and wireframes—the viewer maintains the higher idlePixelRatioCap (default 2) to prevent line aliasing. For scenes without these materials, the viewer drops to the interactionPixelRatioCap (default 1) to maximize frame rates during camera rotation and zoom operations.

Configuration Parameters

The render quality system accepts five parameters that control its behavior:

• idlePixelRatioCap: The desired pixel ratio when the viewer is not being interacted with (default: 2). Higher values produce sharper images but require more GPU power.
• interactionPixelRatioCap: The desired pixel ratio during active user interaction (default: 1). Lower values prevent frame rate drops when rotating or zooming the camera.
• preservePixelRatio: When set to true, forces the idle cap to be used regardless of scene content, effectively disabling automatic quality reduction.
• screenSpaceLineMaterialCount: An explicit number of screen-space line materials present in the scene, used to override automatic detection.
• screenSpaceLineMaterials: A Set or collection of line material objects that the function inspects to determine if edge rendering is active.

Runtime Integration with the Viewer

useViewerRuntime.js Hook

The viewer applies these calculations through the runtime hook located at [viewer/src/client/components/viewer/hooks/useViewerRuntime.js](https://github.com/earthtojake/text-to-cad/blob/main/viewer/src/client/components/viewer/hooks/useViewerRuntime.js). This hook imports resolveInteractionPixelRatioCap and feeds its return value into the three.js renderer via renderer.setPixelRatio.

This integration ensures that:

• Mesh-only scenes automatically use the lower interaction cap, maximizing frame rate during navigation.
• Edge-rendered CAD scenes retain the higher idle cap, ensuring technical line work remains crisp and readable.
• User preferences can override the automatic system by setting preservePixelRatio to maintain maximum quality at all times.

Practical Implementation Examples

The following examples demonstrate how to import and use the render quality resolver in your own implementations:

import { resolveInteractionPixelRatioCap } from "cadjs/lib/viewer/renderQuality";

// Mesh-only scene – no screen-space lines, uses lower quality for performance
const cap1 = resolveInteractionPixelRatioCap({
  idlePixelRatioCap: 2,
  interactionPixelRatioCap: 1.25,
  screenSpaceLineMaterials: new Set()
});
// → 1.25

// Edge-rendered CAD – line materials present, maintains high quality
const cap2 = resolveInteractionPixelRatioCap({
  idlePixelRatioCap: 2,
  interactionPixelRatioCap: 1.25,
  screenSpaceLineMaterials: new Set([{}])
});
// → 2

// Explicit material count overrides automatic detection
const cap3 = resolveInteractionPixelRatioCap({
  idlePixelRatioCap: 2,
  interactionPixelRatioCap: 1.25,
  screenSpaceLineMaterialCount: 4
});
// → 2

// User forces high quality regardless of scene content
const cap4 = resolveInteractionPixelRatioCap({
  idlePixelRatioCap: 2,
  interactionPixelRatioCap: 1.25,
  preservePixelRatio: true
});
// → 2

Testing and Validation

The system includes comprehensive unit tests in [packages/cadjs/src/lib/viewer/renderQuality.test.js](https://github.com/earthtojake/text-to-cad/blob/main/packages/cadjs/src/lib/viewer/renderQuality.test.js) that validate each decision branch. These tests confirm that the function correctly handles empty material sets, explicit counts, and the preservation flag, ensuring reliable behavior across different CAD scene types.

Summary

• The render quality system uses resolveInteractionPixelRatioCap to dynamically select between idle and interaction pixel ratios.
• Screen-space line materials trigger high-quality rendering (idle cap), while mesh-only scenes fall back to lower quality (interaction cap) for better performance.
• The preservePixelRatio parameter allows users to override automatic adjustments and maintain maximum resolution.
• Implementation spans the cadjs package core logic and the viewer's runtime hooks, with full test coverage in renderQuality.test.js.

Frequently Asked Questions

How does the viewer decide when to reduce render quality?

The viewer calls resolveInteractionPixelRatioCap on every frame or when scene composition changes. If no screen-space line materials are detected and preservePixelRatio is false, the function returns the lower interactionPixelRatioCap, causing the renderer to reduce the pixel ratio and improve frame rates during camera navigation.

What is the default pixel ratio behavior in the Text-to-CAD viewer?

By default, the system uses a pixel ratio of 2 when idle (high quality) and drops to 1 during interaction. However, if the scene contains edge-rendered lines (screen-space line materials), the viewer maintains the idle cap of 2 even during interaction to prevent line aliasing.

Can users force high-quality rendering regardless of performance impact?

Yes. Setting the preservePixelRatio parameter to true forces the viewer to always use the idlePixelRatioCap, bypassing the automatic quality reduction that normally occurs during interaction with mesh-only scenes.

Where is the render quality logic integrated into the three.js rendering pipeline?

The logic is integrated in [viewer/src/client/components/viewer/hooks/useViewerRuntime.js](https://github.com/earthtojake/text-to-cad/blob/main/viewer/src/client/components/viewer/hooks/useViewerRuntime.js), where the calculated pixel ratio cap is applied to the three.js renderer instance via the setPixelRatio method, dynamically adjusting the rendering resolution based on current scene demands.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}