clip-hier 0.1.0__tar.gz

clip_hier-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.eggs/
+.venv/
+venv/
+.pytest_cache/
+.ruff_cache/

clip_hier-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 songtang209
+
+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.

clip_hier-0.1.0/PKG-INFO

@@ -0,0 +1,85 @@
+Metadata-Version: 2.4
+Name: clip-hier
+Version: 0.1.0
+Summary: 图像标注 GT JSON（Picture_name/Tag/TagOption）读写工具集
+Author: songtang209
+License: MIT
+License-File: LICENSE
+Keywords: annotation,clip,ground-truth,image-classification,tagging
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Scientific/Engineering :: Image Recognition
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+
+# clip-hier
+
+图像标注 **GT JSON**（`Picture_name` / `Tag` / `TagOption`）的轻量读写工具集，零第三方依赖。
+
+适用于这种标注格式：
+
+```json
+{ "Picture_name": "a.jpg", "Tag": "Birds", "TagOption": "OutdoorScenes|SunriseSunset" }
+```
+
+- `Tag`：必选标签（`|` 分隔）。
+- `TagOption`：疑似/可接受标签（`|` 分隔）。
+
+## 安装
+
+```bash
+pip install clip-hier
+```
+
+## 用法
+
+### 读取目录
+
+```python
+from clip_hier import load_gt_tags
+
+gt = load_gt_tags("path/to/gt_json_dir")
+# {"a.jpg": {"path": ".../a.json", "tag": {"Birds"}, "tag_option": {"OutdoorScenes", "SunriseSunset"}}}
+```
+
+### 把 TagOption 提升为 Tag（并写回文件）
+
+当某个标签命中一张图的 `TagOption` 且不在 `Tag` 时，把它移入 `Tag` 并改写源 JSON：
+
+```python
+from clip_hier import GroundTruthTags
+
+gt = GroundTruthTags("path/to/gt_json_dir")
+
+# 推理得到某图 top1 预测后：
+changed = gt.promote_if_option("a.jpg", "OutdoorScenes")
+# 命中 TagOption -> 移入 Tag、写回磁盘，返回 True；否则 False
+```
+
+也可使用底层函数：
+
+```python
+from clip_hier import load_gt_tags, promote_tag_option
+
+gt = load_gt_tags("path/to/gt_json_dir")
+promote_tag_option(gt["a.jpg"], "OutdoorScenes")
+```
+
+## API
+
+| 名称 | 说明 |
+| --- | --- |
+| `load_gt_tags(json_dir)` | 读目录，返回 `{Picture_name: {"path", "tag", "tag_option"}}`（`tag`/`tag_option` 为 `set`） |
+| `promote_tag_option(entry, name)` | 把 `name` 从 `entry` 的 TagOption 移到 Tag，写回 JSON，返回是否改动 |
+| `GroundTruthTags(json_dir)` | 目录的封装：`get(name)`、`promote_if_option(name, tag)`、`in`、`len` |
+
+写回保留 JSON 中的其它字段；写盘成功后才同步内存，保证内存与磁盘一致。
+
+## License
+
+MIT

clip_hier-0.1.0/README.md

@@ -0,0 +1,66 @@
+# clip-hier
+
+图像标注 **GT JSON**（`Picture_name` / `Tag` / `TagOption`）的轻量读写工具集，零第三方依赖。
+
+适用于这种标注格式：
+
+```json
+{ "Picture_name": "a.jpg", "Tag": "Birds", "TagOption": "OutdoorScenes|SunriseSunset" }
+```
+
+- `Tag`：必选标签（`|` 分隔）。
+- `TagOption`：疑似/可接受标签（`|` 分隔）。
+
+## 安装
+
+```bash
+pip install clip-hier
+```
+
+## 用法
+
+### 读取目录
+
+```python
+from clip_hier import load_gt_tags
+
+gt = load_gt_tags("path/to/gt_json_dir")
+# {"a.jpg": {"path": ".../a.json", "tag": {"Birds"}, "tag_option": {"OutdoorScenes", "SunriseSunset"}}}
+```
+
+### 把 TagOption 提升为 Tag（并写回文件）
+
+当某个标签命中一张图的 `TagOption` 且不在 `Tag` 时，把它移入 `Tag` 并改写源 JSON：
+
+```python
+from clip_hier import GroundTruthTags
+
+gt = GroundTruthTags("path/to/gt_json_dir")
+
+# 推理得到某图 top1 预测后：
+changed = gt.promote_if_option("a.jpg", "OutdoorScenes")
+# 命中 TagOption -> 移入 Tag、写回磁盘，返回 True；否则 False
+```
+
+也可使用底层函数：
+
+```python
+from clip_hier import load_gt_tags, promote_tag_option
+
+gt = load_gt_tags("path/to/gt_json_dir")
+promote_tag_option(gt["a.jpg"], "OutdoorScenes")
+```
+
+## API
+
+| 名称 | 说明 |
+| --- | --- |
+| `load_gt_tags(json_dir)` | 读目录，返回 `{Picture_name: {"path", "tag", "tag_option"}}`（`tag`/`tag_option` 为 `set`） |
+| `promote_tag_option(entry, name)` | 把 `name` 从 `entry` 的 TagOption 移到 Tag，写回 JSON，返回是否改动 |
+| `GroundTruthTags(json_dir)` | 目录的封装：`get(name)`、`promote_if_option(name, tag)`、`in`、`len` |
+
+写回保留 JSON 中的其它字段；写盘成功后才同步内存，保证内存与磁盘一致。
+
+## License
+
+MIT

