endoreg-db 0.8.9.32__py3-none-any.whl

endoreg_db/models/media/video/video_file_frames/_delete_frames.py

@@ -0,0 +1,126 @@
+import logging
+import shutil
+from typing import TYPE_CHECKING
+
+from django.db import transaction
+
+from endoreg_db.models.media.video.video_file_io import (
+    _get_frame_dir_path,
+    _get_temp_anonymized_frame_dir,
+)
+
+if TYPE_CHECKING:
+    from endoreg_db.models import VideoFile, VideoState
+
+logger = logging.getLogger(__name__)
+
+__all__ = ["_delete_frames"]
+
+
+@transaction.atomic
+def _delete_frames(video: "VideoFile") -> str:
+    """
+    Deletes extracted frame FILES ONLY. Resets relevant state flags atomically.
+    Also cleans up temporary anonymization frame directories.
+    Does NOT delete Frame objects from DB, but marks them as is_extracted=False.
+    Raises RuntimeError if state update fails.
+    """
+    from endoreg_db.models.media.frame import Frame
+
+    deleted_messages = []
+    error_messages = []
+    state_updated = False
+    db_updated = False
+
+    frame_dir = _get_frame_dir_path(video)
+    if frame_dir and frame_dir.exists():
+        try:
+            shutil.rmtree(frame_dir)
+            msg = f"Deleted frame directory: {frame_dir}"
+            logger.info(msg)
+            deleted_messages.append(msg)
+        except Exception as e:
+            msg = f"Error deleting frame directory {frame_dir}: {e}"
+            logger.error(msg, exc_info=True)
+            error_messages.append(msg)
+    elif frame_dir:
+        msg = f"Frame directory not found, skipping deletion: {frame_dir}"
+        logger.debug(msg)
+    else:
+        msg = f"Frame directory path not set for video {video.video_hash}, cannot delete standard frames."
+        logger.warning(msg)
+
+    temp_anonym_frame_dir = None
+    try:
+        temp_anonym_frame_dir = _get_temp_anonymized_frame_dir(video)
+        if temp_anonym_frame_dir and temp_anonym_frame_dir.exists():
+            shutil.rmtree(temp_anonym_frame_dir)
+            msg = (
+                f"Deleted temporary anonymized frame directory: {temp_anonym_frame_dir}"
+            )
+            logger.info(msg)
+            deleted_messages.append(msg)
+    except Exception as e:
+        msg = f"Error deleting temporary anonymized frame directory {temp_anonym_frame_dir}: {e}"
+        logger.error(msg, exc_info=True)
+        error_messages.append(msg)
+
+    try:
+        state: "VideoState" = video.get_or_create_state()
+        update_fields_state = []
+        if state.frames_extracted:
+            state.frames_extracted = False
+            update_fields_state.append("frames_extracted")
+
+        if update_fields_state:
+            state.save(update_fields=update_fields_state)
+            logger.info(
+                "Reset frame state flags (%s) for video %s.",
+                ", ".join(update_fields_state),
+                video.video_hash,
+            )
+            state_updated = True
+        else:
+            logger.info(
+                "Frame state flags already False for video %s.", video.video_hash
+            )
+            state_updated = True
+
+        try:
+            update_count = Frame.objects.filter(video=video, is_extracted=True).update(
+                is_extracted=False
+            )
+            if update_count > 0:
+                logger.info(
+                    "Marked %d Frame objects as is_extracted=False for video %s.",
+                    update_count,
+                    video.video_hash,
+                )
+            db_updated = True
+        except Exception as db_err:
+            msg = f"Failed to update is_extracted flag for Frame objects for video %s: {db_err}"
+            logger.error(msg, exc_info=True)
+            error_messages.append(msg)
+            db_updated = False
+
+    except Exception as state_e:
+        msg = (
+            f"Failed to update state after deleting frame files for video %s: {state_e}"
+        )
+        logger.error(msg, exc_info=True)
+        error_messages.append(msg)
+        raise RuntimeError(
+            f"Failed to update state during frame file deletion for video {video.video_hash}"
+        ) from state_e
+
+    final_message = "; ".join(deleted_messages)
+    if error_messages:
+        final_message += "; Errors occurred: " + "; ".join(error_messages)
+    elif state_updated and db_updated:
+        final_message += "; State flags and Frame objects updated successfully."
+    elif state_updated:
+        final_message += "; State flags updated; Frame object update skipped or failed."
+    else:
+        final_message += "; State/Frame update skipped due to errors."
+
+    return final_message

