基于 Syslab 的三维挂谷（Kakeya）猜想有限尺度数

概述

本演示基于 MWORKS.Syslab 与 Julia，完成三维Kakeya（挂谷）猜想有限尺度下的数值仿真与交互式可视化。程序生成三维 $\delta$ -细管簇，直观呈现方向覆盖、空间重叠、并集体积、覆盖重数统计、空间聚集形态以及尺度缩放演化等几何特征。

重要声明：本项目仅为有限方向、有限尺度、有限采样条件下的数值实验与可视化演示，既不是三维Kakeya猜想的严格数学证明、计算机辅助证明，也未对Wang-Zahl论文的证明过程做形式化逻辑验证。

一、数学背景

R³ 空间中的Kakeya集定义为：一个紧集，且在每一个三维单位方向上都包含一条完整单位线段。三维Kakeya猜想核心结论：三维欧氏空间中任意Kakeya集的Hausdorff维数与Minkowski维数均等于3。

核心数学模型

1. 中心单位线段

ℓᵢ(t) = pᵢ + t · vᵢ , -1/2 ≤ t ≤ 1/2

vᵢ 为三维单位方向向量，pᵢ 为线段中心点。

2. δ-细管状邻域

Tᵢ = { x | dist(x, ℓᵢ) ≤ δ/2 }

以单位线段为中轴线、半径 δ/2 的圆柱体（两端附带半球封头）。

3. 覆盖典型重数

μ(T) = ( Σᵢ |Tᵢ| ) / | ∪ᵢ Tᵢ |

所有细管体积总和除以并集体积，表征整体重叠程度。

4. Minkowski维数拟合规则

满足标度关系 |K_δ| ~ δ^(3-d)，对 (logδ, log|K_δ|) 做线性拟合得到斜率 s，有限尺度估算维数：
d = 3 - s

二、运行环境

MWORKS.Syslab：26.3.1
Julia：1.10.10
预装依赖包：TyPlot、CSV、DataFrames、JSON3、TyImages

三、快速开始

方式1：V2交互式实时可视化（推荐）

Syslab打开工程目录，在Julia命令行执行基础入口：

include("main2.jl")

自定义渲染性能档位：

include("showcase_v2.jl")
run_kakeya_showcase_v2(quality=:balanced)

渲染质量档位对照表

档位参数	渲染配置	适用场景
`:high`	共64根细管，几何细节最全	静态截图、成果展示
`:balanced`	默认48根，画质与帧率均衡	日常调试、演示讲解
`:performance`	32根细管，计算负载最低	低配设备、连续动画播放

方式2：通用主脚本入口

include("main.jl")

通过布尔变量开关控制功能模块：

开关变量	功能说明
`show_static`	生成4类构型静态对比图与指标汇总图表
`play_live_animation`	播放中心线生长、相机环绕实时动画
`play_frame_preview`	逐帧回放导出的PNG图片序列
`encode_gif`	调用FFmpeg打包生成GIF动图
`encode_video`	导出MP4/AVI格式视频文件

四、四类几何构型定义

构型名称	内部标识	构型特征
分散型	`A_distributed`	线段中心点添加小幅随机扰动，模拟低空间重叠场景
共点型	`B_common_point`	所有线段中心点汇聚于坐标原点，展示局部极高覆盖重数（不代表集合维数下降）
近平面聚集型	`C_planar`	方向向量与中心点被约束至近似二维平面，形成薄板状聚集结构
多尺度黏连型	`D_sticky`	先构建大尺度方向簇，再拆解为细尺度子簇，简化复现sticky型分层结构（教学演示用途）

五、V2可视化完整播放流程

执行run_kakeya_showcase_v2(quality=:balanced)后自动顺序播放8个联动场景：

开场引言：演示单位方向向量与中心线段的几何对应关系
方向集生成：逐步递增三维方向数量，球面均匀布点可视化
共点构型动画：分批生成中心线→360°相机环绕→高亮原点超高重数区域
分散构型动画：线段中心点从原点缓慢扩散至各自扰动位置
近平面压缩动画：三维方向簇连续坍缩至近似平面，观察板状聚集效果
黏连多尺度动画：先展示粗尺度方向簇→分裂为细尺度子簇→分区域聚焦查看
尺度扫描实验：遍历多组 $\delta$ 值，线段视觉宽度映射管径大小，同步更新体积与重数指标
收尾定格：最终完整构型缓慢自转，叠加实验边界与数学说明文字

