synapse-sdk 1.0.0a23__py3-none-any.whl → 2025.12.3__py3-none-any.whl

synapse_sdk/utils/converters/dm/tools/polyline.py

@@ -0,0 +1,124 @@
+"""
+Polyline Tool Processor
+
+Created: 2025-12-12
+
+Conversion Rules (see data-model.md 4.2):
+V1 → V2:
+  - coordinate [{x, y, id}, ...] → data [[x, y], ...]
+  - classification.class → classification
+  - classification.{other} → attrs[{name, value}]
+
+V2 → V1:
+  - data [[x, y], ...] → coordinate [{x, y, id}, ...]
+  - classification → classification.class
+  - attrs[{name, value}] → classification.{name: value} (excluding special attrs)
+"""
+
+from typing import Any
+
+from ..utils import generate_random_id
+
+
+class PolylineProcessor:
+    """Polyline Tool Processor
+
+    V1 coordinate: [{x, y, id}, ...]
+    V2 data: [[x, y], ...]
+
+    Same data structure as polygon, only tool_name differs.
+    """
+
+    tool_name = 'polyline'
+
+    # V1 meta fields (not stored in attrs)
+    _META_FIELDS = {'isLocked', 'isVisible', 'isValid', 'isDrawCompleted', 'label', 'id', 'tool'}
+
+    # Special attrs not restored to V1 classification (_ prefix)
+    _INTERNAL_ATTR_PREFIX = '_'
+
+    def to_v2(self, v1_annotation: dict[str, Any], v1_data: dict[str, Any]) -> dict[str, Any]:
+        """Convert V1 polyline to V2
+
+        Args:
+            v1_annotation: V1 annotations[] item
+            v1_data: V1 annotationsData[] item (same ID)
+
+        Returns:
+            V2 format polyline annotation
+        """
+        coordinate = v1_data.get('coordinate', [])
+        classification_obj = v1_annotation.get('classification') or {}
+
+        # V2 data: [[x, y], ...] - extract only x, y from coordinate array
+        data = []
+        for point in coordinate:
+            if isinstance(point, dict):
+                data.append([point.get('x', 0), point.get('y', 0)])
+
+        # Build V2 attrs
+        attrs: list[dict[str, Any]] = []
+
+        # Add other classification properties to attrs (excluding class)
+        for key, value in classification_obj.items():
+            if key != 'class':
+                attrs.append({'name': key, 'value': value})
+
+        # Build V2 annotation
+        return {
+            'id': v1_annotation.get('id', ''),
+            'classification': classification_obj.get('class', ''),
+            'attrs': attrs,
+            'data': data,
+        }
+
+    def to_v1(self, v2_annotation: dict[str, Any]) -> tuple[dict[str, Any], dict[str, Any]]:
+        """Convert V2 polyline to V1
+
+        Args:
+            v2_annotation: V2 annotation object
+
+        Returns:
+            (V1 annotation, V1 annotationData) tuple
+        """
+        annotation_id = v2_annotation.get('id', '')
+        classification_str = v2_annotation.get('classification', '')
+        attrs = v2_annotation.get('attrs', [])
+        data = v2_annotation.get('data', [])
+
+        # Build V1 coordinate: [[x, y], ...] → [{x, y, id}, ...]
+        coordinate: list[dict[str, Any]] = []
+        for point in data:
+            if isinstance(point, list) and len(point) >= 2:
+                coordinate.append({
+                    'x': point[0],
+                    'y': point[1],
+                    'id': generate_random_id(),
+                })
+
+        # Build V1 classification
+        classification: dict[str, Any] = {'class': classification_str}
+
+        # Restore properties from attrs
+        for attr in attrs:
+            name = attr.get('name', '')
+            value = attr.get('value')
+
+            if not name.startswith(self._INTERNAL_ATTR_PREFIX):
+                # Add non-internal attrs to classification
+                classification[name] = value
+
+        # V1 annotation (meta info)
+        v1_annotation: dict[str, Any] = {
+            'id': annotation_id,
+            'tool': self.tool_name,
+            'classification': classification,
+        }
+
+        # V1 annotationData (coordinate info)
+        v1_data: dict[str, Any] = {
+            'id': annotation_id,
+            'coordinate': coordinate,
+        }
+
+        return v1_annotation, v1_data

