Welcome to rekall’s documentation!

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 and payload_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 to None, which uses the primary axis of self’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 set optimization_window to that fraction of the range. The optimized operations (join, collect_by_interval, and filter_against) only look at pairs whose distance from each other along the primary axis is less than optimization_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 along axis. 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 with payload_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 least epsilon 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) where P is the original payload in self, and IS is an IntervalSet 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([])) where P is the original payload. Defaults to True.
  • 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 to None, which uses the primary_axis of self.
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 to None, which uses the primary_axis of self.
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.

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 takes len(names) Intervals as arguments and returns True or False.

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 in a without intersecting any of the intervals in b on axis, but only if they pass the predicate.

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 to None, which uses the primary_axis of self.
  • 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 along axis.

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 or minus 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, and match, 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() and Y() 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 spanning self and other in space. Returns None if self and other do not overlap in time.

Returns:A single Bounds3D at the intersection of self and other in time but spanning them in space, or None 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 and other in all three dimensions.

Returns:A single Bounds3D spanning self and other.
width()

Returns the width (X dimension) of the time interval.

Indices and tables