V2界面布局说明

主绘图区（左侧65%）：3D坐标轴渲染各类构型中心线几何
LIVE METRICS右侧面板：显示构型类型、管径 $\delta$ 、绘制总数、并集体积、典型重数、全局最大重数
场景说明文本区：对当前几何模型做简要数学释义
底部进度条：展示场景序号、场景名称、播放进度百分比

六、文件结构与模块函数说明

（一）核心几何计算模块

1. `geometry.jl` 底层几何工具库

结构体/函数	功能描述
`Tube`	细管结构体：存储`center`中心点、`direction`方向向量、`radius`管径、`group`分组编号
`vec3(x)`	数组转为三维浮点三元组`(Float64, Float64, Float64)`
`vadd(a, b)`	三维向量加法
`vsub(a, b)`	三维向量减法
`vmul(s, a)`	标量数乘三维向量
`vdot(a, b)`	三维向量点积运算
`vnorm(a)`	求解三维向量模长
`clamp01(x)`	数值截断至区间 $$[0,1]$$
`normalize3(a)`	三维向量单位归一化
`point_segment_distance(x, center, direction)`	计算空间点到有限中心单位线段的最短距离（参数 $t$ 限制在 $[-0.5,0.5]$ ）
`point_in_tube(x, tube)`	判断空间点是否落在 $\delta$ 细管内部
`tube_volume(radius)`	单根细管体积计算（圆柱柱体+两端半球）
`segment_endpoints(tube)`	提取中心线段两个端点坐标
`tube_aabb(tube)`	求解单根细管轴对齐包围盒AABB
`in_aabb(x, lo, hi)`	判断点是否在包围盒范围内
`multiplicity_at(x, tubes)`	统计某空间点被多少根细管同时覆盖（覆盖重数）

2. `configurations.jl` 四类构型生成器

函数	功能描述
`generate_directions(n)`	黄金角螺旋算法在上半球面生成 $n$ 个近似均匀分布的单位方向向量
`direction_stats(dirs)`	统计方向集几何离散度：最小夹角、近邻平均夹角、最大间隙代理值
`config_distributed(dirs, radius; jitter)`	生成带中心点随机扰动的分散构型
`config_common_point(dirs, radius)`	生成全部中心汇聚原点的共点构型
`config_planar(dirs, radius)`	生成坍缩至近似平面的聚集构型
`config_sticky(dirs, radius; clusters)`	生成多尺度簇状黏连构型
`make_configuration(kind, dirs, radius)`	根据字符串标识一键生成对应构型的`Tube`数组
`configuration_names()`	返回全部4种构型标识列表

3. `estimators.jl` 数值估算与维数拟合

常量/函数	功能描述
`DOMAIN_LO`, `DOMAIN_HI`	三维采样计算域边界： $[-0.8, 0.8]^3$
`DOMAIN_VOLUME`	立方体计算域总体积 $1.6^3$
`estimate_union_volume(tubes; samples)`	蒙特卡洛随机采样估算细管并集体积，输出体积、命中率、标准误、95%置信区间（默认50000采样点）
`estimate_multiplicity(tubes; grid)`	三维体素网格统计覆盖重数（默认64×64×64网格），返回并集体积、最大重数、非零平均重数、重数分布直方图
`convex_density_proxy(tubes)`	凸包聚集度代理指标，搜索最优包围凸集密度
`fit_minkowski_dimension(deltas, volumes)`	对数-对数最小二乘拟合Minkowski维数，返回斜率、截距、 $R^2$ 判定系数、估算维数

（二）可视化渲染模块

1. `visualization.jl` 纯Julia光栅离线渲染管线

