From IGSTK

Contents 1 Motivation for Introducing This class 2 Problem with Current solution 3 Proposed Solution 3.1 Time 3.1.1 Desired Features / Use Cases 3.2 TimeLapse 3.2.1 Desired Features / Use Cases 3.3 Proposed API 3.4 Algebraic Rules 3.5 tcon comments

Time Classes

Motivation for Introducing This class

Time information if fundamental for the functionality of IGSTK. It is required for synchronizing information arriving from different sources, and for ensuring that the surgeon is presented with a time-consistent scene of main elements of the surgical room.

Problem with Current solution

Currently, the time is represented in IGSTK using a "double" number. This implementation introduces a number of risks in the toolkit:

• Lack of units.
• Difficulty for ensuring consistency: e.g. a user can put a negative time.
• Difficulty for differentiating between times and time lapses.

Proposed Solution

In response to the concerns described in the previous section, the introduction of a class for representing Time and TimeLapses has been proposed. This section describes the design of the Time and TimeLapse classes.

Time

Desired Features / Use Cases

The Time class should be able to do:

• Represent Time in values such as seconds and/or milliseconds
• Make explicit the units of time used.
• Convert time between units when appropriate.
• Preclude the use of invalid time values (zero and negative)
• Preclude implicit conversion of Time values to unsafe types such as float or double.
• Hide the implementation of the RealTime clock, so developers do not have to write code with explicit manipulation of Time.
• The Time class should not expose its internal numerical representation (if any).
• Print out its value for the purpose of stamping logs.
• Serve as the representation of time inside the TimeStamp class.

TimeLapse

The TimeLapse class is intended to represent the difference between two Time values. Its relationshiop to the Time class is analog to the relationship between Vectors and Points in space geometry. In this context, TimeLapses will represent duration of events, and time of validity of classes such as Transforms.

Desired Features / Use Cases

The TimeLapse class should be able to:

• Represent the difference between two instances of Time
• Contain an internal representation of units, using an enum:
  • Milliseconds
  • Seconds
  • Minutes
  • Hours
• Provide a type-safe API on classes that expect Time versus TimeLapses.
• A TimeLapse added to a Time will produce a Time
• TimeLapses SHOULD NOT be added and subtracted, to result into another TimeLapse
• TimeLapses should manage the concept of "infinite" both positive and negative.
  • Addition and Subtraction of infinite values should be defined explicitly in the class.
• The TimeLapse should not expose its internal numerical representation (if any).

Proposed API

• Time can only be constructed by the RealTimeClock (which will be declared as a friend).
  • This is because the RealTimeClock is the only class capable of reporting time in a reliable way.
  • Users should NOT be allowed to construct Time instances manually.
• Time will have an internal enum defining units
  • • Milliseconds
    • Seconds
    • Minutes
    • Hours
• The following operations MUST NOT exist, because the do not make sense on "Time":
  • Time = Time + Time
  • Time = Time - Time
  • Time = Time * Scalar
  • Time = Time / Scalar
  • TimeLapse = TimeLapse + TimeLapse (because it compromises the infinity rules)
  • TimeLapse = TimeLapse - TimeLapse (because it compromises the infinity rules)
  • TimeLapse = TimeLapse * Scalar
  • TimeLapse = TimeLapse / Scalar
• The following operations MUST exist:
  • bool = Time == Time
  • bool = Time > Time
  • bool = Time < Time
  • bool = TimeLapse == TimeLapse
  • bool = TimeLapse > TimeLapse
  • bool = TimeLapse < TimeLapse
  • TimeLapse = Time - Time
  • Time = Time - TimeLapse
  • Time = Time + TimeLapse
• These Arithmetic operations must take the Units into account, and always produce results in the Units of Higher Resolution.
• with an internal representation that is DIFFERENT from any numerical value. In other words, infinity will be represented explicity via an enum:
  • InfinityPositive
  • InfinityNegative
  • Finite
• Arithmetic operations must manage the concept of infinity correctly
  • Time(finite) + TimeLapse(finite) = Time(finite) [the easy case]
  • Time(finite) + TimeLapse(InfinityPositive) = Time(InfinityPositive)
  • Time(finite) - TimeLapse(InfinityPositive) = Time(InfinityNegative)
  • Time(finite) + TimeLapse(InfinityNegative) = Time(InfinityNegative)
  • Time(finite) - TimeLapse(InfinityNegative) = Time(InfinityPositive)
  • Time(InfinityPositive) + TimeLapse(InfinityPositive) = Time(InfinityPositive)
  • Time(InfinityPositive) - TimeLapse(InfinityPositive) = Time(InfinityPositive)

Algebraic Rules

tcon comments

• Have a separate class for positive TimeLapse, and negative TimeLapse.
• Units may not be necessary, and may introduce risks.