OTVision 0.6.1__py3-none-any.whl → 0.6.2__py3-none-any.whl

OTVision/track/model/track_exporter.py

@@ -0,0 +1,119 @@
+import logging
+from abc import ABC, abstractmethod
+from pathlib import Path
+from typing import Generic, Iterator, TypeVar
+
+from tqdm import tqdm
+
+from OTVision.config import CONFIG, DEFAULT_FILETYPE, TRACK
+from OTVision.dataformat import (
+    DATA,
+    DETECTIONS,
+    FRAME,
+    FRAME_GROUP,
+    INPUT_FILE_PATH,
+    METADATA,
+    TRACK_ID,
+    TRACKING,
+    TRACKING_RUN_ID,
+)
+from OTVision.helpers.files import write_json
+from OTVision.helpers.log import LOGGER_NAME
+
+log = logging.getLogger(LOGGER_NAME)
+
+
+F = TypeVar("F")  # Finished container: e.g. FinishedFrame or FinishedChunk
+
+
+class FinishedTracksExporter(ABC, Generic[F]):
+
+    def __init__(self, file_type: str = CONFIG[DEFAULT_FILETYPE][TRACK]):
+        self.file_type = file_type
+
+    @abstractmethod
+    def get_detection_dicts(self, container: F) -> list[dict]:
+        pass
+
+    @abstractmethod
+    def get_result_path(self, container: F) -> Path:
+        pass
+
+    @abstractmethod
+    def get_metadata(self, container: F) -> dict:
+        pass
+
+    @abstractmethod
+    def get_frame_group_id(self, container: F) -> int:
+        pass
+
+    def export(
+        self, tracking_run_id: str, stream: Iterator[F], overwrite: bool
+    ) -> None:
+        for container in stream:
+            self.export_frames(container, tracking_run_id, overwrite)
+
+    def export_frames(
+        self, container: F, tracking_run_id: str, overwrite: bool
+    ) -> None:
+        file_path = self.get_result_path(container)
+
+        det_dicts = self.reindex(self.get_detection_dicts(container))
+
+        output = self.build_output(
+            det_dicts,
+            self.get_metadata(container),
+            tracking_run_id,
+            self.get_frame_group_id(container),
+        )
+
+        write_json(
+            dict_to_write=output,
+            file=Path(file_path),
+            filetype=self.file_type,
+            overwrite=overwrite,
+        )
+
+        log.info(f"Successfully tracked and wrote {file_path}")
+
+    @staticmethod
+    def reindex(det_dicts: list[dict]) -> list[dict]:
+        min_frame_no = min(det[FRAME] for det in det_dicts)
+
+        det_dicts_progress = tqdm(
+            det_dicts,
+            desc="reindex TrackedDetections",
+            total=len(det_dicts),
+            leave=False,
+        )
+        reindexed_dets = [
+            {**det, **{FRAME: det[FRAME] - min_frame_no + 1}}
+            for det in det_dicts_progress
+        ]
+
+        if len(reindexed_dets) == 0:
+            return []
+
+        if len({detection[INPUT_FILE_PATH] for detection in reindexed_dets}) > 1:
+            raise ValueError("Expect detections from only a single source file")
+
+        reindexed_dets.sort(
+            key=lambda detection: (
+                detection[INPUT_FILE_PATH],
+                detection[FRAME],
+                detection[TRACK_ID],
+            )
+        )
+
+        return reindexed_dets
+
+    @staticmethod
+    def build_output(
+        detections: list[dict],
+        metadata: dict,
+        tracking_run_id: str,
+        frame_group_id: int,
+    ) -> dict:
+        metadata[TRACKING][TRACKING_RUN_ID] = tracking_run_id
+        metadata[TRACKING][FRAME_GROUP] = frame_group_id
+        return {METADATA: metadata, DATA: {DETECTIONS: detections}}

OTVision/track/model/tracking_interfaces.py

