Files
XericUIActionVessel/Runtime/XChart/XChartDataSource.cs
T
lrss3 c51ab7a3c8 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/,未入本仓库。)
2026-10-25 20:21:28 +08:00

188 lines
7.6 KiB
C#
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
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);
}
}