Upload README.md with huggingface_hub

README.md

@@ -0,0 +1,129 @@
+---
+library_name: pytorch
+tags:
+  - scene-graph-generation
+  - sgg
+  - remote-sensing
+  - pretrained-weights
+---
+
+# SGGLab 模型权重
+
+本仓库用于集中存放 **SGGLab 的模型组件预训练权重**与**完成训练的模型权重**。仓库仅提供权重文件；模型结构、配置、数据预处理和推理代码由对应的 SGGLab 项目版本提供。
+
+## 权重类型
+
+- `pretrained/`：可被不同模型复用的组件预训练权重，例如 PPG 等辅助模块。
+- `models/`：完成训练、可用于评估或继续训练的模型权重。
+
+## 当前文件
+
+| 文件 | 类型 | 边界框表示 | 说明 |
+| --- | --- | --- | --- |
+| `pretrained/PPG/PPG_HBB_model.pth` | PPG 组件权重 | HBB | 用于水平边界框任务 |
+| `pretrained/PPG/PPG_OBB_model.pth` | PPG 组件权重 | OBB | 用于旋转边界框任务 |
+
+其中：
+
+- **HBB**：Horizontal Bounding Box，水平边界框。
+- **OBB**：Oriented Bounding Box，旋转边界框。
+- **PPG**：作为场景图生成流程中的预训练组件使用，不能脱离对应模型代码直接完成推理。
+
+## 目录约定
+
+```text
+.
+├── pretrained/
+│   └── <component>/
+│       └── <component>_<variant>_model.pth
+└── models/
+    └── <model>/
+        └── <dataset>/
+            └── <box_type>/
+                └── <task>.pth
+```
+
+推荐使用以下取值：
+
+- `<component>`：组件名称，例如 `PPG`。
+- `<model>`：模型或方法名称，例如 `RPCM`。
+- `<dataset>`：训练使用的数据集名称。
+- `<box_type>`：`HBB` 或 `OBB`。
+- `<task>`：`PredCls`、`SGCls` 或 `SGDet`。
+
+新增权重时，请同时在“权重清单”中记录其训练配置、适用代码版本和评估结果，避免仅凭文件名判断兼容性。
+
+## 下载
+
+安装 Hugging Face Hub 客户端：
+
+```bash
+uv add huggingface-hub
+```
+
+下载单个文件：
+
+```python
+from huggingface_hub import hf_hub_download
+
+checkpoint_path = hf_hub_download(
+    repo_id="<namespace>/<repository>",
+    filename="pretrained/PPG/PPG_HBB_model.pth",
+)
+```
+
+下载整个仓库：
+
+```python
+from huggingface_hub import snapshot_download
+
+repository_path = snapshot_download(repo_id="<namespace>/<repository>")
+```
+
+请将示例中的 `<namespace>/<repository>` 替换为本仓库在 Hugging Face Hub 上的实际 ID。
+
+## 加载
+
+权重必须由与其结构匹配的 PyTorch 模块加载：
+
+```python
+import torch
+
+checkpoint = torch.load(
+    "pretrained/PPG/PPG_HBB_model.pth",
+    map_location="cpu",
+    weights_only=True,
+)
+model.load_state_dict(checkpoint)
+```
+
+不同权重可能保存为纯 `state_dict`，也可能包含 `state_dict`、优化器状态和训练轮次等字段。加载前应先确认对应训练代码的保存格式。不要将 HBB 与 OBB 权重混用，也不要假设不同提交或不同配置生成的同名模块必然兼容。
+
+## 权重清单
+
+发布完整模型时，建议按下表补充信息：
+
+| 模型 | 数据集 | 任务 | 边界框 | 文件 | 代码版本 | 指标 |
+| --- | --- | --- | --- | --- | --- | --- |
+| 待发布 | — | — | — | — | — | — |
+
+每个权重至少应记录：
+
+1. 模型与配置名称；
+2. 数据集及其版本或划分；
+3. `PredCls`、`SGCls` 或 `SGDet` 任务；
+4. HBB 或 OBB 边界框表示；
+5. 对应代码仓库与提交版本；
+6. 主要评估指标；
+7. 权重来源、许可证及使用限制。
+
+## 兼容性与安全
+
+- `.pth` 文件与模型定义和代码版本强相关，请优先使用权重条目中标注的版本。
+- PyTorch 权重可能包含可执行的序列化对象。只加载可信来源的文件，并在格式允许时使用 `weights_only=True`。
+- 本仓库中的权重不自动继承训练代码或数据集的许可证。使用前请分别确认代码、数据集和权重的授权条件。
+- 若权重由第三方项目转换或派生，请在对应条目中保留原始来源和许可证说明。
+
+## 引用
+
+如在研究中使用本仓库中的权重，请同时引用对应模型、数据集和原始论文。具体引用信息应随每个模型权重条目一并提供。