资源管理

相关源文件

• MANIFEST.in
• README.md
• docs/source/development/about.rst
• docs/source/development/changelog.rst
• docs/source/getting_started/installation.rst
• docs/source/getting_started/structure.rst
• manimlib/mobject/svg/old_tex_mobject.py
• manimlib/mobject/svg/special_tex.py
• manimlib/utils/cache.py
• manimlib/utils/directories.py
• manimlib/utils/file_ops.py
• manimlib/utils/images.py
• manimlib/utils/paths.py
• manimlib/utils/rate_functions.py
• manimlib/utils/sounds.py
• pyproject.toml
• requirements.txt
• setup.cfg
• setup.py

目的与范围

本页面介绍了 Manim 如何管理动画中使用的外部资源，例如图像、声音和其他素材。资源管理系统提供了定位、加载和缓存这些文件的实用程序，确保它们在动画渲染时可用。有关数学工具的信息，请参阅数学工具。

目录结构概览

Manim 使用可配置的目录结构来组织不同类型的资源。这种结构允许系统自动查找资源，同时为自定义提供灵活性。

来源：manimlib/utils/directories.py13-46

目录配置

目录路径通过配置文件（custom_config.yml）中的 directories 部分进行配置。如果未显式配置，Manim 将使用合理的默认值。

目录类型	目的	默认位置	Getter 函数
raster_images	JPEG, PNG 图像	项目的 raster_images/	get_raster_image_dir()
vector_images	SVG 图像	项目的 vector_images/	get_vector_image_dir()
sounds	音频文件	项目的 sounds/	get_sound_dir()
output	渲染的视频/图像	项目的 output/	get_output_dir()
cache	持久化缓存存储	用户缓存目录	get_cache_dir()
temporary_storage	临时文件	系统临时目录	get_temp_dir()
downloads	下载的资源	用户缓存/下载	get_downloads_dir()
shader	GLSL 着色器文件	Manim 的 shader 目录	get_shader_dir()

来源：manimlib/utils/directories.py13-46

资源查找系统

Manim 实现了一个复杂的查找系统，用于根据文件名或 URL 查找资源。该系统无缝处理本地文件和远程资源。

实现此过程的关键函数是 find_file()，它：

1. 检查输入是否为 URL，如有必要则下载
2. 直接检查路径是否存在
3. 使用给定的扩展名在指定目录中搜索
4. 如果找到文件，则返回文件路径，否则引发错误

来源：manimlib/utils/file_ops.py26-57

使用资源类型

图像资源

Manim 通过专门的查找函数支持光栅图像（JPEG、PNG）和矢量图像（SVG）。

光栅图像

函数 get_full_raster_image_path() 在配置的光栅图像目录中搜索具有类似 .jpg、.png 和 .gif 的扩展名的图像文件。

来源：manimlib/utils/images.py16-21

矢量图像

函数 get_full_vector_image_path() 在配置的矢量图像目录中搜索具有类似 .svg 的扩展名的 SVG 文件。

来源：manimlib/utils/images.py24-29

声音资源

Manim 可以通过其声音管理实用程序将声音文件合并到动画中。

函数 get_full_sound_file_path() 用于查找配置的声音目录中的声音文件，而 play_sound() 则负责特定于平台的音频播放（Windows、macOS、Linux）。

来源：manimlib/utils/sounds.py11-40

URL 资源处理

Manim 可以直接使用来自 URL 的资源

1. 当将 URL 传递给 find_file() 时，它会将文件下载到 downloads 目录
2. 文件将使用 URL 的哈希值作为文件名进行保存
3. 该函数返回下载文件的路径

这允许无缝使用在线资源

来源：manimlib/utils/file_ops.py31-40

缓存系统

Manim 实现了磁盘缓存，通过存储昂贵操作的结果来提高性能。

缓存系统使用 diskcache 包，默认大小限制为 1GB。可以使用 @cache_on_disk 装饰器缓存函数。

来源：manimlib/utils/cache.py1-34

与 Manim 组件集成

资源管理系统与其他 Manim 组件紧密集成

与 Mobjects 的集成

资源管理对于基于图像和基于文本的 mobjects 尤其重要

• ImageMobject：使用 get_full_raster_image_path() 来定位图像文件
• SVGMobject：使用 get_full_vector_image_path() 来定位 SVG 文件
• Tex 和 Text：依赖于 TeX 模板和字体资源的正确位置

与场景输出的集成

SceneFileWriter 组件使用输出目录来存储渲染的视频和图像。

来源：manimlib/mobject/svg/old_tex_mobject.py1-333 manimlib/mobject/svg/special_tex.py1-83

最佳实践

1. 保持正确的目录结构：将资源放在其相应的目录中 (raster_images/, vector_images/, sounds/)。

2. 使用简单的文件名：在引用资源时，如果可能，只使用文件名，不带路径或扩展名。

3. 在配置中自定义目录：对于具有特定结构的工程，请在 custom_config.yml 中配置目录。

4. 缓存昂贵的操作：对于计算密集型函数，请使用 @cache_on_disk 装饰器。

5. 考虑远程资源：对于共享项目，考虑在线托管资源并按 URL 引用它们，以确保每个人都能访问相同的素材。

6. 定期清理缓存：对于长期运行的项目，如果磁盘空间成为问题，请偶尔清理缓存目录。

来源：manimlib/utils/cache.py32-34 manimlib/utils/directories.py13-46 manimlib/utils/file_ops.py26-57