How to Customize Display Settings and Themes in cadjs: A Complete Guide

You can fully customize the visual appearance of CAD models in cadjs by overriding the BASE_VIEWER_THEME with a user-supplied themeSettings object that controls backgrounds, floor modes, edge colors, and material properties.

The cadjs library from the earthtojake/text-to-cad repository provides a flexible theming system built on Three.js that allows developers to modify every visual aspect of the viewer without touching core rendering code. All display customization logic resides in packages/cadjs/src/lib/viewer/stageTheme.js, which handles theme resolution, texture generation, and contrast-aware color management.

Understanding the cadjs Theme Architecture

The cadjs viewer uses a layered theme system that merges default values with user overrides. At the foundation lies the BASE_VIEWER_THEME constant defined in stageTheme.js (lines 8-55), which establishes default colors, gradients, and material parameters.

When initializing a viewer instance, you can supply a themeSettings object that overrides specific properties while inheriting defaults for unspecified values. The system supports four background types enumerated in THEME_BACKGROUND_TYPES (lines 58-62): solid color, linear gradient, radial gradient, and transparent.

// Example themeSettings structure accepted by cadjs
const customTheme = {
  background: {
    type: "linear",
    linearStart: "#ffefd5",
    linearEnd: "#1e3a8a",
    linearAngle: 45
  },
  floor: {
    enabled: true,
    mode: "grid",
    color: "#222222"
  },
  materials: {
    roughness: 0.4,
    clearcoat: 0.2
  }
};

Customizing Backgrounds in cadjs

Background customization in cadjs relies on the createSceneBackgroundTexture function (lines 34-81 in stageTheme.js) to generate canvas-based textures for solid colors or gradients. The applySceneBackground function (lines 37-58) then assigns these textures to the Three.js scene.

The system automatically handles hex color validation using HEX_COLOR_PATTERN and helper functions like normalizeHexColor (lines 65-73), ensuring that 3-digit hex codes expand properly and color values remain valid across different rendering contexts.

import { applySceneBackground } from './stageTheme.js';

// Apply a radial gradient background
applySceneBackground(runtime, runtime.viewerTheme, {
  type: "radial",
  radialStart: "#ffffff",
  radialEnd: "#0f172a",
  radialCenterX: 0.5,
  radialCenterY: 0.5
});

Configuring Floor Display Modes

The cadjs viewer supports three distinct floor modes controlled by resolveFloorMode (lines 83-97): grid overlay, solid stage plane, or hidden. When enabled, createStageFloorPlane (lines 95-81) generates a MeshPhysicalMaterial with configurable roughness, reflectivity, and glass factor.

Floor appearance respects both the base theme and user-supplied themeSettings.floor parameters, including horizon blending and opacity controls. The optional grid overlay implemented in stageGrid.js activates when mode: "grid" is specified.

// Force a solid stage floor with specific material properties
runtime.updateFloor(runtime, {
  floor: {
    enabled: true,
    mode: "stage",
    color: "#1a1a1a",
    horizonBlend: 0.2,
    reflectivity: 0.15
  },
  materials: {
    roughness: 0.4,
    clearcoat: 0.2,
    envMapIntensity: 0.7
  }
});

Managing Edge Colors and Contrast

Cadjs automatically ensures wireframe edges remain visible against varying backgrounds through the resolveWireframeEdgeColor function (lines 43-61). This utility calculates relative luminance and contrast ratios using relativeLuminance and contrastRatio helpers, falling back to adjusted colors when user selections fail to meet the minimum contrast threshold (default 3:1).

For stricter accessibility requirements, you can specify a higher minimumContrastRatio when resolving edge colors.

import { resolveWireframeEdgeColor } from './stageTheme.js';

const safeEdgeColor = resolveWireframeEdgeColor({
  edgeColor: "#ff00ff",
  themeSettings: customTheme,
  viewerTheme: runtime.viewerTheme,
  minimumContrastRatio: 4.5  // WCAG AA compliant
});

Implementing Complete Theme Overrides

To implement a comprehensive visual overhaul, pass a complete themeSettings object during skill initialization or viewer setup. The system accepts parameters for background, floor, materials, and lighting, merging your specifications with BASE_VIEWER_THEME defaults.

const myThemeSettings = {
  background: {
    type: "linear",
    linearStart: "#ffefd5",
    linearEnd: "#1e3a8a",
    linearAngle: 45
  },
  floor: {
    enabled: true,
    mode: "grid",
    color: "#222222",
    horizonBlend: 0.2,
    reflectivity: 0.15
  },
  materials: {
    roughness: 0.4,
    clearcoat: 0.2,
    envMapIntensity: 0.7
  },
  lighting: {
    spot: {
      enabled: true,
      intensity: 1.2,
      color: "#ffdd00"
    }
  }
};

// Apply to runtime
runtime.applySceneBackground(runtime, runtime.viewerTheme, myThemeSettings.background);
runtime.updateFloor(runtime, myThemeSettings);

Summary

• Theme system: Cadjs uses a base theme merged with user-supplied themeSettings defined in packages/cadjs/src/lib/viewer/stageTheme.js.
• Background options: Supports solid colors, linear gradients, radial gradients, and transparent backgrounds via createSceneBackgroundTexture.
• Floor modes: Choose between grid, solid stage, or hidden floors using resolveFloorMode and createStageFloorPlane.
• Color safety: The resolveWireframeEdgeColor function ensures minimum contrast ratios for wireframe visibility.
• Validation: Hex colors normalize automatically through normalizeHexColor and HEX_COLOR_PATTERN.

Frequently Asked Questions

How do I change the background to a transparent grid in cadjs?

Set the background type to "transparent" and enable the floor grid mode in your themeSettings object. The viewer will render the Three.js scene without a background texture while displaying the grid overlay defined in stageGrid.js.

const settings = {
  background: { type: "transparent" },
  floor: { enabled: true, mode: "grid" }
};

What file controls the default colors in cadjs?

The BASE_VIEWER_THEME constant in packages/cadjs/src/lib/viewer/stageTheme.js (lines 8-55) defines all default colors, gradients, and material parameters. Override these values by passing a themeSettings object to the viewer runtime rather than modifying the source file.

How does cadjs ensure wireframe edges remain visible against dark backgrounds?

The resolveWireframeEdgeColor function automatically calculates contrast ratios using relativeLuminance and contrastRatio helpers. If your specified edge color fails to meet the minimum contrast threshold against the current background, the system selects a fallback color that satisfies the visibility requirement.

Can I export the background texture created by cadjs for use in other applications?

Yes, the createSceneBackgroundTexture function returns a standard THREE.CanvasTexture that you can extract and export. Pass the Three.js namespace, viewer theme, and background settings to generate a canvas-based texture compatible with any Three.js application or export pipeline.

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