endoreg-db 0.6.3__py3-none-any.whl → 0.8.1__py3-none-any.whl

endoreg_db/serializers/finding_classification/choice.py

@@ -0,0 +1,19 @@
+from endoreg_db.models import FindingClassificationChoice
+from rest_framework import serializers
+
+class FindingClassificationChoiceSerializer(serializers.ModelSerializer):
+    """
+    Serializer for the FindingClassificationChoice model.
+
+    Serializes the following fields:
+        - id: Unique identifier of the classification choice.
+        - name: Name of the classification choice.
+        - description: Description of the classification choice.
+        - subcategories: Related subcategories for further classification.
+        - numerical_descriptors: Associated numerical descriptors for the classification choice.
+    """
+    class Meta:
+        model = FindingClassificationChoice
+        fields = [
+            'id', 'name', 'description', 'subcategories', 'numerical_descriptors'
+        ]

endoreg_db/serializers/finding_classification/classification.py

@@ -0,0 +1,13 @@
+from .choice import FindingClassificationChoiceSerializer
+from endoreg_db.models import FindingClassification
+from rest_framework import serializers
+
+class FindingClassificationSerializer(serializers.ModelSerializer):
+    choices = FindingClassificationChoiceSerializer(many=True, read_only=True)
+
+    class Meta:
+        model = FindingClassification
+        fields = [
+            'id', 'name', 'description', 'choices', 'classification_types'
+        ]
+    

endoreg_db/serializers/label/__init__.py

@@ -0,0 +1,7 @@
+from .label import LabelSerializer
+from .image_classification_annotation import ImageClassificationAnnotationSerializer
+
+__all__ = [
+    'LabelSerializer',
+    'ImageClassificationAnnotationSerializer',
+]

endoreg_db/serializers/label/image_classification_annotation.py

@@ -0,0 +1,62 @@
+from typing import Optional
+from rest_framework import serializers
+
+
+from endoreg_db.models import ImageClassificationAnnotation
+
+
+class ImageClassificationAnnotationSerializer(serializers.ModelSerializer):
+    """
+    Serializer for ImageClassificationAnnotation model.
+    This serializer is used to represent image classification annotations in the API.
+    """
+
+    label_name = serializers.SerializerMethodField()
+    confidence = serializers.SerializerMethodField()
+    frame_number = serializers.IntegerField(source='frame.frame_number', read_only=True)
+
+    class Meta:
+        model = ImageClassificationAnnotation
+        fields = [
+            "id",
+            "label",
+            "confidence",
+            "frame_number",
+            "information_source",
+            "date_created",
+            "date_modified",
+            "label_name",
+        ]
+
+    def get_confidence(self, obj: ImageClassificationAnnotation) -> Optional[float]:
+        """
+        Retrieve the confidence score associated with the annotation.
+        
+        Returns:
+            The float value representing the annotation's confidence, or None if not set.
+        """
+        if obj.float_value is not None:
+            return obj.float_value
+        return None
+
+    def get_label_name(self, obj: ImageClassificationAnnotation) -> str:
+        """
+        Returns the name of the label associated with the annotation, or "No Label" if no label is set.
+        """
+        return obj.label.name if obj.label else "No Label"
+
+    def to_representation(self, instance: ImageClassificationAnnotation) -> dict:
+        """
+        Return the serialized representation of an ImageClassificationAnnotation instance.
+        
+        Overrides the default method to allow for future customization of the serialized output, but currently returns the standard representation unchanged.
+        
+        Parameters:
+            instance (ImageClassificationAnnotation): The annotation instance to serialize.
+        
+        Returns:
+            dict: The serialized data for the annotation.
+        """
+        representation = super().to_representation(instance)
+        # Add any additional fields or transformations here if needed
+        return representation

endoreg_db/serializers/label/label.py

@@ -0,0 +1,15 @@
+from endoreg_db.models import Label
+
+
+from rest_framework import serializers
+
+
+class LabelSerializer(serializers.ModelSerializer):
+    """
+    Serializer for fetching labels from the `endoreg_db_label` table.
+    Includes `id` (for backend processing) and `name` (for dropdown display in Vue.js).
+    """
+
+    class Meta:
+        model = Label
+        fields = ["id", "name"]

endoreg_db/serializers/label_video_segment/__init__.py