clip_hier-0.1.0/pyproject.toml

@@ -0,0 +1,29 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "clip-hier"
+version = "0.1.0"
+description = "图像标注 GT JSON（Picture_name/Tag/TagOption）读写工具集"
+readme = "README.md"
+requires-python = ">=3.8"
+license = { text = "MIT" }
+authors = [{ name = "songtang209" }]
+keywords = ["ground-truth", "annotation", "tagging", "clip", "image-classification"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Topic :: Scientific/Engineering :: Image Recognition",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/clip_hier"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src", "README.md", "LICENSE"]

clip_hier-0.1.0/src/clip_hier/__init__.py

@@ -0,0 +1,14 @@
+"""clip-hier：图像标注 GT JSON（Picture_name / Tag / TagOption）读写工具集。"""
+
+from __future__ import annotations
+
+from .gt import GroundTruthTags, load_gt_tags, promote_tag_option
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "GroundTruthTags",
+    "load_gt_tags",
+    "promote_tag_option",
+    "__version__",
+]

clip_hier-0.1.0/src/clip_hier/gt.py

@@ -0,0 +1,102 @@
+"""图像标注 GT JSON（Picture_name / Tag / TagOption）的读写工具。
+
+每个 GT JSON 形如：
+
+    {"Picture_name": "a.jpg", "Tag": "Birds", "TagOption": "OutdoorScenes|SunriseSunset"}
+
+其中 ``Tag`` / ``TagOption`` 均为 "|" 分隔的字符串，可缺省：
+
+- ``Tag``：必选标签（参与召回评测）。
+- ``TagOption``：疑似/可接受标签（精度免责）。
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from typing import Dict, Optional
+
+
+def _split_tags(value: str) -> list:
+    return [t.strip() for t in value.split("|") if t.strip()]
+
+
+def load_gt_tags(json_dir: str) -> Dict[str, dict]:
+    """读取 GT JSON 目录，返回 ``{Picture_name: {"path", "tag", "tag_option"}}``。
+
+    ``tag`` / ``tag_option`` 为 ``set``，``path`` 为该条对应的 JSON 文件路径
+    （便于后续写回）。无 ``Picture_name`` 的文件会被跳过。
+    """
+    gt: Dict[str, dict] = {}
+    for fname in os.listdir(json_dir):
+        if not fname.lower().endswith(".json"):
+            continue
+        fpath = os.path.join(json_dir, fname)
+        with open(fpath, "r", encoding="utf-8") as f:
+            data = json.load(f)
+        name = data.get("Picture_name", "").strip()
+        if not name:
+            continue
+        gt[name] = {
+            "path": fpath,
+            "tag": set(_split_tags(data.get("Tag", ""))),
+            "tag_option": set(_split_tags(data.get("TagOption", ""))),
+        }
+    return gt
+
+
+def promote_tag_option(entry: dict, name: str) -> bool:
+    """把 ``name`` 从 ``entry`` 的 TagOption 提升到 Tag，并写回对应 JSON 文件。
+
+    仅当 ``name`` 当前在 ``tag_option`` 且不在 ``tag`` 时才动作。写盘成功后才
+    同步内存中的 ``entry["tag"]`` / ``entry["tag_option"]``，保证内存与磁盘一致。
+
+    返回是否真正发生了改动（无需改动或写盘失败均返回 ``False``）。
+    """
+    if name in entry["tag"] or name not in entry["tag_option"]:
+        return False
+    try:
+        with open(entry["path"], "r", encoding="utf-8") as f:
+            data = json.load(f)
+        tags = _split_tags(data.get("Tag", ""))
+        opts = _split_tags(data.get("TagOption", ""))
+        if name not in tags:
+            tags.append(name)
+        opts = [t for t in opts if t != name]
+        data["Tag"] = "|".join(tags)
+        data["TagOption"] = "|".join(opts)
+        with open(entry["path"], "w", encoding="utf-8") as f:
+            json.dump(data, f, ensure_ascii=False, indent=2)
+    except Exception:
+        return False
+    entry["tag_option"].discard(name)
+    entry["tag"].add(name)
+    return True
+
+
+class GroundTruthTags:
+    """加载一个 GT JSON 目录，并支持按预测把 TagOption 提升为 Tag。"""
+
+    def __init__(self, json_dir: str):
+        self.json_dir = json_dir
+        self.entries = load_gt_tags(json_dir)
+
+    def __len__(self) -> int:
+        return len(self.entries)
+
+    def __contains__(self, picture_name: str) -> bool:
+        return picture_name in self.entries
+
+    def get(self, picture_name: str) -> Optional[dict]:
+        """按 ``Picture_name`` 取出条目，不存在返回 ``None``。"""
+        return self.entries.get(picture_name)
+
+    def promote_if_option(self, picture_name: str, tag: str) -> bool:
+        """若 ``tag`` 命中该图 TagOption（且不在 Tag）则提升并写回 JSON。
+
+        图片不存在或无需改动时返回 ``False``。
+        """
+        entry = self.entries.get(picture_name)
+        if entry is None:
+            return False
+        return promote_tag_option(entry, tag)