endoreg-db 0.8.9.32__py3-none-any.whl

endoreg_db/serializers/video/video_file.py

@@ -0,0 +1,283 @@
+from pathlib import Path
+
+from rest_framework import serializers
+
+from ...models import VideoFile
+
+try:
+    import cv2
+except ImportError:
+    cv2 = None
+# from django.conf import settings
+from typing import TYPE_CHECKING
+
+from django.conf import settings
+from rest_framework.exceptions import ValidationError
+
+if TYPE_CHECKING:
+    from endoreg_db.models import VideoFile
+
+
+class VideoFileSerializer(serializers.ModelSerializer):
+    """
+    Serializer that dynamically handles video retrieval and streaming.
+    Ensures file returns the relative file path (not MEDIA_URL)
+    Computes full_video_path using the correct storage path (/home/admin/test-data)-need to change make it dynamic
+    Returns video_url for frontend integration
+    Serves the video file when needed
+
+    """
+
+    video_url = serializers.SerializerMethodField()
+    full_video_path = serializers.SerializerMethodField()
+    file = serializers.SerializerMethodField()  # Override file to remove incorrect MEDIA_URL behavior,otherwise:Django's FileField automatically generates a URL based on MEDIA_URL
+    # Video dropdown field for frontend selection (currently shows video ID, but can be changed later)
+    video_selection_field = serializers.SerializerMethodField()
+    # classification_data = serializers.SerializerMethodField() #data from database (smooth prediction values but currently hardcoded one)
+    # The Meta class tells Django what data to include when serializing a RawVideoFile object.
+    sequences = serializers.SerializerMethodField()
+    label_names = serializers.SerializerMethodField()
+    # Convert selected label frames into time segments (seconds)
+    label_time_segments = serializers.SerializerMethodField()
+    # label_predictions = serializers.SerializerMethodField()
+    original_file_name = serializers.CharField(read_only=True)
+    duration = serializers.SerializerMethodField()
+
+    class Meta:
+        model = VideoFile
+        # he fields list defines which data should be included in the API response.
+        fields = [
+            "id",
+            "original_file_name",
+            "file",
+            "duration",
+            "video_url",
+            "full_video_path",
+            "video_selection_field",
+            "label_names",
+            "sequences",
+            "label_time_segments",
+        ]  #  Ensure computed fields are included
+
+    # @staticmethod #using @staticmethod makes it reusable without needing to create a serializer instance.
+    #  Without @staticmethod, you would need to instantiate the serializer before calling the method, which is unnecessary her
+    def get_video_selection_field(self, obj: "VideoFile"):
+        """
+        Return the UUID of the video for use as a selection value in frontend dropdowns.
+
+        Parameters:
+            obj (Video): The video instance being serialized.
+
+        Returns:
+            str: The UUID of the video.
+        """
+        return obj.video_hash
+
+    def get_video_url(
+        self, obj
+    ):  # when we serialize a RawVideoFile object (video metadata), the get_video_url method is automatically invoked by DRF
+        """
+        Return the absolute API URL for accessing the video file.
+
+        If the video ID is invalid or the request context is missing, returns a dictionary with an error message.
+        """
+        if not obj.id:
+            return {"error": "Invalid video ID"}
+
+        request = self.context.get(
+            "request"
+        )  # Gets the request object (provided by DRF).
+        if request:
+            return request.build_absolute_uri(
+                f"/api/video/{obj.id}/"
+            )  # Added api/ prefix
+
+        return {"error": "Video URL not available"}
+
+    def get_duration(self, obj: "VideoFile"):
+        """
+        Return the duration of the video in seconds, using the stored value if available or extracting it dynamically with OpenCV.
+
+        If the duration is not present in the database, the method opens the video file, retrieves its frame count and frames per second (FPS), and calculates the duration. Returns `None` if the video cannot be opened or FPS is zero.
+        """
+        if hasattr(obj, "duration") and obj.duration:
+            return (
+                obj.duration
+            )  # If duration is stored in the database, return it directly.
+
+        # Dynamically extract duration if not stored
+        video_path = obj.active_file.path
+
+        cap = cv2.VideoCapture(video_path)
+        try:
+            if not cap.isOpened():
+                return None  # Error handling if video can't be opened
+
+            fps = cap.get(cv2.CAP_PROP_FPS)
+            total_frames = cap.get(cv2.CAP_PROP_FRAME_COUNT)
+
+            return (
+                round(total_frames / fps, 2) if fps > 0 else None
+            )  # Return duration in seconds
+        finally:
+            cap.release()
+
+    def get_file(self, obj: "VideoFile"):
+        """
+        Returns the relative file path of the active video file, or an error message if the file is missing or invalid.
+
+        Parameters:
+            obj (Video): The video instance whose file path is to be retrieved.
+
+        Returns:
+            str or dict: The relative file path as a string, or a dictionary with an error message if the file is missing or invalid.
+        """
+        if not obj.active_file:
+            return {"error": "No file  associated with this entry"}
+        # obj.active_file.name is an attribute of FieldFile that returns the file path as a string and name is not the database attribute, it is an attribute of Django’s FieldFile object that holds the file path as a string.
+        if not hasattr(obj.active_file, "name") or not obj.active_file.name.strip():
+            return {"error": "Invalid file name"}
+
+        return str(
+            obj.active_file.name
+        ).strip()  #  Only return the file path, no URL,#obj.active_file returning a FieldFile object instead of a string
+
+    def get_full_video_path(self, obj: "VideoFile"):
+        """
+        Return the absolute filesystem path to the video's active file.
+
+        If the file does not exist or an error occurs during path construction, returns a dictionary with an error message.
+        """
+        if not obj.active_file:
+            return {"error": "No video file associated with this entry"}
+
+        try:
+            # Use the active_file_path property which handles both processed and raw files
+            if hasattr(obj, "active_file_path") and obj.active_file_path:
+                full_path = obj.active_file_path
+                return (
+                    str(full_path)
+                    if full_path.exists()
+                    else {"error": f"file not found at: {full_path}"}
+                )
+            else:
+                # Fallback: construct path manually
+                video_relative_path = str(obj.active_file.name).strip()
+                if not video_relative_path:
+                    return {"error": "Video file path is empty or invalid"}
+
+                # Construct the path using the file's actual path
+                full_path = obj.active_file.path
+                return (
+                    str(full_path)
+                    if Path(full_path).exists()
+                    else {"error": f"file not found at: {full_path}"}
+                )
+
+        except Exception as e:
+            return {"error": f"Error constructing file path: {str(e)}"}
+
+    def get_sequences(self, obj: "VideoFile"):
+        """
+        Retrieve frame sequences for each label from the video object.
+
+        Returns:
+            dict: A mapping of label names to lists of frame ranges, or an error message if no sequences are found.
+        """
+        return obj.sequences or {
+            "error": "no sequence found, check database first"
+        }  #  Get from sequences, return {} if missing
+
+    def get_label_names(self, obj: "VideoFile"):
+        """
+        Return a list of label names present in the video's frame sequences.
+
+        Parameters:
+            obj (Video): The video instance to extract label names from.
+
+        Returns:
+            list[str]: List of label names, or an empty list if no sequences are found.
+        """
+        sequences = self.get_sequences(obj)
+        return list(sequences.keys()) if sequences else []
+
+    def get_label_time_segments(self, obj: "VideoFile"):
+        """
+        Convert frame sequences for each label into time segments with frame-level metadata.
+
+        For each label in the video, this method generates a list of time segments based on frame index ranges, converting them to seconds using the video's FPS. Each segment includes the raw frame indices, start and end times in seconds, and detailed information for each frame in the segment, such as filename, full file path, and a placeholder for predictions.
+
+        Returns:
+            dict: A dictionary mapping each label to its list of time segments and associated frame metadata.
+        """
+
+        fps = getattr(obj, "fps", None)
+        if fps is None and hasattr(obj, "get_fps"):
+            fps = obj.get_fps()
+
+        if not fps or fps <= 0:
+            # Strict by default — only use fallback if explicitly enabled and > 0
+            if (
+                getattr(settings, "VIDEO_ALLOW_FPS_FALLBACK", False)
+                and getattr(settings, "VIDEO_DEFAULT_FPS", 0) > 0
+            ):
+                fps = settings.VIDEO_DEFAULT_FPS
+            else:
+                raise ValidationError(
+                    {
+                        "label_time_segments": "FPS unavailable — cannot calculate time segments",
+                        "video_id": getattr(obj, "id", None),
+                    }
+                )
+
+        sequences = self.get_sequences(obj)  # Fetch sequence data
+        frame_dir = Path(obj.frame_dir)  # Get the correct directory from the model
+        time_segments = {}  # Dictionary to store converted times and frame predictions
+
+        for label, frame_ranges in sequences.items():
+            label_times = []  # Stores time segments
+            frame_predictions = {}  # Ensure frame_predictions is properly initialized for each label #TODO Currently always emty?
+
+            for frame_range in frame_ranges:
+                if len(frame_range) != 2:
+                    continue  # Skip invalid frame ranges
+
+                start_frame, end_frame = frame_range  # Raw frame indices from DB
+                start_time = start_frame / fps  # Convert frame index to seconds
+                end_time = end_frame / fps  # Convert frame index to seconds
+
+                frame_data = {}  # Store frame-wise info
+
+                # Fetch predictions for frames within this range
+                for frame_num in range(start_frame, end_frame + 1):
+                    frame_filename = (
+                        f"frame_{str(frame_num).zfill(7)}.jpg"  # Frame filename format
+                    )
+                    frame_path = frame_dir / frame_filename  # Full path to the frame
+
+                    frame_data[frame_num] = {
+                        "frame_filename": frame_filename,
+                        "frame_file_path": str(frame_path),
+                        "predictions": None,
+                    }
+
+                # Append the converted time segment
+                label_times.append(
+                    {
+                        "segment_start": start_frame,  # Raw start frame (not divided by FPS)
+                        "segment_end": end_frame,  # Raw end frame (not divided by FPS)
+                        "start_time": round(
+                            start_time, 2
+                        ),  # Converted start time in seconds
+                        "end_time": round(end_time, 2),  # Converted end time in seconds
+                        "frames": frame_data,  # Attach frame details
+                    }
+                )
+
+            # Store time segments and frame_predictions under the label
+            time_segments[label] = {
+                "time_ranges": label_times,
+                "frame_predictions": frame_predictions,  # Ensure frame_predictions is correctly assigned
+            }
+
+        return time_segments

