XChart 图表框架落地(P0–P17):格线单一作者、面板一行状态、矢量场

此前整个 XChart 特性一直没有提交(分期 P0–P12 的代码与素材都还在工作区里)。这一批一并入库,
并含本轮 P13–P17 的改动(规范 Documentation/XChart-RenderFramework.md 新增 §22–§25):

- P13:格线只剩一个作者——线框工具不再有"画格线 / 发布格线插槽"的代码路径;BG Cube Grid(原 MeshBg)
  是唯一作者,且"画上去的线=发布给轴线的那份比例数组";插槽板新增 Unpublish(说得出"这里不再有线",
  否则掩码筛掉的面会把上一轮的值留着被消费者吸走);渲染参数搬进元素表
  (DeclareDefaultElements / AddDefaultElement + XChartElementTable 按类型去重,只在第一次读到表时补);
  图上「立方体外观」那组字段删除、公共属性转发到元素表;面板逐行点名脚本注册的工具。
- P14 / P15:数据窗口文案收敛(行末 `-`、标题 `X [0]`、长说明退回 tooltip、范围页三行不再被压扁);
  元素块收成一行状态 `▼ 名称 √ R… D… [↑][↓][-]`;**注册序由类型定死、只显示不给输入控件,
  绘制序与元素在表里的位置绑定**(§24.5,他 2026-10-25 澄清);默认元素让删也让关;
  EnsureSpace 改成每次重建后都跑(删掉"空间"不再等于整张图空掉)。
- P17:矢量场——维数不够时不再静默不画(元素配置报需求,面板与报表同时印"需求/现有");
  相对/绝对两种读法收进纯算术 XChartVectorFieldMath;连续绘制(互斥显示把"相对/绝对"藏起来);
  颜色维(色相走 0..256 色环,饱和/明度/不透明 0..1,不透明度不算硬需求);新增螺旋矢量场测试数据。
  数据口径按他澄清修正为:前三维=坐标、一支箭头=相邻两条记录、第 4~7 维是颜色(§25、CHANGELOG 修正行)。

