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

388 lines
19 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;
using UnityEngine;
namespace XericUI.XChart.Mesh
{
/// <summary>
/// 一片端面在 <b>2D</b> 上的像:中心 + 盘内一对基向量(已投影、<b>已乘半径</b>)。
///
/// <para>正交投影是<b>仿射</b>的,所以 3D 圆盘的像正好是"把盘内基向量的像当半轴"的椭圆:
/// <c>p(θ) = 中心 + U·cosθ + V·sinθ</c>。<b>只需投影中心与两个基各一次</b>,
/// 不必对盘上每点做 3D 投影——这就是"投影从 2D 算起"(2026-10-23 他的要求)。</para>
/// </summary>
public struct XChartCylinderDisc2D
{
public Vector2 Center;
/// <summary>盘内第一根半轴(已投影、已乘半径)</summary>
public Vector2 U;
/// <summary>盘内第二根半轴(已投影、已乘半径)</summary>
public Vector2 V;
public Vector2 PointAt(float angle)
{
return Center + U * Mathf.Cos(angle) + V * Mathf.Sin(angle);
}
/// <summary>第 <paramref name="index"/> 个采样点(角度均匀一圈)</summary>
public Vector2 PointAtStep(int index, int count)
{
if (count <= 0) return Center;
return PointAt(6.2831855f * index / count);
}
/// <summary>椭圆参数式的导数 <c>p'(θ) = -U·sinθ + V·cosθ</c>(贝塞尔控制点要用)</summary>
public Vector2 TangentAt(float angle)
{
float c = Mathf.Cos(angle);
float s = Mathf.Sin(angle);
return new Vector2(-U.x * s + V.x * c, -U.y * s + V.y * c);
}
}
/// <summary>
/// 圆柱的纯几何:<b>不碰 Unity 对象</b>,所以离线 mono 探针能直接验"外轮廓是不是两片椭圆的凸包"
/// "桥接点是否落在垂直于桥接方向的极值点上"这类断言。
///
/// <para><b>为什么外轮廓=凸包</b>:扫掠体的可见轮廓就是两个端面点集的<b>凸包</b>——
/// 对凸截面这是精确解,而且平行、斜置、两端不同法线、两端不同心都是同一套代码,
/// 不需要为"斜圆柱"再写一条切线公式。他要的那两条"过圆心的长轴方向连着外边框"的桥接线
/// 就是凸包自动给出的那两段。</para>
///
/// <para><b>母线只在显式要求时才画</b>:轮廓只画包边;"把两端顶点全连起来"那种透视线框
/// 是可选元素(<c>GeneratrixCount</c>),不再是侧面填充的实现方式。</para>
/// </summary>
public static class XChartCylinderGeometry
{
/// <summary>
/// 取与 <paramref name="normal"/> 垂直的一对单位向量。辅助轴按"离轴最远的那根世界轴"选,
/// 这样叉积不会退化(法线与某世界轴平行时那个叉积接近 0)。
/// </summary>
public static bool TryOrthogonalBasis(Vector3 normal, out Vector3 u, out Vector3 v)
{
u = Vector3.zero;
v = Vector3.zero;
float length = normal.magnitude;
if (length < 1e-6f) return false;
Vector3 n = normal / length;
Vector3 auxiliary = Mathf.Abs(n.y) < 0.9f ? Vector3.up : Vector3.right;
u = Vector3.Cross(n, auxiliary);
float uLength = u.magnitude;
if (uLength < 1e-6f) return false;
u = u / uLength;
v = Vector3.Cross(n, u);
return true;
}
/// <summary>
/// 端面盘 → 2D。只投影中心与两根基(基向量按 <paramref name="pixelsPerUnit"/> 缩放,
/// 半径并进基向量里),所以调用方拿到的是"椭圆的半轴"而不是 3D 点集。
/// </summary>
public static bool TryProjectDisc(Vector2 centerPixels, Vector2 uPixels, Vector2 vPixels,
float radius, out XChartCylinderDisc2D disc)
{
disc = default(XChartCylinderDisc2D);
if (radius <= 0f) return false;
disc.Center = centerPixels;
disc.U = uPixels * radius;
disc.V = vPixels * radius;
return disc.U.sqrMagnitude > 1e-12f || disc.V.sqrMagnitude > 1e-12f;
}
/// <summary>
/// 凸包(Andrew monotone chain),返回包上点数并写进 <paramref name="output"/>。
/// <b><paramref name="points"/> 会被就地排序</b>(它同时充当 scratch,避免每帧分配)。
/// <para><b>容量</b>:两条链各自最多 push 一次每个输入点 ⇒ 写入下标最大到 <c>2×count−3</c>,
/// 所以 <paramref name="output"/> 要能装下 <b>2×count</b> 个点。这不是留白:写成"≥count"
/// 在"输入点几乎全在包上"时会越界(我写的一支变异臂就是这么把它照出来的)。</para>
/// </summary>
public static int ConvexHull(Vector2[] points, int count, Vector2[] output)
{
if (points == null || output == null) throw new ArgumentNullException(nameof(points));
if (output.Length < count * 2) throw new ArgumentException("output 至少要能装下 2×count 个点");
if (count <= 0) return 0;
if (count < 3)
{
int copy = Math.Min(count, output.Length);
for (int i = 0; i < copy; i++) output[i] = points[i];
return copy;
}
SortByXThenY(points, count);
int total = 0;
// 下凸链:从左到右;上凸链:从右到左。两链拼起来就是凸包(逆时针)
for (int i = 0; i < count; i++)
{
while (total >= 2 && Cross(output[total - 2], output[total - 1], points[i]) <= 0f) total--;
output[total++] = points[i];
}
int lower = total + 1;
for (int i = count - 2; i >= 0; i--)
{
while (total >= lower && Cross(output[total - 2], output[total - 1], points[i]) <= 0f) total--;
output[total++] = points[i];
}
return total - 1; // 首点重复了一次
}
/// <summary>
/// 外轮廓=两片端面椭圆点集的凸包。<c>scratch</c> 装采样点(长度 ≥ 2×<paramref name="segmentCount"/>),
/// <c>output</c> 按 <see cref="ConvexHull"/> 的容量口径要能装下 <b>2×采样数</b>(长度 ≥ 4×<paramref name="segmentCount"/>)。
/// </summary>
public static int BuildOutline(in XChartCylinderDisc2D first, in XChartCylinderDisc2D second,
int segmentCount, Vector2[] scratch, Vector2[] output)
{
if (scratch == null || output == null) throw new ArgumentNullException(nameof(scratch));
int samples = segmentCount * 2;
if (scratch.Length < samples || output.Length < samples * 2)
throw new ArgumentException("scratch 要装下两片椭圆的采样点,output 要装下 2×采样数");
float step = 6.2831855f / segmentCount;
for (int i = 0; i < segmentCount; i++)
{
float angle = i * step;
scratch[i] = first.PointAt(angle);
scratch[segmentCount + i] = second.PointAt(angle);
}
return ConvexHull(scratch, segmentCount * 2, output);
}
/// <summary>
/// 两片端面的法线:显式给了就用显式;没给则<b>两端都用同一条轴、同向</b>。
///
/// <para><b>为什么不是"各自朝另一端"</b>:`TryOrthogonalBasis(-n)` 会给出 <c>u' = -u</c>
/// (叉积对第一个参数反号),于是两片的采样角是<b>镜像</b>的——同一个采样下标落在两片上的
/// 方向不一致,可选元素里"两端对应点相连"的母线就会拧成 X 形,端面十字两端也是镜像的
/// (他 2026-10-23 现场看出来的"两个端面是旋转了吗,它的连接顺序错了")。
/// 同向法线让两片参数化完全一致,采样下标 i 在两片上就是同一个 3D 方向。</para>
/// </summary>
public static void ResolveNormals(Vector3 explicitStart, Vector3 explicitEnd,
Vector3 start, Vector3 end, out Vector3 startNormal, out Vector3 endNormal)
{
Vector3 axis = end - start;
if (axis.sqrMagnitude < 1e-8f) axis = Vector3.forward;
startNormal = explicitStart.sqrMagnitude > 1e-8f ? explicitStart : axis;
endNormal = explicitEnd.sqrMagnitude > 1e-8f ? explicitEnd : axis;
}
/// <summary>多边形有向面积(逆时针为正)。探针用它比"凸包面积 ≥ 单个椭圆面积"。</summary>
public static float SignedArea(Vector2[] polygon, int count)
{
if (polygon == null || count < 3) return 0f;
float twice = 0f;
for (int i = 0; i < count; i++)
{
Vector2 a = polygon[i];
Vector2 b = polygon[(i + 1) % count];
twice += a.x * b.y - b.x * a.y;
}
return twice * 0.5f;
}
/// <summary>
/// 椭圆上"带滚转信息"的四个点:+U 方向是 right、+V 是 top、-U 是 left、-V 是 bottom
/// (<c>right - left = 2U</c>、<c>top - bottom = 2V</c>,这样十字的两臂方向就是盘自己的两根基)。
/// 端面十字用它而不是用椭圆的长短轴:长短轴会随观察方向自己转、把滚转吃掉,
/// 而这四个点就是<b>实际渲染用的那几个顶点</b>,所以十字永远与实际端面对得上。
/// </summary>
public static void CrossPoints(in XChartCylinderDisc2D disc, int segmentCount,
out Vector2 left, out Vector2 top, out Vector2 right, out Vector2 bottom)
{
int quarter = Math.Max(1, segmentCount / 4);
right = disc.PointAtStep(0, segmentCount);
top = disc.PointAtStep(quarter, segmentCount);
left = disc.PointAtStep(quarter * 2, segmentCount);
bottom = disc.PointAtStep(quarter * 3, segmentCount);
}
private static float Cross(Vector2 origin, Vector2 a, Vector2 b)
{
return (a.x - origin.x) * (b.y - origin.y) - (a.y - origin.y) * (b.x - origin.x);
}
/// <summary>
/// 反解椭圆参数:<c>p = C + U·cosθ + V·sinθ</c> ⇒ 解 2×2 线性方程得 (cosθ, sinθ),
/// 再按 <c>cos²+sin² ≈ 1</c> 判这点是否真的落在这片椭圆上。凸包分组(弧段 vs 桥接段)靠它。
/// </summary>
public static bool TryParameterOf(in XChartCylinderDisc2D disc, Vector2 point, out float angle)
{
angle = 0f;
float det = disc.U.x * disc.V.y - disc.U.y * disc.V.x;
if (Mathf.Abs(det) < 1e-9f) return false; // 半轴退化(端面看到侧刃)⇒ 参数不唯一
Vector2 d = point - disc.Center;
float cos = (d.x * disc.V.y - d.y * disc.V.x) / det;
float sin = (disc.U.x * d.y - disc.U.y * d.x) / det;
if (Mathf.Abs(cos * cos + sin * sin - 1f) > 1e-3f) return false;
angle = Mathf.Atan2(sin, cos);
return true;
}
/// <summary>把一段扫过的角整理成"朝指定方向"的弧长:先折到 (-π, π],再按方向补一圈。</summary>
public static float SweepToDirection(float sweep, int direction)
{
const float twoPi = 6.2831855f;
sweep = Mathf.Repeat(sweep + 3.1415927f, twoPi) - 3.1415927f;
if (direction > 0 && sweep < 0f) sweep += twoPi;
if (direction < 0 && sweep > 0f) sweep -= twoPi;
return sweep;
}
/// <summary>按"最短路"定转向:折到 (-π, π] 后为正就 +1,否则 -1(弧段的转向靠它推断)。</summary>
public static int ShortestDirection(float sweep)
{
float wrapped = Mathf.Repeat(sweep + 3.1415927f, 6.2831855f) - 3.1415927f;
return wrapped > 0f ? 1 : -1;
}
/// <summary>
/// 一段弧的<b>补弧</b>:起点接在它的终点、<b>同方向</b>走完剩下的那一圈(扫过 <c>2π-|sweep|</c>)。
/// <para><b>不是"反过来走"</b>——这是它最容易写错的地方:反向走会原路覆盖同一段弧(半圆时尤其明显,
/// 反着走一遍正好还是那半个圆),于是端面环又画回包边那条线上(他 2026-10-23 报的"补成外半环")。
/// 补弧与可见弧合起来才是整圈,所以两者<b>同号</b>、绝对值和 = 2π。</para>
/// </summary>
public static float ComplementSweep(float sweep)
{
const float twoPi = 6.2831855f;
if (sweep > 0f) return twoPi - sweep;
if (sweep < 0f) return -twoPi - sweep;
return twoPi;
}
/// <summary>一段椭圆弧要拆成几节三次贝塞尔(每节 ≤ 90°,与圆的贝塞尔逼近同口径)</summary>
public static int ArcPieceCount(float sweep)
{
float magnitude = Mathf.Abs(sweep);
if (magnitude < 1e-6f) return 0;
return Mathf.Max(1, Mathf.CeilToInt(magnitude / 1.5707964f));
}
/// <summary>
/// 写出一节椭圆弧的三次贝塞尔控制点(4 个,顺序 P0/P1/P2/P3)。
/// 系数 <c>k = 4/3·tan(Δ/4)</c> 是"圆弧 → 三次贝塞尔"的经典值。<b>椭圆是圆的仿射像</b>,
/// 而贝塞尔控制点随仿射变换同样变换,所以同一个 k 对椭圆弧一样成立——
/// 我只算控制点,<b>细分交给曲线渲染器</b>(他 2026-10-23 点名的
/// <c>Generation/Curve</c> 那套,它的结构里就是贝塞尔细分)。
/// </summary>
public static void BuildArcPiece(in XChartCylinderDisc2D disc, float fromAngle, float sweep,
int pieceCount, int index, Vector2[] output)
{
if (output == null || output.Length < 4) throw new ArgumentException("控制点数组至少要 4 个点");
if (pieceCount <= 0) pieceCount = 1;
float delta = sweep / pieceCount;
float a = fromAngle + delta * index;
float b = a + delta;
float k = 1.3333333f * Mathf.Tan(delta * 0.25f);
Vector2 pa = disc.PointAt(a);
Vector2 pb = disc.PointAt(b);
output[0] = pa;
output[1] = pa + disc.TangentAt(a) * k;
output[2] = pb - disc.TangentAt(b) * k;
output[3] = pb;
}
/// <summary>直线段 → 一次三次贝塞尔(控制点在 1/3、2/3,形状就是这条直线)</summary>
public static void BuildLineBezier(Vector2 a, Vector2 b, Vector2[] output)
{
if (output == null || output.Length < 4) throw new ArgumentException("控制点数组至少要 4 个点");
Vector2 third = (b - a) / 3f;
output[0] = a;
output[1] = a + third;
output[2] = a + third * 2f;
output[3] = b;
}
/// <summary>
/// 给轮廓每个点打"落在哪片端面上"的标记(1=第一片 / 2=第二片 / 0=都认不出)。
/// 凸包按端面分组,才能把弧段当曲线、把跨端面那两段当直线("过圆心的长轴方向连外框"那两条桥接线)。
/// </summary>
public static void ClassifyOutline(Vector2[] outline, int count, in XChartCylinderDisc2D first,
in XChartCylinderDisc2D second, byte[] tags)
{
if (outline == null || tags == null) throw new ArgumentNullException(nameof(outline));
if (tags.Length < count) throw new ArgumentException("tags 长度不足");
for (int i = 0; i < count; i++)
{
tags[i] = TryParameterOf(first, outline[i], out float _) ? (byte)1
: TryParameterOf(second, outline[i], out float _) ? (byte)2
: (byte)0;
}
}
/// <summary>
/// 把凸包切成"同一片端面"的连续段(每段是那片的可见弧)。从"标记变化处"起步走一圈,
/// 跨末尾的那一段才不会被劈成两半。各段写进 <paramref name="runStarts"/> / <paramref name="runEnds"/> /
/// <paramref name="runTags"/>,返回段数(数组要能装下 count 段)。
/// <para>凸包上每片凸集只贡献一段弧,所以正常就是"2 弧 + 2 桥接";<b>远侧端面可能一段都没有</b>
/// (它整个躲在外轮廓里),这时它没有"可见弧"可补——环只能自己画整圈。</para>
/// </summary>
public static int SplitOutlineRuns(Vector2[] outline, int count, in XChartCylinderDisc2D first,
in XChartCylinderDisc2D second, byte[] tags, int[] runStarts, int[] runEnds, byte[] runTags)
{
if (outline == null || tags == null || runStarts == null || runEnds == null || runTags == null)
throw new ArgumentNullException(nameof(outline));
if (tags.Length < count || runStarts.Length < count || runEnds.Length < count || runTags.Length < count)
throw new ArgumentException("缓冲长度不足");
if (count < 3) return 0;
ClassifyOutline(outline, count, first, second, tags);
int start = 0;
for (int i = 0; i < count; i++)
{
if (tags[i] != tags[(i + count - 1) % count]) { start = i; break; }
}
int runs = 0;
int runStart = start;
int runTag = tags[start];
for (int step = 1; step <= count; step++)
{
int index = (start + step) % count;
if (step < count && tags[index] == runTag) continue;
runTags[runs] = (byte)runTag;
runStarts[runs] = runStart;
runEnds[runs] = (start + step - 1) % count;
runs++;
runStart = index;
if (step < count) runTag = tags[index];
}
return runs;
}
/// <summary>
/// 端面环=包边那段可见弧的<b>补弧</b>:起点接在可见弧的终点、扫过 <c>2π-|可见|</c>(方向相反),
/// 也就是端面圆上<b>躲在外轮廓里面</b>的那一半。外侧由包边画、内侧由环画,两边都不重复。
/// </summary>
public static void RingArc(float fromAngle, float visibleSweep, out float ringStartAngle, out float ringSweep)
{
ringStartAngle = fromAngle + visibleSweep;
ringSweep = ComplementSweep(visibleSweep);
}
/// <summary>按 x 再按 y 排序(就地)。凸包要它,且顺序稳定才能让"包点顺序"可复现。</summary>
private static void SortByXThenY(Vector2[] points, int count)
{
for (int i = 1; i < count; i++)
{
Vector2 key = points[i];
int j = i - 1;
while (j >= 0 && (points[j].x > key.x || (points[j].x == key.x && points[j].y > key.y)))
{
points[j + 1] = points[j];
j--;
}
points[j + 1] = key;
}
}
}
}