manim-3d 0.1.0__tar.gz

manim_3d-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 FTZ-OPUS
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

manim_3d-0.1.0/PKG-INFO

@@ -0,0 +1,197 @@
+Metadata-Version: 2.4
+Name: manim-3d
+Version: 0.1.0
+Summary: Manim 三维几何与动画 —— 几行代码出 3D 曲面数学动画 / 3D geometry & animation presets for Manim CE
+Author: FTZ-OPUS
+License: MIT
+Project-URL: Homepage, https://github.com/FTZ-OPUS/manim-3d
+Project-URL: Repository, https://github.com/FTZ-OPUS/manim-3d
+Keywords: manim,math,animation,3d,surface,geometry,education
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Education
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Multimedia :: Video
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: manim>=0.21
+Requires-Dist: numpy>=1.24
+Dynamic: license-file
+
+# manim-3d 🧊 Manim 三维几何与动画
+
+**manim-3d** 是 [Manim](https://www.manim.community/) 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：
+
+```python
+from manim_3d import gaussian_surface_scene
+
+class GaussianSurface(gaussian_surface_scene()): pass
+```
+
+6 行，渲染命令照旧：`manim -qh demo.py GaussianSurface`。
+配色、运镜、字幕、节拍、时长——全部预设到审美在线的状态；想不一样，每个环节都有参数。
+
+| 高斯曲面 | 马鞍面 | 抛物面 |
+|---|---|---|
+| ![](assets/demo_gaussian.gif) | ![](assets/demo_saddle.gif) | ![](assets/demo_paraboloid.gif) |
+| **椭球面** | **圆环面** | **单叶双曲面** |
+| ![](assets/demo_ellipsoid.gif) | ![](assets/demo_torus.gif) | 📷 见 examples |
+
+以上全部由本库直接渲染输出，无后期。
+
+## 特性
+
+- 🎬 **几行代码出片** —— 类定义即视频；六个曲面开箱即用，覆盖图曲面与闭曲面两种形态
+- ⏱️ **权重配速** —— 同一套动画，45s 完整版与 10s 混剪版只是一个参数：每拍按权重伸缩、
+  夹住"难看下限"，压不下自动按优先级砍可选拍并在日志告诉你砍了啥，主线一个不少
+- 🌈 **预设即美观** —— 七段彩虹高度色带（海洋/熔岩可换）、金色大字幕、环绕恒转满一整圈、
+  标注自动防遮挡（3D 天线 / 屏幕 HUD 两种方案按几何自动选择）
+- 🔧 **全参数可调** —— 换函数、换半轴、换配色主题、五个节拍开关、字幕槽位对位，
+  每一处预设都留了改口
+- 🤫 **字幕默认关** —— 片子干干净净；要讲课时把字幕列表传进去，自动按节拍挂载
+- 🧭 **替你踩平的坑** —— fixed-in-frame 注册、Transform 字形错配、partial 缓存失效、
+  深度遮挡……全部在库内处理，使用者无需知晓
+
+## 安装
+
+```bash
+pip install manim-3d
+# 或从源码
+git clone https://github.com/FTZ-OPUS/manim-3d && pip install -e ./manim-3d
+```
+
+依赖：Python ≥ 3.10、[Manim CE](https://docs.manim.community/) ≥ 0.21（含其自身依赖与 LaTeX）。
+
+## 快速开始
+
+六个曲面，同一套 API——
+
+```python
+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/`](examples/)（每个曲面一个文件，含字幕版与 16 秒速览版）。
+
+### 加字幕
+
+字幕默认关闭。要讲课时传入字幕列表，自动按节拍挂载（整行淡出淡入，绝不形变糊字）：
+
+```python
+class SaddleSurface(saddle_surface_scene(
+    captions=("马鞍面", "建立三维坐标系", "平面扭曲成马鞍面",
+              "等高线：双曲线族与渐近线", "360° 环绕展示",
+              "绕轴翻转 · 展示底面", "manim 立体几何 · 第二画"),
+)): pass
+```
+
+### 控时长（混剪友好）
+
+```python
+class SaddleFast(saddle_surface_scene(pace="fast", name="SaddleFast")):   # 10 秒
+class SaddleTeaser(saddle_surface_scene(duration=16, name="SaddleTeaser")):  # 16 秒
+```
+
+`duration=16` 时放不下全部节拍？库会按 **等高线 → 平面 → 标注 → 环绕 → 翻面** 的优先级
+自动砍拍并打印，保住"成型 → 环绕 → 翻面"主线——混剪快切时每一拍依然完整。
+
+### 换函数 / 换配色 / 换形状
+
+```python
+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
+```
+
+## 参数一览
+
+| 参数 | 默认 | 说明 |
+|---|---|---|
+| `func` / `func_tex`（高斯） | 内置高斯 | 任意 `z=f(x,y)`；公式 LaTeX 自动/手填 |
+| `semi_axes`（椭球） | (2.4, 1.6, 1.2) | 半轴 (a, b, c)，坐标轴等比缩放防畸变 |
+| `major_radius` / `minor_radius`（圆环面） | 2.0 / 0.5 | 环半径 / 管半径 |
+| `waist_radius` / `z_extent`（单叶双曲面） | 1.0 / 1.5 | 腰圆半径 / 上下截断高度 |
+| `domain` | ±2.2~2.6 | 图曲面 x/y 定义域 |
+| `colors` | "rainbow" | `rainbow / ocean / magma` 或 `[(hex, 0~1)...]` |
+| `height` | 1.0~1.2 | 峰值自动归一化目标高度 |
+| `axes / rings / orbit / flip / annotate` | True | 五个节拍开关 |
+| `captions` | None | 字幕按节拍槽位对位，不传 = 无字幕 |
+| `duration` / `pace` | "full" | 内容预算秒数；`fast`=10s / `normal`=24s / `full`=45s |
+
+### 字幕槽位
+
+按曲面节拍序列位置对位：高斯 6 槽（片头/坐标轴/隆起/环绕/翻面/片尾），
+其余 7 槽（多一个"等高线"槽）。传少于槽数的条目时自动截取。
+
+### 配速规则
+
+每拍带三个数：**参考时长**（完整版节奏）、**下限**（低于就难看的压缩底线）、
+**上限倍率**（拉伸顶格）。`duration` 先等比分摊，夹进上下限迭代收敛；
+全体顶到下限仍放不下才砍拍。环绕拍永远**恰好转满一整圈**（角速度随时长自适应）。
+
+## 六曲面差异一览
+
+| 曲面 | 方程 | 成型 | 等高线 | 标注 |
+|---|---|---|---|---|
+| 高斯曲面 | z = e^(−x²−y²) | 平面隆起 | 地板投影圆 | 峰顶 3D 标签 |
+| 马鞍面 | z = x² − y² | 平面扭曲 | 双曲线族 + 渐近线 | 鞍点 HUD 标签 |
+| 抛物面 | z = x² + y² | 平面卷起 | 贴面同心圆 | 顶点 HUD 标签 |
+| 椭球面 | x²/a²+y²/b²+z²/c²=1 | 充气成型 | 贴面水平椭圆环 | 上顶点 3D 标签 |
+| 圆环面 | (√(x²+y²)−R)²+z²=r² | 充气成型 | 贴面水平成对圆环 | 最高点 3D 标签 |
+| 单叶双曲面 | x²+y²−z²=a² | 充气成型 | 水平圆族（含腰圆） | 腰点 HUD 标签 |
+
+标注方案按几何自动选择：特征点外露用 3D 标签（天线虚线），被曲面环抱则用
+**相机定格投影 + 固定帧** 的屏幕 HUD 标签，永不被深度遮挡。
+
+## 设计边界（诚实声明）
+
+- 高斯等高线为径向近似，仅旋转对称函数精确；一般函数建议 `rings=False`
+- 马鞍/抛物面/圆环面/单叶双曲面为固定几何预设（解析等高线依赖具体方程），
+  任意函数请走高斯入口
+- 双叶双曲面等参数曲面在路线图上
+
+## 用它做过的片子
+
+《立体几何 N 画》系列（B站）：高斯曲面 · 第一画 / 马鞍面 · 第二画 / 抛物面 · 第三画 /
+椭球面 · 第四画 / 圆环面 · 第五画 / 单叶双曲面 · 第六画 —— 全部由本库（或其前身脚本）直接渲染。
+
+## License
+
+[MIT](LICENSE) © FTZ-OPUS

manim_3d-0.1.0/README.md

@@ -0,0 +1,171 @@
+# manim-3d 🧊 Manim 三维几何与动画
+
+**manim-3d** 是 [Manim](https://www.manim.community/) 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：
+
+```python
+from manim_3d import gaussian_surface_scene
+
+class GaussianSurface(gaussian_surface_scene()): pass
+```
+
+6 行，渲染命令照旧：`manim -qh demo.py GaussianSurface`。
+配色、运镜、字幕、节拍、时长——全部预设到审美在线的状态；想不一样，每个环节都有参数。
+
+| 高斯曲面 | 马鞍面 | 抛物面 |
+|---|---|---|
+| ![](assets/demo_gaussian.gif) | ![](assets/demo_saddle.gif) | ![](assets/demo_paraboloid.gif) |
+| **椭球面** | **圆环面** | **单叶双曲面** |
+| ![](assets/demo_ellipsoid.gif) | ![](assets/demo_torus.gif) | 📷 见 examples |
+
+以上全部由本库直接渲染输出，无后期。
+
+## 特性
+
+- 🎬 **几行代码出片** —— 类定义即视频；六个曲面开箱即用，覆盖图曲面与闭曲面两种形态
+- ⏱️ **权重配速** —— 同一套动画，45s 完整版与 10s 混剪版只是一个参数：每拍按权重伸缩、
+  夹住"难看下限"，压不下自动按优先级砍可选拍并在日志告诉你砍了啥，主线一个不少
+- 🌈 **预设即美观** —— 七段彩虹高度色带（海洋/熔岩可换）、金色大字幕、环绕恒转满一整圈、
+  标注自动防遮挡（3D 天线 / 屏幕 HUD 两种方案按几何自动选择）
+- 🔧 **全参数可调** —— 换函数、换半轴、换配色主题、五个节拍开关、字幕槽位对位，
+  每一处预设都留了改口
+- 🤫 **字幕默认关** —— 片子干干净净；要讲课时把字幕列表传进去，自动按节拍挂载
+- 🧭 **替你踩平的坑** —— fixed-in-frame 注册、Transform 字形错配、partial 缓存失效、
+  深度遮挡……全部在库内处理，使用者无需知晓
+
+## 安装
+
+```bash
+pip install manim-3d
+# 或从源码
+git clone https://github.com/FTZ-OPUS/manim-3d && pip install -e ./manim-3d
+```
+
+依赖：Python ≥ 3.10、[Manim CE](https://docs.manim.community/) ≥ 0.21（含其自身依赖与 LaTeX）。
+
+## 快速开始
+
+六个曲面，同一套 API——
+
+```python
+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/`](examples/)（每个曲面一个文件，含字幕版与 16 秒速览版）。
+
+### 加字幕
+
+字幕默认关闭。要讲课时传入字幕列表，自动按节拍挂载（整行淡出淡入，绝不形变糊字）：
+
+```python
+class SaddleSurface(saddle_surface_scene(
+    captions=("马鞍面", "建立三维坐标系", "平面扭曲成马鞍面",
+              "等高线：双曲线族与渐近线", "360° 环绕展示",
+              "绕轴翻转 · 展示底面", "manim 立体几何 · 第二画"),
+)): pass
+```
+
+### 控时长（混剪友好）
+
+```python
+class SaddleFast(saddle_surface_scene(pace="fast", name="SaddleFast")):   # 10 秒
+class SaddleTeaser(saddle_surface_scene(duration=16, name="SaddleTeaser")):  # 16 秒
+```
+
+`duration=16` 时放不下全部节拍？库会按 **等高线 → 平面 → 标注 → 环绕 → 翻面** 的优先级
+自动砍拍并打印，保住"成型 → 环绕 → 翻面"主线——混剪快切时每一拍依然完整。
+
+### 换函数 / 换配色 / 换形状
+
+```python
+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
+```
+
+## 参数一览
+
+| 参数 | 默认 | 说明 |
+|---|---|---|
+| `func` / `func_tex`（高斯） | 内置高斯 | 任意 `z=f(x,y)`；公式 LaTeX 自动/手填 |
+| `semi_axes`（椭球） | (2.4, 1.6, 1.2) | 半轴 (a, b, c)，坐标轴等比缩放防畸变 |
+| `major_radius` / `minor_radius`（圆环面） | 2.0 / 0.5 | 环半径 / 管半径 |
+| `waist_radius` / `z_extent`（单叶双曲面） | 1.0 / 1.5 | 腰圆半径 / 上下截断高度 |
+| `domain` | ±2.2~2.6 | 图曲面 x/y 定义域 |
+| `colors` | "rainbow" | `rainbow / ocean / magma` 或 `[(hex, 0~1)...]` |
+| `height` | 1.0~1.2 | 峰值自动归一化目标高度 |
+| `axes / rings / orbit / flip / annotate` | True | 五个节拍开关 |
+| `captions` | None | 字幕按节拍槽位对位，不传 = 无字幕 |
+| `duration` / `pace` | "full" | 内容预算秒数；`fast`=10s / `normal`=24s / `full`=45s |
+
+### 字幕槽位
+
+按曲面节拍序列位置对位：高斯 6 槽（片头/坐标轴/隆起/环绕/翻面/片尾），
+其余 7 槽（多一个"等高线"槽）。传少于槽数的条目时自动截取。
+
+### 配速规则
+
+每拍带三个数：**参考时长**（完整版节奏）、**下限**（低于就难看的压缩底线）、
+**上限倍率**（拉伸顶格）。`duration` 先等比分摊，夹进上下限迭代收敛；
+全体顶到下限仍放不下才砍拍。环绕拍永远**恰好转满一整圈**（角速度随时长自适应）。
+
+## 六曲面差异一览
+
+| 曲面 | 方程 | 成型 | 等高线 | 标注 |
+|---|---|---|---|---|
+| 高斯曲面 | z = e^(−x²−y²) | 平面隆起 | 地板投影圆 | 峰顶 3D 标签 |
+| 马鞍面 | z = x² − y² | 平面扭曲 | 双曲线族 + 渐近线 | 鞍点 HUD 标签 |
+| 抛物面 | z = x² + y² | 平面卷起 | 贴面同心圆 | 顶点 HUD 标签 |
+| 椭球面 | x²/a²+y²/b²+z²/c²=1 | 充气成型 | 贴面水平椭圆环 | 上顶点 3D 标签 |
+| 圆环面 | (√(x²+y²)−R)²+z²=r² | 充气成型 | 贴面水平成对圆环 | 最高点 3D 标签 |
+| 单叶双曲面 | x²+y²−z²=a² | 充气成型 | 水平圆族（含腰圆） | 腰点 HUD 标签 |
+
+标注方案按几何自动选择：特征点外露用 3D 标签（天线虚线），被曲面环抱则用
+**相机定格投影 + 固定帧** 的屏幕 HUD 标签，永不被深度遮挡。
+
+## 设计边界（诚实声明）
+
+- 高斯等高线为径向近似，仅旋转对称函数精确；一般函数建议 `rings=False`
+- 马鞍/抛物面/圆环面/单叶双曲面为固定几何预设（解析等高线依赖具体方程），
+  任意函数请走高斯入口
+- 双叶双曲面等参数曲面在路线图上
+
+## 用它做过的片子
+
+《立体几何 N 画》系列（B站）：高斯曲面 · 第一画 / 马鞍面 · 第二画 / 抛物面 · 第三画 /
+椭球面 · 第四画 / 圆环面 · 第五画 / 单叶双曲面 · 第六画 —— 全部由本库（或其前身脚本）直接渲染。
+
+## License
+
+[MIT](LICENSE) © FTZ-OPUS

manim_3d-0.1.0/manim_3d/__init__.py

@@ -0,0 +1,22 @@
+# -*- coding: utf-8 -*-
+"""manim-3d —— Manim 三维几何与动画。闭式管面与图曲面预设,几行代码出片。"""
+from .core import (
+    GaussianSurface, SaddleSurface, ParaboloidSurface, EllipsoidSurface,
+    TorusSurface, HyperboloidOneSheet,
+    gaussian_surface_scene, saddle_surface_scene, paraboloid_surface_scene,
+    ellipsoid_surface_scene, torus_surface_scene, hyperboloid_one_sheet_scene,
+    GaussianSurfaceScene, SaddleSurfaceScene, ParaboloidSurfaceScene,
+    EllipsoidSurfaceScene, TorusSurfaceScene, HyperboloidOneSheetScene,
+    plan_timeline, RAMPS, PACE,
+)
+
+__version__ = "0.1.0"
+__all__ = [
+    "GaussianSurface", "SaddleSurface", "ParaboloidSurface", "EllipsoidSurface",
+    "TorusSurface", "HyperboloidOneSheet",
+    "gaussian_surface_scene", "saddle_surface_scene", "paraboloid_surface_scene",
+    "ellipsoid_surface_scene", "torus_surface_scene", "hyperboloid_one_sheet_scene",
+    "GaussianSurfaceScene", "SaddleSurfaceScene", "ParaboloidSurfaceScene",
+    "EllipsoidSurfaceScene", "TorusSurfaceScene", "HyperboloidOneSheetScene",
+    "plan_timeline", "RAMPS", "PACE", "__version__",
+]