endoreg_db/serializers/video/video_file_brief.py

@@ -0,0 +1,14 @@
+from endoreg_db.models import VideoFile
+
+
+from rest_framework import serializers
+
+
+class VideoBriefSerializer(serializers.ModelSerializer):
+    class Meta:
+        model = VideoFile
+        fields = [
+            "id",
+            "original_file_name",
+            "sensitive_meta_id",
+        ]  # for tables/overview

endoreg_db/serializers/video/video_file_detail.py

@@ -0,0 +1,96 @@
+from rest_framework import serializers
+from django.conf import settings
+from pathlib import Path
+
+from endoreg_db.models.media.video.video_file import VideoFile
+from endoreg_db.serializers.video.video_file_brief import VideoBriefSerializer
+from ...utils.calc_duration_seconds import _calc_duration_vf
+
+
+class VideoDetailSerializer(VideoBriefSerializer):
+    # pull selected fields from SensitiveMeta (READ-ONLY) - using SerializerMethodField to handle datetime->date conversion
+    patient_first_name = serializers.CharField(
+        source="sensitive_meta.patient_first_name", read_only=True
+    )
+    patient_last_name = serializers.CharField(
+        source="sensitive_meta.patient_last_name", read_only=True
+    )
+    patient_dob = serializers.SerializerMethodField()
+    examination_date = serializers.SerializerMethodField()
+
+    file = serializers.SerializerMethodField()
+    full_path = serializers.SerializerMethodField()
+    duration = serializers.SerializerMethodField()
+    video_url = serializers.SerializerMethodField()
+
+    class Meta(VideoBriefSerializer.Meta):
+        fields = VideoBriefSerializer.Meta.fields + [
+            "file",
+            "full_path",
+            "video_url",
+            "patient_first_name",
+            "patient_last_name",
+            "patient_dob",
+            "examination_date",
+            "duration",
+        ]
+
+    # ---------- helpers ---------- #
+    def get_file(self, obj):
+        f = obj.processed_file or obj.raw_file
+        return f.name if f else None
+
+    def get_full_path(self, obj):
+        f = obj.processed_file or obj.raw_file
+        return str(Path(settings.MEDIA_ROOT) / f.name) if f else None
+
+    def get_video_url(self, obj):
+        """
+        Return the absolute URL for accessing the video streaming resource.
+
+        Returns:
+            str or None: The absolute URL to the video streaming endpoint if a request context is available; otherwise, None.
+        """
+        request = self.context.get("request")
+        # Use video streaming endpoint (VideoStreamView)
+        return (
+            request.build_absolute_uri(f"/api/media/videos/{obj.pk}/")
+            if request
+            else None
+        )
+
+    def get_duration(self, obj: VideoFile):
+        """
+        Return the duration of the video, using the stored value if available or calculating it if not.
+
+        Parameters:
+            obj (VideoFile): The video file instance.
+
+        Returns:
+            float or None: Duration of the video in seconds, or None if unavailable.
+        """
+        return obj.duration or _calc_duration_vf(obj)
+
+    def get_patient_dob(self, obj):
+        """
+        Returns the patient's date of birth as a date object if available, or None if not present.
+
+        Extracts the date part from the patient's date of birth field in the sensitive metadata, handling both datetime and date types.
+        """
+        if obj.sensitive_meta and obj.sensitive_meta.patient_dob:
+            # If it's a datetime, extract the date part
+            dob = obj.sensitive_meta.patient_dob
+            return dob.date() if hasattr(dob, "date") else dob
+        return None
+
+    def get_examination_date(self, obj):
+        """
+        Returns the examination date as a date object from the sensitive metadata, or None if unavailable.
+
+        If the examination date is a datetime, only the date part is returned.
+        """
+        if obj.sensitive_meta and obj.sensitive_meta.examination_date:
+            # If it's a datetime, extract the date part
+            exam_date = obj.sensitive_meta.examination_date
+            return exam_date.date() if hasattr(exam_date, "date") else exam_date
+        return None