synapse_sdk/utils/converters/dm/tools/prompt.py

@@ -0,0 +1,94 @@
+"""
+Prompt Tool Processor
+
+Created: 2025-12-12
+
+Conversion Rules (see data-model.md 9.10):
+V1 → V2:
+  - input → data.input
+  - Other fields from annotationsData → preserved in data
+  - classification.class → classification
+  - classification.{other} → attrs[{name, value}]
+
+V2 → V1:
+  - data.input → input
+  - Other fields from data → preserved in annotationsData
+  - classification → classification.class
+  - attrs[{name, value}] → classification.{name: value}
+"""
+
+from typing import Any
+
+
+class PromptProcessor:
+    """Prompt Tool Processor
+
+    V1 annotationsData: {id, tool, input: [{type, value, changeHistory}]}
+    V2 data: {input: [...], model?, displayName?, generatedBy?, timestamp?}
+
+    Prompt annotation data conversion.
+    """
+
+    tool_name = 'prompt'
+
+    _META_FIELDS = {'isLocked', 'isVisible', 'isValid', 'isDrawCompleted', 'label', 'id', 'tool'}
+    _INTERNAL_ATTR_PREFIX = '_'
+    # Fields to copy from annotationsData to V2 data
+    _DATA_FIELDS = {'input', 'model', 'displayName', 'generatedBy', 'timestamp'}
+
+    def to_v2(self, v1_annotation: dict[str, Any], v1_data: dict[str, Any]) -> dict[str, Any]:
+        """Convert V1 prompt to V2"""
+        classification_obj = v1_annotation.get('classification') or {}
+
+        # Build V2 data (input and other fields)
+        data: dict[str, Any] = {}
+        for key in self._DATA_FIELDS:
+            if key in v1_data:
+                data[key] = v1_data[key]
+
+        # Build V2 attrs (all classification properties excluding class)
+        attrs: list[dict[str, Any]] = []
+        for key, value in classification_obj.items():
+            if key != 'class':
+                attrs.append({'name': key, 'value': value})
+
+        return {
+            'id': v1_annotation.get('id', ''),
+            'classification': classification_obj.get('class', ''),
+            'attrs': attrs,
+            'data': data,
+        }
+
+    def to_v1(self, v2_annotation: dict[str, Any]) -> tuple[dict[str, Any], dict[str, Any]]:
+        """Convert V2 prompt to V1"""
+        annotation_id = v2_annotation.get('id', '')
+        classification_str = v2_annotation.get('classification', '')
+        attrs = v2_annotation.get('attrs', [])
+        data = v2_annotation.get('data', {})
+
+        # Build V1 classification
+        classification: dict[str, Any] = {'class': classification_str}
+        for attr in attrs:
+            name = attr.get('name', '')
+            value = attr.get('value')
+            if not name.startswith(self._INTERNAL_ATTR_PREFIX):
+                classification[name] = value
+
+        v1_annotation: dict[str, Any] = {
+            'id': annotation_id,
+            'tool': self.tool_name,
+            'classification': classification,
+        }
+
+        # Build V1 annotationsData
+        v1_data: dict[str, Any] = {
+            'id': annotation_id,
+            'tool': self.tool_name,
+        }
+
+        # Copy fields from data
+        for key in self._DATA_FIELDS:
+            if key in data:
+                v1_data[key] = data[key]
+
+        return v1_annotation, v1_data

synapse_sdk/utils/converters/dm/tools/relation.py