结构体/函数	功能描述
`Pix`	RGB像素封装结构体
`rgb(r, g, b)`	构造RGB颜色像素
`blank_image(w, h)`	生成深蓝色渐变背景画布
`rotate_project(p; az, el, scale)`	三维坐标旋转+透视投影映射至二维屏幕
`draw_disk!(img, x, y, rad, color, alpha)`	绘制抗锯齿半透明圆形
`draw_line!(img, p1, p2, color; width, alpha)`	绘制带透明度粗直线段
`draw_text_block!(img, lines; x, y, color)`	绘制半透明文字注释块
`tube_color(tube)`	根据方向向量/分组自动分配细管渲染颜色
`render_tubes_png(path, tubes; title, stats, az, el, max_show)`	离线渲染细管三维图并写入PNG，附带标题与统计指标
`render_heatmap_png(path, tubes; plane, value, grid)`	截取指定坐标平面，导出覆盖重数热力图
`render_simple_plot(path, series; title)`	绘制尺度-体积/重数变化折线图
`save_png(path, img)`	原生PNG编码器，手动构造IHDR/IDAT/IEND分块并zlib压缩存储

2. `figure_helpers.jl` MWORKS.Syslab TyPlot绘图辅助

函数	功能描述
`representative_tubes(delta; n)`	批量生成4类构型标准样本
`tube_xyz(tube)`	提取线段端点XYZ坐标，适配TyPlot 3D绘图接口
`draw_tubes_typlot(tubes; max_show)`	在Syslab Figure画布绘制三维细管簇
`safe_file_status(path)`	安全读取文件路径状态，避免IO异常

3. `animation.jl` FFmpeg视频/动图编码工具

函数	功能描述
`smoothstep(t)`	平滑插值函数 $3t^2-2t^3$
`find_ffmpeg()`	自动检索系统FFmpeg可执行文件路径
`encode_frames_to_mp4(frame_pattern, outpath; fps)`	FFmpeg H.264编码帧序列导出MP4视频
`encode_frames_to_gif(frame_pattern, outpath; fps)`	FFmpeg生成循环GIF动图
`render_orbit_animation(tubes, outpath; seconds, fps)`	固定几何模型，相机绕Y轴公转动画
`render_growth_animation(tubes, outpath; seconds, fps)`	细管逐条生长浮现+整体自转动画
`render_slice_scan_animation(tubes, outpath; seconds, fps)`	沿Z轴滑动切面，动态展示重数热力扫描
`extract_check_frames(frame_dir, outdir)`	自动抽取0%/25%/50%/75%/100%五帧关键截图用于验收

4. `show_results_in_figure.jl` 静态结果汇总出图

图1：2×2子图布局，四类构型三维几何并排对比，导出kakeya_configurations.syslabfig与PNG
图2：2×2指标曲线面板，绘制并集体积、典型重数、最大重数、凸聚集度随 $\delta$ 衰减趋势，导出kakeya_results_overview.syslabfig与PNG
所有图表统一归档至results/figures/目录

5. `play_kakeya_in_figure.jl` 画布内实时动画播放器

函数	功能描述
`grouped_indices(n, group_count)`	将序号均分至指定分组，用于分批次上色显示
`tube_group_xyz(tubes, idxs)`	拼接分组线段坐标，NaN做分段隔离适配plot3
`draw_tubes_batched!(tubes; max_show, groups)`	批量创建多组不同颜色3D线段句柄
`update_batched_tubes!(handles, tubes; active)`	增量更新可见线段数据，降低重绘开销
`rotate_xyz(xs, ys, zs, angle)`	坐标数组绕Y轴批量旋转变换
`play_kakeya_in_figure(; mode, fps, frames)`	实时动画总入口，支持`:orbit`环绕模式、`:growth`生长模式

6. `play_frames_in_figure.jl` PNG帧序列回放器

play_frames_in_figure(frame_dir; fps)：调用imshow逐帧加载图片文件夹，在Syslab画布播放动画

7. `check_syslab_figure_backend.jl` 3D后端自检脚本

绘制三维螺旋线，快速验证TyPlot 3D绘图引擎是否正常工作。

（三）实验执行入口脚本

1. `main.jl` 总开关入口

通过顶部布尔变量一键启停所有绘图、动画、编码模块，执行结束返回全模块运行状态字典。

2. `main2.jl` V2极简快捷入口