endoreg_db/serializers/video/video_file_list.py

@@ -0,0 +1,100 @@
+# endoreg_db/serializers/video/video_file_list.py
+from typing import Literal
+import logging
+
+from rest_framework import serializers
+
+from endoreg_db.models import VideoFile
+
+logger = logging.getLogger(__name__)
+
+
+class VideoFileListSerializer(serializers.ModelSerializer):
+    """
+    Minimal serializer to return only basic video information
+    for the video selection dropdown in Vue.js.
+
+    Convention:
+        - Serializer methods must NOT raise if video state is missing or invalid.
+        - They return safe defaults and log what went wrong.
+    """
+
+    # Add computed fields for video status
+    status = serializers.SerializerMethodField()
+    assignedUser = serializers.SerializerMethodField()
+    anonymized = serializers.SerializerMethodField()
+
+    class Meta:
+        model = VideoFile
+        fields = ["id", "original_file_name", "status", "assignedUser", "anonymized"]
+
+    # --- internal helper -------------------------------------------------
+    def _get_video_state(self, obj: VideoFile):
+        """
+        Best-effort accessor for obj.state.
+
+        Serializer layer must never raise here; it only logs and returns None
+        if the state cannot be loaded for any reason.
+        """
+        try:
+            return getattr(obj, "state", None)
+        except (
+            Exception
+        ) as exc:  # pragma: no cover - type of error is DB/backend-specific
+            logger.warning(
+                "VideoFileListSerializer: unable to access state for VideoFile(id=%s): %s",
+                getattr(obj, "id", "unknown"),
+                exc,
+            )
+            return None
+
+    # --- public serializer fields ----------------------------------------
+    def get_status(
+        self, obj: VideoFile
+    ) -> Literal["completed", "in_progress", "available"]:
+        """
+        Determine the processing status of a video file as 'completed',
+        'in_progress', or 'available'.
+
+        Contract:
+            - Never raises.
+            - Missing or invalid state -> treated as 'available'.
+        """
+        state = self._get_video_state(obj)
+
+        if not state:
+            return "available"
+
+        # Use getattr with defaults to tolerate partially populated state objects
+        anonymized = getattr(state, "anonymized", False)
+        frames_extracted = getattr(state, "frames_extracted", False)
+
+        if anonymized:
+            return "completed"
+        if frames_extracted:
+            return "in_progress"
+        return "available"
+
+    def get_assignedUser(self, obj: VideoFile):
+        """
+        Returns the user assigned to the video, or None if no user is assigned.
+
+        Currently always returns None as user assignment is not implemented.
+        """
+        # For now return None, can be extended when user assignment is implemented
+        return None
+
+    def get_anonymized(self, obj: VideoFile) -> bool:
+        """
+        Determine whether the video has been anonymized.
+
+        Contract:
+            - Never raises.
+            - Returns False if state does not exist or cannot be loaded.
+        """
+        state = self._get_video_state(obj)
+        if not state:
+            return False
+
+        # getattr to be robust against partially/populated state
+        return bool(getattr(state, "anonymized", False))