@@ -0,0 +1,86 @@
+"""
+Relation Tool Processor
+
+Created: 2025-12-12
+
+Conversion Rules (see data-model.md 9.9):
+V1 → V2:
+  - annotationId, targetAnnotationId → data [from_id, to_id]
+  - classification.class → classification
+  - classification.{other} → attrs[{name, value}]
+
+V2 → V1:
+  - data [from_id, to_id] → annotationId, targetAnnotationId
+  - classification → classification.class
+  - attrs[{name, value}] → classification.{name: value}
+"""
+
+from typing import Any
+
+
+class RelationProcessor:
+    """Relation Tool Processor
+
+    V1 annotationData: {annotationId, targetAnnotationId}
+    V2 data: [from_id, to_id]
+
+    Represents relationship between two annotations.
+    """
+
+    tool_name = 'relation'
+
+    _META_FIELDS = {'isLocked', 'isVisible', 'isValid', 'isDrawCompleted', 'label', 'id', 'tool'}
+    _INTERNAL_ATTR_PREFIX = '_'
+
+    def to_v2(self, v1_annotation: dict[str, Any], v1_data: dict[str, Any]) -> dict[str, Any]:
+        """Convert V1 relation to V2"""
+        classification_obj = v1_annotation.get('classification') or {}
+
+        # V2 data: [from_id, to_id]
+        data = [
+            v1_data.get('annotationId', ''),
+            v1_data.get('targetAnnotationId', ''),
+        ]
+
+        # Build V2 attrs
+        attrs: list[dict[str, Any]] = []
+        for key, value in classification_obj.items():
+            if key != 'class':
+                attrs.append({'name': key, 'value': value})
+
+        return {
+            'id': v1_annotation.get('id', ''),
+            'classification': classification_obj.get('class', ''),
+            'attrs': attrs,
+            'data': data,
+        }
+
+    def to_v1(self, v2_annotation: dict[str, Any]) -> tuple[dict[str, Any], dict[str, Any]]:
+        """Convert V2 relation to V1"""
+        annotation_id = v2_annotation.get('id', '')
+        classification_str = v2_annotation.get('classification', '')
+        attrs = v2_annotation.get('attrs', [])
+        data = v2_annotation.get('data', [])
+
+        # Build V1 classification
+        classification: dict[str, Any] = {'class': classification_str}
+        for attr in attrs:
+            name = attr.get('name', '')
+            value = attr.get('value')
+            if not name.startswith(self._INTERNAL_ATTR_PREFIX):
+                classification[name] = value
+
+        v1_annotation: dict[str, Any] = {
+            'id': annotation_id,
+            'tool': self.tool_name,
+            'classification': classification,
+        }
+
+        # V1 annotationData
+        v1_data: dict[str, Any] = {
+            'id': annotation_id,
+            'annotationId': data[0] if len(data) > 0 else '',
+            'targetAnnotationId': data[1] if len(data) > 1 else '',
+        }
+
+        return v1_annotation, v1_data

synapse_sdk/utils/converters/dm/tools/segmentation.py