@@ -0,0 +1,7 @@
+from .label_video_segment import LabelVideoSegmentSerializer
+from .label_video_segment_annotation import LabelVideoSegmentAnnotationSerializer
+
+__all__ = [
+    "LabelVideoSegmentSerializer",
+    "LabelVideoSegmentAnnotationSerializer"
+]

endoreg_db/serializers/label_video_segment/_lvs_create.py

@@ -0,0 +1,149 @@
+from typing import TYPE_CHECKING
+from django.core.exceptions import ObjectDoesNotExist
+from rest_framework import serializers
+from endoreg_db.models import (
+    Label,
+    VideoFile,
+    LabelVideoSegment,
+    InformationSource
+)
+
+import logging
+logger = logging.getLogger(__name__)
+
+if TYPE_CHECKING:
+    from endoreg_db.serializers import LabelVideoSegmentSerializer
+
+def _get_video_file(self, video_id):
+    """
+    Retrieve a VideoFile instance by its ID.
+    
+    Raises a serializers.ValidationError if the VideoFile does not exist.
+    """
+    try:
+        return VideoFile.objects.get(id=video_id)
+    except ObjectDoesNotExist as exc:
+        raise serializers.ValidationError(f"VideoFile with id {video_id} does not exist") from exc
+
+def _get_label(self, label_id, label_name):
+    """
+    Retrieve a Label instance by ID or name, creating it if necessary.
+    
+    Raises a ValidationError if the label cannot be found, created, or if neither identifier is provided.
+    """
+    if label_id:
+        try:
+            return Label.objects.get(id=label_id)
+        except ObjectDoesNotExist as exc:
+            raise serializers.ValidationError(f"Label with id {label_id} does not exist") from exc
+    elif label_name:
+        label, _ = Label.get_or_create_from_name(label_name)
+        if not label:
+            raise serializers.ValidationError(f"Failed to create or retrieve label with name {label_name}")
+        return label
+    else:
+        raise serializers.ValidationError("Either label_id or label_name must be provided")
+
+def _validate_fps(self, video_file):
+    """
+    Validate and return the frames per second (FPS) value from a video file.
+    
+    Raises a validation error if the FPS is missing, not a positive number, or cannot be converted to a float.
+    
+    Returns:
+        float: The validated FPS value.
+    """
+    fps_raw = video_file.get_fps()
+    if fps_raw is None:
+        raise serializers.ValidationError("Video file must have a defined FPS")
+    try:
+        fps = float(fps_raw)
+        if fps <= 0:
+            raise ValueError("FPS must be a positive number")
+    except (ValueError, TypeError):
+        raise serializers.ValidationError("Invalid FPS format in video file")
+    return fps
+
+def _calculate_frame_numbers(self, validated_data, fps):
+    """
+    Convert start and end times in the input data to corresponding frame numbers using the provided FPS value.
+    
+    Parameters:
+        validated_data (dict): Input data containing 'start_time' and 'end_time' keys.
+        fps (float): Frames per second of the video.
+    
+    Returns:
+        dict: The input data dictionary updated with 'start_frame_number' and 'end_frame_number' keys.
+    
+    Raises:
+        serializers.ValidationError: If frame numbers cannot be determined from the provided data.
+    """
+    if validated_data.get('start_time') is not None:
+        validated_data['start_frame_number'] = int(float(validated_data['start_time']) * fps)
+    if validated_data.get('end_time') is not None:
+        validated_data['end_frame_number'] = int(float(validated_data['end_time']) * fps)
+    if 'start_frame_number' not in validated_data or 'end_frame_number' not in validated_data:
+        raise serializers.ValidationError("Could not determine frame numbers from provided data")
+    return validated_data
+
+def _get_information_source(self):
+    """
+    Retrieve or create the information source for manual annotation.
+    
+    Returns:
+        InformationSource: The source object representing manual annotation.
+    """
+    source, _ = InformationSource.objects.get_or_create(
+        name='Manual Annotation',
+        defaults={
+            'description': 'Manually created label segments via web interface',
+        }
+    )
+    return source
+
+def _create(self:"LabelVideoSegmentSerializer", validated_data):
+    """
+    Create and persist a new LabelVideoSegment instance from validated input data.
+    
+    This method extracts relevant fields from the input, retrieves or creates related objects (video file, label, information source), validates video FPS, calculates frame numbers from time values, and creates a new LabelVideoSegment. Raises a validation error if required data is missing or invalid, or if creation fails.
+    
+    Returns:
+        LabelVideoSegment: The newly created and saved segment instance.
+    """
+    try:
+        # Extract convenience fields
+        video_id = validated_data.pop('video_id')
+        label_id = validated_data.pop('label_id', None)
+        label_name = validated_data.pop('label_name', None)
+        start_time = validated_data.pop('start_time', None)
+        end_time = validated_data.pop('end_time', None)
+
+        video_file = self.get_video_file(video_id)
+        label = self.get_label(label_id, label_name)
+        fps = self.validate_fps(video_file)
+        validated_data['start_time'] = start_time
+        validated_data['end_time'] = end_time
+        validated_data = self.calculate_frame_numbers(validated_data, fps)
+        source = self.get_information_source()
+
+        # Create the segment directly
+        segment = LabelVideoSegment.safe_create(
+            video_file=video_file,
+            label=label,
+            source=source,
+            start_frame_number=validated_data['start_frame_number'],
+            end_frame_number=validated_data['end_frame_number'],
+            prediction_meta=None  # No prediction meta for manual annotations
+        )
+        segment.save()
+
+        logger.info("Created new video segment: %s for video %s with label %s",
+                    segment.pk, video_id, label.name if label else 'None')
+        return segment
+
+    except serializers.ValidationError as e:
+        logger.error("Validation error while creating video segment: %s", str(e))
+        raise
+    except Exception as e:
+        logger.error("Unexpected error while creating video segment: %s", str(e))
+        raise serializers.ValidationError(f"Failed to create segment: {str(e)}")