endoreg_db/serializers/video/video_processing_history.py

@@ -0,0 +1,172 @@
+"""
+Video Processing History Serializer
+
+Serializes VideoProcessingHistory model for API responses.
+Created as part of Phase 1.1: Video Correction API Endpoints.
+"""
+
+from collections.abc import Mapping
+
+from rest_framework import serializers
+
+from endoreg_db.models import VideoProcessingHistory
+
+
+class VideoProcessingHistorySerializer(serializers.ModelSerializer):
+    """
+    Serializer for VideoProcessingHistory model.
+
+    Provides operation audit trail (masking, frame removal, analysis)
+    with download URLs for processed files.
+    """
+
+    download_url = serializers.SerializerMethodField()
+    operation_display = serializers.SerializerMethodField()
+    status_display = serializers.SerializerMethodField()
+    duration = serializers.ReadOnlyField()
+    is_complete = serializers.ReadOnlyField()
+
+    class Meta:
+        model = VideoProcessingHistory
+        fields = [
+            "id",
+            "video",
+            "operation",
+            "operation_display",
+            "status",
+            "status_display",
+            "config",
+            "output_file",
+            "download_url",
+            "details",
+            "task_id",
+            "created_at",
+            "completed_at",
+            "duration",
+            "is_complete",
+        ]
+        read_only_fields = ["id", "created_at", "completed_at"]
+
+    def get_download_url(self, obj) -> str | None:
+        """
+        Generate download URL for processed video file.
+
+        Args:
+            obj: VideoProcessingHistory instance
+
+        Returns:
+            str: URL to download processed file, or None if not available
+        """
+        if not obj.output_file or obj.status != VideoProcessingHistory.STATUS_SUCCESS:
+            return None
+
+        # Build URL to download endpoint (to be implemented)
+        # Format: /api/media/processed-videos/{video_id}/{history_id}/
+        context = self.context if isinstance(self.context, Mapping) else None
+        request = context.get("request") if context else None
+        if request:
+            return request.build_absolute_uri(
+                f"/api/media/processed-videos/{obj.video.id}/{obj.id}/"
+            )
+
+        return f"/api/media/processed-videos/{obj.video.id}/{obj.id}/"
+
+    def get_operation_display(self, obj) -> str:
+        display = getattr(obj, "get_operation_display", None)
+        result = display() if callable(display) else obj.operation
+        return str(result)
+
+    def get_status_display(self, obj) -> str:
+        display = getattr(obj, "get_status_display", None)
+        result = display() if callable(display) else obj.status
+        return str(result)
+
+    def validate_operation(self, value):
+        """
+        Validate operation is one of the defined choices.
+
+        Args:
+            value: Operation type
+
+        Returns:
+            str: Validated operation
+
+        Raises:
+            ValidationError: If operation is invalid
+        """
+        valid_operations = [
+            choice[0] for choice in VideoProcessingHistory.OPERATION_CHOICES
+        ]
+        if value not in valid_operations:
+            raise serializers.ValidationError(
+                f"Invalid operation. Must be one of: {', '.join(valid_operations)}"
+            )
+        return value
+
+    def validate_status(self, value):
+        """
+        Validate status is one of the defined choices.
+
+        Args:
+            value: Status type
+
+        Returns:
+            str: Validated status
+
+        Raises:
+            ValidationError: If status is invalid
+        """
+        valid_statuses = [choice[0] for choice in VideoProcessingHistory.STATUS_CHOICES]
+        if value not in valid_statuses:
+            raise serializers.ValidationError(
+                f"Invalid status. Must be one of: {', '.join(valid_statuses)}"
+            )
+        return value
+
+    def validate_config(self, value):
+        """
+        Validate config based on operation type.
+
+        Args:
+            value: Config dictionary
+
+        Returns:
+            dict: Validated config
+
+        Raises:
+            ValidationError: If config is invalid for operation
+        """
+        if not isinstance(value, dict):
+            raise serializers.ValidationError("config must be a dictionary")
+
+        initial = self.initial_data if isinstance(self.initial_data, Mapping) else {}
+        operation = initial.get("operation")
+
+        # Validate masking config
+        if operation == VideoProcessingHistory.OPERATION_MASKING:
+            required_fields = ["mask_type"]
+            if "mask_type" not in value:
+                raise serializers.ValidationError(
+                    f"Masking config must include: {', '.join(required_fields)}"
+                )
+
+            # If device mask, require device_name
+            if value["mask_type"] == "device" and "device_name" not in value:
+                raise serializers.ValidationError(
+                    "Device mask requires 'device_name' in config"
+                )
+
+            # If custom ROI, require roi coordinates
+            if value["mask_type"] == "custom" and "roi" not in value:
+                raise serializers.ValidationError(
+                    "Custom mask requires 'roi' coordinates in config"
+                )
+
+        # Validate frame removal config
+        elif operation == VideoProcessingHistory.OPERATION_FRAME_REMOVAL:
+            if "frame_list" not in value and "detection_method" not in value:
+                raise serializers.ValidationError(
+                    "Frame removal config must include 'frame_list' (manual) or 'detection_method' (automatic)"
+                )
+
+        return value