判据:编译门三臂 + 3 支对照绿;离线探针 436 项 0 失败;p4_control 55 支臂各红在自己点名的断言上;
p2_control / pool_family / generator_gate / hierarchy_gate 在同一棵交付树上复跑。
(证据脚本与日志在包外的 .ximage-gate/,未入本仓库。)
This commit is contained in:
2026-10-25 20:21:28 +08:00
parent 216d157472
commit c51ab7a3c8
105 changed files with 13062 additions and 812 deletions
+188
View File
@@ -0,0 +1,188 @@
using System;
namespace XericUI.XChart
{
/// <summary>可向数据源索取的聚合量</summary>
public enum XChartAggregateKind
{
Count,
First,
Last,
Minimum,
Maximum,
Sum,
Mean,
Rms,
Median,
}
/// <summary>聚合量集合(可按位组合,一次扫描一并算出)</summary>
[Flags]
public enum XChartAggregateMask
{
None = 0,
Count = 1 << 0,
First = 1 << 1,
Last = 1 << 2,
Minimum = 1 << 3,
Maximum = 1 << 4,
Sum = 1 << 5,
Mean = 1 << 6,
Rms = 1 << 7,
Median = 1 << 8,
/// <summary>数据范围(轴线自动缩放最常用的两个)</summary>
Range = Minimum | Maximum,
/// <summary>默认集合</summary>
Default = Count | Minimum | Maximum,
All = Count | First | Last | Minimum | Maximum | Sum | Mean | Rms | Median,
}
/// <summary>
/// 聚合结果。<see cref="Computed"/> 标明哪些字段真的被算过(其余字段无意义)。
/// </summary>
public struct XChartAggregates
{
public XChartAggregateMask Computed;
public int Count;
public double First;
public double Last;
public double Minimum;
public double Maximum;
public double Sum;
public double Mean;
public double Rms;
public double Median;
/// <summary>是否算过某项</summary>
public bool Has(XChartAggregateKind kind) => (Computed & ToMask(kind)) != 0;
/// <summary>数据范围(需算过 Minimum/Maximum)</summary>
public double Range => Maximum - Minimum;
/// <summary>取某项,没算过则返回 fallback</summary>
public double Get(XChartAggregateKind kind, double fallback)
{
switch (kind)
{
case XChartAggregateKind.Count: return Has(kind) ? Count : fallback;
case XChartAggregateKind.First: return Has(kind) ? First : fallback;
case XChartAggregateKind.Last: return Has(kind) ? Last : fallback;
case XChartAggregateKind.Minimum: return Has(kind) ? Minimum : fallback;
case XChartAggregateKind.Maximum: return Has(kind) ? Maximum : fallback;
case XChartAggregateKind.Sum: return Has(kind) ? Sum : fallback;
case XChartAggregateKind.Mean: return Has(kind) ? Mean : fallback;
case XChartAggregateKind.Rms: return Has(kind) ? Rms : fallback;
case XChartAggregateKind.Median: return Has(kind) ? Median : fallback;
default: return fallback;
}
}
public static XChartAggregateMask ToMask(XChartAggregateKind kind) => (XChartAggregateMask)(1 << (int)kind);
/// <summary>把单项结果并进结果集</summary>
public void Set(XChartAggregateKind kind, double value)
{
switch (kind)
{
case XChartAggregateKind.Count: Count = (int)value; break;
case XChartAggregateKind.First: First = value; break;
case XChartAggregateKind.Last: Last = value; break;
case XChartAggregateKind.Minimum: Minimum = value; break;
case XChartAggregateKind.Maximum: Maximum = value; break;
case XChartAggregateKind.Sum: Sum = value; break;
case XChartAggregateKind.Mean: Mean = value; break;
case XChartAggregateKind.Rms: Rms = value; break;
case XChartAggregateKind.Median: Median = value; break;
}
Computed |= ToMask(kind);
}
}
/// <summary>
/// 范围游标(虚拟指针):按时间窗在某一维上顺序读取,<b>不暴露底层存储</b>。
///
/// <para>它是为"以后换成桶结构 / 环形缓冲 / 分层预聚合"预留的把手:调用方只认
/// "打开一个范围、逐个 MoveNext",底层是数组直通、桶、还是 ring,都换得来。
/// 默认实现(<see cref="XChartDataModel"/> 直通)就是按下标走记录表。</para>
/// </summary>
public struct XChartRangeCursor
{
internal IXChartDataSource Source;
internal int Dimension;
internal int EndExclusive;
/// <summary>当前记录下标;开始时等于范围的起点</summary>
public int Index;
/// <summary>游标是否还有当前位置</summary>
public bool IsValid => Source != null && Index >= 0 && Index < EndExclusive;
/// <summary>当前记录的时间戳</summary>
public double Time => Source != null ? Source.GetTimeAt(Index) : double.NaN;
/// <summary>当前记录的数值(打开游标时指定的维度)</summary>
public double Value => Source != null ? Source.GetValueAt(Index, Dimension) : double.NaN;
/// <summary>前进一格;返回新位置是否有效</summary>
public bool MoveNext()
{
Index++;
return IsValid;
}
/// <summary>范围内剩余记录数(含当前)</summary>
public int Remaining => Source == null ? 0 : Math.Max(0, EndExclusive - Index);
}
/// <summary>
/// 图表数据访问的<b>唯一中转口</b>。
///
/// <para><b>为什么要有它</b>:元素(网格背景 / 轴线 / 数据图元)不该直接摸记录数组。
/// 一旦它们只认这个接口,"数据怎么存"就变成可替换的实现细节——今天是数组直通,
/// 明天可以是一个包着环形缓冲 + 桶统计的实现(<see cref="XChartTimeSeriesData"/> 已经
/// 具备那套能力),元素一行都不用改。</para>
///
/// <para><b>版本号是脏判定的统一依据</b>:任何写入都会让 <see cref="Version"/> 递增,
/// 需要缓存的元素只需比对这个号,不要再自己发明"成员变了吗"这类判据。</para>
/// </summary>
public interface IXChartDataSource
{
/// <summary>数据版本号:每次写入递增</summary>
long Version { get; }
/// <summary>数值维度数量</summary>
int NumericDimensionCount { get; }
/// <summary>是否有数据</summary>
bool HasData { get; }
/// <summary>记录条数</summary>
int RecordCount { get; }
/// <summary>本实现能直接给出的聚合集合(其余可现算,或声明不支持)</summary>
XChartAggregateMask SupportedAggregates { get; }
/// <summary>
/// 取某一维的聚合量。默认实现一次扫描算出 Count/First/Last/Min/Max/Sum/Rms,
/// 中位数另需排序(桶内样本数小,直接排序即可)。
/// </summary>
bool TryGetAggregates(int dimension, XChartAggregateMask mask, out XChartAggregates aggregates);
/// <summary>取某条记录的时间戳(直通实现不需要映射,直接读)</summary>
double GetTimeAt(int recordIndex);
/// <summary>取某条记录某维的数值</summary>
double GetValueAt(int recordIndex, int dimension);
/// <summary>
/// 取某一维的作者元数据(显示名 / 格式化串 / 维度类型)。轴线的"数据直驱标签"
/// 用它拿默认格式,标签模式用它拿显示名。下标越界返回 false(不抛,渲染路径里调用)。
/// </summary>
bool TryGetDimension(int dimension, out XChartDimensionDefinition definition);
/// <summary>按时间窗打开一个范围游标(虚拟指针)</summary>
XChartRangeCursor OpenRange(int dimension, double fromTime, double toTime);
}
}