Files
XericUIActionVessel/Runtime/XChart/Space/ChartToolSpace.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

157 lines
7.5 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 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();
}
}
}