vdschema 0.1.0__tar.gz

vdschema-0.1.0/PKG-INFO

@@ -0,0 +1,62 @@
+Metadata-Version: 2.4
+Name: vdschema
+Version: 0.1.0
+Summary: Unified annotation schema and JSONL IO for vision datasets.
+Author-email: xiaokun1 <xiaokun1@sensetime.com>
+Project-URL: Homepage, https://github.com/REPLACE_OWNER/vdschema
+Project-URL: Repository, https://github.com/REPLACE_OWNER/vdschema
+Project-URL: Issues, https://github.com/REPLACE_OWNER/vdschema/issues
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: numpy>=1.26
+Requires-Dist: pycocotools>=2.0.7
+
+# vdschema
+
+Unified annotation schema and JSONL IO for vision datasets.
+
+`vdschema` can be used by annotation pipelines to write JSONL annotation files
+and by training pipelines to read those files back into typed Python objects.
+
+## Install
+
+```bash
+uv sync
+```
+
+## Basic Usage
+
+```python
+from vdschema import AnnotationReader, AnnotationWriter, DetectionAnnotation
+
+writer = AnnotationWriter("output/detection/annotation_meta.jsonl", DetectionAnnotation)
+writer.append(
+    filename="images/sample.jpg",
+    width=640,
+    height=480,
+    instances=[
+        {"id": 0, "category_id": 1, "bbox": [10, 20, 100, 200]},
+    ],
+)
+writer.save()
+
+annotations = AnnotationReader(
+    "output/detection/annotation_meta.jsonl",
+    DetectionAnnotation,
+).load()
+```
+
+## Development
+
+```bash
+uv sync --group dev
+uv run python test_annotation_format.py
+uv run ruff check .
+uv build
+```
+
+## Publishing
+
+This repository includes a GitHub Actions workflow for publishing to PyPI with
+trusted publishing. Configure the PyPI project and GitHub environment before
+creating a release.

vdschema-0.1.0/README.md

@@ -0,0 +1,49 @@
+# vdschema
+
+Unified annotation schema and JSONL IO for vision datasets.
+
+`vdschema` can be used by annotation pipelines to write JSONL annotation files
+and by training pipelines to read those files back into typed Python objects.
+
+## Install
+
+```bash
+uv sync
+```
+
+## Basic Usage
+
+```python
+from vdschema import AnnotationReader, AnnotationWriter, DetectionAnnotation
+
+writer = AnnotationWriter("output/detection/annotation_meta.jsonl", DetectionAnnotation)
+writer.append(
+    filename="images/sample.jpg",
+    width=640,
+    height=480,
+    instances=[
+        {"id": 0, "category_id": 1, "bbox": [10, 20, 100, 200]},
+    ],
+)
+writer.save()
+
+annotations = AnnotationReader(
+    "output/detection/annotation_meta.jsonl",
+    DetectionAnnotation,
+).load()
+```
+
+## Development
+
+```bash
+uv sync --group dev
+uv run python test_annotation_format.py
+uv run ruff check .
+uv build
+```
+
+## Publishing
+
+This repository includes a GitHub Actions workflow for publishing to PyPI with
+trusted publishing. Configure the PyPI project and GitHub environment before
+creating a release.

vdschema-0.1.0/pyproject.toml

@@ -0,0 +1,43 @@
+[project]
+name = "vdschema"
+version = "0.1.0"
+description = "Unified annotation schema and JSONL IO for vision datasets."
+readme = "README.md"
+authors = [
+    { name = "xiaokun1", email = "xiaokun1@sensetime.com" }
+]
+requires-python = ">=3.12"
+dependencies = [
+    "numpy>=1.26",
+    "pycocotools>=2.0.7",
+]
+
+[project.urls]
+Homepage = "https://github.com/REPLACE_OWNER/vdschema"
+Repository = "https://github.com/REPLACE_OWNER/vdschema"
+Issues = "https://github.com/REPLACE_OWNER/vdschema/issues"
+
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0",
+    "ruff>=0.8.0",
+    "build>=1.2.0",
+    "twine>=5.0.0",
+]
+
+[tool.setuptools]
+packages = ["vdschema"]
+
+[tool.setuptools.package-data]
+vdschema = ["*.json"]
+
+[tool.pytest.ini_options]
+testpaths = ["."]
+python_files = ["test_*.py"]
+
+[tool.ruff]
+line-length = 88

