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

> Discover how the Text-to-CAD viewer's render quality system balances visual fidelity and GPU performance. Learn about its dynamic pixel ratio cap for optimal rendering.

- Repository: [earthtojake/text-to-cad](https://github.com/earthtojake/text-to-cad)
- Tags: internals
- Published: 2026-08-01

---

**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)](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.

```javascript
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)](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:

```javascript
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

```

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

```

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

```

```javascript
// 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)](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`](https://github.com/earthtojake/text-to-cad/blob/main/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)](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.