开发者指南

本指南涵盖了使用 ProEssentials 构建专业图表所需的一切——从选择正确的图表对象，到高效处理数据，再到 GPU 加速的实时流。ProEssentials 是一个原生 .NET 和 C++ 图表组件，具有 Direct2D、Direct3D 和 GdiPlus 渲染，专为最少的 CPU/GPU 周期和最快的图表渲染而设计。无论您是在构建 WinForm 图表、WPF 图表还是 MFC C++ 可视化，这都是您的技术参考。

选择图表对象

每个 ProEssentials 实现都从选择五个图表对象之一开始。这个选择决定了整个实现——数据模型、轴行为、绘图方法和可用功能。根据您的数据和可视化目标进行选择。

Pego — 图形对象 37 个示例

用于分类和顺序 X 轴数据的标准 .NET 图表控件。支持柱状图、折线图、面积图、堆叠柱状图、堆叠面积图、OHLC、高低收盘、带状图等共 27 种绘图方法。X 轴标签通过 PointLabels 字符串数组设置——无需数值 X 数据数组。

Pesgo — 科学图形对象 50 个示例

用于连续数值 X 轴数据的科学图表组件。支持散点图、折线图、样条线、气泡图、面积图、等高线/热力图等共 26 种绘图方法。需要包含 PeData.X[subset, point] 值的显式 X 数据数组。支持锯齿数据（子集具有不同的点数）、等高线渲染和最广泛的实时流选项。

Pe3do — 3D 科学图形 18 个示例

使用 Direct3D 渲染，通过 X、Y 和 Z 数据数组渲染 3D 表面、线框、3D 等高线、3D 柱状图和 3D 散点图。Y 是垂直（高度）轴。支持通过 AppendData（滚动表面）或 AppendSubset（瀑布）进行实时 3D 表面动画。

Pepso — 极坐标 / Smith 对象 7 个示例

用于角度数据的极坐标图表组件。支持极坐标线图、极坐标散点图、雷达/蜘蛛图、玫瑰图和用于射频工程的 Smith 图。数据以角度和幅度表示。

Pepco — 饼图对象 4 个示例

渲染饼图、环形图和多环图，支持分离扇区、百分比标签和图例集成。单一数据数组用于扇区值。

数据处理模式

ProEssentials 提供六种数据加载模式，根据数据集大小和性能要求进行选择。数据组织为子集（系列/线条）× 点（数据值）。首先设置 PeData.Subsets 和 PeData.Points，然后填充数据数组。最佳实践：将数据准备与图表 API 代码分开——先从数据源构建数组，然后将完成的数组传递给 ProEssentials。

模式 1：直接索引 10K 点以下

使用 PeData.Y[subset, point] = value 逐个赋值。对于 Pesgo，还需设置 PeData.X。对于 Pe3do，还需设置 PeData.Z。简单明了——最适合演示和小型静态数据集。

模式 2：FastCopy 250K 点以下

在代码中构建 float 数组，然后调用 PeData.Y.FastCopyFrom(array)。避免逐元素互操作开销。提供 1D、2D 和锯齿数组的重载。

模式 3：UseDataAtLocation 250K+ 点，零拷贝

将图表直接指向您的托管数组——完全不复制数据。调用 PeData.Y.UseDataAtLocation(array, bufferSize)。最适合超大数据集、多个图表共享数据或实时场景。

模式 4：AppendData 流式 / 实时

调用 PeData.Y.AppendData(newValues, amountPerSubset) 推送新数据。自动移动现有数据。与 CircularBuffers 结合使用，在 100K+ 数据点时获得环形缓冲区性能。

模式 5：BindData 数据库 / DataReader

通过 PeData.Y.BindData() 直接从 ADO.NET DataReader 或 DataView 加载。适合数据库驱动的图表应用程序。

模式 6：锯齿数据 可变长度子集

当子集具有不同的点数时，启用 PeData.JaggedData = true。需要 RenderEngine = Direct2D。三种子方法：直接索引、CopyFromJagged 或 UseJaggedDataAtLocation。

实时流

ProEssentials 支持五种实时更新策略，从简单的条带图到数百万数据点的 GPU 加速高频流。

AppendData 条带图

移动现有数据，在边缘添加新数据。最常见的实时模式。适用于 Pego、Pesgo 和 Pe3do。与 CircularBuffers 结合使用，在 100K+ 点时获得环形缓冲区性能。

FastCopyFrom 全量替换

每次 tick 替换所有数据。最适合整个缓冲区同时变化的示波器式波形显示。示例：4 个子集 × 100K 点 = 每 tick 替换 400K 值。

直接索引循环写入

通过索引直接写入，在缓冲区末尾回绕计数器。不移动、不追加——直接原地覆盖。适合循环显示。

AppendSubset 瀑布

仅限 Pe3do。每次 tick 添加一个新的完整子集，产生 3D 瀑布可视化。每次 tick 向瀑布添加一行新数据。

UseDataAtLocation 零拷贝

