syncfusion-wpf-surface-chart

实现 Syncfusion WPF Surface Chart

SfSurfaceChart 是一种三维曲面，可连接一组数据点。

何时使用此技能

当用户需要以下功能时，请使用此技能：

• 使用 X、Y 和 Z 坐标可视化三维数据
• 为数学函数或科学数据创建三维曲面图
• 显示地形图或高程图
• 展示等高线图或线框可视化
• 实现支持旋转和缩放的交互式三维图表
• 使用颜色编码值渲染热力图
• 可视化三个变量之间的关系
• 创建基于网格的三维可视化

Syncfusion WPF Surface Chart（SfSurfaceChart）专为以网格格式呈现三维数据而设计，支持多种可视化类型，包括标准曲面、线框和等高线视图。

组件概述

SfSurfaceChart 是一款功能强大的三维可视化控件，可在三维空间中显示数据点。它会连接数据点以创建连续曲面，非常适合探索三个变量之间的关系。

主要功能：

• 四种曲面类型：Surface、WireframeSurface、Contour、WireframeContour
• 多种数据绑定方式（ItemsSource 或直接数据点）
• 三个可自定义的坐标轴（X、Y、Z）
• 用于表示数值的颜色条
• 预定义和自定义调色板
• 支持交互式旋转、倾斜和缩放
• 支持透视和正交相机投影
• 渐变和纯色渲染

可视元素：

• 曲面标题 - 图表标题
• 墙面 - 图表周围的边界墙面（左侧、底部、后侧）
• 主要网格线 - 坐标轴网格线
• 颜色条 - 带有颜色映射的数值范围指示器
• 坐标轴标签 - X、Y、Z 轴的标签
• 坐标轴标题 - 各坐标轴的标题

文档与导航指南

入门

📄 阅读： references/getting-started.md

• 程序集引用和安装
• 曲面图元素的可视结构
• 使用 XAML 创建曲面图
• 使用代码隐藏创建曲面图
• 基本初始化和设置
• 添加标题、坐标轴和颜色条
• 完整的可运行示例
• 主题支持和自定义

曲面类型

📄 阅读： references/surface-types.md

• 4 种曲面类型选项概述
• Surface - 标准三维曲面可视化
• WireframeSurface - 网格/线框渲染
• Contour - 自上而下的二维等高线视图
• WireframeContour - 网格等高线可视化
• 为数据选择合适的类型
• Type 属性配置
• 视觉对比和适用场景

数据绑定

📄 阅读： references/data-binding.md

• 数据结构要求（网格格式）
• 使用集合的 ItemsSource 属性
• XBindingPath、YBindingPath、ZBindingPath 映射
• RowSize 和 ColumnSize 配置
• 通过 Data.AddPoints 方法直接输入数据
• 创建数据模型和 ViewModel
• 在 XAML 与代码隐藏中进行绑定
• 性能注意事项

坐标轴配置

📄 阅读： references/axes-configuration.md

• X、Y 和 Z 轴设置
• 默认与显式坐标轴定义
• Header 和 HeaderTemplate 自定义
• LabelTemplate 和 LabelFormat 选项
• Minimum 和 Maximum 范围设置
• Interval 和刻度配置
• GridLines 自定义（笔触、粗细）
• EdgeLabelsDrawingMode 选项
• RangePadding 设置
• 完整的坐标轴样式示例

表面区域自定义

📄 阅读： references/surface-area.md

• 表面区域属性概述
• Rotation 和 Rotate 属性
• 用于设置视角的 Tilt 属性
• 用于启用交互的 EnableRotation
• CameraProjection（Perspective/Orthographic）
• 标题和标题文本自定义
• 墙面画刷（LeftWallBrush、BottomWallBrush、BackWallBrush）
• WallThickness 配置
• 线框描边和粗细
• ShowContourLine 选项
• 用于颜色渐变的 BrushCount
• ApplyGradientBrush 设置

颜色条配置

📄 阅读： references/color-bar.md

• ColorBar 的用途和值表示
• DockPosition 属性（Left、Right、Top、Bottom）
• 用于显示数值的 ShowLabel 属性
• 添加和配置颜色条
• 与调色板集成
• XAML 和代码隐藏设置

调色板和颜色

📄 阅读： references/palettes.md

• 调色板概述和用途
• 12 种预定义调色板（Metro、AutumnBrights、FloraHues、Pineapple 等）
• 通过 Palette 属性应用预定义调色板
• 使用 ChartColorModel 创建自定义调色板
• CustomBrushes 集合
• 渐变与纯色渲染
• 调色板视觉示例

用户交互

📄 阅读： references/user-interactions.md

• 缩放功能和 EnableZooming
• 用于程序化缩放的 ZoomLevel 属性
• 支持捏合缩放
• 使用 EnableRotation 旋转
• 用于程序化旋转的 Rotate 属性
• 用于设置视角的 Tilt 属性
• 交互式控制与程序化控制
• 组合使用旋转、倾斜和缩放