endoreg_db/models/media/video/video_file_frames/_extract_frames.py

@@ -0,0 +1,233 @@
+import logging
+from typing import TYPE_CHECKING
+
+from endoreg_db.models.media.video.video_file_io import _get_frame_dir_path
+from endoreg_db.utils.video.ffmpeg_wrapper import (
+    extract_frames as ffmpeg_extract_frames,
+)
+
+if TYPE_CHECKING:
+    from endoreg_db.models import VideoFile
+
+import shutil
+
+from django.db import transaction
+
+logger = logging.getLogger(__name__)
+
+
+def _extract_frames(
+    video: "VideoFile",
+    quality: int = 2,
+    overwrite: bool = False,
+    ext="jpg",
+    verbose=False,
+    from_processed: bool = False,
+) -> bool:
+    """
+    Extract frames from a raw video file, update frame extraction status in the database, and manage related file system operations.
+
+    This function checks for existing extracted frames and skips extraction if appropriate, unless overwriting is requested. It handles deletion of existing frames when overwriting, invokes ffmpeg to extract frames, parses extracted frame numbers, updates corresponding database records, and manages video extraction state. Robust error handling ensures cleanup and state rollback on failure.
+
+    Parameters:
+        video (VideoFile): The video object from which frames are to be extracted.
+        quality (int, optional): Quality parameter for ffmpeg extraction. Defaults to 2.
+        overwrite (bool, optional): Whether to overwrite existing extracted frames. Defaults to False.
+        ext (str, optional): File extension for extracted frames. Defaults to "jpg".
+
+    Returns:
+        bool: True if extraction and updates succeed.
+
+    Raises:
+        FileNotFoundError: If the raw video file is missing.
+        RuntimeError: If extraction or database update fails.
+        ValueError: If the frame directory path cannot be determined.
+    """
+    from endoreg_db.models.media.frame import Frame
+
+    from ._delete_frames import _delete_frames
+
+    if from_processed:
+        raw_file_path = video.get_processed_file_path()
+        if not raw_file_path or not raw_file_path.exists():
+            raise FileNotFoundError(
+                f"Processed video file not found at {raw_file_path} for video {video.video_hash}. Cannot extract frames."
+            )
+    else:
+        # Pre-validation checks (outside any transaction)
+        if not video.has_raw:
+            raise FileNotFoundError(
+                f"Raw video file not available for {video.video_hash}. Cannot extract frames."
+            )
+
+        raw_file_path = video.get_raw_file_path()
+        if not raw_file_path or not raw_file_path.exists():
+            raise FileNotFoundError(
+                f"Raw video file not found at {raw_file_path} for video {video.video_hash}. Cannot extract frames."
+            )
+
+    frame_dir = _get_frame_dir_path(video)
+    if not frame_dir:
+        raise ValueError(
+            f"Cannot determine frame directory path for video {video.video_hash}."
+        )
+
+    state = video.get_or_create_state()
+    frames_exist_in_db = Frame.objects.filter(video=video).exists()
+    files_exist_on_disk = frame_dir.exists() and any(frame_dir.iterdir())
+
+    # Fast-path: if frames exist and we are not overwriting, update state and return.
+    if (state.frames_extracted or files_exist_on_disk) and not overwrite:
+        logger.info(
+            "Frames already extracted or files exist for video %s, and overwrite=False. Skipping extraction.",
+            video.video_hash,
+        )
+        with transaction.atomic():
+            state.refresh_from_db()
+            if frames_exist_in_db:
+                updated_count = Frame.objects.filter(
+                    video=video, is_extracted=False
+                ).update(is_extracted=True)
+                if updated_count > 0:
+                    logger.info(
+                        "Marked %d existing Frame objects as extracted for video %s based on current records.",
+                        updated_count,
+                        video.video_hash,
+                    )
+            if files_exist_on_disk and not state.frames_extracted:
+                logger.warning(
+                    "Files exist on disk for video %s but state.frames_extracted is False. Persisting corrected state.",
+                    video.video_hash,
+                )
+                state.mark_frames_extracted(save=True)
+        return True
+
+    # Overwrite: delete existing frames/files before re-extraction.
+    if overwrite:
+        logger.info(
+            "Overwrite=True. Preparing to delete existing frames/files for video %s before extraction.",
+            video.video_hash,
+        )
+        try:
+            _delete_frames(video)
+            with transaction.atomic():
+                updated_count = Frame.objects.filter(
+                    video=video, is_extracted=True
+                ).update(is_extracted=False)
+                if updated_count > 0:
+                    logger.info(
+                        "Reset %d Frame objects to is_extracted=False for video %s due to overwrite.",
+                        updated_count,
+                        video.video_hash,
+                    )
+            state.refresh_from_db()
+        except Exception as del_e:
+            logger.error(
+                "Failed to delete existing frames for video %s during overwrite: %s",
+                video.video_hash,
+                del_e,
+                exc_info=True,
+            )
+            raise RuntimeError(
+                f"Failed to delete existing frames for video {video.video_hash} during overwrite."
+            ) from del_e
+
+    frame_dir.mkdir(parents=True, exist_ok=True)
+
+    try:
+        logger.info(
+            "Starting frame extraction for video %s to %s", video.video_hash, frame_dir
+        )
+        # Step 1: Perform the long-running frame extraction outside any transaction.
+        extracted_paths = ffmpeg_extract_frames(
+            raw_file_path, frame_dir, quality=quality, ext=ext
+        )
+        if not extracted_paths:
+            logger.warning(
+                "ffmpeg_extract_frames returned no paths for video %s. Check video duration and ffmpeg logs.",
+                video.video_hash,
+            )
+            if video.frame_count is not None and video.frame_count > 0:
+                raise RuntimeError(
+                    f"ffmpeg_extract_frames returned no paths for video {video.video_hash}, but {video.frame_count} frames were expected."
+                )
+
+        logger.info(
+            "Successfully extracted %d frames using ffmpeg for video %s.",
+            len(extracted_paths),
+            video.video_hash,
+        )
+
+        extracted_frame_numbers = []
+        for frame_path in extracted_paths:
+            try:
+                frame_number = int(frame_path.stem.split("_")[-1])
+                extracted_frame_numbers.append(frame_number)
+            except (ValueError, IndexError) as e:
+                logger.warning(
+                    "Could not parse frame number from extracted file %s: %s",
+                    frame_path.name,
+                    e,
+                )
+
+        # Step 2: Perform all the quick DB updates inside a minimal atomic transaction.
+        with transaction.atomic():
+            if extracted_frame_numbers:
+                try:
+                    update_count = Frame.objects.filter(
+                        video=video, frame_number__in=extracted_frame_numbers
+                    ).update(is_extracted=True)
+                    logger.info(
+                        "Marked %d Frame objects as is_extracted=True for video %s.",
+                        update_count,
+                        video.video_hash,
+                    )
+                    if update_count != len(extracted_frame_numbers):
+                        logger.warning(
+                            "Number of updated frames (%d) does not match number of parsed extracted files (%d) for video %s.",
+                            update_count,
+                            len(extracted_frame_numbers),
+                            video.video_hash,
+                        )
+                except Exception as update_e:
+                    logger.error(
+                        "Failed to update is_extracted flag for frames of video %s: %s",
+                        video.video_hash,
+                        update_e,
+                        exc_info=True,
+                    )
+            state.refresh_from_db()
+            state.mark_frames_extracted()
+        return True
+
+    except Exception as e:
+        logger.error(
+            "Frame extraction or update failed for video %s: %s",
+            video.video_hash,
+            e,
+            exc_info=True,
+        )
+        logger.warning(
+            "Cleaning up frame directory %s for video %s due to extraction error.",
+            frame_dir,
+            video.video_hash,
+        )
+        shutil.rmtree(frame_dir, ignore_errors=True)
+        try:
+            with transaction.atomic():
+                Frame.objects.filter(video=video, is_extracted=True).update(
+                    is_extracted=False
+                )
+                state.refresh_from_db()
+                if state.frames_extracted:
+                    state.frames_extracted = False
+                    state.save(update_fields=["frames_extracted"])
+        except Exception as db_err:
+            logger.error(
+                "Failed to reset flags/state in DB during error handling for video %s: %s",
+                video.video_hash,
+                db_err,
+            )
+        raise RuntimeError(
+            f"Frame extraction or update failed for video {video.video_hash}."
+        ) from e

