Skip to main content

SPC CAD Panel

A Grafana panel plugin for visualizing 3D CAD models, point clouds, and metrology data within Grafana dashboards. Designed for quality control, manufacturing inspection, and metrology data visualization workflows.

SPC CAD demo

Table of Contents​

Overview​

The SPC CAD Panel brings 3D visualization capabilities to Grafana, enabling you to:

  • Display CAD models alongside measurement data
  • Annotate geometric features with live data from your queries
  • Apply conditional color coding based on measurement values
  • Visualize point cloud data with deviation coloring
  • Create interactive 3D reports for quality control workflows

Getting Started​

Basic Setup​

  1. Install the plugin in your Grafana instance
  2. Create a new panel and select "SPC CAD" as the visualization type
  3. Add a CAD model using the panel options (see CAD Model Configuration)
  4. Configure your data query to return feature measurements (see Data Model Requirements)
  5. Click on features in the 3D view to create annotations

Quick Example​

To create a basic CAD visualization:

  1. In panel options, add a CAD model URL (e.g., https://example.com/model.stl)
  2. Create a query that returns at least these columns:
    • feature - Feature name
    • characteristic_id - Unique identifier
    • nominal - Nominal value
  3. The panel will automatically position features if X, Y, Z characteristics are present
  4. Click any feature to open an annotation

SPC CAD Panel with Features

Supported File Formats​

The panel supports multiple file formats for both CAD models and point clouds:

CAD Models​

FormatExtensionDescriptionUse Case
STL.stlStereolithography (binary/ASCII)Most common 3D model format
3MF.3mf3D Manufacturing FormatModern alternative to STL with color support
PLY.plyPolygon File FormatPoint clouds and meshes with custom attributes
ASC.ascASCII Point CloudDeviation/comparison data
Images.jpg, .png, .svg2D imagesTechnical drawings or reference images

Compression Support: All formats can be GZIP compressed (.gz, .gzip extensions)

Recommended file size: Up to 200 MB (5 MB limit for uploads)

ASC Deviation File Format​

ASC files are used for point cloud deviation data. Each line represents a measurement point with space-separated values:

Name X Y Z Nx Ny Nz DevX DevY DevZ DevTotal
  • Name - String identifier for the surface comparison
  • X Y Z - Coordinates of the measurement point
  • Nx Ny Nz - Surface normal vector components
  • DevX DevY DevZ - Deviation components along each axis
  • DevTotal - Absolute magnitude of total deviation

Example:

Surface_comparison_cube 5.000000 5.000000 0.000000 0.000000 0.000000 -1.000000 -0.000000 -0.000000 0.080942 0.080942

All numeric values should be floating-point with six decimal places. No header row is required.

Data Model Requirements​

The panel expects data in a specific structure from your Grafana queries. Understanding this structure is crucial for proper visualization.

Required DataFrame: Features​

Your primary query should return feature and characteristic data:

Required Columns​

  • feature - Feature name/identifier (string)
  • characteristic_id - Unique identifier for each characteristic (string or number)
  • characteristic_name - Display name for the characteristic (defaults to characteristic_id)
  • nominal - Nominal/reference value (number)
  • partid - Part identifier for grouping
  • featuretype - Feature type classification (point, circle, cylinder, etc.)

Additional Columns​

Any additional columns in your query will be treated as characteristic data fields and will be available for display in annotations, tables, and color mapping rules.

Example Query Result:

featurecharacteristic_idnominalcharacteristic_namexyzmeasuredtolerance
Hole_01char_00110.0X Position10.00010.050.1
Hole_01char_00220.0Y Position020.0019.980.1
Hole_01char_0035.0Z Position005.05.020.1
Hole_01char_0046.5Diameter0006.480.05

Optional DataFrame: CAD Models​

You can load CAD models from your data source by returning a DataFrame with:

  • links - URL or path to CAD file
  • colors - Hex color code for the model (e.g., #FF0000)

Optional DataFrame: Scan Timeline​

For time-series point cloud data, create a DataFrame named scans:

  • links - URL to scan file
  • times - Timestamp of the scan (Grafana time format)

This enables the scan timeline slider for navigating through historical scan data.

Optional: Time Series Data​

To display charts in annotations, include time-series data in either:

  1. Grafana Time Series Format - Standard Grafana time field with value columns
  2. Long Format with columns:
    • time - Timestamp
    • characteristic_id - Characteristic identifier
    • value - Measurement value

The panel will automatically filter null values and associate time series data with characteristics.

Features and Characteristics​

In dimensional metrology, a feature refers to a specific geometric element of a component being measured (e.g., hole, surface, edge). Each feature consists of one or more characteristics - measurable properties like position, diameter, angle, or surface finish.

Feature Positioning​

Features are positioned in 3D space when they have X, Y, and Z characteristics with valid nominal values. The panel looks for characteristics named:

  • X, x, or characteristic names containing "X Position"
  • Y, y, or characteristic names containing "Y Position"
  • Z, z, or characteristic names containing "Z Position"

Position Resolution Modes:

  1. Automatic - X, Y, Z characteristics found with valid nominal values
  2. Custom - Manually positioned using the unpositioned features editor
  3. No Position - Feature explicitly marked as having no position (annotation-only)
  4. Undefined - No position data available (must be manually positioned)

Working with Unpositioned Features​

If features lack position data, they appear in the Unpositioned Features Editor in panel options:

  1. Select a feature from the list
  2. Click "Position Feature" to enter placement mode
  3. Click anywhere on the 3D scene to place the feature
  4. Save or cancel the positioning

Alternatively, features can be used without 3D positioning - annotations will appear in window mode without a 3D marker.

CAD Model Configuration​

Adding Models from URL​

  1. Open panel options and navigate to "CAD Models"
  2. Click "Add CAD Model"
  3. Enter the URL to your model file
  4. (Optional) Choose a custom color for the model
  5. Save the panel

Example URLs:

  • https://example.com/models/part.stl
  • /public/models/housing.3mf
  • ${variable}/path/to/model.stl (with dashboard variables)

Uploading Models​

For local files or testing:

  1. Click "Upload File" in the CAD models section
  2. Select a file (max 5 MB)
  3. The file will be embedded as Base64 data in the panel configuration

Note: Uploaded files increase panel configuration size. For production, prefer hosting files separately and using URLs.

Model Appearance​

Each model can be customized:

  • Color - Click the color picker to change the model's color
  • Visibility - Toggle models on/off
  • Multiple Models - Add multiple models to the same scene

Annotations System​

Annotations are interactive information boxes that display data about features. They consist of a 3D label/marker and an expandable window containing customizable views.

Annotations

Annotation Display Modes​

Each annotation has three display states:

  1. Hidden - Annotation not visible
  2. Label - Compact floating label that follows the feature
    • Shows feature title
    • Can be colored based on data values
    • Click to expand to window mode
  3. Window - Fixed panel with full content
    • Resizable and draggable
    • Contains multiple views/tabs
    • Grid layout positioning

Creating Annotations​

  1. Click on a feature in the 3D view
  2. An annotation is automatically created in label mode
  3. Click the label to expand it to a window
  4. Use the pin icon to keep the window open

Annotation Settings​

Each annotation can be configured independently:

  • Title Column - Choose which data column to display as the title
  • Template - Select a template for the annotation layout (see Templates)
  • Color Rules - Apply conditional styling to the header (see Color Mapping)
  • Link - Add URL linking with variable substitution
  • Grid Position - Manually position and resize windows

Annotation Editor​

The Annotation Editor provides full customization of annotation content and appearance.

Annotation Editor Access

Accessing the Editor​

Two ways to open the editor:

  1. Double-click on any annotation view
  2. Click the gear icon in the annotation header

View System​

Annotations support multiple views (tabs), each containing one or more components. Views can be:

  • Added, removed, and reordered
  • Named for easy navigation
  • Set as the default active view

Component Types​

1. Table Component​

Displays characteristic data in tabular format.

Configuration:

  • Columns Filter - Show only specific columns (leave empty for all)
  • Rows Filter - Show only specific characteristics (leave empty for all)
  • Decimals - Number of decimal places (default: 2)

Features:

  • Automatically displays all available columns across characteristics
  • Row headers show characteristic names
  • Values retrieved from the data query

Use Cases:

  • Showing all measurements for a feature
  • Comparing nominal vs. actual values
  • Displaying tolerance information

2. Time Series Component​

Displays measurement trends over time using line/area charts.

Configuration:

  • Characteristic - Select which characteristic to plot
  • Line Color - Customize the line color (default: blue)
  • Line Width - Line thickness in pixels (default: 2)
  • Fill - Area fill percentage 0-100 (default: 0)
  • Point Size - Data point marker size (default: 6)
  • Show Legend - Display legend (default: false)
  • Decimals - Y-axis number formatting (default: 2)

Advanced Options:

  • Limit Lines - Add upper and lower specification limits
  • Constant Lines - Add reference lines with custom colors
  • SPC Integration - Statistical process control chart support

Use Cases:

  • Trending measurements over time
  • Control chart visualization
  • Process stability monitoring

3. Grid Component​

Flexible card-style layout for custom data presentation.

Configuration:

  • Show Headers - Display column headers
  • Grid Cells - Define individual cells with:
    • Name - Cell label
    • Value - Static text or dynamic data reference
    • Color Mapping - Conditional styling per cell
    • Link - URL with variable substitution
    • Suffix - Append units or text
    • Decimals - Number formatting

Features:

  • Fully customizable layout
  • Per-cell conditional formatting
  • Static and dynamic content mixing
  • URL linking with context

Use Cases:

  • Dashboard-style summary cards
  • Key metrics display
  • Pass/fail indicators with color coding

Creating Custom Views​

  1. Click "Add View" in the annotation editor
  2. Choose a view name
  3. Add components:
    • Click "Add Table", "Add Time Series", or "Add Grid"
    • Configure each component's settings
  4. Reorder components by dragging
  5. Save the annotation

Drag and Drop​

Components within a view can be reordered by dragging. This allows you to arrange information in the most logical order for your workflow.

Templates​

Templates are predefined annotation layouts for different feature types. The panel includes 13 built-in templates, each optimized for specific geometric features.

Custom Templates

Built-in Templates​

  1. Generic (Default) - Multi-view layout with Main, X, Y, Z tabs
  2. Point - Single point feature
  3. Circle - Circular features (holes, pins)
  4. Cylinder - Cylindrical features
  5. Sphere - Spherical features
  6. Ellipse - Elliptical features
  7. Line - Linear features (edges)
  8. Rectangle - Rectangular features
  9. Slot - Slot features
  10. Plane - Planar surfaces
  11. Slab - Slab/block features
  12. Cone - Conical features
  13. Comparison Point - Point cloud comparison data

Using Templates​

Automatic Template Selection:

If your data includes a featuretype column, the panel can automatically assign the appropriate template based on the feature type value.

Manual Template Assignment:

  1. Click on a feature to create an annotation
  2. Open the annotation editor (gear icon)
  3. Select a template from the dropdown
  4. The annotation layout updates immediately

Template System Benefits​

Templates provide:

  • Consistency - All features of the same type look identical
  • Efficiency - No need to manually configure each annotation
  • Best Practices - Pre-configured views for common metrology features
  • Customization - Templates serve as starting points and can be overridden

Template Customization​

While templates provide defaults, any annotation can be customized:

  1. Select a template
  2. Modify views, components, or settings
  3. The changes override the template for that annotation only
  4. Other annotations using the same template remain unchanged

Color Mapping​

Color mapping allows you to apply conditional styling to annotations based on measurement data. This provides instant visual feedback on feature quality.

Color Mapping

How Color Mapping Works​

Color rules are evaluated top-to-bottom. The first matching rule determines the header color.

Color Rule Components:

  1. Left Side - Characteristic + column to evaluate
  2. Operator - Comparison type
  3. Right Side - Value or column to compare against
  4. Colors - Background and text color to apply

Supported Operators​

  • < - Less than
  • = - Equals
  • > - Greater than

Mapping Types​

Static Value Comparison​

Compare a characteristic column against a fixed value.

Example: Highlight features where measured value exceeds nominal by more than tolerance

characteristic: "X Position"
column: "measured"
operator: >
value: 10.1
backgroundColor: #FF0000
textColor: #FFFFFF

Dynamic Column Comparison​

Compare two columns within the same characteristic.

Example: Highlight when measured value deviates from nominal

characteristic: "Diameter"
column: "deviation"
operator: >
rightColumn: "tolerance"
backgroundColor: #FFA500
textColor: #000000

Configuring Color Rules​

Template-Level Rules:

  1. Open panel options
  2. Navigate to "Templates"
  3. Select a template
  4. Add color rules
  5. Rules apply to all annotations using this template

Annotation-Level Rules:

  1. Open annotation editor
  2. Go to "Header Colors" section
  3. Add rules specific to this annotation
  4. Annotation rules override template rules

Color Rule Priority​

  1. Annotation-specific rules (highest priority)
  2. Template-default rules
  3. Default annotation color (no rules matched)

Color Mapping Best Practices​

  • Use consistent color schemes across templates (e.g., green = good, yellow = warning, red = fail)
  • Order rules from most specific to least specific
  • Test rules with representative data before deployment
  • Document your color coding in dashboard descriptions or annotations

Example: Pass/Fail Color Coding​

Rule 1: deviation < -tolerance → Red background (below spec)
Rule 2: deviation > tolerance → Red background (above spec)
Rule 3: deviation between -tolerance and tolerance → Green background (pass)

Point Clouds​

Point cloud visualization is a powerful feature for displaying scan data and deviation analysis.

Point Cloud Visualization

Loading Point Clouds​

Point clouds can be loaded from:

  1. ASC files - Deviation data with point-by-point comparison
  2. PLY files - Generic point cloud format with optional deviation attributes

Via URL:

Add CAD Model → Enter ASC/PLY file URL

Via Data Query:

SELECT
  '/path/to/scan.asc' as links,
  '#FF0000' as colors

Deviation Visualization​

When point clouds include deviation data, the panel automatically applies color gradient mapping:

  • Blue - Negative deviation (below nominal)
  • Green - Zero deviation (at nominal)
  • Red - Positive deviation (above nominal)

The gradient is calculated based on standard deviation:

  • Range = ±3σ (captures ~99.7% of points in normal distribution)
  • 7-step gradient for smooth color transitions

Gradient Legend​

The gradient legend appears when a point cloud is loaded.

Features:

  • Shows deviation range (min to max)
  • Current hovered point value with crosshair indicator
  • Automatic decimal precision based on range magnitude
  • Standard deviation-based range calculation

Point Cloud Interaction​

Hover over points to:

  • See the deviation value in the legend
  • Highlight the point with a red sphere marker
  • View point coordinates

Benefits:

  • Quickly identify problem areas
  • Understand deviation patterns
  • Compare actual vs. nominal geometry

Scan Timeline​

For time-series point cloud data, use the scan timeline:

  1. Configure a scans DataFrame in your query with:
    • links - Scan file URLs
    • times - Timestamps
  2. A timeline slider appears at the bottom
  3. Use play/pause controls to animate through scans
  4. Click any point on the timeline to jump to that scan

Use Cases:

  • Part inspection over time
  • Process monitoring
  • Historical comparison
  • Quality trend analysis

Panel Options​

The panel provides extensive configuration options organized into sections.

CAD Models Section​

  • Add Model - Add CAD models from URL
  • Upload File - Upload local files (max 5 MB)
  • Model Color - Customize model appearance
  • Remove Model - Delete models from the scene

Feature Settings​

  • Feature Size - Control the size of feature markers (range: 1-200)
    • Smaller values: More subtle markers
    • Larger values: Easier to click, more prominent
    • Default: 10
  • Feature Color - Default color for features without color mapping

Scene Settings​

  • Camera Position - X, Y, Z coordinates (default: 0, 0, 2500)
  • Camera Target - Look-at point X, Y, Z (default: 0, 0, 0)
  • Camera Up Vector - Orientation (default: 0, 1, 0)

These settings persist when you refresh the dashboard, maintaining your viewing angle.

Annotation Settings​

  • Title Column - Default column for annotation titles
  • Template - Default template for new annotations
  • Pin by Default - Whether new annotations open as windows or labels

Unpositioned Features​

  • Feature List - Shows features without 3D position data
  • Position Tool - Click-to-place positioning interface
  • Manual Positioning - Enter exact X, Y, Z coordinates

3D Navigation​

The panel uses intuitive trackball controls for 3D navigation.

Mouse Controls​

  • Left Click + Drag - Rotate the view around the target point
  • Scroll Wheel - Zoom in/out
  • Middle Click + Drag - Pan the view
  • Right Click - Open feature context menu (when over a feature)

View Helper​

A 3D orientation cube appears in the corner:

  • Shows current view orientation (X, Y, Z axes)
  • Click any face to snap to that view
  • Helps maintain orientation in complex scenes

Camera Presets​

While the panel doesn't include built-in view presets, you can:

  1. Position the camera as desired
  2. The position is saved in panel options
  3. Export/import panel JSON to save views
  4. Use dashboard variables to switch between camera positions
  • Start with a top-down view (Z-axis) for 2D-like inspection
  • Use pan to center features of interest before rotating
  • Zoom in on small features before attempting to click them
  • Reset view by entering default camera settings in panel options

Advanced Topics​

URL Linking​

Both annotations and grid cells support dynamic URL linking:

Variable Substitution:

  • Use ${fieldName} to insert data values
  • Example: https://erp.example.com/parts/${partid}

Configuration:

  • URL template with variables
  • Open in new tab option
  • Available in:
    • Annotation-level settings
    • Grid cell settings

Dashboard Variables Integration​

The panel supports Grafana dashboard variables in:

  • CAD model URLs
  • Link URLs
  • Panel titles

Example:

Model URL: /models/${partNumber}.stl
Link URL: https://mes.example.com/${line}/${batch}

Multi-Part Assemblies​

To display multiple parts simultaneously:

  1. Load multiple CAD models
  2. Use partid column in your data to associate features with specific models
  3. Color code models by part for easy identification
  4. Position models relative to each other using coordinate offsets

Performance Optimization​

For Large Models:

  • Use compressed files (.gz)
  • Prefer binary STL over ASCII STL
  • Consider decimating meshes before loading

For Many Features:

  • Reduce feature size if many overlap
  • Use label mode instead of window mode by default
  • Filter data to show only relevant features

For Time Series:

  • Limit time range in Grafana queries
  • Use query-level filtering
  • The panel filters null values automatically

Data Source Considerations​

Best Practices:

  • Index characteristic_id and feature columns
  • Use time-based partitioning for historical data
  • Pre-calculate deviation values if possible
  • Return only necessary columns to reduce data transfer

Query Performance:

  • Use query-level aggregation when possible
  • Leverage Grafana's time range variables
  • Consider materialized views for complex calculations

Extending Templates​

While the panel includes 13 built-in templates, you can:

  1. Start with the Generic template
  2. Customize views and components
  3. Export panel JSON
  4. Import into other dashboards
  5. Share customized templates with your team

Integration with Other Panels​

The CAD panel works well alongside:

  • Table panels - Detailed feature listings
  • Stat panels - Key metrics summary
  • Time series panels - Trending over time
  • Alert panels - Quality notifications

Use dashboard links and panel links to create coordinated multi-panel reports.

Troubleshooting​

Common Issues​

Models Not Loading​

Problem: CAD model doesn't appear in the scene

Solutions:

  1. Check the URL is accessible (test in browser)
  2. Verify file format is supported
  3. Check browser console for CORS errors
  4. Ensure file size is under 200 MB
  5. Try uploading the file instead of using a URL

Features Not Positioned​

Problem: Features don't appear in 3D space

Solutions:

  1. Verify X, Y, Z characteristics exist in data
  2. Check that nominal values are valid numbers (not null)
  3. Use the Unpositioned Features editor to manually place features
  4. Verify characteristic names match expected patterns (X, Y, Z)

Annotations Not Showing Data​

Problem: Annotation tables or charts are empty

Solutions:

  1. Check that characteristic IDs match between configuration and data
  2. Verify data query returns expected columns
  3. Ensure characteristic names are correct
  4. Check for null values in data (automatically filtered)
  5. Test query separately in Grafana Explore

Color Mapping Not Working​

Problem: Conditional colors don't apply

Solutions:

  1. Verify characteristic names match exactly (case-sensitive)
  2. Check column names in color rules match data columns
  3. Ensure rule operator is correct (<, =, >)
  4. Test with static values first before dynamic comparisons
  5. Check rule order (first match wins)

Point Cloud Colors Wrong​

Problem: Deviation colors don't match expected values

Solutions:

  1. Verify deviation values are in the correct column
  2. Check that deviation range calculation is appropriate
  3. Ensure ASC file format matches specification
  4. Test with a known-good sample file
  5. Check that the gradient legend shows expected range

Performance Issues​

Problem: Panel is slow or unresponsive

Solutions:

  1. Reduce model file size or use compressed formats
  2. Decrease number of features displayed
  3. Limit time series data range
  4. Close unused annotation windows
  5. Use label mode instead of window mode
  6. Filter data at query level, not panel level

Browser Console Errors​

Always check the browser console (F12 → Console tab) for error messages. Common errors:

  • CORS errors: Model files must be served with appropriate headers
  • Memory errors: File too large, try compression or decimation
  • Parse errors: File format issue, verify file integrity
  • Network errors: URL not accessible, check network/firewall

Getting Help​

If you encounter issues not covered here:

  1. Check the GitHub Issues for similar problems
  2. Search the KensoBI documentation
  3. Ask in the KensoBI Discord community
  4. Create a new issue with:
    • Grafana version
    • Plugin version
    • Browser and OS
    • Steps to reproduce
    • Browser console errors
    • Sample data (if possible)

Known Limitations​

  • Maximum upload file size: 5 MB (no limit for URL-loaded files)
  • Point cloud hover detection threshold: 1 unit (may miss very small points)
  • Time series null filtering: Done at display time (may affect performance with very large datasets)

Additional Resources​

License​

This software is distributed under the GNU Affero General Public License v3.0.

Copyright (c) 2026 Kenso Software