Welcome to rekall’s documentation!¶
Submodules¶
Rekall package contents¶
Rekall is a spatiotemporal query language.
It operates over sets of intervals and allows for combining and filtering on temporal and spatial predicates.
This module defines classes Interval
, IntervalSet
, and
IntervalSetMapping
.
An Interval
is a spatiotemporal volume defined by a bounds and a payload of
arbitrary type. An IntervalSet
is a set of such Intervals.
One can perform unary operations such as map
, filter
on IntervalSet
as
well as binary operations between sets such as join
, union
and minus
.
IntervalSetMapping
is a collection of IntervalSets
organized by some key.
It exposes the same interface as IntervalSet
and executes operations on the
underlying IntervalSets
. It performs binary operations between IntervalSets
of the same key.
The rekall.bounds
submodule provides the Bounds
abstraction and two default
Bounds
implementations, a one-dimensional Bounds1D
and a three-dimensional
Bounds3D
. Bounds1D
and Bounds3D
both come with some useful functions on
their co-ordinate systems.
The rekall.predicates
submodule provides a number of useful one-dimensional
and two-dimensional predicate functions. These functions are often used to
filter pairs of Intervals
when joining two IntervalSets
or
IntervalSetMappings
.
The rekall.stdlib
submodule provides a number of useful functions that are
not core to Rekall but that we have nevertheless found to be useful.
rekall.stdlib.ingest
in particular provides a number of useful functions for
reading from various data sources into an IntervalSetMapping
.
The rekall.runtime
submodule provides a library for efficiently executing
rekall queries. Given a function that operates on a batch of inputs, the
runtime divides the long list of inputs into chunks and run each chunk
potentially in parallel, and can combine the results of each chunk at the end.
-
class
rekall.
Interval
(bounds, payload=None)¶ Bases:
object
A single Interval.
An Interval is a wrapper around a Bounds and a payload. The payload can be referenced with the ‘payload’ key - i.e.
interval['payload']
, as can the fields of the Bounds. The bounds field itself can also be referenced with type ‘bounds’ key.-
bounds
¶ Bounds object.
-
payload
¶ payload object.
-
P
()¶ This wraps a predicate so it is applied to the payload of Intervals instead of the Intervals themselves.
The output function expects one or more Intervals as input (depending on how many arguments
pred
expects) and applies the predicate to the payloads of the Intervals instead of the Interavls themselves.- Arg:
- pred: The predicate to wrap.
Returns: An output function that applies pred
to payloads.
-
combine
(other, bounds_combiner, payload_combiner=<function Interval.<lambda>>)¶ Combines two Intervals into one by separately combining the bounds and the payload.
Parameters: - other – The other Interval to combine with.
- bounds_combiner – The function to combine the bounds. Takes two Bounds objects as input and returns one Bounds object.
- payload_combiner – The function to combine the two payloads. Takes two payload objects as input and returns one payload object.
Returns: A new Interval combined using
bounds_combiner
andpayload_combiner
.
-
copy
()¶ Returns a copy of the Interval.
-
size
(axis=None)¶ Get the size of the bounds along some axis.
Parameters: axis (optional) – The axis to compute size on. Represented as a pair of co-ordinates, such as ('t1', 't2')
. Defaults toNone
, which uses the primary axis ofself
’s Bounds.Returns: The size of the bounds across some axis.
-
to_json
(payload_to_json)¶ Converts the interval to a JSON object.
Parameters: payload_to_json – Function that converts the payload to a JSON object. Returns: JSON object for the interval
-
-
class
rekall.
IntervalSet
(intrvls)¶ Bases:
object
A set of Intervals.
IntervalSet provides core operations to transform and combine sets of Intervals such as map, fold, join, union, minus, coalesce, etc.
Note
This class does not obey the uniqueness semantics of a Set.
When the number of intervals is larger than NUM_INTRVLS_THRESHOLD, binary operations join, collect_by_interval and filter_against will no longer operate on the full cross product of the intervals, and instead only look at pairs that are within a certain neighborhood of each other along the primary axis (the primary axis of the first Interval passed in during construction). This neighborhood defaults to DEFAULT_FRACTION of the overall range along that axis of the IntervalSet.
Specifically, we compute
DEFAULT_FRACTION
of the overall range of that axis and setoptimization_window
to that fraction of the range. The optimized operations (join
,collect_by_interval
, andfilter_against
) only look at pairs whose distance from each other along the primary axis is less thanoptimization_window
.-
DEFAULT_FRACTION
= 0.01¶
-
NUM_INTRVLS_THRESHOLD
= 1000¶
-
coalesce
(axis, bounds_merge_op, payload_merge_op=<function IntervalSet.<lambda>>, predicate=None, epsilon=0)¶ Recursively merge all intervals that are touching or overlapping along
axis
.Merge intervals in self if they meet, overlap, or are up to
epsilon
apart alongaxis
. If a predicate is specified, intervals will be merged if they meet/overlap and satisfy the predicate. Repeat the process until all such intervals are merged.Merges the bounds with
bounds_merge_op
and merges payloads withpayload_merge_op
.Parameters: - axis – The axis to coalesce on.
- bounds_merge_op – A function that takes two bounds and returns a
merged version of both of them. Along
axis
, this function should return a bound that spans the two bounds. - payload_merge_op (optional) – A function that takes in two payloads and merges them. Defaults to a function that returns the first of the two payloads.
- predicate (optional) – A function that takes an interval that is currently being coalesced and a new interval and returns whether or not the two intervals should be merged.
- epsilon (optional) – The slack for judging if Intervals meet or overlap. Must be nonnegative. Defaults to 0 (no slack).
Returns: A new IntervalSet of intervals that are disjoint along
axis
and are at leastepsilon
apart.
-
collect_by_interval
(other, predicate, filter_empty=True, window=None)¶ Collect intervals in other and nest them under intervals in self.
For each interval in self, its payload in the output IntervalSet will be all the intervals in other that satisfy the predicate. The payload of each resulting interval will become a pair
(P, IS)
whereP
is the original payload in self, andIS
is anIntervalSet
containing the nested intervals.Note
We do not check the full cross-product of self and other and instead only check pairs that are within
window
of each other along the primary axis. See class documentation for more details.Parameters: - other (IntervalSet) – Set of intervals to collect.
- predicate – A function that takes one interval in self and one in other and returns a bool.
- filter_empty (optional) – Whether to remove intervals in self if no
intervals in other satisfies the predicate with it.
If
False
, such intervals will have payload(P, IntervalSet([]))
whereP
is the original payload. Defaults toTrue
. - window (optional) – Restrict interval pairs to those within window of each other along the primary axis. Defaults to None which means using the default optimization window associated with self. See class Documentation for more detail.
Returns: A new IntervalSet of intervals in self but with nested interval set from other in the payload.
-
dilate
(window, axis=None)¶ Expand the range of every interval in the set along some axis.
Parameters: - window (Number) – The amount to extend at each end-point of the range. The actual interval will grow by 2*window. Use negative number to shrink intervals.
- axis (optional) – The axis to dilate on. Represented as a pair of
co-ordinates, such as
('t1', 't2')
. Defaults toNone
, which uses theprimary_axis
ofself
.
Returns: A new IntervalSet with the dilated intervals.
-
duration
(axis=None)¶ Returns the sum of length of intervals along some axis in the set.
Parameters: axis – The axis to sum the length over. Returns: The sum of the size of the intervals along axis.
-
empty
()¶ Returns whether the set is empty.
-
filter
(predicate)¶ Filter the set and keep intervals that pass the predicate.
Parameters: predicate – A function that takes an Interval and returns a bool. Returns: A new IntervalSet which is the filtered set.
-
filter_against
(other, predicate, window=None)¶ Filter intervals in self against intervals in other.
Keep only intervals in self that satisfy the predicate with at least one interval in other.
Note
We do not check the full cross-product of self and other and instead only check pairs that are within window of each other. See class documentation for more details.
Parameters: - other (IntervalSet) – The other interval set to filter against.
- predicate – A function that takes one interval in self and an interval in other and returns a bool.
- window (optional) – Restrict interval pairs to those within window of each other along the primary axis. Defaults to None which means using the default optimization window associated with self. See class Documentation for more detail.
Returns: A new IntervalSet with intervals in self that satisify predicate with at least one interval in other.
-
filter_size
(min_size=0, max_size='infty', axis=None)¶ Filter the intervals by length of the bounds along some axis.
Parameters: - min_size (Number, optional) – minimum size to pass the filter. Defaults to 0.
- max_size (Number, optional) – maximum size to pass the filter. Defaults to rekall.common.INFTY.
- axis (optional) – The axis to filter on. Represented as a pair of
co-ordinates, such as
('t1', 't2')
. Defaults toNone
, which uses theprimary_axis
ofself
.
Returns: A new IntervalSet of intervals with bound length within [min_size, max_size] along the given axis.
-
fold
(reducer, init=None, sort_key=None)¶ Folds a reducer over an ordered list of intervals in the set.
Parameters: - reducer – A function that takes a previous state and an interval and returns an updated state.
- init (optional) – The initial state to use in fold. Defaults to None, which means using the first interval as the initial state and run reduction from the second interval.
- sort_key (optional) – A function that takes an Interval and
returns a value as the sort key that defines the order of the
list to fold over. If None, uses the
primary_axis
of the Bound of an Interval in the IntervalSet.
Returns: The final value of the state after folding all intervals in set.
-
fold_to_set
(reducer, init=None, sort_key=None, acc_to_set=<function IntervalSet.<lambda>>)¶ Fold over intervals in the set to produce a new IntervalSet.
The same as fold method except it returns a IntervalSet by running
acc_to_set
on the final state of the fold, making it an in-system operation.Parameters: - reducer – A function that takes a previous state and an interval and returns an updated state.
- init (optional) – The initial state to use in fold. Defaults to None, which means using the first interval as the initial state and run reduction from the second interval.
- sort_key (optional) – A function that takes an Interval and
returns a value as the sort key that defines the order of the
list to fold over. If None, uses the
primary_axis
of the Bound of an Interval in the IntervalSet. - acc_to_set (optional) – A function that takes the final state of the fold and returns an IntervalSet. Defaults to a function that takes in a list of Intervals and constructs an IntervalSet with that.
Returns: A new IntervalSet that is the result of acc_to_set on the output of fold.
-
get_intervals
()¶ Returns a list of Intervals, ordered by their Bounds (which are sortable).
-
group_by
(key, merge)¶ Group intervals by key and produces a new interval for each group.
Parameters: - key – A function that takes an Interval and returns a value as the key to group by.
- merge – A function that takes a group key and an IntervalSet of the group, and returns one Interval.
Returns: A new IntervalSet with the results of merge on each group.
-
group_by_axis
(axis, output_bounds)¶ Group intervals by a particular axis.
For each group, create an Interval with bounds equal to
output_bounds
, except for the co-ordinates in axis. These are set to the co-ordinate values for the group. The payload is an IntervalSet containing all the intervals in the group.Example:
iset = IntervalSet([ Interval(Bounds3D(0, 1, 0.5, 0.75, 0.5, 0.75)), Interval(Bounds3D(0, 1, 0.3, 0.75, 0.1, 0.3)), Interval(Bounds3D(0, 2, 0.1, 0.7, 0.1, 0.2)), Interval(Bounds3D(0, 2, 0.05, 0.25, 0.1, 0.12)), Interval(Bounds3D(1, 2, 0.6, 0.75, 0.1, 0.2)) ]) is_grouped = iset.group_by_axis(('t1', 't2'), Bounds3D(0, 1, 0, 1, 0, 1)) # This is what is_grouped looks like is_grouped == IntervalSet([ Interval(Bounds3D(0, 1, 0, 1, 0, 1), [ Interval(Bounds3D(0, 1, 0.5, 0.75, 0.5, 0.75)), Interval(Bounds3D(0, 1, 0.3, 0.75, 0.1, 0.3)), ]), Interval(Bounds3D(0, 2, 0, 1, 0, 1), [ Interval(Bounds3D(0, 2, 0.1, 0.7, 0.1, 0.2)), Interval(Bounds3D(0, 2, 0.05, 0.25, 0.1, 0.12)) ]), Interval(Bounds3D(1, 2, 0, 1, 0, 1), [ Interval(Bounds3D(1, 2, 0.6, 0.75, 0.1, 0.2)) ]) ])
Parameters: - axis – The axis to group by. Represented as a pair of co-ordinates,
such as
('t1', 't2')
. - output_bounds – Default output bounds for the Intervals in the
output. The fields in
axis
are overwritten by the grouped values.
Returns: A new IntervalSet of Intervals grouped by
axis
, with the full IntervalSet of Intervals in the group in the payload.- axis – The axis to group by. Represented as a pair of co-ordinates,
such as
-
join
(other, predicate, merge_op, window=None)¶ Cross-products two sets and combines pairs that pass the predicate.
Named after the database JOIN operation, this method takes the cross- product of two IntervalSets, filters the resulting set of pairs and forms a new IntervalSet by combining each pair into a new Interval.
Note
join
does not take the full cross-product but instead only consider pairs within window of each other. See notes in class documentation for more details.Parameters: - other (IntervalSet) – The interval set to join with.
- predicate – A function that takes two Intervals and returns a bool.
- merge_op – A function that takes two Intervals and returns a single new Interval.
- window (optional) – Restrict interval pairs to those within window of each other along the primary axis. Defaults to None which means using the default optimization window associated with self. See class Documentation for more detail.
Returns: A new IntervalSet from the intervals produced by merge_op on pairs that pass the predicate.
-
map
(map_fn)¶ Maps a function over all intervals in the set.
Parameters: map_fn – A function that takes an Interval and returns an Interval. Returns: A new IntervalSet with the mapped intervals.
-
map_payload
(fn)¶ Maps a function over payloads of all intervals in the set.
Parameters: fn – A function that takes the payload of an interval and returns the new payload. Returns: A new IntervalSet of intervals with the same bounds but with transformed payloads.
-
match
(pattern, exact=False)¶ Pattern matching among the intervals in the set.
A pattern is a list of constraints, where each constraint is a pair of
(names, predicates)
. A name is a string that names the variable in the constraint. A predicate is a function that takeslen(names)
Intervals as arguments and returnsTrue
orFalse
.A solution is a directionary of assignments, where the key is the name of the variable defined in the pattern and the key is the interval in the set that gets assigned to that variable. The assignments in a solution will satisfy all constraints in the pattern.
Example
Here’s a simple example of matching a spatial pattern:
pattern = [ (["harry"], [XY(height_at_least(0.5)), name_is("harry")]), (["ron"], [XY(height_at_least(0.5)), name_is("ron")]), (["harry","ron"], [XY(same_height()), XY(left_of())]) ] # solutions are cases in intervalset where harry and ron are at # least half the screen height and have the same height and # harry is on the left of ron. solutions = intervalset.match(pattern) # solutions == [ # {"harry": Interval(...), "ron": Interval(...)}, # {"harry": Interval(...), "ron": Interval(...)}, # ]
Parameters: - pattern – A pattern specified by a list of constraints. See above for more details.
- exact (optional) – Whether all intervals in the set need to have an assignment for it to be considered a solution. Defaults to False.
Returns: A list of solutions as described above.
-
minus
(other, axis=None, window=None, predicate=None)¶ Subtract one IntervalSet from the other across some axis.
Calculates the interval difference between intervals in self and intervals in other on some axis. The other dimensions are not changed.
In particular,
a.minus(b)
will produce a new set of Intervals that maximally covers the Intervals ina
without intersecting any of the intervals inb
onaxis
, but only if they pass thepredicate
.The difference between two intervals can produce up to two new intervals.
Suppose we try to subtract two sets of intervals from each other:
# Suppose the following interval is in self |--------------------------------------------------------| # and that the following two intervals are in other |--------------| |----------------| # this function will produce three intervals |---------| |-----| |--------|
If an interval in self overlaps no pairs in other along the temporal dimension, then the interval is reproduced in the output.
Note
Although it is possible to compute difference on arbitrary volumes, it is unclear how to break the resulting set into bounding volumes. Therefore we currently only allow difference to be computed along a single axis.
Parameters: - other – The IntervalSet to subtract from
self
. - axis (optional) – The axis to subtract on. Represented as a pair of
co-ordinates, such as
('t1', 't2')
. Defaults toNone
, which uses theprimary_axis
ofself
. - window (optional) – Restrict interval pairs to those within window of each other along the primary axis. Defaults to None which means using the default optimization window associated with self. See class Documentation for more detail.
- predicate (optional) – A function that takes one interval in self and an interval in other and returns a bool. Only counts intervals in other that pass the predicate for the minus operation.
Returns: A new IntervalSet with the results from the subtraction. It may contain more intervals than before the subtraction, but none of the intervals will overlap with the intervals in
other
alongaxis
.- other – The IntervalSet to subtract from
-
size
()¶ Returns the number of intervals in the set.
-
split
(split_fn)¶ Splits each Interval into an IntervalSet, and returns the union of all the IntervalSets.
Parameters: - split_fn – A function that takes an Interval and returns an
- IntervalSet. –
Returns: A new IntervalSet with the union of all the IntervalSets generated by split_fn applied to each Interval.
-
to_json
(payload_to_json)¶ Converts the interval set to a JSON object.
Parameters: payload_to_json – Function that converts each payload to a JSON object. Returns: JSON object for the interval set
-
union
(other)¶ Set union of two IntervalSets.
Parameters: other – The other IntervalSet to union with. Returns: A new IntervalSet with all intervals in self and other.
-
-
class
rekall.
IntervalSetMapping
(grouped_intervals)¶ Bases:
collections.abc.MutableMapping
A wrapper around a dictionary from key to IntervalSet.
It uses method reflection to expose all the same methods as IntervalSet, and delegates the method to the underlying IntervalSet of each domain in the collection. When calling binary methods such as
join
orminus
on two IntervalSetMapping’s, it will match up IntervalSet’s by key and perform the method on the underlying IntervalSet’s for each domain.For each in-system method of IntervalSet (i.e. the return value is an IntervalSet), the corresponding method on IntervalSetMapping returns an IntervalSetMapping as well.
For each out-of-system method on IntervalSet, namely
size
,empty
,fold
, andmatch
, the corresponding method on IntervalSetMapping returns a dictionary from the key to the result of the method call on the underlying IntervalSet.IntervalSetMapping exposes Python’s getter/setter paradigm as well, so individual IntervalSet’s can be referenced using bracket notation and their key.
The methods to wrap from IntervalSet are defined by the class constants: UNARY_METHODS, BINARY_METHODS and OUT_OF_SYSTEM_UNARY_METHODS.
Example
Here are some examples of how IntervalSetMapping reflects IntervalSet’s methods:
ism1 = IntervalSetMapping({ 1: IntervalSet(...), 2: IntervalSet(...), 10: IntervalSet(...) }) ism2 = IntervalSetMapping({ 1: IntervalSet(...), 3: IntervalSet(...), 10: IntervalSet(...) }) # Unary methods ism1.map(mapper) == IntervalSetMapping({ 1: ism1[1].map(mapper), # IntervalSet 2: ism1[2].map(mapper), # IntervalSet 10: ism1[10].map(mapper) # IntervalSet }) # Binary methods ism1.join(ism2, ...) == IntervalSetMapping({ 1: ism1[1].join(ism2[1], ...), # IntervalSet 10: ism1[10].join(ism2[10], ...) # IntervalSet }) # Out of system unary methods: ism1.size() == { 1: ism1[1].size(), # Number 2: ism1[2].size(), # Number 10: ism1[10].size() # Number }
- Atrributes:
- UNARY_METHODS: List of methods that IntervalSetMapping reflects from
- IntervalSet and that will return a IntervalSetMapping where the IntervalSet under each group is transformed under the unary operation. See IntervalSet documentation for arguments and behavior for each method.
- BINARY_METHODS: List of methods that IntervalSetMapping reflects from
- IntervalSet and that will take a second IntervalSetMapping and will return an IntervalSetMapping where the binary operation is performed on the two IntervalSets with the same key. See IntervalSet documentation for arguments and behavior for each method.
- OUT_OF_SYSTEM_UNARY_METHODS: List of methods that IntervalSetMapping
- reflects from IntervalSet and that will return a dictionary mapping from IntervalSet keys to return values of the methods.
-
BINARY_METHODS
= ['merge', 'union', 'join', 'minus', 'filter_against', 'collect_by_interval']¶
-
OUT_OF_SYSTEM_UNARY_METHODS
= ['size', 'duration', 'empty', 'fold', 'match']¶
-
UNARY_METHODS
= ['filter_size', 'map', 'filter', 'group_by', 'fold_to_set', 'map_payload', 'dilate', 'group_by_axis', 'coalesce', 'split']¶
-
add_key_to_payload
()¶ Adds key to payload of each interval in each IntervalSet.
If each interval in an IntervalSet with key K had payload P before, it now has the tuple
(P, K)
as payload.Returns: A new IntervalSetMapping with the transformed intervals. Note
The original IntervalSetMapping is unchanged. This is the same behavior as all unary methods of IntervalSet.
-
classmethod
from_intervalset
(intervalset, key_fn)¶ Constructs an IntervalSetMapping from an IntervalSet by grouping by
key_fn
.Parameters: - intervalset (IntervalSet) – An interval set containing all intervals to put in the mapping.
- key_fn – A function that takes an interval and returns the domain key.
Returns: An IntervalSetMapping with the same intervals organized into domains by their key accroding to
key_fn
.
-
classmethod
from_iterable
(iterable, key_parser, bounds_parser, payload_parser=<function IntervalSetMapping.<lambda>>, progress=False, total=None)¶ Constructs an IntervalSetMapping from an iterable.
Parameters: - iterable – An iterable of arbitrary elements. Each element will become an interval in the collection.
- key_parser – A function that takes an element in iterable and returns the key for the interval.
- bounds_parser – A function that takes an element in iterable and returns the bounds for the interval.
- payload_parser (optional) – A function that takes an element in iterable and returns the payload for the interval. Defaults to producing None for all elements.
- progress (Bool, optional) – Whether to display a progress bar using tqdm. Defaults to False.
- total (int, optional) – Total number of elements in iterable. Only used to estimate ETA for the progress bar, and only takes effect if progress is True.
Returns: A IntervalSetMapping constructed from iterable and the parsers provided.
Note
Everything in iterable will be materialized in RAM.
-
get_flattened_intervalset
()¶ Get an IntervalSet containing all intervals in all the IntervalSets.
-
get_grouped_intervals
()¶ Get dictionary from key to IntervalSet.
-
items
() → a set-like object providing a view on D's items¶
-
keys
() → a set-like object providing a view on D's keys¶
-
values
() → an object providing a view on D's values¶
-
class
rekall.
Bounds3D
(t1, t2, x1=0.0, x2=1.0, y1=0.0, y2=1.0)¶ Bases:
rekall.bounds.abstract_bounds.Bounds
Object representing a three-dimensional (time, x, y) bound.
The class has co-ordinates ‘t1’, ‘t2’, ‘x1’, ‘x2’, ‘y1’, ‘y2’, representing start and end co-ordinates in the time, x, and y dimensions respectively.
This class has two built-in one-dimensional casts -
X()
andY()
cast the time dimensions to the x and y dimensions so that temporal predicates can be used on one-dimensional spatial dimensions.-
T
()¶ Returns a function that transforms predicates by casting accesses to ‘t1’ to ‘t1’ and accesses to ‘t2’ to ‘t2’. This doesn’t actually transform anything, but it’s a nice helper function for readability.
- Arg:
- pred: The predicate to cast.
Returns: The same predicate as pred
.
-
T_axis
()¶ Returns a tuple representing the time axis.
-
X
()¶ Returns a function that transforms predicates by casting accesses to ‘t1’ to ‘x1’ and accesses to ‘t2’ to ‘x2’.
Example
Here is an example of casting an example predicate:
# This predicate tests whether a bound's 't2' value is greater # than its 't1' value def example_pred(bounds): return bounds['t2'] > bounds['t1'] # t1 = 0, t2 = 1, x1 = 1, x2 = 0, y1 = 1, y2 = 0 higher_t2_lower_x2 = Bounds3D(0, 1, 1, 0, 1, 0) example_pred(higher_t2_lower_x2) # this is True, since t2 > t1 Bounds3D.X(example_pred)(higher_t2_lower_x2) # this is False, since x2 < x1
- Arg:
- pred: The predicate to cast.
Returns: The same predicate as pred
, except accesses to ‘t1’ are cast to ‘x1’, and accesses to ‘t2’ are cast to ‘x2’.
-
XY
()¶ Returns a function that transforms predicates by casting accesses to ‘x1’ to ‘x1’, ‘x2’ to ‘x2’, ‘y1’ to ‘y1’, and ‘y2’ to ‘y2’. This doesn’t actually transform anything, but it’s a nice helper function for readability.
- Arg:
- pred: The predicate to cast.
Returns: The same predicate as pred
.
-
X_axis
()¶ Returns a tuple representing the X axis.
-
Y
()¶ Returns a function that transforms predicates by casting accesses to ‘t1’ to ‘y1’ and accesses to ‘t2’ to ‘y2’.
Example
Here is an example of casting an example predicate:
# This predicate tests whether a bound's 't2' value is greater # than its 't1' value def example_pred(bounds): return bounds['t2'] > bounds['t1'] # t1 = 0, t2 = 1, x1 = 1, x2 = 0, y1 = 1, y2 = 0 higher_t2_lower_x2 = Bounds3D(0, 1, 1, 0, 1, 0) example_pred(higher_t2_lower_y2) # this is True, since t2 > t1 Bounds3D.Y(example_pred)(higher_t2_lower_y2) # this is False, since y2 < y1
- Arg:
- pred: The predicate to cast.
Returns: The same predicate as pred
, except accesses to ‘t1’ are cast to ‘y1’, and accesses to ‘t2’ are cast to ‘y2’.
-
Y_axis
()¶ Returns a tuple representing the Y axis.
-
combine_per_axis
(other, t_combiner, x_combiner, y_combiner)¶ Combines two Bounds using a one-dimensional Combiner function for each axis.
Parameters: - other – The other Bounds3D to combine with.
- t_combiner – A function that takes two bounds and returns one. Takes two tuples as input and returns a tuple of two items. Used to combine temporal bounds.
- x_combiner – A function that takes two bounds and returns one. Takes two tuples as input and returns a tuple of two items. Used to combine X bounds.
- y_combiner – A function that takes two bounds and returns one. Takes two tuples as input and returns a tuple of two items. Used to combine Y bounds.
Returns: A new Bounds3D combined using the three combination functions.
-
copy
()¶ Returns a copy of this bound.
-
expand_to_frame
()¶ Returns a bound with the same time extent but with full spatial extent.
Assumes that X/Y co-ordinates are in relative spatial co-ordinates.
-
classmethod
fromTuple
(tuple_3d)¶ Initialize a Bounds3D object with a tuple of length two or six.
Parameters: tuple3d – A tuple of length two or six. The items represent, in order, ‘t1’, ‘t2’, ‘x1’, ‘x2’, ‘y1’, and ‘y2’, respectively. If the tuple is only of length two, ‘x1’ and ‘y1’ get set to 0., and ‘x2’ and ‘y2’ get set to 1. Returns: A Bounds3D object with the six co-ordinates specified by the six items in tuple3d
.
-
height
()¶ Returns the height (Y dimension) of the time interval.
-
intersect_time_span_space
(other)¶ Returns the bound intersecting
other
in time and spanningself
andother
in space. ReturnsNone
ifself
andother
do not overlap in time.Returns: A single Bounds3D at the intersection of self
andother
in time but spanning them in space, orNone
if they do not overlap in time.
-
length
()¶ Returns the length of the time interval.
-
primary_axis
()¶ Primary axis is time.
-
span
(other)¶ Returns the minimum Bound spanning
self
andother
in all three dimensions.Returns: A single Bounds3D spanning self
andother
.
-
width
()¶ Returns the width (X dimension) of the time interval.
-