应用程序管理自己的内存；图表直接读取。零拷贝开销。与 CircularBuffers 和 AppendData 结合——ProEssentials 使用循环指针将数据追加到您的本地内存。示例：4 个子集 × 2M 点的零拷贝。

GPU 性能特性

ProEssentials 通过原生 Direct2D 和 Direct3D 渲染配合 GPU 加速，提供最快的图表渲染。这些功能可以组合使用以获得最大吞吐量。

ComputeShader

PeData.ComputeShader = true。将图表构建卸载到 GPU——潜在地使用 2000+ 核心 vs 单个 CPU 线程。适用于使用 Direct3D 渲染引擎的 Pesgo 和 Pe3do。对于图表几何在 GPU 而非 CPU 上构建的大型数据集，产生显著的加速效果。

Filter2D3D

PeData.Filter2D3D = true（仅限 Pesgo）。两级 ComputeShader 管道：首先无损预过滤顺序 2D 线数据，然后最终着色器构建场景。250K+ 点折线图的显著速度提升。与 ComputeShader = true 一起使用。

CircularBuffers

PeData.CircularBuffers = true。使用环形缓冲区指针代替每次 AppendData 调用时的内存移动。对于 100K+ 数据点的实时流至关重要。适用于 Pego、Pesgo、Pepso 和 Pe3do。

StagingBuffers

PeData.StagingBufferX/Y/Z = true。为高效的 CPU 到 GPU 传输管道保留数据数组的 GPU 端副本。对实时渲染期间正在更新的每个轴启用。

渲染引擎

三种渲染引擎：Direct2D、Direct3D 和 GdiPlus。Direct3D 启用 ComputeShader 和完整 GPU 加速。Direct2D 支持锯齿数据和高级 2D 渲染。GdiPlus 是具有最广泛兼容性的传统备用方案。

架构与属性接口

ProEssentials 使用分层属性接口。所有图表配置都通过从图表控件访问的嵌套属性对象完成。此架构同样适用于 .NET 图表、WPF 图表和 C++ DLL 开发。

Hierarchical Property Groups

属性组：PeData（数据数组、计数、模式）、PePlot（绘图方法、视觉选项）、PeGrid（轴刻度、网格线、缩放）、PeColor（所有元素的颜色）、PeString（标签、标题）、PeFont（字体大小）、PeAnnotation（参考线、图形注释、轴注释）、PeUserInterface（交互、光标、热点、滚动条）、PeConfigure（渲染、缓存）、PeFunction（操作——重新初始化、打印、缩放、导出）、PeTable（图表下方的数据表）、PeLegend（图例配置）。

Enum-Driven Configuration

枚举驱动配置：大多数行为设置使用枚举——切勿硬编码整数值。关键枚举包括：GraphPlottingMethod、SGraphPlottingMethod、ManualScaleControl、ViewingStyle、QuickStyle、RenderEngine、AllowZooming、MultiAxisStyle、CursorMode 和 CursorPromptStyle。重要：PePlot.Method 对每个图表对象使用不同的枚举。

Rendering Pipeline

渲染管线：应始终设置 PeConfigure.CacheBmp = true——它在内存中缓存渲染图像以实现无闪烁重绘。PeFunction.ReinitializeResetImage() 在数据更改后执行完整重建。PeFunction.ResetImage(0,0) 仅在视觉更改后重建图像。ProEssentials 包含 AI 类型的逻辑，通过智能轴缩放、标签放置、图例布局和网格线间距自动防止外观不佳的图表。

Two API Layers

两个 API 层：.NET 属性接口和 C++ DLL 接口可互换——两者都访问相同的原生引擎。.NET 是 C#/VB/WPF 的标准选择。DLL 接口用于 MFC C++、Delphi 和特殊情况。PeSpecial.HObject 为互操作场景提供原生 DLL 句柄。

注释与标签

ProEssentials 提供全面的注释系统，用于向任何图表添加参考线、文本标记、标注标签、形状和数据表。

Line Annotations

线注释：在数据坐标处的水平和垂直参考线。设置 PeAnnotation.Line.YAxis[i] 用于水平线，PeAnnotation.Line.XAxis[i] 用于垂直线。支持 16 种以上的线条样式、每个注释的颜色、文本标签和缩放窗口可见性控制。

Graph Annotations

图形注释：在任意数据坐标放置符号、文本、线条、形状和位图。支持倾斜文本、连接线、文本避让（自动避免重叠）、复合图案、位图和每个注释的单独格式。独立于图表数据——用于标注标签、叠加标记和装饰元素。

Table Annotations

表注释：最多 20 个独立定位的表元素，可出现在轴区域内、图表边缘或与数据点对齐。支持具有单独单元格格式的多列和多行布局。用于自定义图例、数据摘要和信息面板。

Quick Annotations

快速注释：通过避免完整图像重建的优化路径渲染的临时图形注释。非常适合测量叠加、拖动矩形、十字线和每次鼠标移动时更新的瞬态 UI。

用户交互与事件

