From f8cf931816d668e9d4a2052207ae693133616804 Mon Sep 17 00:00:00 2001
From: Philip de Nier <philipn@rd.bbc.co.uk>
Date: Tue, 2 Apr 2024 10:44:08 +0100
Subject: [PATCH] Add Grain.presentation_origin_timestamp/range

Equals the origin timestamp/range adjusted with the temporal offset if not
None.

sem-ver: feature
---
 mediagrains/grains/CodedVideoGrain.py | 32 ++++++++++++++++++++++++++-
 mediagrains/grains/Grain.py           | 20 +++++++++++++++++
 2 files changed, 51 insertions(+), 1 deletion(-)

diff --git a/mediagrains/grains/CodedVideoGrain.py b/mediagrains/grains/CodedVideoGrain.py
index 6d86ac4..b45e5a7 100644
--- a/mediagrains/grains/CodedVideoGrain.py
+++ b/mediagrains/grains/CodedVideoGrain.py
@@ -10,7 +10,7 @@
     Sized,
     Iterable)
 from uuid import UUID
-from mediatimestamp.immutable import Timestamp, SupportsMediaTimestamp, mediatimestamp
+from mediatimestamp.immutable import Timestamp, TimeRange, SupportsMediaTimestamp, mediatimestamp
 from ..typing import (
     CodedVideoGrainMetadataDict,
     FractionDict,
@@ -412,3 +412,33 @@ def media_rate(self) -> Optional[Fraction]:
             return self.rate
         else:
             return None
+
+    @property
+    def presentation_origin_timestamp(self) -> Timestamp:
+        if self.rate is not None and self.temporal_offset is not None:
+            return self.origin_timestamp + Timestamp.from_count(self.temporal_offset, self.rate)
+        else:
+            return self.origin_timestamp
+
+    def final_presentation_origin_timestamp(self) -> Timestamp:
+        if self.rate is not None and self.temporal_offset is not None:
+            return self.final_origin_timestamp() + Timestamp.from_count(self.temporal_offset, self.rate)
+        else:
+            return self.final_origin_timestamp()
+
+    def presentation_origin_timerange(self) -> TimeRange:
+        origin_tr = self.origin_timerange()
+        if self.rate is not None and self.temporal_offset is not None:
+            if origin_tr.start is not None:
+                start = origin_tr.start + Timestamp.from_count(self.temporal_offset, self.rate)
+            else:
+                start = None
+
+            if origin_tr.end is not None:
+                end = origin_tr.end + Timestamp.from_count(self.temporal_offset, self.rate)
+            else:
+                end = None
+
+            return TimeRange(start, end, origin_tr.inclusivity)
+        else:
+            return origin_tr
diff --git a/mediagrains/grains/Grain.py b/mediagrains/grains/Grain.py
index 2d6777f..b438d44 100644
--- a/mediagrains/grains/Grain.py
+++ b/mediagrains/grains/Grain.py
@@ -251,6 +251,16 @@ class Grain(Sequence):
 origin_timerange()
     The origin time range covered by the samples in the grain.
 
+presentation_origin_timestamp
+    The presentation timeline origin timestamp for the grain.
+
+final_presentation_origin_timestamp()
+    The presentation origin timestamp of the final sample in the grain. For most grain types this is the same as
+    presentation_origin_timestamp, but not for audio grains.
+
+presentation_origin_timerange()
+    The presentation timeline origin time range covered by the samples in the grain.
+
 normalise_time(value)
     Returns a normalised Timestamp, TimeOffset or TimeRange using the media rate.
 
@@ -449,6 +459,16 @@ def final_origin_timestamp(self) -> Timestamp:
     def origin_timerange(self) -> TimeRange:
         return TimeRange(self.origin_timestamp, self.final_origin_timestamp(), TimeRange.INCLUSIVE)
 
+    @property
+    def presentation_origin_timestamp(self) -> Timestamp:
+        return self.origin_timestamp
+
+    def final_presentation_origin_timestamp(self) -> Timestamp:
+        return self.final_origin_timestamp()
+
+    def presentation_origin_timerange(self) -> TimeRange:
+        return self.origin_timerange()
+
     @overload
     def normalise_time(self, value: TimeOffset) -> TimeOffset: ...