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
+156
View File
@@ -0,0 +1,156 @@
using UnityEngine;
using XericUI.Core;
using XericUI.XChart.Mesh;
namespace XericUI.XChart.Space
{
/// <summary>
/// 空间工具(<b>数据源工具</b>):一张图里<b>唯一</b>的"立方体局部空间 → 图表局部像素"权威。
///
/// <para><b>为什么要有它</b>:背景网格、线框、散点、轴线以前各算各的投影——同一份 pitch/yaw
/// 在两个类里各存一份、各推一遍,点就落不进盒子里。本工具把基变换收在一处,
/// 所有元素只问它要矩阵和面帧:<c>投影 = 基变换 ∘ 工具变换</c>,
/// 于是"点落在背景里"是结构保证,不是靠两边数值凑巧一致。</para>
///
/// <para><b>两档出口</b>:</para>
/// <list type="bullet">
/// <item><see cref="Compose"/>:基矩阵 × 工具矩阵,得到该工具用的仿射矩阵,
/// 交给 <see cref="XChartCubeGeometry.Project(Matrix4x4,float,Vector2,Vector3)"/> /
/// <see cref="XChartCubeGeometry.BuildFaceFrames"/> 复用同一套投影与面帧推导。</item>
/// <item><see cref="CubeToPixel"/> / <see cref="Offset"/>:需要自己换算长度或偏移的元素(轴线的
/// 刻度长度、标签的让位距离)用它们,不要各自再算一遍 scale。</item>
/// </list>
///
/// <para><b>版本号</b>:<see cref="ProjectionVersion"/> 在标记脏的那一刻递增,
/// 消费者拿它比对"要不要重新投影",不需要谁去清脏标记。</para>
/// </summary>
[AddComponentMenu(XericRegistrationPaths.Chart + "/Space/Space Tool")]
public sealed class ChartToolSpace : XChartToolBase
{
/// <summary>图表自带的空间工具在管理器里的名字</summary>
public const string DefaultToolName = "Space";
/// <summary>空间是"投影权威":投影矩阵没算出来,谁也算不了 ⇒ 归定义组,最先跑(规范 §11.4)</summary>
public override XChartToolCategory Category => XChartToolCategory.Definition;
// ── 基变换 ────────────────────────────────────────────────
/// <summary>图表级姿态(四元数,唯一的旋转权威量)</summary>
public Quaternion Rotation { get; set; } =
XChartCubeView.RotationOf(XChartCubeViewPreset.Isometric);
/// <summary>半边长(UI 像素)</summary>
public float HalfEdge { get; set; } = 120f;
/// <summary>尺寸口径(默认半边长:尺度不随旋转变化)</summary>
public XChartCubeSizeMode SizeMode { get; set; } = XChartCubeSizeMode.HalfEdgeLength;
/// <summary>立方体中心在图表局部像素里的偏移</summary>
public Vector2 CenterOffset { get; set; }
// ── 派生状态 ──────────────────────────────────────────────
private Matrix4x4 m_Base;
private float m_Scale = 1f;
private Vector2 m_Offset;
private bool m_ProjectionDirty = true;
/// <summary>投影版本号(标记脏时递增)</summary>
public int ProjectionVersion { get; private set; }
/// <summary>基变换矩阵(纯旋转)</summary>
public Matrix4x4 BaseMatrix { get { EnsureProjection(); return m_Base; } }
/// <summary>立方体单位 → 像素的缩放(半边长口径下就等于 <see cref="HalfEdge"/>)</summary>
public float CubeToPixel { get { EnsureProjection(); return m_Scale; } }
/// <summary>投影后的平移(图表局部像素)</summary>
public Vector2 Offset { get { EnsureProjection(); return m_Offset; } }
public void MarkProjectionDirty()
{
m_ProjectionDirty = true;
ProjectionVersion++;
}
private void EnsureProjection()
{
if (!m_ProjectionDirty) return;
m_ProjectionDirty = false;
m_Base = XChartCubeView.ToMatrix(Rotation);
XChartCubeView.ComputeProjection(m_Base, HalfEdge, CenterOffset, SizeMode, out m_Scale, out m_Offset);
}
// ── 出口 ──────────────────────────────────────────────────
/// <summary>基变换 ∘ 工具变换(<paramref name="tool"/> 为恒等时就只剩基矩阵)</summary>
public Matrix4x4 Compose(XChartToolTransform tool)
{
EnsureProjection();
return tool.IsIdentity ? m_Base : XChartCubeView.Compose(m_Base, tool.Build());
}
/// <summary>立方体局部点 → 图表局部像素(带工具变换)</summary>
public Vector2 Project(Vector3 cubePoint, Matrix4x4 composed)
{
EnsureProjection();
return XChartCubeGeometry.Project(composed, m_Scale, m_Offset, cubePoint);
}
/// <summary>立方体局部点 → 图表局部像素(只用基变换)</summary>
public Vector2 Project(Vector3 cubePoint)
{
EnsureProjection();
return XChartCubeGeometry.Project(m_Base, m_Scale, m_Offset, cubePoint);
}
/// <summary>深度(越大越靠近观察者),用来做画家序</summary>
public float DepthOf(Vector3 cubePoint, Matrix4x4 composed)
{
EnsureProjection();
return composed.MultiplyPoint3x4(cubePoint).z;
}
/// <summary>六个面帧(<paramref name="output"/> 长度至少 6;顺序同 <see cref="XChartCubeGeometry.CubeFace"/>)</summary>
public void BuildFaceFrames(XChartFaceFrame[] output, Matrix4x4 composed)
{
EnsureProjection();
XChartCubeGeometry.BuildFaceFrames(composed, m_Scale, m_Offset, output);
}
/// <summary>六个面帧(只用基变换)</summary>
public void BuildFaceFrames(XChartFaceFrame[] output)
{
EnsureProjection();
XChartCubeGeometry.BuildFaceFrames(m_Base, m_Scale, m_Offset, output);
}
/// <summary>某个面是否朝向观察者。注意:法线是按矩阵的线性部分转的,
/// 工具带<b>非等比缩放</b>时这只是近似(立方体场景里够用,别拿它判曲面)。</summary>
public bool IsFaceVisible(XChartCubeGeometry.CubeFace face, Matrix4x4 composed)
=> XChartCubeGeometry.IsFaceVisible(composed, face);
public bool IsFaceVisible(XChartCubeGeometry.CubeFace face)
{
EnsureProjection();
return XChartCubeGeometry.IsFaceVisible(m_Base, face);
}
// ── 数据域 → 立方体域 ─────────────────────────────────────
/// <summary>
/// 归一化数据(每维 [0,1])→ 立方体局部点([-1,1])。
/// 数据元素统一走这一条,保证"0.5 就是立方体中间"这件事只有一处定义。
/// </summary>
public static Vector3 NormalizedToCube(Vector3 zeroOne)
=> new Vector3(zeroOne.x * 2f - 1f, zeroOne.y * 2f - 1f, zeroOne.z * 2f - 1f);
protected override void OnInitialize()
{
// 空间本身不画东西:它只是别的元素的坐标系。节点仍然要建,
// 因为元素的兄弟序(= 绘制序)里得有它占的那一格
SetVisible(true);
MarkProjectionDirty();
}
}
}