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
+250 -159
View File
@@ -1,132 +1,115 @@
using UnityEngine;
using XericLibrary.Runtime.UIGraph;
using PrimitiveType = XericLibrary.Runtime.UIGraph.PrimitiveType;
using XericUI.Core;
using XericUI.XChart.Mesh;
using XericUI.XChart.Space;
namespace XericUI.XChart.Pseudo3D
{
/// <summary>
/// 散点渲染工具。
/// 散点元素:把 3D 数据点画进图的空间里。
///
/// 使用 XScatterPointRenderer 渲染 3D 散点数据在 2D 平面上的投影。
/// 数据点从 3D 立方体空间投影到 UI 坐标,每个点用一个图元表示。
/// <para><b>数据从哪儿来</b>:只认图表给的中转接口 <see cref="IXChartDataSource"/>
/// (<see cref="AutoFromData"/> 为真时按维度下标逐条取,范围用聚合量的 min/max)。
/// 元素不直接摸记录数组,所以以后要换桶/环形缓冲也不用改这里。
/// <see cref="AutoFromData"/> 为假时用脚本喂进来的 <see cref="SetCubePoints"/>(立方体单位)。</para>
///
/// <para><b>投影从哪儿来</b>:图里的 <see cref="ChartToolSpace"/>,和背景/线框/轴线<b>同一个</b>。
/// 所以"点落在盒子里"是结构保证——数据归一化到 [0,1] 再映到立方体局部 [-1,1],
/// 然后走和背景一样的 <c>基变换 ∘ 工具变换</c>。</para>
///
/// <para><b>什么时候重算</b>:数据版本号或空间版本号变了才重投影,其余帧什么都不做。</para>
///
/// 子节点结构:
/// [ChartTool_ScatterPoints]
/// [ScatterPoints]
/// └─ PointRenderer (XScatterPointRenderer)
/// </summary>
[AddComponentMenu("Xeric/XChart/Pseudo3D/Scatter Points Tool")]
[AddComponentMenu(XericRegistrationPaths.Chart + "/Pseudo3D/Scatter Points Tool")]
public class ChartToolScatterPoints : XChartToolBase
{
// ── 配置 ──────────────────────────────────────────────────
// ── 数据装配 ──────────────────────────────────────────────
/// <summary>点的大小(像素)</summary>
public float PointSize
{
get => m_PointSize;
set { m_PointSize = Mathf.Max(0.5f, value); if (IsInitialized) SyncShapeParams(); }
}
/// <summary>真=从图的数据源按维度下标读;假=用 <see cref="SetCubePoints"/> 喂的点</summary>
public bool AutoFromData { get; set; } = true;
/// <summary>三个维度在数据源里的下标(绑定:点云画哪三路数据;范围归 chart 的维度行)</summary>
public int DimensionX { get; set; }
public int DimensionY { get; set; } = 1;
public int DimensionZ { get; set; } = 2;
/// <summary>点云自己的变换(立方体单位),用来把点整体缩进盒子里或挪一角</summary>
public XChartToolTransform Transform { get; set; } = XChartToolTransform.Identity;
/// <summary>
/// 桶采样目标点数:<c>0</c> 或 ≥ 记录数=不聚合;否则把记录按桶归约成这么多个点。
/// 目的是"几万条记录也只画 N 个点",同时让每个点代表它那一段时间。
/// </summary>
public int BucketTargetPoints { get; set; }
/// <summary>桶内取哪个统计量当这个点(抽稀 First/Last 不造新值;趋势 Mean/Median;包络 Minimum/Maximum)</summary>
public XChartAggregateKind BucketReduce { get; set; } = XChartAggregateKind.Last;
// ── 外观 ──────────────────────────────────────────────────
public float PointSize { get => m_PointSize; set { m_PointSize = Mathf.Max(0.5f, value); if (IsInitialized) SyncShapeParams(); } }
private float m_PointSize = 8f;
/// <summary>图元类型</summary>
public PrimitiveType PointType
{
get => m_PointType;
set { m_PointType = value; if (IsInitialized) SyncShapeParams(); }
}
public PrimitiveType PointType { get => m_PointType; set { m_PointType = value; if (IsInitialized) SyncShapeParams(); } }
private PrimitiveType m_PointType = PrimitiveType.Polygon;
/// <summary>尺寸模式</summary>
public SizeMode SizeMode
{
get => m_SizeMode;
set { m_SizeMode = value; if (IsInitialized) SyncShapeParams(); }
}
private SizeMode m_SizeMode = SizeMode.InscribedCircle;
public SizeMode PointSizeMode { get => m_PointSizeMode; set { m_PointSizeMode = value; if (IsInitialized) SyncShapeParams(); } }
private SizeMode m_PointSizeMode = SizeMode.InscribedCircle;
/// <summary>填充颜色</summary>
public Color PointColor
{
get => m_PointColor;
set { m_PointColor = value; if (IsInitialized) SyncShapeParams(); }
}
public Color PointColor { get => m_PointColor; set { m_PointColor = value; if (IsInitialized) SyncShapeParams(); } }
private Color m_PointColor = new Color(0.33f, 0.67f, 1f, 1f);
/// <summary>中心渐变颜色</summary>
public Color CenterColor
{
get => m_CenterColor;
set { m_CenterColor = value; if (IsInitialized) SyncShapeParams(); }
}
public Color CenterColor { get => m_CenterColor; set { m_CenterColor = value; if (IsInitialized) SyncShapeParams(); } }
private Color m_CenterColor = Color.white;
/// <summary>边框颜色</summary>
public Color BorderColor
{
get => m_BorderColor;
set { m_BorderColor = value; if (IsInitialized) SyncShapeParams(); }
}
public Color BorderColor { get => m_BorderColor; set { m_BorderColor = value; if (IsInitialized) SyncShapeParams(); } }
private Color m_BorderColor = new Color(0.2f, 0.2f, 0.2f, 1f);
/// <summary>边框宽度</summary>
public float BorderThickness
{
get => m_BorderThickness;
set { m_BorderThickness = Mathf.Max(0f, value); if (IsInitialized) SyncShapeParams(); }
}
public float BorderThickness { get => m_BorderThickness; set { m_BorderThickness = Mathf.Max(0f, value); if (IsInitialized) SyncShapeParams(); } }
private float m_BorderThickness = 1f;
/// <summary>多边形边数</summary>
public int SideCount
{
get => m_SideCount;
set { m_SideCount = Mathf.Max(3, value); if (IsInitialized) SyncShapeParams(); }
}
public int SideCount { get => m_SideCount; set { m_SideCount = Mathf.Max(3, value); if (IsInitialized) SyncShapeParams(); } }
private int m_SideCount = 8;
/// <summary>倒角大小</summary>
public float ChamferSize
{
get => m_ChamferSize;
set { m_ChamferSize = Mathf.Clamp01(value); if (IsInitialized) SyncShapeParams(); }
}
private float m_ChamferSize = 0f;
public float ChamferSize { get => m_ChamferSize; set { m_ChamferSize = Mathf.Clamp01(value); if (IsInitialized) SyncShapeParams(); } }
private float m_ChamferSize;
/// <summary>图元旋转角度</summary>
public float PointAngle
{
get => m_PointAngle;
set { m_PointAngle = value; if (IsInitialized) SyncShapeParams(); }
}
private float m_PointAngle = 0f;
public float PointAngle { get => m_PointAngle; set { m_PointAngle = value; if (IsInitialized) SyncShapeParams(); } }
private float m_PointAngle;
/// <summary>是否使用颜色渐变(按数据范围)</summary>
public bool EnableColorMapping { get; set; } = false;
/// <summary>按某一维的数值做颜色渐变</summary>
public bool EnableColorMapping { get; set; }
/// <summary>颜色映射渐变起始色</summary>
public Color ColorMapMin { get; set; } = Color.blue;
/// <summary>颜色映射渐变结束色</summary>
public Color ColorMapMax { get; set; } = Color.red;
/// <summary>颜色映射轴(0=X, 1=Y, 2=Z)</summary>
public int ColorMapAxis { get; set; } = 2;
/// <summary>拿哪一维的数值做映射</summary>
public int ColorMapDimension { get; set; } = 2;
// ── 内部组件 ──────────────────────────────────────────────
// ── 内部 ──────────────────────────────────────────────────
/// <summary>散点渲染器</summary>
public XScatterPointRenderer PointRenderer { get; private set; }
/// <summary>对 CubeBg 工具的引用(用于投影)</summary>
public ChartToolCubeBg CubeBg { get; set; }
private Matrix4x4 m_Composed = Matrix4x4.identity;
// ── 数据缓存 ──────────────────────────────────────────────
private Vector3[] m_CubePoints = new Vector3[0];
/// <summary>中位数归约用的暂存:长度按记录数上限,渲染路径里不分配</summary>
private double[] m_BucketScratch;
/// <summary>本帧桶数(=-1 表示还没算过);与源记录数一起进报表——"少画了多少"要能看到</summary>
private int m_BucketCount = -1;
private int m_SourceRecords;
private Vector2[] m_Projected = new Vector2[0];
private Color[] m_PointColors;
private float[] m_ColorValues;
private Vector3[] m_NormalizedPoints = new Vector3[0];
private Vector2[] m_ProjectedPoints = new Vector2[0];
private bool m_DataDirty = true;
private int m_LastProjectionVersion = -1;
// ── 初始化 ────────────────────────────────────────────────
private bool m_PointsDirty = true;
private long m_LastDataVersion = -1;
private int m_LastSpaceVersion = -1;
protected override void OnInitialize()
{
@@ -139,17 +122,14 @@ namespace XericUI.XChart.Pseudo3D
rt.offsetMin = Vector2.zero;
rt.offsetMax = Vector2.zero;
}
SyncShapeParams();
}
// ── 形状参数同步 ──────────────────────────────────────────
private void SyncShapeParams()
{
if (PointRenderer == null) return;
PointRenderer.pointType = m_PointType;
PointRenderer.sizeMode = m_SizeMode;
PointRenderer.sizeMode = m_PointSizeMode;
PointRenderer.pointSize = m_PointSize;
PointRenderer.fillColor = m_PointColor;
PointRenderer.centerColor = m_CenterColor;
@@ -160,101 +140,212 @@ namespace XericUI.XChart.Pseudo3D
PointRenderer.chamferSegments = 4;
PointRenderer.angle = m_PointAngle;
// 如果已有数据,触发形状重建
if (m_NormalizedPoints.Length > 0)
{
PointRenderer.UpdateShapeParams();
}
if (m_CubePoints.Length > 0) PointRenderer.UpdateShapeParams();
}
// ── 数据更新 ──────────────────────────────────────────────
/// <summary>
/// 设置要渲染的 3D 点(归一化到 [-1, 1] 立方体空间)。
/// </summary>
public void SetNormalizedPoints(Vector3[] normalizedPoints)
/// <summary>脚本喂点(立方体单位,[-1,1] 就是盒子内部)。配合 <see cref="AutoFromData"/>=false 用</summary>
public void SetCubePoints(Vector3[] cubePoints)
{
m_NormalizedPoints = normalizedPoints ?? new Vector3[0];
m_ProjectedPoints = new Vector2[m_NormalizedPoints.Length];
m_DataDirty = true;
m_CubePoints = cubePoints ?? new Vector3[0];
m_Projected = new Vector2[m_CubePoints.Length];
m_PointColors = null;
m_ColorValues = null;
m_BucketCount = 0; // 脚本喂点这条路没有桶
m_SourceRecords = m_CubePoints.Length;
m_PointsDirty = true;
}
/// <summary>标记数据需要重新投影</summary>
public void MarkDataDirty()
{
m_DataDirty = true;
}
/// <summary>数据或变换变了(版本号比对才是真判据,这里只负责"再算一次")</summary>
public void MarkDataDirty() => m_PointsDirty = true;
// ── 渲染 ──────────────────────────────────────────────────
public override void OnRender()
{
base.OnRender();
if (PointRenderer == null || CubeBg == null) return;
if (m_NormalizedPoints.Length == 0) return;
if (PointRenderer == null) return;
bool projectionChanged = CubeBg.ProjectionVersion != m_LastProjectionVersion;
var space = Context?.Space;
if (space == null) return;
// 如果数据脏了或立方体投影发生了变化,重新投影所有点
if (m_DataDirty || projectionChanged)
bool spaceChanged = space.ProjectionVersion != m_LastSpaceVersion;
bool dataChanged = Data != null && Data.Version != m_LastDataVersion;
if (!m_PointsDirty && !spaceChanged && !dataChanged) return;
if (spaceChanged || dataChanged) m_PointsDirty = true;
m_LastSpaceVersion = space.ProjectionVersion;
m_LastDataVersion = Data != null ? Data.Version : -1;
m_Composed = space.Compose(Transform);
if (m_PointsDirty)
{
m_LastProjectionVersion = CubeBg.ProjectionVersion;
// 使用 CubeBg 的投影能力将 3D 点投影到 2D
for (int i = 0; i < m_NormalizedPoints.Length; i++)
{
m_ProjectedPoints[i] = CubeBg.ProjectPoint3D(m_NormalizedPoints[i]);
}
// 颜色映射
if (EnableColorMapping)
{
ApplyColorMapping();
}
// 批量更新到渲染器
if (EnableColorMapping && m_PointColors != null)
{
PointRenderer.SetPoints(m_ProjectedPoints, m_PointColors);
}
else
{
PointRenderer.SetPoints(m_ProjectedPoints);
}
m_DataDirty = false;
if (AutoFromData) BuildPointsFromDataSource(space);
RebuildProjection(space);
m_PointsDirty = false;
}
if (m_Projected.Length == 0)
{
PointRenderer.ClearAll();
return;
}
if (EnableColorMapping && m_PointColors != null) PointRenderer.SetPoints(m_Projected, m_PointColors);
else PointRenderer.SetPoints(m_Projected);
}
// ── 颜色映射 ──────────────────────────────────────────────
/// <summary>立方体单位点 → 图表局部像素</summary>
private void RebuildProjection(ChartToolSpace space)
{
if (m_Projected == null || m_Projected.Length != m_CubePoints.Length)
m_Projected = new Vector2[m_CubePoints.Length];
private Color[] m_PointColors;
for (int i = 0; i < m_CubePoints.Length; i++)
m_Projected[i] = space.Project(m_CubePoints[i], m_Composed);
if (EnableColorMapping) ApplyColorMapping();
}
/// <summary>
/// 从数据源逐条取值,按每维范围归一化到 [0,1],再映到立方体局部 [-1,1]。
/// 范围优先用配置里给的手动范围,没给就用该维的聚合 min/max。
/// </summary>
private void BuildPointsFromDataSource(ChartToolSpace space)
{
var source = Data;
if (source == null || !source.HasData)
{
ClearPoints();
return;
}
int count = source.RecordCount;
// 桶采样:0 或 ≥ 记录数=不聚合(桶数就是记录数,行为与以前完全一致)
int buckets = XChartBucketMath.BucketCount(count, BucketTargetPoints);
m_BucketCount = buckets;
m_SourceRecords = count;
if (m_CubePoints.Length < buckets)
{
m_CubePoints = new Vector3[buckets];
m_Projected = new Vector2[buckets];
}
if (EnableColorMapping && (m_PointColors == null || m_PointColors.Length < buckets))
m_PointColors = new Color[buckets];
if (EnableColorMapping && (m_ColorValues == null || m_ColorValues.Length < buckets))
m_ColorValues = new float[buckets];
if (BucketReduce == XChartAggregateKind.Median && (m_BucketScratch == null || m_BucketScratch.Length < count))
m_BucketScratch = new double[count];
double minX, maxX, minY, maxY, minZ, maxZ;
ResolveRange(DimensionX, out minX, out maxX);
ResolveRange(DimensionY, out minY, out maxY);
ResolveRange(DimensionZ, out minZ, out maxZ);
double colorMin, colorMax;
ResolveRange(ColorMapDimension, out colorMin, out colorMax);
int written = 0;
for (int b = 0; b < buckets; b++)
{
int first, end;
if (!XChartBucketMath.TryBucketRange(count, b, buckets, out first, out end)) continue;
double x, y, z;
if (!XChartBucketMath.TryReduce(source, DimensionX, first, end, BucketReduce, m_BucketScratch, out x)
|| !XChartBucketMath.TryReduce(source, DimensionY, first, end, BucketReduce, m_BucketScratch, out y)
|| !XChartBucketMath.TryReduce(source, DimensionZ, first, end, BucketReduce, m_BucketScratch, out z))
{
// 整桶坏值:这个桶不画,也不拿别的桶的值顶替(那会造出一个不在数据里的点)
continue;
}
m_CubePoints[written] = ChartToolSpace.NormalizedToCube(new Vector3(
Normalize(x, minX, maxX), Normalize(y, minY, maxY), Normalize(z, minZ, maxZ)));
if (EnableColorMapping)
{
double color;
if (!XChartBucketMath.TryReduce(source, ColorMapDimension, first, end, BucketReduce, m_BucketScratch, out color))
continue;
m_ColorValues[written] = Normalize(color, colorMin, colorMax);
}
written++;
}
if (written != m_CubePoints.Length) TrimPoints(written);
}
private void ClearPoints()
{
m_CubePoints = new Vector3[0];
m_Projected = new Vector2[0];
m_PointColors = null;
m_ColorValues = null;
m_BucketCount = 0;
m_SourceRecords = 0;
}
/// <summary>
/// 只保留前 <paramref name="count"/> 个点:渲染器<b>按数组长度</b>提交,
/// 不裁掉尾巴就会画出一批"上一轮的旧点"。
/// </summary>
private void TrimPoints(int count)
{
System.Array.Resize(ref m_CubePoints, count);
System.Array.Resize(ref m_Projected, count);
if (m_PointColors != null) System.Array.Resize(ref m_PointColors, count);
if (m_ColorValues != null) System.Array.Resize(ref m_ColorValues, count);
}
/// <summary>
/// 显示范围只问上下文要(覆盖优先、否则该维聚合;规则在 <see cref="XChartDomainMath"/>)。
/// <b>范围本身归 chart 的维度行</b>(数据板块),元素只说要哪一维——
/// 元素自己再存一份范围就是"点和轴对不上"的来路。
/// </summary>
private void ResolveRange(int dimension, out double min, out double max)
{
var context = Context;
if (context != null && context.TryResolveDomain(dimension, out min, out max)) return;
min = 0.0;
max = 1.0;
}
private static float Normalize(double value, double min, double max)
{
double span = max - min;
if (span <= 0.0) return 0.5f;
return Mathf.Clamp01((float)((value - min) / span));
}
private void ApplyColorMapping()
{
if (m_NormalizedPoints.Length == 0) return;
if (m_PointColors == null || m_PointColors.Length != m_NormalizedPoints.Length)
m_PointColors = new Color[m_NormalizedPoints.Length];
for (int i = 0; i < m_NormalizedPoints.Length; i++)
{
float value = m_NormalizedPoints[i][ColorMapAxis];
// 从 [-1, 1] 映射到 [0, 1]
float t = Mathf.Clamp01((value + 1f) * 0.5f);
m_PointColors[i] = Color.Lerp(ColorMapMin, ColorMapMax, t);
}
if (m_ColorValues == null || m_PointColors == null) return;
for (int i = 0; i < m_PointColors.Length && i < m_ColorValues.Length; i++)
m_PointColors[i] = Color.Lerp(ColorMapMin, ColorMapMax, m_ColorValues[i]);
}
// ── 清理 ──────────────────────────────────────────────────
protected override void OnDispose()
{
PointRenderer = null;
CubeBg = null;
m_NormalizedPoints = null;
m_ProjectedPoints = null;
m_CubePoints = null;
m_Projected = null;
m_PointColors = null;
m_ColorValues = null;
}
#if UNITY_EDITOR
/// <summary>报表里点名这个组件这一帧提交了多少顶点——按点数长网格的元素靠它自证没撞 65535</summary>
internal override void AppendDebugLine(System.Text.StringBuilder sb)
{
base.AppendDebugLine(sb);
sb.Append(" points=").Append(m_CubePoints != null ? m_CubePoints.Length : 0)
.Append(" pointVerts=").Append(PointRenderer != null ? PointRenderer.LiveVertexCount : 0)
// 桶采样读数:画了几个点、源有多少条、取的是哪个统计量——"少画了多少"必须能看到
.Append(" buckets=").Append(m_BucketCount)
.Append(" records=").Append(m_SourceRecords)
.Append(" reduce=").Append(BucketReduce);
}
#endif
}
}