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

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 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. 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.

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, 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 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.

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.

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.

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

The hash function, defined in 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.

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.

{
  "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:

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, 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 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, 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 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. 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. 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.

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