Merge pull request #1644 from NASA-AMMOS/feat/windows-qol-updates

Implement more convenient delegate methods for Windows and Interval

Author: JoelCourtney

procedural/timeline/src/main/kotlin/gov/nasa/ammos/aerie/procedural/timeline/Interval.kt

@@ -1,5 +1,6 @@
 package gov.nasa.ammos.aerie.procedural.timeline
 
+import gov.nasa.ammos.aerie.procedural.timeline.collections.Windows
 import gov.nasa.jpl.aerie.merlin.protocol.types.Duration
 import gov.nasa.ammos.aerie.procedural.timeline.util.duration.rangeTo
 import gov.nasa.ammos.aerie.procedural.timeline.payloads.IntervalLike
@@ -218,6 +219,8 @@ data class Interval @JvmOverloads constructor(
     return between(start, end, startInclusivity, endInclusivity)
   }
 
+  infix fun intersection(other: Windows) = other intersection this
+
   /**
    * Calculates the union between this interval and another, as a list of intervals.
    *
@@ -252,6 +255,8 @@ data class Interval @JvmOverloads constructor(
     return listOf(between(start, end, startInclusivity, endInclusivity))
   }
 
+  infix fun union(other: Windows) = other union this
+
   /** The smallest interval that contains both this and another interval. */
   infix fun hull(other: Interval): Interval {
     val union = union(other)

procedural/timeline/src/main/kotlin/gov/nasa/ammos/aerie/procedural/timeline/collections/Windows.kt

@@ -1,13 +1,15 @@
 package gov.nasa.ammos.aerie.procedural.timeline.collections
 
 import gov.nasa.ammos.aerie.procedural.timeline.BaseTimeline
+import gov.nasa.ammos.aerie.procedural.timeline.BoundsTransformer
 import gov.nasa.ammos.aerie.procedural.timeline.Interval
 import gov.nasa.ammos.aerie.procedural.timeline.Timeline
 import gov.nasa.ammos.aerie.procedural.timeline.ops.NonZeroDurationOps
 import gov.nasa.ammos.aerie.procedural.timeline.ops.SerialOps
 import gov.nasa.ammos.aerie.procedural.timeline.ops.coalesce.CoalesceIntervalsOp
 import gov.nasa.ammos.aerie.procedural.timeline.util.preprocessList
 import gov.nasa.ammos.aerie.procedural.timeline.util.sorted
+import gov.nasa.jpl.aerie.merlin.protocol.types.Duration
 
 /** A coalescing timeline of [Intervals][Interval] with no extra data. */
 data class Windows(private val timeline: Timeline<Interval, Windows>):
@@ -25,10 +27,16 @@ data class Windows(private val timeline: Timeline<Interval, Windows>):
     combined.sorted()
   }
 
+  /** Calculates the union of this and a single [Interval]. */
+  infix fun union(other: Interval) = union(Windows(other))
+
   /** Calculates the intersection of this and another [Windows]. */
   infix fun intersection(other: Windows) =
       unsafeMap2(::Windows, other) { _, _, i -> i }
 
+  /** Calculates the intersection of this and a single [Interval]. */
+  infix fun intersection(other: Interval) = select(other)
+
   /** Calculates the complement; i.e. highlights everything that is not highlighted in this timeline. */
   fun complement() = unsafeOperate { opts ->
     val result = mutableListOf(opts.bounds)
@@ -37,4 +45,69 @@ data class Windows(private val timeline: Timeline<Interval, Windows>):
     }
     result
   }
+
+  /** Subtracts the intersection with another [Windows] from this. */
+  fun minus(other: Windows) = intersection(other.complement())
+
+  /**
+   * Subtracts the intersection with a single [Interval] from this.
+   *
+   * Essentially a rename of [gov.nasa.ammos.aerie.procedural.timeline.ops.GeneralOps.unset].
+   */
+  fun minus(other: Interval) = unset(other)
+
+  /**
+   * Returns a new [Windows] where each interval is replaced by just the point at its start time.
+   *
+   * Doesn't care about inclusivity.
+   * If an input interval doesn't contain its start point, the output will still be at the same time.
+   */
+  fun starts() = unsafeMapIntervals(BoundsTransformer.IDENTITY, false) {
+    Interval.at(it.start)
+  }
+
+  /**
+   * Returns a new [Windows] where each interval is replaced by just the point at its end time.
+   *
+   * Doesn't care about inclusivity.
+   * If an input interval doesn't contain its end point, the output will still be at the same time.
+   */
+  fun ends() = unsafeMapIntervals(BoundsTransformer.IDENTITY, false) {
+    Interval.at(it.end)
+  }
+
+  /**
+   * Independently shift the start and end points of each interval.
+   *
+   * The start and end can be shifted by different amounts, stretching or squishing the interval.
+   * If the interval is empty after the shift, it is removed.
+   *
+   * Unlike [gov.nasa.ammos.aerie.procedural.timeline.ops.ParallelOps.shiftEndpoints], this function
+   * DOES coalesce the output. If you stretch the intervals such that they start to
+   * overlap, those overlapping intervals will be combined into one. This means that applying
+   * the reverse operation (i.e. `windows.shiftEndpoints(Duration.ZERO, Duration.MINUTE).shiftEndpoints(Duration.ZERO, Duration.MINUTE.negate())`
+   * does NOT necessarily result in the same timeline.
+   *
+   * To turn off coalescing behavior, convert it into a [Universal] timeline first with `.isolate($ -> true)`
+   * or `.unsafeCast(Universal::new)`. You can undo this with `.highlight($ -> true)`.
+   */
+  fun shiftEndpoints(shiftStart: Duration, shiftEnd: Duration = shiftStart) =
+    unsafeMapIntervals(
+      { i ->
+        Interval.between(
+          Duration.min(i.start.minus(shiftStart), i.start.minus(shiftEnd)),
+          Duration.max(i.end.minus(shiftStart), i.end.minus(shiftEnd)),
+          i.startInclusivity,
+          i.endInclusivity
+        )
+      },
+      true
+    ) { t -> t.interval.shiftBy(shiftStart, shiftEnd) }
+
+  /**
+   * Extends the end of each interval by a duration. The duration can be negative.
+   *
+   * See [shiftEndpoints] for a warning about coalescing behavior.
+   */
+  fun extend(shiftEnd: Duration) = shiftEndpoints(Duration.ZERO, shiftEnd)
 }