@@ -0,0 +1,309 @@
+from abc import ABC, abstractmethod
+from typing import Generic, Iterator, TypeVar
+
+from OTVision.track.model.frame import (
+    FinishedFrame,
+    Frame,
+    FrameNo,
+    IsLastFrame,
+    TrackedFrame,
+    TrackId,
+)
+
+S = TypeVar("S")  # Source type (e.g., Path, URL, str, etc.)
+# -> would look nicer in python 3.12
+
+ID_GENERATOR = Iterator[TrackId]
+
+
+class Tracker(ABC, Generic[S]):
+    """Tracker interface for processing a stream of Frames
+    to add tracking information, creating a lazy stream (generator)
+    of TrackedFrames.
+
+    Implementing class can specify template method:
+    track_frame for processing a single frame.
+
+    Args:
+        Generic (S): generic type of Frame source (e.g. file path, or stream url)
+    """
+
+    def track(
+        self, frames: Iterator[Frame[S]], id_generator: ID_GENERATOR
+    ) -> Iterator[TrackedFrame[S]]:
+        """Process the given stream of Frames,
+        yielding TrackedFrames one by one as a lazy stream of TrackedFrames.
+
+        Args:
+            frames (Iterator[Frame[S]]): (lazy) stream of Frames
+                with untracked Detections.
+            id_generator (ID_GENERATOR): provider of new (unique) track ids.
+
+        Yields:
+            Iterator[TrackedFrame[S]]: (lazy) stream of TrackedFrames with
+                TrackedDetections
+        """
+        for frame in frames:
+            yield self.track_frame(frame, id_generator)
+
+    @abstractmethod
+    def track_frame(
+        self,
+        frame: Frame[S],
+        id_generator: ID_GENERATOR,
+    ) -> TrackedFrame[S]:
+        """Process single Frame with untracked Detections,
+        by adding tracking information,
+        creating a TrackedFrame with TrackedDetections.
+
+        Args:
+            frame (Frame[S]): the Frame (with source S) to be tracked.
+            id_generator (ID_GENERATOR): provider of new (unique) track ids.
+
+        Returns:
+            TrackedFrame[S]: TrackedFrame with TrackedDetections
+        """
+        pass
+
+
+C = TypeVar("C")  # Detection container: e.g. TrackedFrame or TrackedChunk
+F = TypeVar("F")  # Finished container: e.g. FinishedFrame or FinishedChunk
+
+
+class UnfinishedTracksBuffer(ABC, Generic[C, F]):
+    """UnfinishedTracksBuffer provides functionality
+    to add finished information to tracked detections.
+
+    It processes containers (C) of TrackedDetections, buffers them
+    and stores track ids that are reported as finished.
+    Only when all tracks of a container (C) were marked as finished,
+    it is converted into a finished container (F) and yielded.
+
+    Args:
+        Generic (C): generic type of TrackedDetection container
+            (e.g. TrackedFrame or TrackedChunk)
+        Generic (F): generic type of FinishedDetection container
+            (e.g. FinishedFrame or FinishedChunk)
+        keep_discarded (bool): whether detections marked as discarded should
+            be kept of filtered when finishing them. Defaults to False.
+    """
+
+    def __init__(self, keep_discarded: bool = False) -> None:
+        self._keep_discarded = keep_discarded
+        self._unfinished_containers: list[tuple[C, set[TrackId]]] = list()
+        self._merged_last_track_frame: dict[TrackId, FrameNo] = dict()
+        self._discarded_tracks: set[TrackId] = set()
+
+    @abstractmethod
+    def _get_last_track_frames(self, container: C) -> dict[TrackId, FrameNo]:
+        """Mapping from TrackId to frame no of last detection occurrence.
+        Mapping for all tracks in newly tracked container.
+
+        Args:
+            container (C): newly tracked TrackedDetection container
+
+        Returns:
+            dict[TrackId, int]: last frame no by TrackId
+        """
+        pass
+
+    @abstractmethod
+    def _get_unfinished_tracks(self, container: C) -> set[TrackId]:
+        """TrackIds of given container, that are marked as unfinished.
+
+        Args:
+            container (C): newly tracked TrackedDetection container
+
+        Returns:
+            set[TrackId]: TrackIds of container marked as unfinished
+        """
+        pass
+
+    @abstractmethod
+    def _get_observed_tracks(self, container: C) -> set[TrackId]:
+        """TrackIds observed given (newly tracked) container.
+
+        Args:
+            container (C): newly tracked TrackedDetection container
+
+        Returns:
+            set[TrackId]: observed TrackIds of container
+        """
+        pass
+
+    @abstractmethod
+    def _get_newly_finished_tracks(self, container: C) -> set[TrackId]:
+        """TrackIds marked as finished in the given (newly tracked) container.
+
+        Args:
+            container (C): newly tracked TrackedDetection container
+
+        Returns:
+            set[TrackId]: finished TrackIds in container
+        """
+        pass
+
+    @abstractmethod
+    def _get_newly_discarded_tracks(self, container: C) -> set[TrackId]:
+        """TrackIds marked as discarded in the given (newly tracked) container.
+
+        Args:
+            container (C): newly tracked TrackedDetection container
+
+        Returns:
+            set[TrackId]: discarded TrackIds in container
+        """
+        pass
+
+    @abstractmethod
+    def _get_last_frame_of_container(self, container: C) -> FrameNo:
+        """The last FrameNo of the given container.
+
+        Args:
+            container (C): newly tracked TrackedDetection container
+
+        Returns:
+            FrameNo: last FrameNo of the given container
+        """
+        pass
+
+    @abstractmethod
+    def _finish(
+        self,
+        container: C,
+        is_last: IsLastFrame,
+        discarded_tracks: set[TrackId],
+        keep_discarded: bool,
+    ) -> F:
+        """Transform the given container to a finished container
+        by adding is_finished information to all contained TrackedDetections
+        turning them into FinishedDetections.
+
+        Args:
+            container (C): container of TrackedDetections
+            is_last (IsLastFrame): check whether a track ends in a certain frame
+            keep_discarded (bool): whether detections marked as discarded are kept.
+        Returns:
+            F: a finished container with transformed detections of given container
+        """
+        pass
+
+    def track_and_finish(self, containers: Iterator[C]) -> Iterator[F]:
+        # TODO template method to obtain containers?
+
+        for container in containers:
+
+            # if track is observed in current iteration, update its last observed frame
+            new_last_track_frames = self._get_last_track_frames(container)
+            self._merged_last_track_frame.update(new_last_track_frames)
+
+            newly_unfinished_tracks = self._get_unfinished_tracks(container)
+            self._unfinished_containers.append((container, newly_unfinished_tracks))
+
+            # update unfinished track ids of previously tracked containers
+            # if containers have no pending tracks, make ready for finishing
+            newly_finished_tracks = self._get_newly_finished_tracks(container)
+            newly_discarded_tracks = self._get_newly_discarded_tracks(container)
+            self._discarded_tracks.update(newly_discarded_tracks)
+
+            ready_containers: list[C] = []
+            for c, track_ids in self._unfinished_containers:
+                track_ids.difference_update(newly_finished_tracks)
+                track_ids.difference_update(newly_discarded_tracks)
+
+                if not track_ids:
+                    ready_containers.append(c)
+
+            self._unfinished_containers = [
+                (c, u)
+                for c, u in self._unfinished_containers
+                if c not in ready_containers
+            ]
+
+            finished_containers: list[F] = self._finish_containers(ready_containers)
+            yield from finished_containers
+
+        # finish remaining containers with pending tracks
+        remaining_containers = [c for c, _ in self._unfinished_containers]
+        self._unfinished_containers = list()
+
+        finished_containers = self._finish_containers(remaining_containers)
+        self._merged_last_track_frame = dict()
+        yield from finished_containers
+
+    def _finish_containers(self, containers: list[C]) -> list[F]:
+        if len(containers) == 0:
+            return []
+
+        def is_last(frame_no: FrameNo, track_id: TrackId) -> bool:
+            return frame_no == self._merged_last_track_frame[track_id]
+
+        keep = self._keep_discarded
+        discarded = self._discarded_tracks
+
+        finished_containers: list[F] = [
+            self._finish(c, is_last, discarded, keep) for c in containers
+        ]
+
+        # todo check if there are edge cases where track ids in merged_last_track_frame
+        # have frame no below containers last frame,
+        # but might appear in following containers
+        last_frame_of_container = max(
+            self._get_last_frame_of_container(c) for c in containers
+        )
+        ids_to_delete = [
+            track_id
+            for track_id, frame_no in self._merged_last_track_frame.items()
+            if frame_no <= last_frame_of_container
+        ]
+
+        self._merged_last_track_frame = {
+            track_id: frame_no
+            for track_id, frame_no in self._merged_last_track_frame.items()
+            if track_id not in ids_to_delete
+        }
+        self._discarded_tracks.difference_update(ids_to_delete)
+        # self._finished_tracks.difference_update(ids_to_delete)
+
+        return finished_containers
+
+
+class UnfinishedFramesBuffer(UnfinishedTracksBuffer[TrackedFrame[S], FinishedFrame[S]]):
+    """UnfinishedTracksBuffer implementation for Frames as Detection container."""
+
+    def __init__(self, tracker: Tracker[S], keep_discarded: bool = False):
+        super().__init__(keep_discarded)
+        self._tracker = tracker
+
+    def track(
+        self, frames: Iterator[Frame[S]], id_generator: ID_GENERATOR
+    ) -> Iterator[FinishedFrame[S]]:
+        tracked_frame_stream = self._tracker.track(frames, id_generator)
+        return self.track_and_finish(tracked_frame_stream)
+
+    def _get_last_track_frames(self, container: TrackedFrame[S]) -> dict[TrackId, int]:
+        return {o: container.no for o in container.observed_tracks}
+
+    def _get_unfinished_tracks(self, container: TrackedFrame[S]) -> set[TrackId]:
+        return container.unfinished_tracks
+
+    def _get_observed_tracks(self, container: TrackedFrame[S]) -> set[TrackId]:
+        return container.observed_tracks
+
+    def _get_newly_finished_tracks(self, container: TrackedFrame[S]) -> set[TrackId]:
+        return container.finished_tracks
+
+    def _get_newly_discarded_tracks(self, container: TrackedFrame[S]) -> set[TrackId]:
+        return container.discarded_tracks
+
+    def _get_last_frame_of_container(self, container: TrackedFrame[S]) -> FrameNo:
+        return container.no
+
+    def _finish(
+        self,
+        container: TrackedFrame[S],
+        is_last: IsLastFrame,
+        discarded_tracks: set[TrackId],
+        keep_discarded: bool,
+    ) -> FinishedFrame[S]:
+        return container.finish(is_last, discarded_tracks, keep_discarded)

