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

OTVision/detect/cli.py

@@ -110,8 +110,8 @@ class ArgparseDetectCliParser(DetectCliParser):
             "--start-time",
             default=None,
             type=str,
-            help=f"Specify start date and time of the recording in format "
-            f"{DATETIME_FORMAT}.",
+            help="Specify start date and time of the recording in format "
+            "YYYY-MM-DD_HH-MM-SS",
             required=False,
         )
         self._parser.add_argument(

OTVision/helpers/files.py

@@ -329,6 +329,7 @@ def get_metadata(otdict: dict) -> dict:
 # TODO: Type hint nested dict during refactoring
 def denormalize_bbox(
     otdict: dict,
+    file_path: Path | None = None,
     keys_width: Union[list[str], None] = None,
     keys_height: Union[list[str], None] = None,
     metadata: dict[str, dict] = {},
@@ -337,6 +338,8 @@ def denormalize_bbox(
 
     Args:
         otdict (dict): dict of detections or tracks
+        file_path (Path): file path source of the given otdict
+            if all detections stem from the same file.
         keys_width (list[str], optional): list of keys describing horizontal position.
             Defaults to ["x", "w"].
         keys_height (list[str], optional): list of keys describing vertical position.
@@ -351,7 +354,9 @@ def denormalize_bbox(
     if keys_height is None:
         keys_height = [dataformat.Y, dataformat.H]
     log.debug("Denormalize frame wise")
-    otdict = _denormalize_transformation(otdict, keys_width, keys_height, metadata)
+    otdict = _denormalize_transformation(
+        otdict, keys_width, keys_height, metadata, file_path
+    )
     return otdict
 
 
@@ -361,6 +366,7 @@ def _denormalize_transformation(
     keys_width: list[str],
     keys_height: list[str],
     metadata: dict[str, dict] = {},
+    file_path: Path | None = None,
 ) -> dict:
     """Helper to do the actual denormalization.
 
@@ -371,6 +377,8 @@ def _denormalize_transformation(
         keys_height (list[str]): list of keys describing vertical position.
             Defaults to ["y", "h"].
         metadata (dict[str, dict]): dict of metadata per input file.
+        file_path (Path): file path source of otdict
+            if all detections stem from the same file.
 
     Returns:
         dict: denormalized dict
@@ -378,7 +386,7 @@ def _denormalize_transformation(
     changed_files = set()
 
     for frame in otdict[dataformat.DATA].values():
-        input_file = frame[INPUT_FILE_PATH]
+        input_file = file_path.as_posix() if file_path else frame[INPUT_FILE_PATH]
         metadate = metadata[input_file]
         width = metadate[dataformat.VIDEO][dataformat.WIDTH]
         height = metadate[dataformat.VIDEO][dataformat.HEIGHT]

OTVision/helpers/input_types.py

@@ -0,0 +1,15 @@
+def check_types(
+    sigma_l: float, sigma_h: float, sigma_iou: float, t_min: int, t_miss_max: int
+) -> None:
+    """Raise ValueErrors if wrong types"""
+
+    if not isinstance(sigma_l, (int, float)):
+        raise ValueError("sigma_l has to be int or float")
+    if not isinstance(sigma_h, (int, float)):
+        raise ValueError("sigma_h has to be int or float")
+    if not isinstance(sigma_iou, (int, float)):
+        raise ValueError("sigma_iou has to be int or float")
+    if not isinstance(t_min, int):
+        raise ValueError("t_min has to be int")
+    if not isinstance(t_miss_max, int):
+        raise ValueError("t_miss_max has to be int")

OTVision/track/exporter/filebased_exporter.py

@@ -0,0 +1,24 @@
+from pathlib import Path
+
+from OTVision.config import CONFIG, DEFAULT_FILETYPE, TRACK
+from OTVision.track.model.filebased.frame_chunk import FinishedChunk
+from OTVision.track.model.filebased.frame_group import get_output_file
+from OTVision.track.model.track_exporter import FinishedTracksExporter
+
+
+class FinishedChunkTrackExporter(FinishedTracksExporter[FinishedChunk]):
+
+    def __init__(self, file_type: str = CONFIG[DEFAULT_FILETYPE][TRACK]) -> None:
+        super().__init__(file_type)
+
+    def get_detection_dicts(self, container: FinishedChunk) -> list[dict]:
+        return container.to_detection_dicts()
+
+    def get_result_path(self, container: FinishedChunk) -> Path:
+        return get_output_file(container.file, self.file_type)
+
+    def get_metadata(self, container: FinishedChunk) -> dict:
+        return container.metadata
+
+    def get_frame_group_id(self, container: FinishedChunk) -> int:
+        return container.frame_group_id

OTVision/track/model/detection.py

@@ -0,0 +1,141 @@
+from dataclasses import dataclass
+
+from OTVision.dataformat import (
+    CLASS,
+    CONFIDENCE,
+    FINISHED,
+    FIRST,
+    INTERPOLATED_DETECTION,
+    TRACK_ID,
+    H,
+    W,
+    X,
+    Y,
+)
+
+TrackId = int
+
+
+@dataclass(frozen=True, repr=True)
+class Detection:
+    """Detection data without track context data.
+
+    Attributes:
+        label (str): Assigned label, e.g. vehicle class.
+        conf (float): Confidence of detected class.
+        x (float): X-coordinate of detection center.
+        y (float): Y-coordinate of detection center.
+        w (float): Width of detection.
+        h (float): Height of detection.
+    """
+
+    label: str
+    conf: float
+    x: float
+    y: float
+    w: float
+    h: float
+
+    def of_track(self, id: TrackId, is_first: bool) -> "TrackedDetection":
+        """Convert to TrackedDetection by adding track information.
+
+        Args:
+            id (TrackId): id of assigned track.
+            is_first (bool): whether this detection is first of track.
+
+        Returns:
+            TrackedDetection: This detection data with additional track information.
+        """
+        return TrackedDetection(
+            self.label,
+            self.conf,
+            self.x,
+            self.y,
+            self.w,
+            self.h,
+            is_first,
+            id,
+        )
+
+    def to_otdet(self) -> dict:
+        return {
+            CLASS: self.label,
+            CONFIDENCE: self.conf,
+            X: self.x,
+            Y: self.y,
+            W: self.w,
+            H: self.h,
+        }
+
+
+@dataclass(frozen=True, repr=True)
+class TrackedDetection(Detection):
+    """Detection with additional track data.
+    At the time a detection is tracked,
+    it might not be known whether it is the last of a track.
+
+    Attributes:
+        is_first (bool): whether this detection is the first in the track.
+        track_id (TrackId): id of the assigned track.
+    """
+
+    is_first: bool
+    track_id: TrackId
+
+    def finish(self, is_last: bool, is_discarded: bool) -> "FinishedDetection":
+        return FinishedDetection.from_tracked_detection(self, is_last, is_discarded)
+
+    def as_last_detection(self, is_discarded: bool) -> "FinishedDetection":
+        return FinishedDetection.from_tracked_detection(
+            self, is_last=True, is_discarded=is_discarded
+        )
+
+    def as_intermediate_detection(self, is_discarded: bool) -> "FinishedDetection":
+        return FinishedDetection.from_tracked_detection(
+            self, is_last=False, is_discarded=is_discarded
+        )
+
+
+@dataclass(frozen=True, repr=True)
+class FinishedDetection(TrackedDetection):
+    """Detection data with extended track information including is_finished.
+
+    Attributes:
+        is_last (bool): whether this detection is the last in the track.
+        is_discarded (bool): whether the detections's track was discarded.
+    """
+
+    is_last: bool
+    is_discarded: bool
+
+    @classmethod
+    def from_tracked_detection(
+        cls, tracked_detection: TrackedDetection, is_last: bool, is_discarded: bool
+    ) -> "FinishedDetection":
+        td = tracked_detection
+        return cls(
+            label=td.label,
+            conf=td.conf,
+            x=td.x,
+            y=td.y,
+            w=td.w,
+            h=td.h,
+            is_first=td.is_first,
+            track_id=td.track_id,
+            is_last=is_last,
+            is_discarded=is_discarded,
+        )
+
+    def to_dict(self) -> dict:
+        return {
+            CLASS: self.label,
+            CONFIDENCE: self.conf,
+            X: self.x,
+            Y: self.y,
+            W: self.w,
+            H: self.h,
+            INTERPOLATED_DETECTION: False,
+            FIRST: self.is_first,
+            FINISHED: self.is_last,
+            TRACK_ID: self.track_id,
+        }

OTVision/track/model/filebased/frame_chunk.py

@@ -0,0 +1,203 @@
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field, replace
+from pathlib import Path
+from typing import Sequence
+
+from tqdm import tqdm
+
+from OTVision.dataformat import FRAME, INPUT_FILE_PATH, TRACK_ID
+from OTVision.track.model.filebased.frame_group import FrameGroup, get_output_file
+from OTVision.track.model.frame import (
+    FinishedFrame,
+    Frame,
+    FrameNo,
+    IsLastFrame,
+    TrackedFrame,
+    TrackId,
+)
+
+
+@dataclass(frozen=True)
+class FrameChunk:
+    """
+    A chunk of Frames obtained from a common file path source.
+
+    Attributes:
+        file (Path): common file path source of Frames.
+        metadata (dict): otdet metadata.
+        frames (Sequence[Frame[Path]]): a sequence of untracked Frames.
+        frame_group_id (int): id of FrameGroup this FrameCHunk is part of.
+    """
+
+    file: Path
+    metadata: dict
+    frames: Sequence[Frame[Path]]
+    frame_group_id: int
+
+    def check_output_file_exists(self, with_suffix: str) -> bool:
+        return get_output_file(self.file, with_suffix).is_file()
+
+
+@dataclass(frozen=True)
+class TrackedChunk(FrameChunk):
+    """A chunk of TrackedFrames extends FrameChunk.
+    Aggregates observed/finished/unfinished tracking metadata.
+
+    If is_last_chunk is true, all unfinished tracks
+    are marked as finished in last frame.
+
+    Attributes:
+        is_last_chunk (bool): whether this chunk is the last of
+            subsequently (related/connected) chunks.
+        frames (Sequence[TrackedFrame[Path]]): overrides frames
+            with more specific frame type.
+        finished_tracks (set[TrackId]): aggregates finished tracks
+            of given TrackedFrames.
+        observed_tracks (set[TrackId]): aggregates observed tracks
+            of given TrackedFrames.
+        unfinished_tracks (set[TrackId]): aggregates unfinished tracks
+            of given TrackedFrames as observed but not finished tracks in chunk.
+        last_track_frame (dict[TrackId, int]): mapping of track id
+            to frame number in which it last occurs.
+    """
+
+    is_last_chunk: bool
+    frames: Sequence[TrackedFrame[Path]] = field(init=False)
+
+    finished_tracks: set[TrackId] = field(init=False)
+    observed_tracks: set[TrackId] = field(init=False)
+    unfinished_tracks: set[TrackId] = field(init=False)
+    discarded_tracks: set[TrackId] = field(init=False)
+    last_track_frame: dict[TrackId, int] = field(init=False)
+
+    def __init__(
+        self,
+        file: Path,
+        metadata: dict,
+        is_last_chunk: bool,
+        frames: Sequence[TrackedFrame[Path]],
+        frame_group_id: int,
+    ) -> None:
+
+        object.__setattr__(self, "file", file)
+        object.__setattr__(self, "metadata", metadata)
+        object.__setattr__(self, "is_last_chunk", is_last_chunk)
+        object.__setattr__(self, "frame_group_id", frame_group_id)
+
+        observed = set().union(*(f.observed_tracks for f in frames))
+        finished = set().union(
+            *(f.finished_tracks for f in frames)
+        )  # TODO remove discarded?
+        discarded = set().union(*(f.discarded_tracks for f in frames))
+        unfinished = {o for o in observed if o not in finished and o not in discarded}
+
+        # set all unfinished tracks as finished, as this is the last track
+        if self.is_last_chunk:
+            frames_list = list(frames)
+            # assume frames sorted by occurrence
+
+            last_frame = frames_list[-1]
+            frames_list[-1] = replace(
+                last_frame,
+                finished_tracks=last_frame.finished_tracks.union(unfinished),
+            )
+
+            unfinished = set()
+            finished = set().union(*(f.finished_tracks for f in frames_list))
+        else:
+            frames_list = list(frames)
+
+        object.__setattr__(self, "frames", frames_list)
+
+        object.__setattr__(self, "finished_tracks", finished)
+        object.__setattr__(self, "observed_tracks", observed)
+        object.__setattr__(self, "unfinished_tracks", unfinished)
+        object.__setattr__(self, "discarded_tracks", discarded)
+
+        # assume frames sorted by occurrence
+        last_track_frame: dict[TrackId, FrameNo] = {
+            detection.track_id: frame.no
+            for frame in self.frames
+            for detection in frame.detections
+        }
+        object.__setattr__(self, "last_track_frame", last_track_frame)
+
+    def finish(
+        self,
+        is_last: IsLastFrame,
+        discarded_tracks: set[TrackId],
+        keep_discarded: bool = False,
+    ) -> "FinishedChunk":
+        """Turn this TrackedChunk into a FinishedChunk
+        by adding is_finished information to all its detections.
+
+        Args:
+            is_last (IsLastFrame): function to determine whether
+                a track is finished in a certain frame.
+            discarded_tracks (set[TrackId]): list of tracks considered discarded.
+                Used to mark corresponding tracks.
+            keep_discarded (bool): whether FinishedDetections marked as discarded
+                should be kept in detections list. Defaults to False.
+
+        Returns:
+            FinishedChunk: chunk of FinishedFrames
+        """
+        return FinishedChunk(
+            file=self.file,
+            metadata=self.metadata,
+            is_last_chunk=self.is_last_chunk,
+            frames=[
+                frame.finish(is_last, discarded_tracks, keep_discarded)
+                for frame in self.frames
+            ],
+            frame_group_id=self.frame_group_id,
+        )
+
+    def __repr__(self) -> str:
+        return self.__str__()
+
+    def __str__(self) -> str:
+        return f"FG [{self.frame_group_id}] - {self.file}"
+
+
+@dataclass(frozen=True)
+class FinishedChunk(TrackedChunk):
+    """A chunk of FinishedFrames.
+
+    Attributes:
+        frames (Sequence[FinishedFrame[Path]]): overrides frames
+            with more specific frame type.
+    """
+
+    frames: Sequence[FinishedFrame[Path]]
+
+    def to_detection_dicts(self) -> list[dict]:
+        chunk_metadata = {INPUT_FILE_PATH: self.file.as_posix()}
+
+        frames_progress = tqdm(
+            self.frames, desc="Frames to_dict", total=len(self.frames), leave=False
+        )
+
+        detection_dict_list = [
+            {**det_dict, **chunk_metadata}
+            for frame in frames_progress
+            for det_dict in frame.to_detection_dicts()
+        ]
+
+        detection_dict_list.sort(
+            key=lambda detection: (
+                detection[FRAME],
+                detection[TRACK_ID],
+            )
+        )
+        return detection_dict_list
+
+
+class ChunkParser(ABC):
+    """A parser for file path to FrameChunk."""
+
+    @abstractmethod
+    def parse(
+        self, file: Path, frame_group: FrameGroup, frame_offset: int
+    ) -> FrameChunk:
+        pass

OTVision/track/model/filebased/frame_group.py

@@ -0,0 +1,95 @@
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, replace
+from datetime import datetime
+from pathlib import Path
+
+from tqdm import tqdm
+
+
+def get_output_file(file: Path, with_suffix: str) -> Path:
+    return file.with_suffix(with_suffix)
+
+
+@dataclass(frozen=True)
+class FrameGroup:
+    id: int
+    start_date: datetime
+    end_date: datetime
+    hostname: str
+    files: list[Path]
+    metadata_by_file: dict[Path, dict]
+
+    def merge(self, other: "FrameGroup") -> "FrameGroup":
+        if self.start_date < other.start_date:
+            return FrameGroup._merge(self, other)
+        else:
+            return FrameGroup._merge(other, self)
+
+    @staticmethod
+    def _merge(first: "FrameGroup", second: "FrameGroup") -> "FrameGroup":
+        if first.hostname != second.hostname:
+            raise ValueError("Hostname of FrameGroups does not match")
+
+        files = first.files + second.files
+        metadata = dict(first.metadata_by_file)
+        metadata.update(second.metadata_by_file)
+
+        merged = FrameGroup(
+            id=first.id,
+            start_date=first.start_date,
+            end_date=second.end_date,
+            hostname=first.hostname,
+            files=files,
+            metadata_by_file=metadata,
+        )
+
+        return merged
+
+    def check_any_output_file_exists(self, with_suffix: str) -> bool:
+        return len(self.get_existing_output_files(with_suffix)) > 0
+
+    def get_existing_output_files(self, with_suffix: str) -> list[Path]:
+        return [file for file in self.get_output_files(with_suffix) if file.is_file()]
+
+    def get_output_files(self, with_suffix: str) -> list[Path]:
+        return [get_output_file(file, with_suffix) for file in self.files]
+
+    def with_id(self, new_id: int) -> "FrameGroup":
+        return replace(self, id=new_id)
+
+    def __repr__(self) -> str:
+        return self.__str__()
+
+    def __str__(self) -> str:
+        return f"FrameGroup[{self.id}] = [{self.start_date} - {self.end_date}]"
+
+
+class FrameGroupParser(ABC):
+
+    def process_all(self, files: list[Path]) -> list[FrameGroup]:
+        files_progress = tqdm(files, desc="parse FrameGroups", total=len(files))
+
+        parsed: list[FrameGroup] = [self.parse(file) for file in files_progress]
+        merged: list[FrameGroup] = self.merge(parsed)
+        updated: list[FrameGroup] = [
+            self.updated_metadata_copy(group).with_id(i)
+            for i, group in enumerate(merged)
+        ]
+
+        return updated
+
+    @abstractmethod
+    def parse(self, file: Path) -> FrameGroup:
+        pass
+
+    @abstractmethod
+    def merge(self, frame_groups: list[FrameGroup]) -> list[FrameGroup]:
+        pass
+
+    def updated_metadata_copy(self, frame_group: FrameGroup) -> FrameGroup:
+        new_metadata = self.update_metadata(frame_group)
+        return replace(frame_group, metadata_by_file=new_metadata)
+
+    @abstractmethod
+    def update_metadata(self, frame_group: FrameGroup) -> dict[Path, dict]:
+        pass

OTVision/track/model/frame.py

@@ -0,0 +1,149 @@
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Callable, Generic, Optional, Sequence, TypeVar
+
+from PIL.Image import Image
+
+from OTVision.dataformat import FRAME, OCCURRENCE, TRACK_ID
+from OTVision.track.model.detection import (
+    Detection,
+    FinishedDetection,
+    TrackedDetection,
+    TrackId,
+)
+
+FrameNo = int
+S = TypeVar("S")
+
+
+@dataclass(frozen=True)
+class Frame(Generic[S]):
+    """Frame metadata, optional image and respective detections.
+
+    Attributes:
+        no (FrameNo): Frame number.
+        occurrence (datetime): Time stamp, at which frame was recorded.
+        source (S): Generic source from where frame was obtained, e.g. video file path.
+        detections (Sequence[Detection]): A sequence of Detections occurring in frame.
+        image (Optional[Image]): Optional image data of frame.
+    """
+
+    no: FrameNo
+    occurrence: datetime
+    source: S
+    detections: Sequence[Detection]
+    image: Optional[Image]
+
+
+IsLastFrame = Callable[[FrameNo, TrackId], bool]
+
+
+@dataclass(frozen=True)
+class TrackedFrame(Frame[S]):
+    """Frame metadata with tracked detections.
+    Also provides additional aggregated information about:
+    observed, finished and unfinished tracks.
+
+    Attributes:
+        detections (Sequence[TrackedDetection]): overrides Frame.detections with more
+            specific type of detection.
+        observed_tracks (set[TrackId]): set of tracks of which detection occur in this
+            frame.
+        finished_tracks (set[TrackId]): track ids of tracks observed in this or prior
+            to this frame that can now be considered finished. These track ids should
+            no longer be observed/assigned in future frames. (successfully completed)
+        discarded_tracks (set[TrackId]): track ids, that are now considered discarded.
+            The corresponding tracks are no longer pursued, previous TrackedDetections
+            of these tracks are also considered discarded. Discarded tracks may be
+            observed but not finished.(unsuccessful, incomplete)
+        unfinished_tracks (set[TrackId]): observed tracks that are not yet finished
+            and were not discarded.
+    """
+
+    detections: Sequence[TrackedDetection]
+    finished_tracks: set[TrackId]
+    discarded_tracks: set[TrackId]
+    observed_tracks: set[TrackId] = field(init=False)
+    unfinished_tracks: set[TrackId] = field(init=False)
+
+    def __post_init__(self) -> None:
+        """
+        Derive observed and unfinished tracks from tracked detections and finished
+        track information.
+        """
+        observed = {d.track_id for d in self.detections}
+        object.__setattr__(self, "observed_tracks", observed)
+
+        unfinished = {
+            o
+            for o in self.observed_tracks
+            if o not in self.finished_tracks and o not in self.discarded_tracks
+        }
+        object.__setattr__(self, "unfinished_tracks", unfinished)
+
+    def finish(
+        self,
+        is_last: IsLastFrame,
+        discarded_tracks: set[TrackId],
+        keep_discarded: bool = False,
+    ) -> "FinishedFrame":
+        """Turn this TrackedFrame into a finished frame
+        by adding is_finished information to all its detections.
+
+        Args:
+            is_last (IsLastFrame): function to determine whether
+                a track is finished in a certain frame.
+            discarded_tracks (set[TrackId]): list of tracks considered discarded.
+                Used to mark corresponding tracks.
+            keep_discarded (bool): whether FinishedDetections marked as discarded
+                should be kept in detections list. Defaults to False.
+        Returns:
+            FinishedFrame: frame with FinishedDetections
+        """
+        if keep_discarded:
+            detections = [
+                det.finish(
+                    is_last=is_last(self.no, det.track_id),
+                    is_discarded=(det.track_id in discarded_tracks),
+                )
+                for det in self.detections
+            ]
+        else:
+            detections = [
+                det.finish(is_last=is_last(self.no, det.track_id), is_discarded=False)
+                for det in self.detections
+                if (det.track_id not in discarded_tracks)
+            ]
+
+        return FinishedFrame(
+            no=self.no,
+            occurrence=self.occurrence,
+            source=self.source,
+            finished_tracks=self.finished_tracks,
+            detections=detections,
+            image=self.image,
+            discarded_tracks=discarded_tracks,
+        )
+
+
+@dataclass(frozen=True)
+class FinishedFrame(TrackedFrame[S]):
+    """TrackedFrame with FinishedDetections.
+
+    Args:
+        detections (Sequence[FinishedDetection]): overrides TrackedFrame.detections
+            with more specific detection type.
+    """
+
+    detections: Sequence[FinishedDetection]
+
+    def to_detection_dicts(self) -> list[dict]:
+        frame_metadata = {FRAME: self.no, OCCURRENCE: self.occurrence.timestamp()}
+
+        # add frame metadata to each detection dict
+        detection_dict_list = [
+            {**detection.to_dict(), **frame_metadata} for detection in self.detections
+        ]
+
+        detection_dict_list.sort(key=lambda det: det[TRACK_ID])
+        return detection_dict_list