procedural/timeline/src/main/kotlin/gov/nasa/ammos/aerie/procedural/timeline/ops/ParallelOps.kt

@@ -22,6 +22,11 @@ import gov.nasa.ammos.aerie.procedural.timeline.util.duration.rangeTo
 interface ParallelOps<T: IntervalLike<T>, THIS: ParallelOps<T, THIS>>: GeneralOps<T, THIS>, CoalesceNoOp<T, THIS> {
 
   override fun isAlwaysSorted() = false
+  
+  /**
+   * Returns just the intervals from the timeline, without coalescing.
+   */
+  fun collectIntervals() = collect().map { it.interval }
 
   /** [(DOC)][highlightAll] Highlights all objects in the timeline in a new [Windows] timeline. */
   fun highlightAll() = unsafeMap(::Windows, BoundsTransformer.IDENTITY, true) { it.interval }
@@ -138,6 +143,9 @@ interface ParallelOps<T: IntervalLike<T>, THIS: ParallelOps<T, THIS>>: GeneralOp
           true
       ) { t -> t.interval.shiftBy(shiftStart, shiftEnd) }
 
+  /** [(DOC)][extend] Extends just the end of each object's interval by a duration. The duration can be negative. */
+  fun extend(shiftEnd: Duration) = shiftEndpoints(Duration.ZERO, shiftEnd)
+
   /** [(DOC)][active] Returns a [Booleans] profile that is true when this timeline has an active object. */
   fun active() = flattenIntoProfile(::Booleans) { _ -> true }.assignGaps(Booleans(false))
 

procedural/timeline/src/test/kotlin/gov/nasa/ammos/aerie/procedural/timeline/collections/WindowsTest.kt

@@ -7,8 +7,10 @@ import gov.nasa.jpl.aerie.merlin.protocol.types.Duration.seconds
 import gov.nasa.ammos.aerie.procedural.timeline.Interval.Companion.at
 import gov.nasa.ammos.aerie.procedural.timeline.Interval.Companion.between
 import gov.nasa.ammos.aerie.procedural.timeline.Interval.Inclusivity.Exclusive
+import gov.nasa.ammos.aerie.procedural.timeline.Interval.Inclusivity.Inclusive
 import gov.nasa.ammos.aerie.procedural.timeline.util.duration.rangeTo
 import gov.nasa.ammos.aerie.procedural.timeline.util.duration.rangeUntil
+import gov.nasa.ammos.aerie.procedural.timeline.util.duration.unaryMinus
 import org.junit.jupiter.api.Assertions.assertIterableEquals
 import org.junit.jupiter.api.Test
 
@@ -129,4 +131,98 @@ class WindowsTest {
     )
   }
 
+  @Test
+  fun starts() {
+    val w = Windows(
+      at(seconds(1)),
+      seconds(2)..seconds(3),
+      seconds(4)..<seconds(5),
+      between(seconds(6), seconds(7), Exclusive, Inclusive)
+    )
+
+    val result = w.starts()
+
+    assertIterableEquals(
+      listOf(
+        at(seconds(1)),
+        at(seconds(2)),
+        at(seconds(4)),
+        at(seconds(6))
+      ),
+      result
+    )
+  }
+
+  @Test
+  fun ends() {
+    val w = Windows(
+      at(seconds(1)),
+      seconds(2)..seconds(3),
+      seconds(4)..<seconds(5),
+      between(seconds(6), seconds(7), Exclusive, Inclusive)
+    )
+
+    val result = w.ends()
+
+    assertIterableEquals(
+      listOf(
+        at(seconds(1)),
+        at(seconds(3)),
+        at(seconds(5)),
+        at(seconds(7))
+      ),
+      result
+    )
+  }
+
+  @Test
+  fun shiftEndpointsShrink() {
+    val w = Windows(
+      at(seconds(1)),
+      seconds(2)..seconds(3),
+      seconds(4)..seconds(6),
+      between(seconds(7), seconds(9), Exclusive, Inclusive),
+      seconds(10)..<seconds(12),
+      seconds(13)..seconds(17)
+    )
+
+    val result1 = w.shiftEndpoints(seconds(2), Duration.ZERO)
+
+    assertIterableEquals(
+      listOf(
+        at(seconds(6)),
+        seconds(15)..seconds(17)
+      ),
+      result1
+    )
+
+    val result2 = w.shiftEndpoints(Duration.ZERO, -seconds(2))
+
+    assertIterableEquals(
+      listOf(
+        at(seconds(4)),
+        seconds(13)..seconds(15)
+      ),
+      result2
+    )
+  }
+
+  @Test
+  fun shiftEndpointsGrow() {
+    val w = Windows(
+      at(seconds(0)),
+      seconds(2)..<seconds(3),
+      seconds(4)..seconds(5),
+    )
+
+    val result = w.extend(seconds(1))
+
+    assertIterableEquals(
+      listOf(
+        seconds(0)..seconds(1),
+        seconds(2)..seconds(6),
+      ),
+      result
+    )
+  }
 }