manim-3d 🧊 Manim 三维几何与动画

manim-3d 是 Manim Community Edition 的立体几何补充库。 高斯曲面、马鞍面、抛物面、椭球面、圆环面、单叶双曲面——这些经典三维曲面的整套演示动画 （成型 → 等高线 → 360° 环绕 → 翻面 → 特征点标注），被封装成一个工厂函数 + 几个参数。

One-liner 3D surface animation presets for Manim CE: rainbow-shaded surfaces, orbit & flip camera work, paced timelines from 10s to 45s — in a class definition.

为什么需要它

不用库，手写一支"平面隆起成彩虹高斯曲面 → 底面等高线 → 360° 环绕 → 翻面 → 峰顶标注"的 3D 视频， 你要面对的是：ThreeDScene 相机调度、set_fill_by_value 高度色带、HUD 固定帧字幕（还得躲开 "字幕被 3D 透视拉斜"的暗坑）、等高线解析与 z-fighting、深度遮挡、逐拍时长编排…… 130+ 行起步，坑还都不在文档里。

用 manim-3d：

from manim_3d import gaussian_surface_scene
class GaussianSurface(gaussian_surface_scene(
    colors="ocean",
    rings=True, orbit=True,
    flip=True, duration=24,
)): pass

6 行，渲染命令照旧：manim -qh demo.py GaussianSurface。 配色、运镜、字幕、节拍、时长——全部预设到审美在线的状态；想不一样，每个环节都有参数。

高斯曲面	马鞍面	抛物面
椭球面	圆环面	单叶双曲面
		📷 查看单叶双曲面示例

以上全部由本库直接渲染输出，无后期。

特性

• 🎬 几行代码出片 —— 类定义即视频；六个曲面开箱即用，覆盖图曲面与闭曲面两种形态
• ⏱️ 权重配速 —— 同一套动画，45s 完整版与 10s 混剪版只是一个参数：每拍按权重伸缩、 夹住"难看下限"，压不下自动按优先级砍可选拍并在日志告诉你砍了啥，主线一个不少
• 🌈 预设即美观 —— 七段彩虹高度色带（海洋/熔岩可换）、金色大字幕、环绕恒转满一整圈、 标注自动防遮挡（3D 天线 / 屏幕 HUD 两种方案按几何自动选择）
• 🔧 全参数可调 —— 换函数、换半轴、换配色主题、五个节拍开关、字幕槽位对位， 每一处预设都留了改口
• 🤫 字幕默认关 —— 片子干干净净；要讲课时把字幕列表传进去，自动按节拍挂载
• 🧭 替你踩平的坑 —— fixed-in-frame 注册、Transform 字形错配、partial 缓存失效、 深度遮挡……全部在库内处理，使用者无需知晓

安装

pip install manim-3d
# 或从源码
git clone https://github.com/FTZ-OPUS/manim-3d && pip install -e ./manim-3d

依赖：Python ≥ 3.10、Manim CE ≥ 0.21（含其自身依赖与 LaTeX）。

快速开始

六个曲面，同一套 API——

from manim_3d import (gaussian_surface_scene, saddle_surface_scene,
                       paraboloid_surface_scene, ellipsoid_surface_scene,
                       torus_surface_scene, hyperboloid_one_sheet_scene)

class GaussianSurface(gaussian_surface_scene()): pass
class SaddleSurface(saddle_surface_scene()): pass
class ParaboloidSurface(paraboloid_surface_scene()): pass
class EllipsoidSurface(ellipsoid_surface_scene()): pass
class TorusSurface(torus_surface_scene()): pass
class Hyperboloid(hyperboloid_one_sheet_scene()): pass

完整可运行示例见 examples 文件夹（每个曲面一个文件，含字幕版与 16 秒速览版）。

加字幕

字幕默认关闭。要讲课时传入字幕列表，自动按节拍挂载（整行淡出淡入，绝不形变糊字）：

class SaddleSurface(saddle_surface_scene(
    captions=("马鞍面", "建立三维坐标系", "平面扭曲成马鞍面",
              "等高线：双曲线族与渐近线", "360° 环绕展示",
              "绕轴翻转 · 展示底面", "manim 立体几何 · 第二画"),
)): pass

控时长（混剪友好）

class SaddleFast(saddle_surface_scene(pace="fast", name="SaddleFast")):   # 10 秒
class SaddleTeaser(saddle_surface_scene(duration=16, name="SaddleTeaser")):  # 16 秒

duration=16 时放不下全部节拍？库会按 等高线 → 平面 → 标注 → 环绕 → 翻面 的优先级 自动砍拍并打印，保住"成型 → 环绕 → 翻面"主线——混剪快切时每一拍依然完整。

换函数 / 换配色 / 换形状

import numpy as np
from manim_3d import gaussian_surface_scene

# 高斯曲面接受任意 z=f(x,y)，峰值自动归一化，不用调坐标轴
class MySurface(gaussian_surface_scene(
    func=lambda x, y: np.exp(-((x - 1) ** 2 + y * y)),
    colors="ocean",                       # rainbow / ocean / magma 或自定义色带
)): pass

# 椭球三轴随意改，公式自动跟着变
class MyEgg(ellipsoid_surface_scene(semi_axes=(2.6, 1.4, 1.8))): pass

参数一览

字幕槽位

按曲面节拍序列位置对位：高斯 6 槽（片头/坐标轴/隆起/环绕/翻面/片尾）， 其余 7 槽（多一个"等高线"槽）。传少于槽数的条目时自动截取。

配速规则

每拍带三个数：参考时长（完整版节奏）、下限（低于就难看的压缩底线）、 上限倍率（拉伸顶格）。duration 先等比分摊，夹进上下限迭代收敛； 全体顶到下限仍放不下才砍拍。环绕拍永远恰好转满一整圈（角速度随时长自适应）。

六曲面差异一览

标注方案按几何自动选择：特征点外露用 3D 标签（天线虚线），被曲面环抱则用 相机定格投影 + 固定帧 的屏幕 HUD 标签，永不被深度遮挡。

设计边界（诚实声明）

• 高斯等高线为径向近似，仅旋转对称函数精确；一般函数建议 rings=False
• 马鞍/抛物面/圆环面/单叶双曲面为固定几何预设（解析等高线依赖具体方程）， 任意函数请走高斯入口
• 双叶双曲面等参数曲面在路线图上

用它做过的片子

《立体几何 N 画》系列（B站）：高斯曲面 · 第一画 / 马鞍面 · 第二画 / 抛物面 · 第三画 / 椭球面 · 第四画 / 圆环面 · 第五画 / 单叶双曲面 · 第六画 —— 全部由本库（或其前身脚本）直接渲染。

License

MIT © FTZ-OPUS