Metadata-Version: 2.4
Name: desmos_polychoron_renderer
Version: 0.4.0
Summary: 从 4OFF 文件生成 Desmos 3D 图表的小工具，顺便附带一些 Desmos 相关的爬虫工具。
Keywords: desmos,polychoron,4d,renderer
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.12
Requires-Python: <4.0,>=3.8
Description-Content-Type: text/markdown
Requires-Dist: cloup<4.0,>=3.1.0
Requires-Dist: requests<3.0,>=2.34.2
Requires-Dist: rich<16.0,>=15.0.0
Requires-Dist: urllib3<2.0,>=1.26

# Desmos Polychoron Renderer

从 **4OFF** 文件生成 **Desmos 3D** 图表的命令行工具，同时附带一组 Desmos 相关的辅助爬虫工具（登录、保存、获取图表）。

## 功能概览

| 子命令 | 作用 |
|--------|------|
| `login` | 使用邮箱密码登录 Desmos，导出 `sid` Cookie |
| `save` | 将本地 `graph.json` 上传/更新到 Desmos（支持新建、复制、更新） |
| `get` | 下载指定 Desmos 图表的 JSON 数据到本地 |
| `off2graph` | 将 4D 多胞体（Polychoron）的 **4OFF** 文件转换为 Desmos 可用的 `graph.json` |

---

## 安装

要求 Python **3.8 ~ 3.14**。

´´´bash
pip install desmos_polychoron_renderer
´´´

安装完成后，命令行入口为：

´´´bash
desmos-render-polychoron -h
´´´

---

## 依赖

- `cloup` — 命令行参数解析
- `requests` — HTTP 请求
- `rich` — 终端美化输出
- `urllib3` — 网络底层（版本限制 `<2.0` 以避免已知通信 Bug）

---

## 快速开始

### 1. 登录 Desmos 获取会话

´´´bash
desmos-render-polychoron login -e "your@email.com" -p "your_password"
´´´

### 2. 将 4OFF 转为 Desmos 图表

´´´bash
desmos-render-polychoron off2graph -i ./16-cell.off -v
´´´

### 3. 上传到 Desmos（新建图表）

´´´bash
desmos-render-polychoron save -t "My 16-Cell"
´´´

### 4. 下载已有图表（额外功能）

´´´bash
desmos-render-polychoron get -g 66bahrmrxa --2d -o ./backup.json
´´´

---

## 命令详解

### `login` — 登录并获取 Session

´´´bash
desmos-render-polychoron login \
 --email    "your@email.com" \
 --password "your_password" \
 --output   ./sid.txt \
 --verbose
´´´

| 选项 | 简写 | 说明 |
|------|------|------|
| `--email` | `-e` | **必填** Desmos 账号邮箱 |
| `--password` | `-p` | **必填** Desmos 账号密码 |
| `--output` | `-o` | 保存 `sid` Cookie 的文件路径（默认 `./sid.txt`） |
| `--verbose` | `-v` | 显示详细信息 |

---

### `save` — 保存图表到 Desmos

支持三种模式：**新建**（默认）、**复制**、**更新**。

´´´bash
# 新建图表
desmos-render-polychoron save -s ./sid.txt -g ./graph.json --new -t "标题"

# 复制图表
desmos-render-polychoron save -s ./sid.txt --copy --parent 66bahrmrxa -t "副本"

# 更新已有图表
desmos-render-polychoron save -s ./sid.txt -g ./graph.json --update --hash 73wketgi3c
´´´

| 选项 | 简写 | 说明 |
|------|------|------|
| `--sid-file` | `-s` | `sid` 文件路径（默认 `./sid.txt`） |
| `--graph-file` | `-g` | 本地 `graph.json` 路径（`--copy` 模式下不需要） |
| `--new` / `--copy` / `--update` | `-n` / `-c` / `-u` | 操作模式（三者互斥，默认 `--new`） |
| `--hash` | `-H` | 图表 ID（复制/更新时必填） |
| `--title` | `-t` | 图表标题（默认 `未命名图表`） |
| `--parent` | `-p` | 父图表 ID（仅 `--copy` 模式） |
| `--3d` / `--2d` / `--auto` | | 产品类型（默认 `--auto` 自动检测） |
| `--verbose` | `-v` | 显示详细信息 |