故障排除

📄 阅读： references/troubleshooting.md

• 常见问题和解决方案
• 数据未正确显示
• RowSize 和 ColumnSize 不匹配
• 轴范围和缩放问题
• 性能优化提示
• 颜色条可见性问题
• 线框渲染问题
• 程序集引用错误

快速入门示例

XAML 中的基本曲面图

<Window xmlns:chart="clr-namespace:Syncfusion.UI.Xaml.Charts;assembly=Syncfusion.SfChart.WPF">
    <Grid>
        <chart:SfSurfaceChart Type="Surface" 
                             ItemsSource="{Binding DataValues}"
                             XBindingPath="X" 
                             YBindingPath="Y" 
                             ZBindingPath="Z"
                             RowSize="{Binding RowSize}"
                             ColumnSize="{Binding ColumnSize}"
                             Header="3D Surface Chart"
                             Rotate="30" 
                             Tilt="15">
            
            
            <chart:SfSurfaceChart.XAxis>
                <chart:SurfaceAxis Header="X-Axis" />
            </chart:SfSurfaceChart.XAxis>
            
            
            <chart:SfSurfaceChart.YAxis>
                <chart:SurfaceAxis Header="Y-Axis" LabelFormat="0.0" />
            </chart:SfSurfaceChart.YAxis>
            
            
            <chart:SfSurfaceChart.ZAxis>
                <chart:SurfaceAxis Header="Z-Axis" />
            </chart:SfSurfaceChart.ZAxis>
            
            
            <chart:SfSurfaceChart.ColorBar>
                <chart:ChartColorBar DockPosition="Right" ShowLabel="True" />
            </chart:SfSurfaceChart.ColorBar>
        </chart:SfSurfaceChart>
    </Grid>
</Window>

数据模型和 ViewModel

// Data Model
public class Data
{
    public double X { get; set; }
    public double Y { get; set; }
    public double Z { get; set; }
}

// ViewModel
public class ViewModel
{
    public ObservableCollection<Data> DataValues { get; set; }
    public int RowSize { get; set; }
    public int ColumnSize { get; set; }
    
    public ViewModel()
    {
        DataValues = new ObservableCollection<Data>();
        
        // Generate sample data for mathematical surface
        double inc = 8.0 / 35;
        for (double x = -4; x < 4; x += inc)
        {
            for (double z = -4; z < 4; z += inc)
            {
                double y = 2 * (x * x) + 2 * (z * z) - 4;
                DataValues.Add(new Data() { X = x, Y = y, Z = z });
            }
        }
        
        RowSize = 35;
        ColumnSize = 35;
    }
}

代码隐藏中的基本曲面图

using Syncfusion.UI.Xaml.Charts;

// Create surface chart
SfSurfaceChart chart = new SfSurfaceChart();
chart.Type = SurfaceType.Surface;
chart.Header = "3D Surface Chart";
chart.Rotate = 30;
chart.Tilt = 15;

// Add data directly using AddPoints
for (double x = -4; x < 4; x += 0.2)
{
    for (double z = -4; z < 4; z += 0.2)
    {
        double y = 2 * (x * x) + 2 * (z * z) - 4;
        chart.Data.AddPoints(x, y, z);
    }
}

chart.RowSize = 40;
chart.ColumnSize = 40;

// Configure axes
chart.XAxis = new SurfaceAxis { Header = "X-Axis" };
chart.YAxis = new SurfaceAxis { Header = "Y-Axis", LabelFormat = "0.0" };
chart.ZAxis = new SurfaceAxis { Header = "Z-Axis" };

// Add color bar
ChartColorBar colorBar = new ChartColorBar();
colorBar.DockPosition = ChartDock.Right;
colorBar.ShowLabel = true;
chart.ColorBar = colorBar;

// Add to grid
grid.Children.Add(chart);

常见模式

模式 1：数学函数可视化

在 3D 中可视化数学函数时：

// Generate data for z = sin(x) * cos(y)
for (double x = -Math.PI; x <= Math.PI; x += 0.1)
{
    for (double y = -Math.PI; y <= Math.PI; y += 0.1)
    {
        double z = Math.Sin(x) * Math.Cos(y);
        chart.Data.AddPoints(x, z, y);
    }
}

chart.RowSize = 63;  // Number of x points
chart.ColumnSize = 63;  // Number of y points

模式 2：俯视图等高线图

需要以 2D 等高线视图查看 3D 数据时：

<chart:SfSurfaceChart Type="Contour" 
                     Rotate="0"
                     ItemsSource="{Binding DataValues}"
                     XBindingPath="X" 
                     YBindingPath="Y" 
                     ZBindingPath="Z">
    <chart:SfSurfaceChart.ColorBar>
        <chart:ChartColorBar DockPosition="Right" ShowLabel="True"/>
    </chart:SfSurfaceChart.ColorBar>
