Add timerange support

[WheheoHu]

Note

• Timerange 主要表示时长概念, 固有一个基础 duration 属性 (是否可为 0 需要讨论)
• Timecode 主要表示时间点/指针概念, 没有长度概念

定义

Timerange 是一个具有方向性的 Interval
Timerange 为了控制后续计算误差, 将引入 precise_duration 属性
一个 Timerange 对象在原理上由 start_precise_time + precise_duration + direction 定义, 但是实际初始化构造的接口可以通过 start_tc + end_tc + direction 的组合构造

Note

不使用 start_tc + end_tc + direction 定义 Timerange主要考量为在计算相关操作中会大量使用到 precise_duration, 对于 offset 这类操作, 实现起来也更简单不用同时维护两个 tc 的状态

核心参数

• fps: 一个 timerange 内的 fps 是恒定不可变化的
• forword: 决定 Timerange 的方向
• strict_24h: 将 timerange 限制在 24h 内

功能

自身操作

Timerange 的自身操作比较类似各种 Interval 类

• offset: 保持 duration 在时间上的移动
• extend / shorten: 直接操作 duration 变化
• reverse: 反向
• retime: 通过 factor 操作 duration 变化
• seperate: 将一个 Timerange 分离成多个 (>=2) sub-timerange

与其他 Timerange 相关的操作

!不同方向的 Timerange 之间进行操作需要明确定义!

• contains: Timerange 的包含判定, 可加入 strict_forward 参数判定限制方向性

• and: 交操作, 需要同方向的 Timerange

• or: 并操作, 需要同方向的 Timerange 并且两个 Timerange 中不存在间隔, 可重叠

• xor: 异或操作, 需要同方向的 Timerange, 如果成功将生成两个 sub-timerange

• add: 对两个 Timerange 的 duration 进行相加操作, 方向敏感

• sub:对两个 Timerange 的 duration 进行相减操作, 方向敏感

• align_to: 将两个 Timerange 对齐 (对齐参照可以是头/尾甚至百分比, 具体实现需要讨论)

与 Timecode 相关的操作

• seperate: 将一个 Timerange 分离成多个 sub-timerange
• contains: Timecode 是否包含在 Timerange 中
• iter: 迭代器相关操作, 输出的精度与 type 相关

---

English Version ⬇️

Note

• Timerange primarily represents the concept of duration, inherently having a basic duration attribute (whether it can be 0 needs discussion).
• Timecode primarily represents the concept of a point in time/pointer, with no concept of length.

Definition

A Timerange is an Interval with directionality.
To control subsequent calculation errors, Timerange will introduce a precise_duration attribute.
A Timerange object is conceptually defined by start_precise_time + precise_duration + direction, but the actual initialization interface can be constructed through a combination of start_tc + end_tc + direction.

Note

The primary consideration for not using start_tc + end_tc + direction to define Timerange is that precise_duration will be heavily used in related calculations. For operations like offset, it is also simpler to implement without simultaneously maintaining the state of two TCs.

Core Parameters

• fps: The fps within a timerange is constant and unchangeable.
• forward: Determines the direction of the Timerange.
• strict_24h: Limits the timerange to within 24 hours.

Features

Self-Operations

Timerange's self-operations are similar to various Interval classes.

• offset: Maintains the duration's movement in time.
• extend / shorten: Directly manipulates duration changes.
• reverse: Reverses direction.
• retime: Manipulates duration changes via a factor.
• separate: Splits a Timerange into multiple (>=2) sub-timeranges.

Operations Related to Other Timeranges

!Operations between Timeranges of different directions need to be clearly defined!

• contains: Determines if a Timerange contains another, can include a strict_forward parameter to limit directionality.

• and: Intersection operation, requires Timeranges of the same direction.

• or: Union operation, requires Timeranges of the same direction and no gaps between the two Timeranges, can overlap.

• xor: Exclusive OR operation, requires Timeranges of the same direction; if successful, will generate two sub-timeranges.

• add: Adds the durations of two Timeranges, direction-sensitive.

• sub: Subtracts the durations of two Timeranges, direction-sensitive.

• align_to: Aligns two Timeranges (alignment reference can be head/tail or even percentage, specific implementation needs discussion).

Operations Related to Timecode

• separate: Splits a Timerange into multiple sub-timeranges.
• contains: Checks if a Timecode is contained within the Timerange.
• iter: Iterator-related operations, output precision is related to type.