GitHub Contribution 3D 可视化工具

将你的 GitHub 年度贡献历史转换为精美的 3D 打印模型。

安装

环境要求

• Python 3.13
• uv 包管理器

安装步骤

# 克隆仓库
git clone https://github.com/Aye10032/github-history-3d.git
cd github-history-3d

# 安装依赖
uv sync

# 配置 GitHub Token
cp .env.example .env
# 编辑 .env 文件，填入你的 GitHub Token

获取 GitHub Token

1. 访问 GitHub Settings > Developer settings > Personal access tokens
2. 创建新 token（Classic）
3. 无需任何权限勾选（只读取公开数据）
4. 复制 token 到 .env 文件

使用

基础用法

# 生成指定用户和年份的 3D 模型
uv run python main.py <username> <year>

# 示例
uv run python main.py Aye10032 2025

可选参数

# 自定义参数
uv run python main.py <username> <year> --margin 2.0 --base-height 1.5

# 查看详细日志
uv run python main.py <username> <year> -v

参数说明

参数	说明	默认值
username	GitHub 用户名	必填
year	年份	必填
--margin	贡献柱与底座边缘的距离 (mm)	2.0
--base-height	嵌入底座的深度 (mm)	2.5
-v, --verbose	显示详细日志	False

输出

生成的 3MF 文件保存在：

output/<year>/<username>_<year>.3mf

可使用 3D 打印切片软件（如 PrusaSlicer、Bambu Studio）打开查看和打印。

模型说明

尺寸参考

• 典型尺寸：约 120mm × 35mm × 50mm
• 底座：118mm × 26mm × 10mm（梯台）
• 贡献柱：2mm × 2mm，高度根据贡献数量变化

颜色

• 底座：白色
• 贡献柱：透明
• 装饰（logo/文字）：黑色

许可证

MIT License