OTVision/track/parser/chunk_parser_plugins.py

@@ -0,0 +1,99 @@
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+
+from tqdm import tqdm
+
+from OTVision.dataformat import (
+    CLASS,
+    CONFIDENCE,
+    DATA,
+    DATE_FORMAT,
+    DETECTIONS,
+    OCCURRENCE,
+    H,
+    W,
+    X,
+    Y,
+)
+from OTVision.helpers.date import (
+    parse_date_string_to_utc_datime,
+    parse_timestamp_string_to_utc_datetime,
+)
+from OTVision.helpers.files import denormalize_bbox, read_json
+from OTVision.track.model.detection import Detection
+from OTVision.track.model.filebased.frame_chunk import ChunkParser, FrameChunk
+from OTVision.track.model.filebased.frame_group import FrameGroup
+from OTVision.track.model.frame import Frame
+
+
+class JsonChunkParser(ChunkParser):
+
+    def parse(
+        self, file: Path, frame_group: FrameGroup, frame_offset: int = 0
+    ) -> FrameChunk:
+        json = read_json(file)
+        metadata: dict = frame_group.metadata_by_file[file]
+
+        denormalized = denormalize_bbox(
+            json, file, metadata={file.as_posix(): metadata}
+        )
+        input: dict[int, dict[str, Any]] = denormalized[DATA]
+
+        frames = self.convert(file, frame_offset, input)
+
+        frames.sort(key=lambda frame: (frame.occurrence, frame.no))
+        return FrameChunk(file, metadata, frames, frame_group.id)
+
+    def convert(
+        self, file: Path, frame_offset: int, input: dict[int, dict[str, Any]]
+    ) -> list[Frame[Path]]:
+        detection_parser = DetectionParser()
+        frames = []
+
+        input_progress = tqdm(
+            input.items(), desc="parse Frames", total=len(input), leave=False
+        )
+        for key, value in input_progress:
+            occurrence: datetime = parse_datetime(value[OCCURRENCE])
+            data_detections = value[DETECTIONS]
+            detections = detection_parser.convert(data_detections)
+            parsed_frame = Frame(
+                int(key) + frame_offset,
+                occurrence=occurrence,
+                source=file,
+                detections=detections,
+                image=None,
+            )
+            frames.append(parsed_frame)
+        return frames
+
+
+class DetectionParser:
+    def convert(self, detection_data: list[dict[str, str]]) -> list[Detection]:
+        detections: list[Detection] = []
+        for detection in detection_data:
+            detected_item = Detection(
+                detection[CLASS],
+                float(detection[CONFIDENCE]),
+                float(detection[X]),
+                float(detection[Y]),
+                float(detection[W]),
+                float(detection[H]),
+            )
+            detections.append(detected_item)
+        return detections
+
+
+def parse_datetime(date: str | float) -> datetime:
+    """Parse a date string or timestamp to a datetime with UTC as timezone.
+
+    Args:
+        date (str | float): the date to parse
+
+    Returns:
+        datetime: the parsed datetime object with UTC set as timezone
+    """
+    if isinstance(date, str) and ("-" in date):
+        return parse_date_string_to_utc_datime(date, DATE_FORMAT)
+    return parse_timestamp_string_to_utc_datetime(date)