endoreg_db/models/media/video/video_file_frames/_get_frame.py

@@ -0,0 +1,36 @@
+import logging
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from endoreg_db.models import Frame, VideoFile
+
+logger = logging.getLogger(__name__)
+
+
+def _get_frame(video: "VideoFile", frame_number: int) -> "Frame":
+    """Gets a specific Frame object by its frame number."""
+    from endoreg_db.models import Frame
+
+    try:
+        # Access related manager directly
+        return video.frames.get(frame_number=frame_number)
+    except AttributeError:
+        logger.error(
+            "Could not access frame %d for video %s via related manager.",
+            frame_number,
+            video.video_hash,
+        )
+        # Fallback query
+        return Frame.objects.get(video_file=video, frame_number=frame_number)
+    except Frame.DoesNotExist:
+        logger.error("Frame %d not found for video %s.", frame_number, video.video_hash)
+        raise  # Re-raise DoesNotExist
+    except Exception as e:
+        logger.error(
+            "Error getting frame %d for video %s: %s",
+            frame_number,
+            video.video_hash,
+            e,
+            exc_info=True,
+        )
+        raise  # Re-raise other exceptions

endoreg_db/models/media/video/video_file_frames/_get_frame_number.py

@@ -0,0 +1,13 @@
+import logging
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from endoreg_db.models import VideoFile
+
+logger = logging.getLogger(__name__)
+
+
+def _get_frame_number(video: "VideoFile") -> int:
+    """Counts the number of associated Frame objects in the database."""
+    # Access related manager directly
+    return video.frames.count()