endoreg_db/serializers/label_video_segment/_lvs_update.py

@@ -0,0 +1,138 @@
+from typing import TYPE_CHECKING, Dict, Any, Optional
+from django.core.exceptions import ObjectDoesNotExist
+from rest_framework import serializers
+from endoreg_db.models import (
+    Label,
+    VideoFile,
+    LabelVideoSegment
+)
+
+import logging
+logger = logging.getLogger(__name__)
+
+if TYPE_CHECKING:
+    from endoreg_db.serializers import LabelVideoSegmentSerializer
+
+
+def _validate_fps(video: "VideoFile"):
+    """Raises a ValidationError if the video's FPS is invalid."""
+    fps = video.get_fps()
+    if not fps or fps <= 0:
+        raise serializers.ValidationError("The video must have a valid FPS to convert times to frames.")
+    return fps
+
+def _convert_time_to_frame(time_value: float, fps: float) -> int:
+    """Converts a time value in seconds to a frame number."""
+    return int(time_value * fps)
+
+def _update_frames_from_data(instance: "LabelVideoSegment", validated_data: Dict[str, Any], fps: Optional[float]):
+    """Updates start and end frames from either time or frame data."""
+    if 'start_time' in validated_data:
+        if fps is None:
+            fps = _validate_fps(instance.video)
+        instance.start_frame_number = _convert_time_to_frame(validated_data['start_time'], fps)
+    elif 'start_frame' in validated_data:
+        instance.start_frame_number = validated_data['start_frame']
+
+    if 'end_time' in validated_data:
+        if fps is None:
+            fps = _validate_fps(instance.video)
+        instance.end_frame_number = _convert_time_to_frame(validated_data['end_time'], fps)
+    elif 'end_frame' in validated_data:
+        instance.end_frame_number = validated_data['end_frame']
+
+def _update(instance: "LabelVideoSegment", validated_data: Dict[str, Any]) -> "LabelVideoSegment":
+    """
+    Handles the update logic for a LabelVideoSegment instance.
+    This function is designed to be used within a serializer's update method.
+    """
+    video: Optional["VideoFile"] = validated_data.get('video')
+    fps = None
+
+    if video and video != instance.video:
+        instance.video = video
+        fps = _validate_fps(video)  # Validate FPS for the new video
+
+    if 'label' in validated_data:
+        instance.label = validated_data['label']
+
+    _update_frames_from_data(instance, validated_data, fps)
+
+    # Final validation of frame numbers
+    if instance.start_frame_number >= instance.end_frame_number:
+        raise serializers.ValidationError("start_frame must be less than end_frame.")
+    
+    if instance.video and instance.end_frame_number > instance.video.frame_count:
+        raise serializers.ValidationError("end_frame cannot exceed the total frames of the video.")
+
+    instance.save()
+    return instance
+
+def _update(self:"LabelVideoSegmentSerializer", instance, validated_data):
+    """
+    Update a LabelVideoSegment instance with new validated data.
+    
+    This method updates the associated video file, label (by ID or name), and segment boundaries (start and end times converted to frame numbers based on the video's FPS). If the referenced video or label does not exist, or if any error occurs during the update, a validation error is raised.
+    
+    Returns:
+        The updated LabelVideoSegment instance.
+    """
+    try:
+        # Handle time-based updates
+        start_time = validated_data.pop('start_time', None)
+        end_time = validated_data.pop('end_time', None)
+        video_id = validated_data.pop('video_id', None)
+        label_id = validated_data.pop('label_id', None)
+        label_name = validated_data.pop('label_name', None)
+        
+        # Update video if provided
+        if video_id and (not instance.video_file or video_id != instance.video_file.id):
+            try:
+                instance.video_file = VideoFile.objects.get(id=video_id)
+            except ObjectDoesNotExist as exc:
+                raise serializers.ValidationError(f"VideoFile with id {video_id} does not exist") from exc
+        
+        # Update label if provided
+        if label_id is not None:
+            if label_id:
+                try:
+                    instance.label = Label.objects.get(id=label_id)
+                except ObjectDoesNotExist as exc:
+                    raise serializers.ValidationError(f"Label with id {label_id} does not exist") from exc
+            else:
+                instance.label = None
+        elif label_name is not None:
+            if label_name:
+                instance.label = self.get_or_create_label_from_name(label_name)
+            else:
+                instance.label = None
+        
+        def _get_valid_fps(video_file):
+            """
+            Extract and validate the frames-per-second (FPS) value from a video file object.
+            
+            Returns:
+                float: The FPS value as a positive float. Defaults to 30.0 if missing, invalid, or non-positive.
+            """
+
+        # Convert time to frame numbers if provided
+        if start_time is not None:
+            fps = _validate_fps(instance.video_file)
+            instance.start_frame_number = _convert_time_to_frame(start_time, fps)
+        
+        if end_time is not None:
+            fps = _validate_fps(instance.video_file)
+            instance.end_frame_number = _convert_time_to_frame(end_time, fps)
+        
+        # Update other fields
+        for attr, value in validated_data.items():
+            setattr(instance, attr, value)
+        
+        instance.save()
+        logger.info("Updated video segment: %s", instance.pk)
+        return instance
+        
+    except Exception as e:
+        logger.error("Error updating video segment %s: %s", instance.pk, str(e))
+        raise serializers.ValidationError(f"Failed to update segment: {str(e)}")
+