---

### `get` — 下载 Desmos 图表

´´´bash
desmos-render-polychoron get \
 --graph-id 66bahrmrxa \
 --output ./backup.json \
 --3d \
 --verbose
´´´

| 选项 | 简写 | 说明 |
|------|------|------|
| `--graph-id` | `-g` | **必填** 图表 ID（如 `66bahrmrxa`） |
| `--output` | `-o` | 输出文件路径（默认 `<graph_id>.json`） |
| `--3d` / `--2d` | | 产品类型（默认 `--3d`） |
| `--no-pretty` | `-P` | 输出紧凑 JSON（默认格式化） |
| `--verbose` | `-v` | 显示详细信息 |

---

### `off2graph` — 4OFF 转 Desmos Graph

核心功能：将四维多胞体的 **4OFF** 文件转换为 Desmos 3D 可渲染的 `graph.json`。

´´´bash
desmos-render-polychoron off2graph \
 --input ./600-cell.off \
 --output ./graph.json \
 --point-color "#6042a6" \
 --edge-color "#2d70b3" \
 --seed 42
´´´

| 选项 | 简写 | 说明 |
|------|------|------|
| `--input` | `-i` | **必填** 输入 4OFF 文件路径 |
| `--output` | `-o` | 输出 `graph.json` 路径（默认 `./graph.json`） |
| `--point-color` | | 投影点颜色（默认 `#6042a6`） |
| `--edge-color` | | 无颜色模式下边的颜色（默认 `#2d70b3`） |
| `--no-color` | `-C` | 禁用胞着色和分段，所有边统一颜色 |
| `--no-rotate` | `-R` | 禁用旋转滑块，硬编码四维点集 |
| `--no-proj` | `-P` | 硬编码投影模式，预计算三维坐标 |
| `--proj-dist` | `-d` | 硬编码投影距离（默认 `滑块最小值 × 1.1`） |
| `--theta` | | 固定旋转角度，格式 `"xw,yw,zw"`（弧度） |
| `--seed` | `-S` | 随机数种子（影响 `randomSeed` 和颜色分配） |
| `--color-seed` | `-s` | 颜色分配专用种子（优先级高于 `--seed`） |
| `--verbose` | `-v` | 显示详细信息 |

#### 硬编码模式说明

- **`--no-rotate`**：不生成旋转矩阵和滑块，四维坐标固定。可配合 `--theta` 指定固定旋转角。
- **`--no-proj`**：进一步预计算三维投影坐标，移除投影函数和距离滑块。适合生成**静态**展示图表。
- **`--theta`** 示例：`--theta "1.2,0.5,0.8"` 分别对应 xw、yw、zw 平面旋转角（弧度）。

---

## 4OFF 文件格式

4OFF 是 OFF（Object File Format）的四维扩展，用于描述**多胞体（Polychoron）**。

´´´text
4OFF
# 顶点数 面数 边数 胞数
V F E C
# 顶点坐标（4 维：x y z w）
x1 y1 z1 w1
x2 y2 z2 w2
...
# 面（面的顶点数 + 顶点索引列表）
...
# 胞（胞的面数 + 面索引列表）
...
´´´

> 工具会自动解析顶点与边，生成 Desmos 3D 中可用的点列表与线段列表。

---

## 注意事项

1. **urllib3 版本限制**：由于 urllib3 `>=2.0` 存在未定位的网络通信 Bug，依赖已强制限制为 `<2.0`。
2. **登录安全**：`sid.txt` 包含有效会话 Cookie，请妥善保管，不要提交到公共仓库。
3. **Desmos 限制**：Desmos 性能较差，复杂多胞体（如 一百二十胞体）可能导致严重卡顿，建议配合 `--no-rotate` / `--no-proj` 减少计算量。
