# How the color_splash Tool in revit-mcp Maps Parameter Values to Element Colors

> Learn how the revit-mcp color_splash tool maps parameter values to element colors. Visualize Revit data with custom or automatic color palettes based on instance parameters.

- Repository: [MCP servers for Revit/revit-mcp](https://github.com/mcp-servers-for-revit/revit-mcp)
- Tags: how-to-guide
- Published: 2026-02-16

---

**The `color_splash` tool in revit-mcp visualizes Revit element data by applying distinct colors to elements based on their instance parameter values, using either a user-defined color map or a deterministic automatic palette.**

The `color_splash` command is a core feature of the [revit-mcp](https://github.com/mcp-servers-for-revit/revit-mcp) repository, enabling Model Context Protocol (MCP) clients to perform data-driven visualization directly within Revit. By mapping parameter values to element colors, architects and engineers can quickly identify patterns in building data such as fire ratings, room types, or structural materials.

## Understanding the color_splash Command Architecture

### Command Arguments and Input Structure

The command accepts a structured JSON argument object defined in [`src/commands/color_splash.ts`](https://github.com/mcp-servers-for-revit/revit-mcp/blob/main/src/commands/color_splash.ts). The primary input is the `parameterName` string, which specifies the exact Revit instance parameter to evaluate. Optionally, users can provide a `colorMap` object that explicitly maps parameter values to hex color strings.

```typescript
const { parameterName, colorMap = {} } = args;

```

If the `colorMap` is omitted or empty, the tool automatically generates colors using an internal hashing algorithm against a default palette.

### Core Implementation in color_splash.ts

The main logic resides in [`src/commands/color_splash.ts`](https://github.com/mcp-servers-for-revit/revit-mcp/blob/main/src/commands/color_splash.ts), which orchestrates the four-stage pipeline: element collection, parameter extraction, color determination, and graphics override application. This file imports the Revit interface from [`src/revit/interface.ts`](https://github.com/mcp-servers-for-revit/revit-mcp/blob/main/src/revit/interface.ts) to execute remote procedure calls (RPC) against the live Revit session.

## Step-by-Step Parameter-to-Color Mapping Process

### 1. Element Collection from Current View

The command first retrieves all visible element IDs from the active Revit view. This ensures that only relevant geometry is processed, improving performance and visual clarity.

```typescript
const elementIds = await revit.getCurrentViewElements();

```

This RPC method interfaces with the Revit API's `FilteredElementCollector` scoped to the active view, returning a list of integer element IDs.

### 2. Parameter Value Extraction

For each element ID, the server queries the specific instance parameter using `Parameter.LookupParameter` via the Revit API. The raw value may be a string, integer, double, or enumeration, depending on the parameter type.

```typescript
const value = await revit.getElementParameter(id, parameterName);

```

The tool handles type conversion internally, converting all values to strings for consistent key matching against the `colorMap` or hashing function.

### 3. Color Determination Logic

The core mapping logic determines the final hex color string through a prioritized fallback system:

1. **User Map Lookup**: If the `colorMap` contains an exact key matching the parameter value, that hex color is used.
2. **Automatic Palette**: If no user mapping exists, the value is hashed to an index in the `defaultPalette` array.

```typescript
const colour = colorMap[value] ?? defaultPalette[hash(value) % defaultPalette.length];

```

The `hash` function, defined in [`src/utils/color.ts`](https://github.com/mcp-servers-for-revit/revit-mcp/blob/main/src/utils/color.ts), generates a stable integer from string or numeric input, ensuring deterministic color assignment across multiple runs.

### 4. Applying Override Graphics in Revit

Finally, the command batches color override requests back to the Revit plugin. Each element receives an `OverrideGraphicSettings` update that modifies its surface or line color without altering the underlying element data.

```typescript
await revit.setElementColor(id, colour);

```

This batching approach minimizes RPC round-trips, maintaining UI responsiveness even when coloring thousands of elements simultaneously.

## Color Mapping Strategies

### User-Defined Color Maps

For categorical data such as fire ratings, room types, or structural usage, users can provide explicit semantic mappings. This ensures that "Fire Rating A" always appears red, regardless of hashing algorithms.

```json
{
  "command": "color_splash",
  "args": {
    "parameterName": "FireRating",
    "colorMap": {
      "A": "#ff0000",
      "B": "#ffa500",
      "C": "#ffff00",
      "D": "#00ff00"
    }
  }
}

```

### Automatic Palette Assignment with Hashing

When no `colorMap` is provided, the tool uses a deterministic palette defined in [`src/utils/color.ts`](https://github.com/mcp-servers-for-revit/revit-mcp/blob/main/src/utils/color.ts):

```typescript
const defaultPalette = [
  "#1f77b4", "#ff7f0e", "#2ca02c", "#d62728",
  "#9467bd", "#8c564b", "#e377c2", "#7f7f7f",
  "#bcbd22", "#17becf"
];

```

The `hash` function converts parameter values to stable indices, ensuring that the same value always maps to the same color across different visualization sessions. This is particularly effective for numeric parameters like area or height values where distinct categories emerge naturally from the data distribution.

## Integration with Revit API

The `color_splash` command relies on the RPC interface defined in [`src/revit/interface.ts`](https://github.com/mcp-servers-for-revit/revit-mcp/blob/main/src/revit/interface.ts), which abstracts the Revit API into three core asynchronous methods:

- `getCurrentViewElements()`: Wraps `FilteredElementCollector` scoped to the active view
- `getElementParameter(id, name)`: Wraps `Element.LookupParameter` and handles type conversion
- `setElementColor(id, color)`: Wraps `OverrideGraphicSettings` application via `ActiveView.SetElementOverrides`

This abstraction layer allows the TypeScript command logic to remain agnostic of Revit's internal threading requirements and document transaction management.

## Summary

- The `color_splash` tool in revit-mcp visualizes Revit element parameters by applying color overrides to elements in the current view.
- It accepts a `parameterName` and optional `colorMap`, falling back to a deterministic hash-based palette when custom mappings are absent.
- The implementation in [`src/commands/color_splash.ts`](https://github.com/mcp-servers-for-revit/revit-mcp/blob/main/src/commands/color_splash.ts) follows a four-stage pipeline: element collection, parameter extraction, color determination, and graphics override application.
- Color assignment uses either explicit user mappings or a default palette with stable hashing to ensure consistent visualization across sessions.
- The tool interfaces with Revit via RPC methods defined in [`src/revit/interface.ts`](https://github.com/mcp-servers-for-revit/revit-mcp/blob/main/src/revit/interface.ts), batching override operations for optimal performance.

## Frequently Asked Questions

### What parameters can I use with color_splash?

The `color_splash` tool works with any Revit **instance parameter** that returns a readable value via the Revit API. This includes built-in parameters like `Mark`, `Comments`, or `FireRating`, as well as custom project parameters and shared parameters added to your Revit model. The tool reads values using `Parameter.LookupParameter`, so the parameter must exist on the element instance rather than being a type parameter only.

### How does color_splash handle numeric parameter values?

For numeric parameters such as `Area`, `Volume`, or `Length`, the tool converts the raw double or integer value to a string key for lookup in the `colorMap`. If no custom mapping exists, the numeric value is passed through the `hash` function in [`src/utils/color.ts`](https://github.com/mcp-servers-for-revit/revit-mcp/blob/main/src/utils/color.ts) to generate a deterministic index into the default palette. This ensures that elements with identical numeric values receive identical colors, while distinct values are distributed across the available color spectrum.

### What happens if a parameter value is missing from my colorMap?

If a parameter value is not found in the user-provided `colorMap`, the tool automatically falls back to the **default palette** defined in [`src/utils/color.ts`](https://github.com/mcp-servers-for-revit/revit-mcp/blob/main/src/utils/color.ts). The missing value is hashed to select a color from the standard palette array, ensuring that every element receives a visual override even when the mapping is incomplete. This fallback behavior guarantees that visualizations remain functional without requiring exhaustive manual color definitions for every possible parameter value.

### Where is the default color palette defined in revit-mcp?

The default color palette is defined as a constant array in [`src/utils/color.ts`](https://github.com/mcp-servers-for-revit/revit-mcp/blob/main/src/utils/color.ts). The palette contains ten distinct hex color values designed for high contrast and visual accessibility: `#1f77b4`, `#ff7f0e`, `#2ca02c`, `#d62728`, `#9467bd`, `#8c564b`, `#e377c2`, `#7f7f7f`, `#bcbd22`, and `#17becf`. This file also exports the `hash` function used to deterministically map parameter values to indices within this palette.