直接封装调用run_kakeya_showcase_v2(quality=:balanced)，无需配置冗余参数，快速启动新版可视化系统。

3. `run_experiments.jl` 完整批量实验流水线

run_all_experiments(project_dir; preview)：自动遍历 $\delta$ 尺度区间0.24→0.085，批量生成4类构型、蒙特卡洛体积估算、体素重数统计、Minkowski维数回归拟合，输出结构化CSV数据表与趋势图表。

4. `render_main_animation.jl` 全量动画批量渲染

完整实验跑完后自动生成环绕动画、生长动画、切面扫描动画、V2完整版演示动画，并导出关键校验帧。

5. `render_preview.jl` 单元测试与快速预览

内置几何函数单元测试（点线段距离、管内判定、向量归一化校验），支持单独渲染共点构型预览图。

（四）V2独立可视化子系统

1. `showcase_v2.jl` V2顶层调度入口

run_kakeya_showcase_v2(; quality)：创建深色主题Figure画布、加载预计算实验数据、串行执行8段场景动画、最终输出运行校验日志。

2. `showcase_v2_data.jl` V2场景数据封装

结构体/函数	功能描述
`TubeSceneData`	单场景数据包：构型名称、标识、中心点数组、方向数组、配色数组、管径 $\delta$ 、显示数量、总方向数、并集体积、典型重数、最大重数、场景说明文本
`ShowcaseV2Data`	全局总数据包，聚合四类构型`TubeSceneData`与全部 $\delta$ 尺度列表
`v2_quality_settings(q)`	根据档位返回渲染参数：显示管数、分组数量、目标帧率、场景缩放系数
`make_v2_data(; quality, delta)`	读取CSV实验指标→生成四类构型→打包为V2标准场景数据结构
`validate_scene_data(data)`	数据合法性校验：方向模长=1、线段总长=1、坐标边界约束、共点构型中心归零
`scaled_common_point_data(base, delta, n)`	基于基准数据生成指定 $\delta$ 下的共点构型场景包

3. `showcase_v2_scenes.jl` 场景动画逻辑控制器

结构体/函数	功能描述
`SceneAnimationAudit`	动画运行审计结构体，记录几何变更、相机参数、UI刷新状态
`SCENE_DESCRIPTIONS`	8个场景对应说明文字常量字典
`smootherstep(t)`	五阶平滑插值 $x^3(6x^2-15x+10)$ ，动画过渡更自然
`animate_for_duration!(update!, duration, target_fps)`	时间驱动动画循环，按目标帧率限频刷新画布
`line_groups_for(n, group_count)`	序号交错分组，实现多色系分段绘制
`lerp_tuple(a, b, s)`	三维三元组线性插值
`normalize_tuple(v)`	三元组向量归一化
`endpoints_for(center, direction; growth)`	支持生长系数缩放的线段端点计算
`build_group_lines_from_vectors(centers, directions, idxs; growth)`	批量构造分组绘图坐标数组
`create_scene_lines!(handles, group_count)`	在画布预创建多组3D线段句柄
`create_origin_glow!(handles)`	原点十字高亮标记三条轴线光晕
`update_scene_lines!(lines, data; active, growth, centers, directions)`	动态刷新场景几何数据
`fit_scene_view!(ax, data; padding_ratio)`	根据模型包围盒自动适配3D相机视角
`prepare_tube_scene!(handles, data, name, group_count; scene_key)`	场景初始化：清空坐标轴、设置标题说明、创建几何对象、适配视图、刷新指标面板
`play_intro_scene!` / `play_direction_scene!` / `play_common_point_scene!` 等	8个独立场景播放函数
`show_scene_only(scene; quality)`	单独调试某一个场景，便于开发排错
`test_metrics_panel_layout!(; quality)`	右侧指标面板排版边界测试，防止文字重叠

4. `showcase_v2_ui.jl` V2深色主题UI布局框架