@@ -0,0 +1,141 @@
+"""
+Segmentation Tool Processor (Image/Video Unified)
+
+Created: 2025-12-12
+
+Conversion Rules (see data-model.md 9.3, 9.4):
+
+Image Segmentation:
+V1 → V2:
+  - pixel_indices [...] → data [...]
+
+V2 → V1:
+  - data [...] → pixel_indices [...]
+
+Video Segmentation:
+V1 → V2:
+  - section {startFrame, endFrame} → data {startFrame, endFrame}
+
+V2 → V1:
+  - data {startFrame, endFrame} → section {startFrame, endFrame}
+"""
+
+from typing import Any
+
+
+class SegmentationProcessor:
+    """Segmentation Tool Processor (Image/Video Unified)
+
+    Image Segmentation:
+        V1 pixel_indices: [int, ...]
+        V2 data: [int, ...]
+
+    Video Segmentation:
+        V1 section: {startFrame, endFrame}
+        V2 data: {startFrame, endFrame}
+
+    Differentiate image/video by data structure:
+    - list: Image segmentation (pixel_indices)
+    - dict: Video segmentation (section)
+    """
+
+    tool_name = 'segmentation'
+
+    # V1 meta fields (not stored in attrs)
+    _META_FIELDS = {'isLocked', 'isVisible', 'isValid', 'isDrawCompleted', 'label', 'id', 'tool'}
+
+    # Special attrs not restored to V1 classification (_ prefix)
+    _INTERNAL_ATTR_PREFIX = '_'
+
+    def to_v2(self, v1_annotation: dict[str, Any], v1_data: dict[str, Any]) -> dict[str, Any]:
+        """Convert V1 segmentation to V2
+
+        Args:
+            v1_annotation: V1 annotations[] item
+            v1_data: V1 annotationsData[] item (same ID)
+
+        Returns:
+            V2 format segmentation annotation
+        """
+        classification_obj = v1_annotation.get('classification') or {}
+
+        # Process based on data type
+        if 'pixel_indices' in v1_data:
+            # Image segmentation
+            data = v1_data.get('pixel_indices', [])
+        elif 'section' in v1_data:
+            # Video segmentation
+            section = v1_data.get('section', {})
+            data = {
+                'startFrame': section.get('startFrame', 0),
+                'endFrame': section.get('endFrame', 0),
+            }
+        else:
+            # Default (empty array)
+            data = []
+
+        # Build V2 attrs
+        attrs: list[dict[str, Any]] = []
+
+        # Add other classification properties to attrs (excluding class)
+        for key, value in classification_obj.items():
+            if key != 'class':
+                attrs.append({'name': key, 'value': value})
+
+        # Build V2 annotation
+        return {
+            'id': v1_annotation.get('id', ''),
+            'classification': classification_obj.get('class', ''),
+            'attrs': attrs,
+            'data': data,
+        }
+
+    def to_v1(self, v2_annotation: dict[str, Any]) -> tuple[dict[str, Any], dict[str, Any]]:
+        """Convert V2 segmentation to V1
+
+        Args:
+            v2_annotation: V2 annotation object
+
+        Returns:
+            (V1 annotation, V1 annotationData) tuple
+        """
+        annotation_id = v2_annotation.get('id', '')
+        classification_str = v2_annotation.get('classification', '')
+        attrs = v2_annotation.get('attrs', [])
+        data = v2_annotation.get('data', [])
+
+        # Build V1 classification
+        classification: dict[str, Any] = {'class': classification_str}
+
+        # Restore properties from attrs
+        for attr in attrs:
+            name = attr.get('name', '')
+            value = attr.get('value')
+
+            if not name.startswith(self._INTERNAL_ATTR_PREFIX):
+                classification[name] = value
+
+        # V1 annotation (meta info)
+        v1_annotation: dict[str, Any] = {
+            'id': annotation_id,
+            'tool': self.tool_name,
+            'classification': classification,
+        }
+
+        # V1 annotationData (coordinate info) - process based on data type
+        v1_data: dict[str, Any] = {'id': annotation_id}
+
+        if isinstance(data, list):
+            # Image segmentation
+            v1_data['pixel_indices'] = data
+        elif isinstance(data, dict):
+            # Video segmentation
+            v1_data['section'] = {
+                'startFrame': data.get('startFrame', 0),
+                'endFrame': data.get('endFrame', 0),
+            }
+        else:
+            # Default
+            v1_data['pixel_indices'] = []
+
+        return v1_annotation, v1_data

synapse_sdk/utils/converters/dm/tools/segmentation_3d.py

