Files
XericUIActionVessel/Runtime/XChart/Mesh/XChartCubeView.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

305 lines
16 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;
namespace XericUI.XChart.Mesh
{
/// <summary>
/// 立方体尺寸的两种口径。两者的差别正是"旋转时立方体会不会变小"。
/// </summary>
public enum XChartCubeSizeMode
{
/// <summary>
/// <b>半边长口径(默认)</b>:给定值是立方体<b>真实边长的一半</b>(也等于面心到中心的距离,
/// 即内切球半径)。投影缩放与旋转<b>无关</b>:怎么转,边长都是 <c>2 * halfEdge</c> 像素。
/// </summary>
HalfEdgeLength,
/// <summary>
/// <b>视口适配口径</b>:把<b>投影包围盒</b>的最长边缩放到 <c>2 * halfEdge</c> 像素,
/// 于是立方体永远刚好铺满那块矩形。代价是尺寸随旋转变化:包围盒在某屏幕轴上的半长是
/// <c>h * (|ux| + |uy| + |uz|)</c>(<c>u</c> 是该屏幕轴在立方体局部空间的像,
/// 即 <c>R^T</c> 的那一行),正对时为 <c>h</c>,某条体对角线对着该轴时最大、为 <c>√3 h</c>。
/// 同一份配置下的实际尺度因此只有设定值的 <c>1/√3 ≈ 0.577</c>(等距预设下垂直方向半长
/// <c>√(8/3) h</c>,即 <c>≈ 0.612</c> 倍)——这就是"越转越小"。
/// 需要"填满指定的矩形"时才用它。
/// </summary>
FitToViewport,
}
/// <summary>
/// 视角预设:每个值都对应<b>一个四元数</b>(见 <see cref="XChartCubeView.RotationOf"/>),不是角度分量。
/// <see cref="Manual"/> 表示不做预设覆盖,直接用配置里序列化好的那个四元数。
/// </summary>
public enum XChartCubeViewPreset
{
Manual = 0,
/// <summary>45° 正交(体对角线对着观察者),轮廓是<b>正六边形</b>,Front/Right/Top 三面可见</summary>
Isometric = 1,
/// <summary>等距视角的镜像(Front/Left/Top 可见)</summary>
IsometricMirrored = 2,
Front = 3,
Back = 4,
Right = 5,
Left = 6,
Top = 7,
Bottom = 8,
}
/// <summary>
/// 立方体视图:旋转<b>只有一个权威量——四元数</b>,尺寸<b>只有一个权威量——半边长</b>。
///
/// <para><b>为什么不再拆 pitch/yaw</b>:两轴拆分本身不算错,但它把"视角"表达成了
/// "绕世界 X 转一下、再绕世界 Y 转一下",于是任何第三个轴的姿态都拿不到(roll 被钉死为 0),
/// 而且默认值 (25, -30) 只是随手取的,既不是正交等距也不是正视,所以画面里的"矩形"总是歪的。
/// 本类把姿态收成一个四元数:预设、拖拽、代码 API 都直接给四元数,需要由角度合成时用
/// <see cref="Euler"/>(它按 <c>Rx * Ry * Rz</c> 合成,与 <c>Quaternion.Euler</c> 同一约定)。</para>
///
/// <para><b>为什么尺寸要收成半边长</b>:见 <see cref="XChartCubeSizeMode"/>。
/// 旧实现按"投影包围盒最长边"来 fit,而包围盒半长随旋转从 <c>h</c> 一路长大到 <c>√3 h</c>,
/// 立方体就必须缩小,调一次俯仰小一档、再调一次偏航又小一档,最后远小于设定的尺寸。
/// 默认口径改成与旋转无关的半边长后,尺寸这件事和视角这件事彻底解耦。</para>
///
/// <para><b>几种半径的关系</b>(半边长记作 <c>h</c>,立方体顶点在 <c>±h</c>):
/// <code>
/// 面心到中心(内切球半径) = h
/// 顶点到中心(外接球半径) = √3 h ≈ 1.7321 h
/// 等距轮廓正六边形的外接圆半径 = √(8/3) h ≈ 1.6330 h
/// 等距轮廓正六边形的内切圆半径 = √2 h ≈ 1.4142 h
/// 沿某屏幕轴的包围盒半长 = h * (|ux| + |uy| + |uz|),取值 h … √3 h
/// </code>
/// 所以"要画进一个 R 半径的圆里"时,半边长取 <c>R / √(8/3)</c>;
/// 换算函数在下面这几个 <c>*FromHalfEdge</c> / <c>HalfEdgeFrom*</c> 里。</para>
///
/// <para><b>离线可跑</b>:这里不做任何引擎内部调用(<c>Quaternion.Euler</c>、
/// <c>Quaternion.FromToRotation</c>、<c>Matrix4x4.TRS</c> 出不了 Unity),
/// 四元数由 axis-angle + Hamilton 积纯托管合成,矩阵由字段逐个拼出来。
/// 编译门里的 mono 探针会把 <see cref="ToMatrix"/> 与 <c>Matrix4x4.Rotate</c> 对拍,
/// 把 <see cref="Euler"/> 与三次 <see cref="AxisAngle"/> 的连乘对拍,
/// 并把"等距视角轮廓是正六边形""半边长口径下尺度不随旋转变化"当断言钉住。</para>
/// </summary>
public static class XChartCubeView
{
/// <summary>atan(1/√2) 的度数:体对角线对着观察者时,对角线与水平面的夹角</summary>
public const float IsometricPitchDegrees = 35.2643897f;
/// <summary>等距视角的偏航量(绝对值),符号由 <see cref="XChartCubeViewPreset"/> 决定</summary>
public const float IsometricYawDegrees = 45f;
private const float k_Sqrt3 = 1.7320508f;
private const float k_Sqrt2 = 1.41421356f;
private const float k_Sqrt8Over3 = 1.6329932f;
private const float k_MinLength = 1e-8f;
// ── 四元数合成(纯托管) ──────────────────────────────────
/// <summary>归一化后的四元数。长度过短返回单位四元数(不做除法放大噪声)</summary>
public static Quaternion Normalized(float x, float y, float z, float w)
{
float length = Mathf.Sqrt(x * x + y * y + z * z + w * w);
if (length < k_MinLength) return new Quaternion(0f, 0f, 0f, 1f);
float inv = 1f / length;
return new Quaternion(x * inv, y * inv, z * inv, w * inv);
}
/// <summary>
/// 绕任意轴的旋转(右手定则,角度制)。轴不必预先归一化。
/// <c>q = (axis * sin(θ/2), cos(θ/2))</c>
/// </summary>
public static Quaternion AxisAngle(Vector3 axis, float angleDegrees)
{
float length = Mathf.Sqrt(axis.x * axis.x + axis.y * axis.y + axis.z * axis.z);
if (length < k_MinLength) return new Quaternion(0f, 0f, 0f, 1f);
float inv = 1f / length;
float half = angleDegrees * 0.5f * Mathf.Deg2Rad;
float s = Mathf.Sin(half);
return new Quaternion(
axis.x * inv * s,
axis.y * inv * s,
axis.z * inv * s,
Mathf.Cos(half));
}
/// <summary>
/// Hamilton 积 <c>a ⊗ b</c>,按 Unity 的约定即"先施加 <paramref name="b"/>、再施加 <paramref name="a"/>"
/// (矩阵视角就是 <c>Ra * Rb</c>)。
/// 手写展开而不用引擎的 <c>operator*</c>,好让整条合成链在离线探针里也走得通。
/// </summary>
public static Quaternion Multiply(Quaternion a, Quaternion b)
{
return new Quaternion(
a.w * b.x + a.x * b.w + a.y * b.z - a.z * b.y,
a.w * b.y - a.x * b.z + a.y * b.w + a.z * b.x,
a.w * b.z + a.x * b.y - a.y * b.x + a.z * b.w,
a.w * b.w - a.x * b.x - a.y * b.y - a.z * b.z);
}
/// <summary>
/// 按 <c>Rx(xDeg) * Ry(yDeg) * Rz(zDeg)</c> 合成——与 <c>Quaternion.Euler</c> 的约定一致
/// (先绕 Z、再绕 Y、最后绕 X,都是绕<b>世界</b>轴)。
/// </summary>
public static Quaternion Euler(float xDegrees, float yDegrees, float zDegrees)
{
Quaternion rx = AxisAngle(Vector3.right, xDegrees);
Quaternion ry = AxisAngle(Vector3.up, yDegrees);
Quaternion rz = AxisAngle(Vector3.forward, zDegrees);
return Multiply(Multiply(rx, ry), rz);
}
/// <summary>把配置里的四元数收正:归一化 + 长度失效时退回单位旋转</summary>
public static Quaternion Sanitize(Quaternion q) => Normalized(q.x, q.y, q.z, q.w);
// ── 预设 ──────────────────────────────────────────────────
/// <summary>
/// 预设对应的旋转。"某面正对观察者"= 把该面的外法线转到 +Z(投影保留 X/Y、丢弃 Z,
/// 所以 <c>(R n).z == 1</c> 时该面正对观察者)。
/// </summary>
public static Quaternion RotationOf(XChartCubeViewPreset preset)
{
switch (preset)
{
case XChartCubeViewPreset.Isometric:
return Euler(IsometricPitchDegrees, -IsometricYawDegrees, 0f);
case XChartCubeViewPreset.IsometricMirrored:
return Euler(IsometricPitchDegrees, IsometricYawDegrees, 0f);
case XChartCubeViewPreset.Front:
return new Quaternion(0f, 0f, 0f, 1f);
case XChartCubeViewPreset.Back:
return AxisAngle(Vector3.up, 180f);
case XChartCubeViewPreset.Right:
return AxisAngle(Vector3.up, -90f);
case XChartCubeViewPreset.Left:
return AxisAngle(Vector3.up, 90f);
case XChartCubeViewPreset.Top:
return AxisAngle(Vector3.right, 90f);
case XChartCubeViewPreset.Bottom:
return AxisAngle(Vector3.right, -90f);
default:
return new Quaternion(0f, 0f, 0f, 1f);
}
}
// ── 旋转 -> 矩阵 ──────────────────────────────────────────
/// <summary>
/// 四元数 -> 3D 旋转矩阵(齐次形式,<c>m33 = 1</c>)。
/// 这里逐字段拼装,和 <c>Matrix4x4.Rotate</c> 是两条独立实现,探针要求它们一致。
/// 输入必须是单位四元数,所以先过一遍 <see cref="Sanitize"/>。
/// </summary>
public static Matrix4x4 ToMatrix(Quaternion q)
{
Quaternion u = Sanitize(q);
float xx = u.x * u.x, yy = u.y * u.y, zz = u.z * u.z;
float xy = u.x * u.y, xz = u.x * u.z, yz = u.y * u.z;
float wx = u.w * u.x, wy = u.w * u.y, wz = u.w * u.z;
var m = new Matrix4x4
{
m00 = 1f - 2f * (yy + zz),
m01 = 2f * (xy - wz),
m02 = 2f * (xz + wy),
m03 = 0f,
m10 = 2f * (xy + wz),
m11 = 1f - 2f * (xx + zz),
m12 = 2f * (yz - wx),
m13 = 0f,
m20 = 2f * (xz - wy),
m21 = 2f * (yz + wx),
m22 = 1f - 2f * (xx + yy),
m23 = 0f,
m30 = 0f,
m31 = 0f,
m32 = 0f,
m33 = 1f,
};
return m;
}
/// <summary>
/// 仿射复合 <c>a ∘ b</c>(矩阵意义下的 <c>a * b</c>:先施加 <paramref name="b"/>,再施加
/// <paramref name="a"/>)。只支持"线性 + 平移"这一族(最后一行恒为 0,0,0,1),
/// 所以 12 个元素就够,不用写全 4x4 乘。
/// <para>为什么不用 <c>Matrix4x4.operator*</c>:它底层是引擎内部调用,出不了 Unity,
/// 离线探针就跑不了这条链;空间层的"基变换 × 工具变换"必须能离线验。</para>
/// </summary>
public static Matrix4x4 Compose(Matrix4x4 a, Matrix4x4 b)
{
var m = new Matrix4x4
{
m00 = a.m00 * b.m00 + a.m01 * b.m10 + a.m02 * b.m20,
m01 = a.m00 * b.m01 + a.m01 * b.m11 + a.m02 * b.m21,
m02 = a.m00 * b.m02 + a.m01 * b.m12 + a.m02 * b.m22,
m03 = a.m00 * b.m03 + a.m01 * b.m13 + a.m02 * b.m23 + a.m03,
m10 = a.m10 * b.m00 + a.m11 * b.m10 + a.m12 * b.m20,
m11 = a.m10 * b.m01 + a.m11 * b.m11 + a.m12 * b.m21,
m12 = a.m10 * b.m02 + a.m11 * b.m12 + a.m12 * b.m22,
m13 = a.m10 * b.m03 + a.m11 * b.m13 + a.m12 * b.m23 + a.m13,
m20 = a.m20 * b.m00 + a.m21 * b.m10 + a.m22 * b.m20,
m21 = a.m20 * b.m01 + a.m21 * b.m11 + a.m22 * b.m21,
m22 = a.m20 * b.m02 + a.m21 * b.m12 + a.m22 * b.m22,
m23 = a.m20 * b.m03 + a.m21 * b.m13 + a.m22 * b.m23 + a.m23,
m30 = 0f, m31 = 0f, m32 = 0f, m33 = 1f,
};
return m;
}
// ── 尺寸口径 ──────────────────────────────────────────────
/// <summary>半边长 -> 外接球半径(顶点到中心)= √3 h</summary>
public static float CircumradiusFromHalfEdge(float halfEdge) => halfEdge * k_Sqrt3;
/// <summary>外接球半径 -> 半边长</summary>
public static float HalfEdgeFromCircumradius(float circumradius) => circumradius / k_Sqrt3;
/// <summary>半边长 -> 等距轮廓正六边形的外接圆半径 = √(8/3) h</summary>
public static float IsometricHexagonCircumradius(float halfEdge) => halfEdge * k_Sqrt8Over3;
/// <summary>想让轮廓正六边形内接于半径 r 的圆,半边长该给多少</summary>
public static float HalfEdgeFromHexagonCircumradius(float radius) => radius / k_Sqrt8Over3;
/// <summary>半边长 -> 等距轮廓正六边形的内切圆半径 = √2 h</summary>
public static float IsometricHexagonInradius(float halfEdge) => halfEdge * k_Sqrt2;
/// <summary>
/// 按口径算投影缩放与平移。
/// <para><see cref="XChartCubeSizeMode.HalfEdgeLength"/>:<c>scale = halfEdge</c>——
/// 立方体顶点在 ±1,所以 scale 就是半边长,与旋转无关;包围盒中心仍然对齐到
/// <paramref name="centerOffset"/>,于是转起来只是转、不会漂。</para>
/// <para><see cref="XChartCubeSizeMode.FitToViewport"/>:<c>scale</c> 让包围盒最长边等于
/// <c>2 * halfEdge</c>,铺满固定矩形但尺寸随旋转变化。</para>
/// </summary>
public static void ComputeProjection(Matrix4x4 rotation, float halfEdge, Vector2 centerOffset,
XChartCubeSizeMode mode, out float scale, out Vector2 offset)
{
XChartCubeGeometry.ComputeProjectedBounds(rotation, out Vector2 min, out Vector2 max);
Vector2 center = new Vector2((min.x + max.x) * 0.5f, (min.y + max.y) * 0.5f);
if (mode == XChartCubeSizeMode.HalfEdgeLength)
{
scale = Mathf.Max(0.001f, halfEdge);
}
else
{
float maxRange = Mathf.Max(max.x - min.x, max.y - min.y);
scale = maxRange > 0.001f ? halfEdge * 2f / maxRange : 1f;
}
offset = new Vector2(centerOffset.x - center.x * scale, centerOffset.y - center.y * scale);
}
/// <summary>四元数版入口:内部先转矩阵,调用方不必自己拿 <see cref="ToMatrix"/></summary>
public static void ComputeProjection(Quaternion rotation, float halfEdge, Vector2 centerOffset,
XChartCubeSizeMode mode, out float scale, out Vector2 offset)
{
ComputeProjection(ToMatrix(rotation), halfEdge, centerOffset, mode, out scale, out offset);
}
}
}