常量/结构体/函数	功能描述
`FIG_BG`、`AX_BG`等	全局深色主题色值常量
`MAIN_AX_POS`	主3D坐标轴归一化画布位置 `[0.105, 0.155, 0.655, 0.695]`
`METRICS_PANEL_POS` 系列	右侧指标面板、文本框、进度条固定坐标
`ShowcaseV2Handles`	全局UI句柄大结构体：Figure对象、3D坐标轴、所有注释文本、几何绘图对象集合
`safe_set!(obj, prop, val)`	安全设置绘图对象属性，捕获异常避免动画中断
`safe_get(obj, prop)`	安全读取对象属性参数
`ann(kind, pos; ...)`	快速创建文本/矩形注释组件
`create_showcase_v2_figure()`	一键搭建完整V2界面：深色画布、3D绘图区、标题副标题、右侧指标面板、场景说明栏、底部进度条
`apply_dark_axes_style!(fig, ax)`	统一坐标轴深色样式（刻度、轴线、标签配色）
`clear_main_axes!(handles)`	清空坐标轴并重置深色主题样式
`update_metrics_panel!(handles, data; shown)`	实时刷新右侧所有数值指标
`set_scene_description!(handles, description)`	更新场景底部释义文本
`update_scene_title!(handles, text)`	修改顶部场景大标题
`update_progress!(handles, idx, name, t)`	绘制底部进度条与进度百分比
`audit_current_scene!(handles, scene_name, expected_lines)`	画布元素审计，统计坐标轴、曲线、散点数量，清理残留孤儿对象
`validate_metrics_panel_layout!()`	校验右侧所有UI元素边界无重叠溢出

（五）独立视频编码封装模块

encode_animation_syslab.jl：调用TyImages库原生接口，不依赖FFmpeg生成灰度GIF、MP4/AVI视频
encode_gif_syslab.jl：索引色调色板压缩GIF，减小动图体积
encode_gif_vector_syslab.jl：向量图像批量写入GIF接口封装

七、输出文件目录结构

1. 数据结果 `results/data/`

文件名	内容说明
`kakeya_results.csv`	核心实验数据表：4种构型×多尺度 $\delta$ 下并集体积、重数、聚集度全部量化指标
`minkowski_fits.csv`	Minkowski维数回归结果：各构型拟合斜率、截距、 $R^2$ 、估算分形维数
`run_metadata.json`	运行环境、随机种子、采样参数、执行时间等元数据存档

2. 图表图片 `results/figures/`

kakeya_configurations.syslabfig / .png：四类构型2×2三维对比总图
kakeya_results_overview.syslabfig / .png：尺度-指标变化四张子图汇总

九、参考文献

Hong Wang, Joshua Zahl. Volume estimates for unions of convex sets, and the Kakeya set conjecture in three dimensions, arXiv:2502.17655
Larry Guth. Introduction to the proof of the Kakeya conjecture, arXiv:2505.07695

十、使用许可

本代码仅用于非商业学术研究与课堂教学演示，请勿用于商业二次开发与盈利性产品封装。

基于 Syslab 的三维挂谷（Kakeya）猜想有限尺度数

概述

一、数学背景

核心数学模型

1. 中心单位线段

2. δ-细管状邻域

3. 覆盖典型重数

4. Minkowski维数拟合规则

二、运行环境

三、快速开始

方式1：V2交互式实时可视化（推荐）

方式2：通用主脚本入口

四、四类几何构型定义

五、V2可视化完整播放流程

V2界面布局说明

六、文件结构与模块函数说明

（一）核心几何计算模块

1. geometry.jl 底层几何工具库

2. configurations.jl 四类构型生成器

3. estimators.jl 数值估算与维数拟合

（二）可视化渲染模块

1. visualization.jl 纯Julia光栅离线渲染管线

2. figure_helpers.jl MWORKS.Syslab TyPlot绘图辅助

3. animation.jl FFmpeg视频/动图编码工具

4. show_results_in_figure.jl 静态结果汇总出图

5. play_kakeya_in_figure.jl 画布内实时动画播放器

6. play_frames_in_figure.jl PNG帧序列回放器

7. check_syslab_figure_backend.jl 3D后端自检脚本

（三）实验执行入口脚本

1. main.jl 总开关入口

2. main2.jl V2极简快捷入口

3. run_experiments.jl 完整批量实验流水线

4. render_main_animation.jl 全量动画批量渲染

5. render_preview.jl 单元测试与快速预览