@@ -0,0 +1,83 @@
+"""
+3D Segmentation Tool Processor
+
+Created: 2025-12-12
+
+Conversion Rules (see data-model.md 9.7):
+V1 → V2:
+  - points [...] → data {points: [...]}
+  - classification.class → classification
+  - classification.{other} → attrs[{name, value}]
+
+V2 → V1:
+  - data {points: [...]} → points [...]
+  - classification → classification.class
+  - attrs[{name, value}] → classification.{name: value}
+"""
+
+from typing import Any
+
+
+class Segmentation3DProcessor:
+    """3D Segmentation Tool Processor
+
+    V1 annotationData: {points: list[int]}
+    V2 data: {points: list[int]}
+
+    Used with pcd media type.
+    """
+
+    tool_name = '3d_segmentation'
+
+    _META_FIELDS = {'isLocked', 'isVisible', 'isValid', 'isDrawCompleted', 'label', 'id', 'tool'}
+    _INTERNAL_ATTR_PREFIX = '_'
+
+    def to_v2(self, v1_annotation: dict[str, Any], v1_data: dict[str, Any]) -> dict[str, Any]:
+        """Convert V1 3D segmentation to V2"""
+        classification_obj = v1_annotation.get('classification') or {}
+
+        # V2 data: {points: [...]}
+        data = {
+            'points': v1_data.get('points', []),
+        }
+
+        # Build V2 attrs
+        attrs: list[dict[str, Any]] = []
+        for key, value in classification_obj.items():
+            if key != 'class':
+                attrs.append({'name': key, 'value': value})
+
+        return {
+            'id': v1_annotation.get('id', ''),
+            'classification': classification_obj.get('class', ''),
+            'attrs': attrs,
+            'data': data,
+        }
+
+    def to_v1(self, v2_annotation: dict[str, Any]) -> tuple[dict[str, Any], dict[str, Any]]:
+        """Convert V2 3D segmentation to V1"""
+        annotation_id = v2_annotation.get('id', '')
+        classification_str = v2_annotation.get('classification', '')
+        attrs = v2_annotation.get('attrs', [])
+        data = v2_annotation.get('data', {})
+
+        # Build V1 classification
+        classification: dict[str, Any] = {'class': classification_str}
+        for attr in attrs:
+            name = attr.get('name', '')
+            value = attr.get('value')
+            if not name.startswith(self._INTERNAL_ATTR_PREFIX):
+                classification[name] = value
+
+        v1_annotation: dict[str, Any] = {
+            'id': annotation_id,
+            'tool': self.tool_name,
+            'classification': classification,
+        }
+
+        v1_data: dict[str, Any] = {
+            'id': annotation_id,
+            'points': data.get('points', []),
+        }
+
+        return v1_annotation, v1_data

synapse_sdk/utils/converters/dm/types.py

