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

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()}

synapse_sdk/utils/converters/dm/utils.py

@@ -0,0 +1,162 @@
+"""
+DM Schema V1/V2 Converter Utility Functions
+
+Created: 2025-12-11
+"""
+
+import random
+import string
+from typing import Any
+
+from .types import MEDIA_TYPE_MAP, MEDIA_TYPE_REVERSE_MAP
+
+
+def generate_random_id(length: int = 10) -> str:
+    """Generate a random ID compatible with V1 format
+
+    Args:
+        length: ID length (default: 10)
+
+    Returns:
+        Random alphanumeric string
+
+    Example:
+        >>> generate_random_id()
+        'Cd1qfFQFI4'
+    """
+    chars = string.ascii_letters + string.digits
+    return ''.join(random.choice(chars) for _ in range(length))
+
+
+def extract_media_type_info(media_id: str) -> tuple[str, str]:
+    """Extract type information from media ID
+
+    Args:
+        media_id: Media ID (e.g., 'image_1', 'video_2')
+
+    Returns:
+        (singular, plural) tuple (e.g., ('image', 'images'))
+
+    Raises:
+        ValueError: Unknown media type
+
+    Example:
+        >>> extract_media_type_info('image_1')
+        ('image', 'images')
+        >>> extract_media_type_info('video_2')
+        ('video', 'videos')
+    """
+    # Extract type from media ID (e.g., 'image_1' -> 'image')
+    for media_type in MEDIA_TYPE_MAP:
+        if media_id.startswith(media_type):
+            return media_type, MEDIA_TYPE_MAP[media_type]
+
+    raise ValueError(f'Unknown media type: {media_id}')
+
+
+def detect_file_type(data: dict[str, Any], is_v2: bool = False) -> str:
+    """Auto-detect file type from data
+
+    Args:
+        data: Input data (V1 or V2)
+        is_v2: Whether the format is V2
+
+    Returns:
+        Detected file type ('image', 'video', etc.)
+
+    Raises:
+        ValueError: Unable to detect file type
+    """
+    if is_v2:
+        # Detect from V2 data (annotation_data or direct data)
+        check_data = data.get('annotation_data', data)
+        for plural_type in MEDIA_TYPE_REVERSE_MAP:
+            if plural_type in check_data and check_data[plural_type]:
+                return MEDIA_TYPE_REVERSE_MAP[plural_type]
+    else:
+        # Detect from V1 data (from annotations or annotationsData keys)
+        for key in ['annotations', 'annotationsData']:
+            if key in data and data[key]:
+                # Extract type from first media ID
+                first_media_id = next(iter(data[key].keys()), None)
+                if first_media_id:
+                    singular, _ = extract_media_type_info(first_media_id)
+                    return singular
+
+    raise ValueError('Unable to detect file type')
+
+
+def get_attr_value(attrs: list[dict[str, Any]], name: str, default: Any = None) -> Any:
+    """Extract value for a specific name from attrs list
+
+    Args:
+        attrs: V2 attrs list [{"name": "...", "value": ...}, ...]
+        name: Attribute name to find
+        default: Default value (if not found)
+
+    Returns:
+        Found value or default
+    """
+    for attr in attrs:
+        if attr.get('name') == name:
+            return attr.get('value', default)
+    return default
+
+
+def set_attr_value(attrs: list[dict[str, Any]], name: str, value: Any) -> list[dict[str, Any]]:
+    """Add or update attribute in attrs list
+
+    Args:
+        attrs: V2 attrs list
+        name: Attribute name
+        value: Attribute value
+
+    Returns:
+        Updated attrs list
+    """
+    # Update existing attribute
+    for attr in attrs:
+        if attr.get('name') == name:
+            attr['value'] = value
+            return attrs
+
+    # Add new attribute
+    attrs.append({'name': name, 'value': value})
+    return attrs
+
+
+def build_v1_annotation_base(
+    annotation_id: str,
+    tool: str,
+    classification: dict[str, Any] | None = None,
+    is_locked: bool = False,
+    is_visible: bool = True,
+    is_valid: bool = False,
+    is_draw_completed: bool = True,
+    label: list[str] | None = None,
+) -> dict[str, Any]:
+    """Create V1 AnnotationBase object
+
+    Args:
+        annotation_id: Annotation ID
+        tool: Tool code
+        classification: Classification info
+        is_locked: Edit lock
+        is_visible: Display visibility
+        is_valid: Validity
+        is_draw_completed: Drawing completed
+        label: Label array
+
+    Returns:
+        V1 AnnotationBase dictionary
+    """
+    return {
+        'id': annotation_id,
+        'tool': tool,
+        'isLocked': is_locked,
+        'isVisible': is_visible,
+        'isValid': is_valid,
+        'isDrawCompleted': is_draw_completed,
+        'classification': classification,
+        'label': label or [],
+    }

synapse_sdk/utils/converters/dm_legacy/__init__.py

@@ -0,0 +1,56 @@
+from abc import ABC, abstractmethod
+
+from synapse_sdk.shared.enums import SupportedTools
+
+
+class BaseDMConverter(ABC):
+    """Base class for DM format converters."""
+
+    SUPPORTED_TOOLS = SupportedTools.get_all_values()
+
+    def __init__(self, file_type=None):
+        """Initialize the base converter.
+
+        Args:
+            file_type (str, optional): Type of file being converted (image, video, pcd, text, audio)
+        """
+        self.file_type = file_type
+        self.tool_processors = self._setup_tool_processors()
+
+    def _setup_tool_processors(self):
+        """Setup tool processor mapping dynamically based on file_type."""
+        if not self.file_type:
+            return {}
+
+        processors = {}
+        tools = SupportedTools.get_tools_for_file_type(self.file_type)
+
+        for tool in tools:
+            # For other tools, use generic method names
+            method_name = f'_convert_{tool.method_name}'
+
+            if hasattr(self, method_name):
+                processors[tool.annotation_tool] = getattr(self, method_name)
+
+        return processors
+
+    @abstractmethod
+    def convert(self):
+        """Convert data from one format to another."""
+
+    def _handle_unknown_tool(self, tool_type, item_id=None):
+        """Handle unknown tool types with consistent warning message."""
+        warning_msg = f"Warning: Unknown tool type '{tool_type}'"
+        if item_id:
+            warning_msg += f' for item {item_id}'
+        print(warning_msg)
+
+    def _extract_media_type_info(self, media_id):
+        """Extract media type information from media ID."""
+        media_type = media_id.split('_')[0] if '_' in media_id else media_id
+        media_type_plural = media_type + 's' if not media_type.endswith('s') else media_type
+        return media_type, media_type_plural
+
+    def _singularize_media_type(self, media_type_plural):
+        """Convert plural media type to singular."""
+        return media_type_plural.rstrip('s')