endoreg_db/serializers/label_video_segment/_lvs_validate.py

@@ -0,0 +1,149 @@
+import logging
+from rest_framework import serializers
+from typing import TYPE_CHECKING
+if TYPE_CHECKING:
+    from endoreg_db.serializers import LabelVideoSegmentSerializer
+
+logger = logging.getLogger(__name__)
+
+def _validate(self:"LabelVideoSegmentSerializer", attrs):
+    """
+    Validate video segment data, ensuring the presence and logical consistency of either time-based or frame-based segment information.
+    
+    Raises:
+        ValidationError: If neither valid time nor frame data is provided, or if time/frame constraints are violated.
+    
+    Returns:
+        dict: The validated attributes for the video segment.
+    """
+    logger.debug("Validation started")
+    video_id, label_id = self.extract_and_validate_basic_attrs(attrs)
+    instance = getattr(self, 'instance', None)
+    start_time, end_time = self.process_time_data(attrs, instance)
+    start_frame_number, end_frame_number = self.process_frame_data(attrs, instance)
+    has_time_data, has_frame_data = self.validate_time_and_frame_presence(start_time, end_time, start_frame_number, end_frame_number)
+    label_id = attrs.get('label_id')
+    label_name = attrs.get('label_name')
+    if not label_id and not label_name:
+        logger.info("Creating segment without label")
+    if has_time_data:
+        self.validate_time_constraints(start_time, end_time)
+    if has_frame_data:
+        self.validate_frame_constraints(start_frame_number, end_frame_number)
+    logger.debug(f"Attributes after validation: {attrs}")
+    return attrs
+
+def _extract_and_validate_basic_attrs(self:"LabelVideoSegmentSerializer", attrs):
+    """
+    Extract and return the video and label identifiers from the provided attributes or initial data.
+    
+    Returns:
+        Tuple containing the resolved video ID and label ID.
+    """
+    video_id = attrs.get('video_id') or self.initial_data.get('video_id') or self.initial_data.get('video_file')
+    label_id = attrs.get('label_id') or self.initial_data.get('label_id') or self.initial_data.get('label')
+    logger.debug(f"Validating video segment: video_id={video_id}, label_id={label_id}, attrs={{k: v for k, v in attrs.items() if k not in ['video_file', 'label']}}")
+    return video_id, label_id
+
+def _process_time_data(self:"LabelVideoSegmentSerializer", attrs, instance):
+    """
+    Extract and convert start and end time values from input data, ensuring they are floats or None.
+    
+    Parameters:
+        attrs (dict): Input attributes containing potential time values.
+        instance: Existing object instance to use as a fallback for time values.
+    
+    Returns:
+        tuple: A pair (start_time, end_time), each as a float or None if missing or invalid.
+    """
+    start_time = attrs.get('start_time', None)
+    end_time = attrs.get('end_time', None)
+    if instance is not None:
+        if start_time is None:
+            start_time = getattr(instance, 'start_time', None)
+        if end_time is None:
+            end_time = getattr(instance, 'end_time', None)
+    # Always convert start_time/end_time to float if present
+    if 'start_time' in self.initial_data:
+        try:
+            attrs['start_time'] = float(self.initial_data['start_time'])
+        except (TypeError, ValueError):
+            attrs['start_time'] = None
+        start_time = attrs['start_time']
+    elif start_time is not None:
+        try:
+            start_time = float(start_time)
+            attrs['start_time'] = start_time
+        except (TypeError, ValueError):
+            start_time = None
+            attrs['start_time'] = None
+    if 'end_time' in self.initial_data:
+        try:
+            attrs['end_time'] = float(self.initial_data['end_time'])
+        except (TypeError, ValueError):
+            attrs['end_time'] = None
+        end_time = attrs['end_time']
+    elif end_time is not None:
+        try:
+            end_time = float(end_time)
+            attrs['end_time'] = end_time
+        except (TypeError, ValueError):
+            end_time = None
+            attrs['end_time'] = None
+    return start_time, end_time
+
+def _process_frame_data(self:"LabelVideoSegmentSerializer", attrs, instance):
+    """
+    Retrieve start and end frame numbers from input attributes or an existing instance.
+    
+    Returns:
+        tuple: A pair containing the start and end frame numbers, or None if not available.
+    """
+    start_frame_number = attrs.get('start_frame_number')
+    end_frame_number = attrs.get('end_frame_number')
+    if instance is not None:
+        if start_frame_number is None:
+            start_frame_number = getattr(instance, 'start_frame_number', None)
+        if end_frame_number is None:
+            end_frame_number = getattr(instance, 'end_frame_number', None)
+    return start_frame_number, end_frame_number
+
+def _validate_time_and_frame_presence(self:"LabelVideoSegmentSerializer", start_time, end_time, start_frame_number, end_frame_number):
+    """
+    Check that either both time values or both frame number values are provided for a video segment.
+    
+    Raises a ValidationError if neither a complete time range nor a complete frame range is present.
+    
+    Returns:
+        has_time_data (bool): True if both start_time and end_time are provided.
+        has_frame_data (bool): True if both start_frame_number and end_frame_number are provided.
+    """
+    has_time_data = start_time is not None and end_time is not None
+    has_frame_data = start_frame_number is not None and end_frame_number is not None
+    if not has_time_data and not has_frame_data:
+        raise serializers.ValidationError(
+            "Either start_time/end_time or start_frame_number/end_frame_number must be provided"
+        )
+    return has_time_data, has_frame_data
+
+def _validate_time_constraints(self:"LabelVideoSegmentSerializer", start_time, end_time):
+    """
+    Validate that the start and end times for a video segment are logically consistent.
+    
+    Raises a ValidationError if start_time is negative or if end_time is not strictly greater than start_time.
+    """
+    if start_time < 0:
+        raise serializers.ValidationError("start_time must be non-negative")
+    if end_time <= start_time:
+        raise serializers.ValidationError("end_time must be greater than start_time")
+
+def _validate_frame_constraints(self:"LabelVideoSegmentSerializer", start_frame_number, end_frame_number):
+    """
+    Validate that frame number constraints are satisfied for a video segment.
+    
+    Raises a ValidationError if `start_frame_number` is negative or if `end_frame_number` is not greater than `start_frame_number`.
+    """
+    if start_frame_number < 0:
+        raise serializers.ValidationError("start_frame_number must be non-negative")
+    if end_frame_number <= start_frame_number:
+        raise serializers.ValidationError("end_frame_number must be greater than start_frame_number")