@@ -0,0 +1,168 @@
+"""
+DM Schema V1/V2 Converter Type Definitions
+
+Created: 2025-12-11
+"""
+
+from typing import Any, TypedDict
+
+# =============================================================================
+# V1 Type Definitions
+# =============================================================================
+
+
+class BoundingBoxCoordinate(TypedDict, total=False):
+    """V1 Bounding Box Coordinate"""
+
+    x: float
+    y: float
+    width: float
+    height: float
+    rotation: float  # In radians, optional
+
+
+class PolygonPoint(TypedDict):
+    """V1 Polygon Individual Point"""
+
+    x: float
+    y: float
+    id: str
+
+
+# V1 Polygon Coordinate Type
+PolygonCoordinate = list[PolygonPoint]
+
+
+class AnnotationBase(TypedDict, total=False):
+    """V1 Annotation Meta Information"""
+
+    id: str  # 10-character random string
+    tool: str  # Tool code (bounding_box, polygon, etc.)
+    isLocked: bool  # Edit lock (default: False)
+    isVisible: bool  # Display visibility (default: True)
+    isValid: bool  # Validity (default: False)
+    isDrawCompleted: bool  # Drawing completed
+    classification: dict[str, Any] | None  # Classification info
+    label: list[str]  # Label array
+
+
+class AnnotationDataItem(TypedDict, total=False):
+    """V1 Annotation Coordinate Data"""
+
+    id: str  # Matches AnnotationBase.id
+    coordinate: BoundingBoxCoordinate | PolygonCoordinate | Any
+
+
+class AnnotatorDataV1(TypedDict, total=False):
+    """DM Schema V1 Top-Level Structure"""
+
+    extra: dict[str, Any]  # Per-media metadata
+    annotations: dict[str, list[AnnotationBase]]  # Annotation meta
+    annotationsData: dict[str, list[AnnotationDataItem]]  # Coordinate data
+    relations: dict[str, list[Any]]  # Relations
+    annotationGroups: dict[str, list[Any]]  # Groups
+    assignmentId: int | str | None  # Task identifier
+
+
+# =============================================================================
+# V2 Type Definitions
+# =============================================================================
+
+
+class V2Attr(TypedDict):
+    """V2 Attribute Object"""
+
+    name: str
+    value: Any
+
+
+class V2Annotation(TypedDict, total=False):
+    """V2 Annotation Common Structure"""
+
+    id: str  # Unique identifier (10 chars, alphanumeric)
+    classification: str  # Class label
+    attrs: list[V2Attr]  # Additional attributes array
+    data: Any  # Tool-specific data (type varies)
+
+
+class V2MediaItem(TypedDict, total=False):
+    """V2 Media Item (annotation arrays by tool)"""
+
+    bounding_box: list[V2Annotation]
+    polygon: list[V2Annotation]
+    polyline: list[V2Annotation]
+    keypoint: list[V2Annotation]
+    # Other tools can be added as needed
+
+
+class V2AnnotationData(TypedDict, total=False):
+    """V2 Common Annotation Structure (annotation_data)"""
+
+    classification: dict[str, list[str]]  # Class labels by tool
+    images: list[V2MediaItem]  # Image media
+    videos: list[V2MediaItem]  # Video media
+    pcds: list[V2MediaItem]  # PCD media
+    texts: list[V2MediaItem]  # Text media
+    audios: list[V2MediaItem]  # Audio media
+    prompts: list[V2MediaItem]  # Prompt media
+
+
+class AnnotationMeta(TypedDict, total=False):
+    """V1 Top-Level Structure Preserved (annotation_meta)
+
+    V1 top-level structure preserved during V1→V2 conversion.
+    Combined with annotation_data for complete V1 restoration during V2→V1 conversion.
+    """
+
+    extra: dict[str, Any]  # Per-media metadata
+    annotations: dict[str, list[AnnotationBase]]  # Annotation meta
+    annotationsData: dict[str, list[AnnotationDataItem]]  # Coordinate data
+    relations: dict[str, list[Any]]  # Relations
+    annotationGroups: dict[str, list[Any]]  # Groups
+    assignmentId: int | str | None  # Task identifier
+
+
+class V2ConversionResult(TypedDict):
+    """V1→V2 Conversion Result (separated structure)
+
+    V1→V2 conversion result is separated into two parts:
+    - annotation_data: V2 common annotation structure (id, classification, attrs, data)
+    - annotation_meta: V1 top-level structure preserved
+      (extra, annotations, annotationsData, relations, annotationGroups, assignmentId)
+
+    V2→V1 conversion:
+    - If both parts exist, complete V1 restoration is possible
+    - If only annotation_data exists, convert to V1 using defaults
+    """
+
+    annotation_data: V2AnnotationData
+    annotation_meta: AnnotationMeta
+
+
+# =============================================================================
+# Bounding Box V2 Data Types
+# =============================================================================
+
+# V2 Bounding Box data: [x, y, width, height]
+BoundingBoxData = list[float]
+
+# V2 Polygon data: [[x1, y1], [x2, y2], ...]
+PolygonData = list[list[float]]
+
+
+# =============================================================================
+# Media Type Constants
+# =============================================================================
+
+SUPPORTED_FILE_TYPES = ('image', 'video', 'pcd', 'text', 'audio', 'prompt')
+
+MEDIA_TYPE_MAP = {
+    'image': 'images',
+    'video': 'videos',
+    'pcd': 'pcds',
+    'text': 'texts',
+    'audio': 'audios',
+    'prompt': 'prompts',
+}
+
+MEDIA_TYPE_REVERSE_MAP = {v: k for k, v in MEDIA_TYPE_MAP.items()}