endoreg_db/models/media/video/video_file_frames/_get_frame_path.py

@@ -0,0 +1,24 @@
+# --- Frame Creation/Deletion ---
+import logging
+from pathlib import Path
+from typing import TYPE_CHECKING, Optional
+
+if TYPE_CHECKING:
+    from endoreg_db.models import VideoFile
+
+logger = logging.getLogger(__name__)
+
+
+def _get_frame_path(video: "VideoFile", frame_number: int) -> Optional[Path]:
+    """Constructs the expected path for a given frame number."""
+    target_dir = video.get_frame_dir_path()  # Use IO helper
+    if not target_dir:
+        logger.warning(
+            "Cannot get frame path for video %s: Frame directory not set.",
+            video.video_hash,
+        )
+        return None
+
+    frame_filename = f"frame_{frame_number:07d}.jpg"
+    path = target_dir / frame_filename
+    return path

endoreg_db/models/media/video/video_file_frames/_get_frame_paths.py

@@ -0,0 +1,40 @@
+import logging
+from pathlib import Path
+from typing import TYPE_CHECKING, List
+
+from endoreg_db.models.media.video.video_file_io import _get_frame_dir_path
+
+if TYPE_CHECKING:
+    from endoreg_db.models import VideoFile
+
+logger = logging.getLogger(__name__)
+
+
+def _get_frame_paths(video: "VideoFile") -> List[Path]:
+    """Returns a sorted list of Path objects for extracted frame image files."""
+    frame_dir = _get_frame_dir_path(video)
+    if not frame_dir or not frame_dir.exists():
+        logger.warning(
+            "Frame directory %s does not exist for video %s.",
+            frame_dir,
+            video.video_hash,
+        )
+        return []
+
+    frame_paths = list(frame_dir.glob("frame_*.jpg"))
+
+    try:
+        frame_paths.sort(key=lambda p: int(p.stem.split("_")[-1]))
+    except (ValueError, IndexError) as e:
+        logger.error(
+            "Error sorting frame paths in %s: %s. Found paths: %s",
+            frame_dir,
+            e,
+            [p.name for p in frame_paths],
+            exc_info=True,
+        )
+        logger.warning(
+            "Falling back to unsorted frame paths to preserve available data."
+        )
+        return frame_paths
+    return frame_paths