vdschema-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

vdschema-0.1.0/vdschema/__init__.py

@@ -0,0 +1,56 @@
+"""Unified annotation schema and JSONL IO."""
+
+from .annotation_io import AnnotationReader, AnnotationWriter
+from .annotation_format import (
+    ANNOTATION_CLASSES,
+    ActionAnnotation,
+    ActionEvent,
+    BaseAnnotation,
+    Bbox,
+    ClassificationAnnotation,
+    ClassificationHead,
+    ContentImage,
+    ContentText,
+    ConversationAnnotation,
+    ConversationRole,
+    ConversationTurn,
+    DataFormatError,
+    DetectionAnnotation,
+    Instance,
+    Keypoint,
+    KeypointAnnotation,
+    Relationship,
+    RelationshipAnnotation,
+    SegmentationAnnotation,
+    SegmentationRLE,
+    TrackItem,
+    VlmAnnotation,
+)
+
+__all__ = [
+    "ANNOTATION_CLASSES",
+    "ActionAnnotation",
+    "ActionEvent",
+    "AnnotationReader",
+    "AnnotationWriter",
+    "BaseAnnotation",
+    "Bbox",
+    "ClassificationAnnotation",
+    "ClassificationHead",
+    "ContentImage",
+    "ContentText",
+    "ConversationAnnotation",
+    "ConversationRole",
+    "ConversationTurn",
+    "DataFormatError",
+    "DetectionAnnotation",
+    "Instance",
+    "Keypoint",
+    "KeypointAnnotation",
+    "Relationship",
+    "RelationshipAnnotation",
+    "SegmentationAnnotation",
+    "SegmentationRLE",
+    "TrackItem",
+    "VlmAnnotation",
+]

vdschema-0.1.0/vdschema/annotation_dict.json