OTVision/track/parser/frame_group_parser_plugins.py

@@ -0,0 +1,127 @@
+import re
+from datetime import datetime, timedelta
+from pathlib import Path
+
+from OTVision import version
+from OTVision.dataformat import (
+    EXPECTED_DURATION,
+    FILENAME,
+    FIRST_TRACKED_VIDEO_START,
+    LAST_TRACKED_VIDEO_END,
+    LENGTH,
+    OTTRACK_VERSION,
+    OTVISION_VERSION,
+    RECORDED_START_DATE,
+    TRACKER,
+    TRACKING,
+    VIDEO,
+)
+from OTVision.helpers.files import (
+    FULL_FILE_NAME_PATTERN,
+    HOSTNAME,
+    InproperFormattedFilename,
+    read_json_bz2_metadata,
+)
+from OTVision.track.model.filebased.frame_group import FrameGroup, FrameGroupParser
+from OTVision.track.parser.chunk_parser_plugins import parse_datetime
+
+MISSING_START_DATE = datetime(1900, 1, 1)
+MISSING_EXPECTED_DURATION = timedelta(minutes=15)
+
+
+class TimeThresholdFrameGroupParser(FrameGroupParser):
+
+    def __init__(
+        self, tracker_data: dict, time_without_frames: timedelta = timedelta(minutes=1)
+    ):
+        self._time_without_frames = time_without_frames
+        self._tracker_data: dict = tracker_data
+        self._id_count = 0
+
+    def new_id(self) -> int:
+        self._id_count += 1
+        return self._id_count
+
+    def parse(self, file: Path) -> FrameGroup:
+        metadata = read_json_bz2_metadata(file)
+        return self.convert(file, metadata)
+
+    def convert(self, file: Path, metadata: dict) -> FrameGroup:
+        start_date: datetime = self.extract_start_date_from(metadata)
+        duration: timedelta = self.extract_expected_duration_from(metadata)
+        end_date: datetime = start_date + duration
+        hostname = self.get_hostname(metadata)
+
+        return FrameGroup(
+            id=self.new_id(),
+            start_date=start_date,
+            end_date=end_date,
+            files=[file],
+            metadata_by_file={file: metadata},
+            hostname=hostname,
+        )
+
+    def get_hostname(self, file_metadata: dict) -> str:
+        video_name = Path(file_metadata[VIDEO][FILENAME]).name
+        match = re.search(
+            FULL_FILE_NAME_PATTERN,
+            video_name,
+        )
+        if match:
+            return match.group(HOSTNAME)
+
+        raise InproperFormattedFilename(f"Could not parse {video_name}.")
+
+    def extract_start_date_from(self, metadata: dict) -> datetime:
+        if RECORDED_START_DATE in metadata[VIDEO].keys():
+            recorded_start_date = metadata[VIDEO][RECORDED_START_DATE]
+            return parse_datetime(recorded_start_date)
+        return MISSING_START_DATE
+
+    def extract_expected_duration_from(self, metadata: dict) -> timedelta:
+        if EXPECTED_DURATION in metadata[VIDEO].keys():
+            if expected_duration := metadata[VIDEO][EXPECTED_DURATION]:
+                return timedelta(seconds=int(expected_duration))
+        return self.parse_video_length(metadata)
+
+    def parse_video_length(self, metadata: dict) -> timedelta:
+        video_length = metadata[VIDEO][LENGTH]
+        time = datetime.strptime(video_length, "%H:%M:%S")
+        return timedelta(hours=time.hour, minutes=time.minute, seconds=time.second)
+
+    def update_metadata(self, frame_group: FrameGroup) -> dict[Path, dict]:
+        metadata_by_file = dict(frame_group.metadata_by_file)
+        for filepath in frame_group.files:
+            metadata = metadata_by_file[filepath]
+            metadata[OTTRACK_VERSION] = version.ottrack_version()
+            metadata[TRACKING] = {
+                OTVISION_VERSION: version.otvision_version(),
+                FIRST_TRACKED_VIDEO_START: frame_group.start_date.timestamp(),
+                LAST_TRACKED_VIDEO_END: frame_group.end_date.timestamp(),
+                TRACKER: self._tracker_data,
+            }
+
+        return metadata_by_file
+
+    def merge(self, frame_groups: list[FrameGroup]) -> list[FrameGroup]:
+        if len(frame_groups) == 0:
+            return []
+
+        merged_groups = []
+        sorted_groups = sorted(frame_groups, key=lambda group: group.start_date)
+        last_group = sorted_groups[0]
+        for current_group in sorted_groups[1:]:
+            if last_group.hostname != current_group.hostname:
+                merged_groups.append(last_group)
+                last_group = current_group
+            elif (
+                timedelta(seconds=0)
+                <= (current_group.start_date - last_group.end_date)
+                <= self._time_without_frames
+            ):
+                last_group = last_group.merge(current_group)
+            else:
+                merged_groups.append(last_group)
+                last_group = current_group
+        merged_groups.append(last_group)
+        return merged_groups