endoreg_db/models/media/video/video_file_frames/_get_frame_range.py

@@ -0,0 +1,44 @@
+import logging
+from typing import TYPE_CHECKING
+
+from django.db.models import QuerySet
+
+if TYPE_CHECKING:
+    from endoreg_db.models import Frame, VideoFile
+
+logger = logging.getLogger(__name__)
+
+
+def _get_frame_range(
+    video: "VideoFile", start_frame_number: int, end_frame_number: int
+) -> "QuerySet[Frame]":
+    """Gets a QuerySet of Frame objects within a specific range, ordered by frame number."""
+    from endoreg_db.models import Frame
+
+    try:
+        # Access related manager directly
+        return video.frames.filter(
+            frame_number__gte=start_frame_number,
+            frame_number__lte=end_frame_number,
+        ).order_by("frame_number")
+    except AttributeError:
+        logger.error(
+            "Could not access frame range for video %s via related manager.",
+            video.video_hash,
+        )
+        # Fallback query
+        return Frame.objects.filter(
+            video_file=video,
+            frame_number__gte=start_frame_number,
+            frame_number__lte=end_frame_number,
+        ).order_by("frame_number")
+    except Exception as e:
+        logger.error(
+            "Error getting frame range (%d-%d) for video %s: %s",
+            start_frame_number,
+            end_frame_number,
+            video.video_hash,
+            e,
+            exc_info=True,
+        )
+        return Frame.objects.none()  # Return empty queryset on error

endoreg_db/models/media/video/video_file_frames/_get_frames.py

@@ -0,0 +1,30 @@
+import logging
+from typing import TYPE_CHECKING
+
+from django.db.models import QuerySet
+
+if TYPE_CHECKING:
+    from endoreg_db.models import Frame, VideoFile
+
+logger = logging.getLogger(__name__)
+
+
+def _get_frames(video: "VideoFile") -> "QuerySet[Frame]":
+    """Gets a QuerySet of all associated Frame objects, ordered by frame number."""
+    from endoreg_db.models import Frame
+
+    try:
+        # Access related manager directly
+        return video.frames.order_by("frame_number")
+    except AttributeError:
+        logger.error(
+            "Could not access frames for video %s. 'frames' related manager not found.",
+            video.video_hash,
+        )
+        # Fallback query
+        return Frame.objects.filter(video_file=video).order_by("frame_number")
+    except Exception as e:
+        logger.error(
+            "Error getting frames for video %s: %s", video.video_hash, e, exc_info=True
+        )
+        return Frame.objects.none()  # Return empty queryset on error