ProEssentials 为用户交互触发 .NET 事件，包括数据热点点击、光标跟踪、缩放更改和自定义事件处理。关键模式包括像素到数据坐标转换（ConvPixelToGraph）、可点击图表区域的热点检测以及具有可配置工具提示样式的光标跟踪。支持鼠标滚轮缩放、交互式数据滚动和弹出菜单自定义。

Multi-Axis Charts

多轴图表：在单个图表上显示多个 Y 轴。每个轴有自己的刻度、网格数字、标签和颜色。子集通过 MultiAxisStyle 和 WorkingAxis 属性分配到轴。支持分离图形区域和重叠轴布局两种方式。

Zoom and Scroll

缩放和滚动：Pesgo 支持三个独立的轴控制级别——自动缩放、手动缩放和缩放控制。缩放覆盖手动缩放而不改变手动值。Pego 使用 PointsToGraph 进行基于滚动条的导航。交互式缩放通过 AllowZooming 枚举和鼠标滚轮配置控制。

Date/Time Axes

日期/时间轴：ProEssentials 通过序列日期值支持日期/时间 X 轴。在 PeData 上启用 DateTimeMode，然后将日期作为 OLE Automation double 传递。支持均匀时间步长（DeltaX）和可变时间步长（DeltasX 数组）。

Styling and Appearance

视觉样式：颜色通过 PeColor 属性组控制，包括每系列的 SubsetColors、图形区域颜色、轴颜色和网格线透明度。通过 ViewingStyle 和 QuickStyle 枚举快速设置视觉主题。字体大小使用比例控制系统。数据可视化功能包括 3D 阴影效果、可配置的点大小、线条样式和柱宽/间距控制。

Printing and Export

打印和导出：通过 PeFunction.PrintGraph() 和 PeFunction.PrintGraphEx() 进行程序化打印，支持方向和边距控制。图像导出支持 BMP、JPG、PNG、EMF 和 SVG 格式。支持剪贴板复制。所有导出都遵循当前渲染引擎以确保一致的输出。

AI 辅助开发

ProEssentials 包含一个 Python 驱动的 AI 辅助系统，为任何 AI 助手提供对完整 API 的按需访问——通过 Ground Truth 验证防止虚构属性路径。该系统包括 pe_query.py（15+ 查询命令）、32 个知识文件、116 个代码示例以及涵盖 1,104 个属性、1,260 个方法和 167 个枚举的结构化 JSON 数据。

知识文件下载

这些 AI 知识文件包含在您的 ProEssentials 安装中，也可以在此处下载。将它们加载到 Claude AI 项目或您首选的 AI 工具中，用于 AI 辅助 ProEssentials 开发。

Architecture & Fundamentals

• pe-core-knowledge.txt — Chart objects, architecture, workflow
• pe-base-examples.txt — Base example configurations (000-400)
• pe-data-handling.txt — 6 data loading patterns
• pe-nulldata.txt — Null and missing data handling
• pe-tool-instructions.txt — AI tool workflow and commands
• pe-cpp-api-reference.txt — C++ DLL API reference

Chart Object Patterns

• pe-pego-patterns.txt — Bar, line, area, OHLC, ribbon
• pe-pesgo-patterns.txt — Scatter, line, spline, bubble, contour
• pe-pe3do-patterns.txt — 3D surface, contour, bar
• pe-pepso-patterns.txt — Polar, radar/spider, Smith
• pe-pepco-patterns.txt — Pie and donut charts

Axes & Scaling

• pe-multiaxis-architecture.txt — Multi-axis setup
• pe-axis-formatting.txt — Axis labels, gridlines, formatting
• pe-mixing-methods-xaxis.txt — Mixed plots, custom scales
• pe-workingaxis-dependent-properties.txt — Per-axis property list
• pe-datetime-handling.txt — Date/time axes
• pe-specificplotmode.txt — Specific plot mode overlays

Annotations & Labels

• pe-annotations.txt — Line and axis annotations
• pe-graph-annotations.txt — Graph-area annotations
• pe-3d-graph-annotations.txt — 3D graph annotations
• pe-table-annotations.txt — Table annotations
• pe-quick-annotations.txt — Quick/temporary annotations
• pe-pointlabelsII.txt — Multi-row X-axis labels
• pe-legends.txt — Legend configuration
• pe-pointcolors.txt — Per-point color control

Interaction & Events

• pe-events-interaction.txt — Event handling patterns
• pe-hotspots.txt — Clickable chart regions
• pe-cursor-tooltip.txt — Cursor tracking and tooltips
• pe-zoom.txt — Zoom and scroll

Appearance & Output

• pe-styling-appearance.txt — Colors, fonts, themes
• pe-printing.txt — Printing and image export
• pe-realtime-patterns.txt — Streaming and real-time

支持的平台

ProEssentials 支持 C# .NET 8.0（WinForms 和 WPF）、VB.NET、MFC C++、Embarcadero Delphi、C++ Builder VCL 和 Excel/Access OCX 开发。部署需要一个原生 DLL（PEGRP64H.DLL）与您的应用程序一起。.NET 包装器程序集可作为本地 NuGet 包或直接程序集引用使用。建议使用 ProEssentials x64 程序集以获得最佳性能。