expenvelope.envelope_segment.EnvelopeSegment¶
-
class
expenvelope.envelope_segment.
EnvelopeSegment
(start_time: float, end_time: float, start_level, end_level, curve_shape: Union[float, str])[source]¶ Bases:
object
A segment of an envelope, with the ability to perform interpolation and integration.
- Parameters
start_time – the start time of the segment (where it is in the parent
Envelope
)end_time – the end time of the segment
start_level – the level of the envelope segment at the beginning. Note that a type has not been specified; the only requirements are that the type should be consistent and respond to addition and multiplication. This means, for instance, that numpy arrays could be used.
end_level – the level of the envelope segment at the end.
curve_shape – 0 is linear, > 0 changes late, < 0 changes early. Also, string expressions involving “exp” can be given, where “exp” stands for the shape that will produce constant proportional change per unit time.
- Variables
start_time – the start time of the segment
end_time – the end time of the segment
Methods
Get the average level achieved in this segment
clone
()Make a duplicate of this segment.
from_endpoints_and_halfway_level
(start_time, …)Construct an EnvelopeSegment with the given start/end times/levels, specifying curve shape indirectly through the desired halfway level.
Returns the range of possible values for the integral of this segment available by tweaking curvature
integrate_segment
(t1, t2)Integrate part of this segment.
is_shifted_version_of
(other[, tolerance])Determines if this segment is simply a shifted version of another segment
Get the max absolute value of the slope of this segment over the interval.
Get the maximum level achieved in this segment
scale_horizontal
(amount)Scales the domain of this segment by the specified amount.
scale_vertical
(amount)Scales the output of this segment by the specified amount.
Changes the curvature of this segment so as to hit a desired target for the integral of the segment
shift_horizontal
(amount)Shifts the domain of this segment by the specified amount.
shift_vertical
(amount)Shifts the output of this segment by the specified amount.
show_plot
([title, resolution])Uses matplotlib to display a graph of this EnvelopeSegment.
split_at
(t)Split this segment into two EnvelopeSegment’s without altering the curve shape and return them.
value_at
(t[, clip_at_boundary])Get interpolated value of the curve at time t.
Attributes
The curve shape of this segment.
Duration of this segment.
The end level of this segment.
The start level of this segment.
-
classmethod
from_endpoints_and_halfway_level
(start_time: float, end_time: float, start_level, end_level, halfway_level) → T[source]¶ Construct an EnvelopeSegment with the given start/end times/levels, specifying curve shape indirectly through the desired halfway level.
- Parameters
start_time – the start time of the segment (where it is in the parent
Envelope
)end_time – the end time of the segment
start_level – the level of the envelope segment at the beginning. (See documentation for
EnvelopeSegment
)end_level – the level of the envelope segment at the end.
halfway_level – The level we want to reach halfway through the segment.
-
property
start_level
¶ The start level of this segment. (Can take a wide variety of types; see documentation for
EnvelopeSegment
)
-
property
end_level
¶ The end level of this segment. (Can take a wide variety of types; see documentation for
EnvelopeSegment
)
-
property
curve_shape
¶ The curve shape of this segment. (See documentation for
EnvelopeSegment
)
-
property
duration
¶ Duration of this segment.
-
max_absolute_slope
()[source]¶ Get the max absolute value of the slope of this segment over the interval. (Since the slope of e^x is e^x, the max slope of e^x in the interval of [0, S] is e^S. If S is negative, the curve has exactly the same slopes, but in reverse (still need to think about why), so that’s why the max slope term ends up being e^abs(S). We then have to scale that by the average slope over our interval divided by the average slope of e^x over [0, S] to get the true, scaled average slope. Hence the other scaling terms.)
-
value_at
(t: float, clip_at_boundary: bool = True)[source]¶ Get interpolated value of the curve at time t. The equation here is y(t) = y1 + (y2 - y1) / (e^S - 1) * (e^(S*t) - 1) (y1=starting rate, y2=final rate, t=progress along the curve 0 to 1, S=curve_shape) Essentially it’s an appropriately scaled and stretched segment of e^x with x in the range [0, S] as S approaches zero, we get a linear segment, and S of ln(y2/y1) represents normal exponential interpolation large values of S correspond to last-minute change, and negative values of S represent early change.
- Parameters
t – time at which to evaluate the level (relative to the time zero, not to the start time of this segment)
clip_at_boundary – if True, any t outside the boundary gets evaluated based on the start or end level (whichever is applicable.
-
integrate_segment
(t1, t2)[source]¶ Integrate part of this segment.
- Parameters
t1 – start time (relative to the time zero, not to the start time of this segment)
t2 – end time (ditto)
-
get_integral_range
()[source]¶ Returns the range of possible values for the integral of this segment available by tweaking curvature
:return a tuple of (low, high)
-
set_curvature_to_desired_integral
(desired_integral) → None[source]¶ Changes the curvature of this segment so as to hit a desired target for the integral of the segment
- Parameters
desired_integral – target value of the segment integral
-
split_at
(t: float) → Tuple[T, T][source]¶ Split this segment into two EnvelopeSegment’s without altering the curve shape and return them. This segment is altered in the process.
- Parameters
t – where to split it (t is absolute time)
- Returns
a tuple of this segment modified to be only the first part, and a new segment for the second part
-
shift_vertical
(amount) → T[source]¶ Shifts the output of this segment by the specified amount.
- Parameters
amount – the amount to shift up and down by
- Returns
self, for chaining purposes
-
scale_vertical
(amount) → T[source]¶ Scales the output of this segment by the specified amount.
- Parameters
amount – amount to scale output by
- Returns
self, for chaining purposes
-
shift_horizontal
(amount: float) → T[source]¶ Shifts the domain of this segment by the specified amount.
- Parameters
amount – the amount to shift the domain by
- Returns
self, for chaining purposes
-
scale_horizontal
(amount: float) → T[source]¶ Scales the domain of this segment by the specified amount.
- Parameters
amount – amount to scale domain by
- Returns
self, for chaining purposes