</chart:SfSurfaceChart>

模式 3：带用户控制的交互式图表

需要与图表交互时：

<chart:SfSurfaceChart EnableRotation="True" 
                     EnableZooming="True"
                     Type="Surface">
    
</chart:SfSurfaceChart>

模式 4：自定义调色板

需要特定颜色时：

<chart:SfSurfaceChart Palette="Custom">
    <chart:SfSurfaceChart.ColorModel>
        <chart:ChartColorModel>
            <chart:ChartColorModel.CustomBrushes>
                <SolidColorBrush Color="Blue"/>
                <SolidColorBrush Color="Lime"/>
                <SolidColorBrush Color="Yellow"/>
                <SolidColorBrush Color="OrangeRed"/>
            </chart:ChartColorModel.CustomBrushes>
        </chart:ChartColorModel>
    </chart:SfSurfaceChart.ColorModel>
</chart:SfSurfaceChart>

模式 5：线框可视化

需要查看网格结构时：

chart.Type = SurfaceType.WireframeSurface;
chart.WireframeStroke = new SolidColorBrush(Colors.Green);
chart.WireframeStrokeThickness = 1;

关键属性

基本属性

• Type - 曲面类型（Surface、WireframeSurface、Contour、WireframeContour）
• ItemsSource - 用于绑定的数据集合
• XBindingPath、YBindingPath、ZBindingPath - X、Y、Z 值的属性路径
• RowSize、ColumnSize - 数据网格尺寸
• Data - 使用 AddPoints 方法直接添加的数据集合

视觉属性

• Header - 图表标题
• Rotate - 旋转角度（0-360）
• Tilt - 用于调整观察视角的倾斜角度
• Palette - 配色方案（Metro、AutumnBrights、FloraHues 等）
• ColorBar - 带颜色的值范围指示器

交互属性

• EnableRotation - 允许通过鼠标拖动旋转
• EnableZooming - 允许通过鼠标滚轮缩放
• ZoomLevel - 程序化缩放级别

轴属性

• XAxis、YAxis、ZAxis - 轴配置对象
• 每个轴都支持：Header、LabelFormat、Minimum、Maximum、Interval 等

自定义属性

• CameraProjection - 透视或正交视图
• LeftWallBrush、BottomWallBrush、BackWallBrush - 墙面颜色
• WallThickness - 墙面边框粗细
• WireframeStroke、WireframeStrokeThickness - 线框外观
• ApplyGradientBrush - 启用渐变着色
• BrushCount - 渐变中的颜色阶数

常见用例

用例 1：科学数据可视化

场景： 研究人员需要将实验数据可视化，其中包含 X、Y 坐标和测量得到的 Z 值。

方法： 使用 ItemsSource 绑定数据集合，配置适当的坐标轴并使用科学计数法，并采用 Metro 或 BlueChrome 等清晰的配色方案，呈现专业外观。

用例 2：数学函数绘图

场景： 学生需要将 z = f(x, y) 这样的三维数学函数可视化。

方法： 使用嵌套循环以编程方式生成数据，使用 Data.AddPoints 直接输入数据，启用旋转以便探索，并使用线框或标准曲面类型以确保清晰度。

用例 3：地形制图

场景： 显示高程数据或地形可视化。

方法： 使用等高线类型进行带颜色渐变的二维表示，或使用曲面类型呈现三维地形。应用自定义大地色系调色板（用绿-棕-白表示不同高程）。

用例 4：热力图可视化

场景： 显示两个维度上的强度或数值分布。

方法： 使用 Contour 类型并设置 Rotate="0" 以获得平面视图，配置 ColorBar 并设置 ShowLabel="True"，并使用适当 BrushCount 的渐变画刷，实现平滑过渡。

用例 5：交互式数据探索

场景： 用户需要从多个角度探索复杂的三维数据集。

方法： 同时启用 EnableRotation 和 EnableZooming，通过 Rotate 和 Tilt 提供合适的初始视角，并考虑添加 UI 控件以动态切换 Surface 类型。

用例 6：工程分析

场景： 将工程仿真中的应力、温度或压力分布可视化。

方法： 使用 Surface 或 WireframeSurface 类型，应用符合工程标准的自定义调色板（例如，蓝色表示冷/低，红色表示热/高），并使用适当的单位和精度配置坐标轴。

---

后续步骤

1. 进行初始设置： 阅读 getting-started.md
2. 选择可视化类型： 阅读 surface-types.md
3. 集成数据： 阅读 data-binding.md
4. 进行详细自定义： 按需查阅特定功能的参考文档

请记住：SfSurfaceChart 需要采用网格格式的数据，并且 RowSize 和 ColumnSize 必须保持一致。数据点的顺序很重要——应按行优先或列优先的格式组织，才能正确渲染曲面。