endoreg-db 0.4.5__py3-none-any.whl → 0.8.6.3__py3-none-any.whl

endoreg_db/serializers/video/segmentation.py

@@ -0,0 +1,263 @@
+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 django.conf import settings
+from typing import TYPE_CHECKING
+from rest_framework.exceptions import ValidationError
+if TYPE_CHECKING:
+    from endoreg_db.models import Video
+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:"Video"):
+        """
+        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.uuid
+
+    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:"Video"):
+        """
+        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:"Video"):
+        """
+        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:"Video"):
+        """
+        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:"Video"):
+        """
+        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:"Video"):
+        """
+        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:"Video"):
+        """
+        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,10 @@
+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,83 @@
+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,67 @@
+from typing import Literal
+from endoreg_db.models import VideoFile
+
+
+from rest_framework import serializers
+
+
+class VideoFileListSerializer(serializers.ModelSerializer):
+    """
+    Minimal serializer to return only basic video information
+    for the video selection dropdown in Vue.js.
+    """
+
+    # 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"]
+
+    def get_status(self, obj:VideoFile) -> Literal['completed'] | Literal['in_progress'] | Literal['available']:
+        """
+        Determine the processing status of a video file as 'completed', 'in_progress', or 'available'.
+        
+        Returns:
+            str: The video's status based on its processing state.
+            
+        Raises:
+            ValueError: If the video's state cannot be accessed.
+        """
+        try:
+            state = obj.state
+            if not state:
+                return 'available'
+            if state.anonymized:
+                return 'completed'
+            if state.frames_extracted:
+                return 'in_progress'
+            return 'available'
+        except Exception as _e:
+            raise ValueError("Video state should not be None") from _e
+
+    def get_assignedUser(self, obj):
+        """
+        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):
+        """
+        Determine whether the video has been anonymized.
+        
+        Returns:
+            bool: True if the video's state indicates it is anonymized; False otherwise or if state information is unavailable.
+        """
+        try:
+            state = getattr(obj, 'state', None)
+            if state:
+                return getattr(state, 'anonymized', False)
+            return False
+        except Exception:
+            return False

endoreg_db/serializers/video/video_metadata.py

@@ -0,0 +1,105 @@
+"""
+Video Metadata Serializer
+
+Serializes VideoMetadata model for API responses.
+Created as part of Phase 1.1: Video Correction API Endpoints.
+"""
+from rest_framework import serializers
+from endoreg_db.models.media.video import VideoMetadata
+import json
+
+
+class VideoMetadataSerializer(serializers.ModelSerializer):
+    """
+    Serializer for VideoMetadata model.
+    
+    Provides analysis results (sensitive frame count, ratio, frame IDs)
+    for the correction UI.
+    """
+    sensitive_frame_ids_list = serializers.SerializerMethodField()
+    sensitive_percentage = serializers.ReadOnlyField()
+    has_analysis = serializers.ReadOnlyField()
+    
+    class Meta:
+        model = VideoMetadata
+        fields = [
+            'id',
+            'video',
+            'sensitive_frame_count',
+            'sensitive_ratio',
+            'sensitive_frame_ids',
+            'sensitive_frame_ids_list',
+            'sensitive_percentage',
+            'has_analysis',
+            'analyzed_at',
+        ]
+        read_only_fields = ['id', 'analyzed_at']
+    
+    def get_sensitive_frame_ids_list(self, obj) -> list:
+        """
+        Parse sensitive_frame_ids from JSON string to Python list.
+        
+        Returns:
+            list: Frame indices (0-based), or empty list if no analysis
+        """
+        if not obj.sensitive_frame_ids:
+            return []
+        
+        try:
+            return json.loads(obj.sensitive_frame_ids)
+        except (json.JSONDecodeError, TypeError):
+            return []
+    
+    def validate_sensitive_frame_ids(self, value):
+        """
+        Validate that sensitive_frame_ids is a valid JSON array.
+        
+        Args:
+            value: JSON string representing frame IDs
+            
+        Returns:
+            str: Validated JSON string
+            
+        Raises:
+            ValidationError: If value is not valid JSON or not an array
+        """
+        if not value:
+            return value
+        
+        try:
+            parsed = json.loads(value)
+            if not isinstance(parsed, list):
+                raise serializers.ValidationError(
+                    "sensitive_frame_ids must be a JSON array"
+                )
+            
+            # Validate all elements are integers
+            if not all(isinstance(x, int) for x in parsed):
+                raise serializers.ValidationError(
+                    "All frame IDs must be integers"
+                )
+            
+            return value
+        except json.JSONDecodeError:
+            raise serializers.ValidationError(
+                "sensitive_frame_ids must be valid JSON"
+            )
+    
+    def validate_sensitive_ratio(self, value):
+        """
+        Validate that sensitive_ratio is between 0.0 and 1.0.
+        
+        Args:
+            value: Ratio value
+            
+        Returns:
+            float: Validated ratio
+            
+        Raises:
+            ValidationError: If value is outside valid range
+        """
+        if value is not None and (value < 0.0 or value > 1.0):
+            raise serializers.ValidationError(
+                "sensitive_ratio must be between 0.0 and 1.0"
+            )
+        return value

endoreg_db/serializers/video/video_processing_history.py

@@ -0,0 +1,153 @@
+"""
+Video Processing History Serializer
+
+Serializes VideoProcessingHistory model for API responses.
+Created as part of Phase 1.1: Video Correction API Endpoints.
+"""
+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.CharField(source='get_operation_display', read_only=True)
+    status_display = serializers.CharField(source='get_status_display', read_only=True)
+    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}/
+        request = self.context.get('request')
+        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 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")
+        
+        operation = self.initial_data.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