@@ -0,0 +1,266 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://example.org/schemas/label-dict.schema.json",
+  "title": "标注标签词典",
+  "description": "数据集级检测类别、图像分类、关系类型、动作标签等 ID 与名称对照。",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "annotation_schema_ref": {
+      "type": "string",
+      "description": "对应标注 schema 的 $id 或版本摘要。",
+      "examples": [
+        "https://example.org/schemas/image_schema.json",
+        "https://example.org/schemas/video_schema.json"
+      ]
+    },
+    "detection": {
+      "type": "array",
+      "description": "检测/实例类别词表；与标注 **`instances[].category_id`** 对应。",
+      "minItems": 1,
+      "items": {
+        "$ref": "#/$defs/category_entry"
+      }
+    },
+    "classification": {
+      "type": "array",
+      "description": "图像级多分类词表；与标注顶层 **`categories[]`**（按 **`category_type`**）对应。",
+      "minItems": 1,
+      "items": {
+        "$ref": "#/$defs/classification_entry"
+      }
+    },
+    "relationship": {
+      "type": "array",
+      "description": "关系类型；标注 **`relationships[].relation_type`** 等与词表对齐（字段含义见 **`relationship_entry`**）。",
+      "minItems": 1,
+      "items": {
+        "$ref": "#/$defs/relationship_entry"
+      }
+    },
+    "action": {
+      "type": "array",
+      "description": "动作/事件类标签词表（若标注侧含对应 ID 字段则与之对齐）。",
+      "minItems": 1,
+      "items": {
+        "$ref": "#/$defs/action_entry"
+      }
+    },
+    "dataset_metadata": {
+      "$ref": "#/$defs/dataset_metadata",
+      "description": "数据来源与许可等（可选）。"
+    }
+  },
+  "allOf": [
+    {
+      "description": "下列词表至少须出现其一，且出现时数组须非空：**`detection`** / **`classification`** / **`relationship`** / **`action`**。",
+      "anyOf": [
+        {
+          "required": [
+            "detection"
+          ]
+        },
+        {
+          "required": [
+            "classification"
+          ]
+        },
+        {
+          "required": [
+            "relationship"
+          ]
+        },
+        {
+          "required": [
+            "action"
+          ]
+        }
+      ]
+    }
+  ],
+  "examples": [
+    {
+      "annotation_schema_ref": "https://example.org/schemas/perception-annotation.schema.json",
+      "detection": [
+        {
+          "category_id": 1,
+          "category_name": "person"
+        },
+        {
+          "category_id": 2,
+          "category_name": "car"
+        }
+      ],
+      "classification": [
+        {
+          "category_type": "scene",
+          "values": [
+            {
+              "category_id": 10,
+              "category_name": "intersection"
+            }
+          ]
+        },
+        {
+          "category_type": "weather",
+          "values": [
+            {
+              "category_id": 3,
+              "category_name": "sunny"
+            },
+            {
+              "category_id": 4,
+              "category_name": "cloudy"
+            }
+          ]
+        }
+      ],
+      "relationship": [
+        {
+          "relationship_id": 0,
+          "relationship_name": "左边"
+        },
+        {
+          "relationship_id": 1,
+          "relationship_name": "右边"
+        }
+      ],
+      "action": [
+        {
+          "action_id": 3,
+          "action_name": "walking"
+        },
+        {
+          "action_id": 4,
+          "action_name": "talking"
+        }
+      ],
+      "dataset_metadata": {
+        "source": "internal_lab",
+        "language": "zh-CN",
+        "license": "CC-BY-4.0",
+        "difficulty": "medium",
+        "quality_score": 0.92
+      }
+    }
+  ],
+  "$defs": {
+    "category_entry": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "category_id": {
+          "type": "integer",
+          "description": "类别 ID（≥0）。",
+          "minimum": 0
+        },
+        "category_name": {
+          "type": "string",
+          "description": "类别名称。",
+          "minLength": 1
+        }
+      },
+      "required": [
+        "category_id",
+        "category_name"
+      ]
+    },
+    "classification_entry": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "category_type": {
+          "type": "string",
+          "description": "分类头键，须与标注 **`categories[].category_type`** 一致。",
+          "minLength": 1,
+          "examples": [
+            "scene",
+            "weather"
+          ]
+        },
+        "values": {
+          "type": "array",
+          "description": "该头下允许的取值（结构与 **`category_entry`** 相同）。",
+          "minItems": 1,
+          "items": {
+            "$ref": "#/$defs/category_entry"
+          }
+        }
+      },
+      "required": [
+        "category_type",
+        "values"
+      ]
+    },
+    "relationship_entry": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "relationship_id": {
+          "type": "integer",
+          "description": "关系 ID（≥0）。",
+          "minimum": 0
+        },
+        "relationship_name": {
+          "type": "string",
+          "description": "关系名称。",
+          "minLength": 1,
+          "examples": [
+            "靠近",
+            "左边"
+          ]
+        }
+      },
+      "required": [
+        "relationship_id",
+        "relationship_name"
+      ]
+    },
+    "action_entry": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "action_id": {
+          "type": "integer",
+          "description": "动作标签 ID（≥0）。",
+          "minimum": 0
+        },
+        "action_name": {
+          "type": "string",
+          "description": "动作名称。",
+          "minLength": 1
+        }
+      },
+      "required": [
+        "action_id",
+        "action_name"
+      ]
+    },
+    "dataset_metadata": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "source": {
+          "type": "string",
+          "description": "数据来源。"
+        },
+        "language": {
+          "type": "string",
+          "description": "主语言，如 zh-CN。"
+        },
+        "license": {
+          "type": "string",
+          "description": "许可证。"
+        },
+        "difficulty": {
+          "type": "string",
+          "description": "难度（自定义枚举）。"
+        },
+        "quality_score": {
+          "type": "number",
+          "description": "质量分（可选）。"
+        }
+      }
+    }
+  }
+}